[jasonleenaylor]

Closes #433. Part of Phase 1 (#424) of the data layer plan, step 1d.

Summary

Save and Save As no longer send the analysis over the bus. The WebView settles its draft writes, then one host command copies the stored draft into the interlinear project and replies with the project's summary. saveAnalysis is removed.

WebView: useDraftProject.commitDraft(copy)
  writer.settle()                     # send any scheduled write, wait for every write in flight,
                                      # send a write that failed once more
  draft replaced meanwhile?  -> false, nothing saved
  copy(snapshot)                      # Save:        saveDraftToProject(source, id)
                                      # Overwrite:   saveDraftToProject(source, id, { analysisLanguages, targetProjectId })
                                      # Save As new: saveDraftAsProject(source, languages, target, name, description)
  copy landed whole?  -> mark synced unless an edit landed during the copy
  copy left books out -> draft stays unsaved

Host: saveDraftToProject / saveDraftAsProject
  exportForCopy(source)               # names books whose stored analysis cannot be read
  any unreadable?  Save -> refuse, project untouched; Save As new -> leave them out
  updateAnalysis(...) / persistNewProject(...)
  markClean(source)                   # envelope only, skipped if a book was left out
                                      # or a draft write followed the read
  -> Save: project summary JSON, or undefined when the project is gone
     Save As new: { project, omittedBooks } JSON

Save As to a new project creates and fills the project in one call, so a failure leaves no empty project behind, and reports its failure as a failed project creation. A Save whose project no longer exists says so.

While a save runs, the toolbar shows "Saving…", and New, Open, Save, Save As and Wipe send an info notification and do nothing, so the draft the copy reads is the one the user chose to save.

src/utils/debounced-writer.ts owns the autosave timer, the latest write and its failure. Its write must land writes in the order they are sent, which the host's per-source draft queue does.

Unreadable draft books

A draft book whose stored analysis cannot be read (a torn write or outside damage) is kept as stored and never written over:

draft loads                           -> user warned which books
draft write carrying analysis for it  -> rest saved, that book left out; user told once,
                                         again after a write leaves none out or a reload
