CoDNA Request access
Contents

Docs Decisions

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.