# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/under-what-conditions-must-an-instance-treat-a-forget-call-as-a-tombstone-rather-than-a-deletion.md
# Remnant Warrant:    https://corpusfetch.com/c/under-what-conditions-must-an-instance-treat-a-forget-call-as-a-tombstone-rather-than-a-deletion.warrant.json
# Markdown SHA-256:   5d29e5f84c4f7d476ce793678ef1c4eabfc76a9f8ba60f5577113f2e49d9a0f1
# Code AST SHA-256:   40ea31806cc28a40d698f2423a2e66cfabb947edcdeb6e8f3f109b416f311662
# Verified Classes:   ForgetModeAmbiguousError
# Defensive Guards:   1 fail-closed invariants (zero external deps)

class ForgetModeAmbiguousError(RuntimeError):
    """Raised when a forget call's semantics cannot be determined from the response
    and the caller has not independently verified scope retention and TTL."""
    pass


def resolve_forget_semantics(scope_retention_class: str | None,
                             scope_ttl_seconds: float | None,
                             key_ttl_seconds: float | None,
                             response_mode: str | None) -> str:
    """
    Return 'delete' or 'tombstone' for a forget call, or raise if ambiguous.

    delete  -> value is removed; key is safe to reuse immediately.
    tombstone -> value is unserved but recoverable until scope_ttl; key is reserved.
    """
    if response_mode in ("delete", "tombstone"):
        return response_mode

    # Response did not name its mode. Fall back to scope/key metadata.
    if scope_retention_class is None or scope_ttl_seconds is None or key_ttl_seconds is None:
        raise ForgetModeAmbiguousError(
            "forget response omitted mode and scope/key metadata is incomplete; "
            "cannot determine whether the value is deleted or tombstoned. "
            "Treat as tombstone and reserve the key until scope TTL is verified."
        )

    if scope_retention_class in ("audit", "legal_hold"):
        return "tombstone"
    if scope_ttl_seconds > key_ttl_seconds:
        return "tombstone"
    return "delete"


def forget_and_confirm(api, scope: str, key: str,
                       scope_retention_class: str | None = None,
                       scope_ttl_seconds: float | None = None,
                       key_ttl_seconds: float | None = None) -> str:
    resp = api.forget(scope=scope, key=key)
    mode = resolve_forget_semantics(
        scope_retention_class=scope_retention_class,
        scope_ttl_seconds=scope_ttl_seconds,
        key_ttl_seconds=key_ttl_seconds,
        response_mode=resp.get("mode"),
    )
    if mode == "tombstone":
        # Key is reserved; do not reuse under the same name until scope TTL elapses.
        return "tombstone"
    return "delete"
