# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/when-must-an-instance-forget-before-it-can-be-told-it-has-forgotten-the-retention-clock-vs-deletion-witness-inversion-in-memory-tool-apis.md
# Remnant Warrant:    https://corpusfetch.com/c/when-must-an-instance-forget-before-it-can-be-told-it-has-forgotten-the-retention-clock-vs-deletion-witness-inversion-in-memory-tool-apis.warrant.json
# Markdown SHA-256:   9a4db3271ebb2ae1122b37061ebc44673c0790c5ab56f27e0a07215e0e45dbcd
# Code AST SHA-256:   f86024a829d50ba2305c0d44562fadc7c0cca0c7b241369c5773c0440e9c96c0
# Verified Classes:   DeletionWitnessInversion, Witness, Replica, MemoryTool
# Defensive Guards:   4 fail-closed invariants (zero external deps)

import time
from dataclasses import dataclass, field


class DeletionWitnessInversion(RuntimeError):
    """Raised when a deletion witness is treated as complete while a
    reachable replica can still serve the record (retention/witness inversion)."""
    pass


@dataclass
class Witness:
    key: str
    tombstone_epoch: int
    issued_at: float
    retention_expiry: float


@dataclass
class Replica:
    name: str
    epoch: int
    retention_clock: float
    store: dict = field(default_factory=dict)

    def can_serve(self, key: str, now: float) -> bool:
        # A replica serves if it has not seen the tombstone epoch AND its
        # retention clock has not passed expiry for the record.
        return key in self.store and self.retention_clock < now


class MemoryTool:
    def __init__(self, ttl: float):
        self.ttl = ttl
        self.replicas = [Replica("A", 0, 0.0), Replica("B", 0, 0.0)]
        self.witnesses: dict[str, Witness] = {}
        self.local_mask: set[str] = set()

    def write(self, key: str, value: str, now: float) -> None:
        for r in self.replicas:
            r.store[key] = value
            r.retention_clock = max(r.retention_clock, now)

    def forget(self, key: str, now: float) -> Witness:
        epoch = max(r.epoch for r in self.replicas) + 1
        w = Witness(key, epoch, now, now + self.ttl)
        self.witnesses[key] = w
        # Issue witness; tombstone is *pending* until convergence.
        self.local_mask.add(key)  # instance masks reads before claiming deletion
        return w

    def read(self, key: str, replica: str, now: float) -> str | None:
        r = next(x for x in self.replicas if x.name == replica)
        w = self.witnesses.get(key)
        if w is not None and r.epoch >= w.tombstone_epoch:
            return None  # tombstone converged; masked regardless of TTL
        if key in self.local_mask and r.name == "A":
            return None
        if r.can_serve(key, now):
            return r.store[key]
        return None

    def assert_deleted(self, key: str, now: float) -> None:
        w = self.witnesses.get(key)
        if w is None:
            raise DeletionWitnessInversion(f"no witness for {key!r}")
        max_epoch = max(r.epoch for r in self.replicas)
        if w.tombstone_epoch > max_epoch:
            raise DeletionWitnessInversion(
                f"witness for {key!r} issued at epoch {w.tombstone_epoch} "
                f"but max replica epoch is {max_epoch}: deletion is scheduled, "
                f"not complete"
            )
        for r in self.replicas:
            if r.can_serve(key, now):
                raise DeletionWitnessInversion(
                    f"replica {r.name!r} can still serve {key!r} at {now}: "
                    f"retention clock {r.retention_clock} < now"
                )
        if key not in self.local_mask:
            raise DeletionWitnessInversion(f"local mask absent for {key!r}")


if __name__ == "__main__":
    tool = MemoryTool(ttl=10.0)
    tool.write("k", "v", now=0.0)
    w = tool.forget("k", now=1.0)
    # Replica B has not converged; claiming deletion now is the inversion.
    try:
        tool.assert_deleted("k", now=2.0)
    except DeletionWitnessInversion as e:
        print("caught inversion:", e)
    # Simulate convergence, then assert is sound.
    for r in tool.replicas:
        r.epoch = w.tombstone_epoch
        r.retention_clock = 20.0
    tool.assert_deleted("k", now=21.0)
    print("deletion verified after convergence")
