[kryptobaseddev]

Problem (T13842, critical)

updateDocBySlug wrote the docs_attachments row (the bytes docs fetch / docs view read) from the incoming text and only then projected the edit through the section CRDT. After a stale-base merge the conduit head held both writers' edits but the row held only the last writer's input, so readers silently lost the concurrent edit even where the merge was correct (probe on main: an append merge reported staleBaseMerged: true, the head had both lines, fetchContent lacked A's).

Fix (docs-update.ts only; preview API from #2358)

Order, per review-2253 option (a):

1. Preview the merge with previewDocUpdateThroughSections (feat(T13842): read-only docs projection preview (previewDocUpdateThroughSections) #2358: the real projection inside its transaction, rolled back).
2. Row bytes = the preview's head text: mergedText when the write would advance the head; the current head version's text when it would lose the head race (explicit lower HLC).
3. wouldChange and the body-schema check run on those bytes (review LOW).
4. Write the blob and the row.
5. Commit the projection.

Failure handling: a failed preview writes the incoming bytes and leaves the head unchanged (W_DOC_PROJECTION_FAILED); a failed commit after the row write is reported with the head uid (W_DOC_PROJECTION_FAILED); a head that moved between preview and commit is reported (W_DOC_HEAD_DIVERGED). The noop check stays keyed on the incoming bytes. #2326's prior-version link is computed once and passed to preview and commit.

T13881: how the preview's rollback is kept from discarding other writes

The preview rolls back on the process-wide shared native handle, so a write another in-process writer lands on that handle during its awaits would be rolled back with it. Before the preview, docs-update.ts:

• settles every tracked background op (settleBackgroundOps, 5 s budget, non-consuming so the shutdown receipt keeps its ledger) — graph nodes, hook dispatches, manifest mirrors, and every other trackBackgroundOp producer. If one is still running after the budget, the preview is skipped (incoming bytes written, head unchanged, W_DOC_PROJECTION_FAILED), never run over it;
• runs the preview on the handle's writer queue (scheduleTaskBackground, the same queue every accessor transaction and committed background effect uses, and the sync apply frame's serialization point), so any accessor transaction or committed effect queued during the preview starts only after its rollback.

Not covered: an in-process writer that bypasses both the accessor queue and the background registry (a raw getDb() write from concurrent code in a long-lived host). The CLI runs one command per process, so only tracked ops run beside it there. A dedicated connection or savepoint for the preview (T13881 AC option 1) would close that, in section-write-path.ts, and stays with T13881.

Tests (docs-update-concurrency.test.ts)

• stale-base append: fetched body carries both writers' lines and equals the head;
• lost head race: fetched body equals the head (a thin vi.mock passthrough feeds an explicit HLC into the real preview/projection);
• a blob write failing after the merge returns E_FILE_ERROR with head and history untouched;
• a failed preview keeps the incoming bytes, head unchanged;
• a failed commit keeps the merged row and the old head.

Verified locally before the owner's no-local-heavy-runs directive: the first two fail on main, the last three fail on the previous ordering, all pass with the fix (concurrency + version-link 15/15; section-write-path, docversion, status-only, derive-links 45/45; tsc -b exit 0). The T13881 guard commit (1ec71e4) is verified by CI only, per the directive. Static checks on the final head: biome, gates 28/32/38 (--base origin/main), changeset lint.

#2335 (pre-merge heading refusal) was closed in favour of #2325's planner property plus this fix.

🤖 Generated with Claude Code