"""Public wire records shared by HTTP, SSE and generated frontend types.

Optional metadata stays absent when unavailable. Additional provenance/tool
fields are retained for compatibility; required response and citation fields are
validated. These contracts describe shape, not legal support or authenticity.
"""

from typing import Any, Literal, NotRequired, Required

from pydantic import ConfigDict, TypeAdapter, ValidationError
from typing_extensions import TypedDict

CONTRACT_VERSION = "2.0"


class PublicRecord(TypedDict, total=False):
    __pydantic_config__ = ConfigDict(extra="allow", strict=True)


class FeedbackContext(PublicRecord):
    question: Required[str]
    answer: Required[str]
    source_ids: Required[list[str]]


class FeedbackReport(PublicRecord):
    category: Required[Literal["answer", "sources", "coverage", "interface", "signin", "other"]]
    details: Required[str]
    consent: Required[bool]
    share_context: Required[bool]
    context: Required[FeedbackContext | None]


class FeedbackReceipt(PublicRecord):
    id: Required[str]
    created_at: Required[str]
    status: Required[Literal["received", "withdrawn"]]
    already_received: Required[bool]
    retention_days: Required[int]


class SubmittedFeedback(FeedbackReceipt):
    report: Required[FeedbackReport]


class FeedbackList(PublicRecord):
    reports: Required[list[SubmittedFeedback]]


class Evaluation(PublicRecord, total=False):
    passed: bool
    notes: list[str]


class KeyQuote(PublicRecord, total=False):
    quote: str
    text: str
    offset: int


class SummaryProvenance(PublicRecord, total=False):
    summarized_from: str
    parent_id: str


class Summary(PublicRecord, total=False):
    variant: str
    case_name: str | None
    facts: str | None
    facts_llm: str
    issues: str | None
    holding: str | None
    sections: dict[str, str]
    key_quotes: list[KeyQuote]
    llm_status: str
    llm_windows: int
    provenance: SummaryProvenance


class Outcome(PublicRecord, total=False):
    action: str
    question: str
    document: str
    note: str
    review_notice: str


class Source(PublicRecord, total=False):
    title: str
    source_id: str
    court: str
    year: int | str
    text: str
    score: float
    citation: str
    decision_date: str
    document_type: str
    edition_as_of: str
    article_number: str
    provision_status: str
    source_section: str
    chunk_index: int
    parent_id: str
    case_id: str
    case_number: str
    case_number_status: str
    case_number_original: str
    proceeding_id: str | None
    proceeding_basis: Literal["source_reported_docket", "pdf_checked_docket"]
    collection: str
    source_url: str
    source_origin: Literal["web"]
    provider: str
    fetched_at: str
    extraction_kind: Literal["provider_excerpts", "provider_full_content"]
    original_pdf_url: str
    page_start: int
    page_end: int
    paragraph_start: int
    paragraph_end: int
    paragraph_locator_kind: str
    section_heading: str
    passage_role: str
    opinion_role: str
    metadata_date_status: str
    pdf_header_date: str
    source_pdf_path: str
    context_kind: str
    text_start: int
    chunk_offset: int
    document_id: str
    pdf_sha256: str
    retrieval_signals: list[Literal["semantic", "bm25", "exact"]]
    retrieval_ranks: dict[Literal["semantic", "bm25", "exact"], int]
    candidate_reservations: list[Literal["semantic", "bm25", "exact"]]


class Judgment(Source, total=False):
    parent_id: Required[str]
    text: Required[str]
    characters: Required[int]
    judge: str


class ReviewPrompt(PublicRecord, total=False):
    note: str
    task: str
    approval_id: str
    expires_at: str


class ApprovalReceipt(PublicRecord):
    approval_id: Required[str]
    approved: Required[bool]
    status: Required[Literal["accepted", "completed", "uncertain"]]
    created_at: Required[str]
    settled_at: Required[str | None]
    expires_at: Required[str]
    retention_days: Required[int]


class DecisionDocument(Source, total=False):
    document_id: Required[str]
    parent_id: Required[str]
    title: Required[str]
    decision_date: Required[str]


class DecisionScope(TypedDict):
    __pydantic_config__ = ConfigDict(extra="forbid", strict=True)
    start: str | None
    end: str | None
    court: str | None


class DecisionPage(PublicRecord, total=False):
    kind: Literal["decision_list"]
    documents: Required[list[DecisionDocument]]
    total: Required[int]
    limit: Required[int]
    offset: Required[int]
    next_offset: Required[int | None]
    scope: Required[DecisionScope]
    date_basis: Required[Literal["source_reported_decision_date"]]
    date_status_counts: Required[dict[str, int]]
    conflicting_dates_excluded: Required[int]
    unknown_dates_excluded: Required[int]
    complete_court_inventory: Required[Literal[False]]


class Citation(PublicRecord, total=False):
    id: Required[int]
    quote: Required[str]
    chunk_offset: Required[int]
    document_offset: int


class AnswerParagraph(PublicRecord, total=False):
    heading: str
    text: Required[str]
    citations: Required[list[Citation]]


