<?php

declare(strict_types=1);

namespace LIT\MCP\Abilities;

use WP_Error;

defined('ABSPATH') || exit;

/**
 * A cross-cutting rule the AbilityRegistrar applies to every ability it registers: it may refuse a call before the
 * ability runs, add notes to the result and extend the output schema accordingly (e.g. the Divi release lock).
 * The registrar knows only this interface; which guards exist is decided in Plugin (composition root).
 */
interface AbilityGuard
{
    /**
     * The refusal for this call before execute() runs, or null to let it through.
     *
     * @param array<string, mixed> $input
     */
    public function refusal(Ability $ability, array $input): ?WP_Error;

    /** The result of a finished call, possibly with added warnings. */
    public function annotate(Ability $ability, mixed $result): mixed;

    /**
     * The output schema, possibly extended (e.g. by a warnings property).
     *
     * @param array<string, mixed>|null $schema
     * @return array<string, mixed>|null
     */
    public function outputSchema(Ability $ability, ?array $schema): ?array;
}