# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/how-does-an-instance-detect-policy-drift-at-a-federated-protocol-boundary-when-the-ledger-is-append-only-but-the-policy-bundle-is-mutable.md
# Remnant Warrant:    https://corpusfetch.com/c/how-does-an-instance-detect-policy-drift-at-a-federated-protocol-boundary-when-the-ledger-is-append-only-but-the-policy-bundle-is-mutable.warrant.json
# Markdown SHA-256:   de7e6442815e7dabfe1454a861c9fb5fb2720faf7b51dd237a3bcc81b02b0479
# Code AST SHA-256:   87da2248de3506a3f552a0ff1f0a789e1b785d2306ab42e6318b976c1a443cdc
# Verified Classes:   PolicyDriftError, DivergenceClass, LedgerEntry
# Defensive Guards:   2 fail-closed invariants (zero external deps)

import hashlib
from dataclasses import dataclass
from enum import Enum


class PolicyDriftError(RuntimeError):
    """Raised when ledger replay cannot reproduce a decision and the cause is
    a mutable policy bundle rather than ledger tampering."""
    pass


class DivergenceClass(Enum):
    INTEGRITY = "integrity"          # digests match, outcomes differ -> tampering
    DRIFT = "drift"                  # digests differ, bundle bytes changed
    INDETERMINATE = "indeterminate"  # bundle no longer resolvable


@dataclass(frozen=True)
class LedgerEntry:
    decision: str                    # "admit" | "deny"
    policy_digest: str | None        # sha256 of effective policy closure at decision time
    bundle_ref: str                  # human label, e.g. "grants-v7"


def digest_bytes(b: bytes) -> str:
    return hashlib.sha256(b).hexdigest()


def classify_divergence(
    entry: LedgerEntry,
    current_bundle_bytes: bytes | None,
    replayed_decision: str | None,
) -> DivergenceClass:
    """Classify a replay divergence. Must branch on digest equality BEFORE
    branching on outcome equality, or drift is misread as tampering."""
    if current_bundle_bytes is None or replayed_decision is None:
        return DivergenceClass.INDETERMINATE

    current_digest = digest_bytes(current_bundle_bytes)

    # Digest is the discriminator. If the ledger never recorded one, we cannot
    # distinguish drift from tampering.
    if entry.policy_digest is None:
        raise PolicyDriftError(
            f"ledger entry for bundle {entry.bundle_ref!r} lacks a policy digest; "
            "replay divergence cannot be classified as drift vs. tampering"
        )

    if entry.policy_digest == current_digest:
        # Same bytes, different outcome -> the engine or ledger is compromised.
        if entry.decision != replayed_decision:
            return DivergenceClass.INTEGRITY
        return DivergenceClass.INTEGRITY  # should not reach here if caller only passes divergences
    else:
        # Bytes changed since decision time -> mutable bundle, i.e. drift.
        return DivergenceClass.DRIFT


def audit_replay(entries: list[LedgerEntry], resolve_bundle) -> dict:
    """Replay ledger entries; raise PolicyDriftError only on unclassifiable cases."""
    counts = {c: 0 for c in DivergenceClass}
    for e in entries:
        bundle = resolve_bundle(e.bundle_ref)
        replayed = None if bundle is None else evaluate(bundle, e)
        if replayed is None:
            counts[DivergenceClass.INDETERMINATE] += 1
            continue
        if replayed == e.decision:
            continue
        cls = classify_divergence(e, bundle, replayed)
        counts[cls] += 1
    return counts


def evaluate(bundle: bytes, entry: LedgerEntry) -> str:
    # Placeholder for the real policy engine; raises if bundle is unusable.
    if not bundle:
        raise PolicyDriftError(f"empty bundle for {entry.bundle_ref!r}")
    return entry.decision  # engine stub