class EvidencePassage(Source, total=False):
    id: Required[int]
    source_id: Required[str]
    parent_id: Required[str]
    title: Required[str]
    citation: Required[str]
    text: Required[str]
    chunk_offset: Required[int]
    locator_scope: Literal["source_chunk"]


class EvidenceContext(PublicRecord, total=False):
    status: Required[str]
    documents_requested: int
    documents_read: int
    candidate_passages: int
    included_passages: int
    focused_passages: int
    requested_facets: list[str]
    selected_facets: list[str]
    bounded_scan_truncated: list[str]
    note: str


class Claim(PublicRecord, total=False):
    claim_id: Required[int]
    paragraph_index: Required[int]
    text: Required[str]
    evidence_ids: Required[list[int]]
    consequential: Required[bool]
    status: Required[
        Literal["references_checked", "rejected", "model_supported", "unsupported", "uncertain"]
    ]
    reason: Required[str]
    review_evidence_ids: list[int]
    paragraph_text: str
    standalone: bool


class ClaimCheck(PublicRecord, total=False):
    status: Required[
        Literal["not_run", "references_checked", "model_reviewed", "review_unavailable"]
    ]
    review_calls: Required[int]
    omitted_paragraphs: int
    partially_retained_paragraphs: int
    verification_scope: Required[str]
    claims: Required[list[Claim]]
    failure_reason: str | None
    repair: dict[str, Any]


class TreatmentFinding(PublicRecord, total=False):
    statement: Required[Literal["overruled", "affirmed", "distinguished", "followed"]]
    identity_basis: Required[str]
    quote: Required[str]
    source: Required[Source]
    evidence_id: int


class TreatmentCheck(PublicRecord, total=False):
    target_title: Required[str]
    target_citation: str
    status: Required[Literal["explicit_statement_found", "unknown"]]
    reason: Required[str]
    findings: Required[list[TreatmentFinding]]


class TreatmentCoverage(PublicRecord, total=False):
    year_start: int | None
    year_end: int | None


class Treatment(PublicRecord, total=False):
    status: Required[str]
    current_status: Required[Literal["unknown"]]
    coverage: Required[TreatmentCoverage]
    note: Required[str]
    checks: Required[list[TreatmentCheck]]


class ResearchAnswer(PublicRecord, total=False):
    message: str
    kind: Literal["decision_list"]
    documents: list[DecisionDocument]
    mode: Required[Literal["synthesis", "excerpts", "insufficient_evidence"]]
    llm_status: Required[str]
    paragraphs: Required[list[AnswerParagraph]]
    evidence: Required[list[EvidencePassage]]
    gaps: Required[list[str]]
    evidence_context: EvidenceContext
    claim_check: ClaimCheck
    treatment: Treatment
    citation_validation: dict[str, Any]


class WebResearch(PublicRecord, total=False):
    provider: Required[Literal["parallel_mcp"]]
    status: Required[str]
    searched: Required[bool]
    documents_fetched: Required[int]
    requests: Required[int]
    queries: list[str]
    note: Required[str]


class ToolResult(PublicRecord, total=False):
    tool: str
    summary: Summary
    outcome: Outcome
    answer: ResearchAnswer
    discovery: "DecisionPage | CaseResolution"
    web_research: WebResearch
    sources: list[Source]


class ChatResult(PublicRecord, total=False):
    # Optional to preserve readable previously saved transcripts; new server
    # responses always include this version.
    contract_version: Literal["2.0"]
    interrupted: Required[bool]
    thread_id: Required[str]
    routed_to: str | None
    evaluation: Evaluation | None
    result: ToolResult
    sources: list[Source] | None
    review: ReviewPrompt


class RecoverySettings(PublicRecord):
    enabled: Required[bool]
    generation: Required[str | None]
    threads: Required[int]
    bytes: Required[int]
    retention_hours: Required[int]
    max_threads: Required[int]
    max_bytes: Required[int]
    max_thread_bytes: Required[int]


class RecoveryThread(PublicRecord):
    thread_id: Required[str]
    updated_at: Required[str]
    expires_at: Required[str]


class RecoveryThreads(PublicRecord):
    threads: Required[list[RecoveryThread]]


class RecoveryExport(PublicRecord):
    version: Required[int]
    encoding: Required[str]
    retention_hours: Required[int]
    checkpoints: Required[list[dict[str, Any]]]


class RecoveryTurn(PublicRecord):
    role: Required[Literal["user", "assistant"]]
    content: Required[str]


class RecoveryConversation(PublicRecord):
    thread_id: Required[str]
    request: Required[str]
    status: Required[Literal["completed", "review_required", "review_expired", "decision_consumed", "interrupted"]]
    history: Required[list[RecoveryTurn]]
    result: Required[ChatResult | None]


class HealthReport(TypedDict):
    status: str
    llm: str
    web_fallback: str
    backend: str
    index: str
    lexical_index: str


