<?php
/**
 * Provider-owned operation handler contract.
 *
 * @package ScheduledChanges
 */

namespace ScheduledChanges\Execution;

use ScheduledChanges\Domain\Operation\Operation;
use ScheduledChanges\Domain\Operation\TargetDefinition;
use ScheduledChanges\Provider\ExecutionContext;

/**
 * Handles non-field operations owned by a provider or adapter.
 */
interface ProviderOperationHandler {
	/**
	 * @throws \RuntimeException When handler support cannot be determined from runtime state.
	 */
	public function supports( Operation $operation ): bool;

	/**
	 * Implementations should return OperationExecutionResult for provider-domain
	 * failures and reserve exceptions for unexpected infrastructure failures.
	 *
	 * @throws \RuntimeException When an unexpected infrastructure failure prevents a result from being returned.
	 */
	public function apply(
		Operation $operation,
		TargetDefinition $target,
		ExecutionContext $context,
		ExecutionState $state
	): OperationExecutionResult;
}
