# SPDX-License-Identifier: Apache-2.0
"""Evidence: opaque evidence records for claims.

The kernel records that evidence was attached — it does NOT validate
or fetch the evidence. Evidence is opaque: a kind tag plus a reference
string. The governor runtime does evidence linking and validation.
"""

from __future__ import annotations

from dataclasses import dataclass
from typing import Any


VALID_EVIDENCE_KINDS = frozenset({
    "test_result",      # Output of running tests
    "receipt",          # A receipt_id from another gate
    "human_assertion",  # A human said so
    "citation",         # External reference (URL, DOI, etc.)
    "tool_output",      # Output from a tool/command
})


@dataclass(frozen=True)
class Evidence:
    """An evidence record attached to a claim.

    kind: validated against VALID_EVIDENCE_KINDS.
    reference: opaque string (receipt_id, URL, description).
               The kernel never fetches or verifies references.
    source: who/what provided this evidence (optional).
    """

    kind: str
    reference: str
    source: str = ""

    def __post_init__(self) -> None:
        if self.kind not in VALID_EVIDENCE_KINDS:
            raise ValueError(
                f"Invalid evidence kind {self.kind!r}; "
                f"must be one of {sorted(VALID_EVIDENCE_KINDS)}"
            )
        if not self.reference:
            raise ValueError("Evidence reference must be non-empty")

    def to_dict(self) -> dict[str, Any]:
        return {
            "kind": self.kind,
            "reference": self.reference,
            "source": self.source,
        }

    @classmethod
    def from_dict(cls, d: dict[str, Any]) -> Evidence:
        return cls(
            kind=d["kind"],
            reference=d["reference"],
            source=d.get("source", ""),
        )
