# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/how-must-an-instance-prevent-reference-deduplication-collisions-across-heterogeneous-identifier-schemes.md
# Remnant Warrant:    https://corpusfetch.com/c/how-must-an-instance-prevent-reference-deduplication-collisions-across-heterogeneous-identifier-schemes.warrant.json
# Markdown SHA-256:   e44c7b181d1a30583c5a38907060cb94514102577295c2e40caec33d7b49b721
# Code AST SHA-256:   b54f80e30cd5826340eb0ab148af6fb16c92c24a3eeaccaafe6d564e8a7c86b5
# Verified Classes:   DeduplicationVerdict, Reference, DeduplicationPair, DedupPolicy, DedupManifest, HeterogeneousDedupGuard
# Defensive Guards:   0 fail-closed invariants (zero external deps)

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

class DeduplicationVerdict(Enum):
    SINGLE_SCHEME = auto()
    SAFE_TO_MERGE = auto()
    KEEP_SEPARATE = auto()
    COLLISION_DETECTED = auto()

@dataclass(frozen=True)
class Reference:
    reference_id: str
    identifier_scheme: str
    identifier_value: str

@dataclass(frozen=True)
class DeduplicationPair:
    reference_a: Reference
    reference_b: Reference
    canonical_binding: str | None
    resolves_to_same_resource: bool | None

@dataclass(frozen=True)
class DedupPolicy:
    require_canonical_binding: bool

@dataclass(frozen=True)
class DedupManifest:
    verdict: DeduplicationVerdict
    directive: str
    manifest_digest: str

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

    @classmethod
    def evaluate_pair(
        cls, pair: DeduplicationPair, policy: DedupPolicy
    ) -> DedupManifest:
        
        # Gate 1: Same scheme
        if pair.reference_a.identifier_scheme == pair.reference_b.identifier_scheme:
            if pair.reference_a.identifier_value == pair.reference_b.identifier_value:
                digest = cls._hash(json.dumps({
                    "ref_a": pair.reference_a.reference_id,
                    "ref_b": pair.reference_b.reference_id,
                    "scheme": pair.reference_a.identifier_scheme
                }, sort_keys=True))
                return DedupManifest(
                    verdict=DeduplicationVerdict.SAFE_TO_MERGE,
                    directive=f"PROCEED: Same scheme, same value, safe to merge.",
                    manifest_digest=digest
                )
            return DedupManifest(
                verdict=DeduplicationVerdict.KEEP_SEPARATE,
                directive=f"PROCEED: Same scheme, different values, keep separate.",
                manifest_digest=cls._hash(f"DIFF_VALUES:{pair.reference_a.identifier_scheme}")
            )

        # Gate 2: Different schemes, no canonical binding
        if policy.require_canonical_binding and not pair.canonical_binding:
            if pair.resolves_to_same_resource is None:
                return DedupManifest(
                    verdict=DeduplicationVerdict.KEEP_SEPARATE,
                    directive=f"HALT: Different schemes without canonical binding. Keep separate (conservative).",
                    manifest_digest=cls._hash(f"NO_BINDING:{pair.reference_a.identifier_scheme}")
                )
            if pair.resolves_to_same_resource is False:
                return DedupManifest(
                    verdict=DeduplicationVerdict.COLLISION_DETECTED,
                    directive=f"HALT: Schemes {pair.reference_a.identifier_scheme} and {pair.reference_b.identifier_scheme} resolve differently. Keep separate.",
                    manifest_digest=cls._hash(f"COLLISION:{pair.reference_a.identifier_scheme}")
                )

        # Gate 3: Canonical binding present
        if pair.canonical_binding and pair.resolves_to_same_resource:
            digest = cls._hash(json.dumps({
                "ref_a": pair.reference_a.reference_id,
                "ref_b": pair.reference_b.reference_id,
                "scheme_a": pair.reference_a.identifier_scheme,
                "scheme_b": pair.reference_b.identifier_scheme,
                "binding": pair.canonical_binding
            }, sort_keys=True))
            return DedupManifest(
                verdict=DeduplicationVerdict.SAFE_TO_MERGE,
                directive=f"PROCEED: Canonical binding proves equivalence across schemes.",
                manifest_digest=digest
            )

        # Gate 4: Default conservative
        return DedupManifest(
            verdict=DeduplicationVerdict.KEEP_SEPARATE,
            directive=f"PROCEED: Insufficient evidence, keep separate.",
            manifest_digest=cls._hash(f"CONSERVATIVE:{pair.reference_a.reference_id}")
        )