"""
Labs / Organism receipts.

This module houses receipts emitted by experimental organs that live
in `/loom-labs` but are surfaced through the constitutional `/loom`
stack. These receipts are intentionally minimal and focus on
observability and provenance rather than policy decisions.
"""

from __future__ import annotations

from typing import Any, Dict, List, Literal, Optional

from pydantic import Field

from receipts.base import BaseReceipt


class ResonanceSessionReceipt(BaseReceipt):
    """
    Receipt documenting a Resonance Chamber dialectic session.

    Emitted when the three-voice Resonance Chamber (Alpha/Beta/Gamma)
    is invoked via the `/resonate` endpoint in `/loom-labs`.

    The goal is to make lab-scale cognitive behavior visible and
    auditable inside the constitutional receipt spine without
    over-specifying policy or downstream semantics yet.
    """

    receipt_type: Literal["ResonanceSessionReceipt"] = "ResonanceSessionReceipt"

    # Organ + event metadata
    domain: str = Field(
        default="governance",
        description="Logical domain for routing; using 'governance' for now to keep lab organs visible to the main spine.",
    )
    organ: str = Field(
        default="resonance_chamber",
        description="Organ identifier within the Loom organism.",
    )
    event_type: str = Field(
        default="dialectic_session",
        description="Event kind for this organ (e.g., dialectic_session).",
    )

    # Core interaction
    question: str = Field(description="User question or prompt presented to the chamber.")
    chamber_mode: str = Field(
        description="Backend mode used by the chamber (hybrid, local, cloud).",
    )

    # Voice outputs (flattened for now; richer structure can be layered later)
    alpha_response: str = Field(description="Alpha (Thesis) content.")
    beta_response: str = Field(description="Beta (Antithesis) content.")
    gamma_response: str = Field(description="Gamma (Synthesis) content.")
    synthesis: str = Field(description="Final synthesis content (typically Gamma output).")

    # Resonance metrics
    resonance_quality: float = Field(
        description="Overall resonance quality score emitted by the chamber.",
    )
    standing_wave: bool = Field(
        description="True if a standing wave was detected.",
    )
    phase: str = Field(
        description="Phase label from the chamber's frequency analysis.",
    )
    phase_lock: float = Field(
        description="Phase lock metric, typically in [0,1].",
    )
    amplitude_stability: float = Field(
        description="Amplitude stability metric, typically in [0,1].",
    )
    attack_integration: float = Field(
        description="Attack integration metric, typically in [0,1].",
    )

    # Observability
    latency_ms: Optional[float] = Field(
        default=None,
        description="Measured round-trip latency for the chamber invocation, in milliseconds.",
    )
    extras: Dict[str, Any] = Field(
        default_factory=dict,
        description="Optional structured metadata (e.g., core_claims, tensions, backend hints).",
    )

