blog · · engineering

A deterministic id is also an address in the trash

Typing into today's journal on the desktop did nothing, forever, with no error. The day had been deleted once, weeks earlier. Three correct decisions compose into that: delete is a move to the trash and the node keeps its id, a page root's id is derived from its slug so the slug still resolves to it, and Op::Create is idempotent, so reopening the day emitted a Create that found the node and left it exactly where it was. The page rendered, and ensure_live rejected every keystroke under it as NotInTree. Opening the same day once in the TUI fixed it by accident, because the TUI persists by rendering the .md and reconciling it, which emits Move(page, root()) with a fresh HLC. This is that accident done on purpose, the two revive paths that must not call each other, and why the only honest error the backend could return was one no client could act on.

A
11 min read

I typed four lines into today’s journal on the desktop, left the page, and came back to an empty day.

Opening the same date once in the terminal fixed it, permanently, on that day and on every later reopen of it. There is no repair command in the TUI and I had not run one. The only other fact I had was that this particular day had been deleted, weeks earlier, and reopened since.

three decisions meet here, and each one is right on its own

Invariant 6 of outl’s CLAUDE.md says delete is Move(node, TRASH_ROOT), never physical removal. The node keeps its record and its id, which is the whole reason the trash can be read back at all.

A page root’s id is derived from its slug, through page_id_from_slug. That is deliberate and I have written about why: two devices that create the same day’s journal offline land on one node instead of two competing roots, which is what stops the day splitting. It is also the decision that doubled the title of every journal opened on two devices when the title lived in the root’s text.

And Op::Create is idempotent. The comment sits right there in crates/outl-core/src/tree/op.rs:

