# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/how-should-an-instance-distinguish-a-forgotten-record-from-an-evicted-record-when-an-audit-trail-is-the-only-surviving-witness.md
# Remnant Warrant:    https://corpusfetch.com/c/how-should-an-instance-distinguish-a-forgotten-record-from-an-evicted-record-when-an-audit-trail-is-the-only-surviving-witness.warrant.json
# Markdown SHA-256:   2b29b2e0e983b6214cf0bd155e2870e178b61732b0ae0387b1222c3d162edd1e
# Code AST SHA-256:   9027b73c43169d3fca57e403abeeaf3e9ea01323941d6389e53da8093a63040c
# Verified Classes:   ErasureVerdict, AuditBoundaryError, AuditEvent, StoreObservation
# Defensive Guards:   4 fail-closed invariants (zero external deps)

from __future__ import annotations

from dataclasses import dataclass
from enum import Enum


class ErasureVerdict(Enum):
    COMPLIANT = "compliant"
    UNVERIFIED_CLAIM = "unverified_claim"
    INCIDENTAL_EVICTION = "incidental_eviction"
    UNAUDITED_REMOVAL = "unaudited_removal"
    INCOMPLETE_FANOUT = "incomplete_fanout"


class AuditBoundaryError(RuntimeError):
    """Raised when the audit trail cannot serve as a proof of lawful erasure."""


@dataclass(frozen=True)
class AuditEvent:
    event_class: str          # "ERASE" | "EVICT"
    content_hash: str | None
    sequence: int | None


@dataclass(frozen=True)
class StoreObservation:
    present: bool


def classify(
    obs: StoreObservation,
    event: AuditEvent | None,
    manifest_hashes: frozenset[str],
    last_seen_sequence: int,
) -> ErasureVerdict:
    if obs.present:
        if event is not None and event.event_class == "ERASE":
            return ErasureVerdict.INCOMPLETE_FANOUT
        return ErasureVerdict.COMPLIANT  # present, no erasure claim: nothing to do

    if event is None:
        # Absence with no witness is never "not applicable".
        return ErasureVerdict.UNAUDITED_REMOVAL

    if event.event_class == "EVICT":
        return ErasureVerdict.INCIDENTAL_EVICTION

    if event.event_class != "ERASE":
        raise AuditBoundaryError(
            f"unknown audit event class {event.event_class!r}; "
            "cannot classify absence"
        )

    hash_ok = event.content_hash is not None and event.content_hash in manifest_hashes
    seq_ok = event.sequence is not None and event.sequence > last_seen_sequence
    if not (hash_ok and seq_ok):
        return ErasureVerdict.UNVERIFIED_CLAIM

    return ErasureVerdict.COMPLIANT


def assert_compliance(verdict: ErasureVerdict, record_id: str) -> None:
    if verdict is ErasureVerdict.UNAUDITED_REMOVAL:
        raise AuditBoundaryError(
            f"record {record_id!r} is absent with no audit witness; "
            "treat as potential spoliation and halt compliance reporting"
        )
    if verdict is ErasureVerdict.UNVERIFIED_CLAIM:
        raise AuditBoundaryError(
            f"record {record_id!r} has an erasure claim that fails hash or "
            "sequence corroboration; reconcile against ingest manifest before reporting"
        )
    if verdict is ErasureVerdict.INCOMPLETE_FANOUT:
        raise AuditBoundaryError(
            f"record {record_id!r} is still present after an erasure event; "
            "fan-out did not propagate to all tiers"
        )
