<?php
defined( 'ABSPATH' ) || exit;

/**
 * Provider contract for the Strategy LLM Review layer.
 *
 * Layer 3 of the review stack:
 *   1. Trace data
 *   2. Deterministic Trace Audit
 *   3. Strategy LLM Review (this contract; v0.5 = simulated only)
 *   4. Human arbitration
 *
 * Implementations of this interface must:
 *   - Treat the deterministic audit as authoritative for closure_state and
 *     needs_human_arbitration. They MUST NOT override either.
 *   - Return a five-key advisory shape (see review_trace docblock).
 *   - Be local-dev safe. No external calls unless the operator has explicitly
 *     enabled and configured a network-backed provider.
 */
interface SA_Orch_LLM_Provider_Interface {

    /** Stable id used in settings ('simulated', 'openai', 'anthropic', etc.). */
    public function id(): string;

    /** Human-readable name shown in the admin dropdown. */
    public function name(): string;

    /** Whether this provider needs an API token to function. */
    public function requires_api_key(): bool;

    /**
     * Produce a strategy review of the trace.
     *
     * Input:
     *   $trace                — output of SA_Orch_Rest::get_demand_trace().
     *   $deterministic_audit  — output of SA_Orch_Reasoning::evaluate( $trace ).
     *
     * Output (required keys):
     *   [
     *     'summary'               => string,                    // narrative
     *     'agreement_with_audit'  => 'true'|'false'|'partial',
     *     'additional_risks'      => string[],                  // risks not caught by audit
     *     'suggested_next_action' => string,
     *     'confidence'            => 'low'|'medium'|'high',
     *   ]
     */
    public function review_trace( array $trace, array $deterministic_audit ): array;
}