docs(adr): ADR-092 — one write path for a KB node

[cuttlefisch]

Design record for the KB write-path work. No behavior change — this is the ADR, the regenerated ADR KB, and the CLAUDE.md index entry. Implementation follows in phases, each with a test that fails first.

What prompted it

A node created by kb_create, (kb-create), or received over CRDT has no human edit surface. help_edit_source (help_ops.rs:1355) resolves kb_node_source_file and otherwise reports "No source file for '{id}'". On a hosted KB the client holds no files, so that's the ordinary case.

Designing the fix showed the missing surface is the smaller half.

Five write paths, one correct

Path	CRDT op	Evidence
kb_update_node_with (MCP kb_update, Scheme, commands)	yes	kb_ops/nodes.rs:499
buffer :w → kb_reimport_file	no	file_ops.rs:319-336
org-dir watcher drain	no	same shape
kb_widen_meta	no	kb_ops/dispatch.rs:322-347
meta-body recompose	no	kb_ops/dispatch.rs:344

Two are live data-loss paths: on a host that shared a file-backed KB, editing the .org and pressing :w never broadcasts and clobbers peer edits; and kb_widen_meta matches only self.kb.primary.get_mut(...) with no else (dispatch.rs:325), then reports success (:369) — an edit to a federated-instance member is discarded while the user is told it saved.

The CRDT bug underneath

set_body/set_title (shared/sync/src/kb/node.rs:190/:165) do remove_range(0,len) + insert(0,new) on a YText. Two peers editing the same body from a shared base converge, lose neither edit, and duplicate the entire untouched base — verified empirically:

Line one.     ← shared base
Line two.
From A.
Line one.     ← shared base, DUPLICATED
Line two.
From B.

No test caught it. three_client_concurrent_edits_converge (node_tests.rs:248) has peers edit different fields — its own comment says so — and the one same-field test, two_clients_merge_body (:71), asserts only a.body() == b.body(). That oracle is worthless here: CRDT gives convergence for free. The meaningful oracle is that the base appears exactly once.

The fix already exists in-tree: TextSync::reconcile_to (text.rs:533), whose UTF-16 offsets already match. KB nodes never got it.

Decisions

1. kb_update_node_with is the sole node-content mutator; every other path routes through it.
2. CRDT text mutation is incremental, never wholesale — one shared diff core for the buffer layer and KbNodeDoc.
3. The human edit surface is the node's normalized org source text — not its rendered view, not necessarily a file.
4. Editable scope is bounded by what syncs. KbNodeDoc carries only id/title/body/tags/links/meta, so the properties drawer stays out until front matter is folded into the body CRDT. Offering a field that silently never reaches peers is worse than the current dead end — it looks like it worked.
5. Surface selection is configurable and the default reproduces today's behavior byte-identically.

Alternatives rejected (with reasons recorded)

• Writable rendered buffer — the render pipeline is lossy twice over (strip_kb_body_noise drops drawers/#+ keywords; render_kb_body rewrites [[T][D]] to bare display text), and the surviving link spans are static offsets invalidated by the first keystroke.
• File as the edit surface — serves none of the three target clients: a browser can't reach the notes dir, an external editor has no guarantee it's in the workspace, a hosted participant has no files at all.
• node_to_org ∘ parse_org as the pair — parse_org (org.rs:75) returns the whole file as the body and hardcodes NodeKind::Note, dropping kind/aliases; todo_state/priority are emitted but never parsed back. A save cycle doubles the front matter.
• Name-encoded node identity — the kb-narrow precedent (dispatch.rs:296) splits at the first colon, so it's wrong for every namespaced id.

Out of scope

Wiring the projector (daemon/src/projector.rs — Projector::new and set_change_feed still have zero non-test callers; ProjectionStores has no production impl) is ADR-029's read side and stays tracked separately. This ADR is its write side.

Verification

• make adr-kb — 92 ADRs parsed, corpus validated (no dangling references, no Extends cycles)
• make pre-commit — fmt + clippy on both workspaces, code-map, heavy-e2e, and the ADR-059 Phase E staleness gate confirming assets/mae-adr.cozo.sha256 moved in the same range

Also syncs both Cargo.lock files 0.14.89 → 0.14.92 (issue #61 fallout — the version-bump workflow doesn't update them).

🤖 Generated with Claude Code