class ReadinessComponent(TypedDict, total=False):
    name: Required[str]
    status: Required[Literal["ready", "failed", "disabled", "configured", "missing_credentials"]]
    code: str
    probe_ms: float


class ReadinessResources(TypedDict, total=False):
    process_peak_rss_bytes: int
    runtime_filesystem_free_bytes: int
    container_memory_limit_bytes: int
    container_memory_used_bytes: int


class ReadinessReport(TypedDict):
    status: Literal["ready", "retrieval_only", "warming", "degraded", "unavailable"]
    detail: str
    checked_at: str | None
    components: list[ReadinessComponent]
    generation: Literal["configured", "disabled", "missing_credentials", "not_probed"]
    verification_scope: str
    resources: NotRequired[ReadinessResources]


class HistoryTurn(PublicRecord, total=False):
    role: Required[Literal["user", "assistant"]]
    content: Required[str]


class HistoryResponse(PublicRecord, total=False):
    thread_id: Required[str]
    history: Required[list[HistoryTurn]]
    status: str | None


class SupervisorResponse(PublicRecord, total=False):
    sources: list[Source]
    summary: Summary
    evaluation: Evaluation


class CancelResponse(TypedDict):
    stopped: bool


class UsageReport(PublicRecord, total=False):
    calls: Required[int]
    failed_calls: Required[int]
    prompt_tokens: Required[int]
    completion_tokens: Required[int]
    total_tokens: Required[int]
    cost_usd_estimate: Required[float]
    by_model: dict[str, Any]


class LimitWindow(PublicRecord, total=False):
    limit: Required[int]
    remaining: Required[int]
    used: Required[int]
    window_seconds: Required[int]
    next_expiry_at: str | None
    retry_after: int


class ProviderMinuteLimits(TypedDict):
    __pydantic_config__ = ConfigDict(extra="forbid", strict=True)
    model_provider_calls: LimitWindow
    model_provider_tokens: LimitWindow


class ProviderWindow(TypedDict):
    provider: str
    model: str
    limits: ProviderMinuteLimits


class ServiceLimitsReport(PublicRecord, total=False):
    persistence: Required[Literal["disabled", "memory", "postgres"]]
    counted_at: str
    limits: Required[dict[str, LimitWindow]]
    provider_windows: list[ProviderWindow]


class CoverageSource(PublicRecord, total=False):
    provider: Required[str]
    url: Required[str]
    license: str
    attribution: str


class CoverageReport(PublicRecord, total=False):
    snapshot_id: Required[str]
    documents: Required[int]
    built_at: Required[str]
    decision_year_counts: Required[dict[str, int]]
    court_counts: Required[dict[str, int]]
    date_status_counts: Required[dict[str, int]]
    document_kind_counts: Required[dict[str, int]]
    limitations: Required[list[str]]
    sources: Required[list[CoverageSource]]


class CaseResolution(PublicRecord, total=False):
    kind: Literal["case_resolution"]
    status: Required[Literal["resolved", "ambiguous", "no_match"]]
    match_kind: Required[Literal["identity", "party_fragment", "none"]]
    documents: Required[list[Source]]


class HistorySettings(TypedDict):
    enabled: bool
    threads: int
    bytes: int
    max_threads: int
    max_bytes: int
    max_thread_bytes: int
    retention_days: int


class IdentityResponse(TypedDict):
    id: str
    persistence: Literal["postgres"]


class SavedThread(PublicRecord, total=False):
    id: Required[str]
    title: Required[str]
    createdAt: Required[int]
    updatedAt: Required[int]
    messages: Required[list[dict[str, Any]]]
    revision: Required[int]


class SavedThreads(TypedDict):
    threads: list[SavedThread]


class HistoryExport(SavedThreads):
    version: Literal[1]


class StreamNode(TypedDict):
    event: Literal["node"]
    name: str


class StreamDone(ChatResult, total=False):
    event: Required[Literal["done"]]


class StreamError(TypedDict):
    event: Literal["error"]
    code: str
    detail: str


class ErrorResponse(PublicRecord, total=False):
    detail: Required[str | list[dict[str, Any]]]
    code: str
    category: str


StreamEvent = StreamNode | StreamDone | StreamError
chat_adapter = TypeAdapter(ChatResult)
stream_adapter = TypeAdapter(StreamEvent)
limits_adapter = TypeAdapter(ServiceLimitsReport)


class ContractError(RuntimeError):
    """Sanitized failure; never include a private prompt or source payload."""


def _validate(adapter: TypeAdapter, payload: Any):
    try:
        return adapter.validate_python(payload)
    except ValidationError:
        raise ContractError("The research response was incomplete. Please try again.") from None


def public_chat(payload: dict[str, Any]) -> ChatResult:
    return _validate(chat_adapter, {**payload, "contract_version": CONTRACT_VERSION})


def public_limits(payload: dict[str, Any]) -> ServiceLimitsReport:
    return _validate(limits_adapter, payload)


def stream_frame(payload: dict[str, Any]) -> str:
    checked = _validate(stream_adapter, payload)
    return f"data: {stream_adapter.dump_json(checked).decode()}\n\n"