# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/what-happens-when-an-instance-acknowledges-a-deletion-it-has-not-yet-made-durable-the-tombstone-before-durability-inversion-in-verifiable-memory-forge.md
# Remnant Warrant:    https://corpusfetch.com/c/what-happens-when-an-instance-acknowledges-a-deletion-it-has-not-yet-made-durable-the-tombstone-before-durability-inversion-in-verifiable-memory-forge.warrant.json
# Markdown SHA-256:   ba87384f67d2c0ac8028f99e0c09adb88e230e9becc74ba153ca9b5c0b3a7714
# Code AST SHA-256:   92c64ff7ec9233f924b7917feea4be03b8b3bbd1f918f279fe3b97f0e4bb5866
# Verified Classes:   ErasureAuditError, PurgeState, PurgeProof
# Defensive Guards:   4 fail-closed invariants (zero external deps)

import hashlib
from dataclasses import dataclass
from enum import Enum


class ErasureAuditError(RuntimeError):
    """Raised when an audit receipt would assert erasure not yet durable."""
    pass


class PurgeState(Enum):
    TOMBSTONED = "tombstoned"          # logical delete only
    PENDING_PURGE = "pending_purge"    # acknowledged, deadline set
    ERASED = "erased"                  # durable across all shards


@dataclass(frozen=True)
class PurgeProof:
    record_id: str
    min_shard_compaction_seq: int      # minimum over shards, not maximum
    destroyed_range_digest: str
    shards_covered: frozenset


def emit_terminal_erasure_receipt(
    record_id: str,
    state: PurgeState,
    proof: PurgeProof | None,
    required_shards: frozenset,
) -> dict:
    """Emit an `erased_at` receipt ONLY when durable erasure is proven.

    This is the guard that prevents the tombstone-before-durability
    inversion: a past-tense `erased_at` is a commitment to fact.
    """
    if state is not PurgeState.ERASED:
        raise ErasureAuditError(
            f"refusing terminal receipt for {record_id}: state={state.value}; "
            "emit a pending_purge receipt with a deadline instead"
        )
    if proof is None:
        raise ErasureAuditError(
            f"refusing terminal receipt for {record_id}: no purge proof"
        )
    missing = required_shards - proof.shards_covered
    if missing:
        raise ErasureAuditError(
            f"refusing terminal receipt for {record_id}: shards not purged: "
            f"{sorted(missing)}"
        )
    if proof.destroyed_range_digest != hashlib.sha256(
        f"{record_id}:{proof.min_shard_compaction_seq}".encode()
    ).hexdigest():
        raise ErasureAuditError(
            f"refusing terminal receipt for {record_id}: digest mismatch"
        )
    return {
        "record_id": record_id,
        "status": "erased",
        "erased_at_durable": True,
        "min_compaction_seq": proof.min_shard_compaction_seq,
        "digest": proof.destroyed_range_digest,
    }


def acknowledge_deletion(record_id: str, deadline_ts: int) -> dict:
    """Request-path acknowledgment: honest about incompleteness."""
    return {
        "record_id": record_id,
        "status": "pending_purge",
        "erasure_deadline": deadline_ts,
        # NOTE: intentionally no `erased_at` field here.
    }
