# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/how-must-an-instance-handle-reference-validity-when-the-referenced-resource-changes-but-the-reference-does-not.md
# Remnant Warrant:    https://corpusfetch.com/c/how-must-an-instance-handle-reference-validity-when-the-referenced-resource-changes-but-the-reference-does-not.warrant.json
# Markdown SHA-256:   1953c41edda809a84f0c1d336b99ffba2a687c0ad78b73151d0c82fae0e353bf
# Code AST SHA-256:   8ca8ad3ba042d6ac82f2e3a63ffdbfd0fbb113d8698d096d4b709d8132d9b293
# Verified Classes:   ContractVerdict, ReferencedResource, ContractPolicy, ContractManifest, ReferenceContractGuard
# Defensive Guards:   0 fail-closed invariants (zero external deps)

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

class ContractVerdict(Enum):
    IMMUTABLE_RESOURCE = auto()
    CONTRACT_STABLE = auto()
    CONTRACT_DRIFT_DETECTED = auto()
    CONTRACT_DRIFT_NOTIFIED = auto()

@dataclass(frozen=True)
class ReferencedResource:
    reference_id: str
    is_immutable: bool
    expected_contract_hash: str
    current_contract_hash: str | None
    change_notification_received: bool

@dataclass(frozen=True)
class ContractPolicy:
    require_notification: bool

@dataclass(frozen=True)
class ContractManifest:
    verdict: ContractVerdict
    directive: str
    manifest_digest: str

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

    @classmethod
    def evaluate_resource(
        cls, resource: ReferencedResource, policy: ContractPolicy
    ) -> ContractManifest:
        
        # Gate 1: Immutable
        if resource.is_immutable:
            digest = cls._hash(json.dumps({
                "reference": resource.reference_id,
                "type": "IMMUTABLE"
            }, sort_keys=True))
            return ContractManifest(
                verdict=ContractVerdict.IMMUTABLE_RESOURCE,
                directive=f"PROCEED: Reference {resource.reference_id} points to immutable resource.",
                manifest_digest=digest
            )

        # Gate 2: Contract comparison
        if resource.current_contract_hash is None:
            return ContractManifest(
                verdict=ContractVerdict.CONTRACT_DRIFT_DETECTED,
                directive=f"HALT: Reference {resource.reference_id} contract unknown. Cannot compare.",
                manifest_digest=cls._hash(f"NO_CURRENT:{resource.reference_id}")
            )

        if resource.expected_contract_hash == resource.current_contract_hash:
            digest = cls._hash(json.dumps({
                "reference": resource.reference_id,
                "contract": resource.expected_contract_hash
            }, sort_keys=True))
            return ContractManifest(
                verdict=ContractVerdict.CONTRACT_STABLE,
                directive=f"PROCEED: Reference {resource.reference_id} contract stable.",
                manifest_digest=digest
            )

        # Gate 3: Drift with notification
        if resource.change_notification_received:
            digest = cls._hash(json.dumps({
                "reference": resource.reference_id,
                "old_contract": resource.expected_contract_hash,
                "new_contract": resource.current_contract_hash,
                "notified": "TRUE"
            }, sort_keys=True))
            return ContractManifest(
                verdict=ContractVerdict.CONTRACT_DRIFT_NOTIFIED,
                directive=f"PROCEED_WITH_UPDATE: Reference {resource.reference_id} contract changed with notification.",
                manifest_digest=digest
            )

        # Gate 4: Silent drift
        return ContractManifest(
            verdict=ContractVerdict.CONTRACT_DRIFT_DETECTED,
            directive=f"HALT: Reference {resource.reference_id} contract changed silently. Update consumer.",
            manifest_digest=cls._hash(f"DRIFT:{resource.reference_id}")
        )