"""Decision recorder port — protocol interface for recording decisions.

This module defines the ``DecisionRecorder`` protocol, which is the
shared interface used by both ``StrategizeDecisionHook`` and the future
``ExecuteDecisionHook`` to record decisions without coupling to a
concrete ``DecisionService`` implementation.

Based on:
    - docs/adr/ADR-033-decision-recording-protocol.md
    - Forgejo issue #8522
"""

from __future__ import annotations

from typing import TYPE_CHECKING, Protocol, runtime_checkable

if TYPE_CHECKING:
    from cleveragents.domain.models.core.decision import (
        ContextSnapshot,
        Decision,
        DecisionType,
    )
    from cleveragents.domain.models.core.plan import PlanPhase


@runtime_checkable
class DecisionRecorder(Protocol):
    """Protocol for recording decisions (subset of DecisionService API).

    Both ``StrategizeDecisionHook`` and the future ``ExecuteDecisionHook``
    depend on this protocol rather than the concrete ``DecisionService``,
    keeping the hooks decoupled from the persistence layer.
    """

    def record_decision(
        self,
        plan_id: str,
        decision_type: DecisionType | str,
        question: str,
        chosen_option: str,
        *,
        parent_decision_id: str | None = None,
        alternatives_considered: list[str] | None = None,
        confidence_score: float | None = None,
        rationale: str = "",
        actor_reasoning: str | None = None,
        context_snapshot: ContextSnapshot | None = None,
        plan_phase: PlanPhase | str | None = None,
    ) -> Decision: ...
