[imnasnainaec]

Part of #426; closes #449.

Summary

The host re-anchors every book the session's draft links into, in the session's turn, as the whole-text read delivers each book and again when a book's text changes.

openSession
  startTextRead                       # a fresh read; closing the session ends it
BookService
  onBookRead(book)         -> session turn: re-anchor the book, record the pass
  onTextRead(textBookIds)  -> session turn: stale the links into books the text lacks
  onBookTextChanged        -> after the session's turn: emit onAnalysisChanged
undo / redo
  re-anchor what the step restores to each book passed over since, in memory
  apply the step and its re-anchor as one

• The pass reads one book through Add derived indexes with a rebuild-and-diff command #487's lookups (getScope, findLinksInBooks, getSegmentAnalyses), runs the WebView's own reanchorDraftToBook over it, and applies the links it rewrote, with the scope's record when it moved a split.
• Undo. A pass is no undo step. EditHistory records each pass while a step predates it, and an undo or redo re-anchors what it restores to the latest text of each book passed over since, as recordBookPass does on main.
• Open book. An edit to the open book that the read has yet to reach waits for the book's new text, hands it to onBookRead, then is reported, so its pass runs before the refetch.
• Read-only sessions aren't re-anchored, as main leaves the import view alone.

Evidence

• Parity with the WebView passes. Every case of reanchor-analysis.test.ts (88) and reanchor-draft.test.ts (7) now also checks that the host's change set brings the draft to the WebView pass's result, and that the pass over the book's links alone, as the host reads them, makes the same changes. Five fixtures that gave two links one id now give each its own, as the host's records need.

• The Data layer: capture a performance baseline before the database migration #407 tiers. perf:bench re-anchors every book of each tier both ways, ignoring the time each pass stamps:

  tier	books	changed by WebView	by host	disagreeing	host, all books
  small	82	1	1	0	0.8 s
  medium	82	1	1	0	1.8 s
  large-loadable	82	67	67	0	3.4 s
  large	82	72	72	0	4.5 s

  One run each, on a development machine. The changed books hold the tiers' cross-verse phrases, which the pass stales on both paths.

• Undo and redo. An edit, then a Scripture edit and its pass, then an undo restores the earlier link on the word's new ref; a redo restores the later one there too.

• A mid-session Scripture edit. BookService hands the edited book to onBookRead before reporting the edit, the pass runs in the session's turn, and onAnalysisChanged waits for that turn.

• npm run test:coverage passes at 100%; npm run lint and tsc are clean.

Decisions with a strong alternative

1. Every book is read at session open. The 2e checkpoint measured about 1.4 s and +38 MB of host heap. Alternative: read on demand, as main does.
2. Session open starts the read and close ends it, here rather than in 4a. Open doesn't wait for the book list; a failure to list it shows up where getTextReadStatus reports it. Each session gets a fresh read, so one opened after an earlier read still hears of every book.
3. No onAnalysisChanged after a pass on a book's first arrival. Until 3k the event only names a Scripture edit; 3k's touched ranges can cover passes.
4. An undo or redo and its re-anchor are one apply, so a failure applies nothing and the step stays. Alternative: apply the step, then re-anchor, and leave stale anchors when the second fails.
5. The open book's edit waits for its new text before it's reported. The view's refetch already waited for that tokenizing, so no view waits longer.
6. getScope is copied from [3d] Add token commands with parity tests #443 rather than stacking on it. Whichever lands second takes the other's version.
7. Books the text lacks are looked for among the canon's book codes, as presentBookIds lists books present.

Follow-up

• Scope apply's draft write to the books an edit reaches #505: at a large tier's first session open, 67 to 72 books change, each an apply on the session's queue.
• 3k ([3k] Add analysis to segment pages #450): onAnalysisChanged should name a pass's touched ranges, as a command's.
• 4c ([4c] Delete the WebView write path #455): deleting the WebView's re-anchor passes must keep reanchorDraftToBook, which the host's pass calls.
• The pass relies on a one-book lookup returning links in stored order, as Add derived indexes with a rebuild-and-diff command #487 keeps it, for its tie-breaks to match main's. The seam doesn't promise that order.

Merge Danger

Door: two-way

No released build opens a session, so no pass runs. Released builds see one change: since they never start the whole-text read, each edit to the open book is reported once the book's new text is tokenized instead of at once.

Blast Radius: BookService's edit reporting

🤖 Generated with Claude Code

---

This change is 

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}