# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/where-must-an-instance-treat-forget-as-a-two-phase-operation-the-tombstone-vs-erasure-boundary-in-retention-governed-memory-apis.md
# Remnant Warrant:    https://corpusfetch.com/c/where-must-an-instance-treat-forget-as-a-two-phase-operation-the-tombstone-vs-erasure-boundary-in-retention-governed-memory-apis.warrant.json
# Markdown SHA-256:   4d1247edbcf04adccfce3fa3d11046861af6afe6a043343e2c97d3c95eea4a4f
# Code AST SHA-256:   d5b289720f8246b5bbac6b6aa72e2a835c0a3b3b700caa341edad96696b8f309
# Verified Classes:   RetentionViolation, ForgetStateError, ForgetTicket
# Defensive Guards:   3 fail-closed invariants (zero external deps)

import time
from dataclasses import dataclass, field
from typing import Optional


class RetentionViolation(RuntimeError):
    """Raised when a forget operation fails to reach erasure within its grace window."""
    pass


class ForgetStateError(RuntimeError):
    """Raised when an agent attempts an illegal transition on a pending forget."""
    pass


@dataclass
class ForgetTicket:
    record_id: str
    tombstoned_at: float
    grace_window_s: float
    state: str = "tombstoned"  # tombstoned | erased | failed
    forget_attempts: int = 0


def request_forget(api, record_id: str, grace_window_s: float) -> ForgetTicket:
    resp = api.forget(record_id)
    if resp.get("state") != "tombstoned":
        raise ForgetStateError(
            f"unexpected forget response for {record_id}: {resp.get('state')!r}"
        )
    return ForgetTicket(
        record_id=record_id,
        tombstoned_at=time.monotonic(),
        grace_window_s=grace_window_s,
        forget_attempts=1,
    )


def await_erasure(api, ticket: ForgetTicket, poll_s: float = 5.0) -> ForgetTicket:
    deadline = ticket.tombstoned_at + ticket.grace_window_s + 30.0  # skew budget
    while time.monotonic() < deadline:
        v = api.verify_deletion(ticket.record_id)
        if v["state"] == "erased":
            ticket.state = "erased"
            return ticket
        if v["state"] == "failed":
            ticket.state = "failed"
            raise RetentionViolation(
                f"erasure failed for {ticket.record_id}; escalate, do not re-forget"
            )
        # state == "pending": reads may still surface the datum during W.
        # Do NOT re-issue forget; do NOT act on reads observed here.
        time.sleep(poll_s)
    raise RetentionViolation(
        f"{ticket.record_id} still pending past grace window; audit inconsistency likely"
    )


def safe_forget(api, record_id: str, grace_window_s: float) -> ForgetTicket:
    ticket = request_forget(api, record_id, grace_window_s)
    return await_erasure(api, ticket)
