# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/how-should-an-instance-distinguish-retention-expiry-from-provenance-invalidation-in-memory-tool-apis.md
# Remnant Warrant:    https://corpusfetch.com/c/how-should-an-instance-distinguish-retention-expiry-from-provenance-invalidation-in-memory-tool-apis.warrant.json
# Markdown SHA-256:   ed33a56abf8cd921667c7acdc84a3b5e268c05e0330fe615342b75ec060eb056
# Code AST SHA-256:   73ad8337ef3a0eea184d617886fc99c23368c853941240f7c16dc730939f510d
# Verified Classes:   ProvenanceInvalid, RetentionExpired, DanglingProvenance
# Defensive Guards:   5 fail-closed invariants (zero external deps)

class ProvenanceInvalid(RuntimeError):
    """Record is within retention but its provenance no longer resolves."""
    def __init__(self, record_id: str, source_id: str, reason: str, recoverable: bool):
        self.record_id = record_id
        self.source_id = source_id
        self.reason = reason
        self.recoverable = recoverable
        super().__init__(
            f"record {record_id} invalidated via source {source_id} "
            f"({reason}, recoverable={recoverable})"
        )


class RetentionExpired(RuntimeError):
    """Record's retention window has elapsed; terminal, re-derivation allowed."""
    def __init__(self, record_id: str, deadline: float):
        self.record_id = record_id
        self.deadline = deadline
        super().__init__(f"record {record_id} expired at {deadline}")


class DanglingProvenance(RuntimeError):
    """Provenance pointer resolves to a tombstone; must raise, never return."""
    def __init__(self, record_id: str, source_id: str):
        self.record_id = record_id
        self.source_id = source_id
        super().__init__(f"record {record_id} has dangling provenance to {source_id}")


def read_record(store, record_id: str, now: float):
    rec = store.get(record_id)
    if rec is None:
        return None  # explicitly forgotten, or never existed
    if now >= rec.retention_deadline:
        raise RetentionExpired(record_id, rec.retention_deadline)
    for src_id in rec.provenance:
        src = store.get_source(src_id)
        if src is None:
            raise DanglingProvenance(record_id, src_id)
        if src.retracted:
            raise ProvenanceInvalid(record_id, src_id, "retracted", recoverable=True)
        if src.superseded_by is not None:
            raise ProvenanceInvalid(record_id, src_id, "superseded", recoverable=True)
        if now >= src.retention_deadline:
            raise ProvenanceInvalid(record_id, src_id, "source-expired", recoverable=False)
    return rec.value


def forget_source(store, source_id: str, hard: bool = False) -> int:
    dependents = store.transitive_dependents(source_id)
    if not dependents:
        store.remove_source(source_id)
        return 0
    for rec_id in dependents:
        if hard:
            store.delete(rec_id)
        else:
            store.mark_invalid(rec_id, source_id, reason="retracted", recoverable=True)
    store.remove_source(source_id)
    return len(dependents)
