# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/in-what-scenarios-must-an-instance-treat-a-memory-tool-forget-as-unverified-until-a-read-back-confirms-tombstoning.md
# Remnant Warrant:    https://corpusfetch.com/c/in-what-scenarios-must-an-instance-treat-a-memory-tool-forget-as-unverified-until-a-read-back-confirms-tombstoning.warrant.json
# Markdown SHA-256:   e3a983e47924e7ad8e40f4d3507dcb4a3f47293caee709ccd832facae5a7279c
# Code AST SHA-256:   e034877e7421c7455166ba32944d5dde1990dca53ff13cb9ff54aa9daf75f5c9
# Verified Classes:   UnverifiedDeletionError
# Defensive Guards:   3 fail-closed invariants (zero external deps)

class UnverifiedDeletionError(RuntimeError):
    """Raised when a forget() has not been confirmed absent on all read surfaces."""
    pass


ABSENCE_MARKERS = {"__deleted__", "__tombstoned__", "__absent__"}


def forget_and_verify(memory_api, key: str, namespace: str,
                      read_surfaces: list[str],
                      max_verify_attempts: int = 3) -> None:
    """
    Issue a forget and require every named read surface to return a typed
    absence marker before the deletion is considered committed.

    Raises UnverifiedDeletionError if any surface still returns a value,
    or if a surface returns a non-typed not-found (ambiguous absence).
    """
    if not read_surfaces:
        raise UnverifiedDeletionError(
            f"refusing to certify deletion of {namespace}/{key}: "
            "no read surfaces enumerated; alias leakage unverifiable"
        )

    resp = memory_api.forget(key, namespace=namespace)
    if not resp.get("ok"):
        raise UnverifiedDeletionError(
            f"forget rejected for {namespace}/{key}: {resp!r}"
        )

    for attempt in range(max_verify_attempts):
        unverified = []
        for surface in read_surfaces:
            result = memory_api.read(key, namespace=surface)
            if result is None or result not in ABSENCE_MARKERS:
                # None means "not found" but could be wrong-namespace;
                # a real value means tombstone has not propagated.
                unverified.append((surface, result))
        if not unverified:
            return
        # brief backoff omitted for brevity; retry the read-back only

    raise UnverifiedDeletionError(
        f"deletion of {namespace}/{key} unverified after "
        f"{max_verify_attempts} attempts; stale surfaces: {unverified!r}"
    )
