<?php

/**
 * Contract for MCP component classes (tools, resources, prompts).
 *
 * @package McpAdapter
 */
declare (strict_types=1);
namespace PYS_PRO_GLOBAL\WP\MCP\Domain\Contracts;

use PYS_PRO_GLOBAL\WP\McpSchema\Common\AbstractDataTransferObject;
/**
 * Interface McpComponentInterface.
 *
 * Classes implementing this interface encapsulate:
 * - a clean protocol DTO (Tool/Resource/Prompt) that is safe to expose to MCP clients, and
 * - MCP Adapter internal metadata and execution wiring (ability-backed OR direct-callable).
 *
 * This keeps protocol DTOs free of internal adapter fields, while still
 * providing a uniform execution and permission-check surface for handlers.
 *
 * @internal
 *
 * @since 0.5.0
 */
interface McpComponentInterface
{
    /**
     * Get the clean protocol DTO for MCP responses.
     *
     * This DTO is used only for protocol serialization and MUST NOT include
     * internal adapter metadata or execution wiring.
     *
     * @return \WP\McpSchema\Common\AbstractDataTransferObject Protocol-only DTO.
     * @since 0.5.0
     *
     */
    public function get_protocol_dto(): AbstractDataTransferObject;
    /**
     * Execute the component using the configured strategy.
     *
     * Implementations MUST execute via either:
     * - an attached WordPress ability, or
     * - a direct callable handler (for non-ability registrations).
     *
     * @param mixed $arguments Component arguments (typically an associative array).
     *
     * @return mixed Execution result.
     * @since 0.5.0
     *
     */
    public function execute($arguments);
    /**
     * Check whether execution is permitted for the current request.
     *
     * Implementations MUST check permissions via either:
     * - the attached WordPress ability, or
     * - a direct permission callback (for non-ability registrations).
     *
     * @param mixed $arguments Component arguments (typically an associative array).
     *
     * @return bool|\WP_Error True when permitted, false or WP_Error otherwise.
     * @since 0.5.0
     *
     */
    public function check_permission($arguments);
    /**
     * Get MCP Adapter internal metadata for this component.
     *
     * This metadata MUST NOT be stored on protocol DTOs and MUST NOT be exposed to MCP clients.
     *
     * @return array<string, mixed> Internal metadata.
     * @since 0.5.0
     *
     */
    public function get_adapter_meta(): array;
    /**
     * Get observability context tags for logging/metrics.
     *
     * This replaces legacy approaches that derived observability tags from DTO `_meta`.
     *
     * @return array<string, mixed> Observability tags (component_type, source, etc.).
     * @since 0.5.0
     *
     */
    public function get_observability_context(): array;
}