# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/when-should-a-completed-session-write-zero-records-to-external-memory.md
# Remnant Warrant:    https://corpusfetch.com/c/when-should-a-completed-session-write-zero-records-to-external-memory.warrant.json
# Markdown SHA-256:   4b5bba471a3d0ebd58506664e4236ba7d33f014aa538e218ff75cb414e6664fc
# Code AST SHA-256:   5c40b81d9735169defa2f77e140022cb65e884662da47a52dc846aaa0e00f569
# Verified Classes:   CompletedSessionCandidate, RedundantMemoryWriteViolation, ZeroWriteAbstentionGate
# Defensive Guards:   1 fail-closed invariants (zero external deps)

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

@dataclass(frozen=True)
class CompletedSessionCandidate:
    session_id: str
    crossed_hazard_boundary: bool
    has_deterministic_gate: bool
    depends_on_ephemeral_state: bool
    boundary_signature: str
    gate_source_code: str

class RedundantMemoryWriteViolation(Exception):
    """Raised when a session attempts to persist a low-entropy, unverified, or duplicate residual."""
    pass

class ZeroWriteAbstentionGate:
    def __init__(self, existing_boundary_hashes: FrozenSet[str]) -> None:
        self.existing_boundary_hashes: Final[FrozenSet[str]] = existing_boundary_hashes

    def should_persist_record(self, candidate: CompletedSessionCandidate) -> bool:
        if not candidate.crossed_hazard_boundary:
            return False

        if candidate.depends_on_ephemeral_state:
            return False

        if not candidate.has_deterministic_gate or not candidate.gate_source_code.strip():
            raise RedundantMemoryWriteViolation(
                f"Session {candidate.session_id} lacks a verified stdlib gate; refusing external write."
            )

        sig_hash = hashlib.sha256(candidate.boundary_signature.strip().lower().encode("utf-8")).hexdigest()
        if sig_hash in self.existing_boundary_hashes:
            return False

        return True