NEC-272: P5 · Replay a note's disk edit against its exact base as CRDT operations #345

Merged
nectenda-agent merged 9 commits from worktree-nec-272-replay-a-notes-disk-edit-against-its-exa into main 2026-11-08 21:36:57 +00:00
Collaborator

Task: NEC-272 — https://projectron.nerchure.com/tasks/283

A note's file change (another program, an edit made while sync was stopped, a save from an unbound editor) is now replayed as whole-line CRDT operations on a copy of the document rebuilt at the exact snapshot the file was built on, and merged into the live document as a collaborator's edit would be (SAFE-A54). That replaces line matching and its keep-both rules for every read-in with an exact base; where none is held, or the rebuilt copy does not read as the base, the old line merge runs and the diagnostic log says so. To rebuild the base, each note keeps the content of deleted text only while a ledger snapshot needs it, through a gcFilter history window released as the snapshots move on (SAFE-A55); let-go entries now carry their snapshot (SAFE-A35). The nearness rule proposed in the plan was removed after review: it deleted a collaborator's lines everywhere when the file repeated part of their edit, so a replay is always from the base. Two Markdown hardness seeds passed on the final code; mobile memory of the window is a manual-testing entry, not yet run.

🤖 Generated with Claude Code

https://claude.ai/code/session_01EV8ztaiamSggtFCLfVKakB

Spec: docs/changes/NEC-272-exact-base-replay/spec.md

Changelog

A note changed on disk while this vault was not syncing, or by another program, is now merged exactly as a collaborator's edit would be, instead of by matching lines and keeping both versions.

Task: NEC-272 — https://projectron.nerchure.com/tasks/283 A note's file change (another program, an edit made while sync was stopped, a save from an unbound editor) is now replayed as whole-line CRDT operations on a copy of the document rebuilt at the exact snapshot the file was built on, and merged into the live document as a collaborator's edit would be (SAFE-A54). That replaces line matching and its keep-both rules for every read-in with an exact base; where none is held, or the rebuilt copy does not read as the base, the old line merge runs and the diagnostic log says so. To rebuild the base, each note keeps the content of deleted text only while a ledger snapshot needs it, through a gcFilter history window released as the snapshots move on (SAFE-A55); let-go entries now carry their snapshot (SAFE-A35). The nearness rule proposed in the plan was removed after review: it deleted a collaborator's lines everywhere when the file repeated part of their edit, so a replay is always from the base. Two Markdown hardness seeds passed on the final code; mobile memory of the window is a manual-testing entry, not yet run. 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_01EV8ztaiamSggtFCLfVKakB Spec: `docs/changes/NEC-272-exact-base-replay/spec.md` ## Changelog A note changed on disk while this vault was not syncing, or by another program, is now merged exactly as a collaborator's edit would be, instead of by matching lines and keeping both versions.
A note's file change was merged by a line diff from its base, placed onto the
current text by matching lines, with a rule for each way two sides' changes
meet and both versions of a line kept where none decided. Here the same
whole-line diff is applied on a copy of the document rebuilt at the base's
snapshot, where its positions are exact, and the result merged into the live
document as a collaborator's edit: Yjs decides, as it does for two editors.

The copy needs the content of text deleted since the base, which Yjs collects
on deletion. A history window per document keeps only what a snapshot the
ledger still holds was taken with, and releases it when the snapshots move on.

Task: NEC-272

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EV8ztaiamSggtFCLfVKakB
Every read-in of a note's file — the connect's first write, a modify event,
the reconcile before a bind, a change met while bound — plans the change
against the exact state the ledger holds for its base and applies it as a
collaborator's edit, falling back to the line merge where none is held or
it does not rebuild. The copy under SAFE-A30 is decided on the replay's own
predicted result. A let-go text now carries the document's snapshot, exact
when the editor showed the document's text, so an edit made while not
syncing is replayed too.

Collection stays off while the last session's updates load, since the ledger
that names the snapshots is read after them; it is turned on and swept once
it is. The identity a replay is made under is recorded as this vault's own.

Task: NEC-272

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EV8ztaiamSggtFCLfVKakB
SAFE-A54 names the replay and its fallback, SAFE-A55 what deleted content a
document keeps and for how long, and SAFE-A35 the snapshot a let-go text now
carries. The sync-limitations entry for a note edited while sync was stopped
says what the merge does now and where the line merge still runs; a new
deliberate-trade entry records the window's cost as measured by the bench
(about a kilobyte per fifty unagreed edits, within half a percent of default
collection once released). The e2e case types into a paragraph in one vault
while another program rewrites its last word in the other, the case the line
merge kept in two versions. The phone measurement is a manual-testing entry.

Task: NEC-272

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EV8ztaiamSggtFCLfVKakB
Task: NEC-272

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EV8ztaiamSggtFCLfVKakB
The callback runs in the renderer, where the test's constant is not defined.

Task: NEC-272

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EV8ztaiamSggtFCLfVKakB
Review found that taking a file nearer the current text than the base, by
lines, for one built on the current text — and applying it against that —
deleted the collaborator's lines everywhere whenever the file's edit
repeated part of theirs (both deleted the same two lines, or both added the
same property block). The copy was of the file, which never held them.
mergeEdits had dropped the same rule after its randomised seed 46. The file
is always replayed from its base now; the once-only rule covers a save that
did load the collaborator's change, doubling a line at worst.

Also from the review: a let-go text noted again with an exact snapshot where
it had one that was not takes the exact one; own-client writes are
serialised and the in-memory set updated at once; the randomised replay test
runs over 24 seeds; a cross-session test covers the let-go path; SAFE-A54
and the spec say so.

Task: NEC-272

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EV8ztaiamSggtFCLfVKakB
Task: NEC-272

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EV8ztaiamSggtFCLfVKakB
A passing run keeps no logs, so it says at the end how many file changes
each vault replayed on the document as it was, and how many it merged line
by line, with the reason (NEC-272).

Task: NEC-272

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EV8ztaiamSggtFCLfVKakB
Record the two Markdown hardness seeds and what their replay count says
All checks were successful
Release note / release-note (pull_request) Successful in 17s
CI / build (pull_request) Successful in 3m55s
CI / e2e (pull_request) Successful in 16m15s
CI / promote (pull_request) Has been skipped
CI / build (push) Successful in 4m7s
CI / e2e (push) Successful in 16m16s
CI / promote (push) Successful in 31s
acbe0988e7
Task: NEC-272

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EV8ztaiamSggtFCLfVKakB
Sign in to join this conversation.
No reviewers
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
Nectenda/nectenda!345
No description provided.