superlocalmemory 3.8.13 → 4.0.0

package/src/superlocalmemory/core/transactions/erasure.py

@@ -0,0 +1,825 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under AGPL-3.0-or-later - see LICENSE file
+
+from __future__ import annotations
+
+import hashlib
+import hmac as _hmac_mod
+import json
+import logging
+import time
+from collections.abc import Callable, Iterable, Mapping
+from dataclasses import dataclass
+
+_RECEIPT_V1: int = 1
+_RECEIPT_V2: int = 2
+
+from superlocalmemory.core.transactions.obligations import ObligationLedger
+from superlocalmemory.core.transactions.owners import (
+    ObligationKind,
+    ObligationState,
+    OperationContext,
+    ProjectionOwner,
+)
+
+logger = logging.getLogger("superlocalmemory.core.transactions.erasure")
+
+MAX_ERASE_ATTEMPTS = 10
+
+VALID_SUBJECT_TYPES = frozenset({"fact", "entity", "profile"})
+
+AuditLogger = Callable[[Mapping[str, object]], None]
+
+
+class ErasureState:
+    COMPLETE = "COMPLETE"
+    FAILED = "FAILED"
+
+
+@dataclass(frozen=True, slots=True)
+class ErasureProofRecord:
+    owner: str
+    erased: bool
+    checksum: str
+    residue: tuple[str, ...] = ()
+
+    def as_dict(self) -> dict[str, object]:
+        return {
+            "owner": self.owner,
+            "erased": bool(self.erased),
+            "checksum": self.checksum,
+            "residue": list(self.residue),
+        }
+
+
+@dataclass(frozen=True, slots=True)
+class RemoveResult:
+    proofs: tuple["ErasureProofRecord", ...]
+    spine_ok: bool
+    tombstoned: bool
+
+
+@dataclass(frozen=True, slots=True)
+class ErasureReceipt:
+    erasure_id: str
+    profile_id: str
+    subject_type: str
+    subject_id: str
+    requested_by: str
+    fact_count: int
+    state: str
+    all_erased: bool
+    proofs: tuple[ErasureProofRecord, ...]
+    audit_hash: str
+    requested_at: float
+    completed_at: float
+    persisted: bool
+
+
+def _proof_dicts(proofs: Iterable[ErasureProofRecord]) -> list[dict[str, object]]:
+    return sorted((p.as_dict() for p in proofs), key=lambda d: d["owner"])
+
+
+def compute_erasure_hash(
+    *,
+    erasure_id: str,
+    profile_id: str,
+    subject_type: str,
+    subject_id: str,
+    requested_by: str,
+    fact_count: int,
+    state: str,
+    all_erased: bool,
+    evidence_json: str,
+    requested_at: float,
+    completed_at: float,
+) -> str:
+    """Unkeyed SHA-256 hash for erasure receipts (v1, backward-compat)."""
+    canonical = _erasure_canonical(
+        erasure_id=erasure_id,
+        profile_id=profile_id,
+        subject_type=subject_type,
+        subject_id=subject_id,
+        requested_by=requested_by,
+        fact_count=fact_count,
+        state=state,
+        all_erased=all_erased,
+        evidence_json=evidence_json,
+        requested_at=requested_at,
+        completed_at=completed_at,
+    )
+    return hashlib.sha256(canonical).hexdigest()
+
+
+def _erasure_canonical(
+    *,
+    erasure_id: str,
+    profile_id: str,
+    subject_type: str,
+    subject_id: str,
+    requested_by: str,
+    fact_count: int,
+    state: str,
+    all_erased: bool,
+    evidence_json: str,
+    requested_at: float,
+    completed_at: float,
+    receipt_version: int | None = None,
+) -> bytes:
+    """Produce the deterministic byte representation of the erasure receipt envelope.
+
+    When ``receipt_version`` is provided (v2+), it is bound into the canonical
+    bytes so a downgrade from v2 → v1 is detected by the MAC mismatch.
+    """
+    envelope: dict[str, object] = {
+        "erasure_id": erasure_id,
+        "profile_id": profile_id,
+        "subject_type": subject_type,
+        "subject_id": subject_id,
+        "requested_by": requested_by,
+        "fact_count": fact_count,
+        "state": state,
+        "all_erased": bool(all_erased),
+        "evidence": evidence_json,
+        "requested_at": repr(float(requested_at)),
+        "completed_at": repr(float(completed_at)),
+    }
+    if receipt_version is not None:
+        envelope["receipt_version"] = receipt_version
+    return json.dumps(
+        envelope, sort_keys=True, separators=(",", ":"), ensure_ascii=False,
+    ).encode("utf-8")
+
+
+def compute_erasure_hmac(
+    *,
+    erasure_id: str,
+    profile_id: str,
+    subject_type: str,
+    subject_id: str,
+    requested_by: str,
+    fact_count: int,
+    state: str,
+    all_erased: bool,
+    evidence_json: str,
+    requested_at: float,
+    completed_at: float,
+    key: bytes | None = None,
+) -> str:
+    """HMAC-SHA256 keyed hash for erasure receipts (v2).
+
+    ``key`` is injected in tests; production code passes ``key=None`` to
+    auto-derive from the installation key.
+    """
+    from superlocalmemory.core.transactions.manifest_key import (
+        compute_hmac,
+        derive_receipt_hmac_key,
+    )
+
+    actual_key = key if key is not None else derive_receipt_hmac_key()
+    canonical = _erasure_canonical(
+        erasure_id=erasure_id,
+        profile_id=profile_id,
+        subject_type=subject_type,
+        subject_id=subject_id,
+        requested_by=requested_by,
+        fact_count=fact_count,
+        state=state,
+        all_erased=all_erased,
+        evidence_json=evidence_json,
+        requested_at=requested_at,
+        completed_at=completed_at,
+        receipt_version=_RECEIPT_V2,
+    )
+    return compute_hmac(actual_key, canonical)
+
+
+class ErasureService:
+    def __init__(
+        self,
+        owners: Mapping[str, ProjectionOwner],
+        *,
+        ledger: ObligationLedger | None = None,
+        audit_logger: AuditLogger | None = None,
+    ) -> None:
+        self._owners: dict[str, ProjectionOwner] = dict(owners)
+        self._ledger = ledger or ObligationLedger()
+        self._audit_logger = audit_logger
+
+    def erase(
+        self,
+        db: object,
+        context: OperationContext,
+        *,
+        subject_type: str,
+        subject_id: str,
+        requested_by: str = "",
+    ) -> ErasureReceipt:
+        requested_at = time.time()
+        remove_result = self.remove(db, context, memory_id=None)
+        return self.finalize(
+            db, context,
+            subject_type=subject_type, subject_id=subject_id,
+            requested_by=requested_by, requested_at=requested_at,
+            remove_result=remove_result,
+        )
+
+    def remove(
+        self, db: object, context: OperationContext, *, memory_id: str | None = None,
+    ) -> RemoveResult:
+        self._record_obligations(db, context)
+        status = write_tombstones_status(
+            db, context.profile_id, tuple(sorted(set(context.fact_ids))),
+            context.operation_id, time.time(), memory_id,
+        )
+        if status == TOMBSTONE_CONFLICT:
+            # Fail closed: do not delete owner projections under a provenance
+            # conflict — the resurrection guard cannot be trusted here.
+            return RemoveResult(proofs=(), spine_ok=False, tombstoned=False)
+        proofs = [self._erase_owner(db, context, name) for name in sorted(self._owners)]
+        owners_ok = bool(proofs) and all(p.erased for p in proofs)
+        # A missing tombstone table (older schema) or an empty fact set does not
+        # gate; a real write error on a modern store does.
+        tombstone_ok = status in (TOMBSTONE_WRITTEN, TOMBSTONE_ABSENT)
+        return RemoveResult(
+            proofs=tuple(proofs),
+            spine_ok=owners_ok and tombstone_ok,
+            tombstoned=(status == TOMBSTONE_WRITTEN),
+        )
+
+    def finalize(
+        self,
+        db: object,
+        context: OperationContext,
+        *,
+        subject_type: str,
+        subject_id: str,
+        requested_by: str = "",
+        requested_at: float | None = None,
+        extra_proofs: Iterable[ErasureProofRecord] = (),
+        remove_result: "RemoveResult | None" = None,
+    ) -> ErasureReceipt:
+        if subject_type not in VALID_SUBJECT_TYPES:
+            raise ValueError(f"invalid subject_type: {subject_type!r}")
+        requested_at = time.time() if requested_at is None else requested_at
+        proofs: list[ErasureProofRecord] = [
+            self._prove_owner(context, name) for name in sorted(self._owners)
+        ]
+        proofs.extend(extra_proofs)
+        owners_erased = bool(proofs) and all(p.erased for p in proofs)
+        # Fail closed: COMPLETE requires proven owner erasure AND, when the
+        # caller threads its remove() result, a clean tombstone step (no
+        # provenance conflict or write error on a modern store).
+        all_erased = owners_erased and (
+            remove_result.spine_ok if remove_result is not None else True
+        )
+        state = ErasureState.COMPLETE if all_erased else ErasureState.FAILED
+        evidence_json = json.dumps(
+            {"fact_ids": sorted(set(context.fact_ids)), "proofs": _proof_dicts(proofs)},
+            sort_keys=True,
+            separators=(",", ":"),
+            ensure_ascii=False,
+        )
+        fact_count = len(set(context.fact_ids))
+        completed_at = time.time()
+        receipt_version = _receipt_version_from_db(db)
+        if receipt_version >= _RECEIPT_V2:
+            audit_hash = compute_erasure_hmac(
+                erasure_id=context.operation_id,
+                profile_id=context.profile_id,
+                subject_type=subject_type,
+                subject_id=subject_id,
+                requested_by=requested_by,
+                fact_count=fact_count,
+                state=state,
+                all_erased=all_erased,
+                evidence_json=evidence_json,
+                requested_at=requested_at,
+                completed_at=completed_at,
+            )
+        else:
+            audit_hash = compute_erasure_hash(
+                erasure_id=context.operation_id,
+                profile_id=context.profile_id,
+                subject_type=subject_type,
+                subject_id=subject_id,
+                requested_by=requested_by,
+                fact_count=fact_count,
+                state=state,
+                all_erased=all_erased,
+                evidence_json=evidence_json,
+                requested_at=requested_at,
+                completed_at=completed_at,
+            )
+        persisted = self._persist(
+            db,
+            erasure_id=context.operation_id,
+            profile_id=context.profile_id,
+            subject_type=subject_type,
+            subject_id=subject_id,
+            requested_by=requested_by,
+            fact_count=fact_count,
+            state=state,
+            all_erased=all_erased,
+            evidence_json=evidence_json,
+            audit_hash=audit_hash,
+            requested_at=requested_at,
+            completed_at=completed_at,
+            fact_ids=tuple(sorted(set(context.fact_ids))),
+        )
+        self._emit_audit(
+            erasure_id=context.operation_id,
+            profile_id=context.profile_id,
+            subject_type=subject_type,
+            subject_id=subject_id,
+            requested_by=requested_by,
+            state=state,
+            audit_hash=audit_hash,
+        )
+        return ErasureReceipt(
+            erasure_id=context.operation_id,
+            profile_id=context.profile_id,
+            subject_type=subject_type,
+            subject_id=subject_id,
+            requested_by=requested_by,
+            fact_count=fact_count,
+            state=state,
+            all_erased=all_erased,
+            proofs=tuple(proofs),
+            audit_hash=audit_hash,
+            requested_at=requested_at,
+            completed_at=completed_at,
+            persisted=persisted,
+        )
+
+    def _prove_owner(
+        self, context: OperationContext, name: str,
+    ) -> ErasureProofRecord:
+        owner = self._owners[name]
+        try:
+            proof = owner.prove_erased(context)
+            erased = bool(proof.erased)
+            checksum = proof.checksum or ""
+            raw_residue = dict(proof.detail).get("residue")
+            residue = (
+                tuple(str(x) for x in raw_residue)
+                if isinstance(raw_residue, list) else ()
+            )
+        except Exception as exc:  # noqa: BLE001
+            erased = False
+            checksum = ""
+            residue = ()
+            logger.warning("erasure prove failed for %s: %s", name, _err(exc))
+        return ErasureProofRecord(
+            owner=name, erased=erased, checksum=checksum, residue=residue,
+        )
+
+    def _record_obligations(self, db: object, context: OperationContext) -> None:
+        try:
+            with db.raw_connection() as conn:
+                for name in sorted(self._owners):
+                    self._ledger.record(conn, context, name, ObligationKind.ERASE)
+        except Exception as exc:  # noqa: BLE001
+            logger.warning("erasure obligation record skipped: %s", _err(exc))
+
+    def _write_tombstones(
+        self,
+        db: object,
+        profile_id: str,
+        fact_ids: tuple[str, ...],
+        erasure_id: str,
+        created_at: float,
+        memory_id: str | None = None,
+    ) -> None:
+        write_tombstones(
+            db, profile_id, fact_ids, erasure_id, created_at, memory_id,
+        )
+
+    def _erase_owner(
+        self, db: object, context: OperationContext, name: str,
+    ) -> ErasureProofRecord:
+        owner = self._owners[name]
+        residue: tuple[str, ...] = ()
+        try:
+            proof = owner.erase(context)
+            erased = bool(proof.erased)
+            checksum = proof.checksum or ""
+            detail = {"phase": "erase", **dict(proof.detail)}
+            raw_residue = detail.get("residue")
+            if isinstance(raw_residue, list):
+                residue = tuple(str(x) for x in raw_residue)
+        except Exception as exc:  # noqa: BLE001
+            erased = False
+            checksum = ""
+            detail = {"phase": "erase", "error": _err(exc)}
+        try:
+            with db.raw_connection() as conn:
+                self._ledger.mark(
+                    conn,
+                    context.operation_id,
+                    name,
+                    ObligationKind.ERASE,
+                    ObligationState.ERASED if erased else ObligationState.FAILED,
+                    checksum=checksum or None,
+                    detail=detail,
+                    bump_attempts=True,
+                )
+        except Exception as exc:  # noqa: BLE001
+            logger.warning("erasure obligation mark skipped for %s: %s", name, _err(exc))
+        return ErasureProofRecord(
+            owner=name, erased=erased, checksum=checksum, residue=residue,
+        )
+
+    def _persist(
+        self,
+        db: object,
+        *,
+        erasure_id: str,
+        profile_id: str,
+        subject_type: str,
+        subject_id: str,
+        requested_by: str,
+        fact_count: int,
+        state: str,
+        all_erased: bool,
+        evidence_json: str,
+        audit_hash: str,
+        requested_at: float,
+        completed_at: float,
+        fact_ids: tuple[str, ...],
+    ) -> bool:
+        try:
+            with db.raw_connection() as conn:
+                if not _table_exists(conn, "erasure_receipts"):
+                    return False
+                version = _receipt_version_supported(conn)
+                if version >= _RECEIPT_V2:
+                    conn.execute(
+                        "INSERT INTO erasure_receipts "
+                        "(erasure_id, profile_id, subject_type, subject_id, "
+                        "requested_by, fact_count, state, all_erased, "
+                        "owner_evidence_json, audit_hash, receipt_version, "
+                        "requested_at, completed_at) "
+                        "VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?) "
+                        "ON CONFLICT(erasure_id) DO UPDATE SET "
+                        "state = excluded.state, "
+                        "all_erased = excluded.all_erased, "
+                        "owner_evidence_json = excluded.owner_evidence_json, "
+                        "audit_hash = excluded.audit_hash, "
+                        "receipt_version = excluded.receipt_version, "
+                        "requested_at = excluded.requested_at, "
+                        "completed_at = excluded.completed_at",
+                        (
+                            erasure_id, profile_id, subject_type, subject_id,
+                            requested_by, fact_count, state,
+                            1 if all_erased else 0, evidence_json, audit_hash,
+                            _RECEIPT_V2, requested_at, completed_at,
+                        ),
+                    )
+                else:
+                    conn.execute(
+                        "INSERT INTO erasure_receipts "
+                        "(erasure_id, profile_id, subject_type, subject_id, "
+                        "requested_by, fact_count, state, all_erased, "
+                        "owner_evidence_json, audit_hash, requested_at, completed_at) "
+                        "VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?) "
+                        "ON CONFLICT(erasure_id) DO UPDATE SET "
+                        "state = excluded.state, "
+                        "all_erased = excluded.all_erased, "
+                        "owner_evidence_json = excluded.owner_evidence_json, "
+                        "audit_hash = excluded.audit_hash, "
+                        "requested_at = excluded.requested_at, "
+                        "completed_at = excluded.completed_at",
+                        (
+                            erasure_id, profile_id, subject_type, subject_id,
+                            requested_by, fact_count, state,
+                            1 if all_erased else 0, evidence_json, audit_hash,
+                            requested_at, completed_at,
+                        ),
+                    )
+                conn.commit()
+            return True
+        except Exception as exc:  # noqa: BLE001
+            logger.warning("erasure receipt persist skipped: %s", _err(exc))
+            return False
+
+    def _emit_audit(
+        self,
+        *,
+        erasure_id: str,
+        profile_id: str,
+        subject_type: str,
+        subject_id: str,
+        requested_by: str,
+        state: str,
+        audit_hash: str,
+    ) -> None:
+        if self._audit_logger is None:
+            return
+        try:
+            self._audit_logger({
+                "erasure_id": erasure_id,
+                "profile_id": profile_id,
+                "subject_type": subject_type,
+                "subject_id": subject_id,
+                "requested_by": requested_by,
+                "state": state,
+                "audit_hash": audit_hash,
+            })
+        except Exception as exc:  # noqa: BLE001
+            logger.warning("erasure audit-chain emit skipped: %s", _err(exc))
+
+
+def fetch_receipt(
+    conn: object, erasure_id: str, *, profile_id: str | None = None,
+) -> ErasureReceipt | None:
+    predicate = "erasure_id = ?"
+    params: list[object] = [erasure_id]
+    if profile_id is not None:
+        predicate += " AND profile_id = ?"
+        params.append(profile_id)
+    row = conn.execute(
+        "SELECT erasure_id, profile_id, subject_type, subject_id, requested_by, "
+        "fact_count, state, all_erased, owner_evidence_json, audit_hash, "
+        f"requested_at, completed_at FROM erasure_receipts WHERE {predicate}",
+        tuple(params),
+    ).fetchone()
+    if row is None:
+        return None
+    return ErasureReceipt(
+        erasure_id=row[0],
+        profile_id=row[1],
+        subject_type=row[2],
+        subject_id=row[3],
+        requested_by=row[4],
+        fact_count=int(row[5]),
+        state=row[6],
+        all_erased=bool(row[7]),
+        proofs=_proofs_from_json(row[8]),
+        audit_hash=row[9],
+        requested_at=float(row[10]),
+        completed_at=float(row[11]),
+        persisted=True,
+    )
+
+
+def verify_receipt(
+    conn: object, erasure_id: str, *, profile_id: str | None = None,
+) -> bool:
+    """Verify the audit_hash of an erasure receipt.
+
+    Uses HMAC (v2) when the ``receipt_version`` column is present and
+    the row has version >= 2, otherwise falls back to unkeyed SHA-256 (v1).
+    """
+    predicate = "erasure_id = ?"
+    params: list[object] = [erasure_id]
+    if profile_id is not None:
+        predicate += " AND profile_id = ?"
+        params.append(profile_id)
+
+    db_version = _receipt_version_supported(conn)
+    row_version = _receipt_row_version(conn, erasure_id)
+
+    row = conn.execute(
+        "SELECT erasure_id, profile_id, subject_type, subject_id, requested_by, "
+        "fact_count, state, all_erased, owner_evidence_json, audit_hash, "
+        f"requested_at, completed_at FROM erasure_receipts WHERE {predicate}",
+        tuple(params),
+    ).fetchone()
+    if row is None:
+        return False
+
+    kwargs = dict(
+        erasure_id=row[0],
+        profile_id=row[1],
+        subject_type=row[2],
+        subject_id=row[3],
+        requested_by=row[4],
+        fact_count=int(row[5]),
+        state=row[6],
+        all_erased=bool(row[7]),
+        evidence_json=row[8],
+        requested_at=float(row[10]),
+        completed_at=float(row[11]),
+    )
+
+    if db_version >= _RECEIPT_V2:
+        # On M037-capable DBs NEVER accept the unkeyed v1 SHA path — a
+        # version-downgrade forgery rewrites receipt_version=1 with a valid
+        # SHA of mutated content.  Any v1 row here is rejected; legitimate
+        # old rows should be re-sealed before use.
+        if row_version < _RECEIPT_V2:
+            return False
+        from superlocalmemory.core.transactions.manifest_key import (
+            derive_receipt_hmac_key,
+            verify_hmac,
+        )
+        canonical = _erasure_canonical(**kwargs, receipt_version=_RECEIPT_V2)
+        return verify_hmac(row[9], derive_receipt_hmac_key(), canonical)
+
+    # v1 path (M037 absent) — use constant-time comparison to prevent
+    # timing oracles on old SHA256 hex digests.
+    recomputed = compute_erasure_hash(**kwargs)
+    stored = row[9] or ""
+    return _hmac_mod.compare_digest(
+        recomputed.encode("utf-8"), stored.encode("utf-8")
+    )
+
+
+# Tombstone write outcomes. WRITTEN/ABSENT are non-failures (ABSENT = the
+# table does not exist on an older schema, or there were no fact ids);
+# CONFLICT and ERROR must fail the erasure closed on a modern store.
+TOMBSTONE_WRITTEN = "written"
+TOMBSTONE_ABSENT = "absent"
+TOMBSTONE_CONFLICT = "conflict"
+TOMBSTONE_ERROR = "error"
+
+
+def write_tombstones_status(
+    db: object,
+    profile_id: str,
+    fact_ids: tuple[str, ...],
+    erasure_id: str,
+    created_at: float,
+    memory_id: str | None = None,
+) -> str:
+    """Write projection tombstones and report a precise outcome code.
+
+    Returns one of TOMBSTONE_WRITTEN / TOMBSTONE_ABSENT / TOMBSTONE_CONFLICT /
+    TOMBSTONE_ERROR so callers can fail an erasure closed on a real failure
+    while still tolerating an older schema without the tombstone table.
+    """
+    if not fact_ids:
+        return TOMBSTONE_ABSENT
+    try:
+        with db.raw_connection() as conn:
+            if not _table_exists(conn, "projection_tombstones"):
+                return TOMBSTONE_ABSENT
+            for fact_id in fact_ids:
+                conn.execute(
+                    "INSERT INTO projection_tombstones "
+                    "(profile_id, fact_id, erasure_id, memory_id, created_at) "
+                    "VALUES (?, ?, ?, ?, ?) "
+                    "ON CONFLICT(profile_id, fact_id) DO UPDATE SET "
+                    "memory_id = COALESCE(projection_tombstones.memory_id, excluded.memory_id)",
+                    (profile_id, fact_id, erasure_id, memory_id, created_at),
+                )
+                stored = conn.execute(
+                    "SELECT memory_id FROM projection_tombstones "
+                    "WHERE profile_id = ? AND fact_id = ?",
+                    (profile_id, fact_id),
+                ).fetchone()
+                if (
+                    stored is not None
+                    and memory_id is not None
+                    and stored[0] is not None
+                    and stored[0] != memory_id
+                ):
+                    logger.error(
+                        "tombstone provenance conflict for %s: stored=%r != passed=%r; "
+                        "failing closed",
+                        fact_id[:16], stored[0], memory_id,
+                    )
+                    try:
+                        conn.rollback()
+                    except Exception:  # noqa: BLE001
+                        pass
+                    return TOMBSTONE_CONFLICT
+            conn.commit()
+        return TOMBSTONE_WRITTEN
+    except Exception as exc:  # noqa: BLE001
+        logger.warning("erasure tombstone write skipped: %s", _err(exc))
+        return TOMBSTONE_ERROR
+
+
+def write_tombstones(
+    db: object,
+    profile_id: str,
+    fact_ids: tuple[str, ...],
+    erasure_id: str,
+    created_at: float,
+    memory_id: str | None = None,
+) -> bool:
+    """Backward-compatible boolean wrapper: True only on a clean write."""
+    return (
+        write_tombstones_status(
+            db, profile_id, fact_ids, erasure_id, created_at, memory_id
+        )
+        == TOMBSTONE_WRITTEN
+    )
+
+
+def is_tombstoned(conn: object, profile_id: str, fact_id: str) -> bool:
+    row = conn.execute(
+        "SELECT 1 FROM projection_tombstones WHERE profile_id = ? AND fact_id = ?",
+        (profile_id, fact_id),
+    ).fetchone()
+    return row is not None
+
+
+def tombstone_memory_id(db: object, profile_id: str, fact_id: str) -> str | None:
+    try:
+        with db.raw_connection() as conn:
+            if not _table_exists(conn, "projection_tombstones"):
+                return None
+            row = conn.execute(
+                "SELECT memory_id FROM projection_tombstones "
+                "WHERE profile_id = ? AND fact_id = ?",
+                (profile_id, fact_id),
+            ).fetchone()
+            return row[0] if row and row[0] else None
+    except Exception:  # noqa: BLE001
+        return None
+
+
+def _proofs_from_json(payload: str) -> tuple[ErasureProofRecord, ...]:
+    try:
+        parsed = json.loads(payload)
+    except (TypeError, json.JSONDecodeError):
+        return ()
+    entries = parsed.get("proofs") if isinstance(parsed, dict) else None
+    if not isinstance(entries, list):
+        return ()
+    records: list[ErasureProofRecord] = []
+    for entry in entries:
+        if not isinstance(entry, dict):
+            continue
+        raw_residue = entry.get("residue")
+        residue = (
+            tuple(str(x) for x in raw_residue)
+            if isinstance(raw_residue, list) else ()
+        )
+        try:
+            records.append(ErasureProofRecord(
+                owner=str(entry["owner"]),
+                erased=bool(entry["erased"]),
+                checksum=str(entry["checksum"]),
+                residue=residue,
+            ))
+        except KeyError:
+            continue
+    return tuple(records)
+
+
+def _table_exists(conn: object, name: str) -> bool:
+    return conn.execute(
+        "SELECT 1 FROM sqlite_master WHERE type='table' AND name=?",
+        (name,),
+    ).fetchone() is not None
+
+
+def _receipt_version_supported(conn: object) -> int:
+    """Return the highest receipt version this DB supports."""
+    try:
+        cols = {row[1] for row in conn.execute("PRAGMA table_info(erasure_receipts)").fetchall()}
+        return _RECEIPT_V2 if "receipt_version" in cols else _RECEIPT_V1
+    except Exception:  # noqa: BLE001
+        # Fail-closed: PRAGMA failure must not silently route verification through
+        # the unkeyed-SHA v1 path — same downgrade-forgery risk as manifest probe.
+        return _RECEIPT_V2
+
+
+def _receipt_version_from_db(db: object) -> int:
+    """Return the highest receipt version supported by the DB wrapper."""
+    try:
+        with db.raw_connection() as conn:
+            return _receipt_version_supported(conn)
+    except Exception:  # noqa: BLE001
+        return _RECEIPT_V1
+
+
+def _receipt_row_version(conn: object, erasure_id: str) -> int:
+    """Read the receipt_version for an existing row; fall back to V1."""
+    try:
+        cols = {row[1] for row in conn.execute("PRAGMA table_info(erasure_receipts)").fetchall()}
+        if "receipt_version" not in cols:
+            return _RECEIPT_V1
+        row = conn.execute(
+            "SELECT receipt_version FROM erasure_receipts WHERE erasure_id = ?",
+            (erasure_id,),
+        ).fetchone()
+        return int(row[0]) if row and row[0] is not None else _RECEIPT_V1
+    except Exception:  # noqa: BLE001
+        return _RECEIPT_V1
+
+
+def _err(exc: BaseException) -> str:
+    return f"{type(exc).__name__}: {exc}"[:500]
+
+
+__all__ = [
+    "ErasureProofRecord",
+    "ErasureReceipt",
+    "ErasureService",
+    "ErasureState",
+    "RemoveResult",
+    "MAX_ERASE_ATTEMPTS",
+    "VALID_SUBJECT_TYPES",
+    "compute_erasure_hash",
+    "compute_erasure_hmac",
+    "fetch_receipt",
+    "is_tombstoned",
+    "tombstone_memory_id",
+    "verify_receipt",
+    "write_tombstones",
+]