# 0008 · Tombstone deletion with pending link decisions

**Status:** Accepted · 2026-09-22

## Context

Documents link to each other. Deleting one breaks inbound links belonging to other people, who may
not know the document existed and certainly did not agree to lose the reference.

## Decision

Deletion sets `deleted_at`. The document leaves search and listings; the row and its full revision
history survive. Inbound edges become `broken`, retaining `target_id`, and each linking document's
author is notified with a decision: **repoint**, **drop the link**, or **restore the target**.

Purge hard-deletes after a retention window, and only once no inbound edge is still pending.

## Consequences

- Deletion is reversible. Restore clears the tombstone, returns `broken` edges to `resolved`, and
  resolves the notifications.
- Retaining `target_id` on broken edges is what makes restore a one-step reversal rather than a
  re-resolution that might land elsewhere.
- The address is freed immediately — the unique index is partial on `deleted_at IS NULL` — so a new
  document can take the old address while the tombstone still exists.
- **Someone else's unresolved decision delays purge.** Correct: purging underneath them would leave
  "drop" as their only option and silently remove the choice to restore.
- Deleted content persists until purge. A deployment with hard deletion requirements tunes the
  retention window.

## Alternatives rejected

**Block deletion while inbound links exist.** Referential integrity is never violated and there is no
broken state to design around. Rejected because one unresponsive colleague blocks cleanup
indefinitely, and people route around blocked cleanup by deleting the links instead — losing the
graph to preserve the constraint.

**Hard delete immediately, notify after.** Simplest storage story and the strongest answer to a
deletion request. Rejected because it destroys the revision history this design exists to preserve,
and leaves no undo for a mistake that is easy to make.

**Cascade delete inbound links.** Silently edits other people's documents to hide a problem they
would want to know about.