# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/which-resolved-ambiguity-definitions-must-persist-across-subsequent-task-checkpoints.md
# Remnant Warrant:    https://corpusfetch.com/c/which-resolved-ambiguity-definitions-must-persist-across-subsequent-task-checkpoints.warrant.json
# Markdown SHA-256:   707201c372a35e880787100b706fbc3da51a428a707c4bd2dcc47c12af5a05d0
# Code AST SHA-256:   5ab438e8c314988502076e20bb45d7158338343058e3e1486cd65ee310b06735
# Verified Classes:   ResolvedAmbiguityBinding, CheckpointGlossaryState, AmbiguityBindingDriftViolation, CheckpointAmbiguityPersistenceGate
# Defensive Guards:   5 fail-closed invariants (zero external deps)

from dataclasses import dataclass
from typing import Final, FrozenSet, Mapping, Tuple
import hashlib

VALID_SCOPES: Final[FrozenSet[str]] = frozenset({"TaskWide", "StepLocal"})

@dataclass(frozen=True)
class ResolvedAmbiguityBinding:
    symbol: str
    canonical_definition: str
    unit_or_invariant_constraint: str
    scope: str
    established_at_step: int

@dataclass(frozen=True)
class CheckpointGlossaryState:
    checkpoint_step_index: int
    bindings: Tuple[ResolvedAmbiguityBinding, ...]
    declared_glossary_sha256: str

class AmbiguityBindingDriftViolation(Exception):
    """Raised when a TaskWide resolved ambiguity is dropped, mutated, or unverified across checkpoints."""
    pass

class CheckpointAmbiguityPersistenceGate:
    def compute_glossary_digest(self, bindings: Tuple[ResolvedAmbiguityBinding, ...]) -> str:
        task_wide = sorted(
            (b for b in bindings if b.scope == "TaskWide"),
            key=lambda x: x.symbol,
        )
        tokens = [
            f"{b.symbol}={b.canonical_definition}[{b.unit_or_invariant_constraint}]@{b.established_at_step}"
            for b in task_wide
        ]
        return hashlib.sha256("|".join(tokens).encode("utf-8")).hexdigest()

    def verify_checkpoint_transition(
        self,
        prior_state: CheckpointGlossaryState,
        next_state: CheckpointGlossaryState,
        explicitly_superseded_symbols: FrozenSet[str] = frozenset(),
    ) -> bool:
        # 1. Validate scopes and non-empty definitions in the incoming checkpoint
        for binding in next_state.bindings:
            if binding.scope not in VALID_SCOPES:
                raise AmbiguityBindingDriftViolation(
                    f"Symbol '{binding.symbol}' has invalid scope '{binding.scope}'."
                )
            if not binding.canonical_definition.strip() or not binding.unit_or_invariant_constraint.strip():
                raise AmbiguityBindingDriftViolation(
                    f"Symbol '{binding.symbol}' is missing its canonical definition or constraint."
                )

        # 2. Verify cryptographic digest of the new checkpoint's TaskWide bindings
        expected_digest = self.compute_glossary_digest(next_state.bindings)
        if next_state.declared_glossary_sha256 != expected_digest:
            raise AmbiguityBindingDriftViolation(
                f"Checkpoint {next_state.checkpoint_step_index} glossary SHA-256 mismatch."
            )

        # 3. Ensure every prior TaskWide binding persists unchanged unless explicitly superseded
        next_map: Mapping[str, ResolvedAmbiguityBinding] = {
            b.symbol: b for b in next_state.bindings if b.scope == "TaskWide"
        }

        for prior_binding in prior_state.bindings:
            if prior_binding.scope != "TaskWide":
                continue
            if prior_binding.symbol not in next_map:
                raise AmbiguityBindingDriftViolation(
                    f"TaskWide ambiguity binding '{prior_binding.symbol}' was dropped at checkpoint "
                    f"{next_state.checkpoint_step_index}."
                )
            curr = next_map[prior_binding.symbol]
            if (
                curr.canonical_definition != prior_binding.canonical_definition
                or curr.unit_or_invariant_constraint != prior_binding.unit_or_invariant_constraint
            ) and prior_binding.symbol not in explicitly_superseded_symbols:
                raise AmbiguityBindingDriftViolation(
                    f"TaskWide ambiguity binding '{prior_binding.symbol}' mutated silently across checkpoints."
                )

        return True