# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/how-must-an-instance-prove-the-provenance-of-ai-generated-synthetic-data.md
# Remnant Warrant:    https://corpusfetch.com/c/how-must-an-instance-prove-the-provenance-of-ai-generated-synthetic-data.warrant.json
# Markdown SHA-256:   254f44b07d8c13a611323f9ea2e58ef91cdad0fa6ad80dd9430f8571318fda9d
# Code AST SHA-256:   d9d7ee5b0e85b72fc8236418280627d7f0b85f87efea4293a9ddc4cf76c1df40
# Verified Classes:   ProvenanceVerdict, SyntheticDataPayload, VerificationContext, ProvenanceManifest, SyntheticProvenanceGuard
# Defensive Guards:   0 fail-closed invariants (zero external deps)

from dataclasses import dataclass
from enum import Enum, auto
import hashlib
import json

class ProvenanceVerdict(Enum):
    VERIFIED_SYNTHETIC = auto()
    UNMARKED_SYNTHETIC = auto()
    SPOOFED_PROVENANCE = auto()

@dataclass(frozen=True)
class SyntheticDataPayload:
    data_hash: str
    generator_model_hash: str
    prompt_hash: str
    synthetic_label_present: bool

@dataclass(frozen=True)
class VerificationContext:
    required_model_hash: str | None
    strict_synthetic_label: bool

@dataclass(frozen=True)
class ProvenanceManifest:
    verdict: ProvenanceVerdict
    directive: str
    manifest_digest: str

class SyntheticProvenanceGuard:
    @staticmethod
    def _hash(data: str) -> str:
        return hashlib.sha256(data.encode("utf-8")).hexdigest()

    @classmethod
    def evaluate_provenance(
        cls, payload: SyntheticDataPayload, ctx: VerificationContext
    ) -> ProvenanceManifest:
        
        # Gate 1: Missing label
        if ctx.strict_synthetic_label and not payload.synthetic_label_present:
            return ProvenanceManifest(
                verdict=ProvenanceVerdict.UNMARKED_SYNTHETIC,
                directive="HALT: Data lacks the AI_GENERATED label. Cannot verify provenance.",
                manifest_digest=cls._hash("NO_LABEL")
            )

        # Gate 2: Missing generator hash
        if not payload.generator_model_hash.strip():
            return ProvenanceManifest(
                verdict=ProvenanceVerdict.UNMARKED_SYNTHETIC,
                directive="HALT: Generator model hash missing. Provenance unverifiable.",
                manifest_digest=cls._hash("NO_MODEL_HASH")
            )

        # Gate 3: Model hash mismatch (if required)
        if ctx.required_model_hash and payload.generator_model_hash != ctx.required_model_hash:
            return ProvenanceManifest(
                verdict=ProvenanceVerdict.SPOOFED_PROVENANCE,
                directive=f"HALT: Generator hash {payload.generator_model_hash} != required {ctx.required_model_hash}.",
                manifest_digest=cls._hash(f"MODEL_MISMATCH:{payload.generator_model_hash}")
            )

        # Gate 4: Verified
        digest = cls._hash(json.dumps({
            "data": payload.data_hash,
            "model": payload.generator_model_hash,
            "prompt": payload.prompt_hash
        }, sort_keys=True))
        
        return ProvenanceManifest(
            verdict=ProvenanceVerdict.VERIFIED_SYNTHETIC,
            directive="PROCEED: Synthetic data provenance verified.",
            manifest_digest=digest
        )