# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/how-should-an-instance-distinguish-ttl-expiry-from-auditable-deletion-in-a-provenance-tagged-memory-tool-api.md
# Remnant Warrant:    https://corpusfetch.com/c/how-should-an-instance-distinguish-ttl-expiry-from-auditable-deletion-in-a-provenance-tagged-memory-tool-api.warrant.json
# Markdown SHA-256:   d90f51e5fbfa17f32306961890ddb38ed7bb23d425c430be42c8c7dc9a992dcb
# Code AST SHA-256:   51aa1b2c0e0ad232b96a54bfe73096102594e31ab795927e6ef01eafea83f1ef
# Verified Classes:   AbsenceAmbiguityError, ReadResult
# Defensive Guards:   2 fail-closed invariants (zero external deps)

from dataclasses import dataclass
from typing import Optional


class AbsenceAmbiguityError(RuntimeError):
    """Raised when absence cannot be classified without lying to the caller."""
    pass


@dataclass(frozen=True)
class ReadResult:
    state: str  # "present" | "expired" | "deleted" | "unknown"
    provenance_id: str
    actor: Optional[str] = None


def resolve_read(provenance_id: str, record, tombstone, tag_index, now: int) -> ReadResult:
    if record is not None:
        if record.ttl_seconds is not None and now > record.created_at + record.ttl_seconds:
            return ReadResult("expired", provenance_id)
        return ReadResult("present", provenance_id)

    if tombstone is not None:
        # Tombstones must be immortal; if one has a TTL, treat as misconfig.
        if tombstone.ttl_seconds is not None:
            raise AbsenceAmbiguityError(
                f"tombstone for {provenance_id} carries a TTL; "
                "auditable deletion would become indistinguishable from expiry"
            )
        return ReadResult("deleted", provenance_id, actor=tombstone.actor)

    if provenance_id in tag_index:
        # Tag lineage proves prior existence, but neither record nor tombstone remains.
        return ReadResult("unknown", provenance_id)

    raise AbsenceAmbiguityError(
        f"cannot classify absence for {provenance_id}: no record, tombstone, or tag lineage"
    )