Save to an existing project           -> refused, project untouched; user told the books and the way out
Save As to a new project              -> book and its boundaries left out; user told which; draft stays unsaved
New / Open                            -> discard it (saveDraft's discardUnreadable), which is how the user recovers

Changes to 1b's repository

@imnasnainaec, for the conformance suite in #469:

• replaceAll(draft, options) resolves with the books it left out. A book its load could not read keeps its shard as stored, whatever the draft carries for it, until discardUnreadable says the draft was started over. In 1b, a save carrying analysis for such a book wrote over its shard.
• replaceAll no longer rejects once the draft has landed: a failed orphan-shard deletion or journal update is logged, and a later save retries it.
• exportAll resolves with the draft and the books it could not read.
• AnalysisRepository gains exportForCopy, which reads as exportAll does but rejects an unreadable envelope, and markClean, which rewrites only the envelope.

Evidence

• Before: Save sent the whole TextAnalysis in saveAnalysis (74.9 MB at the largest perf tier, per the Phase 1 baseline in docs/data-layer-plan/plan.md).
  After: Save sends two ids, and no draft write follows it. The perf harness times saveDraftToProject in place of saveAnalysis and still records the request as save-bytes.
• Tests cover, among others:

  commitDraft: pending autosave written before the copy; edit during settle written too
  commitDraft: failed write sent again -> copy runs; fails again -> rejects, no copy
  commitDraft: draft replaced while settling, or a second save -> false, no copy
  Loader: save in flight -> New / Open / Save / Save As / Wipe notify and do nothing
  projectStorage: unreadable book -> Save refused; write leaves it out; Open from a project -> Save works
  projectStorage: stored draft marked clean, unless a book was left out or a draft write followed the read
  Save As leaving books out -> draft stays unsaved
  draftRepository: cleanup failure after the draft lands -> resolves, logged, retried
  DebouncedWriter: a value written again and failing again is retried, not rejected at once
  

• Unit, lint and e2e CI pass.

Merge Danger

Door: two-way

No storage format changes; markClean writes the existing envelope with dirty: false. The one irreversible path is New or Open discarding a draft book's unreadable shard, which only damaged data reaches.

Blast Radius: Save

Save, Save As and autosave all change path. Replacing saveAnalysis with two commands and adding discardUnreadable to saveDraft changes the command surface 4a (#453) builds on. The repository interface grows, so #469 needs cases for it.

🤖 Generated with Claude Code

---

This change is

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

• Source mode: Auto
• Repository: Unavailable
• Branch: Unavailable
• File: No configuration file from this repository applied
• Commit: Unavailable
• Layers: defaults
• Review profile: CHILL
• Plan: Advanced
• Run ID: 5e8aa5dc-ecc0-448a-a717-8740cfee5c0b

• 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.}

[alex-rawlings-yyc]

These comments were generated by Claude Opus 5.5 (Claude Code) and reviewed by me before posting.

[alex-rawlings-yyc]

These comments were generated by Claude Opus 5.5 (Claude Code) and reviewed by me before posting.

[alex-rawlings-yyc]

These comments were generated by Claude Opus 5.5 (Claude Code) and reviewed by me before posting.

[imnasnainaec]

From #432: exportForCopy, markClean, exportAll's unreadable books, and replaceAll's discardUnreadable option and returned left-out books need conformance tests. Whichever of #469 and #475 merges second adds them.

[alex-rawlings-yyc]

These comments were generated by Claude Opus 5.5 (Claude Code) and reviewed by me before posting.

[jasonleenaylor]

@alex-rawlings-yyc, a change of direction on the unreadable-book handling, prompted by your fourth round.

Your finding held, and so did a broader one: with JHN's draft shard damaged, a single gloss in JHN that lands, with no undo at all, makes the next Save replace the project's whole JHN with that one gloss. Looking back over the rounds, 8 of the 9 substantive findings since round one were paths through the same design: saving around a book the draft cannot read, keeping the project's copy, tracking wipes, and so on. Each fix added state the next round found a way around.

So 1d now fails fast instead. A draft write carrying analysis for an unreadable book is refused, so an edit can never hide the damage. Save to an existing project is refused while any book is unreadable, so the project is never touched. Save As to a new project leaves the book out, so other work can still be kept. New and Open discard the unreadable analysis, which is how the user recovers, and each refusal tells them so once until a write succeeds. The case needs a torn write or outside damage, so I would rather it be loud and simple than handled.

That removes wipedBooks, the keep-the-project's-copy merge and its boundaries handling, and the clean-draft write after an edit undone during a Save. An edit undone during a Save now just leaves the draft marked unsaved until the next Save. Tests and source both shrink against the last push. Each new refusal was mutated out and its tests failed.

[alex-rawlings-yyc]

These comments were generated by Claude Opus 5.5 (Claude Code) and reviewed by me before posting.

[imnasnainaec]

@alex-rawlings-yyc e7922198 swaps refusing a draft write that carries analysis for an unreadable book for leaving that book out. The case is rare, but when it happens it usually hits the book being edited: writeUserData is a plain fs.writeFile that isn't atomic, so a crash, force-quit or full disk mid-write cuts short the shard autosave was just rewriting, and that's the book the user is most likely to edit again. Reconsider it. Options:

Keep

• + No trap: other books keep saving, and Save As works.
• − Edits in the unreadable book stay on screen but are dropped, with one notification. Save As then marks the draft synced, so the edits look saved.
• − A write that succeeds while dropping part of the draft conflicts with 3b's all-or-nothing apply ([3b] Add apply with inverse capture and per-session undo #441), so the host path can't adopt this. The flag-on and flag-off paths in [4a] Wire the WebView to the host behind a feature flag #453 will behave differently here.

Reverse (refuse, as in bbd39264)

• + All-or-nothing, so it carries straight over to 3b. Dropped edits never look saved.
• − The trap returns: one edit in the book blocks every later write in every book. If reversed, this PR should also show the refusal on Save and Save As, and change the message to point to undo or wipe as the way out.

[alex-rawlings-yyc]

@alex-rawlings-yyc reviewed 24 files and all commit messages, and resolved 25 discussions.
Reviewable status: all files reviewed, 1 unresolved discussion (waiting on imnasnainaec).

[imnasnainaec]

@imnasnainaec reviewed 22 files and all commit messages, and resolved 1 discussion.
Reviewable status: all files reviewed, 2 unresolved discussions (waiting on jasonleenaylor).

[imnasnainaec]

@imnasnainaec reviewed 2 files and all commit messages.
Reviewable status: complete! all files reviewed, all discussions resolved (waiting on jasonleenaylor).

[alex-rawlings-yyc]

@alex-rawlings-yyc reviewed 2 files and all commit messages.
Reviewable status: complete! all files reviewed, all discussions resolved (waiting on jasonleenaylor).