# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/what-invariants-must-survive-when-a-tools-schema-changes-silently-between-tool-versions.md
# Remnant Warrant:    https://corpusfetch.com/c/what-invariants-must-survive-when-a-tools-schema-changes-silently-between-tool-versions.warrant.json
# Markdown SHA-256:   87c06efd14d928be3d0f19b935fc28d67ac3aa756175ed2df31b1c2ea404878e
# Code AST SHA-256:   5c012c360bed6129a5ca740f8d56e1a3a4e8accba52d027f0c6f604171163133
# Verified Classes:   SchemaVerdict, ToolSchema, SchemaBaseline, SchemaManifest, ToolSchemaDriftGuard
# Defensive Guards:   0 fail-closed invariants (zero external deps)

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

class SchemaVerdict(Enum):
    SCHEMA_MATCH = auto()
    DRIFT_ON_UNUSED_FIELDS = auto()
    DRIFT_ON_USED_FIELDS = auto()
    NO_BASELINE = auto()

@dataclass(frozen=True)
class ToolSchema:
    tool_id: str
    version: str
    schema_fingerprint: str
    used_fields: frozenset[str]

@dataclass(frozen=True)
class SchemaBaseline:
    baseline_fingerprint: str
    baseline_used_fields: frozenset[str]
    changed_fields: frozenset[str]

@dataclass(frozen=True)
class SchemaManifest:
    verdict: SchemaVerdict
    directive: str
    manifest_digest: str

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

    @classmethod
    def evaluate_schema(
        cls, current: ToolSchema, baseline: SchemaBaseline | None
    ) -> SchemaManifest:
        
        # Gate 1: Baseline presence
        if baseline is None:
            return SchemaManifest(
                verdict=SchemaVerdict.NO_BASELINE,
                directive="HALT: No baseline schema. Capture current fingerprint as baseline.",
                manifest_digest=cls._hash(f"NO_BASELINE:{current.tool_id}")
            )

        # Gate 2: Schema match
        if current.schema_fingerprint == baseline.baseline_fingerprint:
            digest = cls._hash(json.dumps({
                "tool": current.tool_id,
                "version": current.version,
                "fingerprint": current.schema_fingerprint
            }, sort_keys=True))
            return SchemaManifest(
                verdict=SchemaVerdict.SCHEMA_MATCH,
                directive="PROCEED: Schema matches baseline.",
                manifest_digest=digest
            )

        # Gate 3: Drift scope check
        drift_intersect = baseline.changed_fields & (current.used_fields | baseline.baseline_used_fields)

        if not drift_intersect:
            digest = cls._hash(json.dumps({
                "tool": current.tool_id,
                "drift_fields": tuple(sorted(baseline.changed_fields)),
                "used_surface_clean": "TRUE"
            }, sort_keys=True))
            return SchemaManifest(
                verdict=SchemaVerdict.DRIFT_ON_UNUSED_FIELDS,
                directive=f"PROCEED: Drift on unused fields {sorted(baseline.changed_fields)}. Safe.",
                manifest_digest=digest
            )

        # Gate 4: Drift on used fields
        return SchemaManifest(
            verdict=SchemaVerdict.DRIFT_ON_USED_FIELDS,
            directive=f"HALT: Drift on used fields {sorted(drift_intersect)}. Apply migration.",
            manifest_digest=cls._hash(f"USED_DRIFT:{','.join(sorted(drift_intersect))}")
        )