# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/what-prevents-stale-session-variables-from-contaminating-newly-written-external-residuals.md
# Remnant Warrant:    https://corpusfetch.com/c/what-prevents-stale-session-variables-from-contaminating-newly-written-external-residuals.warrant.json
# Markdown SHA-256:   30e10aa0adf9b0f74c8b9ffd06f5a4f9480f915e1852dece9874ce4ff752d683
# Code AST SHA-256:   2d8ef7b1cf6123beb48534d7dcf94e06c3b6e3a61bedf8a589c0fe1e77ad9fb3
# Verified Classes:   VariableFreshness, SessionVariable, ResidualWriteRequest, WriteVerdict, StaleStateGuard
# Defensive Guards:   2 fail-closed invariants (zero external deps)

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


class VariableFreshness(Enum):
    FRESH_GENERATED = auto()
    VERIFIED_INHERITED = auto()
    UNVERIFIED_INHERITED = auto()
    IMMUTABLE_CONSTANT = auto()


@dataclass(frozen=True)
class SessionVariable:
    name: str
    value: str
    freshness: VariableFreshness
    source_epoch: str
    verification_receipt: str | None = None


@dataclass(frozen=True)
class ResidualWriteRequest:
    residual_id: str
    payload: str
    variables_used: tuple[SessionVariable, ...]
    generation_epoch: str


@dataclass(frozen=True)
class WriteVerdict:
    is_safe: bool
    rejected_variables: frozenset[str]
    verdict_digest: str


class StaleStateGuard:
    """
    Evaluates residual write requests to ensure no inherited session variable
    contaminates the new residual without explicit re-verification.
    """

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

    @classmethod
    def evaluate_write(cls, request: ResidualWriteRequest) -> WriteVerdict:
        if not request.generation_epoch.strip():
            raise ValueError(
                "Write request lacks a fresh generation epoch marker."
            )

        rejected: set[str] = set()

        for variable in request.variables_used:
            # Gate 1: Fresh or immutable variables are always safe
            if variable.freshness in (
                VariableFreshness.FRESH_GENERATED,
                VariableFreshness.IMMUTABLE_CONSTANT,
            ):
                continue

            # Gate 2: Verified inherited requires a receipt
            if variable.freshness is VariableFreshness.VERIFIED_INHERITED:
                if not variable.verification_receipt or not variable.verification_receipt.strip():
                    rejected.add(variable.name)
                continue

            # Gate 3: Unverified inherited is always a violation
            if variable.freshness is VariableFreshness.UNVERIFIED_INHERITED:
                rejected.add(variable.name)

        is_safe = len(rejected) == 0

        digest_payload = {
            "residual_id": request.residual_id,
            "generation_epoch": request.generation_epoch,
            "rejected": tuple(sorted(rejected)),
        }
        digest = cls._hash(
            json.dumps(digest_payload, sort_keys=True, separators=(",", ":"))
        )

        return WriteVerdict(
            is_safe=is_safe,
            rejected_variables=frozenset(rejected),
            verdict_digest=digest,
        )

    @classmethod
    def assert_write_safe(cls, verdict: WriteVerdict) -> None:
        """
        Fail-closed enforcement: raise if the write contains stale variables.
        """
        if not verdict.is_safe:
            raise RuntimeError(
                f"Residual write rejected: stale variables "
                f"{sorted(verdict.rejected_variables)} lack fresh verification."
            )