# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/how-does-an-instance-detect-ttl-expiry-versus-an-unproven-deletion-in-a-scoped-memory-store.md
# Remnant Warrant:    https://corpusfetch.com/c/how-does-an-instance-detect-ttl-expiry-versus-an-unproven-deletion-in-a-scoped-memory-store.warrant.json
# Markdown SHA-256:   7bdde32cbe51f5f814c2d72a013069b559aebe36a96d219bc3481d7cc2882e49
# Code AST SHA-256:   1f0a1332925f2c68d77dd76181dbbd82fbb7bd927080481a7193dc16c659095e
# Verified Classes:   MemoryContractViolation
# Defensive Guards:   6 fail-closed invariants (zero external deps)

class MemoryContractViolation(RuntimeError):
    """Raised when a read miss is treated as a deletion proof without a valid receipt."""
    pass


VALID_READ_STATUSES = {"live", "expired", "deleted", "absent"}


def resolve_forget(
    read_result: dict,
    last_written_generation: int,
    forget_receipt: dict | None,
) -> str:
    """
    Decide whether a forget contract is satisfied given a read result and any receipt.

    read_result: {"status": str, "generation": int | None, "scope": str, "key": str}
    forget_receipt: {"generation": int, "kind": "deleted" | "no_live_value", "epoch": int} | None
    """
    status = read_result.get("status")
    if status not in VALID_READ_STATUSES:
        raise MemoryContractViolation(
            f"read returned undiscriminated status {status!r}; "
            "cannot distinguish expiry from deletion"
        )

    if status == "live":
        if forget_receipt is not None:
            raise MemoryContractViolation(
                f"proof-visibility violation: receipt for generation "
                f"{forget_receipt['generation']} issued but value still live "
                f"at generation {read_result.get('generation')}"
            )
        return "live_no_forget_attempted"

    if status == "deleted":
        if forget_receipt is None:
            raise MemoryContractViolation(
                "read reports deleted but no receipt supplied; "
                "deletion is unproven"
            )
        if forget_receipt["generation"] != last_written_generation:
            raise MemoryContractViolation(
                f"receipt generation {forget_receipt['generation']} does not cover "
                f"last written generation {last_written_generation}"
            )
        return "forget_complete_with_proof"

    if status == "expired":
        # Value gone by time, but no deletion proof yet. Contract may still require one.
        if forget_receipt is None:
            return "expired_unproven_requires_forget"
        if forget_receipt["kind"] != "no_live_value":
            raise MemoryContractViolation(
                "expired entry has receipt of kind 'deleted'; "
                "receipt kind inconsistent with observed status"
            )
        return "forget_complete_no_live_value"

    # status == "absent"
    if forget_receipt is not None:
        raise MemoryContractViolation(
            "receipt supplied for a key that reads absent in this scope; "
            "scope key or generation mismatch"
        )
    return "absent_verify_scope_no_deletion_inferred"
