# ADR 022: The trash never expires; history is the audit log; "restore this version" is a walk of undos

> item 10a's asset GC).

Source: https://nooklet.danielalder.cz/decisions/022-trash-history-retention

Date: 2026-09-12. Status: accepted. Implements research/13 §4.2 item 8 (and the retention half of
item 10a's asset GC).

## Context

Every write is already an op in the log, every deletion is already a tombstone (`deleted_at`,
ADR 003), and every write already records a full before/after image per entity in `changes`
(ADR 013). So "trash" and "page history" were, in the data, already there — what was missing was
a way to read them and a way to act on them, and an honest statement of what they promise.

Three of the v1 tool descriptions promised deletions were "restorable for 30 days". Nothing
implemented that: `nooklet gc` (M6) trims the `op` table and never touches a `page`/`block` row,
so tombstones were kept forever and nothing listed them. The review of 2026-09-12 struck the
wording (B-56). This ADR decides what the promise actually is.

## Decisions

### 1. Retention: none. The trash is kept indefinitely.

`page`/`block` rows with a tombstone are never hard-deleted. `trash.list` shows all of them;
`trash.restore` brings any of them back. The asset GC (below) treats a reference from a
tombstoned block as a live reference for the same reason.

**Rejected: purge tombstones after N days.** It costs more than it saves, in four places:

- `nooklet verify` replays the op log and diffs it against live state (ADR 003's core guarantee).
  A purged row reappears on replay, so every purge is a permanent, growing "expected divergence"
  — unless the purge is gated behind the op-log GC floor, at which point it is a second GC with
  its own floor logic for a table that is a rounding error in size (tens of KB of tombstones next
  to an 85 MB vector table, sql-schema.md rule 28).
- A device that was offline through the purge can still push a `block.text` for the purged block.
  Core's `applyOps` treats a missing row as "no such block" (noop), so the edit is silently lost,
  and a `block.place` of a live child under a purged parent is a rejected move. Both are new
  failure modes for a feature whose whole point is trust.
- `((block-ref))` targets, `changes.entity_id`, `path_ref` and the FTS shadow tables all key on
  the id. A purge is a cascade, and each table has its own trigger semantics.
- The saving is disk that nobody will miss.

**Not done, recorded:** a "purge now" button on the trash view, gated behind the GC floor, is the
shape a future purge would take if someone actually wants one. Nothing in this design prevents it.

### 2. What one trash entry is, and what a restore brings back

The grouping key is the **tombstone instant**. Every deleter stamps one `now` across the whole
action — the editor's `deleteSelectedBlocks`, the API's `block.delete` (the subtree) and
`page.delete` (the page and its blocks). So:

- A **page** entry is a tombstoned page. Restoring it un-deletes the page and every block on it
  whose `deleted_at` equals the page's; blocks that were never tombstoned (hidden only because
  the page was) simply reappear. A block deleted separately, earlier, keeps its own tombstone —
  it is not offered while its page is in the trash (it could not be restored on its own), and it
  becomes its own entry once the page is back.
- A **block** entry is a tombstoned block on a live page whose parent is live or was tombstoned
  at a different instant — the root of a delete action. Restoring it un-deletes the descendants
  that share its instant, plus any tombstoned ancestor, so the block is actually visible rather
  than live-but-hidden. Only the ancestor chain is revived, not the ancestors' other deleted
  children; those stay as their own entries.
- A page whose name has since been taken by a live page is refused with `conflict` unless
  `new_name` is given. Core's `applyPageDelete(null)` does not re-check the live-name unique
  index (B-90), so without the guard the write would fail on a SQL constraint mid-transaction.

**Known limitation:** two separate delete actions in the same millisecond share an instant and
merge into one entry; restoring one restores both. Real actions are never that close; in-process
tests space theirs out.

**Rejected: the deleting batch as the grouping key.** More precise on paper, but a sync push is
one batch per HTTP request (200 ops), so a large subtree delete from a device spans batches and
would split into several entries; the timestamp does not.

**Rejected: a raw `UPDATE … SET deleted_at = NULL`.** It would be one line and wrong twice, for
the reasons ADR 018 gives for its migration: other devices never hear of it, and `verify` flags
it. The restore mints `page.delete`/`block.delete {deletedAt: null}` ops through
`serverApplyOps`, exactly as `batch.undo` does — so it replicates, it is audited, and it is
itself a batch that `batch.undo` can reverse.

### 3. History is the audit log, grouped by batch

`page.history` reads the `changes` rows for the page entity and for every block currently on the
page, grouped by `batch_id` (one batch = one write call, one sync push, one undo), newest first,
each with a summary in words and the per-entity before/after images the client diffs. A batch
whose ops were all LWW-stale or identical re-sends changed nothing visible and is hidden.

"This page's" rows are attributed by the block's *current* page: a block moved here brings its
earlier history along, one moved away takes it. Same choice as `changes.since`'s `page` filter;
the alternative (parsing every row's `place.pageId`) is a full scan for a distinction nobody
asked for.

### 4. "Restore this version" is `batch.undo` of every newer batch, newest first — from the client

The op log has no page snapshots to jump to. What it has is each batch's before-image, and
`batch.undo` already turns one batch into a complete, audited, LWW-winning compensating write.
Restoring the page as it was after batch K is therefore: undo every batch newer than K on this
page, newest first. The History view does exactly that after a confirm that says how many.

What this honestly is and is not:

- **Not atomic across batches.** If step 3 of 5 fails, the page is left after step 2, and the
  view says so. Each step is atomic on its own.
- **Not page-scoped.** A batch that also touched another page (a cross-page move, a `batch` op,
  a graph-wide replace) is undone there too. The confirm says so.
- **Recorded.** Each undo is its own batch, so the walk shows up in the timeline and can be
  undone in turn — there is no separate redo.

**Rejected: a server-side `page.restore_version` op.** It would call `batch.undo`'s logic in a
loop inside one savepoint, which buys all-or-nothing across the walk — but the cross-page
semantics are identical, the audit trail is identical (still one batch per undo), and it means
either re-implementing or re-exporting `batch.undo`'s compensation. Worth doing when someone
actually hits the partial-failure case; recorded here so the shape is known.

**Rejected: page snapshots.** A per-write full-page image would make "jump to version K" one
op, at the cost of storing every page's whole text on every keystroke batch. The per-entity
images already stored are the right granularity for a tool whose unit of change is the block.

### 5. Asset orphans and the trash

An asset is an orphan only when no block text or property value — **live or tombstoned** —
mentions `assets/<id>.<ext>`, and the upload is older than a grace period (7 days by default,
`--asset-grace`). The trash-only rule follows from decision 1: a page restored from the trash
must not come back with broken images. The grace period exists because the one legitimate
unreferenced window is between an upload and the block write that embeds it, which can sit in an
offline device's push queue for as long as a laptop stays closed; a week covers a holiday, and a
monthly `nooklet gc` still collects. A `changes` row for the asset newer than the cutoff extends
the grace, so a future "touched on deduplicated re-upload" audit row (B-91) needs no GC change.

**Amended 2026-09-13 (M7 server/sync review, F10): page history counts as a reference too.** An
asset mentioned in a page or block pre/post-image in `changes` is kept, reported as
`keptByHistoryOnly`. Decision 4 makes "restore this version" a walk of `batch.undo`, which
rewrites block text from `changes.before_json`; an image removed by an *edit* (nothing in the
trash) and collected a week later came back from a history restore as a broken image, recoverable
only by digging the file out of the pre-GC backup. The reasoning is decision 1's: the saving is
disk nobody will miss, the loss is a restore people trust.

What it costs, stated plainly: `changes` is never trimmed, so an asset any recorded write ever
embedded is never collected. The GC still collects uploads no write ever pointed at — an agent's
`asset_upload` that was never used, a paste whose block write never reached the server — which is
the window the grace period was built for; it no longer collects "a picture pasted and later
edited out of its block".

Rejected: *extend the grace from the last history mention* (an image edited out within the last 7
days is kept, older ones collected) — keeps GC useful for old edits, but a restore of a version
from last month still shows a broken image, the failure this amendment exists to remove.
*Document the limitation and keep collecting* — honest, and the smallest change, but it leaves a
first-class feature (History's restore) silently lossy. If disk ever matters, the shape of a real
answer is trimming history itself behind an explicit horizon, at which point the assets it alone
kept become collectable with no GC change.

## Consequences

- `docs/spec/mcp-tools.md` gains `trash.list`, `trash.restore`, `page.history` (rows 25–27); the
  earlier note that `trash.*` would be HTTP-only is superseded — an agent that deletes the wrong
  thing needs the trash as much as a person does.
- Tool descriptions say "the trash has no expiry", never a number of days.
- `/trash` and `/history/<name>` are routes; the history route is not nested under `/page/…`
  because that route is a splat and would read `/history` as part of the page name.
- The web client's `data/history.ts` carries its own copy of `store.ts`'s `stamped` invalidation
  idiom; `store.ts` keeps its signals private and is owned by another workstream this milestone.
- Open follow-ups, logged: B-90 (core should reject a colliding un-delete the way it rejects a
  colliding rename), B-91 (record a deduplicated re-upload so the asset GC sees it as recent).

## Amendment (2026-09-13): the walk keeps later edits (B-251)

Decision 4 said the walk is "not page-scoped" and left it there. Exploratory QA on the real graph
showed what that costs: restoring one journal day walked back through a graph-wide replace and its
undo, and `batch.undo`'s last-writer-wins before-images overwrote every later edit to the 835
blocks the replace had touched — a page merge's 19 link rewrites, a Turn-into-page link — with
nothing on screen saying so. The confirm's one sentence about other pages did not describe that.

`batch.undo` now takes `keep_later_edits` and `ignore_batches`. With the flag, a field another
batch changed after the one being undone is left as it is and reported in `kept`; the walk passes
its own batches and the undo batches it has written so far as `ignore_batches`, so its earlier
steps are not mistaken for later edits. The History view passes both for Undo and for Restore and
names the pages where something was kept. The walk is still not page-scoped — a replace is still
undone on the other pages it touched, where nothing has changed since — but it no longer
destroys work there.

**Default stays last-writer-wins** for the API and MCP (ADR 013's contract: an agent undoing its
own last write gets exactly the before-state). Whether agents should default to keeping later
edits too is left to the owner; the tool description now tells them when to pass the flag.

**Rejected: a whole-entity version check (`if_version`).** A later collapse toggle or an unrelated
property would then block restoring a block's text. The `changes` rows already carry each later
batch's before/after image, so the check is per field at no extra storage.

**Rejected: page-scoping the walk** (undo only this page's entities). It would leave a cross-page
batch half-undone — a merge's moved blocks back but its link rewrites not, a replace undone on one
page of the 300 it touched — which is a state no write ever produced.