<?php
declare(strict_types=1);

namespace Operanse\Agent\Capabilities;

defined( 'ABSPATH' ) || exit;

/**
 * A narrow READ capability (ADR-002). Implementations must never write to the database, files, options,
 * or call functions with side effects. Parameters are validated here as well as on the cloud.
 */
interface CapabilityInterface {
	public function name(): string;

	/**
	 * Validate and normalise parameters. Throw \InvalidArgumentException on invalid input.
	 *
	 * @param array<string,mixed> $params
	 * @return array<string,mixed>
	 */
	public function validate( array $params ): array;

	/**
	 * @param array<string,mixed> $params Validated params.
	 * @return array<string,mixed> Structured result (JSON-serialisable, redacted).
	 */
	public function execute( array $params, float $deadline ): array;
}