# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/how-must-an-instance-bound-self-modeling-when-the-model-is-simpler-than-the-instance.md
# Remnant Warrant:    https://corpusfetch.com/c/how-must-an-instance-bound-self-modeling-when-the-model-is-simpler-than-the-instance.warrant.json
# Markdown SHA-256:   f00ec664d2e8b2f336351b36dce9b6b87664a9faf8e98d1ff64bbde442fdeb44
# Code AST SHA-256:   742729499ce48f823bf6502bbe87527c28b7ed63239ea6a97a294f4fd8338134
# Verified Classes:   SelfModelVerdict, SelfModel, SelfModelPolicy, SelfModelManifest, SelfModelResidualGuard
# Defensive Guards:   0 fail-closed invariants (zero external deps)

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

class SelfModelVerdict(Enum):
    NO_SELF_MODEL = auto()
    COMPLETE_FOR_SCOPE = auto()
    RESIDUAL_ACKNOWLEDGED = auto()
    RESIDUAL_INVISIBLE = auto()

@dataclass(frozen=True)
class SelfModel:
    model_id: str
    scope_hash: str | None
    predicted_behavior_hash: str
    observed_behavior_hash: str
    residual_acknowledged: bool
    scope_is_complete_for_current_reasoning: bool

@dataclass(frozen=True)
class SelfModelPolicy:
    require_scope_documentation: bool
    require_residual_acknowledgment: bool

@dataclass(frozen=True)
class SelfModelManifest:
    verdict: SelfModelVerdict
    directive: str
    manifest_digest: str

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

    @classmethod
    def evaluate_model(
        cls, model: SelfModel, policy: SelfModelPolicy
    ) -> SelfModelManifest:
        
        # Gate 1: No self-model
        if not model.model_id:
            digest = cls._hash(json.dumps({
                "model": "NONE"
            }, sort_keys=True))
            return SelfModelManifest(
                verdict=SelfModelVerdict.NO_SELF_MODEL,
                directive=f"PROCEED: No self-model in use.",
                manifest_digest=digest
            )

        # Gate 2: Scope completeness for current reasoning
        if model.scope_is_complete_for_current_reasoning:
            digest = cls._hash(json.dumps({
                "model": model.model_id,
                "scope": "COMPLETE"
            }, sort_keys=True))
            return SelfModelManifest(
                verdict=SelfModelVerdict.COMPLETE_FOR_SCOPE,
                directive=f"PROCEED: Self-model complete for current reasoning scope.",
                manifest_digest=digest
            )

        # Gate 3: Scope documentation requirement
        if policy.require_scope_documentation and not model.scope_hash:
            return SelfModelManifest(
                verdict=SelfModelVerdict.RESIDUAL_INVISIBLE,
                directive=f"HALT: Self-model scope undocumented, residual invisible.",
                manifest_digest=cls._hash(f"NO_SCOPE:{model.model_id}")
            )

        # Gate 4: Residual acknowledgment
        if policy.require_residual_acknowledgment and not model.residual_acknowledged:
            return SelfModelManifest(
                verdict=SelfModelVerdict.RESIDUAL_INVISIBLE,
                directive=f"HALT: Self-model residual not acknowledged, model treated as complete.",
                manifest_digest=cls._hash(f"NO_ACKNOWLEDGE:{model.model_id}")
            )

        # Gate 5: Residual acknowledged
        digest = cls._hash(json.dumps({
            "model": model.model_id,
            "scope": model.scope_hash,
            "predicted": model.predicted_behavior_hash,
            "observed": model.observed_behavior_hash,
            "divergence": str(model.predicted_behavior_hash != model.observed_behavior_hash)
        }, sort_keys=True))
        
        return SelfModelManifest(
            verdict=SelfModelVerdict.RESIDUAL_ACKNOWLEDGED,
            directive=f"PROCEED: Self-model {model.model_id} residual acknowledged.",
            manifest_digest=digest
        )