From bdc89f914eb43e44120076acd3a4d6def5bb4131 Mon Sep 17 00:00:00 2001
From: Danny Rorabaugh <imnasnainaec@gmail.com>
Date: Fri, 16 Oct 2026 14:17:51 -0400
Subject: [PATCH 1/5] Route getDraft and saveDraft through an async repository
 (#431)

AnalysisRepository is the seam a later storage backend replaces: async
calls taking and returning only JSON-plain values, with payload reads
named per kind (getTokenAnalyses, getPhraseAnalyses, getSegmentAnalyses)
and exportAll/replaceAll for callers that still exchange the whole draft.

DraftRepository implements it in memory over today's draft envelope and
per-book shards, keeping projectStorage's guards: only changed shards are
rewritten, the shard journal recovers interrupted saves, and a draft
written by a newer build is neither read nor overwritten. It reaches
storage only through a KeyValueStorage and imports nothing from PAPI.
getDraft and saveDraft keep their contracts and storage calls.

The perf harness seeds each tier's draft and saved projects from Node,
writing the app's storage files through the repository, so seeding no
longer depends on saveDraft or saveAnalysis carrying a whole analysis.
perf:shape reads stored drafts through it too.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 AGENTS.md                                     |   2 +
 e2e-tests/global-setup-perf.ts                |   7 +-
 e2e-tests/perf-app.ts                         |   7 +-
 e2e-tests/tests/perf/app-perf.spec.ts         |  33 +-
 perf/README.md                                |   1 +
 perf/paths.ts                                 |   6 +
 perf/shape/cli.ts                             |  58 +-
 perf/storage.ts                               |  96 +++
 .../services/draftRepository.test.ts          | 191 ++++++
 src/services/draftRepository.ts               | 564 ++++++++++++++++++
 src/services/projectStorage.ts                | 481 ++-------------
 src/types/analysis-repository.ts              |  55 ++
 src/types/type-guards.ts                      |   5 +
 13 files changed, 995 insertions(+), 511 deletions(-)
 create mode 100644 perf/storage.ts
 create mode 100644 src/__tests__/services/draftRepository.test.ts
 create mode 100644 src/services/draftRepository.ts
 create mode 100644 src/types/analysis-repository.ts

diff --git a/AGENTS.md b/AGENTS.md
index 7d2cc6550..090f080f1 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -77,6 +77,8 @@ The WebView root component is assigned to `globalThis.webViewComponent` (not exp
 
 [src/services/projectStorage.ts](src/services/projectStorage.ts) — owns all `papi.storage` reads and writes for interlinearizer projects. Two serialization queues prevent interleaved read-modify-write races. Tests must call `resetQueuesForTesting()` between tests because module state is not cleared by `resetMocks`.
 
+Drafts are read and written through [AnalysisRepository](src/types/analysis-repository.ts), the seam a later storage backend replaces. [DraftRepository](src/services/draftRepository.ts) implements it in memory over the draft envelope and its per-book shards. It imports nothing from PAPI and reaches storage only through a `KeyValueStorage`, so the perf harness runs it in Node straight over the storage files ([perf/storage.ts](perf/storage.ts)).
+
 ### Components
 
 Prefer Platform.Bible's `platform-bible-react` components (`Button`, `Input`, `Textarea`, `Label`, `Switch`, `RadioGroup`, `Popover`, `Tooltip`, etc.) over hand-rolled raw HTML (`<button>`, `<input>`, `<textarea>`, `<label>`, custom dropdowns) wherever an equivalent exists — this keeps the UI visually and behaviorally consistent with the host app and gives us theming and accessibility for free. Reserve raw elements for cases where the platform component can't preserve behavior the extension depends on (e.g. `field-sizing: content` gloss inputs); when you do, add a comment explaining why. When a raw element is replaced by a platform component in tests, extend `__mocks__/platform-bible-react.tsx` to stub the newly-used component.
diff --git a/e2e-tests/global-setup-perf.ts b/e2e-tests/global-setup-perf.ts
index 9a163473c..79aa8a39f 100644
--- a/e2e-tests/global-setup-perf.ts
+++ b/e2e-tests/global-setup-perf.ts
@@ -5,14 +5,9 @@ import { execSync } from 'child_process';
 import globalSetupCdp, { CDP_PORT } from './global-setup-cdp';
 import { isPortInUse, WEBSOCKET_PORT } from './global-setup';
 import globalTeardownCdp from './global-teardown-cdp';
+import { DEV_STORAGE_DIR as STORAGE_DIR } from '../perf/paths';
 import { launchPackagedApp, PACKAGED_APP_PATH, stopPackagedApp } from './perf-app';
 
-/** The development host's storage for this extension's projects and drafts. */
-const STORAGE_DIR = path.resolve(
-  __dirname,
-  '../../paranext-core/dev-appdata/extensions/interlinearizer/user-data',
-);
-
 /** Where the developer's storage waits out a run. */
 const STORAGE_BACKUP_DIR = `${STORAGE_DIR}.perf-backup`;
 
diff --git a/e2e-tests/perf-app.ts b/e2e-tests/perf-app.ts
index 170970822..579056eca 100644
--- a/e2e-tests/perf-app.ts
+++ b/e2e-tests/perf-app.ts
@@ -3,7 +3,7 @@ import { spawn } from 'child_process';
 import fs from 'fs';
 import os from 'os';
 import path from 'path';
-import { CACHE_DIR } from '../perf/paths';
+import { CACHE_DIR, DEV_STORAGE_DIR } from '../perf/paths';
 import { CDP_PORT, waitForRendererSettled } from './global-setup-cdp';
 import { isPortInUse, waitForPort, WEBSOCKET_PORT } from './global-setup';
 import { E2E_SETTINGS_OVERRIDES } from './fixtures/helpers';
@@ -15,6 +15,11 @@ export const PACKAGED_APP_PATH = process.env.PERF_APP_PATH;
 /** Home the packaged app runs under, apart from the developer's profile and kept across restarts. */
 export const PERF_HOME_DIR = path.join(CACHE_DIR, 'app-home');
 
+/** This extension's projects and drafts in the app a run drives. */
+export const STORAGE_DIR = PACKAGED_APP_PATH
+  ? path.join(PERF_HOME_DIR, '.platform.bible', 'extensions', 'interlinearizer', 'user-data')
+  : DEV_STORAGE_DIR;
+
 /** Display backend the app runs on under Linux, overridable with `PERF_OZONE_PLATFORM`. */
 export const OZONE_PLATFORM =
   process.platform === 'linux' ? (process.env.PERF_OZONE_PLATFORM ?? 'x11') : undefined;
diff --git a/e2e-tests/tests/perf/app-perf.spec.ts b/e2e-tests/tests/perf/app-perf.spec.ts
index 7afd746dd..9a80a8af2 100644
--- a/e2e-tests/tests/perf/app-perf.spec.ts
+++ b/e2e-tests/tests/perf/app-perf.spec.ts
@@ -1,8 +1,10 @@
 import type { Browser, Frame, Page } from '@playwright/test';
+import type { DraftProject } from 'interlinearizer';
 import path from 'path';
 import { readDraftJson, readManifest } from '../../../perf/dataset/store';
 import { TIERS, type TierSpec } from '../../../perf/dataset/tiers';
 import { provenance, writeResults } from '../../../perf/results';
+import { addSavedProject, readDraft, writeDraft } from '../../../perf/storage';
 import { readCaptureMeta } from '../../../perf/usj-cache';
 import { expect, test } from '../../fixtures/cdp.fixture';
 import { waitForAppAndInterlinearizerReady } from '../../fixtures/helpers';
@@ -11,6 +13,7 @@ import {
   OZONE_PLATFORM,
   PACKAGED_APP_PATH,
   stopPackagedApp,
+  STORAGE_DIR,
 } from '../../perf-app';
 import type { HostHeap } from './host-inspector';
 import {
@@ -102,31 +105,21 @@ async function restart(app: App): Promise<number> {
   return startupMs;
 }
 
-/** Stores the tier's draft and saved projects, adding each project's id to `created` as it lands. */
+/**
+ * Stores the tier's draft and saved projects straight into the app's extension storage, adding each
+ * project's id to `created` as it lands. The app sees the draft from its next load of it.
+ */
 async function seedTier(
-  page: Page,
   projectId: string,
   tier: TierSpec,
   draftJson: string,
   created: string[],
 ): Promise<void> {
-  await sendCommand(page, 'interlinearizer.saveDraft', projectId, draftJson);
-  const analysisJson = JSON.stringify(JSON.parse(draftJson).analysis);
+  const draft: DraftProject = { ...JSON.parse(draftJson), sourceProjectId: projectId };
+  await writeDraft(STORAGE_DIR, draft);
   for (let i = 0; i < tier.savedProjects; i += 1) {
     // eslint-disable-next-line no-await-in-loop
-    const projectJson = await sendCommand(
-      page,
-      'interlinearizer.createProject',
-      projectId,
-      ['en'],
-      undefined,
-      `Perf ${tier.name} ${i + 1}`,
-    );
-    if (typeof projectJson !== 'string') throw new Error('createProject returned no project');
-    const { id } = JSON.parse(projectJson);
-    created.push(id);
-    // eslint-disable-next-line no-await-in-loop
-    await sendCommand(page, 'interlinearizer.saveAnalysis', id, analysisJson, 'null');
+    created.push(await addSavedProject(STORAGE_DIR, draft, `Perf ${tier.name} ${i + 1}`));
   }
 }
 
@@ -208,7 +201,7 @@ async function measureTier(
   }
 
   await closeView(app.page);
-  await seedTier(app.page, projectId, tier, draftJson, createdProjects);
+  await seedTier(projectId, tier, draftJson, createdProjects);
 
   // The first open after each app start.
   if (PACKAGED_APP_PATH) {
@@ -414,7 +407,7 @@ test('measure the app', async ({ mainPage }) => {
   const tiers = TIERS.filter((t) => requested.length === 0 || requested.includes(t.name));
   await closeView(mainPage);
   await deleteLeftoverProjects(mainPage, projectId);
-  const originalDraft = await sendCommand(mainPage, 'interlinearizer.getDraft', projectId);
+  const originalDraft = await readDraft(STORAGE_DIR, projectId);
   await enableMarks(mainPage);
 
   const createdProjects: string[] = [];
@@ -443,7 +436,7 @@ test('measure the app', async ({ mainPage }) => {
     await closeView(app.page);
     await app.page.evaluate((key) => localStorage.removeItem(key), PERF_MARKS_KEY);
     await setHostPerfMarks(app.page, false);
-    await sendCommand(app.page, 'interlinearizer.saveDraft', projectId, originalDraft);
+    await writeDraft(STORAGE_DIR, originalDraft);
   }
 
   const file = writeResults('app', {
diff --git a/perf/README.md b/perf/README.md
index c3d2f37bd..b534626fd 100644
--- a/perf/README.md
+++ b/perf/README.md
@@ -27,6 +27,7 @@ A dataset is a tier name, or a `draft:<sourceProjectId>` or `project:<id>` key i
 
 - Global setup builds the extension for production (`E2E_BUILD_SCRIPT=build:production`).
 - The run gets empty extension storage, so listing projects reads only what the run seeds. Your own storage waits in `user-data.perf-backup` beside it and comes back on teardown.
+- Each tier's draft and saved projects are written into that storage from Node, through the extension's draft repository, so seeding needs no command that carries a whole draft.
 
 Quit Platform.Bible first. A perf run refuses to start while any instance holds its ports, since that app may own the storage a run sets aside.
 
diff --git a/perf/paths.ts b/perf/paths.ts
index 62622c221..b03577152 100644
--- a/perf/paths.ts
+++ b/perf/paths.ts
@@ -15,6 +15,12 @@ export const DATASETS_DIR = path.join(CACHE_DIR, 'datasets');
 /** Committed result files. */
 export const RESULTS_DIR = path.join(PERF_DIR, 'results');
 
+/** The development app's storage for this extension's projects and drafts. */
+export const DEV_STORAGE_DIR = path.resolve(
+  PERF_DIR,
+  '../../paranext-core/dev-appdata/extensions/interlinearizer/user-data',
+);
+
 /** Short name of the platform's bundled sample project, the text every tier is drawn from. */
 export const SOURCE_PROJECT_NAME = 'WEB';
 
diff --git a/perf/shape/cli.ts b/perf/shape/cli.ts
index 62e4f0004..c96253e0b 100644
--- a/perf/shape/cli.ts
+++ b/perf/shape/cli.ts
@@ -1,29 +1,18 @@
 /* eslint-disable no-console -- a command-line tool reports to its terminal */
-import fs from 'fs';
 import type { TextAnalysis } from 'interlinearizer';
-import path from 'path';
-import { draftAnalysisKey, draftKey } from '../../src/services/storageKeys';
 import { isTextAnalysis } from '../../src/types/type-guards';
-import { mergeAnalyses } from '../../src/utils/analysis-book';
 import { normalizeSurfaceForm } from '../../src/utils/analysis-identity';
 import { verseOfTokenRef } from '../../src/utils/reanchor-analysis';
 import { percentile } from '../bench/measure';
 import { readDraftJson } from '../dataset/store';
 import { TIERS } from '../dataset/tiers';
+import { DEV_STORAGE_DIR } from '../paths';
+import { fileStorage, readDraft } from '../storage';
 
-/** The development host's extension storage, where real imports and drafts sit. */
-const DEFAULT_STORAGE_DIR = path.resolve(
-  __dirname,
-  '../../../paranext-core/dev-appdata/extensions/interlinearizer/user-data',
-);
-
-/** Storage file name for `key`, mirroring core's private `buildUserDataUri`. */
-function storageFile(dir: string, key: string): string {
-  return path.join(dir, Buffer.from(key).toString('base64url'));
-}
-
-function readStored(dir: string, key: string): unknown {
-  return JSON.parse(fs.readFileSync(storageFile(dir, key), 'utf-8'));
+async function readStored(dir: string, key: string): Promise<unknown> {
+  const raw = await fileStorage(dir).read(key);
+  if (raw === undefined) throw new Error(`Nothing is stored at ${key}`);
+  return JSON.parse(raw);
 }
 
 function asAnalysis(value: unknown, what: string): TextAnalysis {
@@ -37,29 +26,16 @@ function analysisOf(value: unknown, what: string): TextAnalysis {
   return asAnalysis(value.analysis, what);
 }
 
-/** A stored draft's analysis, merged from the per-book shards its envelope lists. */
-function readStoredDraft(dir: string, sourceProjectId: string): TextAnalysis {
-  const key = draftKey(sourceProjectId);
-  const envelope = readStored(dir, key);
-  const inline = analysisOf(envelope, key);
-  if (!envelope || typeof envelope !== 'object' || !('analysisBooks' in envelope)) return inline;
-  const { analysisBooks } = envelope;
-  if (!Array.isArray(analysisBooks)) throw new Error(`${key} lists no shards`);
-  return mergeAnalyses([
-    inline,
-    ...analysisBooks.map((book) => {
-      const shardKey = draftAnalysisKey(sourceProjectId, book);
-      return asAnalysis(readStored(dir, shardKey), shardKey);
-    }),
-  ]);
-}
-
 /** Resolves one argument: a tier name, or a `draft:<sourceProjectId>` / `project:<id>` storage key. */
-function load(arg: string, storageDir: string): TextAnalysis {
+async function load(arg: string, storageDir: string): Promise<TextAnalysis> {
   if (TIERS.some((tier) => tier.name === arg))
     return analysisOf(JSON.parse(readDraftJson(arg)), arg);
-  if (arg.startsWith('draft:')) return readStoredDraft(storageDir, arg.slice('draft:'.length));
-  if (arg.startsWith('project:')) return analysisOf(readStored(storageDir, arg), arg);
+  if (arg.startsWith('draft:')) {
+    // A load stands an empty draft in for a missing one, which would measure as all zeros.
+    await readStored(storageDir, arg);
+    return (await readDraft(storageDir, arg.slice('draft:'.length))).analysis;
+  }
+  if (arg.startsWith('project:')) return analysisOf(await readStored(storageDir, arg), arg);
   throw new Error(`Unknown dataset ${arg}: expected a tier name, draft:<id> or project:<id>`);
 }
 
@@ -144,14 +120,16 @@ function shapeOf(analysis: TextAnalysis) {
   };
 }
 
-function main(): void {
-  const storageDir = process.env.PERF_STORAGE_DIR ?? DEFAULT_STORAGE_DIR;
+async function main(): Promise<void> {
+  const storageDir = process.env.PERF_STORAGE_DIR ?? DEV_STORAGE_DIR;
   const args = process.argv.slice(2);
   if (args.length === 0)
     throw new Error(
       `Name datasets to compare: tier names, or draft:<sourceProjectId> / project:<id> keys in ${storageDir}`,
     );
-  const shapes = Object.fromEntries(args.map((arg) => [arg, shapeOf(load(arg, storageDir))]));
+  const shapes = Object.fromEntries(
+    await Promise.all(args.map(async (arg) => [arg, shapeOf(await load(arg, storageDir))])),
+  );
   console.log(JSON.stringify(shapes, undefined, 2));
 }
 
diff --git a/perf/storage.ts b/perf/storage.ts
new file mode 100644
index 000000000..65cacd4f6
--- /dev/null
+++ b/perf/storage.ts
@@ -0,0 +1,96 @@
+import { randomUUID } from 'crypto';
+import fs from 'fs/promises';
+import type { DraftProject, InterlinearProject } from 'interlinearizer';
+import path from 'path';
+import type { KeyValueStorage } from '../src/types/analysis-repository';
+import { DraftRepository } from '../src/services/draftRepository';
+import { projectKey } from '../src/services/storageKeys';
+import { CURRENT_MODEL_VERSION } from '../src/types/model-version';
+
+/** Key of the index listing every saved project's id. */
+const PROJECT_IDS_KEY = 'projectIds';
+
+function isNotFound(e: unknown): boolean {
+  return !!e && typeof e === 'object' && 'code' in e && e.code === 'ENOENT';
+}
+
+/**
+ * The extension's user data in `dir`, laid out as the platform stores it: one file per key, named
+ * by the key's base64url encoding.
+ */
+export function fileStorage(dir: string): KeyValueStorage {
+  const fileOf = (key: string) => path.join(dir, Buffer.from(key, 'utf-8').toString('base64url'));
+  return {
+    async read(key) {
+      try {
+        return await fs.readFile(fileOf(key), 'utf-8');
+      } catch (e) {
+        if (isNotFound(e)) return undefined;
+        throw e;
+      }
+    },
+    async write(key, data) {
+      await fs.mkdir(dir, { recursive: true });
+      await fs.writeFile(fileOf(key), data);
+    },
+    async delete(key) {
+      await fs.rm(fileOf(key), { force: true });
+    },
+  };
+}
+
+/**
+ * Reads a source project's draft from the extension storage in `dir` as the app would load it.
+ *
+ * @throws If the stored draft was written by a newer build, or a stored record cannot be read.
+ */
+export async function readDraft(dir: string, sourceProjectId: string): Promise<DraftProject> {
+  const repository = new DraftRepository(fileStorage(dir), sourceProjectId, console);
+  await repository.load();
+  return { ...(await repository.getScope()), analysis: await repository.exportAll() };
+}
+
+/**
+ * Writes a draft to the extension storage in `dir` as the app would save it. An app running over
+ * `dir` sees it from its next load of that draft.
+ *
+ * @throws If the stored draft was written by a newer build, or a record cannot be written.
+ */
+export async function writeDraft(dir: string, draft: DraftProject): Promise<void> {
+  const { analysis, ...scope } = draft;
+  await new DraftRepository(fileStorage(dir), draft.sourceProjectId, console).replaceAll(
+    scope,
+    analysis,
+  );
+}
+
+/**
+ * Adds a saved project holding `draft`'s analysis and analysis languages to the extension storage
+ * in `dir`.
+ *
+ * @returns The new project's id.
+ * @throws If the project index is not an array of ids, or a record cannot be read or written.
+ */
+export async function addSavedProject(
+  dir: string,
+  draft: DraftProject,
+  name: string,
+): Promise<string> {
+  const storage = fileStorage(dir);
+  const now = new Date().toISOString();
+  const project: InterlinearProject = {
+    id: randomUUID(),
+    modelVersion: CURRENT_MODEL_VERSION,
+    createdAt: now,
+    updatedAt: now,
+    name,
+    sourceProjectId: draft.sourceProjectId,
+    analysisLanguages: draft.analysisLanguages,
+    analysis: draft.analysis,
+  };
+  await storage.write(projectKey(project.id), JSON.stringify(project));
+  const index: unknown = JSON.parse((await storage.read(PROJECT_IDS_KEY)) ?? '[]');
+  if (!Array.isArray(index)) throw new Error(`${PROJECT_IDS_KEY} is not an array of ids`);
+  await storage.write(PROJECT_IDS_KEY, JSON.stringify([...index, project.id]));
+  return project.id;
+}
diff --git a/src/__tests__/services/draftRepository.test.ts b/src/__tests__/services/draftRepository.test.ts
new file mode 100644
index 000000000..e79efc3c5
--- /dev/null
+++ b/src/__tests__/services/draftRepository.test.ts
@@ -0,0 +1,191 @@
+/// <reference types="jest" />
+
+import type { TextAnalysis } from 'interlinearizer';
+import type {
+  DraftScope,
+  KeyValueStorage,
+  RepositoryLogger,
+} from '../../types/analysis-repository';
+import { DraftRepository } from '../../services/draftRepository';
+import { draftAnalysisKey, draftKey } from '../../services/storageKeys';
+import { emptyAnalysis, emptyDraft } from '../../types/empty-factories';
+import { CURRENT_MODEL_VERSION } from '../../types/model-version';
+import { FIXTURE_STAMPS, makePhraseLink } from '../test-helpers';
+
+/** Storage held in a map, recording every write in order. */
+function memoryStorage(initial: Record<string, string> = {}) {
+  const records = new Map(Object.entries(initial));
+  const writes: string[] = [];
+  const storage: KeyValueStorage = {
+    read: async (key) => records.get(key),
+    write: async (key, data) => {
+      writes.push(key);
+      records.set(key, data);
+    },
+    delete: async (key) => {
+      records.delete(key);
+    },
+  };
+  return { storage, records, writes };
+}
+
+/** An empty draft's scope. */
+function scopeOf(sourceProjectId: string): DraftScope {
+  return {
+    sourceProjectId,
+    modelVersion: CURRENT_MODEL_VERSION,
+    analysisLanguages: [],
+    dirty: false,
+  };
+}
+
+function silentLogger(): RepositoryLogger & { warn: jest.Mock } {
+  return { warn: jest.fn() };
+}
+
+/** An analysis with a token payload shared by GEN and EXO, a phrase in GEN and a segment in EXO. */
+function twoBookAnalysis(): TextAnalysis {
+  return {
+    ...emptyAnalysis(),
+    tokenAnalyses: [{ id: 'ta-and', ...FIXTURE_STAMPS, surfaceText: 'and', gloss: { en: 'and' } }],
+    tokenAnalysisLinks: ['GEN', 'EXO'].map((book) => ({
+      id: `tl-${book}`,
+      analysisId: 'ta-and',
+      ...FIXTURE_STAMPS,
+      status: 'approved' as const,
+      token: { tokenRef: `${book} 1:1!0`, surfaceText: 'and' },
+    })),
+    phraseAnalyses: [{ id: 'pa-1', ...FIXTURE_STAMPS, surfaceText: 'in the', gloss: { en: 'in' } }],
+    phraseAnalysisLinks: [makePhraseLink('pa-1', ['GEN 1:1!0', 'GEN 1:1!4'])],
+    segmentAnalyses: [
+      { id: 'sa-1', ...FIXTURE_STAMPS, surfaceText: 'And so', freeTranslation: { en: 'And so.' } },
+    ],
+    segmentAnalysisLinks: [
+      {
+        id: 'sl-1',
+        analysisId: 'sa-1',
+        ...FIXTURE_STAMPS,
+        status: 'approved',
+        segmentId: 'EXO 1:1',
+      },
+    ],
+  };
+}
+
+describe('DraftRepository', () => {
+  it('holds an empty draft for its source project before anything is loaded', async () => {
+    const { storage } = memoryStorage();
+    const repository = new DraftRepository(storage, 'src', silentLogger());
+
+    await expect(repository.getScope()).resolves.toEqual(scopeOf('src'));
+    await expect(repository.exportAll()).resolves.toEqual(emptyAnalysis());
+  });
+
+  it('reads back in a new instance what another wrote', async () => {
+    const { storage } = memoryStorage();
+    const scope = { ...scopeOf('src'), analysisLanguages: ['en'] };
+    await new DraftRepository(storage, 'src', silentLogger()).replaceAll(scope, twoBookAnalysis());
+
+    const reader = new DraftRepository(storage, 'src', silentLogger());
+    await reader.load();
+
+    await expect(reader.getScope()).resolves.toEqual(scope);
+    await expect(reader.exportAll()).resolves.toEqual(twoBookAnalysis());
+  });
+
+  it('serves the payloads asked for by id, in request order, leaving out ids with none', async () => {
+    const { storage } = memoryStorage();
+    const repository = new DraftRepository(storage, 'src', silentLogger());
+    await repository.replaceAll(scopeOf('src'), twoBookAnalysis());
+    const [tokenAnalysis] = twoBookAnalysis().tokenAnalyses;
+    const [phraseAnalysis] = twoBookAnalysis().phraseAnalyses;
+    const [segmentAnalysis] = twoBookAnalysis().segmentAnalyses;
+
+    await expect(repository.getTokenAnalyses(['missing', 'ta-and'])).resolves.toEqual([
+      tokenAnalysis,
+    ]);
+    await expect(repository.getPhraseAnalyses(['pa-1'])).resolves.toEqual([phraseAnalysis]);
+    await expect(repository.getSegmentAnalyses(['sa-1', 'missing'])).resolves.toEqual([
+      segmentAnalysis,
+    ]);
+  });
+
+  it('serves one copy of a payload every book it is linked from stores', async () => {
+    const { storage, records } = memoryStorage();
+    await new DraftRepository(storage, 'src', silentLogger()).replaceAll(
+      scopeOf('src'),
+      twoBookAnalysis(),
+    );
+    expect(records.get(draftAnalysisKey('src', 'EXO'))).toContain('ta-and');
+    expect(records.get(draftAnalysisKey('src', 'GEN'))).toContain('ta-and');
+
+    const reader = new DraftRepository(storage, 'src', silentLogger());
+    await reader.load();
+
+    await expect(reader.getTokenAnalyses(['ta-and'])).resolves.toHaveLength(1);
+  });
+
+  it('serves payloads from what a load read, not what the instance held before', async () => {
+    const { storage } = memoryStorage();
+    const repository = new DraftRepository(storage, 'src', silentLogger());
+    await repository.replaceAll(scopeOf('src'), twoBookAnalysis());
+    await expect(repository.getTokenAnalyses(['ta-and'])).resolves.toHaveLength(1);
+    await new DraftRepository(storage, 'src', silentLogger()).replaceAll(
+      scopeOf('src'),
+      emptyAnalysis(),
+    );
+
+    await repository.load();
+
+    await expect(repository.getTokenAnalyses(['ta-and'])).resolves.toEqual([]);
+  });
+
+  it('rewrites only the books whose records changed since the load', async () => {
+    const { storage, writes } = memoryStorage();
+    await new DraftRepository(storage, 'src', silentLogger()).replaceAll(
+      scopeOf('src'),
+      twoBookAnalysis(),
+    );
+    const repository = new DraftRepository(storage, 'src', silentLogger());
+    await repository.load();
+    writes.length = 0;
+    const edited = twoBookAnalysis();
+    edited.segmentAnalyses[0].freeTranslation = { en: 'And then.' };
+
+    await repository.replaceAll(scopeOf('src'), edited);
+
+    expect(writes).toContain(draftAnalysisKey('src', 'EXO'));
+    expect(writes).not.toContain(draftAnalysisKey('src', 'GEN'));
+  });
+
+  it('leaves a draft written by a newer build as it stands', async () => {
+    const newer = JSON.stringify({ ...emptyDraft('src'), modelVersion: CURRENT_MODEL_VERSION + 1 });
+    const { storage, records, writes } = memoryStorage({ [draftKey('src')]: newer });
+    const repository = new DraftRepository(storage, 'src', silentLogger());
+
+    await expect(repository.load()).rejects.toThrow(/newer than this build supports/);
+    await expect(repository.replaceAll(scopeOf('src'), twoBookAnalysis())).rejects.toThrow(
+      /newer than this build supports/,
+    );
+
+    expect(writes).toEqual([]);
+    expect(records.get(draftKey('src'))).toBe(newer);
+  });
+
+  it('reports a stored shard it cannot use to its logger', async () => {
+    const { storage, records } = memoryStorage();
+    await new DraftRepository(storage, 'src', silentLogger()).replaceAll(
+      scopeOf('src'),
+      twoBookAnalysis(),
+    );
+    records.set(draftAnalysisKey('src', 'GEN'), 'not json');
+    const logger = silentLogger();
+    const repository = new DraftRepository(storage, 'src', logger);
+
+    await repository.load();
+
+    expect(logger.warn).toHaveBeenCalledWith(
+      `Interlinearizer: analysis shard ${draftAnalysisKey('src', 'GEN')} is not valid JSON; treating as empty`,
+    );
+  });
+});
diff --git a/src/services/draftRepository.ts b/src/services/draftRepository.ts
new file mode 100644
index 000000000..933281d77
--- /dev/null
+++ b/src/services/draftRepository.ts
@@ -0,0 +1,564 @@
+import type {
+  DraftProject,
+  PhraseAnalysis,
+  SegmentAnalysis,
+  TextAnalysis,
+  TokenAnalysis,
+} from 'interlinearizer';
+import { emptyAnalysis, emptyDraft } from '../types/empty-factories';
+import { assertSupportedModelVersion, CURRENT_MODEL_VERSION } from '../types/model-version';
+import {
+  hasLinkWithoutId,
+  isDraftProject,
+  isStringArray,
+  isTextAnalysis,
+  validateTextAnalysis,
+} from '../types/type-guards';
+import { mergeAnalyses, splitAnalysisByBook } from '../utils/analysis-book';
+import { perfTime, perfTimeAsync, perfTimeAsyncExcluding } from '../utils/perf-marks';
+import type {
+  AnalysisRepository,
+  DraftScope,
+  KeyValueStorage,
+  RepositoryLogger,
+} from '../types/analysis-repository';
+import { draftAnalysisKey, draftJournalKey, draftKey } from './storageKeys';
+
+/**
+ * Logs how an analysis falls short as it crosses the storage boundary — an unreadable shape, or an
+ * invariant its collections break — tagged with `description` to name the record and the point it
+ * was checked at, e.g. `project abc on save`. Logging is the whole response: the read or the write
+ * proceeds either way, since a record that disagrees with itself still renders, and refusing it
+ * would cost the user their work over a fault they cannot act on.
+ */
+export function reportAnalysisViolations(
+  logger: RepositoryLogger,
+  analysis: unknown,
+  description: string,
+): void {
+  // A stored record is typed but never validated, so its analysis may be absent or misshapen. Only
+  // absence is legitimate: a stored null is corruption.
+  if (analysis === undefined) return;
+  if (!isTextAnalysis(analysis)) {
+    logger.warn(`Interlinearizer: ${description} has a structurally invalid analysis`);
+    return;
+  }
+  validateTextAnalysis(analysis).forEach(({ kind, layer, count, sample }) => {
+    logger.warn(
+      `Interlinearizer: ${description} has ${count} ${layer}-layer ${kind} violation(s): ${sample.join(', ')}`,
+    );
+  });
+}
+
+/**
+ * Awaits every operation, so a caller that rejects leaves none of them still in flight.
+ *
+ * @throws Whatever the first rejecting operation threw, in argument order.
+ */
+async function settleAll(operations: readonly Promise<unknown>[]): Promise<void> {
+  const outcomes = await Promise.allSettled(operations);
+  const failure = outcomes.find((outcome) => outcome.status === 'rejected');
+  if (failure?.status === 'rejected') throw failure.reason;
+}
+
+/**
+ * Names the shards a save is about to strand if it is interrupted, so the next run can find them
+ * without the in-memory tally. Storage cannot enumerate keys, so a shard the manifest does not name
+ * is otherwise unreachable once this process is gone.
+ */
+interface ShardJournal {
+  /**
+   * Books whose shard this save wrote, pending the envelope write that names them. A load reads
+   * these, recovering work an interrupted save would otherwise strand.
+   */
+  adding: string[];
+  /**
+   * Books whose shard is orphaned pending deletion, already dropped from the envelope. A load must
+   * not read these, or the wipe that recorded them would undo itself; they await a retried
+   * deletion.
+   */
+  removing: string[];
+}
+
+/** A journal naming no shards, which is what a cleared or unusable one recovers as. */
+function emptyShardJournal(): ShardJournal {
+  return { adding: [], removing: [] };
+}
+
+/** Type guard for a JSON-parsed value that must be a {@link ShardJournal}. */
+function isShardJournal(value: unknown): value is ShardJournal {
+  if (!value || typeof value !== 'object') return false;
+  return (
+    'adding' in value &&
+    isStringArray(value.adding) &&
+    'removing' in value &&
+    isStringArray(value.removing)
+  );
+}
+
+/** A draft as persisted: the in-memory draft with an always-empty `analysis`, held in shards. */
+type StoredDraft = DraftProject & {
+  /**
+   * Book codes of the shards holding this draft's analysis. Storage cannot enumerate keys, so
+   * nothing else can say which shards a draft owns.
+   */
+  analysisBooks: string[];
+};
+
+/**
+ * Separates a validated draft from its shard manifest, which is absent when the analysis is stored
+ * inline and dropped when it is unusable.
+ */
+function withoutShardManifest(draft: DraftProject): DraftProject & { analysisBooks?: string[] } {
+  if (!('analysisBooks' in draft)) return draft;
+  const { analysisBooks, ...rest } = draft;
+  return isStringArray(analysisBooks) ? { ...rest, analysisBooks } : rest;
+}
+
+/** One book's shard as loaded. */
+type LoadedShard = {
+  /** Empty when the shard could not be read, standing in for content this build cannot recover. */
+  analysis: TextAnalysis;
+  /**
+   * Whether the shard was read, and failing that, whether it still occupies storage — which is what
+   * decides whether anything is left to keep reachable.
+   */
+  state: 'loaded' | 'unusable' | 'absent';
+};
+
+/** Payloads by id, first stored copy winning, for reads by id. */
+interface PayloadsById {
+  token: Map<string, TokenAnalysis>;
+  phrase: Map<string, PhraseAnalysis>;
+  segment: Map<string, SegmentAnalysis>;
+}
+
+/** Indexes payloads by id, keeping the first of any that share one. */
+function byId<T extends { id: string }>(payloads: readonly T[]): Map<string, T> {
+  const map = new Map<string, T>();
+  payloads.forEach((payload) => {
+    if (!map.has(payload.id)) map.set(payload.id, payload);
+  });
+  return map;
+}
+
+/** The stored payload for each id that has one, in request order. */
+function pick<T>(map: ReadonlyMap<string, T>, ids: readonly string[]): T[] {
+  return ids.flatMap((id) => {
+    const payload = map.get(id);
+    return payload === undefined ? [] : [payload];
+  });
+}
+
+/**
+ * A source project's draft held in memory over its stored envelope and per-book analysis shards.
+ * Writes rewrite only the shards whose content changed since this instance last read or wrote them,
+ * and never overwrite a draft written by a newer build.
+ *
+ * Not safe for overlapping calls: the caller serializes {@link load} and {@link replaceAll} on one
+ * instance.
+ */
+export class DraftRepository implements AnalysisRepository {
+  private readonly storage: KeyValueStorage;
+
+  private readonly logger: RepositoryLogger;
+
+  private readonly sourceProjectId: string;
+
+  private scope: DraftScope;
+
+  private analysis: TextAnalysis;
+
+  private payloadsById: PayloadsById | undefined;
+
+  /**
+   * The serialized shard last read or written per book code. An unknown book counts as changed, so
+   * a lost entry costs a write, not correctness.
+   */
+  private writtenShards = new Map<string, string>();
+
+  /**
+   * Book codes whose shard the last load could not read. Such a book reaches the caller as empty,
+   * so a save holds its shard and manifest entry rather than taking it for wiped.
+   */
+  private unreadableShards = new Set<string>();
+
+  /** Starts as an empty draft; {@link load} reads what is stored. */
+  constructor(storage: KeyValueStorage, sourceProjectId: string, logger: RepositoryLogger) {
+    this.storage = storage;
+    this.logger = logger;
+    this.sourceProjectId = sourceProjectId;
+    const { analysis, ...scope } = emptyDraft(sourceProjectId);
+    this.scope = scope;
+    this.analysis = analysis;
+  }
+
+  /**
+   * Replaces what this instance holds with the stored draft. A draft that has never been written,
+   * fails validation, or belongs to a different source project loads as a fresh empty draft, and
+   * the invalid one is logged.
+   *
+   * A draft written by a newer build is refused rather than discarded, leaving it intact for the
+   * build that can read it; {@link replaceAll} refuses to overwrite that same record.
+   *
+   * A book whose shard is missing or unusable loads as empty, and {@link replaceAll} then leaves
+   * that shard and its manifest entry alone rather than treating the book as wiped, until a write
+   * carries analyses for that book again. A shard holding a link with no id is unusable, and a
+   * draft storing its analysis inline with such a link loads as a fresh empty draft; either is
+   * logged.
+   *
+   * A write interrupted before its envelope landed leaves shards the stored manifest does not name.
+   * A book first analyzed in that write still loads with its work rather than empty.
+   *
+   * @throws {SyntaxError} If the draft's stored value contains invalid JSON.
+   * @throws {Error} If the stored draft's `modelVersion` is higher than this build's.
+   * @throws If storage rejects a read.
+   */
+  async load(): Promise<void> {
+    const { analysis, ...scope } = await this.readDraft();
+    this.scope = scope;
+    this.analysis = analysis;
+    this.payloadsById = undefined;
+  }
+
+  async getScope(): Promise<DraftScope> {
+    return { ...this.scope };
+  }
+
+  async getTokenAnalyses(ids: readonly string[]): Promise<TokenAnalysis[]> {
+    return pick(this.payloads().token, ids);
+  }
+
+  async getPhraseAnalyses(ids: readonly string[]): Promise<PhraseAnalysis[]> {
+    return pick(this.payloads().phrase, ids);
+  }
+
+  async getSegmentAnalyses(ids: readonly string[]): Promise<SegmentAnalysis[]> {
+    return pick(this.payloads().segment, ids);
+  }
+
+  async exportAll(): Promise<TextAnalysis> {
+    return { ...this.analysis };
+  }
+
+  /**
+   * Writes the draft, replacing the stored one whole apart from the {@link CURRENT_MODEL_VERSION}
+   * stamp. A draft written by a newer build is the exception: it is left as it stands.
+   *
+   * The analysis spans several records and no storage transaction spans them, so an interrupted
+   * write can leave books from two writes. It never leaves a book listed whose shard is gone. What
+   * did reach storage is tallied as it lands, so the write that follows a failed one rewrites only
+   * the books still missing it.
+   *
+   * Recovery does not depend on this process staying up: a shard the envelope never came to name is
+   * still found on the next load, and a deletion that fails is retried by a later write even across
+   * a restart. A book dropped from the analysis leaves no shard behind whether or not this instance
+   * loaded the draft.
+   *
+   * A write that fails leaves no storage call of its own in flight. What this instance holds takes
+   * the new draft once its envelope lands.
+   *
+   * @throws {Error} If the stored draft was written by a newer build; nothing is written.
+   * @throws If storage rejects a read while checking the stored draft; nothing is written.
+   * @throws If storage rejects a write.
+   * @throws If deleting a wiped book's shard rejects; the shard stays journaled for a later write
+   *   to retry.
+   */
+  async replaceAll(scope: DraftScope, analysis: TextAnalysis): Promise<void> {
+    const { sourceProjectId, storage, writtenShards: written, unreadableShards: unreadable } = this;
+    const storedBooks = await perfTimeAsync('saveDraft:read', () =>
+      this.assertStoredDraftIsWritable(),
+    );
+    const byBook = perfTime('saveDraft:compare', () => splitAnalysisByBook(analysis));
+
+    // Books this write no longer carries, less those held back because the load could not read
+    // them. A write whose draft was never loaded here has only the stored manifest or the journal
+    // to name earlier shards. A journaled addition whose shard never landed deletes as a no-op.
+    const journaled = await perfTimeAsync('saveDraft:read', () => this.readShardJournal());
+    const knownShards = new Set([
+      ...written.keys(),
+      ...storedBooks,
+      ...journaled.adding,
+      ...journaled.removing,
+    ]);
+    const wiped = [...knownShards].filter(
+      (bookCode) => !byBook.has(bookCode) && !unreadable.has(bookCode),
+    );
+    const held = [...unreadable].filter((bookCode) => !byBook.has(bookCode));
+
+    // Name every shard this write could strand before writing any of it. A book the stored manifest
+    // already names needs no entry: it survives an interruption by that manifest alone.
+    const stranded = [...byBook.keys()].filter((bookCode) => !storedBooks.includes(bookCode));
+    await perfTimeAsync('saveDraft:write', () =>
+      this.writeShardJournal({ adding: stranded, removing: wiped }),
+    );
+
+    const shards = perfTime('saveDraft:compare', () =>
+      [...byBook].map(([bookCode, partition]) => {
+        const json = JSON.stringify(partition);
+        return { bookCode, json, changed: written.get(bookCode) !== json };
+      }),
+    );
+    await perfTimeAsync('saveDraft:write', () =>
+      settleAll(
+        shards.map(async ({ bookCode, json, changed }) => {
+          if (changed) await storage.write(draftAnalysisKey(sourceProjectId, bookCode), json);
+          written.set(bookCode, json);
+          // This write restored the book, so a later wipe must be free to delete its shard.
+          unreadable.delete(bookCode);
+        }),
+      ),
+    );
+
+    const envelope: StoredDraft = {
+      ...scope,
+      modelVersion: CURRENT_MODEL_VERSION,
+      analysis: emptyAnalysis(),
+      analysisBooks: [...byBook.keys(), ...held],
+    };
+    await perfTimeAsync('saveDraft:write', () =>
+      storage.write(draftKey(sourceProjectId), JSON.stringify(envelope)),
+    );
+    this.scope = { ...scope, modelVersion: CURRENT_MODEL_VERSION };
+    this.analysis = analysis;
+    this.payloadsById = undefined;
+
+    // A wiped book would otherwise leave its shard orphaned. Deleting only once the envelope has
+    // stopped naming the book keeps a failure here from stranding the manifest on a missing shard.
+    const undeleted: string[] = [];
+    const deletions = await perfTimeAsync('saveDraft:write', () =>
+      Promise.allSettled(
+        wiped.map(async (bookCode) => {
+          try {
+            await storage.delete(draftAnalysisKey(sourceProjectId, bookCode));
+          } catch (e) {
+            // Kept in the journal so a later write retries the deletion even across a restart.
+            undeleted.push(bookCode);
+            throw e;
+          }
+          // Dropped only once the shard is gone, so a later write in this process retries a failed
+          // deletion.
+          written.delete(bookCode);
+        }),
+      ),
+    );
+
+    // With the envelope naming every shard this write added, only a failed deletion is still owed.
+    // A failure to record that yields to the shard error, which is the one worth surfacing; the
+    // next write retries the journal either way.
+    const failed = deletions.find((outcome) => outcome.status === 'rejected');
+    try {
+      await perfTimeAsync('saveDraft:write', () =>
+        this.writeShardJournal({ adding: [], removing: undeleted }),
+      );
+    } catch (e) {
+      if (!failed) throw e;
+      this.logger.warn(
+        `Interlinearizer: could not update the shard journal for ${sourceProjectId}:`,
+        e,
+      );
+    }
+
+    if (failed?.status === 'rejected') throw failed.reason;
+  }
+
+  private payloads(): PayloadsById {
+    this.payloadsById ??= {
+      token: byId(this.analysis.tokenAnalyses),
+      phrase: byId(this.analysis.phraseAnalyses),
+      segment: byId(this.analysis.segmentAnalyses),
+    };
+    return this.payloadsById;
+  }
+
+  /**
+   * Reads the stored draft as {@link load} describes, resetting the shard tally when the draft holds
+   * its analysis in shards.
+   *
+   * @throws {SyntaxError} If the draft's stored value contains invalid JSON.
+   * @throws {Error} If the stored draft's `modelVersion` is higher than this build's.
+   * @throws If storage rejects a read.
+   */
+  private async readDraft(): Promise<DraftProject> {
+    const { sourceProjectId, storage } = this;
+    const raw = await perfTimeAsync('getDraft:read', () => storage.read(draftKey(sourceProjectId)));
+    if (raw === undefined) return emptyDraft(sourceProjectId);
+    const parsed: unknown = perfTime('getDraft:parse', () => JSON.parse(raw));
+    // Refuse a newer build's draft before validating it: a later shape need not satisfy this
+    // build's guard, and failing validation is what resets the draft to empty.
+    assertSupportedModelVersion(parsed, `draft for source project ${sourceProjectId}`);
+    if (
+      !!parsed &&
+      typeof parsed === 'object' &&
+      'analysis' in parsed &&
+      hasLinkWithoutId(parsed.analysis)
+    ) {
+      this.logger.warn(
+        `Interlinearizer: draft for source project ${sourceProjectId} has links without ids; loading it empty`,
+      );
+      return emptyDraft(sourceProjectId);
+    }
+    if (!isDraftProject(parsed) || parsed.sourceProjectId !== sourceProjectId) {
+      this.logger.warn('Interlinearizer: stored draft failed validation; resetting to empty draft');
+      return emptyDraft(sourceProjectId);
+    }
+    const { analysisBooks, ...draft } = withoutShardManifest(parsed);
+    const describeDraft = `draft for source project ${sourceProjectId} on load`;
+    // A draft with no manifest carries its analysis inline, with no shards to read.
+    if (!analysisBooks) {
+      perfTime('getDraft:parse', () =>
+        reportAnalysisViolations(this.logger, draft.analysis, describeDraft),
+      );
+      return draft;
+    }
+    const keyOf = (bookCode: string) => draftAnalysisKey(sourceProjectId, bookCode);
+    // A write interrupted before its envelope landed leaves shards this manifest never came to
+    // name. A journaled book whose shard never landed reads as missing and drops back out below.
+    const { booksToRead, orphaned, shards } = await perfTimeAsyncExcluding(
+      'getDraft:read',
+      'getDraft:parse',
+      async () => {
+        const { adding } = await this.readShardJournal();
+        const orphanedBooks = adding.filter((bookCode) => !analysisBooks.includes(bookCode));
+        const books = [...analysisBooks, ...orphanedBooks];
+        return {
+          booksToRead: books,
+          orphaned: orphanedBooks,
+          shards: await Promise.all(
+            books.map(async (bookCode) => {
+              const shardRaw = await storage.read(keyOf(bookCode));
+              return perfTime('getDraft:parse', () =>
+                this.parseAnalysisShard(shardRaw, keyOf(bookCode)),
+              );
+            }),
+          ),
+        };
+      },
+    );
+    // Record what each shard holds so the next write can tell which books actually changed. An
+    // unusable shard's empty stand-in is not what is on disk, so it is recorded apart. A journaled
+    // book is dropped only when its shard is gone: dropping one still in storage would strand it,
+    // with neither the manifest nor the journal left to name it.
+    const loadedByBook = booksToRead
+      .map((bookCode, i) => ({ bookCode, ...shards[i] }))
+      .filter(({ bookCode, state }) => state !== 'absent' || !orphaned.includes(bookCode));
+    perfTime('getDraft:compare', () => {
+      this.writtenShards = new Map(
+        loadedByBook
+          .filter(({ state }) => state === 'loaded')
+          .map(({ bookCode, analysis }) => [bookCode, JSON.stringify(analysis)]),
+      );
+    });
+    this.unreadableShards = new Set(
+      loadedByBook.filter(({ state }) => state !== 'loaded').map(({ bookCode }) => bookCode),
+    );
+    return perfTime('getDraft:parse', () => {
+      // Checked once merged: a link and its payload can sit in different shards, so a violation
+      // is only real of the whole.
+      const analysis = mergeAnalyses(shards.map((shard) => shard.analysis));
+      reportAnalysisViolations(this.logger, analysis, describeDraft);
+      return { ...draft, analysis };
+    });
+  }
+
+  /**
+   * Parses one book's analysis shard as read from `key`, treating a missing or unusable one as
+   * empty so a single lost book does not fail the whole load. A shard holding a link with no id is
+   * unusable.
+   */
+  private parseAnalysisShard(raw: string | undefined, key: string): LoadedShard {
+    if (raw === undefined) return { analysis: emptyAnalysis(), state: 'absent' };
+    try {
+      const parsed: unknown = JSON.parse(raw);
+      if (hasLinkWithoutId(parsed)) {
+        this.logger.warn(
+          `Interlinearizer: analysis shard ${key} has links without ids; treating as empty`,
+        );
+        return { analysis: emptyAnalysis(), state: 'unusable' };
+      }
+      if (!isTextAnalysis(parsed)) {
+        this.logger.warn(
+          `Interlinearizer: analysis shard ${key} failed validation; treating as empty`,
+        );
+        return { analysis: emptyAnalysis(), state: 'unusable' };
+      }
+      return { analysis: parsed, state: 'loaded' };
+    } catch {
+      this.logger.warn(
+        `Interlinearizer: analysis shard ${key} is not valid JSON; treating as empty`,
+      );
+      return { analysis: emptyAnalysis(), state: 'unusable' };
+    }
+  }
+
+  /**
+   * Guards an otherwise blind draft write against clobbering a record this build cannot read. The
+   * draft in hand is not evidence about what is on disk: a caller that could not read the stored
+   * draft holds an empty one stamped with this revision, and writing that would land on the very
+   * record the refused read protected.
+   *
+   * A draft that is absent or unparseable carries no stamp to refuse, so the write proceeds and
+   * replaces it. A read that fails for any other reason cannot rule out the very record this guard
+   * protects: a refused write costs a retry, where an overwritten record is gone for good.
+   *
+   * @returns The book codes the stored draft's manifest names, empty when there is no readable
+   *   manifest to name them.
+   * @throws {Error} If the stored draft's `modelVersion` is higher than this build's.
+   * @throws If storage rejects the read.
+   */
+  private async assertStoredDraftIsWritable(): Promise<string[]> {
+    const raw = await this.storage.read(draftKey(this.sourceProjectId));
+    if (raw === undefined) return [];
+    let stored: unknown;
+    try {
+      stored = JSON.parse(raw);
+    } catch {
+      return [];
+    }
+    assertSupportedModelVersion(stored, `draft for source project ${this.sourceProjectId}`);
+    if (!isDraftProject(stored)) return [];
+    const { analysisBooks } = withoutShardManifest(stored);
+    return analysisBooks ?? [];
+  }
+
+  /**
+   * Reads the shard journal, recovering a missing, unparseable, or malformed one as empty. A
+   * journal is a recovery hint rather than a record of truth: every book it names is cross-checked
+   * against storage before it is acted on, so losing one costs an orphaned shard, never
+   * correctness.
+   *
+   * @throws If storage rejects the read.
+   */
+  private async readShardJournal(): Promise<ShardJournal> {
+    const { sourceProjectId } = this;
+    const raw = await this.storage.read(draftJournalKey(sourceProjectId));
+    if (raw === undefined) return emptyShardJournal();
+    try {
+      const parsed: unknown = JSON.parse(raw);
+      if (isShardJournal(parsed)) return parsed;
+      this.logger.warn(
+        `Interlinearizer: shard journal for ${sourceProjectId} is malformed; treating as empty`,
+      );
+    } catch {
+      this.logger.warn(
+        `Interlinearizer: shard journal for ${sourceProjectId} is not valid JSON; treating as empty`,
+      );
+    }
+    return emptyShardJournal();
+  }
+
+  /**
+   * Writes the shard journal, deleting the record instead when it names nothing, so a settled draft
+   * leaves no journal behind.
+   *
+   * @throws If storage rejects the write or the deletion.
+   */
+  private async writeShardJournal(journal: ShardJournal): Promise<void> {
+    const key = draftJournalKey(this.sourceProjectId);
+    if (journal.adding.length === 0 && journal.removing.length === 0) {
+      await this.storage.delete(key);
+      return;
+    }
+    await this.storage.write(key, JSON.stringify(journal));
+  }
+}
diff --git a/src/services/projectStorage.ts b/src/services/projectStorage.ts
index 39b5b1151..fc014fbb8 100644
--- a/src/services/projectStorage.ts
+++ b/src/services/projectStorage.ts
@@ -6,17 +6,13 @@ import type {
   SegmentationDelta,
   TextAnalysis,
 } from 'interlinearizer';
-import { emptyAnalysis, emptyDraft } from '../types/empty-factories';
-import { mergeAnalyses, splitAnalysisByBook } from '../utils/analysis-book';
+import { emptyAnalysis } from '../types/empty-factories';
 import { assertSupportedModelVersion, CURRENT_MODEL_VERSION } from '../types/model-version';
-import {
-  hasLinkWithoutId,
-  isDraftProject,
-  isTextAnalysis,
-  validateTextAnalysis,
-} from '../types/type-guards';
+import { hasLinkWithoutId, isStringArray } from '../types/type-guards';
 import { perfTime, perfTimeAsync, perfTimeAsyncExcluding } from '../utils/perf-marks';
-import { draftAnalysisKey, draftJournalKey, draftKey, projectKey } from './storageKeys';
+import type { KeyValueStorage } from '../types/analysis-repository';
+import { DraftRepository, reportAnalysisViolations } from './draftRepository';
+import { draftKey, projectKey } from './storageKeys';
 
 const PROJECT_IDS_KEY = 'projectIds';
 
@@ -57,27 +53,32 @@ const projectQueues = new Map<string, Promise<unknown>>();
 const draftQueues = new Map<string, Promise<unknown>>();
 
 /**
- * The serialized analysis shard last read or written per source project, keyed by source project id
- * then book code. An unknown book counts as changed, so a lost entry costs a write, not
- * correctness.
+ * Each source project's draft repository, kept across calls so a save rewrites only the books that
+ * changed since the last load or save.
  */
-const shardContentsBySource = new Map<string, Map<string, string>>();
+const draftRepositories = new Map<string, DraftRepository>();
 
-/**
- * Book codes whose shard the last load could not read, per source project. Such a book reaches the
- * caller as empty, so a save holds its shard and manifest entry rather than taking it for wiped.
- */
-const unreadableShardsBySource = new Map<string, Set<string>>();
+/** Extension user data as {@link KeyValueStorage}, reading a never-written key as absent. */
+function userDataStorage(token: ExecutionToken): KeyValueStorage {
+  return {
+    read: (key) => readRecord(token, key),
+    write: (key, data) => papi.storage.writeUserData(token, key, data),
+    async delete(key) {
+      try {
+        await papi.storage.deleteUserData(token, key);
+      } catch (e) {
+        if (!isNotFound(e)) throw e;
+      }
+    },
+  };
+}
 
-/**
- * Returns `key`'s entry in `map`, storing a fresh one from `create` when absent. The entry itself
- * is returned, not a copy, so a caller's mutations reach the map.
- */
-function getOrCreateEntry<K, V>(map: Map<K, V>, key: K, create: () => V): V {
-  const existing = map.get(key);
-  if (existing !== undefined) return existing;
-  const created = create();
-  map.set(key, created);
+/** The source project's draft repository, created over `token`'s user data on first use. */
+function draftRepositoryFor(token: ExecutionToken, sourceProjectId: string): DraftRepository {
+  const existing = draftRepositories.get(sourceProjectId);
+  if (existing) return existing;
+  const created = new DraftRepository(userDataStorage(token), sourceProjectId, logger);
+  draftRepositories.set(sourceProjectId, created);
   return created;
 }
 
@@ -136,17 +137,6 @@ function enqueuePendingCleanupOp<T>(fn: () => Promise<T>): Promise<T> {
   );
 }
 
-/**
- * Awaits every operation, so a caller that rejects leaves none of them still in flight.
- *
- * @throws Whatever the first rejecting operation threw, in argument order.
- */
-async function settleAll(operations: readonly Promise<unknown>[]): Promise<void> {
-  const outcomes = await Promise.allSettled(operations);
-  const failure = outcomes.find((outcome) => outcome.status === 'rejected');
-  if (failure?.status === 'rejected') throw failure.reason;
-}
-
 /**
  * Enqueues `fn` on the serialization queue identified by `key` within `queues` and returns a
  * promise that resolves or rejects with `fn`'s result. Cleans up the queue entry when the operation
@@ -190,128 +180,6 @@ function pt9ImportReadOnlyError(id: string): Error {
   return new Error(`Project ${id} is a Paratext 9 import and is read-only`);
 }
 
-/**
- * Names the shards a save is about to strand if it is interrupted, so the next run can find them
- * without the in-memory tally. Storage cannot enumerate keys, so a shard the manifest does not name
- * is otherwise unreachable once this process is gone.
- */
-interface ShardJournal {
-  /**
-   * Books whose shard this save wrote, pending the envelope write that names them. A load reads
-   * these, recovering work an interrupted save would otherwise strand.
-   */
-  adding: string[];
-  /**
-   * Books whose shard is orphaned pending deletion, already dropped from the envelope. A load must
-   * not read these, or the wipe that recorded them would undo itself; they await a retried
-   * deletion.
-   */
-  removing: string[];
-}
-
-/** A journal naming no shards, which is what a cleared or unusable one recovers as. */
-function emptyShardJournal(): ShardJournal {
-  return { adding: [], removing: [] };
-}
-
-/** Type guard for a JSON-parsed value that must be a {@link ShardJournal}. */
-function isShardJournal(value: unknown): value is ShardJournal {
-  if (!value || typeof value !== 'object') return false;
-  return (
-    'adding' in value &&
-    isStringArray(value.adding) &&
-    'removing' in value &&
-    isStringArray(value.removing)
-  );
-}
-
-/**
- * Reads a source project's shard journal, recovering a missing, unparseable, or malformed one as
- * empty. A journal is a recovery hint rather than a record of truth: every book it names is
- * cross-checked against storage before it is acted on, so losing one costs an orphaned shard, never
- * correctness.
- *
- * @throws If `papi.storage.readUserData` rejects for any non-ENOENT reason.
- */
-async function readShardJournal(
-  token: ExecutionToken,
-  sourceProjectId: string,
-): Promise<ShardJournal> {
-  let raw: string;
-  try {
-    raw = await papi.storage.readUserData(token, draftJournalKey(sourceProjectId));
-  } catch (e) {
-    if (isNotFound(e)) return emptyShardJournal();
-    throw e;
-  }
-  try {
-    const parsed: unknown = JSON.parse(raw);
-    if (isShardJournal(parsed)) return parsed;
-    logger.warn(
-      `Interlinearizer: shard journal for ${sourceProjectId} is malformed; treating as empty`,
-    );
-  } catch {
-    logger.warn(
-      `Interlinearizer: shard journal for ${sourceProjectId} is not valid JSON; treating as empty`,
-    );
-  }
-  return emptyShardJournal();
-}
-
-/**
- * Writes a source project's shard journal, deleting the record instead when it names nothing, so a
- * settled draft leaves no journal behind.
- *
- * @throws If `papi.storage.writeUserData` rejects, or if `papi.storage.deleteUserData` rejects for
- *   any non-ENOENT reason.
- */
-async function writeShardJournal(
-  token: ExecutionToken,
-  sourceProjectId: string,
-  journal: ShardJournal,
-): Promise<void> {
-  const key = draftJournalKey(sourceProjectId);
-  if (journal.adding.length === 0 && journal.removing.length === 0) {
-    try {
-      await papi.storage.deleteUserData(token, key);
-    } catch (e) {
-      if (!isNotFound(e)) throw e;
-    }
-    return;
-  }
-  await papi.storage.writeUserData(token, key, JSON.stringify(journal));
-}
-
-/** A draft as persisted: the in-memory draft with an always-empty `analysis`, held in shards. */
-type StoredDraft = DraftProject & {
-  /**
-   * Book codes of the shards holding this draft's analysis. Storage cannot enumerate keys, so
-   * nothing else can say which shards a draft owns.
-   */
-  analysisBooks: string[];
-};
-
-/**
- * Separates a validated draft from its shard manifest, which is absent when the analysis is stored
- * inline and dropped when it is unusable.
- */
-function withoutShardManifest(draft: DraftProject): DraftProject & { analysisBooks?: string[] } {
-  if (!('analysisBooks' in draft)) return draft;
-  const { analysisBooks, ...rest } = draft;
-  return isStringArray(analysisBooks) ? { ...rest, analysisBooks } : rest;
-}
-
-/** One book's shard as loaded. */
-type LoadedShard = {
-  /** Empty when the shard could not be read, standing in for content this build cannot recover. */
-  analysis: TextAnalysis;
-  /**
-   * Whether the shard was read, and failing that, whether it still occupies storage — which is what
-   * decides whether anything is left to keep reachable.
-   */
-  state: 'loaded' | 'unusable' | 'absent';
-};
-
 /**
  * Reads the record stored at `key`.
  *
@@ -327,32 +195,6 @@ async function readRecord(token: ExecutionToken, key: string): Promise<string |
   }
 }
 
-/**
- * Parses one book's analysis shard as read from `key`, treating a missing or unusable one as empty
- * so a single lost book does not fail the whole load. A shard holding a link with no id is
- * unusable.
- */
-function parseAnalysisShard(raw: string | undefined, key: string): LoadedShard {
-  if (raw === undefined) return { analysis: emptyAnalysis(), state: 'absent' };
-  try {
-    const parsed: unknown = JSON.parse(raw);
-    if (hasLinkWithoutId(parsed)) {
-      logger.warn(
-        `Interlinearizer: analysis shard ${key} has links without ids; treating as empty`,
-      );
-      return { analysis: emptyAnalysis(), state: 'unusable' };
-    }
-    if (!isTextAnalysis(parsed)) {
-      logger.warn(`Interlinearizer: analysis shard ${key} failed validation; treating as empty`);
-      return { analysis: emptyAnalysis(), state: 'unusable' };
-    }
-    return { analysis: parsed, state: 'loaded' };
-  } catch {
-    logger.warn(`Interlinearizer: analysis shard ${key} is not valid JSON; treating as empty`);
-    return { analysis: emptyAnalysis(), state: 'unusable' };
-  }
-}
-
 /**
  * Returns true when `e` is a file-not-found error (ENOENT) from the Node.js file system, which is
  * what `papi.storage.readUserData` throws when the requested key has never been written.
@@ -361,36 +203,6 @@ function isNotFound(e: unknown): boolean {
   return !!e && typeof e === 'object' && 'code' in e && e.code === 'ENOENT';
 }
 
-/**
- * Logs how an analysis falls short as it crosses the storage boundary — an unreadable shape, or an
- * invariant its collections break — tagged with `description` to name the record and the point it
- * was checked at, e.g. `project abc on save`. Logging is the whole response: the read or the write
- * proceeds either way, since a record that disagrees with itself still renders, and refusing it
- * would cost the user their work over a fault they cannot act on.
- */
-function reportAnalysisViolations(analysis: unknown, description: string): void {
-  // A stored record is typed but never validated, so its analysis may be absent or misshapen. Only
-  // absence is legitimate: a stored null is corruption.
-  if (analysis === undefined) return;
-  if (!isTextAnalysis(analysis)) {
-    logger.warn(`Interlinearizer: ${description} has a structurally invalid analysis`);
-    return;
-  }
-  validateTextAnalysis(analysis).forEach(({ kind, layer, count, sample }) => {
-    logger.warn(
-      `Interlinearizer: ${description} has ${count} ${layer}-layer ${kind} violation(s): ${sample.join(', ')}`,
-    );
-  });
-}
-
-/**
- * Type guard for a JSON-parsed value that must be an array of strings — the shape of both the
- * `projectIds` index and the `pendingCleanup` set.
- */
-function isStringArray(value: unknown): value is string[] {
-  return Array.isArray(value) && value.every((id) => typeof id === 'string');
-}
-
 /**
  * Reads and JSON-parses the value stored at `key`, treating a never-written key as an empty array.
  * Returns the raw parsed value as `unknown` and does not validate that it is an array of strings.
@@ -707,7 +519,7 @@ export async function savePt9Import(
     };
   };
 
-  reportAnalysisViolations(analysis, `Paratext 9 import of ${sourceProjectId} on save`);
+  reportAnalysisViolations(logger, analysis, `Paratext 9 import of ${sourceProjectId} on save`);
 
   const existing = await getPt9ImportForSource(token, sourceProjectId);
   if (existing) {
@@ -827,7 +639,7 @@ function parseProject(raw: string, id: string): InterlinearProject {
   const lacksLinkIds = hasLinkWithoutId(stored.analysis);
   if (lacksLinkIds)
     logger.warn(`Interlinearizer: project ${id} has links without ids; loading it empty`);
-  else reportAnalysisViolations(stored.analysis, `project ${id} on load`);
+  else reportAnalysisViolations(logger, stored.analysis, `project ${id} on load`);
   return {
     ...stored,
     ...(lacksLinkIds && { analysis: emptyAnalysis() }),
@@ -915,7 +727,7 @@ export async function updateAnalysis(
     const project = perfTime('updateAnalysis:parse', () => parseProject(raw, id));
     if (project.pt9Import) throw pt9ImportReadOnlyError(id);
     perfTime('updateAnalysis:parse', () =>
-      reportAnalysisViolations(analysis, `project ${id} on save`),
+      reportAnalysisViolations(logger, analysis, `project ${id} on save`),
     );
     const updated: InterlinearProject = {
       ...project,
@@ -1062,131 +874,12 @@ export async function getDraft(
   sourceProjectId: string,
 ): Promise<DraftProject> {
   return enqueueSerialized(draftQueues, sourceProjectId, async () => {
-    const raw = await perfTimeAsync('getDraft:read', () =>
-      readRecord(token, draftKey(sourceProjectId)),
-    );
-    if (raw === undefined) return emptyDraft(sourceProjectId);
-    const parsed: unknown = perfTime('getDraft:parse', () => JSON.parse(raw));
-    // Refuse a newer build's draft before validating it: a later shape need not satisfy this
-    // build's guard, and failing validation is what resets the draft to empty.
-    assertSupportedModelVersion(parsed, `draft for source project ${sourceProjectId}`);
-    if (
-      !!parsed &&
-      typeof parsed === 'object' &&
-      'analysis' in parsed &&
-      hasLinkWithoutId(parsed.analysis)
-    ) {
-      logger.warn(
-        `Interlinearizer: draft for source project ${sourceProjectId} has links without ids; loading it empty`,
-      );
-      return emptyDraft(sourceProjectId);
-    }
-    if (!isDraftProject(parsed) || parsed.sourceProjectId !== sourceProjectId) {
-      logger.warn('Interlinearizer: stored draft failed validation; resetting to empty draft');
-      return emptyDraft(sourceProjectId);
-    }
-    const { analysisBooks, ...draft } = withoutShardManifest(parsed);
-    const describeDraft = `draft for source project ${sourceProjectId} on load`;
-    // A draft with no manifest carries its analysis inline, with no shards to read.
-    if (!analysisBooks) {
-      perfTime('getDraft:parse', () => reportAnalysisViolations(draft.analysis, describeDraft));
-      return draft;
-    }
-    const keyOf = (bookCode: string) => draftAnalysisKey(sourceProjectId, bookCode);
-    // A save interrupted before its envelope landed leaves shards this manifest never came to
-    // name. A journaled book whose shard never landed reads as missing and drops back out below.
-    const { booksToRead, orphaned, shards } = await perfTimeAsyncExcluding(
-      'getDraft:read',
-      'getDraft:parse',
-      async () => {
-        const { adding } = await readShardJournal(token, sourceProjectId);
-        const orphanedBooks = adding.filter((bookCode) => !analysisBooks.includes(bookCode));
-        const books = [...analysisBooks, ...orphanedBooks];
-        return {
-          booksToRead: books,
-          orphaned: orphanedBooks,
-          shards: await Promise.all(
-            books.map(async (bookCode) => {
-              const shardRaw = await readRecord(token, keyOf(bookCode));
-              return perfTime('getDraft:parse', () =>
-                parseAnalysisShard(shardRaw, keyOf(bookCode)),
-              );
-            }),
-          ),
-        };
-      },
-    );
-    // Record what each shard holds so the next save can tell which books actually changed. An
-    // unusable shard's empty stand-in is not what is on disk, so it is recorded apart. A journaled
-    // book is dropped only when its shard is gone: dropping one still in storage would strand it,
-    // with neither the manifest nor the journal left to name it.
-    const loadedByBook = booksToRead
-      .map((bookCode, i) => ({ bookCode, ...shards[i] }))
-      .filter(({ bookCode, state }) => state !== 'absent' || !orphaned.includes(bookCode));
-    perfTime('getDraft:compare', () =>
-      shardContentsBySource.set(
-        sourceProjectId,
-        new Map(
-          loadedByBook
-            .filter(({ state }) => state === 'loaded')
-            .map(({ bookCode, analysis }) => [bookCode, JSON.stringify(analysis)]),
-        ),
-      ),
-    );
-    unreadableShardsBySource.set(
-      sourceProjectId,
-      new Set(
-        loadedByBook.filter(({ state }) => state !== 'loaded').map(({ bookCode }) => bookCode),
-      ),
-    );
-    return perfTime('getDraft:parse', () => {
-      // Checked once merged: a link and its payload can sit in different shards, so a violation
-      // is only real of the whole.
-      const analysis = mergeAnalyses(shards.map((shard) => shard.analysis));
-      reportAnalysisViolations(analysis, describeDraft);
-      return { ...draft, analysis };
-    });
+    const repository = draftRepositoryFor(token, sourceProjectId);
+    await repository.load();
+    return { ...(await repository.getScope()), analysis: await repository.exportAll() };
   });
 }
 
-/**
- * Guards an otherwise blind draft write against clobbering a record this build cannot read. The
- * draft in hand is not evidence about what is on disk: a caller that could not read the stored
- * draft holds an empty one stamped with this revision, and writing that would land on the very
- * record the refused read protected.
- *
- * A draft that is absent or unparseable carries no stamp to refuse, so the write proceeds and
- * replaces it. A read that fails for any other reason cannot rule out the very record this guard
- * protects: a refused write costs a retry, where an overwritten record is gone for good.
- *
- * @returns The book codes the stored draft's manifest names, empty when there is no readable
- *   manifest to name them.
- * @throws {Error} If the stored draft's `modelVersion` is higher than this build's.
- * @throws If `papi.storage.readUserData` rejects for any non-ENOENT reason.
- */
-async function assertStoredDraftIsWritable(
-  token: ExecutionToken,
-  sourceProjectId: string,
-): Promise<string[]> {
-  let raw: string;
-  try {
-    raw = await papi.storage.readUserData(token, draftKey(sourceProjectId));
-  } catch (e) {
-    if (isNotFound(e)) return [];
-    throw e;
-  }
-  let stored: unknown;
-  try {
-    stored = JSON.parse(raw);
-  } catch {
-    return [];
-  }
-  assertSupportedModelVersion(stored, `draft for source project ${sourceProjectId}`);
-  if (!isDraftProject(stored)) return [];
-  const { analysisBooks } = withoutShardManifest(stored);
-  return analysisBooks ?? [];
-}
-
 /**
  * Writes the draft working buffer for a source project, replacing any existing draft. Writes are
  * serialized per source project, so a WebView's rapid auto-saves cannot persist out of order. The
@@ -1220,107 +913,8 @@ export async function saveDraft(
 ): Promise<void> {
   // Invariant violations go unreported here: this runs on every edit, so one would log per keystroke.
   await enqueueSerialized(draftQueues, sourceProjectId, async () => {
-    const storedBooks = await perfTimeAsync('saveDraft:read', () =>
-      assertStoredDraftIsWritable(token, sourceProjectId),
-    );
-    const byBook = perfTime('saveDraft:compare', () => splitAnalysisByBook(draft.analysis));
-    const written = getOrCreateEntry(shardContentsBySource, sourceProjectId, () => new Map());
-    const unreadable = getOrCreateEntry(unreadableShardsBySource, sourceProjectId, () => new Set());
-
-    // Books this save no longer carries, less those held back because the load could not read them.
-    // A save whose draft was never loaded here has only the stored manifest or the journal to name
-    // earlier shards. A journaled addition whose shard never landed deletes as a no-op.
-    const journaled = await perfTimeAsync('saveDraft:read', () =>
-      readShardJournal(token, sourceProjectId),
-    );
-    const knownShards = new Set([
-      ...written.keys(),
-      ...storedBooks,
-      ...journaled.adding,
-      ...journaled.removing,
-    ]);
-    const wiped = [...knownShards].filter(
-      (bookCode) => !byBook.has(bookCode) && !unreadable.has(bookCode),
-    );
-    const held = [...unreadable].filter((bookCode) => !byBook.has(bookCode));
-
-    // Name every shard this save could strand before writing any of it. A book the stored manifest
-    // already names needs no entry: it survives an interruption by that manifest alone.
-    const stranded = [...byBook.keys()].filter((bookCode) => !storedBooks.includes(bookCode));
-    await perfTimeAsync('saveDraft:write', () =>
-      writeShardJournal(token, sourceProjectId, { adding: stranded, removing: wiped }),
-    );
-
-    const shards = perfTime('saveDraft:compare', () =>
-      [...byBook].map(([bookCode, partition]) => {
-        const json = JSON.stringify(partition);
-        return { bookCode, json, changed: written.get(bookCode) !== json };
-      }),
-    );
-    await perfTimeAsync('saveDraft:write', () =>
-      settleAll(
-        shards.map(async ({ bookCode, json, changed }) => {
-          if (changed) {
-            await papi.storage.writeUserData(
-              token,
-              draftAnalysisKey(sourceProjectId, bookCode),
-              json,
-            );
-          }
-          written.set(bookCode, json);
-          // This save rewrote the book, so a later wipe must be free to delete the shard it
-          // restored.
-          unreadable.delete(bookCode);
-        }),
-      ),
-    );
-
-    const envelope: StoredDraft = {
-      ...draft,
-      modelVersion: CURRENT_MODEL_VERSION,
-      analysis: emptyAnalysis(),
-      analysisBooks: [...byBook.keys(), ...held],
-    };
-    await perfTimeAsync('saveDraft:write', () =>
-      papi.storage.writeUserData(token, draftKey(sourceProjectId), JSON.stringify(envelope)),
-    );
-
-    // A wiped book would otherwise leave its shard orphaned. Deleting only once the envelope has
-    // stopped naming the book keeps a failure here from stranding the manifest on a missing shard.
-    const undeleted: string[] = [];
-    const deletions = await perfTimeAsync('saveDraft:write', () =>
-      Promise.allSettled(
-        wiped.map(async (bookCode) => {
-          try {
-            await papi.storage.deleteUserData(token, draftAnalysisKey(sourceProjectId, bookCode));
-          } catch (e) {
-            if (!isNotFound(e)) {
-              // Kept in the journal so a later save retries the deletion even across a restart.
-              undeleted.push(bookCode);
-              throw e;
-            }
-          }
-          // Dropped only once the shard is gone, so a later save in this process retries a failed
-          // deletion.
-          written.delete(bookCode);
-        }),
-      ),
-    );
-
-    // With the envelope naming every shard this save added, only a failed deletion is still owed.
-    // A failure to record that yields to the shard error, which is the one worth surfacing; the
-    // next save retries the journal either way.
-    const failed = deletions.find((outcome) => outcome.status === 'rejected');
-    try {
-      await perfTimeAsync('saveDraft:write', () =>
-        writeShardJournal(token, sourceProjectId, { adding: [], removing: undeleted }),
-      );
-    } catch (e) {
-      if (!failed) throw e;
-      logger.warn(`Interlinearizer: could not update the shard journal for ${sourceProjectId}:`, e);
-    }
-
-    if (failed?.status === 'rejected') throw failed.reason;
+    const { analysis, ...scope } = draft;
+    await draftRepositoryFor(token, sourceProjectId).replaceAll(scope, analysis);
   });
 }
 
@@ -1334,6 +928,5 @@ export function resetQueuesForTesting(): void {
   pendingCleanupQueue = Promise.resolve();
   projectQueues.clear();
   draftQueues.clear();
-  shardContentsBySource.clear();
-  unreadableShardsBySource.clear();
+  draftRepositories.clear();
 }
diff --git a/src/types/analysis-repository.ts b/src/types/analysis-repository.ts
new file mode 100644
index 000000000..b23b63fa4
--- /dev/null
+++ b/src/types/analysis-repository.ts
@@ -0,0 +1,55 @@
+import type {
+  DraftProject,
+  PhraseAnalysis,
+  SegmentAnalysis,
+  TextAnalysis,
+  TokenAnalysis,
+} from 'interlinearizer';
+
+/**
+ * Text records by key: the platform's per-extension user data in the extension host, or files in
+ * the same layout in Node.
+ */
+export interface KeyValueStorage {
+  /** @returns `undefined` when nothing is stored at `key`. */
+  read(key: string): Promise<string | undefined>;
+  write(key: string, data: string): Promise<void>;
+  /** Succeeds as well when nothing is stored at `key`. */
+  delete(key: string): Promise<void>;
+}
+
+/** Where a repository reports records it could not use as stored. */
+export interface RepositoryLogger {
+  warn(message: string, ...details: unknown[]): void;
+}
+
+/** A source project's draft apart from its analysis: what the records it holds belong to. */
+export type DraftScope = Omit<DraftProject, 'analysis'>;
+
+/**
+ * Reads and writes one draft's analysis records. Every call is async and takes and returns only
+ * JSON-plain values, so an implementation may sit behind a network boundary or another language.
+ */
+export interface AnalysisRepository {
+  getScope(): Promise<DraftScope>;
+
+  /** @returns One payload per requested id that is stored; ids with none are left out. */
+  getTokenAnalyses(ids: readonly string[]): Promise<TokenAnalysis[]>;
+
+  /** @returns One payload per requested id that is stored; ids with none are left out. */
+  getPhraseAnalyses(ids: readonly string[]): Promise<PhraseAnalysis[]>;
+
+  /** @returns One payload per requested id that is stored; ids with none are left out. */
+  getSegmentAnalyses(ids: readonly string[]): Promise<SegmentAnalysis[]>;
+
+  /** Every record, for callers that still exchange the whole draft. */
+  exportAll(): Promise<TextAnalysis>;
+
+  /**
+   * Replaces the scope and every record, for callers that still exchange the whole draft.
+   *
+   * @throws {Error} If the stored draft was written by a newer build; nothing is written.
+   * @throws If storage rejects a read or a write.
+   */
+  replaceAll(scope: DraftScope, analysis: TextAnalysis): Promise<void>;
+}
diff --git a/src/types/type-guards.ts b/src/types/type-guards.ts
index c2777f47a..becb38acc 100644
--- a/src/types/type-guards.ts
+++ b/src/types/type-guards.ts
@@ -280,6 +280,11 @@ export function hasLinkWithoutId(analysis: unknown): boolean {
   );
 }
 
+/** Type guard for a JSON-parsed value that must be an array of strings. */
+export function isStringArray(value: unknown): value is string[] {
+  return Array.isArray(value) && value.every((item) => typeof item === 'string');
+}
+
 /**
  * Validates a {@link SegmentationDelta} parsed from unknown JSON, so a malformed delta cannot
  * corrupt re-segmentation.

From 25c651a5cb5e699642b8891502edd4d1cf05319f Mon Sep 17 00:00:00 2001
From: Danny Rorabaugh <imnasnainaec@gmail.com>
Date: Fri, 16 Oct 2026 17:16:18 -0400
Subject: [PATCH 2/5] Narrow the repository to whole-draft calls and harden
 perf seeding

The interface keeps only exportAll and replaceAll; per-kind reads are
left to 3b, which settles the repository's naming. DraftRepository no
longer holds records between calls, only the per-book record of what
storage holds, so host memory matches main.

The storage-boundary violation report moves to its own module, shared
by the draft repository and project storage.

A packaged perf run seeds each tier with the app stopped, inside the
restart before its first open. A dev-core run seeds live, and every
view close first waits for any autosave an edit or Save started, so no
late save overwrites a seeded draft.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 AGENTS.md                                     |   2 +-
 e2e-tests/tests/perf/app-perf.spec.ts         |  60 +++++--
 perf/README.md                                |   3 +-
 perf/storage.ts                               |  10 +-
 .../services/draftRepository.test.ts          | 111 ++++---------
 src/services/draftRepository.ts               | 147 +++---------------
 src/services/projectStorage.ts                |  10 +-
 src/types/analysis-repository.ts              |  32 +---
 src/utils/analysis-violations.ts              |  28 ++++
 9 files changed, 138 insertions(+), 265 deletions(-)
 create mode 100644 src/utils/analysis-violations.ts

diff --git a/AGENTS.md b/AGENTS.md
index 090f080f1..ebdfc53bd 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -77,7 +77,7 @@ The WebView root component is assigned to `globalThis.webViewComponent` (not exp
 
 [src/services/projectStorage.ts](src/services/projectStorage.ts) — owns all `papi.storage` reads and writes for interlinearizer projects. Two serialization queues prevent interleaved read-modify-write races. Tests must call `resetQueuesForTesting()` between tests because module state is not cleared by `resetMocks`.
 
-Drafts are read and written through [AnalysisRepository](src/types/analysis-repository.ts), the seam a later storage backend replaces. [DraftRepository](src/services/draftRepository.ts) implements it in memory over the draft envelope and its per-book shards. It imports nothing from PAPI and reaches storage only through a `KeyValueStorage`, so the perf harness runs it in Node straight over the storage files ([perf/storage.ts](perf/storage.ts)).
+Drafts are read and written through [AnalysisRepository](src/types/analysis-repository.ts), the seam a later storage backend replaces. [DraftRepository](src/services/draftRepository.ts) implements it over the draft envelope and its per-book shards, rewriting only the books that changed. It imports nothing from PAPI and reaches storage only through a `KeyValueStorage`, so the perf harness runs it in Node straight over the storage files ([perf/storage.ts](perf/storage.ts)).
 
 ### Components
 
diff --git a/e2e-tests/tests/perf/app-perf.spec.ts b/e2e-tests/tests/perf/app-perf.spec.ts
index 9a80a8af2..ba31de5dc 100644
--- a/e2e-tests/tests/perf/app-perf.spec.ts
+++ b/e2e-tests/tests/perf/app-perf.spec.ts
@@ -60,11 +60,36 @@ function tokenGlossInputs(frame: Frame) {
   return frame.locator('input[aria-label^="Gloss for "]:not([aria-label^="Gloss for morpheme"])');
 }
 
+/**
+ * The view holding an edit or Save whose autosave has yet to be seen landing. Closing a view sends
+ * its pending autosave, which could then land after the next tier's seed and overwrite it.
+ */
+let unsavedFrame: Frame | undefined;
+
 /** Glosses the `index`th visible word and commits it, as a reader moving on with Tab does. */
 async function editGloss(frame: Frame, index: number, value: string): Promise<void> {
   const input = tokenGlossInputs(frame).nth(index);
   await input.fill(value);
   await input.press('Tab');
+  unsavedFrame = frame;
+}
+
+/** Waits for the view's autosave to land. */
+async function waitForAutosave(frame: Frame): Promise<Measure[]> {
+  const measures = await waitForMeasure(frame, 'autosave');
+  if (unsavedFrame === frame) unsavedFrame = undefined;
+  return measures;
+}
+
+/** Waits for any autosave an edit or Save started to land. */
+async function settleAutosave(): Promise<void> {
+  if (unsavedFrame) await waitForAutosave(unsavedFrame);
+}
+
+/** Closes the open view once any autosave it owes has landed, so none lands after a later seed. */
+async function closeSettledView(page: Page): Promise<void> {
+  await settleAutosave();
+  await closeView(page);
 }
 
 /** Picks `item` from the Project menu, starting over when a re-render closes the menu mid-click. */
@@ -90,13 +115,16 @@ async function enableMarks(page: Page): Promise<void> {
 }
 
 /**
- * Restarts the packaged app and points `app` at the new instance, with no view open.
+ * Restarts the packaged app and points `app` at the new instance, with no view open. `whileStopped`
+ * runs between the old instance exiting and the new one launching, outside the startup time.
  *
  * @returns Milliseconds until the new instance was ready.
  */
-async function restart(app: App): Promise<number> {
+async function restart(app: App, whileStopped?: () => Promise<void>): Promise<number> {
+  await settleAutosave();
   await app.browser?.close();
   await stopPackagedApp();
+  await whileStopped?.();
   const startupMs = await launchPackagedApp();
   Object.assign(app, await connect());
   // A view the layout restored would load before a timed open could.
@@ -107,7 +135,8 @@ async function restart(app: App): Promise<number> {
 
 /**
  * Stores the tier's draft and saved projects straight into the app's extension storage, adding each
- * project's id to `created` as it lands. The app sees the draft from its next load of it.
+ * project's id to `created` as it lands. A running app sees the draft from its next load of it, so
+ * no view may be open and no autosave in flight.
  */
 async function seedTier(
   projectId: string,
@@ -165,7 +194,7 @@ async function measureOpen(
     .forEach(({ duration }) => open.host.addValue('page-fetch', duration));
   const tokenizes = hostEntries.filter(({ name }) => name === 'getTokenizedBook:tokenize').length;
   if (tokenizes !== 1) console.warn(`Opening ${book} tokenized it ${tokenizes} times, not once`);
-  await closeView(page);
+  await closeSettledView(page);
 }
 
 /** The bytes a measure's detail records, when it records any. */
@@ -200,15 +229,17 @@ async function measureTier(
     return;
   }
 
-  await closeView(app.page);
-  await seedTier(projectId, tier, draftJson, createdProjects);
+  const seed = () => seedTier(projectId, tier, draftJson, createdProjects);
+  await closeSettledView(app.page);
+  // A packaged app restarts before its first open below, so it is seeded while stopped.
+  if (!PACKAGED_APP_PATH) await seed();
 
   // The first open after each app start.
   if (PACKAGED_APP_PATH) {
     const cold = scenarioSamples();
     for (let run = 0; run < RUNS; run += 1) {
       // eslint-disable-next-line no-await-in-loop
-      cold.webView.addValue('app-startup', await restart(app));
+      cold.webView.addValue('app-startup', await restart(app, run === 0 ? seed : undefined));
       // eslint-disable-next-line no-await-in-loop
       await measureOpen(app.page, projectId, tier.viewBook, cold);
     }
@@ -296,7 +327,7 @@ async function measureTier(
     // eslint-disable-next-line no-await-in-loop
     await waitForMeasure(frame, 'dispatch-render');
     // eslint-disable-next-line no-await-in-loop
-    const measures = await waitForMeasure(frame, 'autosave');
+    const measures = await waitForAutosave(frame);
     edits.webView.add(measures, ['dispatch-render', 'autosave-serialize', 'autosave']);
     // eslint-disable-next-line no-await-in-loop
     edits.addHostCall(HOST_CALLS.saveDraft, await takeHostEntries(page), measures);
@@ -310,7 +341,7 @@ async function measureTier(
     // eslint-disable-next-line no-await-in-loop
     await editGloss(frame, i % 20, `undo-${i}`);
   }
-  await waitForMeasure(frame, 'autosave');
+  await waitForAutosave(frame);
   await clearMeasures(frame);
   await recordMemory('withFullUndoHistory');
 
@@ -360,11 +391,12 @@ async function measureTier(
     await takeHostEntries(page);
     // eslint-disable-next-line no-await-in-loop
     await openProjectMenuItem(frame, /^Save(?! As)/);
+    unsavedFrame = frame;
     // eslint-disable-next-line no-await-in-loop
     const measures = await waitForMeasure(frame, 'save');
     // A save then persists the draft as clean, and that re-render would close the next run's menu.
     // eslint-disable-next-line no-await-in-loop
-    await waitForMeasure(frame, 'autosave');
+    await waitForAutosave(frame);
     saves.webView.add(measures, ['save']);
     const bytes = detailBytes(measures, 'save');
     if (bytes !== undefined) saves.webView.addValue('save-bytes', bytes);
@@ -379,7 +411,7 @@ async function measureTier(
   const concordance = new Samples();
   for (let run = 0; run < RUNS; run += 1) {
     // eslint-disable-next-line no-await-in-loop
-    await closeView(page);
+    await closeSettledView(page);
     // eslint-disable-next-line no-await-in-loop
     const { frame: view } = await openView(page, projectId, tier.viewBook);
     // eslint-disable-next-line no-await-in-loop
@@ -405,7 +437,7 @@ test('measure the app', async ({ mainPage }) => {
 
   const requested = (process.env.PERF_TIERS ?? '').split(',').filter(Boolean);
   const tiers = TIERS.filter((t) => requested.length === 0 || requested.includes(t.name));
-  await closeView(mainPage);
+  await closeSettledView(mainPage);
   await deleteLeftoverProjects(mainPage, projectId);
   const originalDraft = await readDraft(STORAGE_DIR, projectId);
   await enableMarks(mainPage);
@@ -423,7 +455,7 @@ test('measure the app', async ({ mainPage }) => {
         result.error = e instanceof Error ? e.message : String(e);
       } finally {
         // Each tier's picker lists only the projects that tier seeded.
-        await closeView(app.page);
+        await closeSettledView(app.page);
         await Promise.all(
           createdProjects
             .splice(0)
@@ -433,7 +465,7 @@ test('measure the app', async ({ mainPage }) => {
       console.log(`${tier.name}: ${JSON.stringify(result, undefined, 2)}`);
     }, Promise.resolve());
   } finally {
-    await closeView(app.page);
+    await closeSettledView(app.page);
     await app.page.evaluate((key) => localStorage.removeItem(key), PERF_MARKS_KEY);
     await setHostPerfMarks(app.page, false);
     await writeDraft(STORAGE_DIR, originalDraft);
diff --git a/perf/README.md b/perf/README.md
index b534626fd..a2f0426ce 100644
--- a/perf/README.md
+++ b/perf/README.md
@@ -27,7 +27,7 @@ A dataset is a tier name, or a `draft:<sourceProjectId>` or `project:<id>` key i
 
 - Global setup builds the extension for production (`E2E_BUILD_SCRIPT=build:production`).
 - The run gets empty extension storage, so listing projects reads only what the run seeds. Your own storage waits in `user-data.perf-backup` beside it and comes back on teardown.
-- Each tier's draft and saved projects are written into that storage from Node, through the extension's draft repository, so seeding needs no command that carries a whole draft.
+- Each tier's draft and saved projects are written into that storage from Node, through the extension's draft repository, so seeding needs no command that carries a whole draft. The run seeds only once the view is closed and its last autosave has landed.
 
 Quit Platform.Bible first. A perf run refuses to start while any instance holds its ports, since that app may own the storage a run sets aside.
 
@@ -49,6 +49,7 @@ Set `PERF_APP_PATH` to the packaged executable (`release/build/linux-unpacked/pl
 - Setup builds the extension for production.
 - The app runs with its home folder (`HOME`, and `USERPROFILE` on Windows) set to `perf/.cache/app-home`, so it installs WEB into its own profile and never touches yours.
 - Teardown asks it to quit.
+- Each tier is seeded while the app is stopped, inside the restart before its first open.
 - `perf:app` also times the first open after each app start, restarting the app before each run. A dev core gets the warm scenarios only.
 
 On Linux the app runs on X11 unless `PERF_OZONE_PLATFORM` names another backend, such as `wayland` when Xwayland is unavailable; results record it.
diff --git a/perf/storage.ts b/perf/storage.ts
index 65cacd4f6..00f1b9a33 100644
--- a/perf/storage.ts
+++ b/perf/storage.ts
@@ -45,9 +45,7 @@ export function fileStorage(dir: string): KeyValueStorage {
  * @throws If the stored draft was written by a newer build, or a stored record cannot be read.
  */
 export async function readDraft(dir: string, sourceProjectId: string): Promise<DraftProject> {
-  const repository = new DraftRepository(fileStorage(dir), sourceProjectId, console);
-  await repository.load();
-  return { ...(await repository.getScope()), analysis: await repository.exportAll() };
+  return new DraftRepository(fileStorage(dir), sourceProjectId, console).exportAll();
 }
 
 /**
@@ -57,11 +55,7 @@ export async function readDraft(dir: string, sourceProjectId: string): Promise<D
  * @throws If the stored draft was written by a newer build, or a record cannot be written.
  */
 export async function writeDraft(dir: string, draft: DraftProject): Promise<void> {
-  const { analysis, ...scope } = draft;
-  await new DraftRepository(fileStorage(dir), draft.sourceProjectId, console).replaceAll(
-    scope,
-    analysis,
-  );
+  await new DraftRepository(fileStorage(dir), draft.sourceProjectId, console).replaceAll(draft);
 }
 
 /**
diff --git a/src/__tests__/services/draftRepository.test.ts b/src/__tests__/services/draftRepository.test.ts
index e79efc3c5..913f50a96 100644
--- a/src/__tests__/services/draftRepository.test.ts
+++ b/src/__tests__/services/draftRepository.test.ts
@@ -1,13 +1,9 @@
 /// <reference types="jest" />
 
-import type { TextAnalysis } from 'interlinearizer';
-import type {
-  DraftScope,
-  KeyValueStorage,
-  RepositoryLogger,
-} from '../../types/analysis-repository';
+import type { DraftProject, TextAnalysis } from 'interlinearizer';
 import { DraftRepository } from '../../services/draftRepository';
 import { draftAnalysisKey, draftKey } from '../../services/storageKeys';
+import type { KeyValueStorage, RepositoryLogger } from '../../types/analysis-repository';
 import { emptyAnalysis, emptyDraft } from '../../types/empty-factories';
 import { CURRENT_MODEL_VERSION } from '../../types/model-version';
 import { FIXTURE_STAMPS, makePhraseLink } from '../test-helpers';
@@ -29,16 +25,6 @@ function memoryStorage(initial: Record<string, string> = {}) {
   return { storage, records, writes };
 }
 
-/** An empty draft's scope. */
-function scopeOf(sourceProjectId: string): DraftScope {
-  return {
-    sourceProjectId,
-    modelVersion: CURRENT_MODEL_VERSION,
-    analysisLanguages: [],
-    dirty: false,
-  };
-}
-
 function silentLogger(): RepositoryLogger & { warn: jest.Mock } {
   return { warn: jest.fn() };
 }
@@ -72,87 +58,48 @@ function twoBookAnalysis(): TextAnalysis {
   };
 }
 
+function twoBookDraft(): DraftProject {
+  return { ...emptyDraft('src'), analysisLanguages: ['en'], analysis: twoBookAnalysis() };
+}
+
 describe('DraftRepository', () => {
-  it('holds an empty draft for its source project before anything is loaded', async () => {
+  it('reads an empty draft for its source project when none is stored', async () => {
     const { storage } = memoryStorage();
-    const repository = new DraftRepository(storage, 'src', silentLogger());
 
-    await expect(repository.getScope()).resolves.toEqual(scopeOf('src'));
-    await expect(repository.exportAll()).resolves.toEqual(emptyAnalysis());
+    await expect(new DraftRepository(storage, 'src', silentLogger()).exportAll()).resolves.toEqual(
+      emptyDraft('src'),
+    );
   });
 
   it('reads back in a new instance what another wrote', async () => {
     const { storage } = memoryStorage();
-    const scope = { ...scopeOf('src'), analysisLanguages: ['en'] };
-    await new DraftRepository(storage, 'src', silentLogger()).replaceAll(scope, twoBookAnalysis());
-
-    const reader = new DraftRepository(storage, 'src', silentLogger());
-    await reader.load();
+    await new DraftRepository(storage, 'src', silentLogger()).replaceAll(twoBookDraft());
 
-    await expect(reader.getScope()).resolves.toEqual(scope);
-    await expect(reader.exportAll()).resolves.toEqual(twoBookAnalysis());
-  });
-
-  it('serves the payloads asked for by id, in request order, leaving out ids with none', async () => {
-    const { storage } = memoryStorage();
-    const repository = new DraftRepository(storage, 'src', silentLogger());
-    await repository.replaceAll(scopeOf('src'), twoBookAnalysis());
-    const [tokenAnalysis] = twoBookAnalysis().tokenAnalyses;
-    const [phraseAnalysis] = twoBookAnalysis().phraseAnalyses;
-    const [segmentAnalysis] = twoBookAnalysis().segmentAnalyses;
-
-    await expect(repository.getTokenAnalyses(['missing', 'ta-and'])).resolves.toEqual([
-      tokenAnalysis,
-    ]);
-    await expect(repository.getPhraseAnalyses(['pa-1'])).resolves.toEqual([phraseAnalysis]);
-    await expect(repository.getSegmentAnalyses(['sa-1', 'missing'])).resolves.toEqual([
-      segmentAnalysis,
-    ]);
+    await expect(new DraftRepository(storage, 'src', silentLogger()).exportAll()).resolves.toEqual(
+      twoBookDraft(),
+    );
   });
 
-  it('serves one copy of a payload every book it is linked from stores', async () => {
+  it('reads one copy of a payload every book linking it stores', async () => {
     const { storage, records } = memoryStorage();
-    await new DraftRepository(storage, 'src', silentLogger()).replaceAll(
-      scopeOf('src'),
-      twoBookAnalysis(),
-    );
+    await new DraftRepository(storage, 'src', silentLogger()).replaceAll(twoBookDraft());
     expect(records.get(draftAnalysisKey('src', 'EXO'))).toContain('ta-and');
     expect(records.get(draftAnalysisKey('src', 'GEN'))).toContain('ta-and');
 
-    const reader = new DraftRepository(storage, 'src', silentLogger());
-    await reader.load();
-
-    await expect(reader.getTokenAnalyses(['ta-and'])).resolves.toHaveLength(1);
-  });
-
-  it('serves payloads from what a load read, not what the instance held before', async () => {
-    const { storage } = memoryStorage();
-    const repository = new DraftRepository(storage, 'src', silentLogger());
-    await repository.replaceAll(scopeOf('src'), twoBookAnalysis());
-    await expect(repository.getTokenAnalyses(['ta-and'])).resolves.toHaveLength(1);
-    await new DraftRepository(storage, 'src', silentLogger()).replaceAll(
-      scopeOf('src'),
-      emptyAnalysis(),
-    );
+    const { analysis } = await new DraftRepository(storage, 'src', silentLogger()).exportAll();
 
-    await repository.load();
-
-    await expect(repository.getTokenAnalyses(['ta-and'])).resolves.toEqual([]);
+    expect(analysis.tokenAnalyses).toHaveLength(1);
   });
 
-  it('rewrites only the books whose records changed since the load', async () => {
+  it('rewrites only the books whose records changed since the read', async () => {
     const { storage, writes } = memoryStorage();
-    await new DraftRepository(storage, 'src', silentLogger()).replaceAll(
-      scopeOf('src'),
-      twoBookAnalysis(),
-    );
+    await new DraftRepository(storage, 'src', silentLogger()).replaceAll(twoBookDraft());
     const repository = new DraftRepository(storage, 'src', silentLogger());
-    await repository.load();
+    const draft = await repository.exportAll();
     writes.length = 0;
-    const edited = twoBookAnalysis();
-    edited.segmentAnalyses[0].freeTranslation = { en: 'And then.' };
+    draft.analysis.segmentAnalyses[0].freeTranslation = { en: 'And then.' };
 
-    await repository.replaceAll(scopeOf('src'), edited);
+    await repository.replaceAll(draft);
 
     expect(writes).toContain(draftAnalysisKey('src', 'EXO'));
     expect(writes).not.toContain(draftAnalysisKey('src', 'GEN'));
@@ -163,8 +110,8 @@ describe('DraftRepository', () => {
     const { storage, records, writes } = memoryStorage({ [draftKey('src')]: newer });
     const repository = new DraftRepository(storage, 'src', silentLogger());
 
-    await expect(repository.load()).rejects.toThrow(/newer than this build supports/);
-    await expect(repository.replaceAll(scopeOf('src'), twoBookAnalysis())).rejects.toThrow(
+    await expect(repository.exportAll()).rejects.toThrow(/newer than this build supports/);
+    await expect(repository.replaceAll(twoBookDraft())).rejects.toThrow(
       /newer than this build supports/,
     );
 
@@ -174,15 +121,11 @@ describe('DraftRepository', () => {
 
   it('reports a stored shard it cannot use to its logger', async () => {
     const { storage, records } = memoryStorage();
-    await new DraftRepository(storage, 'src', silentLogger()).replaceAll(
-      scopeOf('src'),
-      twoBookAnalysis(),
-    );
+    await new DraftRepository(storage, 'src', silentLogger()).replaceAll(twoBookDraft());
     records.set(draftAnalysisKey('src', 'GEN'), 'not json');
     const logger = silentLogger();
-    const repository = new DraftRepository(storage, 'src', logger);
 
-    await repository.load();
+    await new DraftRepository(storage, 'src', logger).exportAll();
 
     expect(logger.warn).toHaveBeenCalledWith(
       `Interlinearizer: analysis shard ${draftAnalysisKey('src', 'GEN')} is not valid JSON; treating as empty`,
diff --git a/src/services/draftRepository.ts b/src/services/draftRepository.ts
index 933281d77..9d46e44cb 100644
--- a/src/services/draftRepository.ts
+++ b/src/services/draftRepository.ts
@@ -1,10 +1,4 @@
-import type {
-  DraftProject,
-  PhraseAnalysis,
-  SegmentAnalysis,
-  TextAnalysis,
-  TokenAnalysis,
-} from 'interlinearizer';
+import type { DraftProject, TextAnalysis } from 'interlinearizer';
 import { emptyAnalysis, emptyDraft } from '../types/empty-factories';
 import { assertSupportedModelVersion, CURRENT_MODEL_VERSION } from '../types/model-version';
 import {
@@ -12,44 +6,17 @@ import {
   isDraftProject,
   isStringArray,
   isTextAnalysis,
-  validateTextAnalysis,
 } from '../types/type-guards';
 import { mergeAnalyses, splitAnalysisByBook } from '../utils/analysis-book';
+import { reportAnalysisViolations } from '../utils/analysis-violations';
 import { perfTime, perfTimeAsync, perfTimeAsyncExcluding } from '../utils/perf-marks';
 import type {
   AnalysisRepository,
-  DraftScope,
   KeyValueStorage,
   RepositoryLogger,
 } from '../types/analysis-repository';
 import { draftAnalysisKey, draftJournalKey, draftKey } from './storageKeys';
 
-/**
- * Logs how an analysis falls short as it crosses the storage boundary — an unreadable shape, or an
- * invariant its collections break — tagged with `description` to name the record and the point it
- * was checked at, e.g. `project abc on save`. Logging is the whole response: the read or the write
- * proceeds either way, since a record that disagrees with itself still renders, and refusing it
- * would cost the user their work over a fault they cannot act on.
- */
-export function reportAnalysisViolations(
-  logger: RepositoryLogger,
-  analysis: unknown,
-  description: string,
-): void {
-  // A stored record is typed but never validated, so its analysis may be absent or misshapen. Only
-  // absence is legitimate: a stored null is corruption.
-  if (analysis === undefined) return;
-  if (!isTextAnalysis(analysis)) {
-    logger.warn(`Interlinearizer: ${description} has a structurally invalid analysis`);
-    return;
-  }
-  validateTextAnalysis(analysis).forEach(({ kind, layer, count, sample }) => {
-    logger.warn(
-      `Interlinearizer: ${description} has ${count} ${layer}-layer ${kind} violation(s): ${sample.join(', ')}`,
-    );
-  });
-}
-
 /**
  * Awaits every operation, so a caller that rejects leaves none of them still in flight.
  *
@@ -126,37 +93,13 @@ type LoadedShard = {
   state: 'loaded' | 'unusable' | 'absent';
 };
 
-/** Payloads by id, first stored copy winning, for reads by id. */
-interface PayloadsById {
-  token: Map<string, TokenAnalysis>;
-  phrase: Map<string, PhraseAnalysis>;
-  segment: Map<string, SegmentAnalysis>;
-}
-
-/** Indexes payloads by id, keeping the first of any that share one. */
-function byId<T extends { id: string }>(payloads: readonly T[]): Map<string, T> {
-  const map = new Map<string, T>();
-  payloads.forEach((payload) => {
-    if (!map.has(payload.id)) map.set(payload.id, payload);
-  });
-  return map;
-}
-
-/** The stored payload for each id that has one, in request order. */
-function pick<T>(map: ReadonlyMap<string, T>, ids: readonly string[]): T[] {
-  return ids.flatMap((id) => {
-    const payload = map.get(id);
-    return payload === undefined ? [] : [payload];
-  });
-}
-
 /**
- * A source project's draft held in memory over its stored envelope and per-book analysis shards.
- * Writes rewrite only the shards whose content changed since this instance last read or wrote them,
- * and never overwrite a draft written by a newer build.
+ * A source project's draft over its stored envelope and per-book analysis shards. Writes rewrite
+ * only the shards whose content changed since this instance last read or wrote them, and never
+ * overwrite a draft written by a newer build.
  *
- * Not safe for overlapping calls: the caller serializes {@link load} and {@link replaceAll} on one
- * instance.
+ * Not safe for overlapping calls: the caller serializes {@link exportAll} and {@link replaceAll} on
+ * one instance.
  */
 export class DraftRepository implements AnalysisRepository {
   private readonly storage: KeyValueStorage;
@@ -165,12 +108,6 @@ export class DraftRepository implements AnalysisRepository {
 
   private readonly sourceProjectId: string;
 
-  private scope: DraftScope;
-
-  private analysis: TextAnalysis;
-
-  private payloadsById: PayloadsById | undefined;
-
   /**
    * The serialized shard last read or written per book code. An unknown book counts as changed, so
    * a lost entry costs a write, not correctness.
@@ -178,67 +115,39 @@ export class DraftRepository implements AnalysisRepository {
   private writtenShards = new Map<string, string>();
 
   /**
-   * Book codes whose shard the last load could not read. Such a book reaches the caller as empty,
-   * so a save holds its shard and manifest entry rather than taking it for wiped.
+   * Book codes whose shard the last read could not use. Such a book reaches the caller as empty, so
+   * a write holds its shard and manifest entry rather than taking it for wiped.
    */
   private unreadableShards = new Set<string>();
 
-  /** Starts as an empty draft; {@link load} reads what is stored. */
   constructor(storage: KeyValueStorage, sourceProjectId: string, logger: RepositoryLogger) {
     this.storage = storage;
     this.logger = logger;
     this.sourceProjectId = sourceProjectId;
-    const { analysis, ...scope } = emptyDraft(sourceProjectId);
-    this.scope = scope;
-    this.analysis = analysis;
   }
 
   /**
-   * Replaces what this instance holds with the stored draft. A draft that has never been written,
-   * fails validation, or belongs to a different source project loads as a fresh empty draft, and
-   * the invalid one is logged.
+   * Reads the stored draft. A draft that has never been written, fails validation, or belongs to a
+   * different source project reads as a fresh empty draft, and the invalid one is logged.
    *
    * A draft written by a newer build is refused rather than discarded, leaving it intact for the
    * build that can read it; {@link replaceAll} refuses to overwrite that same record.
    *
-   * A book whose shard is missing or unusable loads as empty, and {@link replaceAll} then leaves
+   * A book whose shard is missing or unusable reads as empty, and {@link replaceAll} then leaves
    * that shard and its manifest entry alone rather than treating the book as wiped, until a write
    * carries analyses for that book again. A shard holding a link with no id is unusable, and a
-   * draft storing its analysis inline with such a link loads as a fresh empty draft; either is
+   * draft storing its analysis inline with such a link reads as a fresh empty draft; either is
    * logged.
    *
    * A write interrupted before its envelope landed leaves shards the stored manifest does not name.
-   * A book first analyzed in that write still loads with its work rather than empty.
+   * A book first analyzed in that write still reads with its work rather than empty.
    *
    * @throws {SyntaxError} If the draft's stored value contains invalid JSON.
    * @throws {Error} If the stored draft's `modelVersion` is higher than this build's.
    * @throws If storage rejects a read.
    */
-  async load(): Promise<void> {
-    const { analysis, ...scope } = await this.readDraft();
-    this.scope = scope;
-    this.analysis = analysis;
-    this.payloadsById = undefined;
-  }
-
-  async getScope(): Promise<DraftScope> {
-    return { ...this.scope };
-  }
-
-  async getTokenAnalyses(ids: readonly string[]): Promise<TokenAnalysis[]> {
-    return pick(this.payloads().token, ids);
-  }
-
-  async getPhraseAnalyses(ids: readonly string[]): Promise<PhraseAnalysis[]> {
-    return pick(this.payloads().phrase, ids);
-  }
-
-  async getSegmentAnalyses(ids: readonly string[]): Promise<SegmentAnalysis[]> {
-    return pick(this.payloads().segment, ids);
-  }
-
-  async exportAll(): Promise<TextAnalysis> {
-    return { ...this.analysis };
+  async exportAll(): Promise<DraftProject> {
+    return this.readDraft();
   }
 
   /**
@@ -255,8 +164,7 @@ export class DraftRepository implements AnalysisRepository {
    * a restart. A book dropped from the analysis leaves no shard behind whether or not this instance
    * loaded the draft.
    *
-   * A write that fails leaves no storage call of its own in flight. What this instance holds takes
-   * the new draft once its envelope lands.
+   * A write that fails leaves no storage call of its own in flight.
    *
    * @throws {Error} If the stored draft was written by a newer build; nothing is written.
    * @throws If storage rejects a read while checking the stored draft; nothing is written.
@@ -264,8 +172,9 @@ export class DraftRepository implements AnalysisRepository {
    * @throws If deleting a wiped book's shard rejects; the shard stays journaled for a later write
    *   to retry.
    */
-  async replaceAll(scope: DraftScope, analysis: TextAnalysis): Promise<void> {
+  async replaceAll(draft: DraftProject): Promise<void> {
     const { sourceProjectId, storage, writtenShards: written, unreadableShards: unreadable } = this;
+    const { analysis } = draft;
     const storedBooks = await perfTimeAsync('saveDraft:read', () =>
       this.assertStoredDraftIsWritable(),
     );
@@ -311,7 +220,7 @@ export class DraftRepository implements AnalysisRepository {
     );
 
     const envelope: StoredDraft = {
-      ...scope,
+      ...draft,
       modelVersion: CURRENT_MODEL_VERSION,
       analysis: emptyAnalysis(),
       analysisBooks: [...byBook.keys(), ...held],
@@ -319,9 +228,6 @@ export class DraftRepository implements AnalysisRepository {
     await perfTimeAsync('saveDraft:write', () =>
       storage.write(draftKey(sourceProjectId), JSON.stringify(envelope)),
     );
-    this.scope = { ...scope, modelVersion: CURRENT_MODEL_VERSION };
-    this.analysis = analysis;
-    this.payloadsById = undefined;
 
     // A wiped book would otherwise leave its shard orphaned. Deleting only once the envelope has
     // stopped naming the book keeps a failure here from stranding the manifest on a missing shard.
@@ -362,18 +268,9 @@ export class DraftRepository implements AnalysisRepository {
     if (failed?.status === 'rejected') throw failed.reason;
   }
 
-  private payloads(): PayloadsById {
-    this.payloadsById ??= {
-      token: byId(this.analysis.tokenAnalyses),
-      phrase: byId(this.analysis.phraseAnalyses),
-      segment: byId(this.analysis.segmentAnalyses),
-    };
-    return this.payloadsById;
-  }
-
   /**
-   * Reads the stored draft as {@link load} describes, resetting the shard tally when the draft holds
-   * its analysis in shards.
+   * Reads the stored draft as {@link exportAll} describes, resetting the shard tally when the draft
+   * holds its analysis in shards.
    *
    * @throws {SyntaxError} If the draft's stored value contains invalid JSON.
    * @throws {Error} If the stored draft's `modelVersion` is higher than this build's.
diff --git a/src/services/projectStorage.ts b/src/services/projectStorage.ts
index fc014fbb8..89831a8ad 100644
--- a/src/services/projectStorage.ts
+++ b/src/services/projectStorage.ts
@@ -11,7 +11,8 @@ import { assertSupportedModelVersion, CURRENT_MODEL_VERSION } from '../types/mod
 import { hasLinkWithoutId, isStringArray } from '../types/type-guards';
 import { perfTime, perfTimeAsync, perfTimeAsyncExcluding } from '../utils/perf-marks';
 import type { KeyValueStorage } from '../types/analysis-repository';
-import { DraftRepository, reportAnalysisViolations } from './draftRepository';
+import { reportAnalysisViolations } from '../utils/analysis-violations';
+import { DraftRepository } from './draftRepository';
 import { draftKey, projectKey } from './storageKeys';
 
 const PROJECT_IDS_KEY = 'projectIds';
@@ -874,9 +875,7 @@ export async function getDraft(
   sourceProjectId: string,
 ): Promise<DraftProject> {
   return enqueueSerialized(draftQueues, sourceProjectId, async () => {
-    const repository = draftRepositoryFor(token, sourceProjectId);
-    await repository.load();
-    return { ...(await repository.getScope()), analysis: await repository.exportAll() };
+    return draftRepositoryFor(token, sourceProjectId).exportAll();
   });
 }
 
@@ -913,8 +912,7 @@ export async function saveDraft(
 ): Promise<void> {
   // Invariant violations go unreported here: this runs on every edit, so one would log per keystroke.
   await enqueueSerialized(draftQueues, sourceProjectId, async () => {
-    const { analysis, ...scope } = draft;
-    await draftRepositoryFor(token, sourceProjectId).replaceAll(scope, analysis);
+    await draftRepositoryFor(token, sourceProjectId).replaceAll(draft);
   });
 }
 
diff --git a/src/types/analysis-repository.ts b/src/types/analysis-repository.ts
index b23b63fa4..02e160580 100644
--- a/src/types/analysis-repository.ts
+++ b/src/types/analysis-repository.ts
@@ -1,10 +1,4 @@
-import type {
-  DraftProject,
-  PhraseAnalysis,
-  SegmentAnalysis,
-  TextAnalysis,
-  TokenAnalysis,
-} from 'interlinearizer';
+import type { DraftProject } from 'interlinearizer';
 
 /**
  * Text records by key: the platform's per-extension user data in the extension host, or files in
@@ -23,33 +17,19 @@ export interface RepositoryLogger {
   warn(message: string, ...details: unknown[]): void;
 }
 
-/** A source project's draft apart from its analysis: what the records it holds belong to. */
-export type DraftScope = Omit<DraftProject, 'analysis'>;
-
 /**
- * Reads and writes one draft's analysis records. Every call is async and takes and returns only
+ * Reads and writes one source project's draft. Every call is async and takes and returns only
  * JSON-plain values, so an implementation may sit behind a network boundary or another language.
  */
 export interface AnalysisRepository {
-  getScope(): Promise<DraftScope>;
-
-  /** @returns One payload per requested id that is stored; ids with none are left out. */
-  getTokenAnalyses(ids: readonly string[]): Promise<TokenAnalysis[]>;
-
-  /** @returns One payload per requested id that is stored; ids with none are left out. */
-  getPhraseAnalyses(ids: readonly string[]): Promise<PhraseAnalysis[]>;
-
-  /** @returns One payload per requested id that is stored; ids with none are left out. */
-  getSegmentAnalyses(ids: readonly string[]): Promise<SegmentAnalysis[]>;
-
-  /** Every record, for callers that still exchange the whole draft. */
-  exportAll(): Promise<TextAnalysis>;
+  /** The whole stored draft, for callers that still exchange it whole. */
+  exportAll(): Promise<DraftProject>;
 
   /**
-   * Replaces the scope and every record, for callers that still exchange the whole draft.
+   * Replaces the stored draft whole, for callers that still exchange it whole.
    *
    * @throws {Error} If the stored draft was written by a newer build; nothing is written.
    * @throws If storage rejects a read or a write.
    */
-  replaceAll(scope: DraftScope, analysis: TextAnalysis): Promise<void>;
+  replaceAll(draft: DraftProject): Promise<void>;
 }
diff --git a/src/utils/analysis-violations.ts b/src/utils/analysis-violations.ts
new file mode 100644
index 000000000..fc74b1856
--- /dev/null
+++ b/src/utils/analysis-violations.ts
@@ -0,0 +1,28 @@
+import { isTextAnalysis, validateTextAnalysis } from '../types/type-guards';
+import type { RepositoryLogger } from '../types/analysis-repository';
+
+/**
+ * Logs how an analysis falls short as it crosses the storage boundary — an unreadable shape, or an
+ * invariant its collections break — tagged with `description` to name the record and the point it
+ * was checked at, e.g. `project abc on save`. Logging is the whole response: the read or the write
+ * proceeds either way, since a record that disagrees with itself still renders, and refusing it
+ * would cost the user their work over a fault they cannot act on.
+ */
+export function reportAnalysisViolations(
+  logger: RepositoryLogger,
+  analysis: unknown,
+  description: string,
+): void {
+  // A stored record is typed but never validated, so its analysis may be absent or misshapen. Only
+  // absence is legitimate: a stored null is corruption.
+  if (analysis === undefined) return;
+  if (!isTextAnalysis(analysis)) {
+    logger.warn(`Interlinearizer: ${description} has a structurally invalid analysis`);
+    return;
+  }
+  validateTextAnalysis(analysis).forEach(({ kind, layer, count, sample }) => {
+    logger.warn(
+      `Interlinearizer: ${description} has ${count} ${layer}-layer ${kind} violation(s): ${sample.join(', ')}`,
+    );
+  });
+}

From 0366b38d60aadb14e8c6b92de1084664914997dd Mon Sep 17 00:00:00 2001
From: Danny Rorabaugh <imnasnainaec@gmail.com>
Date: Fri, 16 Oct 2026 17:41:35 -0400
Subject: [PATCH 3/5] Tighten repository docs, terms and import order

Use load and save for draft operations throughout the repository,
keeping read and write for single storage calls. Rename the shard
record to shardContents and the logger type to WarningLogger, which
serve more than the repository. Shorten the moved doc prose, fold the
restart parameter note into its summary, and fix the perf README's
difference count and AGENTS.md's description of the seam.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 AGENTS.md                                     |   2 +-
 e2e-tests/global-setup-perf.ts                |  16 +-
 e2e-tests/perf-app.ts                         |   4 +-
 e2e-tests/tests/perf/app-perf.spec.ts         |   7 +-
 perf/README.md                                |   3 +-
 perf/storage.ts                               |   5 +-
 .../services/draftRepository.test.ts          |  12 +-
 src/services/draftRepository.ts               | 186 +++++++++---------
 src/services/projectStorage.ts                |   4 +-
 src/types/analysis-repository.ts              |   8 +-
 src/utils/analysis-violations.ts              |  15 +-
 11 files changed, 129 insertions(+), 133 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index ebdfc53bd..4685ffb84 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -77,7 +77,7 @@ The WebView root component is assigned to `globalThis.webViewComponent` (not exp
 
 [src/services/projectStorage.ts](src/services/projectStorage.ts) — owns all `papi.storage` reads and writes for interlinearizer projects. Two serialization queues prevent interleaved read-modify-write races. Tests must call `resetQueuesForTesting()` between tests because module state is not cleared by `resetMocks`.
 
-Drafts are read and written through [AnalysisRepository](src/types/analysis-repository.ts), the seam a later storage backend replaces. [DraftRepository](src/services/draftRepository.ts) implements it over the draft envelope and its per-book shards, rewriting only the books that changed. It imports nothing from PAPI and reaches storage only through a `KeyValueStorage`, so the perf harness runs it in Node straight over the storage files ([perf/storage.ts](perf/storage.ts)).
+Drafts are loaded and saved through [AnalysisRepository](src/types/analysis-repository.ts), the seam a later storage backend implements. [DraftRepository](src/services/draftRepository.ts) implements it over the draft envelope and its per-book shards, and rewrites only the books that changed. It imports nothing from PAPI and reaches storage only through a `KeyValueStorage`. That lets the perf harness run it in Node, straight over the storage files ([perf/storage.ts](perf/storage.ts)).
 
 ### Components
 
diff --git a/e2e-tests/global-setup-perf.ts b/e2e-tests/global-setup-perf.ts
index 79aa8a39f..76e8efd9f 100644
--- a/e2e-tests/global-setup-perf.ts
+++ b/e2e-tests/global-setup-perf.ts
@@ -1,21 +1,21 @@
 import type { FullConfig } from '@playwright/test';
+import { execSync } from 'child_process';
 import fs from 'fs';
 import path from 'path';
-import { execSync } from 'child_process';
+import { DEV_STORAGE_DIR } from '../perf/paths';
 import globalSetupCdp, { CDP_PORT } from './global-setup-cdp';
 import { isPortInUse, WEBSOCKET_PORT } from './global-setup';
 import globalTeardownCdp from './global-teardown-cdp';
-import { DEV_STORAGE_DIR as STORAGE_DIR } from '../perf/paths';
 import { launchPackagedApp, PACKAGED_APP_PATH, stopPackagedApp } from './perf-app';
 
 /** Where the developer's storage waits out a run. */
-const STORAGE_BACKUP_DIR = `${STORAGE_DIR}.perf-backup`;
+const STORAGE_BACKUP_DIR = `${DEV_STORAGE_DIR}.perf-backup`;
 
 /** Puts back storage a run set aside, discarding what the run stored. */
 function restoreStorage(): void {
   if (!fs.existsSync(STORAGE_BACKUP_DIR)) return;
-  fs.rmSync(STORAGE_DIR, { recursive: true, force: true });
-  fs.renameSync(STORAGE_BACKUP_DIR, STORAGE_DIR);
+  fs.rmSync(DEV_STORAGE_DIR, { recursive: true, force: true });
+  fs.renameSync(STORAGE_BACKUP_DIR, DEV_STORAGE_DIR);
 }
 
 /**
@@ -41,10 +41,10 @@ export default async function globalSetupPerf(config: FullConfig): Promise<() =>
   }
   // A crashed run leaves its backup in place; put it back before setting storage aside again.
   restoreStorage();
-  fs.mkdirSync(STORAGE_DIR, { recursive: true });
-  fs.renameSync(STORAGE_DIR, STORAGE_BACKUP_DIR);
+  fs.mkdirSync(DEV_STORAGE_DIR, { recursive: true });
+  fs.renameSync(DEV_STORAGE_DIR, STORAGE_BACKUP_DIR);
   try {
-    fs.mkdirSync(STORAGE_DIR);
+    fs.mkdirSync(DEV_STORAGE_DIR);
     await globalSetupCdp(config);
   } catch (error) {
     restoreStorage();
diff --git a/e2e-tests/perf-app.ts b/e2e-tests/perf-app.ts
index 579056eca..32a74779e 100644
--- a/e2e-tests/perf-app.ts
+++ b/e2e-tests/perf-app.ts
@@ -4,9 +4,9 @@ import fs from 'fs';
 import os from 'os';
 import path from 'path';
 import { CACHE_DIR, DEV_STORAGE_DIR } from '../perf/paths';
-import { CDP_PORT, waitForRendererSettled } from './global-setup-cdp';
-import { isPortInUse, waitForPort, WEBSOCKET_PORT } from './global-setup';
 import { E2E_SETTINGS_OVERRIDES } from './fixtures/helpers';
+import { isPortInUse, waitForPort, WEBSOCKET_PORT } from './global-setup';
+import { CDP_PORT, waitForRendererSettled } from './global-setup-cdp';
 import { killProcessTree, waitForPidExit } from './process-utils';
 
 /** Path to a packaged app's executable; set, it is what the harness launches. */
diff --git a/e2e-tests/tests/perf/app-perf.spec.ts b/e2e-tests/tests/perf/app-perf.spec.ts
index ba31de5dc..a0d4c4aec 100644
--- a/e2e-tests/tests/perf/app-perf.spec.ts
+++ b/e2e-tests/tests/perf/app-perf.spec.ts
@@ -74,7 +74,7 @@ async function editGloss(frame: Frame, index: number, value: string): Promise<vo
   unsavedFrame = frame;
 }
 
-/** Waits for the view's autosave to land. */
+/** Waits for the view's autosave to land, and stops counting the view as unsaved. */
 async function waitForAutosave(frame: Frame): Promise<Measure[]> {
   const measures = await waitForMeasure(frame, 'autosave');
   if (unsavedFrame === frame) unsavedFrame = undefined;
@@ -115,8 +115,9 @@ async function enableMarks(page: Page): Promise<void> {
 }
 
 /**
- * Restarts the packaged app and points `app` at the new instance, with no view open. `whileStopped`
- * runs between the old instance exiting and the new one launching, outside the startup time.
+ * Restarts the packaged app and points `app` at the new instance, with no view open. Runs
+ * `whileStopped` between the old instance exiting and the new one launching, outside the startup
+ * time.
  *
  * @returns Milliseconds until the new instance was ready.
  */
diff --git a/perf/README.md b/perf/README.md
index a2f0426ce..b8f55a337 100644
--- a/perf/README.md
+++ b/perf/README.md
@@ -27,7 +27,8 @@ A dataset is a tier name, or a `draft:<sourceProjectId>` or `project:<id>` key i
 
 - Global setup builds the extension for production (`E2E_BUILD_SCRIPT=build:production`).
 - The run gets empty extension storage, so listing projects reads only what the run seeds. Your own storage waits in `user-data.perf-backup` beside it and comes back on teardown.
-- Each tier's draft and saved projects are written into that storage from Node, through the extension's draft repository, so seeding needs no command that carries a whole draft. The run seeds only once the view is closed and its last autosave has landed.
+
+The run writes each tier's draft and saved projects straight into the app's extension storage from Node. It goes through the extension's draft repository, so seeding needs no command that carries a whole draft. A dev core keeps running meanwhile, so the run seeds only once the view has closed and its last autosave has landed.
 
 Quit Platform.Bible first. A perf run refuses to start while any instance holds its ports, since that app may own the storage a run sets aside.
 
diff --git a/perf/storage.ts b/perf/storage.ts
index 00f1b9a33..36c0a1e37 100644
--- a/perf/storage.ts
+++ b/perf/storage.ts
@@ -2,10 +2,11 @@ import { randomUUID } from 'crypto';
 import fs from 'fs/promises';
 import type { DraftProject, InterlinearProject } from 'interlinearizer';
 import path from 'path';
-import type { KeyValueStorage } from '../src/types/analysis-repository';
 import { DraftRepository } from '../src/services/draftRepository';
 import { projectKey } from '../src/services/storageKeys';
+import type { KeyValueStorage } from '../src/types/analysis-repository';
 import { CURRENT_MODEL_VERSION } from '../src/types/model-version';
+import { isStringArray } from '../src/types/type-guards';
 
 /** Key of the index listing every saved project's id. */
 const PROJECT_IDS_KEY = 'projectIds';
@@ -84,7 +85,7 @@ export async function addSavedProject(
   };
   await storage.write(projectKey(project.id), JSON.stringify(project));
   const index: unknown = JSON.parse((await storage.read(PROJECT_IDS_KEY)) ?? '[]');
-  if (!Array.isArray(index)) throw new Error(`${PROJECT_IDS_KEY} is not an array of ids`);
+  if (!isStringArray(index)) throw new Error(`${PROJECT_IDS_KEY} is not an array of ids`);
   await storage.write(PROJECT_IDS_KEY, JSON.stringify([...index, project.id]));
   return project.id;
 }
diff --git a/src/__tests__/services/draftRepository.test.ts b/src/__tests__/services/draftRepository.test.ts
index 913f50a96..db3af459a 100644
--- a/src/__tests__/services/draftRepository.test.ts
+++ b/src/__tests__/services/draftRepository.test.ts
@@ -3,7 +3,7 @@
 import type { DraftProject, TextAnalysis } from 'interlinearizer';
 import { DraftRepository } from '../../services/draftRepository';
 import { draftAnalysisKey, draftKey } from '../../services/storageKeys';
-import type { KeyValueStorage, RepositoryLogger } from '../../types/analysis-repository';
+import type { KeyValueStorage, WarningLogger } from '../../types/analysis-repository';
 import { emptyAnalysis, emptyDraft } from '../../types/empty-factories';
 import { CURRENT_MODEL_VERSION } from '../../types/model-version';
 import { FIXTURE_STAMPS, makePhraseLink } from '../test-helpers';
@@ -25,7 +25,7 @@ function memoryStorage(initial: Record<string, string> = {}) {
   return { storage, records, writes };
 }
 
-function silentLogger(): RepositoryLogger & { warn: jest.Mock } {
+function silentLogger(): WarningLogger & { warn: jest.Mock } {
   return { warn: jest.fn() };
 }
 
@@ -63,7 +63,7 @@ function twoBookDraft(): DraftProject {
 }
 
 describe('DraftRepository', () => {
-  it('reads an empty draft for its source project when none is stored', async () => {
+  it('loads an empty draft for its source project when none is stored', async () => {
     const { storage } = memoryStorage();
 
     await expect(new DraftRepository(storage, 'src', silentLogger()).exportAll()).resolves.toEqual(
@@ -71,7 +71,7 @@ describe('DraftRepository', () => {
     );
   });
 
-  it('reads back in a new instance what another wrote', async () => {
+  it('loads in a new instance what another saved', async () => {
     const { storage } = memoryStorage();
     await new DraftRepository(storage, 'src', silentLogger()).replaceAll(twoBookDraft());
 
@@ -80,7 +80,7 @@ describe('DraftRepository', () => {
     );
   });
 
-  it('reads one copy of a payload every book linking it stores', async () => {
+  it('loads a payload shared by several books once', async () => {
     const { storage, records } = memoryStorage();
     await new DraftRepository(storage, 'src', silentLogger()).replaceAll(twoBookDraft());
     expect(records.get(draftAnalysisKey('src', 'EXO'))).toContain('ta-and');
@@ -91,7 +91,7 @@ describe('DraftRepository', () => {
     expect(analysis.tokenAnalyses).toHaveLength(1);
   });
 
-  it('rewrites only the books whose records changed since the read', async () => {
+  it('rewrites only the books whose records changed since the load', async () => {
     const { storage, writes } = memoryStorage();
     await new DraftRepository(storage, 'src', silentLogger()).replaceAll(twoBookDraft());
     const repository = new DraftRepository(storage, 'src', silentLogger());
diff --git a/src/services/draftRepository.ts b/src/services/draftRepository.ts
index 9d46e44cb..f2835a171 100644
--- a/src/services/draftRepository.ts
+++ b/src/services/draftRepository.ts
@@ -1,4 +1,9 @@
 import type { DraftProject, TextAnalysis } from 'interlinearizer';
+import type {
+  AnalysisRepository,
+  KeyValueStorage,
+  WarningLogger,
+} from '../types/analysis-repository';
 import { emptyAnalysis, emptyDraft } from '../types/empty-factories';
 import { assertSupportedModelVersion, CURRENT_MODEL_VERSION } from '../types/model-version';
 import {
@@ -10,11 +15,6 @@ import {
 import { mergeAnalyses, splitAnalysisByBook } from '../utils/analysis-book';
 import { reportAnalysisViolations } from '../utils/analysis-violations';
 import { perfTime, perfTimeAsync, perfTimeAsyncExcluding } from '../utils/perf-marks';
-import type {
-  AnalysisRepository,
-  KeyValueStorage,
-  RepositoryLogger,
-} from '../types/analysis-repository';
 import { draftAnalysisKey, draftJournalKey, draftKey } from './storageKeys';
 
 /**
@@ -29,20 +29,18 @@ async function settleAll(operations: readonly Promise<unknown>[]): Promise<void>
 }
 
 /**
- * Names the shards a save is about to strand if it is interrupted, so the next run can find them
- * without the in-memory tally. Storage cannot enumerate keys, so a shard the manifest does not name
- * is otherwise unreachable once this process is gone.
+ * Names the shards an interrupted save could strand, so a later process can still find them.
+ * Storage cannot enumerate keys, so a shard the manifest does not name is otherwise unreachable.
  */
 interface ShardJournal {
   /**
-   * Books whose shard this save wrote, pending the envelope write that names them. A load reads
-   * these, recovering work an interrupted save would otherwise strand.
+   * Books whose shard this save wrote before the envelope came to name them. A load reads these,
+   * recovering work an interrupted save would otherwise strand.
    */
   adding: string[];
   /**
-   * Books whose shard is orphaned pending deletion, already dropped from the envelope. A load must
-   * not read these, or the wipe that recorded them would undo itself; they await a retried
-   * deletion.
+   * Books whose orphaned shard awaits deletion, already dropped from the envelope. A load must not
+   * read these, or the wipe that recorded them would undo itself.
    */
   removing: string[];
 }
@@ -63,7 +61,7 @@ function isShardJournal(value: unknown): value is ShardJournal {
   );
 }
 
-/** A draft as persisted: the in-memory draft with an always-empty `analysis`, held in shards. */
+/** A draft as stored: its `analysis` always empty, with the analysis itself held in shards. */
 type StoredDraft = DraftProject & {
   /**
    * Book codes of the shards holding this draft's analysis. Storage cannot enumerate keys, so
@@ -87,60 +85,59 @@ type LoadedShard = {
   /** Empty when the shard could not be read, standing in for content this build cannot recover. */
   analysis: TextAnalysis;
   /**
-   * Whether the shard was read, and failing that, whether it still occupies storage — which is what
-   * decides whether anything is left to keep reachable.
+   * Whether the shard was read. If not, whether it still occupies storage, which decides whether
+   * anything is left to keep reachable.
    */
   state: 'loaded' | 'unusable' | 'absent';
 };
 
 /**
- * A source project's draft over its stored envelope and per-book analysis shards. Writes rewrite
- * only the shards whose content changed since this instance last read or wrote them, and never
- * overwrite a draft written by a newer build.
+ * A source project's draft, stored as an envelope plus one analysis shard per book. A save rewrites
+ * only the shards whose content changed since this instance last loaded or saved them. Nothing
+ * overwrites a draft written by a newer build.
  *
- * Not safe for overlapping calls: the caller serializes {@link exportAll} and {@link replaceAll} on
- * one instance.
+ * Calls on one instance must not overlap.
  */
 export class DraftRepository implements AnalysisRepository {
   private readonly storage: KeyValueStorage;
 
-  private readonly logger: RepositoryLogger;
+  private readonly logger: WarningLogger;
 
   private readonly sourceProjectId: string;
 
   /**
-   * The serialized shard last read or written per book code. An unknown book counts as changed, so
-   * a lost entry costs a write, not correctness.
+   * Each book's shard as last loaded or saved, serialized. A book missing here counts as changed,
+   * so a lost entry costs a write, not correctness.
    */
-  private writtenShards = new Map<string, string>();
+  private shardContents = new Map<string, string>();
 
   /**
-   * Book codes whose shard the last read could not use. Such a book reaches the caller as empty, so
-   * a write holds its shard and manifest entry rather than taking it for wiped.
+   * Books whose shard the last load could not use. Such a book reaches the caller as empty. A save
+   * keeps its shard and manifest entry rather than taking the book for wiped.
    */
   private unreadableShards = new Set<string>();
 
-  constructor(storage: KeyValueStorage, sourceProjectId: string, logger: RepositoryLogger) {
+  constructor(storage: KeyValueStorage, sourceProjectId: string, logger: WarningLogger) {
     this.storage = storage;
     this.logger = logger;
     this.sourceProjectId = sourceProjectId;
   }
 
   /**
-   * Reads the stored draft. A draft that has never been written, fails validation, or belongs to a
-   * different source project reads as a fresh empty draft, and the invalid one is logged.
+   * Loads the stored draft. A draft never saved loads as a fresh empty one. So does a draft that
+   * fails validation or belongs to another source project, and it is logged.
+   *
+   * A draft written by a newer build is refused, not discarded, so the build that can read it still
+   * finds it. {@link replaceAll} refuses to overwrite it too.
    *
-   * A draft written by a newer build is refused rather than discarded, leaving it intact for the
-   * build that can read it; {@link replaceAll} refuses to overwrite that same record.
+   * A book whose shard is missing or unusable loads as empty. {@link replaceAll} then keeps that
+   * shard and its manifest entry until a save carries analyses for the book again.
    *
-   * A book whose shard is missing or unusable reads as empty, and {@link replaceAll} then leaves
-   * that shard and its manifest entry alone rather than treating the book as wiped, until a write
-   * carries analyses for that book again. A shard holding a link with no id is unusable, and a
-   * draft storing its analysis inline with such a link reads as a fresh empty draft; either is
-   * logged.
+   * A shard holding a link with no id is unusable. A draft holding such a link inline loads as a
+   * fresh empty draft. Both are logged.
    *
-   * A write interrupted before its envelope landed leaves shards the stored manifest does not name.
-   * A book first analyzed in that write still reads with its work rather than empty.
+   * A save interrupted before its envelope landed leaves shards the manifest does not name. A book
+   * first analyzed in that save still loads with its work.
    *
    * @throws {SyntaxError} If the draft's stored value contains invalid JSON.
    * @throws {Error} If the stored draft's `modelVersion` is higher than this build's.
@@ -151,41 +148,39 @@ export class DraftRepository implements AnalysisRepository {
   }
 
   /**
-   * Writes the draft, replacing the stored one whole apart from the {@link CURRENT_MODEL_VERSION}
-   * stamp. A draft written by a newer build is the exception: it is left as it stands.
+   * Saves the draft, replacing the stored one whole apart from the {@link CURRENT_MODEL_VERSION}
+   * stamp. A draft written by a newer build is left as it stands.
    *
-   * The analysis spans several records and no storage transaction spans them, so an interrupted
-   * write can leave books from two writes. It never leaves a book listed whose shard is gone. What
-   * did reach storage is tallied as it lands, so the write that follows a failed one rewrites only
-   * the books still missing it.
+   * No storage transaction spans the shards, so an interrupted save can leave books from two saves.
+   * It never leaves a listed book without its shard. Each shard counts as saved once it lands, so
+   * the save after a failed one rewrites only the books still missing.
    *
-   * Recovery does not depend on this process staying up: a shard the envelope never came to name is
-   * still found on the next load, and a deletion that fails is retried by a later write even across
-   * a restart. A book dropped from the analysis leaves no shard behind whether or not this instance
-   * loaded the draft.
+   * Recovery survives a restart. The next load finds a shard the envelope never came to name, and a
+   * later save retries a failed deletion. A book dropped from the analysis leaves no shard behind,
+   * whether or not this instance loaded the draft.
    *
-   * A write that fails leaves no storage call of its own in flight.
+   * A save that fails leaves no storage call of its own in flight.
    *
    * @throws {Error} If the stored draft was written by a newer build; nothing is written.
    * @throws If storage rejects a read while checking the stored draft; nothing is written.
    * @throws If storage rejects a write.
-   * @throws If deleting a wiped book's shard rejects; the shard stays journaled for a later write
-   *   to retry.
+   * @throws If deleting a wiped book's shard rejects; the shard stays journaled for a later save to
+   *   retry.
    */
   async replaceAll(draft: DraftProject): Promise<void> {
-    const { sourceProjectId, storage, writtenShards: written, unreadableShards: unreadable } = this;
+    const { sourceProjectId, storage, shardContents: saved, unreadableShards: unreadable } = this;
     const { analysis } = draft;
     const storedBooks = await perfTimeAsync('saveDraft:read', () =>
       this.assertStoredDraftIsWritable(),
     );
     const byBook = perfTime('saveDraft:compare', () => splitAnalysisByBook(analysis));
 
-    // Books this write no longer carries, less those held back because the load could not read
-    // them. A write whose draft was never loaded here has only the stored manifest or the journal
-    // to name earlier shards. A journaled addition whose shard never landed deletes as a no-op.
+    // Books this save no longer carries, less those held back because the load could not read them.
+    // Without a load here, only the stored manifest and the journal name earlier shards. A
+    // journaled addition whose shard never landed deletes as a no-op.
     const journaled = await perfTimeAsync('saveDraft:read', () => this.readShardJournal());
     const knownShards = new Set([
-      ...written.keys(),
+      ...saved.keys(),
       ...storedBooks,
       ...journaled.adding,
       ...journaled.removing,
@@ -195,8 +190,8 @@ export class DraftRepository implements AnalysisRepository {
     );
     const held = [...unreadable].filter((bookCode) => !byBook.has(bookCode));
 
-    // Name every shard this write could strand before writing any of it. A book the stored manifest
-    // already names needs no entry: it survives an interruption by that manifest alone.
+    // Journal every shard this save could strand before writing any. A book the stored manifest
+    // already names needs no entry: the manifest alone keeps it reachable.
     const stranded = [...byBook.keys()].filter((bookCode) => !storedBooks.includes(bookCode));
     await perfTimeAsync('saveDraft:write', () =>
       this.writeShardJournal({ adding: stranded, removing: wiped }),
@@ -205,15 +200,15 @@ export class DraftRepository implements AnalysisRepository {
     const shards = perfTime('saveDraft:compare', () =>
       [...byBook].map(([bookCode, partition]) => {
         const json = JSON.stringify(partition);
-        return { bookCode, json, changed: written.get(bookCode) !== json };
+        return { bookCode, json, changed: saved.get(bookCode) !== json };
       }),
     );
     await perfTimeAsync('saveDraft:write', () =>
       settleAll(
         shards.map(async ({ bookCode, json, changed }) => {
           if (changed) await storage.write(draftAnalysisKey(sourceProjectId, bookCode), json);
-          written.set(bookCode, json);
-          // This write restored the book, so a later wipe must be free to delete its shard.
+          saved.set(bookCode, json);
+          // This save restored the book, so a later wipe may delete its shard.
           unreadable.delete(bookCode);
         }),
       ),
@@ -229,8 +224,8 @@ export class DraftRepository implements AnalysisRepository {
       storage.write(draftKey(sourceProjectId), JSON.stringify(envelope)),
     );
 
-    // A wiped book would otherwise leave its shard orphaned. Deleting only once the envelope has
-    // stopped naming the book keeps a failure here from stranding the manifest on a missing shard.
+    // A wiped book's shard would otherwise be orphaned. Deleting it only after the envelope stops
+    // naming the book means a failure here never leaves the manifest naming a missing shard.
     const undeleted: string[] = [];
     const deletions = await perfTimeAsync('saveDraft:write', () =>
       Promise.allSettled(
@@ -238,20 +233,20 @@ export class DraftRepository implements AnalysisRepository {
           try {
             await storage.delete(draftAnalysisKey(sourceProjectId, bookCode));
           } catch (e) {
-            // Kept in the journal so a later write retries the deletion even across a restart.
+            // Kept in the journal, so a later save retries the deletion even across a restart.
             undeleted.push(bookCode);
             throw e;
           }
-          // Dropped only once the shard is gone, so a later write in this process retries a failed
+          // Dropped only once the shard is gone, so a later save in this process retries a failed
           // deletion.
-          written.delete(bookCode);
+          saved.delete(bookCode);
         }),
       ),
     );
 
-    // With the envelope naming every shard this write added, only a failed deletion is still owed.
-    // A failure to record that yields to the shard error, which is the one worth surfacing; the
-    // next write retries the journal either way.
+    // With the envelope naming every shard this save added, only a failed deletion is still owed.
+    // If recording it fails too, the shard error wins: it is the one worth surfacing, and the next
+    // save retries the journal either way.
     const failed = deletions.find((outcome) => outcome.status === 'rejected');
     try {
       await perfTimeAsync('saveDraft:write', () =>
@@ -269,8 +264,8 @@ export class DraftRepository implements AnalysisRepository {
   }
 
   /**
-   * Reads the stored draft as {@link exportAll} describes, resetting the shard tally when the draft
-   * holds its analysis in shards.
+   * Loads the stored draft as {@link exportAll} describes. Loading a sharded draft also resets the
+   * shard contents and unreadable books this instance keeps.
    *
    * @throws {SyntaxError} If the draft's stored value contains invalid JSON.
    * @throws {Error} If the stored draft's `modelVersion` is higher than this build's.
@@ -281,8 +276,8 @@ export class DraftRepository implements AnalysisRepository {
     const raw = await perfTimeAsync('getDraft:read', () => storage.read(draftKey(sourceProjectId)));
     if (raw === undefined) return emptyDraft(sourceProjectId);
     const parsed: unknown = perfTime('getDraft:parse', () => JSON.parse(raw));
-    // Refuse a newer build's draft before validating it: a later shape need not satisfy this
-    // build's guard, and failing validation is what resets the draft to empty.
+    // Refuse a newer build's draft before validating it. A later shape need not pass this build's
+    // guard, and failing validation is what resets the draft to empty.
     assertSupportedModelVersion(parsed, `draft for source project ${sourceProjectId}`);
     if (
       !!parsed &&
@@ -309,8 +304,8 @@ export class DraftRepository implements AnalysisRepository {
       return draft;
     }
     const keyOf = (bookCode: string) => draftAnalysisKey(sourceProjectId, bookCode);
-    // A write interrupted before its envelope landed leaves shards this manifest never came to
-    // name. A journaled book whose shard never landed reads as missing and drops back out below.
+    // A save interrupted before its envelope landed leaves shards this manifest never came to name.
+    // A journaled book whose shard never landed reads as missing and drops back out below.
     const { booksToRead, orphaned, shards } = await perfTimeAsyncExcluding(
       'getDraft:read',
       'getDraft:parse',
@@ -332,15 +327,15 @@ export class DraftRepository implements AnalysisRepository {
         };
       },
     );
-    // Record what each shard holds so the next write can tell which books actually changed. An
-    // unusable shard's empty stand-in is not what is on disk, so it is recorded apart. A journaled
-    // book is dropped only when its shard is gone: dropping one still in storage would strand it,
-    // with neither the manifest nor the journal left to name it.
+    // Record what each shard holds, so the next save can tell which books changed. An unusable
+    // shard's empty stand-in is not what storage holds, so it is recorded apart. A journaled book is
+    // dropped only once its shard is gone. Dropping one still in storage would strand it, with
+    // neither the manifest nor the journal naming it.
     const loadedByBook = booksToRead
       .map((bookCode, i) => ({ bookCode, ...shards[i] }))
       .filter(({ bookCode, state }) => state !== 'absent' || !orphaned.includes(bookCode));
     perfTime('getDraft:compare', () => {
-      this.writtenShards = new Map(
+      this.shardContents = new Map(
         loadedByBook
           .filter(({ state }) => state === 'loaded')
           .map(({ bookCode, analysis }) => [bookCode, JSON.stringify(analysis)]),
@@ -359,9 +354,8 @@ export class DraftRepository implements AnalysisRepository {
   }
 
   /**
-   * Parses one book's analysis shard as read from `key`, treating a missing or unusable one as
-   * empty so a single lost book does not fail the whole load. A shard holding a link with no id is
-   * unusable.
+   * Parses one book's shard as read from `key`. A missing or unusable shard is treated as empty, so
+   * one lost book does not fail the whole load. A shard holding a link with no id is unusable.
    */
   private parseAnalysisShard(raw: string | undefined, key: string): LoadedShard {
     if (raw === undefined) return { analysis: emptyAnalysis(), state: 'absent' };
@@ -389,14 +383,13 @@ export class DraftRepository implements AnalysisRepository {
   }
 
   /**
-   * Guards an otherwise blind draft write against clobbering a record this build cannot read. The
-   * draft in hand is not evidence about what is on disk: a caller that could not read the stored
-   * draft holds an empty one stamped with this revision, and writing that would land on the very
-   * record the refused read protected.
+   * Guards an otherwise blind save against clobbering a draft this build cannot read. The draft in
+   * hand says nothing about storage. A caller whose load was refused holds an empty draft stamped
+   * with this revision, and saving it would overwrite the very record the refusal protected.
    *
-   * A draft that is absent or unparseable carries no stamp to refuse, so the write proceeds and
-   * replaces it. A read that fails for any other reason cannot rule out the very record this guard
-   * protects: a refused write costs a retry, where an overwritten record is gone for good.
+   * An absent or unparseable draft carries no stamp to refuse, so the save replaces it. A read that
+   * fails for any other reason cannot rule that record out. A refused save costs a retry; an
+   * overwritten record is gone for good.
    *
    * @returns The book codes the stored draft's manifest names, empty when there is no readable
    *   manifest to name them.
@@ -419,10 +412,9 @@ export class DraftRepository implements AnalysisRepository {
   }
 
   /**
-   * Reads the shard journal, recovering a missing, unparseable, or malformed one as empty. A
-   * journal is a recovery hint rather than a record of truth: every book it names is cross-checked
-   * against storage before it is acted on, so losing one costs an orphaned shard, never
-   * correctness.
+   * Reads the shard journal. A missing, unparseable or malformed journal recovers as empty. It is a
+   * recovery hint, not a record of truth: every book it names is checked against storage before
+   * anything acts on it. Losing one costs an orphaned shard, never correctness.
    *
    * @throws If storage rejects the read.
    */
@@ -445,8 +437,8 @@ export class DraftRepository implements AnalysisRepository {
   }
 
   /**
-   * Writes the shard journal, deleting the record instead when it names nothing, so a settled draft
-   * leaves no journal behind.
+   * Writes the shard journal, or deletes it when it names nothing, so a settled draft leaves none
+   * behind.
    *
    * @throws If storage rejects the write or the deletion.
    */
diff --git a/src/services/projectStorage.ts b/src/services/projectStorage.ts
index 89831a8ad..305800a13 100644
--- a/src/services/projectStorage.ts
+++ b/src/services/projectStorage.ts
@@ -6,12 +6,12 @@ import type {
   SegmentationDelta,
   TextAnalysis,
 } from 'interlinearizer';
+import type { KeyValueStorage } from '../types/analysis-repository';
 import { emptyAnalysis } from '../types/empty-factories';
 import { assertSupportedModelVersion, CURRENT_MODEL_VERSION } from '../types/model-version';
 import { hasLinkWithoutId, isStringArray } from '../types/type-guards';
-import { perfTime, perfTimeAsync, perfTimeAsyncExcluding } from '../utils/perf-marks';
-import type { KeyValueStorage } from '../types/analysis-repository';
 import { reportAnalysisViolations } from '../utils/analysis-violations';
+import { perfTime, perfTimeAsync, perfTimeAsyncExcluding } from '../utils/perf-marks';
 import { DraftRepository } from './draftRepository';
 import { draftKey, projectKey } from './storageKeys';
 
diff --git a/src/types/analysis-repository.ts b/src/types/analysis-repository.ts
index 02e160580..b528fd1ad 100644
--- a/src/types/analysis-repository.ts
+++ b/src/types/analysis-repository.ts
@@ -12,8 +12,8 @@ export interface KeyValueStorage {
   delete(key: string): Promise<void>;
 }
 
-/** Where a repository reports records it could not use as stored. */
-export interface RepositoryLogger {
+/** Where warnings about stored records go. */
+export interface WarningLogger {
   warn(message: string, ...details: unknown[]): void;
 }
 
@@ -22,11 +22,11 @@ export interface RepositoryLogger {
  * JSON-plain values, so an implementation may sit behind a network boundary or another language.
  */
 export interface AnalysisRepository {
-  /** The whole stored draft, for callers that still exchange it whole. */
+  /** Loads the whole stored draft. */
   exportAll(): Promise<DraftProject>;
 
   /**
-   * Replaces the stored draft whole, for callers that still exchange it whole.
+   * Saves the whole draft, replacing the stored one.
    *
    * @throws {Error} If the stored draft was written by a newer build; nothing is written.
    * @throws If storage rejects a read or a write.
diff --git a/src/utils/analysis-violations.ts b/src/utils/analysis-violations.ts
index fc74b1856..d51da0019 100644
--- a/src/utils/analysis-violations.ts
+++ b/src/utils/analysis-violations.ts
@@ -1,15 +1,16 @@
+import type { WarningLogger } from '../types/analysis-repository';
 import { isTextAnalysis, validateTextAnalysis } from '../types/type-guards';
-import type { RepositoryLogger } from '../types/analysis-repository';
 
 /**
- * Logs how an analysis falls short as it crosses the storage boundary — an unreadable shape, or an
- * invariant its collections break — tagged with `description` to name the record and the point it
- * was checked at, e.g. `project abc on save`. Logging is the whole response: the read or the write
- * proceeds either way, since a record that disagrees with itself still renders, and refusing it
- * would cost the user their work over a fault they cannot act on.
+ * Logs, tagged with `description`, how an analysis falls short at the storage boundary: an
+ * unreadable shape, or an invariant its collections break. The tag names the record and where it
+ * was checked, e.g. `project abc on save`.
+ *
+ * Logging is the whole response, and the load or save proceeds. A record that disagrees with itself
+ * still renders, and refusing it would cost the user work over a fault they cannot act on.
  */
 export function reportAnalysisViolations(
-  logger: RepositoryLogger,
+  logger: WarningLogger,
   analysis: unknown,
   description: string,
 ): void {

From d2841240cf3f2e54979225ed88936ce9d86e3735 Mon Sep 17 00:00:00 2001
From: Danny Rorabaugh <imnasnainaec@gmail.com>
Date: Mon, 19 Oct 2026 10:11:04 -0400
Subject: [PATCH 4/5] Address review: repository docs and boundary tests

Document exportAll's throws on the seam, state KeyValueStorage's
contract alone, and give read and delete the same doc form. Correct the
claim that a dropped book never leaves a shard: one the load could not
use is held.

Split the newer-build test into its load and save refusals, and test
isStringArray and reportAnalysisViolations directly.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../services/draftRepository.test.ts          | 17 ++--
 src/__tests__/types/type-guards.test.ts       | 19 ++++
 .../utils/analysis-violations.test.ts         | 89 +++++++++++++++++++
 src/services/draftRepository.ts               |  3 +-
 src/types/analysis-repository.ts              | 15 ++--
 5 files changed, 131 insertions(+), 12 deletions(-)
 create mode 100644 src/__tests__/utils/analysis-violations.test.ts

diff --git a/src/__tests__/services/draftRepository.test.ts b/src/__tests__/services/draftRepository.test.ts
index db3af459a..fbe1eaf35 100644
--- a/src/__tests__/services/draftRepository.test.ts
+++ b/src/__tests__/services/draftRepository.test.ts
@@ -105,15 +105,22 @@ describe('DraftRepository', () => {
     expect(writes).not.toContain(draftAnalysisKey('src', 'GEN'));
   });
 
-  it('leaves a draft written by a newer build as it stands', async () => {
+  it('refuses to load a draft written by a newer build', async () => {
     const newer = JSON.stringify({ ...emptyDraft('src'), modelVersion: CURRENT_MODEL_VERSION + 1 });
-    const { storage, records, writes } = memoryStorage({ [draftKey('src')]: newer });
-    const repository = new DraftRepository(storage, 'src', silentLogger());
+    const { storage } = memoryStorage({ [draftKey('src')]: newer });
 
-    await expect(repository.exportAll()).rejects.toThrow(/newer than this build supports/);
-    await expect(repository.replaceAll(twoBookDraft())).rejects.toThrow(
+    await expect(new DraftRepository(storage, 'src', silentLogger()).exportAll()).rejects.toThrow(
       /newer than this build supports/,
     );
+  });
+
+  it('leaves a draft written by a newer build as it stands', async () => {
+    const newer = JSON.stringify({ ...emptyDraft('src'), modelVersion: CURRENT_MODEL_VERSION + 1 });
+    const { storage, records, writes } = memoryStorage({ [draftKey('src')]: newer });
+
+    await expect(
+      new DraftRepository(storage, 'src', silentLogger()).replaceAll(twoBookDraft()),
+    ).rejects.toThrow(/newer than this build supports/);
 
     expect(writes).toEqual([]);
     expect(records.get(draftKey('src'))).toBe(newer);
diff --git a/src/__tests__/types/type-guards.test.ts b/src/__tests__/types/type-guards.test.ts
index 3f680a4f4..3e22e0d48 100644
--- a/src/__tests__/types/type-guards.test.ts
+++ b/src/__tests__/types/type-guards.test.ts
@@ -4,6 +4,7 @@ import { emptyAnalysis } from '../../types/empty-factories';
 import {
   hasLinkWithoutId,
   isPt9ImportProvenance,
+  isStringArray,
   isTextAnalysis,
   validateTextAnalysis,
 } from '../../types/type-guards';
@@ -533,3 +534,21 @@ describe('isPt9ImportProvenance', () => {
     expect(isPt9ImportProvenance('pt9')).toBe(false);
   });
 });
+
+describe('isStringArray', () => {
+  it('accepts an array of strings', () => {
+    expect(isStringArray(['GEN', 'EXO'])).toBe(true);
+  });
+
+  it('accepts an empty array', () => {
+    expect(isStringArray([])).toBe(true);
+  });
+
+  it('rejects an array holding a non-string', () => {
+    expect(isStringArray(['GEN', 1])).toBe(false);
+  });
+
+  it('rejects a non-array', () => {
+    expect(isStringArray('GEN')).toBe(false);
+  });
+});
diff --git a/src/__tests__/utils/analysis-violations.test.ts b/src/__tests__/utils/analysis-violations.test.ts
new file mode 100644
index 000000000..ca63095c9
--- /dev/null
+++ b/src/__tests__/utils/analysis-violations.test.ts
@@ -0,0 +1,89 @@
+/// <reference types="jest" />
+
+import type { TextAnalysis, TokenAnalysisLink } from 'interlinearizer';
+import type { WarningLogger } from '../../types/analysis-repository';
+import { emptyAnalysis } from '../../types/empty-factories';
+import { reportAnalysisViolations } from '../../utils/analysis-violations';
+import { FIXTURE_STAMPS } from '../test-helpers';
+
+function silentLogger(): WarningLogger & { warn: jest.Mock } {
+  return { warn: jest.fn() };
+}
+
+function linkTo(analysisId: string, tokenRef: string, id = `tl-${tokenRef}`): TokenAnalysisLink {
+  return {
+    id,
+    analysisId,
+    ...FIXTURE_STAMPS,
+    status: 'approved',
+    token: { tokenRef, surfaceText: 'word' },
+  };
+}
+
+function analysisWithLinks(tokenAnalysisLinks: TokenAnalysisLink[]): TextAnalysis {
+  return {
+    ...emptyAnalysis(),
+    tokenAnalyses: [{ id: 'ta-1', ...FIXTURE_STAMPS, surfaceText: 'word', gloss: { en: 'word' } }],
+    tokenAnalysisLinks,
+  };
+}
+
+describe('reportAnalysisViolations', () => {
+  it('reports nothing for an absent analysis', () => {
+    const logger = silentLogger();
+
+    reportAnalysisViolations(logger, undefined, 'project abc on load');
+
+    expect(logger.warn).not.toHaveBeenCalled();
+  });
+
+  it('reports a null analysis as structurally invalid', () => {
+    const logger = silentLogger();
+
+    // eslint-disable-next-line no-null/no-null -- the corrupt stored shape under test
+    reportAnalysisViolations(logger, null, 'project abc on load');
+
+    expect(logger.warn).toHaveBeenCalledWith(
+      'Interlinearizer: project abc on load has a structurally invalid analysis',
+    );
+  });
+
+  it('reports a misshapen analysis once, without checking its invariants', () => {
+    const logger = silentLogger();
+
+    reportAnalysisViolations(logger, { tokenAnalysisLinks: 'GEN' }, 'project abc on load');
+
+    expect(logger.warn.mock.calls).toEqual([
+      ['Interlinearizer: project abc on load has a structurally invalid analysis'],
+    ]);
+  });
+
+  it('reports nothing for an analysis whose collections agree', () => {
+    const logger = silentLogger();
+
+    reportAnalysisViolations(logger, analysisWithLinks([linkTo('ta-1', 'GEN 1:1:0')]), 'x');
+
+    expect(logger.warn).not.toHaveBeenCalled();
+  });
+
+  it('reports each violation kind once, with its count and a sample', () => {
+    const logger = silentLogger();
+    const analysis = analysisWithLinks([
+      linkTo('ta-missing', 'GEN 1:1:0'),
+      linkTo('ta-missing', 'GEN 1:1:4'),
+      linkTo('ta-1', 'GEN 1:1:8', 'tl-same'),
+      linkTo('ta-1', 'GEN 1:1:12', 'tl-same'),
+    ]);
+
+    reportAnalysisViolations(logger, analysis, 'project abc on save');
+
+    expect(logger.warn.mock.calls).toEqual([
+      [
+        'Interlinearizer: project abc on save has 2 token-layer danglingLink violation(s): GEN 1:1:0, GEN 1:1:4',
+      ],
+      [
+        'Interlinearizer: project abc on save has 1 token-layer duplicateLinkId violation(s): tl-same',
+      ],
+    ]);
+  });
+});
diff --git a/src/services/draftRepository.ts b/src/services/draftRepository.ts
index f2835a171..0d46e8b86 100644
--- a/src/services/draftRepository.ts
+++ b/src/services/draftRepository.ts
@@ -157,7 +157,8 @@ export class DraftRepository implements AnalysisRepository {
    *
    * Recovery survives a restart. The next load finds a shard the envelope never came to name, and a
    * later save retries a failed deletion. A book dropped from the analysis leaves no shard behind,
-   * whether or not this instance loaded the draft.
+   * whether or not this instance loaded the draft, unless that load could not use the book's
+   * shard.
    *
    * A save that fails leaves no storage call of its own in flight.
    *
diff --git a/src/types/analysis-repository.ts b/src/types/analysis-repository.ts
index b528fd1ad..9eccfc9e2 100644
--- a/src/types/analysis-repository.ts
+++ b/src/types/analysis-repository.ts
@@ -1,11 +1,8 @@
 import type { DraftProject } from 'interlinearizer';
 
-/**
- * Text records by key: the platform's per-extension user data in the extension host, or files in
- * the same layout in Node.
- */
+/** Text records by key. */
 export interface KeyValueStorage {
-  /** @returns `undefined` when nothing is stored at `key`. */
+  /** Resolves `undefined` when nothing is stored at `key`. */
   read(key: string): Promise<string | undefined>;
   write(key: string, data: string): Promise<void>;
   /** Succeeds as well when nothing is stored at `key`. */
@@ -22,7 +19,13 @@ export interface WarningLogger {
  * JSON-plain values, so an implementation may sit behind a network boundary or another language.
  */
 export interface AnalysisRepository {
-  /** Loads the whole stored draft. */
+  /**
+   * Loads the whole stored draft.
+   *
+   * @throws {SyntaxError} If the stored draft contains invalid JSON.
+   * @throws {Error} If the stored draft was written by a newer build.
+   * @throws If storage rejects a read.
+   */
   exportAll(): Promise<DraftProject>;
 
   /**

From 170aa7a6b751473c711632ed019bad3fc357c4e9 Mon Sep 17 00:00:00 2001
From: Danny Rorabaugh <imnasnainaec@gmail.com>
Date: Mon, 19 Oct 2026 12:08:53 -0400
Subject: [PATCH 5/5] Narrow exportAll's SyntaxError to the draft's stored
 value

A shard holding invalid JSON loads its book as empty rather than
throwing, so the seam's @throws names only the draft's own record.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 src/types/analysis-repository.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/types/analysis-repository.ts b/src/types/analysis-repository.ts
index 9eccfc9e2..85b5bf8d6 100644
--- a/src/types/analysis-repository.ts
+++ b/src/types/analysis-repository.ts
@@ -22,7 +22,7 @@ export interface AnalysisRepository {
   /**
    * Loads the whole stored draft.
    *
-   * @throws {SyntaxError} If the stored draft contains invalid JSON.
+   * @throws {SyntaxError} If the draft's stored value contains invalid JSON.
    * @throws {Error} If the stored draft was written by a newer build.
    * @throws If storage rejects a read.
    */