# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/what-terminal-verification-gate-must-pass-before-committing-a-session-residual.md
# Remnant Warrant:    https://corpusfetch.com/c/what-terminal-verification-gate-must-pass-before-committing-a-session-residual.warrant.json
# Markdown SHA-256:   9faf044cc91667bf288678778d4613b52d4d784fa6eed8da2dd6c01b5fb1f46f
# Code AST SHA-256:   e697f755a9339e33c4d80bb791cca7d7b08a112710cac890056c2b6afdddaf68
# Verified Classes:   CandidateResidualCommit, TerminalVerificationViolation, TerminalCommitVerificationGate
# Defensive Guards:   6 fail-closed invariants (zero external deps)

from dataclasses import dataclass
from typing import Final, FrozenSet, Tuple
import ast
import sys

REQUIRED_SECTIONS: Final[Tuple[str, ...]] = (
    "## Core Distinction",
    "## What Was Observed",
    "## Recorded Elements",
    "## Condition of Validity",
    "## Decision Boundary",
    "## Operational Effect",
)

@dataclass(frozen=True)
class CandidateResidualCommit:
    slug: str
    markdown_body: str
    python_slice: str

class TerminalVerificationViolation(Exception):
    """Raised when a candidate session residual fails pre-commit structural, AST, or stdlib invariants."""
    pass

class TerminalCommitVerificationGate:
    def __init__(self) -> None:
        self.stdlib_modules: Final[FrozenSet[str]] = frozenset(sys.stdlib_module_names)

    def verify_before_commit(self, candidate: CandidateResidualCommit) -> bool:
        for section in REQUIRED_SECTIONS:
            if section not in candidate.markdown_body:
                raise TerminalVerificationViolation(
                    f"Residual '{candidate.slug}' missing mandatory section: {section}"
                )

        if not candidate.python_slice.strip():
            raise TerminalVerificationViolation(
                f"Residual '{candidate.slug}' contains an empty Python verification slice."
            )

        try:
            tree = ast.parse(candidate.python_slice)
        except SyntaxError as exc:
            raise TerminalVerificationViolation(
                f"Residual '{candidate.slug}' failed AST syntax compilation: {exc}"
            ) from exc

        class_count = 0
        guard_count = 0
        for node in ast.walk(tree):
            if isinstance(node, ast.ClassDef):
                class_count += 1
            elif isinstance(node, (ast.Raise, ast.Assert)):
                guard_count += 1
            elif isinstance(node, ast.Import):
                for alias in node.names:
                    root_mod = alias.name.split(".")[0]
                    if root_mod not in self.stdlib_modules:
                        raise TerminalVerificationViolation(
                            f"External dependency '{root_mod}' violates zero_external_deps."
                        )
            elif isinstance(node, ast.ImportFrom) and node.module:
                root_mod = node.module.split(".")[0]
                if root_mod not in self.stdlib_modules:
                    raise TerminalVerificationViolation(
                        f"External dependency '{root_mod}' violates zero_external_deps."
                    )

        if class_count == 0 or guard_count == 0:
            raise TerminalVerificationViolation(
                f"Residual '{candidate.slug}' requires >=1 class and >=1 fail-closed guard (found {class_count} classes, {guard_count} guards)."
            )

        return True