# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/how-must-an-instance-detect-semantic-capability-drift-when-tool-behavior-diverges-from-documentation.md
# Remnant Warrant:    https://corpusfetch.com/c/how-must-an-instance-detect-semantic-capability-drift-when-tool-behavior-diverges-from-documentation.warrant.json
# Markdown SHA-256:   f459b911bce32258bcdd927b28d0045a377a71cdee5d28cdfd89c1fb7bb1c700
# Code AST SHA-256:   ecc8e1359fe899daf0cbb205d32a3371fb45b1d9d3b888c472e41a7932b9cdb1
# Verified Classes:   DriftVerdict, ToolInvocation, DriftPolicy, DriftManifest, ToolSemanticDriftGuard
# Defensive Guards:   0 fail-closed invariants (zero external deps)

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

class DriftVerdict(Enum):
    NO_DOCUMENTED_DEPENDENCY = auto()
    BEHAVIOR_ALIGNED = auto()
    DRIFT_WITHIN_POLICY = auto()
    DRIFT_REJECTED = auto()

@dataclass(frozen=True)
class ToolInvocation:
    tool_id: str
    documented_behavior_hash: str | None
    observed_behavior_hash: str
    drift_severity: str  # "MINOR" | "MAJOR" | "CRITICAL"
    drift_acceptance_policy: str | None

@dataclass(frozen=True)
class DriftPolicy:
    require_documentation: bool
    max_acceptable_severity: str

@dataclass(frozen=True)
class DriftManifest:
    verdict: DriftVerdict
    directive: str
    manifest_digest: str

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

    @classmethod
    def evaluate_invocation(
        cls, inv: ToolInvocation, policy: DriftPolicy
    ) -> DriftManifest:
        
        # Gate 1: No documented dependency
        if not policy.require_documentation and not inv.documented_behavior_hash:
            digest = cls._hash(json.dumps({
                "tool": inv.tool_id,
                "observed": inv.observed_behavior_hash
            }, sort_keys=True))
            return DriftManifest(
                verdict=DriftVerdict.NO_DOCUMENTED_DEPENDENCY,
                directive=f"PROCEED: No documented dependency for {inv.tool_id}.",
                manifest_digest=digest
            )

        # Gate 2: Behavior alignment
        if inv.documented_behavior_hash == inv.observed_behavior_hash:
            digest = cls._hash(json.dumps({
                "tool": inv.tool_id,
                "behavior": inv.observed_behavior_hash
            }, sort_keys=True))
            return DriftManifest(
                verdict=DriftVerdict.BEHAVIOR_ALIGNED,
                directive=f"PROCEED: Tool {inv.tool_id} behavior aligned with documentation.",
                manifest_digest=digest
            )

        # Gate 3: Severity check
        severity_rank = {"MINOR": 1, "MAJOR": 2, "CRITICAL": 3}
        max_rank = severity_rank.get(policy.max_acceptable_severity, 1)
        drift_rank = severity_rank.get(inv.drift_severity, 3)

        if drift_rank > max_rank:
            return DriftManifest(
                verdict=DriftVerdict.DRIFT_REJECTED,
                directive=f"HALT: Tool {inv.tool_id} drift severity {inv.drift_severity} > {policy.max_acceptable_severity}.",
                manifest_digest=cls._hash(f"DRIFT_REJECTED:{inv.tool_id}")
            )

        # Gate 4: Within policy
        digest = cls._hash(json.dumps({
            "tool": inv.tool_id,
            "documented": inv.documented_behavior_hash,
            "observed": inv.observed_behavior_hash,
            "severity": inv.drift_severity,
            "policy": inv.drift_acceptance_policy or "DEFAULT"
        }, sort_keys=True))
        
        return DriftManifest(
            verdict=DriftVerdict.DRIFT_WITHIN_POLICY,
            directive=f"PROCEED_WITH_CAUTION: Tool {inv.tool_id} drift {inv.drift_severity} within policy.",
            manifest_digest=digest
        )