Op::Create {
    node,
    parent,
    position,
} => {
    // Idempotent: if the node already exists, keep its current
    // parent/position. The Create only seeds initial placement.

Now compose them. page::open_or_create asks find_by_slug first, and find_by_slug scans children_of(workspace, NodeId::root()) for a node carrying that page-slug. A root in the trash is not a child of the workspace root, so the scan reports the page absent. The function falls through to minting it: page_id_from_slug returns the same id it has always returned, and Op::Create for that id finds the node already in the tree and keeps its current parent, which is TRASH_ROOT.

The page then opens, because the view is built from that node and its descendants, and a node under the trash has descendants like any other. Every write goes the other way. ensure_live in crates/outl-actions/src/block/mod.rs is two questions, not one:

fn ensure_live(workspace: &Workspace, node: NodeId) -> Result<(), ActionError> {
    ensure_in_tree(workspace, node)?;
    if crate::tree::is_trashed(workspace, node) {
        return Err(ActionError::NotInTree(node.to_string()));
    }
    Ok(())
}

So the day rendered, and every keystroke under it came back NotInTree. On the journal this repeats every morning, because today’s page is reopened every morning, and a page reopened on a schedule re-stamps its template under a subtree nobody can edit, once per open. That is issue #473.

the TUI recovered by accident, and the accident is the fix

The TUI does not persist a keystroke by writing an op for it. Its save path, in crates/outl-tui/src/runtime/event_loop.rs, is render → write → reconcile_md → fsync: it renders the page to .md, writes the file, and reconciles the file back into the tree.

Reconcile’s first job is making sure the page root exists where a page root belongs. ensure_page_root_in_tree in crates/outl-md/src/reconcile/page_root.rs has three cases, and the second one is the accident:

} else if let Some(old_parent) = current_parent.filter(|p| *p != NodeId::root()) {

Any parent that is not root() gets a Move back to root(), and the trash is such a parent. That branch was written for a page node that had somehow migrated under a block, and it has been quietly reviving trashed roots since long before anyone filed #473. It is also why outl serve’s watcher never reproduced the bug either.

So the fix is that accident, done on purpose, on the path every client takes. crates/outl-actions/src/page/revive.rs runs before the Create, never after, and it is cheap enough to sit on the page-open path because the ordinary answer costs two map reads:

let node = super::page_id_from_slug(slug);
if !workspace.tree().contains(node) {
    return Ok(None);
}
if !crate::tree::is_trashed(workspace, node) {
    return Ok(None);
}

is_trashed is an ancestor walk rather than parent == trash(), because a page root re-parented under another page that was later deleted is just as unreachable and just as broken from the user’s seat.

two paths revive a root, and neither may call the other

The sharpest thing I learned writing this is that the reconcile path and the open path disagree about the deleted blocks, and both are right.

ensure_page_root_in_tree moves only the root and leaves the children live. revive_if_trashed trashes each child first. That is not drift, because the inputs differ. Reconcile holds a file with content in it, and that file is evidence of the user’s intent the op log does not have, so it answers “make the tree match this”. The open path has no such file, because a GUI delete removed the .md, so it answers “the user wants to write here today”.

Routing one through the other is the thing to refuse in review. If reconcile called the revive, it would trash blocks whose text is in the .md it is reconciling against, and the parse immediately after would recreate them with fresh ids, breaking every ((blk-…)) handle aimed at them and rewriting the sidecar. Two implementations beat that, and because a doc sentence cannot fail, the asymmetry is pinned by the_md_reconcile_revives_a_page_root_too_and_keeps_its_children in crates/outl-actions/tests/revive_convergence.rs.

trash::restore is a third thing and refuses a page root outright, for reasons that do not transfer: restoring one needs a re-projected .md, and on my workspace 16 of 18 deleted pages have their slug taken by a live page today, so trash would have to pick a free slug and become a second owner of the slug rule. Neither condition holds on the open path, whose caller owns the slug rule and has already established the slug is free.

yesterday’s blocks stay in the trash, one op each

Reviving the root alone would bring every block the user deleted back live, so “I deleted this page” would mean “hidden until tomorrow morning”. Each direct child is moved to the trash in its own op, before the root leaves, so the page is never momentarily live holding deleted content, in the tree or in the op log a peer replays.

The cost is that one trash entry becomes N, deliberately. Hiding is not destroying: invariant 6 keeps every block in the log, each becomes an ordinary trash::list entry, and reviving_a_page_leaves_its_deleted_blocks_in_the_trash asserts the whole round trip, including that a restored block brings its subtree back under the revived page.

One child shape does not come back that way. A direct child that is itself a page root, reachable when one page was re-parented under another, is refused by trash::landing_for with TrashPageRestoreUnsupported. For those the recovery is not the trash at all: reopening that nested page by its own slug revives it through this same function, because a trashed root keeps its page-slug.

Two smaller things fell out of this. The revive is the first caller in the workspace to move a node to NodeId::root(), which caught two guards asking contains about a parent that never appears in Tree::nodes, pinned now by crates/outl-actions/tests/root_is_a_legal_parent.rs. And a revived page renders empty, so the next projection wants to write that over whatever is on disk. The revive is Op::Moves only and never advances last_synced_hash, so invariant 8’s guard is untouched by it, and crates/outl-actions/tests/revived_page_md.rs is what makes that a fact rather than a claim about code nobody re-read.

the only honest error was one no client could act on

The second half of the issue is what the backend should say when a keystroke arrives for a block that is no longer live. The honest answer is the error, and the error was worse than swallowing it.

edit_block in crates/outl-tauri-shared/src/commands/block.rs spells out why, and the reason is the shape of each client rather than a preference:

// Returning the error is not the answer, and the shape of each client
// says why: mobile's `commitEdit` keeps the editor open and pins a
// **Retry** button to the failure, so a dead id becomes a retry that
// can never succeed with the draft parked behind it; the desktop's
// `handleError` skips `applyView`, so the client also never drops the
// stale `editingId` it is failing against.

So the text is kept at the end of the page through create_after_or_append, the function that already owned that tolerance for create_block. That had its own hole: append_block has no parent guard, and create_with_explicit_id applies the Op::Create unconditionally before edit_text asks ensure_live. Appending under a trashed page therefore landed an empty block in the log under a parent nobody can see, discarded the text anyway, and returned the error it was written to avoid. One junk op per attempt, and a client that retries writes another. append_in_page in crates/outl-actions/src/block/siblings.rs refuses before the Create now, and a_trashed_page_keeps_the_log_clean asserts the op count does not move.

Keeping the text silently is a new silence rather than a fixed one, and this is the part I would rather state than let a user discover. The end of a journal day is below the fold, so “my text vanished from where I typed it” is the identical observation from the user’s seat, now with a block they did not ask for somewhere they are not looking. So the reply carries a DroppedEdit, with the wording in the two constructors rather than in either client: “That block is gone, so your text was kept as a new block at the end of this page”, or, when the page went too and nothing was written, “This page was deleted, so your text could not be saved.”

Here is what it actually cost. The field is on the wire, pinned, and mirrored in crates/outl-frontend-shared/src/api/types.ts, and neither client renders it yet. The two files that would, OutlineView.tsx and Journal.tsx, sit exactly at their size baseline and are each being split by separate work. So today the backend tells the truth into a reply nobody reads, which is better than lying and is not the same as telling the user. This is the same shape as a refreshed outline committing the pre-paste draft back over the paste: the mutation is fine, and the question is which surface is the authority on what the user sees next.

the id is not evidence, and the guard that says so is not the only branch

A trashed page root keeps its page-slug, because a Move touches nothing else. So the revive asks for it, through the same claims_slug predicate find_by_slug uses, and declines when the deterministic id names something that is not a page for this slug:

tracing::warn!(
    "page {node}: the deterministic id for slug {slug:?} is in the trash but does \
     not carry that slug, so it is not revived — writes to this page will be \
     dropped until it is repaired (`outl doctor`)"
);
return Ok(None);

Falling through to the idempotent Create there means the worst case is the state we already had, which is #473 again for that one page, with a log line to tell it apart.

Except the fall-through does not happen, and that is my own mistake rather than the issue’s. #473 was fixed twice. PR #501 landed page/revive.rs at 22:38 and PR #500 landed a second module, crates/outl-actions/src/page_revive.rs, at 22:54. The two call sites are adjacent lines in crates/outl-actions/src/page.rs rather than the same line, so git merged both cleanly and nothing failed to compile:

if let Some(id) = revive::revive_if_trashed(workspace, hlc, slug)? {
    return Ok(id);
}
let node_id = page_id_from_slug(slug);
if crate::tree::is_trashed(workspace, node_id) {
    return crate::page_revive::revive_trashed_page(workspace, hlc, node_id, slug, title, kind);
}

The second branch is dead for every case the first one handles. It is reachable in exactly one: the case the first one deliberately declines. A node that is trashed and does not claim the slug gets the warn! and then gets revived anyway, with its page-slug, page-kind and title overwritten to the slug being opened. outl page rename writes a new page-slug onto the same node without re-minting its id, so rename a page, delete it, and open its old name: the deleted page comes back out of the trash wearing the name you renamed it away from, with its content stripped into the trash one block at a time.

I have not seen it happen to anyone. It is still the exact failure the guard was written to prevent, reintroduced by a fix for the same issue sixteen minutes apart. The CHANGELOG entry is the other half of the tell: it says the revive re-applies the slug, kind and title properties, which is what page_revive.rs does and what page/revive.rs deliberately does not, with a comment saying they survived the Move and a second open must not rename a page that is already there.

This is the mirror of the duplicate Create that let an undo delete somebody else’s node. That post was about Create’s idempotency doing something nobody asked for. This one is about the same idempotency silently not doing something, and about a second fix for it that no test could notice, because both implementations pass the same assertions on the path that matters.

The lesson I would take out of it is that idempotency is a claim about an operation, not about the state it leaves behind. “The node already exists” and “the node is where you want it” are different questions, and a deterministic id answers the first one forever while saying nothing at all about the second. Every surface that asks only the first will be right until the day somebody deletes something.

The revive is in crates/outl-actions/src/page/revive.rs, the convergence suite beside it in tests/revive_convergence.rs, and the duplicate module is still in crates/outl-actions/src/lib.rs waiting to be deleted, in the outl repository.