From d7d34dbec20e0ae8b4f1cfce1c34a646079f06a2 Mon Sep 17 00:00:00 2001
From: Alex Rawlings <alex.rawlings@wycliffe.ca>
Date: Thu, 22 Oct 2026 09:32:30 -0600
Subject: [PATCH 01/22] Add host sessions with read-only PT9 imports (#440)

---
 AGENTS.md                                     |   8 +-
 __mocks__/papi-backend.ts                     |   5 +
 .../analysis-repository-conformance.ts        |  88 ++++
 src/__tests__/main.test.ts                    | 159 ++++++-
 .../services/analysisSessions.parity.test.ts  |  45 ++
 .../services/analysisSessions.test.ts         | 434 ++++++++++++++++++
 .../draftRepository.conformance.test.ts       |  25 +-
 src/__tests__/services/projectStorage.test.ts | 129 ++++++
 .../services/pt9ImportRepository.test.ts      | 115 +++++
 .../types/read-only-analysis-error.test.ts    |  13 +
 src/__tests__/utils/free-translations.test.ts |  44 ++
 src/components/InterlinearizerLoader.tsx      |  10 +-
 src/main.ts                                   | 127 +++++
 src/services/analysisSessions.ts              | 245 ++++++++++
 src/services/draftRepository.ts               |   3 +
 src/services/projectStorage.ts                |  64 ++-
 src/services/pt9ImportRepository.ts           |  88 ++++
 src/types/analysis-repository.ts              |  21 +-
 src/types/interlinearizer.d.ts                |  30 ++
 src/types/read-only-analysis-error.ts         |   7 +
 src/utils/free-translations.ts                |   7 +
 21 files changed, 1643 insertions(+), 24 deletions(-)
 create mode 100644 src/__tests__/services/analysisSessions.parity.test.ts
 create mode 100644 src/__tests__/services/analysisSessions.test.ts
 create mode 100644 src/__tests__/services/pt9ImportRepository.test.ts
 create mode 100644 src/__tests__/types/read-only-analysis-error.test.ts
 create mode 100644 src/__tests__/utils/free-translations.test.ts
 create mode 100644 src/services/analysisSessions.ts
 create mode 100644 src/services/pt9ImportRepository.ts
 create mode 100644 src/types/read-only-analysis-error.ts
 create mode 100644 src/utils/free-translations.ts

diff --git a/AGENTS.md b/AGENTS.md
index fd1197177..12823d9a8 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -77,12 +77,16 @@ 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 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)).
+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)). [Pt9ImportRepository](src/services/pt9ImportRepository.ts) serves a Paratext 9 import through the same seam, read-only.
 
-[The conformance suite](src/__tests__/analysis-repository-conformance.ts) defines the seam: every `AnalysisRepository` implementation must pass it, and [draftRepository.conformance.test.ts](src/__tests__/services/draftRepository.conformance.test.ts) runs it against `DraftRepository`. A behavior every implementation owes goes in the suite; one particular to an implementation, such as which shards a save rewrites, goes in that implementation's own tests. A later backend runs the suite by passing `describeAnalysisRepositoryConformance` a factory that returns a fresh `ConformanceStore` for each test.
+[The conformance suite](src/__tests__/analysis-repository-conformance.ts) defines the seam: every `AnalysisRepository` implementation must pass it, and [draftRepository.conformance.test.ts](src/__tests__/services/draftRepository.conformance.test.ts) runs it against `DraftRepository` and `Pt9ImportRepository`. A behavior every implementation owes goes in the suite; one particular to an implementation, such as which shards a save rewrites, goes in that implementation's own tests. A later backend runs the suite by passing `describeAnalysisRepositoryConformance` a factory that returns a fresh `ConformanceStore` for each test.
 
 Saved projects are listed through [ProjectSummaries](src/services/projectSummaries.ts): one record holding every project's summary, rewritten on each project write so listing reads no analysis. Like `DraftRepository`, it is PAPI-free.
 
+### Sessions
+
+[AnalysisSessions](src/services/analysisSessions.ts) keeps the host's sessions, behind the `openSession`, `closeSession` and `setAnalysisLanguage` commands. A session is a handle on one source project's draft, paired with the interlinear project it saves to, or on a Paratext 9 import alone, read-only. A source has at most one session: opening another closes it. Each session runs its commands one at a time, through `run`, or `runEdit` for a command that changes stored analysis, which a read-only session refuses. The WebView doesn't use sessions yet.
+
 ### 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/__mocks__/papi-backend.ts b/__mocks__/papi-backend.ts
index 30fddb30c..0335bfb25 100644
--- a/__mocks__/papi-backend.ts
+++ b/__mocks__/papi-backend.ts
@@ -19,6 +19,7 @@ const mockNotificationsSend = jest.fn();
 const mockProjectDataProvidersGet = jest.fn();
 const mockGetLocalizedString = jest.fn();
 const mockCreateNetworkEventEmitterAsync = jest.fn();
+const mockSettingsGet = jest.fn();
 const mockLogger = {
   debug: jest.fn(),
   error: jest.fn(),
@@ -36,6 +37,9 @@ const papi = {
   projectSettings: {
     registerValidator: mockRegisterValidator,
   },
+  settings: {
+    get: mockSettingsGet,
+  },
   notifications: {
     send: mockNotificationsSend,
   },
@@ -87,6 +91,7 @@ const defaultExport = {
   __mockProjectDataProvidersGet: mockProjectDataProvidersGet,
   __mockGetLocalizedString: mockGetLocalizedString,
   __mockCreateNetworkEventEmitterAsync: mockCreateNetworkEventEmitterAsync,
+  __mockSettingsGet: mockSettingsGet,
   __mockLogger: mockLogger,
 };
 
diff --git a/src/__tests__/analysis-repository-conformance.ts b/src/__tests__/analysis-repository-conformance.ts
index d708b5ee3..ca12e8f5b 100644
--- a/src/__tests__/analysis-repository-conformance.ts
+++ b/src/__tests__/analysis-repository-conformance.ts
@@ -4,6 +4,7 @@ import type { DraftProject, TextAnalysis } from 'interlinearizer';
 import type { AnalysisRepository, DraftExport } from '../types/analysis-repository';
 import { emptyAnalysis, emptyDraft } from '../types/empty-factories';
 import { CURRENT_MODEL_VERSION } from '../types/model-version';
+import { ReadOnlyAnalysisError } from '../types/read-only-analysis-error';
 import { FIXTURE_STAMPS, makePhraseLink } from './test-helpers';
 
 /** One empty store an {@link AnalysisRepository} implementation keeps drafts in. */
@@ -38,6 +39,12 @@ export interface ConformanceStore {
 
   /** Whether storage holds anything for `sourceProjectId` that its stored draft no longer needs. */
   holdsLeftovers(sourceProjectId: string): Promise<boolean>;
+
+  /**
+   * Stores `draft`'s analysis where only a read-only repository reaches it, as for a Paratext 9
+   * import of `draft`'s source project, and opens that repository.
+   */
+  openReadOnly(draft: DraftProject): Promise<AnalysisRepository>;
 }
 
 const SOURCE = 'source-project';
@@ -681,5 +688,86 @@ export function describeAnalysisRepositoryConformance(
         await expect((await store.open(SOURCE)).exportForCopy()).rejects.toThrow();
       });
     });
+
+    describe('capabilities', () => {
+      it("lets a source project's draft be written", async () => {
+        expect((await store.open(SOURCE)).capabilities.readOnly).toBe(false);
+      });
+
+      it('marks a read-only repository as read-only', async () => {
+        expect((await store.openReadOnly(fullDraft())).capabilities.readOnly).toBe(true);
+      });
+    });
+
+    describe('a read-only repository', () => {
+      /** The analysis `repository` loads, with its record lists in id order. */
+      async function analysisOf(repository: AnalysisRepository): Promise<TextAnalysis> {
+        return (await load(repository)).analysis;
+      }
+
+      it('loads the analysis it was opened over', async () => {
+        const repository = await store.openReadOnly(fullDraft());
+
+        await expect(analysisOf(repository)).resolves.toStrictEqual(
+          inIdOrder(fullDraft()).analysis,
+        );
+      });
+
+      it('loads JSON-plain values', async () => {
+        expectJsonPlain(await (await store.openReadOnly(fullDraft())).exportAll());
+      });
+
+      it('returns a draft the caller may change without changing what is stored', async () => {
+        const repository = await store.openReadOnly(fullDraft());
+
+        const { draft: loaded } = await repository.exportAll();
+        loaded.analysis.tokenAnalyses[0].surfaceText = 'changed';
+
+        await expect(analysisOf(repository)).resolves.toStrictEqual(
+          inIdOrder(fullDraft()).analysis,
+        );
+      });
+
+      it('refuses a save, leaving what it loads unchanged', async () => {
+        const repository = await store.openReadOnly(fullDraft());
+
+        await expect(repository.replaceAll(exodusOnlyDraft())).rejects.toThrow(
+          ReadOnlyAnalysisError,
+        );
+
+        await expect(analysisOf(repository)).resolves.toStrictEqual(
+          inIdOrder(fullDraft()).analysis,
+        );
+      });
+
+      it('loads for copying what it loads', async () => {
+        const repository = await store.openReadOnly(fullDraft());
+
+        const { draft, unreadableBooks } = await repository.exportForCopy();
+
+        expect(unreadableBooks).toStrictEqual([]);
+        expect(inIdOrder(draft).analysis).toStrictEqual(inIdOrder(fullDraft()).analysis);
+      });
+
+      it('refuses to be marked clean', async () => {
+        const repository = await store.openReadOnly(fullDraft());
+
+        await expect(repository.markClean()).rejects.toThrow(ReadOnlyAnalysisError);
+      });
+
+      it("keeps apart from the source project's draft", async () => {
+        await (await store.open(SOURCE)).replaceAll(exodusOnlyDraft());
+
+        const repository = await store.openReadOnly(fullDraft());
+        await (await store.open(SOURCE)).replaceAll({ ...exodusOnlyDraft(), dirty: true });
+
+        await expect(analysisOf(repository)).resolves.toStrictEqual(
+          inIdOrder(fullDraft()).analysis,
+        );
+        await expect(reload(store)).resolves.toStrictEqual(
+          inIdOrder({ ...exodusOnlyDraft(), dirty: true }),
+        );
+      });
+    });
   });
 }
diff --git a/src/__tests__/main.test.ts b/src/__tests__/main.test.ts
index bb3730fe2..ca39346ab 100644
--- a/src/__tests__/main.test.ts
+++ b/src/__tests__/main.test.ts
@@ -4,12 +4,12 @@ import type { OpenWebViewOptions, SavedWebViewDefinition, WebViewDefinition } fr
 import papiBackendMock from '@papi/backend';
 import { activate, deactivate } from '@main';
 import type { InterlinearizerOpenOptions } from '@main';
-import type { ProjectConfig } from 'interlinearizer';
+import type { DraftProject, ProjectConfig } from 'interlinearizer';
 import * as bookService from '../services/bookService';
 import * as hostPerf from '../services/hostPerf';
 import * as projectStorage from '../services/projectStorage';
 import * as pt9ImportService from '../services/pt9ImportService';
-import { UnreadableBooksError } from '../types/analysis-repository';
+import { type AnalysisRepository, UnreadableBooksError } from '../types/analysis-repository';
 import { emptyDraft } from '../types/empty-factories';
 import { toProjectSummary } from '../types/interlinear-project-summary';
 import { createTestActivationContext, makeStubProject } from './test-helpers';
@@ -36,6 +36,7 @@ interface PapiBackendTestMock {
   __mockProjectDataProvidersGet: jest.Mock;
   __mockGetLocalizedString: jest.Mock;
   __mockCreateNetworkEventEmitterAsync: jest.Mock;
+  __mockSettingsGet: jest.Mock;
   __mockLogger: { debug: jest.Mock; error: jest.Mock; info: jest.Mock; warn: jest.Mock };
 }
 
@@ -62,6 +63,7 @@ function isPapiBackendTestMock(m: unknown): m is PapiBackendTestMock {
     '__mockProjectDataProvidersGet' in m &&
     '__mockGetLocalizedString' in m &&
     '__mockCreateNetworkEventEmitterAsync' in m &&
+    '__mockSettingsGet' in m &&
     '__mockLogger' in m
   );
 }
@@ -81,6 +83,7 @@ const {
   __mockProjectDataProvidersGet,
   __mockGetLocalizedString,
   __mockCreateNetworkEventEmitterAsync,
+  __mockSettingsGet,
   __mockLogger,
 } = papiBackendMock;
 
@@ -391,6 +394,9 @@ describe('main', () => {
           'interlinearizer.getSegments',
           'interlinearizer.getTextReadStatus',
           'interlinearizer.saveDraft',
+          'interlinearizer.openSession',
+          'interlinearizer.closeSession',
+          'interlinearizer.setAnalysisLanguage',
           'interlinearizer.openSelectProjectModal',
           'interlinearizer.openNewProjectModal',
           'interlinearizer.openProjectInfoModal',
@@ -1815,6 +1821,155 @@ describe('main', () => {
     });
   });
 
+  describe('session commands', () => {
+    /** A repository handing out `draft`, as storage would open one. */
+    function stubRepository(draft: DraftProject, readOnly = false): AnalysisRepository {
+      return {
+        capabilities: { readOnly },
+        exportAll: async () => ({ draft, unreadableBooks: [] }),
+        exportForCopy: async () => ({ draft, unreadableBooks: [] }),
+        replaceAll: async () => [],
+        markClean: async () => {},
+      };
+    }
+
+    /** Activates the extension and returns the session commands' handlers. */
+    async function activateSessionCommands() {
+      await activate(createTestActivationContext());
+      const handler = <T>(commandName: string): T => {
+        const raw = findRegisteredHandler(commandName);
+        if (!raw) throw new Error(`Handler not found for ${commandName}`);
+        // eslint-disable-next-line no-type-assertion/no-type-assertion
+        return raw as unknown as T;
+      };
+      return {
+        openSession: handler<
+          (sourceProjectId: string, interlinearProjectId?: string) => Promise<string>
+        >('interlinearizer.openSession'),
+        closeSession: handler<(sessionId: string) => Promise<void>>('interlinearizer.closeSession'),
+        setAnalysisLanguage: handler<
+          (sessionId: string, analysisLanguage: string) => Promise<void>
+        >('interlinearizer.setAnalysisLanguage'),
+      };
+    }
+
+    beforeEach(() => {
+      jest
+        .mocked(projectStorage.openDraftRepository)
+        .mockReturnValue(
+          stubRepository({ ...emptyDraft('src-project'), analysisLanguages: ['en'] }),
+        );
+      __mockSettingsGet.mockResolvedValue(['en']);
+    });
+
+    it("opens a session on the source project's draft", async () => {
+      const { openSession } = await activateSessionCommands();
+
+      const opened = JSON.parse(await openSession('src-project'));
+
+      expect(opened).toStrictEqual({
+        sessionId: expect.any(String),
+        readOnly: false,
+        hasFreeTranslations: false,
+      });
+      expect(projectStorage.openDraftRepository).toHaveBeenCalledWith(
+        expect.anything(),
+        'src-project',
+      );
+    });
+
+    it("opens a Paratext 9 import's session read-only, found among the source's projects", async () => {
+      const imported = {
+        ...makeStubProject('import-id'),
+        pt9Import: { fileHashes: {}, importedAt: '2026-02-01T00:00:00.000Z' },
+      };
+      jest
+        .mocked(projectStorage.getProjectSummariesForSource)
+        .mockResolvedValue([
+          toProjectSummary(makeStubProject('other-id')),
+          toProjectSummary(imported),
+        ]);
+      jest
+        .mocked(projectStorage.openPt9ImportRepository)
+        .mockReturnValue(stubRepository(emptyDraft('src-project'), true));
+      const { openSession } = await activateSessionCommands();
+
+      const opened = JSON.parse(await openSession('src-project', 'import-id'));
+
+      expect(opened.readOnly).toBe(true);
+      expect(projectStorage.getProjectSummariesForSource).toHaveBeenCalledWith(
+        expect.anything(),
+        'src-project',
+      );
+      expect(projectStorage.openPt9ImportRepository).toHaveBeenCalledWith(
+        expect.anything(),
+        'import-id',
+      );
+    });
+
+    it('reads the interface languages for a draft that lists no analysis language', async () => {
+      jest
+        .mocked(projectStorage.openDraftRepository)
+        .mockReturnValue(stubRepository(emptyDraft('src-project')));
+      __mockSettingsGet.mockResolvedValue(['fr']);
+      const { openSession } = await activateSessionCommands();
+
+      await openSession('src-project');
+
+      expect(__mockSettingsGet).toHaveBeenCalledWith('platform.interfaceLanguage');
+    });
+
+    it('logs the error and rethrows when the session cannot open', async () => {
+      jest.mocked(projectStorage.getProjectSummariesForSource).mockResolvedValue([]);
+      const { openSession } = await activateSessionCommands();
+
+      await expect(openSession('src-project', 'missing')).rejects.toThrow(
+        'has no interlinear project missing',
+      );
+      expect(__mockLogger.error).toHaveBeenCalledWith(
+        'Interlinearizer: failed to open a session on project src-project',
+        expect.any(Error),
+      );
+    });
+
+    it("closes a session, releasing its draft's repository", async () => {
+      const { openSession, closeSession } = await activateSessionCommands();
+      const { sessionId } = JSON.parse(await openSession('src-project'));
+
+      await closeSession(sessionId);
+
+      expect(projectStorage.releaseDraftRepository).toHaveBeenCalledWith('src-project');
+    });
+
+    it('sets the analysis language of an open session', async () => {
+      const { openSession, setAnalysisLanguage } = await activateSessionCommands();
+      const { sessionId } = JSON.parse(await openSession('src-project'));
+
+      await expect(setAnalysisLanguage(sessionId, 'fr')).resolves.toBeUndefined();
+    });
+
+    it('logs the error and rethrows when setting the language of a session that is not open', async () => {
+      const { setAnalysisLanguage } = await activateSessionCommands();
+
+      await expect(setAnalysisLanguage('not-a-session', 'fr')).rejects.toThrow(
+        'no session not-a-session is open',
+      );
+      expect(__mockLogger.error).toHaveBeenCalledWith(
+        'Interlinearizer: failed to set the analysis language of session not-a-session',
+        expect.any(Error),
+      );
+    });
+
+    it('closes every session on deactivation', async () => {
+      const { openSession } = await activateSessionCommands();
+      await openSession('src-project');
+
+      await deactivate();
+
+      expect(projectStorage.releaseDraftRepository).toHaveBeenCalledWith('src-project');
+    });
+  });
+
   describe('deactivate', () => {
     it('returns true to indicate successful deactivation', async () => {
       const result = await deactivate();
diff --git a/src/__tests__/services/analysisSessions.parity.test.ts b/src/__tests__/services/analysisSessions.parity.test.ts
new file mode 100644
index 000000000..536524f03
--- /dev/null
+++ b/src/__tests__/services/analysisSessions.parity.test.ts
@@ -0,0 +1,45 @@
+/// <reference types="jest" />
+
+import { AnalysisSessions } from '../../services/analysisSessions';
+import { DraftRepository } from '../../services/draftRepository';
+import reducer, { selectAnalysisLanguage, setAnalysisLanguage } from '../../store/analysisSlice';
+import { emptyAnalysis, emptyDraft } from '../../types/empty-factories';
+import { memoryStorage, silentLogger } from '../test-helpers';
+
+const SOURCE = 'src-project';
+
+describe('setAnalysisLanguage parity with the reducer', () => {
+  it.each([
+    ['a language its scope lists after the first', 'en'],
+    ['the language it is already on', 'fr'],
+    ['a language its scope does not list', 'de'],
+  ])('sets %s as the reducer does, storing nothing', async (_case, tag) => {
+    const { storage, writes } = memoryStorage();
+    const logger = silentLogger();
+    const draft = { ...emptyDraft(SOURCE), analysisLanguages: ['fr', 'en'] };
+    await new DraftRepository(storage, SOURCE, logger).replaceAll(draft);
+    const savedWrites = writes.length;
+    const sessions = new AnalysisSessions({
+      findProject: async () => undefined,
+      openDraftRepository: (sourceProjectId) =>
+        new DraftRepository(storage, sourceProjectId, logger),
+      releaseDraftRepository: async () => {},
+      openPt9ImportRepository: () => {
+        throw new Error('no import in this test');
+      },
+      getInterfaceLanguages: async () => [],
+    });
+    const { sessionId } = await sessions.open(SOURCE);
+
+    const state = reducer(
+      { analysis: emptyAnalysis(), analysisLanguage: 'fr' },
+      setAnalysisLanguage(tag),
+    );
+    await sessions.setAnalysisLanguage(sessionId, tag);
+
+    await expect(
+      sessions.run(sessionId, async ({ analysisLanguage }) => analysisLanguage),
+    ).resolves.toBe(selectAnalysisLanguage(state));
+    expect(writes).toHaveLength(savedWrites);
+  });
+});
diff --git a/src/__tests__/services/analysisSessions.test.ts b/src/__tests__/services/analysisSessions.test.ts
new file mode 100644
index 000000000..aaf4d6b65
--- /dev/null
+++ b/src/__tests__/services/analysisSessions.test.ts
@@ -0,0 +1,434 @@
+/// <reference types="jest" />
+
+import type { DraftProject, InterlinearProject, TextAnalysis } from 'interlinearizer';
+import {
+  AnalysisSessions,
+  type SessionHost,
+  UNDETERMINED_LANGUAGE,
+} from '../../services/analysisSessions';
+import { DraftRepository } from '../../services/draftRepository';
+import { Pt9ImportRepository } from '../../services/pt9ImportRepository';
+import { draftKey } from '../../services/storageKeys';
+import { ReadOnlyAnalysisError } from '../../types/read-only-analysis-error';
+import { emptyAnalysis, emptyDraft } from '../../types/empty-factories';
+import { toProjectSummary } from '../../types/interlinear-project-summary';
+import { CURRENT_MODEL_VERSION } from '../../types/model-version';
+import { FIXTURE_STAMPS, makeStubProject, memoryStorage, silentLogger } from '../test-helpers';
+
+const SOURCE = 'src-project';
+const OTHER_SOURCE = 'other-project';
+
+const FREE_TRANSLATED: TextAnalysis = {
+  ...emptyAnalysis(),
+  segmentAnalyses: [
+    {
+      id: 'sa-1',
+      ...FIXTURE_STAMPS,
+      surfaceText: 'In the beginning',
+      freeTranslation: { en: 'At first' },
+    },
+  ],
+};
+
+function makeImport(overrides: Partial<InterlinearProject> = {}): InterlinearProject {
+  return {
+    ...makeStubProject('import-id'),
+    pt9Import: { fileHashes: {}, importedAt: '2026-02-01T00:00:00.000Z' },
+    ...overrides,
+  };
+}
+
+/** Sessions over drafts in memory and over `projects`, with the host they reach them through. */
+function makeSessions(projects: InterlinearProject[] = []) {
+  const { storage } = memoryStorage();
+  const logger = silentLogger();
+  const host = {
+    findProject: jest.fn(async (sourceProjectId: string, interlinearProjectId: string) => {
+      const project = projects.find(
+        ({ id, sourceProjectId: source }) =>
+          id === interlinearProjectId && source === sourceProjectId,
+      );
+      return project && toProjectSummary(project);
+    }),
+    openDraftRepository: jest.fn(
+      (sourceProjectId: string) => new DraftRepository(storage, sourceProjectId, logger),
+    ),
+    releaseDraftRepository: jest.fn<Promise<void>, [string]>(async () => {}),
+    openPt9ImportRepository: jest.fn(
+      (interlinearProjectId: string) =>
+        new Pt9ImportRepository(interlinearProjectId, async () =>
+          projects.find(({ id }) => id === interlinearProjectId),
+        ),
+    ),
+    getInterfaceLanguages: jest.fn(async (): Promise<string[]> => []),
+  } satisfies SessionHost;
+  const saveDraft = (draft: DraftProject) =>
+    new DraftRepository(storage, draft.sourceProjectId, logger).replaceAll(draft);
+  return { host, sessions: new AnalysisSessions(host), saveDraft, storage };
+}
+
+/** A promise a test settles when it chooses. */
+function deferred() {
+  let settle: () => void = () => {};
+  const promise = new Promise<void>((resolve) => {
+    settle = resolve;
+  });
+  return { promise, resolve: () => settle() };
+}
+
+/** Lets every already-settled promise's callbacks run. */
+const flushPromises = () =>
+  new Promise<void>((resolve) => {
+    setTimeout(resolve, 0);
+  });
+
+describe('AnalysisSessions', () => {
+  describe('open', () => {
+    it('opens an editable session on a draft', async () => {
+      const { host, sessions, saveDraft } = makeSessions();
+      await saveDraft({ ...emptyDraft(SOURCE), analysisLanguages: ['en'] });
+
+      const opened = await sessions.open(SOURCE);
+
+      expect(opened).toStrictEqual({
+        sessionId: expect.any(String),
+        readOnly: false,
+        hasFreeTranslations: false,
+      });
+      expect(host.openDraftRepository).toHaveBeenCalledWith(SOURCE);
+      await expect(sessions.run(opened.sessionId, async ({ scope }) => scope)).resolves.toEqual({
+        kind: 'draft',
+        sourceProjectId: SOURCE,
+      });
+    });
+
+    it('reports a free translation in the draft', async () => {
+      const { sessions, saveDraft } = makeSessions();
+      await saveDraft({ ...emptyDraft(SOURCE), analysis: FREE_TRANSLATED });
+
+      await expect(sessions.open(SOURCE)).resolves.toMatchObject({ hasFreeTranslations: true });
+    });
+
+    it('opens a draft with the interlinear project it saves to, reading the draft', async () => {
+      const { sessions } = makeSessions([{ ...makeStubProject(), analysis: FREE_TRANSLATED }]);
+
+      const opened = await sessions.open(SOURCE, 'proj-id');
+
+      expect(opened).toMatchObject({ readOnly: false, hasFreeTranslations: false });
+      await expect(sessions.run(opened.sessionId, async ({ scope }) => scope)).resolves.toEqual({
+        kind: 'draft',
+        sourceProjectId: SOURCE,
+        interlinearProjectId: 'proj-id',
+      });
+    });
+
+    it('opens a Paratext 9 import read-only, reading its analysis', async () => {
+      const { host, sessions } = makeSessions([makeImport({ analysis: FREE_TRANSLATED })]);
+
+      const opened = await sessions.open(SOURCE, 'import-id');
+
+      expect(opened).toMatchObject({ readOnly: true, hasFreeTranslations: true });
+      expect(host.openDraftRepository).not.toHaveBeenCalled();
+      await expect(sessions.run(opened.sessionId, async ({ scope }) => scope)).resolves.toEqual({
+        kind: 'pt9Import',
+        sourceProjectId: SOURCE,
+        interlinearProjectId: 'import-id',
+      });
+    });
+
+    it('refuses an interlinear project the source project does not have', async () => {
+      const { sessions } = makeSessions([{ ...makeStubProject(), sourceProjectId: OTHER_SOURCE }]);
+
+      await expect(sessions.open(SOURCE, 'proj-id')).rejects.toThrow(
+        'source project src-project has no interlinear project proj-id',
+      );
+      await expect(sessions.open(SOURCE)).resolves.toMatchObject({ readOnly: false });
+    });
+
+    it('starts on the first analysis language its scope lists', async () => {
+      const { host, sessions, saveDraft } = makeSessions();
+      await saveDraft({ ...emptyDraft(SOURCE), analysisLanguages: ['fr', 'en'] });
+
+      const { sessionId } = await sessions.open(SOURCE);
+
+      await expect(
+        sessions.run(sessionId, async ({ analysisLanguage }) => analysisLanguage),
+      ).resolves.toBe('fr');
+      expect(host.getInterfaceLanguages).not.toHaveBeenCalled();
+    });
+
+    it('starts on the first interface language when its scope lists none', async () => {
+      const { host, sessions } = makeSessions();
+      host.getInterfaceLanguages.mockResolvedValue(['de', 'en']);
+
+      const { sessionId } = await sessions.open(SOURCE);
+
+      await expect(
+        sessions.run(sessionId, async ({ analysisLanguage }) => analysisLanguage),
+      ).resolves.toBe('de');
+    });
+
+    it('starts on the undetermined language when neither its scope nor the platform lists one', async () => {
+      const { sessions } = makeSessions();
+
+      const { sessionId } = await sessions.open(SOURCE);
+
+      await expect(
+        sessions.run(sessionId, async ({ analysisLanguage }) => analysisLanguage),
+      ).resolves.toBe(UNDETERMINED_LANGUAGE);
+    });
+
+    it("closes the source's earlier session, releasing its draft before reopening it", async () => {
+      const { host, sessions } = makeSessions();
+      const earlier = await sessions.open(SOURCE);
+
+      const later = await sessions.open(SOURCE);
+
+      await expect(sessions.run(earlier.sessionId, async () => {})).rejects.toThrow(
+        `no session ${earlier.sessionId} is open`,
+      );
+      await expect(sessions.run(later.sessionId, async () => 'ran')).resolves.toBe('ran');
+      expect(host.releaseDraftRepository).toHaveBeenCalledTimes(1);
+      expect(host.releaseDraftRepository.mock.invocationCallOrder[0]).toBeLessThan(
+        host.openDraftRepository.mock.invocationCallOrder[1],
+      );
+    });
+
+    it('reopens a source on what storage holds', async () => {
+      const { sessions, saveDraft } = makeSessions();
+      await sessions.open(SOURCE);
+      await saveDraft({ ...emptyDraft(SOURCE), analysis: FREE_TRANSLATED });
+
+      await expect(sessions.open(SOURCE)).resolves.toMatchObject({ hasFreeTranslations: true });
+    });
+
+    it("waits for the earlier session's commands before reopening the source", async () => {
+      const { host, sessions } = makeSessions();
+      const earlier = await sessions.open(SOURCE);
+      const command = deferred();
+      const running = sessions.run(earlier.sessionId, () => command.promise);
+
+      const reopening = sessions.open(SOURCE);
+      await flushPromises();
+
+      expect(host.openDraftRepository).toHaveBeenCalledTimes(1);
+      command.resolve();
+      await running;
+      await expect(reopening).resolves.toMatchObject({ readOnly: false });
+      expect(host.openDraftRepository).toHaveBeenCalledTimes(2);
+    });
+
+    it('leaves the source with no session when the replacing open fails', async () => {
+      const { sessions, storage } = makeSessions();
+      const earlier = await sessions.open(SOURCE);
+      await storage.write(
+        draftKey(SOURCE),
+        JSON.stringify({ ...emptyDraft(SOURCE), modelVersion: CURRENT_MODEL_VERSION + 1 }),
+      );
+
+      await expect(sessions.open(SOURCE)).rejects.toThrow('newer than this build supports');
+      await expect(sessions.run(earlier.sessionId, async () => {})).rejects.toThrow(
+        `no session ${earlier.sessionId} is open`,
+      );
+    });
+
+    it('keeps the sessions of different source projects open together', async () => {
+      const { host, sessions } = makeSessions();
+
+      const first = await sessions.open(SOURCE);
+      const second = await sessions.open(OTHER_SOURCE);
+
+      await expect(sessions.run(first.sessionId, async () => 'first')).resolves.toBe('first');
+      await expect(sessions.run(second.sessionId, async () => 'second')).resolves.toBe('second');
+      expect(host.releaseDraftRepository).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('close', () => {
+    it('refuses every command sent after it', async () => {
+      const { sessions } = makeSessions();
+      const { sessionId } = await sessions.open(SOURCE);
+
+      const closing = sessions.close(sessionId);
+
+      await expect(sessions.run(sessionId, async () => {})).rejects.toThrow(
+        `no session ${sessionId} is open`,
+      );
+      await closing;
+    });
+
+    it('releases the draft once the commands sent before it settle', async () => {
+      const { host, sessions } = makeSessions();
+      const { sessionId } = await sessions.open(SOURCE);
+      const command = deferred();
+      const running = sessions.run(sessionId, () => command.promise);
+
+      const closing = sessions.close(sessionId);
+      await flushPromises();
+
+      expect(host.releaseDraftRepository).not.toHaveBeenCalled();
+      command.resolve();
+      await running;
+      await closing;
+      expect(host.releaseDraftRepository).toHaveBeenCalledWith(SOURCE);
+    });
+
+    it("releases no draft for a Paratext 9 import's session", async () => {
+      const { host, sessions } = makeSessions([makeImport()]);
+      const { sessionId } = await sessions.open(SOURCE, 'import-id');
+
+      await sessions.close(sessionId);
+
+      expect(host.releaseDraftRepository).not.toHaveBeenCalled();
+    });
+
+    it('does nothing for a session that is not open', async () => {
+      const { host, sessions } = makeSessions();
+
+      await sessions.close('not-a-session');
+
+      expect(host.releaseDraftRepository).not.toHaveBeenCalled();
+    });
+
+    it('releases once when sent twice', async () => {
+      const { host, sessions } = makeSessions();
+      const { sessionId } = await sessions.open(SOURCE);
+
+      await Promise.all([sessions.close(sessionId), sessions.close(sessionId)]);
+
+      expect(host.releaseDraftRepository).toHaveBeenCalledTimes(1);
+    });
+
+    it('releases once when sent before a replacing open takes its turn', async () => {
+      const { host, sessions } = makeSessions();
+      const earlier = await sessions.open(SOURCE);
+
+      const reopening = sessions.open(SOURCE);
+      const closing = sessions.close(earlier.sessionId);
+      const later = await reopening;
+      await closing;
+
+      expect(host.releaseDraftRepository).toHaveBeenCalledTimes(1);
+      await expect(sessions.run(later.sessionId, async () => 'ran')).resolves.toBe('ran');
+    });
+  });
+
+  describe('closeAll', () => {
+    it('closes every open session', async () => {
+      const { host, sessions } = makeSessions();
+      const first = await sessions.open(SOURCE);
+      const second = await sessions.open(OTHER_SOURCE);
+
+      await sessions.closeAll();
+
+      await expect(sessions.run(first.sessionId, async () => {})).rejects.toThrow();
+      await expect(sessions.run(second.sessionId, async () => {})).rejects.toThrow();
+      expect(host.releaseDraftRepository).toHaveBeenCalledWith(SOURCE);
+      expect(host.releaseDraftRepository).toHaveBeenCalledWith(OTHER_SOURCE);
+    });
+  });
+
+  describe('run', () => {
+    it('runs commands one at a time, in the order they were sent', async () => {
+      const { sessions } = makeSessions();
+      const { sessionId } = await sessions.open(SOURCE);
+      const steps: string[] = [];
+      const first = deferred();
+
+      const running = Promise.all([
+        sessions.run(sessionId, async () => {
+          steps.push('first started');
+          await first.promise;
+          steps.push('first ended');
+        }),
+        sessions.run(sessionId, async () => {
+          steps.push('second ran');
+        }),
+      ]);
+      await flushPromises();
+      first.resolve();
+      await running;
+
+      expect(steps).toStrictEqual(['first started', 'first ended', 'second ran']);
+    });
+
+    it('runs later commands after one fails', async () => {
+      const { sessions } = makeSessions();
+      const { sessionId } = await sessions.open(SOURCE);
+
+      const failing = sessions.run(sessionId, async () => {
+        throw new Error('command failed');
+      });
+      const later = sessions.run(sessionId, async () => 'ran');
+
+      await expect(failing).rejects.toThrow('command failed');
+      await expect(later).resolves.toBe('ran');
+    });
+
+    it('refuses a session that is not open', async () => {
+      const { sessions } = makeSessions();
+
+      await expect(sessions.run('not-a-session', async () => {})).rejects.toThrow(
+        'no session not-a-session is open',
+      );
+    });
+  });
+
+  describe('runEdit', () => {
+    it("refuses an edit on a Paratext 9 import's session without running it", async () => {
+      const { sessions } = makeSessions([makeImport()]);
+      const { sessionId } = await sessions.open(SOURCE, 'import-id');
+      const edit = jest.fn(async () => {});
+
+      await expect(sessions.runEdit(sessionId, edit)).rejects.toThrow(ReadOnlyAnalysisError);
+      expect(edit).not.toHaveBeenCalled();
+    });
+
+    it("runs an edit on a draft's session", async () => {
+      const { sessions } = makeSessions();
+      const { sessionId } = await sessions.open(SOURCE);
+
+      await expect(sessions.runEdit(sessionId, async () => 'edited')).resolves.toBe('edited');
+    });
+
+    it('refuses a session that is not open', async () => {
+      const { sessions } = makeSessions();
+
+      await expect(sessions.runEdit('not-a-session', async () => {})).rejects.toThrow(
+        'no session not-a-session is open',
+      );
+    });
+  });
+
+  describe('setAnalysisLanguage', () => {
+    it('sets the language the commands sent after it read', async () => {
+      const { sessions } = makeSessions();
+      const { sessionId } = await sessions.open(SOURCE);
+
+      await sessions.setAnalysisLanguage(sessionId, 'fr');
+
+      await expect(
+        sessions.run(sessionId, async ({ analysisLanguage }) => analysisLanguage),
+      ).resolves.toBe('fr');
+    });
+
+    it("sets the language of a Paratext 9 import's session", async () => {
+      const { sessions } = makeSessions([makeImport()]);
+      const { sessionId } = await sessions.open(SOURCE, 'import-id');
+
+      await sessions.setAnalysisLanguage(sessionId, 'fr');
+
+      await expect(
+        sessions.run(sessionId, async ({ analysisLanguage }) => analysisLanguage),
+      ).resolves.toBe('fr');
+    });
+
+    it('refuses a session that is not open', async () => {
+      const { sessions } = makeSessions();
+
+      await expect(sessions.setAnalysisLanguage('not-a-session', 'fr')).rejects.toThrow(
+        'no session not-a-session is open',
+      );
+    });
+  });
+});
diff --git a/src/__tests__/services/draftRepository.conformance.test.ts b/src/__tests__/services/draftRepository.conformance.test.ts
index 7a707768f..4ec8e65db 100644
--- a/src/__tests__/services/draftRepository.conformance.test.ts
+++ b/src/__tests__/services/draftRepository.conformance.test.ts
@@ -1,7 +1,9 @@
 /// <reference types="jest" />
 
+import type { InterlinearProject } from 'interlinearizer';
 import { DraftRepository } from '../../services/draftRepository';
-import { draftAnalysisKey, draftKey } from '../../services/storageKeys';
+import { Pt9ImportRepository } from '../../services/pt9ImportRepository';
+import { draftAnalysisKey, draftKey, projectKey } from '../../services/storageKeys';
 import { emptyDraft } from '../../types/empty-factories';
 import { CURRENT_MODEL_VERSION } from '../../types/model-version';
 import { describeAnalysisRepositoryConformance } from '../analysis-repository-conformance';
@@ -12,7 +14,9 @@ const logger = silentLogger();
 /** Whether the current test damaged storage or failed its cleanup, which a repository may log. */
 let warningsExpected = false;
 
-describeAnalysisRepositoryConformance('DraftRepository', () => {
+const IMPORT_ID = 'pt9-import';
+
+describeAnalysisRepositoryConformance('DraftRepository with Pt9ImportRepository', () => {
   const { storage: memory, records } = memoryStorage();
   warningsExpected = false;
   /** The key of the draft whose cleanup fails; unset while cleanup succeeds. */
@@ -74,6 +78,23 @@ describeAnalysisRepositoryConformance('DraftRepository', () => {
         (key) => key.startsWith(`${draftKey(sourceProjectId)}:`) && !needed.has(key),
       );
     },
+    async openReadOnly({ sourceProjectId, analysisLanguages, analysis }) {
+      const project: InterlinearProject = {
+        id: IMPORT_ID,
+        modelVersion: CURRENT_MODEL_VERSION,
+        createdAt: '2026-01-01T00:00:00.000Z',
+        updatedAt: '2026-01-01T00:00:00.000Z',
+        sourceProjectId,
+        analysisLanguages,
+        analysis,
+        pt9Import: { fileHashes: {}, importedAt: '2026-01-01T00:00:00.000Z' },
+      };
+      await memory.write(projectKey(IMPORT_ID), JSON.stringify(project));
+      return new Pt9ImportRepository(IMPORT_ID, async () => {
+        const raw = await memory.read(projectKey(IMPORT_ID));
+        return raw === undefined ? undefined : JSON.parse(raw);
+      });
+    },
   };
 });
 
diff --git a/src/__tests__/services/projectStorage.test.ts b/src/__tests__/services/projectStorage.test.ts
index 23da9d71d..8c97e0e40 100644
--- a/src/__tests__/services/projectStorage.test.ts
+++ b/src/__tests__/services/projectStorage.test.ts
@@ -11,6 +11,9 @@ import {
   getProjectSummariesForSource,
   getPt9ImportForSource,
   hasDraft,
+  openDraftRepository,
+  openPt9ImportRepository,
+  releaseDraftRepository,
   resetQueuesForTesting,
   saveDraft,
   saveDraftAsNewProject,
@@ -21,6 +24,7 @@ import {
   updateProjectMetadata,
 } from '../../services/projectStorage';
 import { summarizeProject } from '../../services/projectSummaries';
+import { ReadOnlyAnalysisError } from '../../types/read-only-analysis-error';
 import { emptyAnalysis, emptyDraft } from '../../types/empty-factories';
 import { removeBookFromAnalysis } from '../../utils/analysis-book';
 import { UnreadableBooksError } from '../../types/analysis-repository';
@@ -2830,6 +2834,131 @@ describe('projectStorage', () => {
     });
   });
 
+  describe('openDraftRepository', () => {
+    beforeEach(() => writeThroughStore());
+
+    it('is writable', () => {
+      expect(openDraftRepository(token, 'src-proj').capabilities.readOnly).toBe(false);
+    });
+
+    it('loads and saves the draft getDraft and saveDraft reach', async () => {
+      const repository = openDraftRepository(token, 'src-proj');
+      const saved = makeDraftSpanningBooks('src-proj', 'GEN');
+      const savedElsewhere = makeDraftSpanningBooks('src-proj', 'JHN');
+
+      await repository.replaceAll(saved);
+      await expect(getDraft(token, 'src-proj')).resolves.toEqual({
+        draft: saved,
+        unreadableBooks: [],
+      });
+      await saveDraft(token, 'src-proj', savedElsewhere);
+      await expect(repository.exportAll()).resolves.toEqual({
+        draft: savedElsewhere,
+        unreadableBooks: [],
+      });
+    });
+
+    it('loads the draft for copying and marks it clean', async () => {
+      const repository = openDraftRepository(token, 'src-proj');
+      const saved = { ...makeDraftSpanningBooks('src-proj', 'GEN'), dirty: true };
+      await repository.replaceAll(saved);
+
+      await expect(repository.exportForCopy()).resolves.toEqual({
+        draft: saved,
+        unreadableBooks: [],
+      });
+      await repository.markClean();
+      await expect(repository.exportAll()).resolves.toMatchObject({ draft: { dirty: false } });
+    });
+
+    it('shares what saveDraft knows of storage, rewriting only the edited book', async () => {
+      const draft = makeDraftSpanningBooks('src-proj', 'GEN', 'JHN');
+      await saveDraft(token, 'src-proj', draft);
+      __mockWriteUserData.mockClear();
+
+      draft.analysis.tokenAnalysisLinks[0].token.surfaceText = 'edited';
+      await openDraftRepository(token, 'src-proj').replaceAll(draft);
+
+      expect(writtenKeys()).toContain('draft:src-proj:analysis:GEN');
+      expect(writtenKeys()).not.toContain('draft:src-proj:analysis:JHN');
+    });
+
+    it('waits for a draft call already made before reading', async () => {
+      let finishWrite: () => void = () => {};
+      __mockWriteUserData.mockImplementationOnce(
+        () =>
+          new Promise<void>((resolve) => {
+            finishWrite = resolve;
+          }),
+      );
+      const saving = saveDraft(token, 'src-proj', makeDraftSpanningBooks('src-proj', 'GEN'));
+      await new Promise((resolve) => {
+        setTimeout(resolve, 0);
+      });
+      const draftReads = () =>
+        __mockReadUserData.mock.calls.filter(([, key]) => key === 'draft:src-proj').length;
+      const readsBefore = draftReads();
+
+      const loading = openDraftRepository(token, 'src-proj').exportAll();
+      await new Promise((resolve) => {
+        setTimeout(resolve, 0);
+      });
+
+      expect(draftReads()).toBe(readsBefore);
+      finishWrite();
+      await saving;
+      await loading;
+      expect(draftReads()).toBeGreaterThan(readsBefore);
+    });
+  });
+
+  describe('releaseDraftRepository', () => {
+    beforeEach(() => writeThroughStore());
+
+    it('leaves the next save knowing nothing of storage, so it rewrites every book', async () => {
+      const draft = makeDraftSpanningBooks('src-proj', 'GEN', 'JHN');
+      await saveDraft(token, 'src-proj', draft);
+
+      await releaseDraftRepository('src-proj');
+      __mockWriteUserData.mockClear();
+      await saveDraft(token, 'src-proj', draft);
+
+      expect(writtenKeys()).toContain('draft:src-proj:analysis:GEN');
+      expect(writtenKeys()).toContain('draft:src-proj:analysis:JHN');
+    });
+
+    it('lets a draft call already made finish on the repository it releases', async () => {
+      const draft = makeDraftSpanningBooks('src-proj', 'GEN', 'JHN');
+      await saveDraft(token, 'src-proj', draft);
+      __mockWriteUserData.mockClear();
+
+      draft.analysis.tokenAnalysisLinks[0].token.surfaceText = 'edited';
+      await Promise.all([saveDraft(token, 'src-proj', draft), releaseDraftRepository('src-proj')]);
+
+      expect(writtenKeys()).not.toContain('draft:src-proj:analysis:JHN');
+    });
+  });
+
+  describe('openPt9ImportRepository', () => {
+    it("loads the stored import's analysis, refusing writes", async () => {
+      const imported: InterlinearProject = {
+        ...makeStubProject('import-id'),
+        analysis: makeDraftSpanningBooks('src-project', 'GEN').analysis,
+        pt9Import: { fileHashes: {}, importedAt: '2026-02-01T00:00:00.000Z' },
+      };
+      mockListedProject(imported);
+      const repository = openPt9ImportRepository(token, 'import-id');
+
+      expect(repository.capabilities.readOnly).toBe(true);
+      await expect(repository.exportAll()).resolves.toMatchObject({
+        draft: { sourceProjectId: 'src-project', analysis: imported.analysis },
+      });
+      await expect(repository.replaceAll(emptyDraft('src-project'))).rejects.toThrow(
+        ReadOnlyAnalysisError,
+      );
+    });
+  });
+
   describe('Paratext 9 import projects', () => {
     const PT9_PROVENANCE = {
       fileHashes: { 'Lexicon.xml': 'aaaa1111' },
diff --git a/src/__tests__/services/pt9ImportRepository.test.ts b/src/__tests__/services/pt9ImportRepository.test.ts
new file mode 100644
index 000000000..1e9ddf8dc
--- /dev/null
+++ b/src/__tests__/services/pt9ImportRepository.test.ts
@@ -0,0 +1,115 @@
+/// <reference types="jest" />
+
+import type { InterlinearProject } from 'interlinearizer';
+import { Pt9ImportRepository } from '../../services/pt9ImportRepository';
+import type { AnalysisRepository } from '../../types/analysis-repository';
+import { ReadOnlyAnalysisError } from '../../types/read-only-analysis-error';
+import { emptyAnalysis, emptyDraft } from '../../types/empty-factories';
+import { CURRENT_MODEL_VERSION } from '../../types/model-version';
+import { FIXTURE_STAMPS, makeStubProject } from '../test-helpers';
+
+function makeImport(overrides: Partial<InterlinearProject> = {}): InterlinearProject {
+  return {
+    ...makeStubProject('import-id'),
+    name: 'Paratext 9 import',
+    description: 'Imported from Paratext 9',
+    pt9Import: { fileHashes: { 'Interlinear_en_GEN.xml': 'hash' }, importedAt: '2026-02-01' },
+    ...overrides,
+  };
+}
+
+function repositoryOver(project: InterlinearProject | undefined) {
+  return new Pt9ImportRepository('import-id', async () => project);
+}
+
+describe('Pt9ImportRepository', () => {
+  it('is read-only', () => {
+    expect(repositoryOver(makeImport()).capabilities.readOnly).toBe(true);
+  });
+
+  describe('exportAll', () => {
+    it("loads the import's analysis and languages as a clean draft of its source project", async () => {
+      const analysis = {
+        ...emptyAnalysis(),
+        tokenAnalyses: [{ id: 'ta-1', ...FIXTURE_STAMPS, surfaceText: 'and' }],
+      };
+
+      await expect(
+        repositoryOver(makeImport({ analysisLanguages: ['fr', 'en'], analysis })).exportAll(),
+      ).resolves.toStrictEqual({
+        draft: { ...emptyDraft('src-project'), analysisLanguages: ['fr', 'en'], analysis },
+        unreadableBooks: [],
+      });
+    });
+
+    it("carries the import's target project and boundaries", async () => {
+      const segmentation = { removedVerseStarts: ['GEN 1:2'], addedStarts: [] };
+
+      const { draft } = await repositoryOver(
+        makeImport({ targetProjectId: 'target', segmentation }),
+      ).exportAll();
+
+      expect(draft.targetProjectId).toBe('target');
+      expect(draft.segmentation).toStrictEqual(segmentation);
+    });
+
+    it('stamps the draft with the current model version', async () => {
+      const { draft } = await repositoryOver(
+        makeImport({ modelVersion: CURRENT_MODEL_VERSION - 1 }),
+      ).exportAll();
+
+      expect(draft.modelVersion).toBe(CURRENT_MODEL_VERSION);
+    });
+
+    it('refuses when no project is stored under its id', async () => {
+      await expect(repositoryOver(undefined).exportAll()).rejects.toThrow(
+        'no Paratext 9 import is stored as project import-id',
+      );
+    });
+
+    it('refuses a project that is not a Paratext 9 import', async () => {
+      await expect(repositoryOver(makeStubProject('import-id')).exportAll()).rejects.toThrow(
+        'no Paratext 9 import is stored as project import-id',
+      );
+    });
+
+    it('rethrows a failed read', async () => {
+      const repository = new Pt9ImportRepository('import-id', async () => {
+        throw new Error('disk full');
+      });
+
+      await expect(repository.exportAll()).rejects.toThrow('disk full');
+    });
+  });
+
+  describe('exportForCopy', () => {
+    it('loads the import as exportAll does', async () => {
+      const repository = repositoryOver(makeImport());
+
+      await expect(repository.exportForCopy()).resolves.toStrictEqual(await repository.exportAll());
+    });
+  });
+
+  describe('markClean', () => {
+    it('refuses, reading nothing', async () => {
+      const readProject = jest.fn(async () => makeImport());
+
+      await expect(new Pt9ImportRepository('import-id', readProject).markClean()).rejects.toThrow(
+        ReadOnlyAnalysisError,
+      );
+      expect(readProject).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('replaceAll', () => {
+    it('refuses every save', async () => {
+      const readProject = jest.fn(async () => makeImport());
+      const repository: AnalysisRepository = new Pt9ImportRepository('import-id', readProject);
+
+      await expect(repository.replaceAll(emptyDraft('src-project'))).rejects.toThrow(
+        ReadOnlyAnalysisError,
+      );
+      expect(readProject).not.toHaveBeenCalled();
+    });
+  });
+});
diff --git a/src/__tests__/types/read-only-analysis-error.test.ts b/src/__tests__/types/read-only-analysis-error.test.ts
new file mode 100644
index 000000000..409538a40
--- /dev/null
+++ b/src/__tests__/types/read-only-analysis-error.test.ts
@@ -0,0 +1,13 @@
+/// <reference types="jest" />
+
+import { ReadOnlyAnalysisError } from '../../types/read-only-analysis-error';
+
+describe('ReadOnlyAnalysisError', () => {
+  it('is an Error named for itself, carrying its message', () => {
+    const error = new ReadOnlyAnalysisError('import is read-only');
+
+    expect(error).toBeInstanceOf(Error);
+    expect(error.name).toBe('ReadOnlyAnalysisError');
+    expect(error.message).toBe('import is read-only');
+  });
+});
diff --git a/src/__tests__/utils/free-translations.test.ts b/src/__tests__/utils/free-translations.test.ts
new file mode 100644
index 000000000..07b6bc6d8
--- /dev/null
+++ b/src/__tests__/utils/free-translations.test.ts
@@ -0,0 +1,44 @@
+/// <reference types="jest" />
+
+import type { SegmentAnalysis, TextAnalysis } from 'interlinearizer';
+import { emptyAnalysis } from '../../types/empty-factories';
+import { analysisHasFreeTranslations } from '../../utils/free-translations';
+import { FIXTURE_STAMPS } from '../test-helpers';
+
+function withSegmentAnalyses(...analyses: Partial<SegmentAnalysis>[]): TextAnalysis {
+  return {
+    ...emptyAnalysis(),
+    segmentAnalyses: analyses.map((analysis, i) => ({
+      id: `sa-${i}`,
+      ...FIXTURE_STAMPS,
+      surfaceText: 'In the beginning',
+      ...analysis,
+    })),
+  };
+}
+
+describe('analysisHasFreeTranslations', () => {
+  it('finds a free translation on any segment analysis', () => {
+    expect(
+      analysisHasFreeTranslations(
+        withSegmentAnalyses({}, { freeTranslation: { en: 'In the start' } }),
+      ),
+    ).toBe(true);
+  });
+
+  it('finds none in an analysis without segment analyses', () => {
+    expect(analysisHasFreeTranslations(emptyAnalysis())).toBe(false);
+  });
+
+  it('counts a free translation holding only whitespace as none', () => {
+    expect(analysisHasFreeTranslations(withSegmentAnalyses({ freeTranslation: { en: ' ' } }))).toBe(
+      false,
+    );
+  });
+
+  it('counts a literal translation as none', () => {
+    expect(
+      analysisHasFreeTranslations(withSegmentAnalyses({ literalTranslation: { en: 'In the' } })),
+    ).toBe(false);
+  });
+});
diff --git a/src/components/InterlinearizerLoader.tsx b/src/components/InterlinearizerLoader.tsx
index 08f13f837..9d0e8f792 100644
--- a/src/components/InterlinearizerLoader.tsx
+++ b/src/components/InterlinearizerLoader.tsx
@@ -92,7 +92,7 @@ import {
 import { placeHeadings, type CatalogFilters } from '../utils/analysis-query';
 import { nextSegmentAmong } from '../utils/stale-free-translations';
 import { resolvedOrEmpty } from '../utils/localized-strings';
-import { isEmptyMultiString } from '../utils/multi-string';
+import { analysisHasFreeTranslations } from '../utils/free-translations';
 import usePanelResizeKeys from '../hooks/usePanelResizeKeys';
 import { isPt9TooLargeError } from '../utils/pt9-import-error';
 import { readPt9Manifest } from '../utils/pt9-manifest';
@@ -621,10 +621,10 @@ function InterlinearizerLoaderInner({
   // Read from the seed analysis rather than the live store, so clearing the last free translation
   // cannot take its input away mid-edit.
   const hasFreeTranslations = useMemo(
-    () =>
-      (isImportView ? importAnalysis : draft?.analysis)?.segmentAnalyses.some(
-        (sa) => !isEmptyMultiString(sa.freeTranslation),
-      ) ?? false,
+    () => {
+      const seed = isImportView ? importAnalysis : draft?.analysis;
+      return seed ? analysisHasFreeTranslations(seed) : false;
+    },
     // eslint-disable-next-line react-hooks/exhaustive-deps -- draftVersion and isDraftLoading track draft?.analysis, a ref value
     [isImportView, importAnalysis, draftVersion, isDraftLoading],
   );
diff --git a/src/main.ts b/src/main.ts
index 8b3eae37a..9c6ff232f 100644
--- a/src/main.ts
+++ b/src/main.ts
@@ -11,6 +11,7 @@ import type { ProjectConfig } from 'interlinearizer';
 import { formatReplacementString, type LocalizeKey } from 'platform-bible-utils';
 import interlinearizerReact from './interlinearizer.web-view?inline';
 import interlinearizerStyles from './interlinearizer.web-view.scss?inline';
+import { AnalysisSessions } from './services/analysisSessions';
 import * as bookService from './services/bookService';
 import { readHostPerf, setHostPerfMarks } from './services/hostPerf';
 import * as projectStorage from './services/projectStorage';
@@ -126,6 +127,21 @@ const openWebViewsByProject = new Map<string, string>();
  */
 const leftOutDraftBooks = new Map<string, string>();
 
+/** The open analysis sessions, over the extension's storage. */
+const sessions = new AnalysisSessions({
+  findProject: async (sourceProjectId, interlinearProjectId) =>
+    (await projectStorage.getProjectSummariesForSource(executionToken, sourceProjectId)).find(
+      (summary) => summary.id === interlinearProjectId,
+    ),
+  openDraftRepository: (sourceProjectId) =>
+    projectStorage.openDraftRepository(executionToken, sourceProjectId),
+  releaseDraftRepository: (sourceProjectId) =>
+    projectStorage.releaseDraftRepository(sourceProjectId),
+  openPt9ImportRepository: (interlinearProjectId) =>
+    projectStorage.openPt9ImportRepository(executionToken, interlinearProjectId),
+  getInterfaceLanguages: () => papi.settings.get('platform.interfaceLanguage'),
+});
+
 // #endregion
 
 // #region Command handlers
@@ -721,6 +737,41 @@ async function saveInterlinearDraft(
   );
 }
 
+/**
+ * Opens a session on the source project's draft, paired with `interlinearProjectId` when given, or
+ * on that project alone, read-only, when it is a Paratext 9 import. Closes the source's earlier
+ * session, if any.
+ *
+ * @returns A JSON string of `{ sessionId, readOnly, hasFreeTranslations }`.
+ * @throws If the source project has no such interlinear project, or its analysis cannot be loaded.
+ *   The error is logged before rethrowing.
+ */
+async function openSession(
+  sourceProjectId: string,
+  interlinearProjectId?: string,
+): Promise<string> {
+  try {
+    return JSON.stringify(await sessions.open(sourceProjectId, interlinearProjectId));
+  } catch (e) {
+    logger.error(`Interlinearizer: failed to open a session on project ${sourceProjectId}`, e);
+    throw e;
+  }
+}
+
+/**
+ * Sets the language a session's glosses are read and written in.
+ *
+ * @throws If the session is not open. The error is logged before rethrowing.
+ */
+async function setAnalysisLanguage(sessionId: string, analysisLanguage: string): Promise<void> {
+  try {
+    await sessions.setAnalysisLanguage(sessionId, analysisLanguage);
+  } catch (e) {
+    logger.error(`Interlinearizer: failed to set the analysis language of session ${sessionId}`, e);
+    throw e;
+  }
+}
+
 /**
  * Returns a summary of every interlinearizer project for the given source project as a JSON string.
  * The WebView deserializes this to populate its project picker and to decide whether to prompt
@@ -1224,6 +1275,78 @@ export async function activate(context: ExecutionActivationContext): Promise<voi
     },
   );
 
+  /** The parameter naming the session a session command acts on. */
+  const sessionIdParam = {
+    name: 'sessionId',
+    required: true,
+    summary: 'ID of the session, as openSession returned it',
+    schema: { type: 'string' },
+  } as const;
+
+  const openSessionCommandRegistration = await papi.commands.registerCommand(
+    'interlinearizer.openSession',
+    openSession,
+    {
+      method: {
+        summary:
+          "Open a session on a source project's draft, or read-only on its Paratext 9 import, closing the source's earlier session",
+        params: [
+          {
+            name: 'sourceProjectId',
+            required: true,
+            summary: 'Platform.Bible source project ID whose analysis to open',
+            schema: { type: 'string' },
+          },
+          {
+            name: 'interlinearProjectId',
+            required: false,
+            summary:
+              'UUID of the interlinear project the draft saves to, or of the Paratext 9 import to read; omit for the draft alone',
+            schema: { type: 'string' },
+          },
+        ],
+        result: {
+          name: 'return value',
+          summary: 'JSON-stringified { sessionId, readOnly, hasFreeTranslations }',
+          schema: { type: 'string' },
+        },
+      },
+    },
+  );
+
+  const closeSessionCommandRegistration = await papi.commands.registerCommand(
+    'interlinearizer.closeSession',
+    (sessionId: string) => sessions.close(sessionId),
+    {
+      method: {
+        summary:
+          "Close a session once the commands sent to it settle; send it only after the session's last save",
+        params: [sessionIdParam],
+        result: { name: 'return value', summary: 'void', schema: { type: 'null' } },
+      },
+    },
+  );
+
+  const setAnalysisLanguageCommandRegistration = await papi.commands.registerCommand(
+    'interlinearizer.setAnalysisLanguage',
+    setAnalysisLanguage,
+    {
+      method: {
+        summary: "Set the language a session's glosses are read and written in",
+        params: [
+          sessionIdParam,
+          {
+            name: 'analysisLanguage',
+            required: true,
+            summary: 'BCP 47 tag of the language',
+            schema: { type: 'string' },
+          },
+        ],
+        result: { name: 'return value', summary: 'void', schema: { type: 'null' } },
+      },
+    },
+  );
+
   const setPerfMarksCommandRegistration = await papi.commands.registerCommand(
     'interlinearizer.setPerfMarks',
     async (enabled: boolean) => setHostPerfMarks(enabled),
@@ -1594,6 +1717,9 @@ export async function activate(context: ExecutionActivationContext): Promise<voi
     getSegmentsCommandRegistration,
     getTextReadStatusCommandRegistration,
     saveDraftCommandRegistration,
+    openSessionCommandRegistration,
+    closeSessionCommandRegistration,
+    setAnalysisLanguageCommandRegistration,
     setPerfMarksCommandRegistration,
     readPerfCommandRegistration,
     updateProjectMetadataCommandRegistration,
@@ -1628,6 +1754,7 @@ export async function activate(context: ExecutionActivationContext): Promise<voi
  */
 export async function deactivate(): Promise<boolean> {
   openWebViewsByProject.clear();
+  await sessions.closeAll();
   await bookService.closeAllProjects();
   logger.debug('Interlinearizer extension is deactivating!');
   return true;
diff --git a/src/services/analysisSessions.ts b/src/services/analysisSessions.ts
new file mode 100644
index 000000000..a0ea586ab
--- /dev/null
+++ b/src/services/analysisSessions.ts
@@ -0,0 +1,245 @@
+import type { AnalysisRepository } from '../types/analysis-repository';
+import { ReadOnlyAnalysisError } from '../types/read-only-analysis-error';
+import type { InterlinearProjectSummary } from '../types/interlinear-project-summary';
+import { analysisHasFreeTranslations } from '../utils/free-translations';
+
+/** BCP 47 tag for a language that cannot be determined. */
+export const UNDETERMINED_LANGUAGE = 'und';
+
+/**
+ * What a session opens: a source project's draft, paired with the interlinear project it saves to
+ * when it has one, or a Paratext 9 import on its own.
+ */
+export type SessionScope =
+  | {
+      kind: 'draft';
+      sourceProjectId: string;
+      /** The interlinear project the draft saves to; absent when it has none. */
+      interlinearProjectId?: string;
+    }
+  | { kind: 'pt9Import'; sourceProjectId: string; interlinearProjectId: string };
+
+/** What opening a session tells its caller. */
+export type OpenedSession = {
+  /** Addresses the session in every later call. */
+  sessionId: string;
+  /** Whether the session refuses edits, as it does for a Paratext 9 import. */
+  readOnly: boolean;
+  /** Whether any segment of the opened analysis had a free translation when it opened. */
+  hasFreeTranslations: boolean;
+};
+
+/** An open session, as the commands run on it see it. */
+export type Session = {
+  readonly id: string;
+  readonly scope: SessionScope;
+  readonly repository: AnalysisRepository;
+  /** BCP 47 tag of the language that glosses are read and written in. */
+  analysisLanguage: string;
+};
+
+/** What sessions reach projects and storage through. */
+export interface SessionHost {
+  /**
+   * The summary of `interlinearProjectId` among `sourceProjectId`'s interlinear projects, or
+   * `undefined` when the source has none by that id.
+   */
+  findProject(
+    sourceProjectId: string,
+    interlinearProjectId: string,
+  ): Promise<InterlinearProjectSummary | undefined>;
+  /** The source project's draft repository, shared with every other reader and writer of its draft. */
+  openDraftRepository(sourceProjectId: string): AnalysisRepository;
+  /** Releases the source project's draft repository once the calls already queued on it settle. */
+  releaseDraftRepository(sourceProjectId: string): Promise<void>;
+  /** A read-only repository over the Paratext 9 import `interlinearProjectId`. */
+  openPt9ImportRepository(interlinearProjectId: string): AnalysisRepository;
+  /** The platform's interface languages, most preferred first. */
+  getInterfaceLanguages(): Promise<string[]>;
+}
+
+type OpenSession = {
+  session: Session;
+  /** Settles once every command sent to the session so far has settled; never rejects. */
+  queue: Promise<unknown>;
+  /** Settles once the session is closed; set from the moment a close is sent. */
+  closed?: Promise<void>;
+};
+
+/**
+ * The open sessions, at most one per source project. Each runs the commands sent to it one at a
+ * time, in the order they were sent.
+ */
+export class AnalysisSessions {
+  private readonly host: SessionHost;
+
+  private readonly sessions = new Map<string, OpenSession>();
+
+  private readonly sessionsBySource = new Map<string, OpenSession>();
+
+  /**
+   * Each source project's opens and closes, chained so an open never interleaves with the close of
+   * the session it replaces.
+   */
+  private readonly lifecycles = new Map<string, Promise<unknown>>();
+
+  constructor(host: SessionHost) {
+    this.host = host;
+  }
+
+  /**
+   * Opens a session on the source project's draft, paired with `interlinearProjectId` when given,
+   * or on that project alone, read-only, when it is a Paratext 9 import. Opening closes the
+   * source's earlier session, if any, and starts the new one on what storage holds.
+   *
+   * The session starts on its scope's first analysis language. When the scope lists none, it starts
+   * on the platform's first interface language, or {@link UNDETERMINED_LANGUAGE} when the platform
+   * lists none either.
+   *
+   * @throws {Error} If the source project has no interlinear project `interlinearProjectId`.
+   * @throws Whatever finding the project or loading the scope's analysis throws; the source is left
+   *   with no session.
+   */
+  open(sourceProjectId: string, interlinearProjectId?: string): Promise<OpenedSession> {
+    return this.onLifecycle(sourceProjectId, async () => {
+      const replaced = this.sessionsBySource.get(sourceProjectId);
+      if (replaced) await this.closeNow(replaced);
+
+      const scope = await this.resolveScope(sourceProjectId, interlinearProjectId);
+      const repository =
+        scope.kind === 'pt9Import'
+          ? this.host.openPt9ImportRepository(scope.interlinearProjectId)
+          : this.host.openDraftRepository(sourceProjectId);
+      const { draft: opened } = await repository.exportAll();
+      const session: Session = {
+        id: crypto.randomUUID(),
+        scope,
+        repository,
+        analysisLanguage:
+          opened.analysisLanguages[0] ??
+          ((await this.host.getInterfaceLanguages())[0] || UNDETERMINED_LANGUAGE),
+      };
+      const entry: OpenSession = { session, queue: Promise.resolve() };
+      this.sessions.set(session.id, entry);
+      this.sessionsBySource.set(sourceProjectId, entry);
+      return {
+        sessionId: session.id,
+        readOnly: repository.capabilities.readOnly,
+        hasFreeTranslations: analysisHasFreeTranslations(opened.analysis),
+      };
+    });
+  }
+
+  /**
+   * Closes the session, refusing every command sent to it from now on. Resolves once the commands
+   * sent before have settled and its repository is released. Closing a session that is not open
+   * does nothing.
+   */
+  close(sessionId: string): Promise<void> {
+    const entry = this.sessions.get(sessionId);
+    if (!entry) return Promise.resolve();
+    entry.closed ??= this.onLifecycle(entry.session.scope.sourceProjectId, () =>
+      this.closeNow(entry),
+    );
+    return entry.closed;
+  }
+
+  /** Closes every open session. */
+  async closeAll(): Promise<void> {
+    await Promise.all([...this.sessions.keys()].map((sessionId) => this.close(sessionId)));
+  }
+
+  /**
+   * Sets the language that the session's glosses are read and written in, unchecked against the
+   * languages its scope lists. A read-only session takes it too, since it changes nothing stored.
+   *
+   * @throws {Error} If the session is not open.
+   */
+  setAnalysisLanguage(sessionId: string, analysisLanguage: string): Promise<void> {
+    return this.run(sessionId, async (session) => {
+      session.analysisLanguage = analysisLanguage;
+    });
+  }
+
+  /**
+   * Runs `command` on the session once every command sent to it before has settled.
+   *
+   * @throws {Error} If the session is not open.
+   * @throws Whatever `command` throws; later commands still run.
+   */
+  run<T>(sessionId: string, command: (session: Session) => Promise<T>): Promise<T> {
+    const entry = this.sessions.get(sessionId);
+    if (!entry || entry.closed) {
+      return Promise.reject(new Error(`Interlinearizer: no session ${sessionId} is open`));
+    }
+    const result = entry.queue.then(() => command(entry.session));
+    entry.queue = result.catch(() => {});
+    return result;
+  }
+
+  /**
+   * Runs `edit` as {@link run} does, refusing it on a read-only session without running it.
+   *
+   * @throws {ReadOnlyAnalysisError} If the session is read-only.
+   * @throws {Error} If the session is not open.
+   * @throws Whatever `edit` throws; later commands still run.
+   */
+  runEdit<T>(sessionId: string, edit: (session: Session) => Promise<T>): Promise<T> {
+    if (this.sessions.get(sessionId)?.session.repository.capabilities.readOnly) {
+      return Promise.reject(
+        new ReadOnlyAnalysisError(`Interlinearizer: session ${sessionId} is read-only`),
+      );
+    }
+    return this.run(sessionId, edit);
+  }
+
+  /**
+   * Resolves the scope for a session on the source project, paired with `interlinearProjectId` when
+   * given.
+   *
+   * @throws {Error} If the source project has no interlinear project `interlinearProjectId`.
+   */
+  private async resolveScope(
+    sourceProjectId: string,
+    interlinearProjectId: string | undefined,
+  ): Promise<SessionScope> {
+    if (interlinearProjectId === undefined) return { kind: 'draft', sourceProjectId };
+    const project = await this.host.findProject(sourceProjectId, interlinearProjectId);
+    if (!project) {
+      throw new Error(
+        `Interlinearizer: source project ${sourceProjectId} has no interlinear project ${interlinearProjectId}`,
+      );
+    }
+    return {
+      kind: project.pt9Import ? 'pt9Import' : 'draft',
+      sourceProjectId,
+      interlinearProjectId,
+    };
+  }
+
+  /**
+   * Stops addressing the session, then releases its repository once the commands sent to it have
+   * settled. A session that an earlier step already closed is left alone, so its repository is
+   * released only once.
+   */
+  private async closeNow(entry: OpenSession): Promise<void> {
+    const { id, scope } = entry.session;
+    if (this.sessions.get(id) !== entry) return;
+    this.sessions.delete(id);
+    this.sessionsBySource.delete(scope.sourceProjectId);
+    await entry.queue;
+    if (scope.kind === 'draft') await this.host.releaseDraftRepository(scope.sourceProjectId);
+  }
+
+  /** Runs `step` once every open and close of the source project enqueued before has settled. */
+  private onLifecycle<T>(sourceProjectId: string, step: () => Promise<T>): Promise<T> {
+    const result = (this.lifecycles.get(sourceProjectId) ?? Promise.resolve()).then(step);
+    let settled: Promise<void>;
+    const cleanup = () => {
+      if (this.lifecycles.get(sourceProjectId) === settled) this.lifecycles.delete(sourceProjectId);
+    };
+    settled = result.then(cleanup, cleanup);
+    this.lifecycles.set(sourceProjectId, settled);
+    return result;
+  }
+}
diff --git a/src/services/draftRepository.ts b/src/services/draftRepository.ts
index 35e1c68c4..5623d24bc 100644
--- a/src/services/draftRepository.ts
+++ b/src/services/draftRepository.ts
@@ -4,6 +4,7 @@ import type {
   DraftExport,
   KeyValueStorage,
   ReplaceAllOptions,
+  RepositoryCapabilities,
   WarningLogger,
 } from '../types/analysis-repository';
 import { emptyAnalysis, emptyDraft } from '../types/empty-factories';
@@ -101,6 +102,8 @@ type LoadedShard = {
  * Calls on one instance must not overlap.
  */
 export class DraftRepository implements AnalysisRepository {
+  readonly capabilities: RepositoryCapabilities = { readOnly: false };
+
   private readonly storage: KeyValueStorage;
 
   private readonly logger: WarningLogger;
diff --git a/src/services/projectStorage.ts b/src/services/projectStorage.ts
index 6906c7ffe..e45289c23 100644
--- a/src/services/projectStorage.ts
+++ b/src/services/projectStorage.ts
@@ -7,7 +7,12 @@ import type {
   SegmentationDelta,
   TextAnalysis,
 } from 'interlinearizer';
-import type { DraftExport, KeyValueStorage, ReplaceAllOptions } from '../types/analysis-repository';
+import type {
+  AnalysisRepository,
+  DraftExport,
+  KeyValueStorage,
+  ReplaceAllOptions,
+} from '../types/analysis-repository';
 import { UnreadableBooksError } from '../types/analysis-repository';
 import { emptyAnalysis } from '../types/empty-factories';
 import type { InterlinearProjectSummary } from '../types/interlinear-project-summary';
@@ -17,6 +22,7 @@ import { removeBookFromSegmentation } from '../utils/analysis-book';
 import { reportAnalysisViolations } from '../utils/analysis-violations';
 import { perfTime, perfTimeAsync } from '../utils/perf-marks';
 import { DraftRepository } from './draftRepository';
+import { Pt9ImportRepository } from './pt9ImportRepository';
 import { ProjectSummaries, summarizeProject } from './projectSummaries';
 import { draftKey, projectKey } from './storageKeys';
 
@@ -57,8 +63,8 @@ const projectQueues = new Map<string, Promise<unknown>>();
 const draftQueues = new Map<string, Promise<unknown>>();
 
 /**
- * Each source project's draft repository, kept across calls so a save rewrites only the books that
- * changed since the last load or save.
+ * Each source project's draft repository, kept across calls until released, so a save rewrites only
+ * the books that changed since the last load or save.
  */
 const draftRepositories = new Map<string, DraftRepository>();
 
@@ -1017,9 +1023,7 @@ export async function getDraft(
   token: ExecutionToken,
   sourceProjectId: string,
 ): Promise<DraftExport> {
-  return enqueueSerialized(draftQueues, sourceProjectId, async () => {
-    return draftRepositoryFor(token, sourceProjectId).exportAll();
-  });
+  return openDraftRepository(token, sourceProjectId).exportAll();
 }
 
 /**
@@ -1102,10 +1106,52 @@ export async function saveDraft(
   draft: DraftProject,
   options?: ReplaceAllOptions,
 ): Promise<string[]> {
-  draftWriteCounts.set(sourceProjectId, (draftWriteCounts.get(sourceProjectId) ?? 0) + 1);
   // Invariant violations go unreported here: this runs on every edit, so one would log per keystroke.
-  return enqueueSerialized(draftQueues, sourceProjectId, async () =>
-    draftRepositoryFor(token, sourceProjectId).replaceAll(draft, options),
+  return openDraftRepository(token, sourceProjectId).replaceAll(draft, options);
+}
+
+/**
+ * The source project's draft repository. Each call waits for every draft call already made for that
+ * source, through any handle, so calls never overlap.
+ */
+export function openDraftRepository(
+  token: ExecutionToken,
+  sourceProjectId: string,
+): AnalysisRepository {
+  const queued = <T>(call: (repository: DraftRepository) => Promise<T>) =>
+    enqueueSerialized(draftQueues, sourceProjectId, () =>
+      call(draftRepositoryFor(token, sourceProjectId)),
+    );
+  return {
+    capabilities: { readOnly: false },
+    exportAll: () => queued((repository) => repository.exportAll()),
+    exportForCopy: () => queued((repository) => repository.exportForCopy()),
+    replaceAll: (draft, options) => {
+      draftWriteCounts.set(sourceProjectId, (draftWriteCounts.get(sourceProjectId) ?? 0) + 1);
+      return queued((repository) => repository.replaceAll(draft, options));
+    },
+    markClean: () => queued((repository) => repository.markClean()),
+  };
+}
+
+/**
+ * Releases the source project's draft repository once the draft calls already made for that source
+ * settle. The next call gets a new one, which knows nothing of what the released one loaded or
+ * saved.
+ */
+export function releaseDraftRepository(sourceProjectId: string): Promise<void> {
+  return enqueueSerialized(draftQueues, sourceProjectId, async () => {
+    draftRepositories.delete(sourceProjectId);
+  });
+}
+
+/** A read-only repository over the Paratext 9 import `interlinearProjectId`. */
+export function openPt9ImportRepository(
+  token: ExecutionToken,
+  interlinearProjectId: string,
+): AnalysisRepository {
+  return new Pt9ImportRepository(interlinearProjectId, () =>
+    getProject(token, interlinearProjectId),
   );
 }
 
diff --git a/src/services/pt9ImportRepository.ts b/src/services/pt9ImportRepository.ts
new file mode 100644
index 000000000..90914e600
--- /dev/null
+++ b/src/services/pt9ImportRepository.ts
@@ -0,0 +1,88 @@
+import type { InterlinearProject } from 'interlinearizer';
+import type {
+  AnalysisRepository,
+  DraftExport,
+  RepositoryCapabilities,
+} from '../types/analysis-repository';
+import { CURRENT_MODEL_VERSION } from '../types/model-version';
+import { ReadOnlyAnalysisError } from '../types/read-only-analysis-error';
+
+/**
+ * A Paratext 9 import's analysis, read in a draft's shape. Only a sync replaces an import's
+ * content, so every write is refused.
+ */
+export class Pt9ImportRepository implements AnalysisRepository {
+  readonly capabilities: RepositoryCapabilities = { readOnly: true };
+
+  private readonly interlinearProjectId: string;
+
+  private readonly readProject: () => Promise<InterlinearProject | undefined>;
+
+  /**
+   * @param interlinearProjectId - Id of the project to read, which must be a Paratext 9 import.
+   * @param readProject - Reads the project stored under that id afresh, resolving `undefined` when
+   *   none is stored.
+   */
+  constructor(
+    interlinearProjectId: string,
+    readProject: () => Promise<InterlinearProject | undefined>,
+  ) {
+    this.interlinearProjectId = interlinearProjectId;
+    this.readProject = readProject;
+  }
+
+  /**
+   * Loads the import as a clean draft of its source project, carrying every field the two share. An
+   * import is stored whole, so none of its books goes unread.
+   *
+   * @throws {Error} If no project is stored under the import's id, or the one stored there is not a
+   *   Paratext 9 import.
+   * @throws Whatever reading the project throws.
+   */
+  async exportAll(): Promise<DraftExport> {
+    const project = await this.readProject();
+    if (!project?.pt9Import) {
+      throw new Error(
+        `Interlinearizer: no Paratext 9 import is stored as project ${this.interlinearProjectId}`,
+      );
+    }
+    const { sourceProjectId, analysisLanguages, targetProjectId, analysis, segmentation } = project;
+    return {
+      draft: {
+        sourceProjectId,
+        modelVersion: CURRENT_MODEL_VERSION,
+        analysisLanguages,
+        ...(targetProjectId !== undefined && { targetProjectId }),
+        analysis,
+        dirty: false,
+        ...(segmentation !== undefined && { segmentation }),
+      },
+      unreadableBooks: [],
+    };
+  }
+
+  /**
+   * Loads the import as {@link exportAll} does.
+   *
+   * @throws Whatever {@link exportAll} throws.
+   */
+  exportForCopy(): Promise<DraftExport> {
+    return this.exportAll();
+  }
+
+  /** @throws {ReadOnlyAnalysisError} Always; nothing is written. */
+  async replaceAll(): Promise<string[]> {
+    throw this.readOnlyError();
+  }
+
+  /** @throws {ReadOnlyAnalysisError} Always; nothing is written. */
+  async markClean(): Promise<void> {
+    throw this.readOnlyError();
+  }
+
+  private readOnlyError(): ReadOnlyAnalysisError {
+    return new ReadOnlyAnalysisError(
+      `Interlinearizer: Paratext 9 import ${this.interlinearProjectId} is read-only`,
+    );
+  }
+}
diff --git a/src/types/analysis-repository.ts b/src/types/analysis-repository.ts
index ea40cca45..83460d76b 100644
--- a/src/types/analysis-repository.ts
+++ b/src/types/analysis-repository.ts
@@ -14,6 +14,12 @@ export interface WarningLogger {
   warn(message: string, ...details: unknown[]): void;
 }
 
+/** What an {@link AnalysisRepository} lets its caller do. */
+export interface RepositoryCapabilities {
+  /** Whether every write is refused, as it is for a Paratext 9 import. */
+  readOnly: boolean;
+}
+
 /**
  * Thrown where a draft that could not be read for some books would overwrite stored analysis with
  * only what it could read.
@@ -51,20 +57,25 @@ export type DraftExport = {
 };
 
 /**
- * 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.
- * Once a call settles, the caller may change a draft it passed in or got back without changing what
- * is stored. Lists of records come back in no promised order.
+ * Reads and writes one source project's draft, or reads one Paratext 9 import in a draft's shape.
+ * Every call is async and takes and returns only JSON-plain values, so an implementation may sit
+ * behind a network boundary or another language. Once a call settles, the caller may change a draft
+ * it passed in or got back without changing what is stored. Lists of records come back in no
+ * promised order.
  *
  * Calls for one draft must not overlap, whether on one repository or several. After one repository
  * saves a draft, any other that had already loaded or saved it must load it again before its next
  * save.
  */
 export interface AnalysisRepository {
+  /** Fixed for the repository's lifetime. */
+  readonly capabilities: RepositoryCapabilities;
+
   /**
    * Loads the whole stored draft, or an empty one for the source project when none is stored.
    * Stored content that cannot be read loads as empty, so one damaged record never hides the rest.
    *
+   * @throws {Error} If the repository is read-only and nothing is stored for it to read.
    * @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.
@@ -93,6 +104,7 @@ export interface AnalysisRepository {
    *
    * @returns The books whose analysis in the draft was left out for that reason; empty when the
    *   draft was saved whole.
+   * @throws {ReadOnlyAnalysisError} If the repository is read-only; nothing is written.
    * @throws {Error} If the stored draft was written by a newer build; nothing is written.
    * @throws If storage rejects a read or a write.
    */
@@ -102,6 +114,7 @@ export interface AnalysisRepository {
    * Records the stored draft as saved to its project, leaving its content as it stands. A draft
    * never saved, or already clean, is left alone.
    *
+   * @throws {ReadOnlyAnalysisError} If the repository is read-only; nothing is written.
    * @throws {Error} If the stored draft was written by a newer build, or is unreadable; nothing is
    *   written.
    * @throws If storage rejects a read or a write.
diff --git a/src/types/interlinearizer.d.ts b/src/types/interlinearizer.d.ts
index 9626af962..36e438b67 100644
--- a/src/types/interlinearizer.d.ts
+++ b/src/types/interlinearizer.d.ts
@@ -333,6 +333,36 @@ declare module 'papi-shared-types' {
       discardUnreadable?: boolean,
     ) => Promise<void>;
 
+    /**
+     * Opens a session on the source project's draft, paired with `interlinearProjectId` when given,
+     * or on that project alone, read-only, when it is a Paratext 9 import. Closes the source's
+     * earlier session, if any.
+     *
+     * @returns A JSON string of `{ sessionId, readOnly, hasFreeTranslations }`.
+     * @throws If the source project has no such interlinear project, or its analysis cannot be
+     *   loaded (logged before rethrowing).
+     */
+    'interlinearizer.openSession': (
+      sourceProjectId: string,
+      interlinearProjectId?: string,
+    ) => Promise<string>;
+
+    /**
+     * Closes a session once the commands sent to it settle, refusing any sent after. Send it only
+     * once the session's last save has landed. Closing a session that is not open does nothing.
+     */
+    'interlinearizer.closeSession': (sessionId: string) => Promise<void>;
+
+    /**
+     * Sets the language a session's glosses are read and written in.
+     *
+     * @throws If the session is not open (logged before rethrowing).
+     */
+    'interlinearizer.setAnalysisLanguage': (
+      sessionId: string,
+      analysisLanguage: string,
+    ) => Promise<void>;
+
     /**
      * Turns the extension host's timing entries on or off, discarding any it holds. Off until
      * turned on.
diff --git a/src/types/read-only-analysis-error.ts b/src/types/read-only-analysis-error.ts
new file mode 100644
index 000000000..0888f1473
--- /dev/null
+++ b/src/types/read-only-analysis-error.ts
@@ -0,0 +1,7 @@
+/** Thrown by an edit to analysis that is read-only, as a Paratext 9 import is. */
+export class ReadOnlyAnalysisError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'ReadOnlyAnalysisError';
+  }
+}
diff --git a/src/utils/free-translations.ts b/src/utils/free-translations.ts
new file mode 100644
index 000000000..56a2f103c
--- /dev/null
+++ b/src/utils/free-translations.ts
@@ -0,0 +1,7 @@
+import type { TextAnalysis } from 'interlinearizer';
+import { isEmptyMultiString } from './multi-string';
+
+/** Whether any segment analysis in `analysis` carries a free translation. */
+export function analysisHasFreeTranslations(analysis: TextAnalysis): boolean {
+  return analysis.segmentAnalyses.some((sa) => !isEmptyMultiString(sa.freeTranslation));
+}

From 7c5b6579b4287a22f01fc11eb60f2012d48a674f Mon Sep 17 00:00:00 2001
From: Alex Rawlings <alex.rawlings@wycliffe.ca>
Date: Thu, 22 Oct 2026 13:07:35 -0600
Subject: [PATCH 02/22] Keep unreadable draft shards across a repository
 release

---
 .../services/draftRepository.test.ts          | 11 ++++++
 src/__tests__/services/projectStorage.test.ts | 17 ++++++---
 src/services/draftRepository.ts               | 37 +++++++++++++------
 src/services/projectStorage.ts                |  3 +-
 4 files changed, 49 insertions(+), 19 deletions(-)

diff --git a/src/__tests__/services/draftRepository.test.ts b/src/__tests__/services/draftRepository.test.ts
index bf889a1b7..7fdbbb88f 100644
--- a/src/__tests__/services/draftRepository.test.ts
+++ b/src/__tests__/services/draftRepository.test.ts
@@ -218,6 +218,17 @@ describe('DraftRepository', () => {
       expect(records.get(draftAnalysisKey('src', 'GEN'))).toBe('not json');
     });
 
+    it('keeps an unreadable book when the saving repository never loaded the draft', async () => {
+      const { storage, draft, records } = await loadedWithUnreadableGen();
+
+      await new DraftRepository(storage, 'src', silentLogger()).replaceAll({
+        ...draft,
+        analysis: emptyAnalysis(),
+      });
+
+      expect(records.get(draftAnalysisKey('src', 'GEN'))).toBe('not json');
+    });
+
     it('leaves out the analysis a draft carries for an unreadable book, keeping its shard', async () => {
       const { repository, records } = await loadedWithUnreadableGen();
 
diff --git a/src/__tests__/services/projectStorage.test.ts b/src/__tests__/services/projectStorage.test.ts
index 8c97e0e40..40664973a 100644
--- a/src/__tests__/services/projectStorage.test.ts
+++ b/src/__tests__/services/projectStorage.test.ts
@@ -2915,16 +2915,21 @@ describe('projectStorage', () => {
   describe('releaseDraftRepository', () => {
     beforeEach(() => writeThroughStore());
 
-    it('leaves the next save knowing nothing of storage, so it rewrites every book', async () => {
-      const draft = makeDraftSpanningBooks('src-proj', 'GEN', 'JHN');
-      await saveDraft(token, 'src-proj', draft);
+    it("keeps a shard the released repository's load could not use", async () => {
+      writeThroughStore({
+        'draft:src-proj': JSON.stringify({
+          ...emptyDraft('src-proj'),
+          modelVersion: CURRENT_MODEL_VERSION,
+          analysisBooks: ['GEN'],
+        }),
+        'draft:src-proj:analysis:GEN': 'not json',
+      });
+      const { draft } = await getDraft(token, 'src-proj');
 
       await releaseDraftRepository('src-proj');
-      __mockWriteUserData.mockClear();
       await saveDraft(token, 'src-proj', draft);
 
-      expect(writtenKeys()).toContain('draft:src-proj:analysis:GEN');
-      expect(writtenKeys()).toContain('draft:src-proj:analysis:JHN');
+      expect(__mockDeleteUserData).not.toHaveBeenCalledWith(token, 'draft:src-proj:analysis:GEN');
     });
 
     it('lets a draft call already made finish on the repository it releases', async () => {
diff --git a/src/services/draftRepository.ts b/src/services/draftRepository.ts
index 5623d24bc..7b5c71c8e 100644
--- a/src/services/draftRepository.ts
+++ b/src/services/draftRepository.ts
@@ -122,6 +122,9 @@ export class DraftRepository implements AnalysisRepository {
    */
   private unreadableShards = new Set<string>();
 
+  /** Whether this instance has loaded the stored draft, so it knows which shards it cannot read. */
+  private loaded = false;
+
   constructor(storage: KeyValueStorage, sourceProjectId: string, logger: WarningLogger) {
     this.storage = storage;
     this.logger = logger;
@@ -150,7 +153,9 @@ export class DraftRepository implements AnalysisRepository {
    * @throws If storage rejects a read.
    */
   async exportAll(): Promise<DraftExport> {
-    return this.readDraft(false);
+    const exported = await this.readDraft(false);
+    this.loaded = true;
+    return exported;
   }
 
   /**
@@ -164,7 +169,9 @@ export class DraftRepository implements AnalysisRepository {
    * @throws If storage rejects a read.
    */
   async exportForCopy(): Promise<DraftExport> {
-    return this.readDraft(true);
+    const exported = await this.readDraft(true);
+    this.loaded = true;
+    return exported;
   }
 
   /**
@@ -203,22 +210,30 @@ 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, unless that load could not use the book's shard.
-   * Such a book's shard is kept as it stands, and any analysis the draft carries for the book is
-   * left out rather than written over what could not be read. Starting the draft over, through
-   * `options`, lets the save write or wipe the book like any other.
+   * unless its stored shard cannot be read. Such a book's shard is kept as it stands, and any
+   * analysis the draft carries for the book is left out rather than written over what could not be
+   * read. Starting the draft over, through `options`, lets the save write or wipe the book like any
+   * other.
    *
    * A save that fails leaves no storage call of its own in flight. Once the draft has landed, a
    * wiped book's shard that could not be deleted, or a shard journal that could not be updated, is
    * no failure of the save: each is logged, and a later save retries it.
    *
-   * @returns The books whose analysis in the draft was left out because this instance's load could
-   *   not use their shard; empty when the draft was saved whole.
+   * @returns The books whose analysis in the draft was left out because their stored shard cannot
+   *   be read; empty when the draft was saved whole.
    * @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 read; nothing is written.
    * @throws If storage rejects a write.
    */
   async replaceAll(draft: DraftProject, options?: ReplaceAllOptions): Promise<string[]> {
+    if (!this.loaded) {
+      try {
+        await this.exportAll();
+      } catch (e) {
+        // An unparseable draft names no shard to keep, and this save replaces it.
+        if (!(e instanceof SyntaxError)) throw e;
+      }
+    }
     const { sourceProjectId, storage, shardContents: saved, unreadableShards: unreadable } = this;
     const { analysis } = draft;
     const storedBooks = await perfTimeAsync('saveDraft:read', () =>
@@ -230,8 +245,8 @@ export class DraftRepository implements AnalysisRepository {
     leftOut.forEach((bookCode) => byBook.delete(bookCode));
 
     // 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.
+    // The stored manifest and the journal also list shards the load did not see, such as one
+    // awaiting deletion. A journaled addition whose shard never landed deletes as a no-op.
     const journaled = await perfTimeAsync('saveDraft:read', () => this.readShardJournal());
     const knownShards = new Set([
       ...saved.keys(),
diff --git a/src/services/projectStorage.ts b/src/services/projectStorage.ts
index e45289c23..fdf3ee5ac 100644
--- a/src/services/projectStorage.ts
+++ b/src/services/projectStorage.ts
@@ -1094,8 +1094,7 @@ async function markCopiedDraftClean(
  * @returns The books whose analysis in the draft was left out for that reason; empty when the draft
  *   was saved whole.
  * @throws {Error} If the stored draft was written by a newer build; nothing is written.
- * @throws If `papi.storage.readUserData` rejects for any non-ENOENT reason while checking the
- *   stored draft; nothing is written.
+ * @throws If `papi.storage.readUserData` rejects for any non-ENOENT reason; nothing is written.
  * @throws If `papi.storage.writeUserData` rejects. Once the draft has landed, a wiped book's shard
  *   that could not be deleted, or a shard journal that could not be updated, is no failure of the
  *   save: each is logged, and a later save retries it.

From 5d5d1cf78697fdb4e35d8b74f75d0fa1f0fd4a32 Mon Sep 17 00:00:00 2001
From: Alex Rawlings <alex.rawlings@wycliffe.ca>
Date: Thu, 22 Oct 2026 13:50:42 -0600
Subject: [PATCH 03/22] Clarify session and analysis repository docs

---
 .../services/analysisSessions.parity.test.ts  |  4 +--
 .../services/analysisSessions.test.ts         |  6 ++--
 src/main.ts                                   | 11 ++++----
 src/services/analysisSessions.ts              | 28 +++++++++++--------
 src/services/projectStorage.ts                |  4 +--
 src/services/pt9ImportRepository.ts           |  4 +--
 src/types/analysis-repository.ts              | 18 ++++++------
 src/types/interlinearizer.d.ts                | 10 +++----
 8 files changed, 45 insertions(+), 40 deletions(-)

diff --git a/src/__tests__/services/analysisSessions.parity.test.ts b/src/__tests__/services/analysisSessions.parity.test.ts
index 536524f03..19ca95bd4 100644
--- a/src/__tests__/services/analysisSessions.parity.test.ts
+++ b/src/__tests__/services/analysisSessions.parity.test.ts
@@ -10,9 +10,9 @@ const SOURCE = 'src-project';
 
 describe('setAnalysisLanguage parity with the reducer', () => {
   it.each([
-    ['a language its scope lists after the first', 'en'],
+    ['a language its draft lists after the first', 'en'],
     ['the language it is already on', 'fr'],
-    ['a language its scope does not list', 'de'],
+    ['a language its draft does not list', 'de'],
   ])('sets %s as the reducer does, storing nothing', async (_case, tag) => {
     const { storage, writes } = memoryStorage();
     const logger = silentLogger();
diff --git a/src/__tests__/services/analysisSessions.test.ts b/src/__tests__/services/analysisSessions.test.ts
index aaf4d6b65..b3d0f7d35 100644
--- a/src/__tests__/services/analysisSessions.test.ts
+++ b/src/__tests__/services/analysisSessions.test.ts
@@ -145,7 +145,7 @@ describe('AnalysisSessions', () => {
       await expect(sessions.open(SOURCE)).resolves.toMatchObject({ readOnly: false });
     });
 
-    it('starts on the first analysis language its scope lists', async () => {
+    it('starts on the first analysis language its draft lists', async () => {
       const { host, sessions, saveDraft } = makeSessions();
       await saveDraft({ ...emptyDraft(SOURCE), analysisLanguages: ['fr', 'en'] });
 
@@ -157,7 +157,7 @@ describe('AnalysisSessions', () => {
       expect(host.getInterfaceLanguages).not.toHaveBeenCalled();
     });
 
-    it('starts on the first interface language when its scope lists none', async () => {
+    it('starts on the first interface language when its draft lists none', async () => {
       const { host, sessions } = makeSessions();
       host.getInterfaceLanguages.mockResolvedValue(['de', 'en']);
 
@@ -168,7 +168,7 @@ describe('AnalysisSessions', () => {
       ).resolves.toBe('de');
     });
 
-    it('starts on the undetermined language when neither its scope nor the platform lists one', async () => {
+    it('starts on the undetermined language when neither its draft nor the platform lists one', async () => {
       const { sessions } = makeSessions();
 
       const { sessionId } = await sessions.open(SOURCE);
diff --git a/src/main.ts b/src/main.ts
index 9c6ff232f..b4a03b466 100644
--- a/src/main.ts
+++ b/src/main.ts
@@ -738,11 +738,11 @@ async function saveInterlinearDraft(
 }
 
 /**
- * Opens a session on the source project's draft, paired with `interlinearProjectId` when given, or
- * on that project alone, read-only, when it is a Paratext 9 import. Closes the source's earlier
- * session, if any.
+ * Opens a session read-only on `interlinearProjectId` when it names a Paratext 9 import, otherwise
+ * on the source project's draft, which saves to `interlinearProjectId` when given. Closes the
+ * source's earlier session, if any.
  *
- * @returns A JSON string of `{ sessionId, readOnly, hasFreeTranslations }`.
+ * @returns A JSON string of what {@link AnalysisSessions.open} resolves to.
  * @throws If the source project has no such interlinear project, or its analysis cannot be loaded.
  *   The error is logged before rethrowing.
  */
@@ -1319,8 +1319,7 @@ export async function activate(context: ExecutionActivationContext): Promise<voi
     (sessionId: string) => sessions.close(sessionId),
     {
       method: {
-        summary:
-          "Close a session once the commands sent to it settle; send it only after the session's last save",
+        summary: 'Close a session once the commands sent to it settle',
         params: [sessionIdParam],
         result: { name: 'return value', summary: 'void', schema: { type: 'null' } },
       },
diff --git a/src/services/analysisSessions.ts b/src/services/analysisSessions.ts
index a0ea586ab..176121682 100644
--- a/src/services/analysisSessions.ts
+++ b/src/services/analysisSessions.ts
@@ -29,7 +29,7 @@ export type OpenedSession = {
   hasFreeTranslations: boolean;
 };
 
-/** An open session, as the commands run on it see it. */
+/** An open session, as seen by the commands sent to it. */
 export type Session = {
   readonly id: string;
   readonly scope: SessionScope;
@@ -48,7 +48,10 @@ export interface SessionHost {
     sourceProjectId: string,
     interlinearProjectId: string,
   ): Promise<InterlinearProjectSummary | undefined>;
-  /** The source project's draft repository, shared with every other reader and writer of its draft. */
+  /**
+   * The source project's draft repository. Every handle for a source reaches the same repository,
+   * one call at a time.
+   */
   openDraftRepository(sourceProjectId: string): AnalysisRepository;
   /** Releases the source project's draft repository once the calls already queued on it settle. */
   releaseDraftRepository(sourceProjectId: string): Promise<void>;
@@ -88,13 +91,14 @@ export class AnalysisSessions {
   }
 
   /**
-   * Opens a session on the source project's draft, paired with `interlinearProjectId` when given,
-   * or on that project alone, read-only, when it is a Paratext 9 import. Opening closes the
-   * source's earlier session, if any, and starts the new one on what storage holds.
+   * Opens a session read-only on `interlinearProjectId` when it names a Paratext 9 import,
+   * otherwise on the source project's draft, which saves to `interlinearProjectId` when given.
+   * Opening closes the source's earlier session, if any, and starts the new one on what storage
+   * holds.
    *
-   * The session starts on its scope's first analysis language. When the scope lists none, it starts
-   * on the platform's first interface language, or {@link UNDETERMINED_LANGUAGE} when the platform
-   * lists none either.
+   * The session starts on the opened draft's first analysis language. When the draft lists none, it
+   * starts on the platform's first interface language, or {@link UNDETERMINED_LANGUAGE} when the
+   * platform lists none either.
    *
    * @throws {Error} If the source project has no interlinear project `interlinearProjectId`.
    * @throws Whatever finding the project or loading the scope's analysis throws; the source is left
@@ -151,7 +155,7 @@ export class AnalysisSessions {
 
   /**
    * Sets the language that the session's glosses are read and written in, unchecked against the
-   * languages its scope lists. A read-only session takes it too, since it changes nothing stored.
+   * languages its draft lists. A read-only session takes it too, since it changes nothing stored.
    *
    * @throws {Error} If the session is not open.
    */
@@ -218,9 +222,9 @@ export class AnalysisSessions {
   }
 
   /**
-   * Stops addressing the session, then releases its repository once the commands sent to it have
-   * settled. A session that an earlier step already closed is left alone, so its repository is
-   * released only once.
+   * Makes the session unreachable by id or source, then, for a draft, releases its repository once
+   * the commands sent to it have settled. A session that an earlier step already closed is left
+   * alone, so its repository is released only once.
    */
   private async closeNow(entry: OpenSession): Promise<void> {
     const { id, scope } = entry.session;
diff --git a/src/services/projectStorage.ts b/src/services/projectStorage.ts
index fdf3ee5ac..193cd1be5 100644
--- a/src/services/projectStorage.ts
+++ b/src/services/projectStorage.ts
@@ -1110,8 +1110,8 @@ export async function saveDraft(
 }
 
 /**
- * The source project's draft repository. Each call waits for every draft call already made for that
- * source, through any handle, so calls never overlap.
+ * The source project's draft repository. Calls on it wait for every draft call already made for
+ * that source, through any handle, so calls never overlap.
  */
 export function openDraftRepository(
   token: ExecutionToken,
diff --git a/src/services/pt9ImportRepository.ts b/src/services/pt9ImportRepository.ts
index 90914e600..33114f202 100644
--- a/src/services/pt9ImportRepository.ts
+++ b/src/services/pt9ImportRepository.ts
@@ -32,8 +32,8 @@ export class Pt9ImportRepository implements AnalysisRepository {
   }
 
   /**
-   * Loads the import as a clean draft of its source project, carrying every field the two share. An
-   * import is stored whole, so none of its books goes unread.
+   * Loads the import as a clean draft of its source project, carrying every field the two share. It
+   * reports no unreadable books, since an import is stored whole.
    *
    * @throws {Error} If no project is stored under the import's id, or the one stored there is not a
    *   Paratext 9 import.
diff --git a/src/types/analysis-repository.ts b/src/types/analysis-repository.ts
index 83460d76b..27014f1c9 100644
--- a/src/types/analysis-repository.ts
+++ b/src/types/analysis-repository.ts
@@ -57,10 +57,10 @@ export type DraftExport = {
 };
 
 /**
- * Reads and writes one source project's draft, or reads one Paratext 9 import in a draft's shape.
- * Every call is async and takes and returns only JSON-plain values, so an implementation may sit
- * behind a network boundary or another language. Once a call settles, the caller may change a draft
- * it passed in or got back without changing what is stored. Lists of records come back in no
+ * Reads and writes one source project's draft, or, when read-only, reads analysis in a draft's
+ * shape. Every call is async and takes and returns only JSON-plain values, so an implementation may
+ * sit behind a network boundary or another language. Once a call settles, the caller may change a
+ * draft it passed in or got back without changing what is stored. Lists of records come back in no
  * promised order.
  *
  * Calls for one draft must not overlap, whether on one repository or several. After one repository
@@ -72,8 +72,9 @@ export interface AnalysisRepository {
   readonly capabilities: RepositoryCapabilities;
 
   /**
-   * Loads the whole stored draft, or an empty one for the source project when none is stored.
-   * Stored content that cannot be read loads as empty, so one damaged record never hides the rest.
+   * Loads the whole stored draft, or, from a writable repository, an empty one for the source
+   * project when none is stored. Stored content that cannot be read loads as empty, so one damaged
+   * record never hides the rest.
    *
    * @throws {Error} If the repository is read-only and nothing is stored for it to read.
    * @throws {SyntaxError} If the draft's stored value contains invalid JSON.
@@ -83,9 +84,10 @@ export interface AnalysisRepository {
   exportAll(): Promise<DraftExport>;
 
   /**
-   * Loads the whole stored draft for copying into a project, or an empty one for the source project
-   * when none is stored.
+   * Loads the whole stored draft for copying into a project, or, from a writable repository, an
+   * empty one for the source project when none is stored.
    *
+   * @throws {Error} If the repository is read-only and nothing is stored for it to read.
    * @throws {SyntaxError} If the draft's stored value contains invalid JSON.
    * @throws {Error} If the stored draft was written by a newer build.
    * @throws {Error} If the draft itself is unreadable, so no book in it can be vouched for.
diff --git a/src/types/interlinearizer.d.ts b/src/types/interlinearizer.d.ts
index 36e438b67..5177060be 100644
--- a/src/types/interlinearizer.d.ts
+++ b/src/types/interlinearizer.d.ts
@@ -334,9 +334,9 @@ declare module 'papi-shared-types' {
     ) => Promise<void>;
 
     /**
-     * Opens a session on the source project's draft, paired with `interlinearProjectId` when given,
-     * or on that project alone, read-only, when it is a Paratext 9 import. Closes the source's
-     * earlier session, if any.
+     * Opens a session read-only on `interlinearProjectId` when it names a Paratext 9 import,
+     * otherwise on the source project's draft, which saves to `interlinearProjectId` when given.
+     * Closes the source's earlier session, if any.
      *
      * @returns A JSON string of `{ sessionId, readOnly, hasFreeTranslations }`.
      * @throws If the source project has no such interlinear project, or its analysis cannot be
@@ -348,8 +348,8 @@ declare module 'papi-shared-types' {
     ) => Promise<string>;
 
     /**
-     * Closes a session once the commands sent to it settle, refusing any sent after. Send it only
-     * once the session's last save has landed. Closing a session that is not open does nothing.
+     * Closes a session once the commands sent to it settle, refusing any sent after. Closing a
+     * session that is not open does nothing.
      */
     'interlinearizer.closeSession': (sessionId: string) => Promise<void>;
 

From a64ac261d16fdd1a110a31d77e1d75f73b45a171 Mon Sep 17 00:00:00 2001
From: Alex Rawlings <alex.rawlings@wycliffe.ca>
Date: Thu, 22 Oct 2026 09:55:36 -0600
Subject: [PATCH 04/22] Add apply with inverse capture and per-session undo
 (#441)

---
 AGENTS.md                                     |   2 +-
 .../analysis-repository-conformance.ts        | 420 +++++++++++++++++-
 src/__tests__/main.test.ts                    |  62 +++
 .../services/analysisSessions.test.ts         |  51 +++
 .../services/draftRepository.test.ts          | 129 ++++++
 src/__tests__/services/editHistory.test.ts    | 122 +++++
 src/__tests__/services/projectStorage.test.ts |  32 ++
 .../services/pt9ImportRepository.test.ts      |  12 +
 src/__tests__/utils/change-set.test.ts        | 197 ++++++++
 src/main.ts                                   |  67 +++
 src/services/analysisSessions.ts              |  32 +-
 src/services/draftRepository.ts               |  55 +++
 src/services/editHistory.ts                   |  60 +++
 src/services/projectStorage.ts                |  11 +-
 src/services/pt9ImportRepository.ts           |   6 +
 src/types/analysis-repository.ts              |  48 +-
 src/types/interlinearizer.d.ts                |  18 +
 src/utils/change-set.ts                       | 140 ++++++
 18 files changed, 1455 insertions(+), 9 deletions(-)
 create mode 100644 src/__tests__/services/editHistory.test.ts
 create mode 100644 src/__tests__/utils/change-set.test.ts
 create mode 100644 src/services/editHistory.ts
 create mode 100644 src/utils/change-set.ts

diff --git a/AGENTS.md b/AGENTS.md
index 12823d9a8..1a3163569 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -85,7 +85,7 @@ Saved projects are listed through [ProjectSummaries](src/services/projectSummari
 
 ### Sessions
 
-[AnalysisSessions](src/services/analysisSessions.ts) keeps the host's sessions, behind the `openSession`, `closeSession` and `setAnalysisLanguage` commands. A session is a handle on one source project's draft, paired with the interlinear project it saves to, or on a Paratext 9 import alone, read-only. A source has at most one session: opening another closes it. Each session runs its commands one at a time, through `run`, or `runEdit` for a command that changes stored analysis, which a read-only session refuses. The WebView doesn't use sessions yet.
+[AnalysisSessions](src/services/analysisSessions.ts) keeps the host's sessions, behind the `openSession`, `closeSession` and `setAnalysisLanguage` commands. A session is a handle on one source project's draft, paired with the interlinear project it saves to, or on a Paratext 9 import alone, read-only. A source has at most one session: opening another closes it. Each session runs its commands one at a time, through `run`, or `runEdit` for a command that changes stored analysis, which a read-only session refuses. An edit reaches the repository as a `ChangeSet` of whole-record puts and deletes, applied through the session's [EditHistory](src/services/editHistory.ts) so that undo can revert it; boundary changes ride in the change set's scope record. The WebView doesn't use sessions yet.
 
 ### Components
 
diff --git a/src/__tests__/analysis-repository-conformance.ts b/src/__tests__/analysis-repository-conformance.ts
index ca12e8f5b..455e8e1f0 100644
--- a/src/__tests__/analysis-repository-conformance.ts
+++ b/src/__tests__/analysis-repository-conformance.ts
@@ -1,10 +1,11 @@
 /// <reference types="jest" />
 
 import type { DraftProject, TextAnalysis } from 'interlinearizer';
-import type { AnalysisRepository, DraftExport } from '../types/analysis-repository';
+import type { AnalysisRepository, ChangeSet, DraftExport } from '../types/analysis-repository';
 import { emptyAnalysis, emptyDraft } from '../types/empty-factories';
 import { CURRENT_MODEL_VERSION } from '../types/model-version';
 import { ReadOnlyAnalysisError } from '../types/read-only-analysis-error';
+import { scopeRecordOf } from '../utils/change-set';
 import { FIXTURE_STAMPS, makePhraseLink } from './test-helpers';
 
 /** One empty store an {@link AnalysisRepository} implementation keeps drafts in. */
@@ -203,6 +204,99 @@ function fullDraftWithoutGenesis(): DraftProject {
   };
 }
 
+/** One record of every kind in GEN, none of which {@link fullDraft} holds. */
+function newRecords() {
+  return {
+    segmentAnalyses: [
+      {
+        id: 'sa-gen',
+        ...FIXTURE_STAMPS,
+        surfaceText: 'In the beginning',
+        freeTranslation: { en: 'At first' },
+      },
+    ],
+    segmentAnalysisLinks: [
+      {
+        id: 'sl-gen',
+        analysisId: 'sa-gen',
+        ...FIXTURE_STAMPS,
+        status: 'approved' as const,
+        segmentId: 'GEN 1:1',
+      },
+    ],
+    tokenAnalyses: [{ id: 'ta-god', ...FIXTURE_STAMPS, surfaceText: 'God', gloss: { en: 'God' } }],
+    tokenAnalysisLinks: [tokenLink('tl-gen-god', 'ta-god', 'GEN 1:1:17', 'God')],
+    phraseAnalyses: [
+      {
+        id: 'pa-the-beginning',
+        ...FIXTURE_STAMPS,
+        surfaceText: 'the beginning',
+        gloss: { en: 'start' },
+      },
+    ],
+    phraseAnalysisLinks: [
+      makePhraseLink('pa-the-beginning', ['GEN 1:1:9', 'GEN 1:1:13'], ['the', 'beginning']),
+    ],
+  };
+}
+
+/** Puts {@link newRecords}, one list per record kind. */
+function puttingNewRecords(): ChangeSet {
+  const records = newRecords();
+  return {
+    intent: 'putNewRecords',
+    segmentAnalyses: { puts: records.segmentAnalyses, deletes: [] },
+    segmentAnalysisLinks: { puts: records.segmentAnalysisLinks, deletes: [] },
+    tokenAnalyses: { puts: records.tokenAnalyses, deletes: [] },
+    tokenAnalysisLinks: { puts: records.tokenAnalysisLinks, deletes: [] },
+    phraseAnalyses: { puts: records.phraseAnalyses, deletes: [] },
+    phraseAnalysisLinks: { puts: records.phraseAnalysisLinks, deletes: [] },
+  };
+}
+
+/** {@link fullDraft} holding {@link newRecords} as well. */
+function fullDraftWithNewRecords(): DraftProject {
+  const draft = fullDraft();
+  const records = newRecords();
+  const { analysis } = draft;
+  analysis.segmentAnalyses.push(...records.segmentAnalyses);
+  analysis.segmentAnalysisLinks.push(...records.segmentAnalysisLinks);
+  analysis.tokenAnalyses.push(...records.tokenAnalyses);
+  analysis.tokenAnalysisLinks.push(...records.tokenAnalysisLinks);
+  analysis.phraseAnalyses.push(...records.phraseAnalyses);
+  analysis.phraseAnalysisLinks.push(...records.phraseAnalysisLinks);
+  return draft;
+}
+
+/**
+ * Changes to {@link fullDraft} of every sort: new records and deleted ones in every kind, a replaced
+ * payload, and new boundaries in the scope's record.
+ */
+function mixedChanges(): ChangeSet {
+  const { analysis } = fullDraft();
+  const records = newRecords();
+  return {
+    intent: 'mixedChanges',
+    scope: {
+      ...scopeRecordOf(fullDraft()),
+      dirty: false,
+      segmentation: {
+        removedVerseStarts: [],
+        addedStarts: [{ tokenRef: 'GEN 1:1:9', surfaceText: 'beginning' }],
+      },
+    },
+    segmentAnalyses: { puts: records.segmentAnalyses, deletes: ['sa-exo'] },
+    segmentAnalysisLinks: { puts: records.segmentAnalysisLinks, deletes: ['sl-exo'] },
+    tokenAnalyses: {
+      puts: [{ ...analysis.tokenAnalyses[0], gloss: { en: 'and then' } }, ...records.tokenAnalyses],
+      deletes: ['ta-unlinked'],
+    },
+    tokenAnalysisLinks: { puts: records.tokenAnalysisLinks, deletes: ['tl-gen-beginning'] },
+    phraseAnalyses: { puts: records.phraseAnalyses, deletes: ['pa-in-the'] },
+    phraseAnalysisLinks: { puts: records.phraseAnalysisLinks, deletes: ['pa-in-the'] },
+  };
+}
+
 /**
  * The draft with each record list sorted by id. Lists of records promise no order, but the arrays
  * inside a record keep theirs.
@@ -689,6 +783,320 @@ export function describeAnalysisRepositoryConformance(
       });
     });
 
+    describe('apply', () => {
+      it('puts new records of every kind, for the same repository and a newly opened one to load', async () => {
+        const repository = await store.open(SOURCE);
+        await repository.replaceAll(fullDraft());
+
+        await repository.apply(puttingNewRecords());
+
+        await expect(load(repository)).resolves.toStrictEqual(inIdOrder(fullDraftWithNewRecords()));
+        await expect(reload(store)).resolves.toStrictEqual(inIdOrder(fullDraftWithNewRecords()));
+      });
+
+      it('replaces a stored record whole, dropping fields the put lacks', async () => {
+        const repository = await store.open(SOURCE);
+        await repository.replaceAll(fullDraft());
+        const bare = { id: 'ta-beginning', ...FIXTURE_STAMPS, surfaceText: 'beginning' };
+
+        await repository.apply({ intent: 'replace', tokenAnalyses: { puts: [bare], deletes: [] } });
+
+        const { analysis } = await reload(store);
+        expect(analysis.tokenAnalyses.find(({ id }) => id === 'ta-beginning')).toStrictEqual(bare);
+      });
+
+      it('deletes records of every kind', async () => {
+        const repository = await store.open(SOURCE);
+        await repository.replaceAll(fullDraft());
+
+        await repository.apply({
+          intent: 'deleteExodus',
+          segmentAnalyses: { puts: [], deletes: ['sa-exo'] },
+          segmentAnalysisLinks: { puts: [], deletes: ['sl-exo'] },
+          tokenAnalysisLinks: { puts: [], deletes: ['tl-exo-and'] },
+        });
+
+        await expect(reload(store)).resolves.toStrictEqual(
+          inIdOrder({
+            ...fullDraft(),
+            analysis: {
+              ...fullAnalysis(),
+              segmentAnalyses: [],
+              segmentAnalysisLinks: [],
+              tokenAnalysisLinks: fullAnalysis().tokenAnalysisLinks.filter(
+                ({ id }) => id !== 'tl-exo-and',
+              ),
+            },
+          }),
+        );
+      });
+
+      it('skips a delete of a record that is not stored, with nothing for its inverse to restore', async () => {
+        const repository = await store.open(SOURCE);
+        await repository.replaceAll(fullDraft());
+
+        const { inverse } = await repository.apply({
+          intent: 'deleteMissing',
+          tokenAnalyses: { puts: [], deletes: ['ta-missing'] },
+        });
+
+        expect(inverse).toStrictEqual({ intent: 'deleteMissing' });
+        await expect(reload(store)).resolves.toStrictEqual(inIdOrder(fullDraft()));
+      });
+
+      it('applies to a draft this repository never loaded', async () => {
+        await (await store.open(SOURCE)).replaceAll(fullDraft());
+
+        await (await store.open(SOURCE)).apply(puttingNewRecords());
+
+        await expect(reload(store)).resolves.toStrictEqual(inIdOrder(fullDraftWithNewRecords()));
+      });
+
+      it('applies to a draft never saved as to an empty one', async () => {
+        await (await store.open(SOURCE)).apply(puttingNewRecords());
+
+        await expect(reload(store)).resolves.toStrictEqual(
+          inIdOrder({ ...emptyDraft(SOURCE), analysis: { ...emptyAnalysis(), ...newRecords() } }),
+        );
+      });
+
+      it('builds each apply on the one before it', async () => {
+        const repository = await store.open(SOURCE);
+        const { tokenAnalyses, tokenAnalysisLinks } = newRecords();
+
+        await repository.apply({
+          intent: 'first',
+          tokenAnalyses: { puts: tokenAnalyses, deletes: [] },
+        });
+        await repository.apply({
+          intent: 'second',
+          tokenAnalysisLinks: { puts: tokenAnalysisLinks, deletes: [] },
+        });
+
+        await expect(reload(store)).resolves.toStrictEqual(
+          inIdOrder({
+            ...emptyDraft(SOURCE),
+            analysis: { ...emptyAnalysis(), tokenAnalyses, tokenAnalysisLinks },
+          }),
+        );
+      });
+
+      it('builds on a whole save made since the last apply', async () => {
+        const repository = await store.open(SOURCE);
+        await repository.apply(puttingNewRecords());
+        await repository.replaceAll(fullDraft());
+
+        await repository.apply({
+          intent: 'deleteUnlinked',
+          tokenAnalyses: { puts: [], deletes: ['ta-unlinked'] },
+        });
+
+        await expect(reload(store)).resolves.toStrictEqual(
+          inIdOrder({
+            ...fullDraft(),
+            analysis: {
+              ...fullAnalysis(),
+              tokenAnalyses: fullAnalysis().tokenAnalyses.filter(({ id }) => id !== 'ta-unlinked'),
+            },
+          }),
+        );
+      });
+
+      it('applies over a draft another repository replaced, once reloaded', async () => {
+        const repository = await store.open(SOURCE);
+        await repository.apply(puttingNewRecords());
+        await (await store.open(SOURCE)).replaceAll(fullDraft());
+        await repository.exportAll();
+
+        await repository.apply({
+          intent: 'deleteUnlinked',
+          tokenAnalyses: { puts: [], deletes: ['ta-unlinked'] },
+        });
+
+        await expect(reload(store)).resolves.toStrictEqual(
+          inIdOrder({
+            ...fullDraft(),
+            analysis: {
+              ...fullAnalysis(),
+              tokenAnalyses: fullAnalysis().tokenAnalyses.filter(({ id }) => id !== 'ta-unlinked'),
+            },
+          }),
+        );
+      });
+
+      it('saves an edit to a payload linked from several books, for both books to load', async () => {
+        const repository = await store.open(SOURCE);
+        await repository.replaceAll(fullDraft());
+        const edited = { ...fullAnalysis().tokenAnalyses[0], gloss: { en: 'and then' } };
+
+        await repository.apply({
+          intent: 'writeGloss',
+          tokenAnalyses: { puts: [edited], deletes: [] },
+        });
+
+        const { analysis } = await reload(store);
+        expect(analysis.tokenAnalyses.filter(({ id }) => id === 'ta-and')).toStrictEqual([edited]);
+        expect(
+          analysis.tokenAnalysisLinks.filter(({ analysisId }) => analysisId === 'ta-and'),
+        ).toHaveLength(2);
+      });
+
+      it("carries boundary changes in the scope's record", async () => {
+        const repository = await store.open(SOURCE);
+        await repository.replaceAll(fullDraft());
+        const segmentation = {
+          removedVerseStarts: [],
+          addedStarts: [{ tokenRef: 'GEN 1:1:9', surfaceText: 'beginning' }],
+        };
+
+        await repository.apply({
+          intent: 'splitSegment',
+          scope: { ...scopeRecordOf(fullDraft()), segmentation },
+        });
+
+        await expect(reload(store)).resolves.toStrictEqual(
+          inIdOrder({ ...fullDraft(), segmentation }),
+        );
+      });
+
+      it("clears the boundaries when the scope's record carries none", async () => {
+        const repository = await store.open(SOURCE);
+        await repository.replaceAll(fullDraft());
+        const { segmentation, ...withoutBoundaries } = scopeRecordOf(fullDraft());
+
+        await repository.apply({ intent: 'resetBoundaries', scope: withoutBoundaries });
+
+        const reloaded = await reload(store);
+        expect(segmentation).toBeDefined();
+        expect(reloaded).not.toHaveProperty('segmentation');
+      });
+
+      it('stamps what it applies with the current model version', async () => {
+        await (
+          await store.open(SOURCE)
+        ).apply({
+          intent: 'stamp',
+          scope: { ...scopeRecordOf(fullDraft()), modelVersion: CURRENT_MODEL_VERSION - 1 },
+        });
+
+        const { modelVersion } = await reload(store);
+
+        expect(modelVersion).toBe(CURRENT_MODEL_VERSION);
+      });
+
+      it('returns an inverse that undoes the changes, boundaries included', async () => {
+        const repository = await store.open(SOURCE);
+        await repository.replaceAll(fullDraft());
+
+        const { inverse } = await repository.apply(mixedChanges());
+        await repository.apply(inverse);
+
+        await expect(reload(store)).resolves.toStrictEqual(inIdOrder(fullDraft()));
+      });
+
+      it("redoes the changes when the inverse's inverse is applied", async () => {
+        const repository = await store.open(SOURCE);
+        await repository.replaceAll(fullDraft());
+        const { inverse } = await repository.apply(mixedChanges());
+        const changed = await reload(store);
+        const { inverse: redo } = await repository.apply(inverse);
+
+        await repository.apply(redo);
+
+        await expect(reload(store)).resolves.toStrictEqual(changed);
+      });
+
+      it('undoes the changes through a newly opened repository', async () => {
+        await (await store.open(SOURCE)).replaceAll(fullDraft());
+        const { inverse } = await (await store.open(SOURCE)).apply(mixedChanges());
+
+        await (await store.open(SOURCE)).apply(inverse);
+
+        await expect(reload(store)).resolves.toStrictEqual(inIdOrder(fullDraft()));
+      });
+
+      it('names the intent of the changes in their inverse, as JSON-plain values', async () => {
+        const repository = await store.open(SOURCE);
+        await repository.replaceAll(fullDraft());
+
+        const { inverse } = await repository.apply(mixedChanges());
+
+        expect(inverse.intent).toBe('mixedChanges');
+        expectJsonPlain(inverse);
+      });
+
+      it('stores what it was given, unaffected by later changes to the changes or their inverse', async () => {
+        const repository = await store.open(SOURCE);
+        const changes = puttingNewRecords();
+        const { inverse } = await repository.apply(changes);
+        const applied = await reload(store);
+
+        changes.tokenAnalyses?.puts.push({
+          id: 'ta-later',
+          ...FIXTURE_STAMPS,
+          surfaceText: 'later',
+        });
+        inverse.tokenAnalyses?.deletes.push('ta-later');
+        const [god] = changes.tokenAnalyses?.puts ?? [];
+        god.surfaceText = 'changed';
+
+        await expect(load(repository)).resolves.toStrictEqual(applied);
+        await repository.apply({ intent: 'nothing' });
+        await expect(reload(store)).resolves.toStrictEqual(applied);
+      });
+
+      it('refuses an id named twice in one record kind, applying nothing', async () => {
+        const repository = await store.open(SOURCE);
+        await repository.replaceAll(fullDraft());
+        const [and] = fullAnalysis().tokenAnalyses;
+
+        await expect(
+          repository.apply({
+            intent: 'conflicting',
+            tokenAnalyses: { puts: [{ ...and, gloss: { en: 'also' } }], deletes: ['ta-and'] },
+          }),
+        ).rejects.toThrow();
+
+        await expect(load(repository)).resolves.toStrictEqual(inIdOrder(fullDraft()));
+      });
+
+      it("refuses a scope's record of another source project, applying nothing", async () => {
+        const repository = await store.open(SOURCE);
+        await repository.replaceAll(fullDraft());
+
+        await expect(
+          repository.apply({
+            intent: 'wrongScope',
+            scope: { ...scopeRecordOf(fullDraft()), sourceProjectId: 'other-project' },
+          }),
+        ).rejects.toThrow();
+
+        await expect(reload(store)).resolves.toStrictEqual(inIdOrder(fullDraft()));
+      });
+
+      it('keeps the drafts of different source projects apart', async () => {
+        await (await store.open(SOURCE)).replaceAll(fullDraft());
+
+        await (await store.open('other-project')).apply(puttingNewRecords());
+
+        await expect(reload(store)).resolves.toStrictEqual(inIdOrder(fullDraft()));
+        await expect(reload(store, 'other-project')).resolves.toStrictEqual(
+          inIdOrder({
+            ...emptyDraft('other-project'),
+            analysis: { ...emptyAnalysis(), ...newRecords() },
+          }),
+        );
+      });
+
+      it('leaves a draft written by a newer build in place, refusing to apply over it', async () => {
+        await store.storeNewerBuildDraft(SOURCE);
+
+        await expect((await store.open(SOURCE)).apply(puttingNewRecords())).rejects.toThrow();
+
+        await expect((await store.open(SOURCE)).exportAll()).rejects.toThrow();
+      });
+    });
+
     describe('capabilities', () => {
       it("lets a source project's draft be written", async () => {
         expect((await store.open(SOURCE)).capabilities.readOnly).toBe(false);
@@ -755,6 +1163,16 @@ export function describeAnalysisRepositoryConformance(
         await expect(repository.markClean()).rejects.toThrow(ReadOnlyAnalysisError);
       });
 
+      it('refuses to apply changes, leaving what it loads unchanged', async () => {
+        const repository = await store.openReadOnly(fullDraft());
+
+        await expect(repository.apply(puttingNewRecords())).rejects.toThrow(ReadOnlyAnalysisError);
+
+        await expect(analysisOf(repository)).resolves.toStrictEqual(
+          inIdOrder(fullDraft()).analysis,
+        );
+      });
+
       it("keeps apart from the source project's draft", async () => {
         await (await store.open(SOURCE)).replaceAll(exodusOnlyDraft());
 
diff --git a/src/__tests__/main.test.ts b/src/__tests__/main.test.ts
index ca39346ab..5d00fe95b 100644
--- a/src/__tests__/main.test.ts
+++ b/src/__tests__/main.test.ts
@@ -5,6 +5,7 @@ import papiBackendMock from '@papi/backend';
 import { activate, deactivate } from '@main';
 import type { InterlinearizerOpenOptions } from '@main';
 import type { DraftProject, ProjectConfig } from 'interlinearizer';
+import { AnalysisSessions } from '../services/analysisSessions';
 import * as bookService from '../services/bookService';
 import * as hostPerf from '../services/hostPerf';
 import * as projectStorage from '../services/projectStorage';
@@ -397,6 +398,8 @@ describe('main', () => {
           'interlinearizer.openSession',
           'interlinearizer.closeSession',
           'interlinearizer.setAnalysisLanguage',
+          'interlinearizer.undoEdit',
+          'interlinearizer.redoEdit',
           'interlinearizer.openSelectProjectModal',
           'interlinearizer.openNewProjectModal',
           'interlinearizer.openProjectInfoModal',
@@ -1830,6 +1833,7 @@ describe('main', () => {
         exportForCopy: async () => ({ draft, unreadableBooks: [] }),
         replaceAll: async () => [],
         markClean: async () => {},
+        apply: async (changes) => ({ inverse: changes }),
       };
     }
 
@@ -1850,6 +1854,12 @@ describe('main', () => {
         setAnalysisLanguage: handler<
           (sessionId: string, analysisLanguage: string) => Promise<void>
         >('interlinearizer.setAnalysisLanguage'),
+        undoEdit: handler<(sessionId: string) => Promise<string | undefined>>(
+          'interlinearizer.undoEdit',
+        ),
+        redoEdit: handler<(sessionId: string) => Promise<string | undefined>>(
+          'interlinearizer.redoEdit',
+        ),
       };
     }
 
@@ -1960,6 +1970,58 @@ describe('main', () => {
       );
     });
 
+    it('replies to an undo with the changes it applied', async () => {
+      const reverted = { intent: 'writeGloss', tokenAnalyses: { puts: [], deletes: ['ta-1'] } };
+      jest.spyOn(AnalysisSessions.prototype, 'undo').mockResolvedValue(reverted);
+      const { undoEdit } = await activateSessionCommands();
+
+      await expect(undoEdit('session-id')).resolves.toBe(JSON.stringify(reverted));
+      expect(AnalysisSessions.prototype.undo).toHaveBeenCalledWith('session-id');
+    });
+
+    it('replies to an undo with nothing when there is no edit to undo', async () => {
+      const { openSession, undoEdit } = await activateSessionCommands();
+      const { sessionId } = JSON.parse(await openSession('src-project'));
+
+      await expect(undoEdit(sessionId)).resolves.toBeUndefined();
+    });
+
+    it('logs the error and rethrows when an undo fails', async () => {
+      const { undoEdit } = await activateSessionCommands();
+
+      await expect(undoEdit('not-a-session')).rejects.toThrow('no session not-a-session is open');
+      expect(__mockLogger.error).toHaveBeenCalledWith(
+        'Interlinearizer: failed to undo an edit in session not-a-session',
+        expect.any(Error),
+      );
+    });
+
+    it('replies to a redo with the changes it applied', async () => {
+      const remade = { intent: 'writeGloss', tokenAnalyses: { puts: [], deletes: ['ta-1'] } };
+      jest.spyOn(AnalysisSessions.prototype, 'redo').mockResolvedValue(remade);
+      const { redoEdit } = await activateSessionCommands();
+
+      await expect(redoEdit('session-id')).resolves.toBe(JSON.stringify(remade));
+      expect(AnalysisSessions.prototype.redo).toHaveBeenCalledWith('session-id');
+    });
+
+    it('replies to a redo with nothing when there is no undone edit', async () => {
+      const { openSession, redoEdit } = await activateSessionCommands();
+      const { sessionId } = JSON.parse(await openSession('src-project'));
+
+      await expect(redoEdit(sessionId)).resolves.toBeUndefined();
+    });
+
+    it('logs the error and rethrows when a redo fails', async () => {
+      const { redoEdit } = await activateSessionCommands();
+
+      await expect(redoEdit('not-a-session')).rejects.toThrow('no session not-a-session is open');
+      expect(__mockLogger.error).toHaveBeenCalledWith(
+        'Interlinearizer: failed to redo an edit in session not-a-session',
+        expect.any(Error),
+      );
+    });
+
     it('closes every session on deactivation', async () => {
       const { openSession } = await activateSessionCommands();
       await openSession('src-project');
diff --git a/src/__tests__/services/analysisSessions.test.ts b/src/__tests__/services/analysisSessions.test.ts
index b3d0f7d35..22a981587 100644
--- a/src/__tests__/services/analysisSessions.test.ts
+++ b/src/__tests__/services/analysisSessions.test.ts
@@ -400,6 +400,57 @@ describe('AnalysisSessions', () => {
     });
   });
 
+  describe('undo and redo', () => {
+    const putting = (id: string) => ({
+      intent: `put ${id}`,
+      tokenAnalyses: { puts: [{ id, ...FIXTURE_STAMPS, surfaceText: id }], deletes: [] },
+    });
+
+    /** The ids of the token payloads the source project's stored draft holds. */
+    async function storedIds(storage: ReturnType<typeof makeSessions>['storage']) {
+      const { draft } = await new DraftRepository(storage, SOURCE, silentLogger()).exportAll();
+      return draft.analysis.tokenAnalyses.map(({ id }) => id);
+    }
+
+    it("undoes and redoes an edit applied through the session's history", async () => {
+      const { sessions, storage } = makeSessions();
+      const { sessionId } = await sessions.open(SOURCE);
+      await sessions.runEdit(sessionId, (session) => session.history.apply(putting('a')));
+
+      await expect(sessions.undo(sessionId)).resolves.toStrictEqual({
+        intent: 'put a',
+        tokenAnalyses: { puts: [], deletes: ['a'] },
+      });
+      await expect(storedIds(storage)).resolves.toStrictEqual([]);
+      await expect(sessions.redo(sessionId)).resolves.toStrictEqual(putting('a'));
+      await expect(storedIds(storage)).resolves.toStrictEqual(['a']);
+    });
+
+    it('starts a reopened source with nothing to undo', async () => {
+      const { sessions } = makeSessions();
+      const earlier = await sessions.open(SOURCE);
+      await sessions.runEdit(earlier.sessionId, (session) => session.history.apply(putting('a')));
+
+      const { sessionId } = await sessions.open(SOURCE);
+
+      await expect(sessions.undo(sessionId)).resolves.toBeUndefined();
+    });
+
+    it("refuses an undo on a Paratext 9 import's session", async () => {
+      const { sessions } = makeSessions([makeImport()]);
+      const { sessionId } = await sessions.open(SOURCE, 'import-id');
+
+      await expect(sessions.undo(sessionId)).rejects.toThrow(ReadOnlyAnalysisError);
+    });
+
+    it("refuses a redo on a Paratext 9 import's session", async () => {
+      const { sessions } = makeSessions([makeImport()]);
+      const { sessionId } = await sessions.open(SOURCE, 'import-id');
+
+      await expect(sessions.redo(sessionId)).rejects.toThrow(ReadOnlyAnalysisError);
+    });
+  });
+
   describe('setAnalysisLanguage', () => {
     it('sets the language the commands sent after it read', async () => {
       const { sessions } = makeSessions();
diff --git a/src/__tests__/services/draftRepository.test.ts b/src/__tests__/services/draftRepository.test.ts
index 7fdbbb88f..e12aec981 100644
--- a/src/__tests__/services/draftRepository.test.ts
+++ b/src/__tests__/services/draftRepository.test.ts
@@ -248,4 +248,133 @@ describe('DraftRepository', () => {
       expect(records.has(draftAnalysisKey('src', 'GEN'))).toBe(false);
     });
   });
+
+  describe('apply', () => {
+    it('rewrites only the books whose records the changes alter', async () => {
+      const { storage, writes } = memoryStorage();
+      const repository = new DraftRepository(storage, 'src', silentLogger());
+      await repository.replaceAll(twoBookDraft());
+      writes.length = 0;
+      const [segment] = twoBookAnalysis().segmentAnalyses;
+
+      await repository.apply({
+        intent: 'writeFreeTranslation',
+        segmentAnalyses: {
+          puts: [{ ...segment, freeTranslation: { en: 'And then.' } }],
+          deletes: [],
+        },
+      });
+
+      expect(writes).toContain(draftAnalysisKey('src', 'EXO'));
+      expect(writes).not.toContain(draftAnalysisKey('src', 'GEN'));
+    });
+
+    it('builds on the stored draft after it was marked clean, keeping it clean', async () => {
+      const { storage } = memoryStorage();
+      const repository = new DraftRepository(storage, 'src', silentLogger());
+      await repository.replaceAll({ ...twoBookDraft(), dirty: true });
+      await repository.apply({ intent: 'nothing' });
+
+      await repository.markClean();
+      await repository.apply({
+        intent: 'deleteLink',
+        tokenAnalysisLinks: { puts: [], deletes: ['tl-GEN'] },
+      });
+
+      const { draft } = await new DraftRepository(storage, 'src', silentLogger()).exportAll();
+      expect(draft.dirty).toBe(false);
+      expect(draft.analysis.tokenAnalysisLinks.map(({ id }) => id)).toEqual(['tl-EXO']);
+    });
+
+    it('rewrites every book linking a payload it edits', async () => {
+      const { storage, records } = memoryStorage();
+      const repository = new DraftRepository(storage, 'src', silentLogger());
+      await repository.replaceAll(twoBookDraft());
+      const [payload] = twoBookAnalysis().tokenAnalyses;
+
+      await repository.apply({
+        intent: 'writeGloss',
+        tokenAnalyses: { puts: [{ ...payload, gloss: { en: 'and then' } }], deletes: [] },
+      });
+
+      expect(records.get(draftAnalysisKey('src', 'GEN'))).toContain('and then');
+      expect(records.get(draftAnalysisKey('src', 'EXO'))).toContain('and then');
+    });
+
+    describe('with a book whose shard could not be read', () => {
+      /** A repository that loaded {@link twoBookDraft} with its GEN shard unusable. */
+      async function loadedWithUnusableGenesis() {
+        const { storage, records, writes } = memoryStorage();
+        await new DraftRepository(storage, 'src', silentLogger()).replaceAll(twoBookDraft());
+        records.set(draftAnalysisKey('src', 'GEN'), 'not json');
+        const repository = new DraftRepository(storage, 'src', silentLogger());
+        await repository.exportAll();
+        writes.length = 0;
+        return { repository, records, writes };
+      }
+
+      it('refuses changes that reach that book, writing nothing', async () => {
+        const { repository, records, writes } = await loadedWithUnusableGenesis();
+        const [payload] = twoBookAnalysis().tokenAnalyses;
+
+        await expect(
+          repository.apply({
+            intent: 'writeGloss',
+            tokenAnalyses: { puts: [{ ...payload, gloss: { en: 'and then' } }], deletes: [] },
+            tokenAnalysisLinks: { puts: twoBookAnalysis().tokenAnalysisLinks, deletes: [] },
+          }),
+        ).rejects.toThrow('could not read the stored analysis of GEN');
+
+        expect(writes).toEqual([]);
+        expect(records.get(draftAnalysisKey('src', 'GEN'))).toBe('not json');
+      });
+
+      it('applies changes elsewhere, keeping its shard', async () => {
+        const { repository, records } = await loadedWithUnusableGenesis();
+        const [segment] = twoBookAnalysis().segmentAnalyses;
+
+        await repository.apply({
+          intent: 'writeFreeTranslation',
+          segmentAnalyses: {
+            puts: [{ ...segment, freeTranslation: { en: 'And then.' } }],
+            deletes: [],
+          },
+        });
+
+        expect(records.get(draftAnalysisKey('src', 'EXO'))).toContain('And then.');
+        expect(records.get(draftAnalysisKey('src', 'GEN'))).toBe('not json');
+      });
+    });
+
+    it('keeps its draft as it was when a write fails, so the next apply leaves the failed one out', async () => {
+      const { storage, records } = memoryStorage();
+      const repository = new DraftRepository(storage, 'src', silentLogger());
+      await repository.replaceAll(twoBookDraft());
+      const [payload] = twoBookAnalysis().tokenAnalyses;
+      const [segment] = twoBookAnalysis().segmentAnalyses;
+      const write = jest.spyOn(storage, 'write').mockRejectedValueOnce(new Error('disk full'));
+
+      await expect(
+        repository.apply({
+          intent: 'writeGloss',
+          tokenAnalyses: { puts: [{ ...payload, gloss: { en: 'and then' } }], deletes: [] },
+        }),
+      ).rejects.toThrow('disk full');
+      write.mockRestore();
+      await repository.apply({
+        intent: 'writeFreeTranslation',
+        segmentAnalyses: {
+          puts: [{ ...segment, freeTranslation: { en: 'And then.' } }],
+          deletes: [],
+        },
+      });
+
+      const {
+        draft: { analysis },
+      } = await new DraftRepository(storage, 'src', silentLogger()).exportAll();
+      expect(analysis.tokenAnalyses[0].gloss).toEqual({ en: 'and' });
+      expect(analysis.segmentAnalyses[0].freeTranslation).toEqual({ en: 'And then.' });
+      expect(records.get(draftAnalysisKey('src', 'GEN'))).not.toContain('and then');
+    });
+  });
 });
diff --git a/src/__tests__/services/editHistory.test.ts b/src/__tests__/services/editHistory.test.ts
new file mode 100644
index 000000000..a1f15d58d
--- /dev/null
+++ b/src/__tests__/services/editHistory.test.ts
@@ -0,0 +1,122 @@
+/// <reference types="jest" />
+
+import type { TokenAnalysis } from 'interlinearizer';
+import { DraftRepository } from '../../services/draftRepository';
+import { EditHistory } from '../../services/editHistory';
+import type { ChangeSet } from '../../types/analysis-repository';
+import { FIXTURE_STAMPS, memoryStorage, silentLogger } from '../test-helpers';
+
+function payload(id: string): TokenAnalysis {
+  return { id, ...FIXTURE_STAMPS, surfaceText: id };
+}
+
+function putting(id: string): ChangeSet {
+  return { intent: `put ${id}`, tokenAnalyses: { puts: [payload(id)], deletes: [] } };
+}
+
+/** A history over an empty draft in memory, with a way to read back the stored payload ids. */
+function makeHistory() {
+  const { storage } = memoryStorage();
+  const repository = new DraftRepository(storage, 'src', silentLogger());
+  const storedIds = async () =>
+    (
+      await new DraftRepository(storage, 'src', silentLogger()).exportAll()
+    ).draft.analysis.tokenAnalyses
+      .map(({ id }) => id)
+      .sort();
+  return { history: new EditHistory(repository), repository, storedIds };
+}
+
+describe('EditHistory', () => {
+  it('applies an edit through its repository', async () => {
+    const { history, storedIds } = makeHistory();
+
+    await history.apply(putting('a'));
+
+    await expect(storedIds()).resolves.toStrictEqual(['a']);
+  });
+
+  it('undoes edits latest first, returning what reverted each', async () => {
+    const { history, storedIds } = makeHistory();
+    await history.apply(putting('a'));
+    await history.apply(putting('b'));
+
+    await expect(history.undo()).resolves.toStrictEqual({
+      intent: 'put b',
+      tokenAnalyses: { puts: [], deletes: ['b'] },
+    });
+    await expect(storedIds()).resolves.toStrictEqual(['a']);
+    await history.undo();
+    await expect(storedIds()).resolves.toStrictEqual([]);
+  });
+
+  it('redoes undone edits latest undone first, returning what made each again', async () => {
+    const { history, storedIds } = makeHistory();
+    await history.apply(putting('a'));
+    await history.apply(putting('b'));
+    await history.undo();
+    await history.undo();
+
+    await expect(history.redo()).resolves.toStrictEqual({
+      intent: 'put a',
+      tokenAnalyses: { puts: [payload('a')], deletes: [] },
+    });
+    await expect(storedIds()).resolves.toStrictEqual(['a']);
+    await history.redo();
+    await expect(storedIds()).resolves.toStrictEqual(['a', 'b']);
+  });
+
+  it('has nothing to undo before any edit', async () => {
+    await expect(makeHistory().history.undo()).resolves.toBeUndefined();
+  });
+
+  it('has nothing to redo before any undo', async () => {
+    const { history } = makeHistory();
+    await history.apply(putting('a'));
+
+    await expect(history.redo()).resolves.toBeUndefined();
+  });
+
+  it('drops the undone edits when a new edit is applied', async () => {
+    const { history, storedIds } = makeHistory();
+    await history.apply(putting('a'));
+    await history.undo();
+
+    await history.apply(putting('b'));
+
+    await expect(history.redo()).resolves.toBeUndefined();
+    await expect(storedIds()).resolves.toStrictEqual(['b']);
+  });
+
+  it('records no step for an edit that fails', async () => {
+    const { history, repository } = makeHistory();
+    jest.spyOn(repository, 'apply').mockRejectedValueOnce(new Error('disk full'));
+
+    await expect(history.apply(putting('a'))).rejects.toThrow('disk full');
+
+    await expect(history.undo()).resolves.toBeUndefined();
+  });
+
+  it('keeps an edit to undo when undoing it fails', async () => {
+    const { history, repository, storedIds } = makeHistory();
+    await history.apply(putting('a'));
+    jest.spyOn(repository, 'apply').mockRejectedValueOnce(new Error('disk full'));
+
+    await expect(history.undo()).rejects.toThrow('disk full');
+
+    await history.undo();
+    await expect(storedIds()).resolves.toStrictEqual([]);
+  });
+
+  it('keeps an undone edit to redo when redoing it fails', async () => {
+    const { history, repository, storedIds } = makeHistory();
+    await history.apply(putting('a'));
+    await history.undo();
+    jest.spyOn(repository, 'apply').mockRejectedValueOnce(new Error('disk full'));
+
+    await expect(history.redo()).rejects.toThrow('disk full');
+
+    await history.redo();
+    await expect(storedIds()).resolves.toStrictEqual(['a']);
+  });
+});
diff --git a/src/__tests__/services/projectStorage.test.ts b/src/__tests__/services/projectStorage.test.ts
index 40664973a..24a6a63ab 100644
--- a/src/__tests__/services/projectStorage.test.ts
+++ b/src/__tests__/services/projectStorage.test.ts
@@ -1574,6 +1574,24 @@ describe('projectStorage', () => {
         });
       });
 
+      it('leaves the stored draft dirty when changes were applied after the copy read it', async () => {
+        const stored = backStorageWithMap();
+        storeListedProject(stored, makeStubProject('proj-id'));
+        await saveDraft(token, 'src-proj', {
+          ...makeDraftSpanningBooks('src-proj', 'GEN'),
+          dirty: true,
+        });
+
+        const save = saveDraftToProject(token, 'src-proj', 'proj-id');
+        const apply = openDraftRepository(token, 'src-proj').apply({
+          intent: 'deleteLink',
+          tokenAnalysisLinks: { puts: [], deletes: ['link-GEN'] },
+        });
+        await Promise.all([save, apply]);
+
+        expect((await getDraft(token, 'src-proj')).draft.dirty).toBe(true);
+      });
+
       it('does not mark the draft clean when the project is gone', async () => {
         backStorageWithMap();
         await saveDraft(token, 'src-proj', {
@@ -2883,6 +2901,20 @@ describe('projectStorage', () => {
       expect(writtenKeys()).not.toContain('draft:src-proj:analysis:JHN');
     });
 
+    it('applies changes to the draft saveDraft saved', async () => {
+      await saveDraft(token, 'src-proj', makeDraftSpanningBooks('src-proj', 'GEN'));
+
+      await openDraftRepository(token, 'src-proj').apply({
+        intent: 'deleteLink',
+        tokenAnalysisLinks: { puts: [], deletes: ['link-GEN'] },
+      });
+
+      const {
+        draft: { analysis },
+      } = await getDraft(token, 'src-proj');
+      expect(analysis.tokenAnalysisLinks).toStrictEqual([]);
+    });
+
     it('waits for a draft call already made before reading', async () => {
       let finishWrite: () => void = () => {};
       __mockWriteUserData.mockImplementationOnce(
diff --git a/src/__tests__/services/pt9ImportRepository.test.ts b/src/__tests__/services/pt9ImportRepository.test.ts
index 1e9ddf8dc..25a85d471 100644
--- a/src/__tests__/services/pt9ImportRepository.test.ts
+++ b/src/__tests__/services/pt9ImportRepository.test.ts
@@ -112,4 +112,16 @@ describe('Pt9ImportRepository', () => {
       expect(readProject).not.toHaveBeenCalled();
     });
   });
+
+  describe('apply', () => {
+    it('refuses every change', async () => {
+      const readProject = jest.fn(async () => makeImport());
+      const repository: AnalysisRepository = new Pt9ImportRepository('import-id', readProject);
+
+      await expect(repository.apply({ intent: 'writeGloss' })).rejects.toThrow(
+        ReadOnlyAnalysisError,
+      );
+      expect(readProject).not.toHaveBeenCalled();
+    });
+  });
 });
diff --git a/src/__tests__/utils/change-set.test.ts b/src/__tests__/utils/change-set.test.ts
new file mode 100644
index 000000000..e07b209f8
--- /dev/null
+++ b/src/__tests__/utils/change-set.test.ts
@@ -0,0 +1,197 @@
+/// <reference types="jest" />
+
+import type { DraftProject, TokenAnalysis } from 'interlinearizer';
+import { emptyAnalysis, emptyDraft } from '../../types/empty-factories';
+import { applyChangeSet, scopeRecordOf } from '../../utils/change-set';
+import { FIXTURE_STAMPS } from '../test-helpers';
+
+function payload(id: string, gloss?: string): TokenAnalysis {
+  return { id, ...FIXTURE_STAMPS, surfaceText: id, ...(gloss && { gloss: { en: gloss } }) };
+}
+
+function draftOf(...tokenAnalyses: TokenAnalysis[]): DraftProject {
+  return {
+    ...emptyDraft('src'),
+    analysisLanguages: ['en'],
+    analysis: { ...emptyAnalysis(), tokenAnalyses },
+  };
+}
+
+describe('scopeRecordOf', () => {
+  it("returns the draft's record without its analysis", () => {
+    const draft = { ...draftOf(payload('a')), suggestedName: 'Draft' };
+
+    expect(scopeRecordOf(draft)).toStrictEqual({
+      sourceProjectId: 'src',
+      modelVersion: draft.modelVersion,
+      analysisLanguages: ['en'],
+      suggestedName: 'Draft',
+      dirty: false,
+    });
+  });
+});
+
+describe('applyChangeSet', () => {
+  it('puts a new record after those stored, restored by deleting it', () => {
+    const { draft, inverse } = applyChangeSet(draftOf(payload('a')), {
+      intent: 'add',
+      tokenAnalyses: { puts: [payload('b')], deletes: [] },
+    });
+
+    expect(draft.analysis.tokenAnalyses).toStrictEqual([payload('a'), payload('b')]);
+    expect(inverse).toStrictEqual({
+      intent: 'add',
+      tokenAnalyses: { puts: [], deletes: ['b'] },
+    });
+  });
+
+  it('replaces a stored record in its place, restored by putting it back', () => {
+    const { draft, inverse } = applyChangeSet(draftOf(payload('a'), payload('b'), payload('c')), {
+      intent: 'edit',
+      tokenAnalyses: { puts: [payload('b', 'bee')], deletes: [] },
+    });
+
+    expect(draft.analysis.tokenAnalyses).toStrictEqual([
+      payload('a'),
+      payload('b', 'bee'),
+      payload('c'),
+    ]);
+    expect(inverse.tokenAnalyses).toStrictEqual({ puts: [payload('b')], deletes: [] });
+  });
+
+  it('deletes a stored record, restored by putting it back', () => {
+    const { draft, inverse } = applyChangeSet(draftOf(payload('a'), payload('b')), {
+      intent: 'delete',
+      tokenAnalyses: { puts: [], deletes: ['a'] },
+    });
+
+    expect(draft.analysis.tokenAnalyses).toStrictEqual([payload('b')]);
+    expect(inverse.tokenAnalyses).toStrictEqual({ puts: [payload('a')], deletes: [] });
+  });
+
+  it('leaves out of the inverse a kind whose changes replaced and added nothing', () => {
+    const { inverse } = applyChangeSet(draftOf(payload('a')), {
+      intent: 'deleteMissing',
+      tokenAnalyses: { puts: [], deletes: ['missing'] },
+    });
+
+    expect(inverse).toStrictEqual({ intent: 'deleteMissing' });
+  });
+
+  it("puts the scope's record, restored by putting the one it replaced", () => {
+    const stored = { ...draftOf(), dirty: true, suggestedName: 'Old' };
+    const scope = {
+      ...scopeRecordOf(draftOf()),
+      segmentation: { removedVerseStarts: ['GEN 1:2'], addedStarts: [] },
+    };
+
+    const { draft, inverse } = applyChangeSet(stored, { intent: 'boundaries', scope });
+
+    expect(draft).toStrictEqual({ ...scope, analysis: stored.analysis });
+    expect(inverse.scope).toStrictEqual(scopeRecordOf(stored));
+  });
+
+  it('leaves the draft it was given as it was', () => {
+    const stored = draftOf(payload('a'));
+
+    applyChangeSet(stored, {
+      intent: 'edit',
+      scope: { ...scopeRecordOf(stored), dirty: true },
+      tokenAnalyses: { puts: [payload('a', 'ay'), payload('b')], deletes: [] },
+    });
+
+    expect(stored).toStrictEqual(draftOf(payload('a')));
+  });
+
+  it('holds copies of the records the changes put', () => {
+    const put = payload('b');
+    const scope = scopeRecordOf(draftOf());
+    const { draft } = applyChangeSet(draftOf(), {
+      intent: 'add',
+      scope,
+      tokenAnalyses: { puts: [put], deletes: [] },
+    });
+
+    put.surfaceText = 'changed';
+    scope.analysisLanguages.push('fr');
+
+    expect(draft.analysis.tokenAnalyses).toStrictEqual([payload('b')]);
+    expect(draft.analysisLanguages).toStrictEqual(['en']);
+  });
+
+  it('refuses an id both put and deleted', () => {
+    expect(() =>
+      applyChangeSet(draftOf(payload('a')), {
+        intent: 'conflict',
+        tokenAnalyses: { puts: [payload('a', 'ay')], deletes: ['a'] },
+      }),
+    ).toThrow('a change set names token analysis record a more than once');
+  });
+
+  it('refuses an id put twice', () => {
+    expect(() =>
+      applyChangeSet(draftOf(), {
+        intent: 'conflict',
+        tokenAnalyses: { puts: [payload('a'), payload('a', 'ay')], deletes: [] },
+      }),
+    ).toThrow('a change set names token analysis record a more than once');
+  });
+
+  it("refuses a scope's record of another source project", () => {
+    expect(() =>
+      applyChangeSet(draftOf(), {
+        intent: 'wrongScope',
+        scope: { ...scopeRecordOf(draftOf()), sourceProjectId: 'other' },
+      }),
+    ).toThrow('a change set for source project other cannot apply to the draft of src');
+  });
+
+  it('applies the changes of every record kind', () => {
+    const link = {
+      id: 'link',
+      analysisId: 'a',
+      ...FIXTURE_STAMPS,
+      status: 'approved' as const,
+    };
+    const { draft } = applyChangeSet(draftOf(), {
+      intent: 'everyKind',
+      segmentAnalyses: { puts: [{ id: 'sa', ...FIXTURE_STAMPS, surfaceText: 'In' }], deletes: [] },
+      segmentAnalysisLinks: {
+        puts: [{ ...link, id: 'sl', analysisId: 'sa', segmentId: 'GEN 1:1' }],
+        deletes: [],
+      },
+      tokenAnalyses: { puts: [payload('a')], deletes: [] },
+      tokenAnalysisLinks: {
+        puts: [{ ...link, id: 'tl', token: { tokenRef: 'GEN 1:1:0', surfaceText: 'In' } }],
+        deletes: [],
+      },
+      phraseAnalyses: {
+        puts: [{ id: 'pa', ...FIXTURE_STAMPS, surfaceText: 'In the' }],
+        deletes: [],
+      },
+      phraseAnalysisLinks: {
+        puts: [
+          {
+            ...link,
+            id: 'pl',
+            analysisId: 'pa',
+            tokens: [{ tokenRef: 'GEN 1:1:0', surfaceText: 'In' }],
+          },
+        ],
+        deletes: [],
+      },
+    });
+
+    const { analysis } = draft;
+    expect(
+      [
+        analysis.segmentAnalyses,
+        analysis.segmentAnalysisLinks,
+        analysis.tokenAnalyses,
+        analysis.tokenAnalysisLinks,
+        analysis.phraseAnalyses,
+        analysis.phraseAnalysisLinks,
+      ].map((records) => records.map(({ id }) => id)),
+    ).toStrictEqual([['sa'], ['sl'], ['a'], ['tl'], ['pa'], ['pl']]);
+  });
+});
diff --git a/src/main.ts b/src/main.ts
index b4a03b466..bade29711 100644
--- a/src/main.ts
+++ b/src/main.ts
@@ -772,6 +772,40 @@ async function setAnalysisLanguage(sessionId: string, analysisLanguage: string):
   }
 }
 
+/**
+ * Reverts a session's latest edit not yet undone.
+ *
+ * @returns The changes that reverted it, as JSON, or `undefined` when there is none.
+ * @throws If the session is read-only or not open, or the changes cannot be applied. The error is
+ *   logged before rethrowing.
+ */
+async function undoEdit(sessionId: string): Promise<string | undefined> {
+  try {
+    const changes = await sessions.undo(sessionId);
+    return changes && JSON.stringify(changes);
+  } catch (e) {
+    logger.error(`Interlinearizer: failed to undo an edit in session ${sessionId}`, e);
+    throw e;
+  }
+}
+
+/**
+ * Redoes a session's latest undone edit.
+ *
+ * @returns The changes that redid it, as JSON, or `undefined` when there is none.
+ * @throws If the session is read-only or not open, or the changes cannot be applied. The error is
+ *   logged before rethrowing.
+ */
+async function redoEdit(sessionId: string): Promise<string | undefined> {
+  try {
+    const changes = await sessions.redo(sessionId);
+    return changes && JSON.stringify(changes);
+  } catch (e) {
+    logger.error(`Interlinearizer: failed to redo an edit in session ${sessionId}`, e);
+    throw e;
+  }
+}
+
 /**
  * Returns a summary of every interlinearizer project for the given source project as a JSON string.
  * The WebView deserializes this to populate its project picker and to decide whether to prompt
@@ -1346,6 +1380,37 @@ export async function activate(context: ExecutionActivationContext): Promise<voi
     },
   );
 
+  /** The result of a command that replies with the changes it applied, if any. */
+  const appliedChangesResult = {
+    name: 'return value',
+    summary: 'JSON-stringified ChangeSet it applied; omitted when there was nothing to apply',
+    schema: { type: 'string' },
+  } as const;
+
+  const undoEditCommandRegistration = await papi.commands.registerCommand(
+    'interlinearizer.undoEdit',
+    undoEdit,
+    {
+      method: {
+        summary: "Revert a session's latest edit not yet undone",
+        params: [sessionIdParam],
+        result: appliedChangesResult,
+      },
+    },
+  );
+
+  const redoEditCommandRegistration = await papi.commands.registerCommand(
+    'interlinearizer.redoEdit',
+    redoEdit,
+    {
+      method: {
+        summary: "Make a session's latest undone edit again",
+        params: [sessionIdParam],
+        result: appliedChangesResult,
+      },
+    },
+  );
+
   const setPerfMarksCommandRegistration = await papi.commands.registerCommand(
     'interlinearizer.setPerfMarks',
     async (enabled: boolean) => setHostPerfMarks(enabled),
@@ -1719,6 +1784,8 @@ export async function activate(context: ExecutionActivationContext): Promise<voi
     openSessionCommandRegistration,
     closeSessionCommandRegistration,
     setAnalysisLanguageCommandRegistration,
+    undoEditCommandRegistration,
+    redoEditCommandRegistration,
     setPerfMarksCommandRegistration,
     readPerfCommandRegistration,
     updateProjectMetadataCommandRegistration,
diff --git a/src/services/analysisSessions.ts b/src/services/analysisSessions.ts
index 176121682..964ed062a 100644
--- a/src/services/analysisSessions.ts
+++ b/src/services/analysisSessions.ts
@@ -1,7 +1,8 @@
-import type { AnalysisRepository } from '../types/analysis-repository';
+import type { AnalysisRepository, ChangeSet } from '../types/analysis-repository';
 import { ReadOnlyAnalysisError } from '../types/read-only-analysis-error';
 import type { InterlinearProjectSummary } from '../types/interlinear-project-summary';
 import { analysisHasFreeTranslations } from '../utils/free-translations';
+import { EditHistory } from './editHistory';
 
 /** BCP 47 tag for a language that cannot be determined. */
 export const UNDETERMINED_LANGUAGE = 'und';
@@ -34,6 +35,8 @@ export type Session = {
   readonly id: string;
   readonly scope: SessionScope;
   readonly repository: AnalysisRepository;
+  /** Every edit to the session's analysis is applied through it, so that undo can revert each one. */
+  readonly history: EditHistory;
   /** BCP 47 tag of the language that glosses are read and written in. */
   analysisLanguage: string;
 };
@@ -94,7 +97,7 @@ export class AnalysisSessions {
    * Opens a session read-only on `interlinearProjectId` when it names a Paratext 9 import,
    * otherwise on the source project's draft, which saves to `interlinearProjectId` when given.
    * Opening closes the source's earlier session, if any, and starts the new one on what storage
-   * holds.
+   * holds, with nothing to undo.
    *
    * The session starts on the opened draft's first analysis language. When the draft lists none, it
    * starts on the platform's first interface language, or {@link UNDETERMINED_LANGUAGE} when the
@@ -119,6 +122,7 @@ export class AnalysisSessions {
         id: crypto.randomUUID(),
         scope,
         repository,
+        history: new EditHistory(repository),
         analysisLanguage:
           opened.analysisLanguages[0] ??
           ((await this.host.getInterfaceLanguages())[0] || UNDETERMINED_LANGUAGE),
@@ -197,6 +201,30 @@ export class AnalysisSessions {
     return this.run(sessionId, edit);
   }
 
+  /**
+   * Reverts the session's latest edit not yet undone.
+   *
+   * @returns The changes that reverted it, or `undefined` when there is none.
+   * @throws {ReadOnlyAnalysisError} If the session is read-only.
+   * @throws {Error} If the session is not open.
+   * @throws Whatever applying the changes throws; the edit stays the next to undo.
+   */
+  undo(sessionId: string): Promise<ChangeSet | undefined> {
+    return this.runEdit(sessionId, (session) => session.history.undo());
+  }
+
+  /**
+   * Redoes the session's latest undone edit.
+   *
+   * @returns The changes that redid it, or `undefined` when there is none.
+   * @throws {ReadOnlyAnalysisError} If the session is read-only.
+   * @throws {Error} If the session is not open.
+   * @throws Whatever applying the changes throws; the edit stays the next to redo.
+   */
+  redo(sessionId: string): Promise<ChangeSet | undefined> {
+    return this.runEdit(sessionId, (session) => session.history.redo());
+  }
+
   /**
    * Resolves the scope for a session on the source project, paired with `interlinearProjectId` when
    * given.
diff --git a/src/services/draftRepository.ts b/src/services/draftRepository.ts
index 7b5c71c8e..a81e8f72d 100644
--- a/src/services/draftRepository.ts
+++ b/src/services/draftRepository.ts
@@ -1,6 +1,8 @@
 import type { DraftProject, TextAnalysis } from 'interlinearizer';
 import type {
   AnalysisRepository,
+  ApplyResult,
+  ChangeSet,
   DraftExport,
   KeyValueStorage,
   ReplaceAllOptions,
@@ -17,6 +19,7 @@ import {
 } from '../types/type-guards';
 import { mergeAnalyses, splitAnalysisByBook } from '../utils/analysis-book';
 import { reportAnalysisViolations } from '../utils/analysis-violations';
+import { applyChangeSet } from '../utils/change-set';
 import { perfTime, perfTimeAsync, perfTimeAsyncExcluding } from '../utils/perf-marks';
 import { draftAnalysisKey, draftJournalKey, draftKey } from './storageKeys';
 
@@ -125,6 +128,13 @@ export class DraftRepository implements AnalysisRepository {
   /** Whether this instance has loaded the stored draft, so it knows which shards it cannot read. */
   private loaded = false;
 
+  /**
+   * The draft as this instance's last apply left it, which the next apply builds on. Dropped by
+   * every load and by every write but an apply, since each may come from a caller holding another
+   * draft.
+   */
+  private current: DraftProject | undefined;
+
   constructor(storage: KeyValueStorage, sourceProjectId: string, logger: WarningLogger) {
     this.storage = storage;
     this.logger = logger;
@@ -153,6 +163,7 @@ export class DraftRepository implements AnalysisRepository {
    * @throws If storage rejects a read.
    */
   async exportAll(): Promise<DraftExport> {
+    this.current = undefined;
     const exported = await this.readDraft(false);
     this.loaded = true;
     return exported;
@@ -169,6 +180,7 @@ export class DraftRepository implements AnalysisRepository {
    * @throws If storage rejects a read.
    */
   async exportForCopy(): Promise<DraftExport> {
+    this.current = undefined;
     const exported = await this.readDraft(true);
     this.loaded = true;
     return exported;
@@ -184,6 +196,7 @@ export class DraftRepository implements AnalysisRepository {
    * @throws If storage rejects the read or the write.
    */
   async markClean(): Promise<void> {
+    this.current = undefined;
     const { sourceProjectId, storage } = this;
     const raw = await storage.read(draftKey(sourceProjectId));
     if (raw === undefined) return;
@@ -226,6 +239,7 @@ export class DraftRepository implements AnalysisRepository {
    * @throws If storage rejects a write.
    */
   async replaceAll(draft: DraftProject, options?: ReplaceAllOptions): Promise<string[]> {
+    this.current = undefined;
     if (!this.loaded) {
       try {
         await this.exportAll();
@@ -234,6 +248,42 @@ export class DraftRepository implements AnalysisRepository {
         if (!(e instanceof SyntaxError)) throw e;
       }
     }
+    return this.writeDraft(draft, options, { refuseUnreadable: false });
+  }
+
+  /**
+   * Applies the changes to the draft as this instance's last apply left it, or to the stored draft
+   * when it has made none since its last whole load or save. Only the books whose content the
+   * changes alter are rewritten, so an edit to a payload rewrites every book linking it.
+   *
+   * @throws {Error} If an id appears more than once in one record kind's changes, or the scope's
+   *   record names another source project; nothing is written.
+   * @throws {Error} If the changes reach a book whose shard could not be read; nothing is written.
+   * @throws {SyntaxError} If the draft's stored value contains invalid JSON.
+   * @throws {Error} If the stored draft was written by a newer build; nothing is written.
+   * @throws If storage rejects a read or a write, as {@link replaceAll} does; this instance's draft
+   *   is left as it was.
+   */
+  async apply(changes: ChangeSet): Promise<ApplyResult> {
+    this.current ??= (await this.exportAll()).draft;
+    const { draft, inverse } = applyChangeSet(this.current, changes);
+    await this.writeDraft(draft, undefined, { refuseUnreadable: true });
+    this.current = draft;
+    return { inverse };
+  }
+
+  /**
+   * Saves `draft` as {@link replaceAll} describes.
+   *
+   * @throws {Error} If `refuseUnreadable` is set and the draft carries analysis for a book whose
+   *   shard could not be read; nothing is written.
+   * @throws Whatever {@link replaceAll} throws.
+   */
+  private async writeDraft(
+    draft: DraftProject,
+    options: ReplaceAllOptions | undefined,
+    { refuseUnreadable }: { refuseUnreadable: boolean },
+  ): Promise<string[]> {
     const { sourceProjectId, storage, shardContents: saved, unreadableShards: unreadable } = this;
     const { analysis } = draft;
     const storedBooks = await perfTimeAsync('saveDraft:read', () =>
@@ -242,6 +292,11 @@ export class DraftRepository implements AnalysisRepository {
     const byBook = perfTime('saveDraft:compare', () => splitAnalysisByBook(analysis));
     if (options?.discardUnreadable) unreadable.clear();
     const leftOut = [...unreadable].filter((bookCode) => byBook.has(bookCode));
+    if (refuseUnreadable && leftOut.length > 0) {
+      throw new Error(
+        `Interlinearizer: the draft for ${sourceProjectId} could not read the stored analysis of ${leftOut.join(', ')}, so it refuses changes there`,
+      );
+    }
     leftOut.forEach((bookCode) => byBook.delete(bookCode));
 
     // Books this save no longer carries, less those held back because the load could not read them.
diff --git a/src/services/editHistory.ts b/src/services/editHistory.ts
new file mode 100644
index 000000000..d4c09be60
--- /dev/null
+++ b/src/services/editHistory.ts
@@ -0,0 +1,60 @@
+import type { AnalysisRepository, ChangeSet } from '../types/analysis-repository';
+
+/**
+ * A linear undo history of the edits applied through it to one repository. Each edit is one step,
+ * and a new edit drops every step undone before it.
+ */
+export class EditHistory {
+  private readonly repository: AnalysisRepository;
+
+  /** What reverts each edit not yet undone, latest last. */
+  private readonly undoable: ChangeSet[] = [];
+
+  /** What redoes each undone edit, latest last. */
+  private readonly redoable: ChangeSet[] = [];
+
+  constructor(repository: AnalysisRepository) {
+    this.repository = repository;
+  }
+
+  /**
+   * Applies `changes` as one undo step.
+   *
+   * @throws Whatever applying the changes throws; the history is left as it was.
+   */
+  async apply(changes: ChangeSet): Promise<void> {
+    const { inverse } = await this.repository.apply(changes);
+    this.undoable.push(inverse);
+    this.redoable.length = 0;
+  }
+
+  /**
+   * Reverts the latest edit not yet undone.
+   *
+   * @returns The changes that reverted it, or `undefined` when there is none.
+   * @throws Whatever applying those changes throws; the edit stays the next to undo.
+   */
+  undo(): Promise<ChangeSet | undefined> {
+    return this.step(this.undoable, this.redoable);
+  }
+
+  /**
+   * Redoes the latest undone edit.
+   *
+   * @returns The changes that redid it, or `undefined` when there is none.
+   * @throws Whatever applying those changes throws; the edit stays the next to redo.
+   */
+  redo(): Promise<ChangeSet | undefined> {
+    return this.step(this.redoable, this.undoable);
+  }
+
+  /** Applies the latest changes on `from`, moving what reverts them onto `to`. */
+  private async step(from: ChangeSet[], to: ChangeSet[]): Promise<ChangeSet | undefined> {
+    const changes = from.at(-1);
+    if (!changes) return undefined;
+    const { inverse } = await this.repository.apply(changes);
+    from.pop();
+    to.push(inverse);
+    return changes;
+  }
+}
diff --git a/src/services/projectStorage.ts b/src/services/projectStorage.ts
index 193cd1be5..e6eefe7a3 100644
--- a/src/services/projectStorage.ts
+++ b/src/services/projectStorage.ts
@@ -1121,15 +1121,18 @@ export function openDraftRepository(
     enqueueSerialized(draftQueues, sourceProjectId, () =>
       call(draftRepositoryFor(token, sourceProjectId)),
     );
+  // Counted when queued, so a copy can tell a write was sent after it read the draft.
+  const counted = <T>(call: (repository: DraftRepository) => Promise<T>) => {
+    draftWriteCounts.set(sourceProjectId, (draftWriteCounts.get(sourceProjectId) ?? 0) + 1);
+    return queued(call);
+  };
   return {
     capabilities: { readOnly: false },
     exportAll: () => queued((repository) => repository.exportAll()),
     exportForCopy: () => queued((repository) => repository.exportForCopy()),
-    replaceAll: (draft, options) => {
-      draftWriteCounts.set(sourceProjectId, (draftWriteCounts.get(sourceProjectId) ?? 0) + 1);
-      return queued((repository) => repository.replaceAll(draft, options));
-    },
+    replaceAll: (draft, options) => counted((repository) => repository.replaceAll(draft, options)),
     markClean: () => queued((repository) => repository.markClean()),
+    apply: (changes) => counted((repository) => repository.apply(changes)),
   };
 }
 
diff --git a/src/services/pt9ImportRepository.ts b/src/services/pt9ImportRepository.ts
index 33114f202..e8c7d4c4f 100644
--- a/src/services/pt9ImportRepository.ts
+++ b/src/services/pt9ImportRepository.ts
@@ -1,6 +1,7 @@
 import type { InterlinearProject } from 'interlinearizer';
 import type {
   AnalysisRepository,
+  ApplyResult,
   DraftExport,
   RepositoryCapabilities,
 } from '../types/analysis-repository';
@@ -80,6 +81,11 @@ export class Pt9ImportRepository implements AnalysisRepository {
     throw this.readOnlyError();
   }
 
+  /** @throws {ReadOnlyAnalysisError} Always; nothing is applied. */
+  async apply(): Promise<ApplyResult> {
+    throw this.readOnlyError();
+  }
+
   private readOnlyError(): ReadOnlyAnalysisError {
     return new ReadOnlyAnalysisError(
       `Interlinearizer: Paratext 9 import ${this.interlinearProjectId} is read-only`,
diff --git a/src/types/analysis-repository.ts b/src/types/analysis-repository.ts
index 27014f1c9..e19571e19 100644
--- a/src/types/analysis-repository.ts
+++ b/src/types/analysis-repository.ts
@@ -1,4 +1,4 @@
-import type { DraftProject } from 'interlinearizer';
+import type { DraftProject, TextAnalysis } from 'interlinearizer';
 
 /** Text records by key. */
 export interface KeyValueStorage {
@@ -56,6 +56,36 @@ export type DraftExport = {
   unreadableBooks: string[];
 };
 
+/** A draft's own record: everything in it but its analysis. */
+export type ScopeRecord = Omit<DraftProject, 'analysis'>;
+
+/** Whole-record puts and deletes of one record kind. */
+export type RecordChanges<T> = {
+  /** Records to store whole, each replacing any stored under its id. */
+  puts: T[];
+  /** Ids of records to remove; an id with nothing stored under it is skipped. */
+  deletes: string[];
+};
+
+/**
+ * One command's changes, applied all-or-nothing. A record kind it leaves alone is absent, and an id
+ * appears at most once in a kind's puts and deletes together.
+ */
+export type ChangeSet = {
+  /** Names the command that made the changes. */
+  intent: string;
+  /** The scope's record, whole, which carries boundary changes; absent when it is left alone. */
+  scope?: ScopeRecord;
+} & {
+  [Kind in keyof TextAnalysis]?: RecordChanges<TextAnalysis[Kind][number]>;
+};
+
+/** What applying a {@link ChangeSet} tells its caller. */
+export type ApplyResult = {
+  /** Restores what the applied changes replaced; applying it undoes them. */
+  inverse: ChangeSet;
+};
+
 /**
  * Reads and writes one source project's draft, or, when read-only, reads analysis in a draft's
  * shape. Every call is async and takes and returns only JSON-plain values, so an implementation may
@@ -122,4 +152,20 @@ export interface AnalysisRepository {
    * @throws If storage rejects a read or a write.
    */
   markClean(): Promise<void>;
+
+  /**
+   * Applies `changes` to the stored draft whole or not at all, stamped with this build's model
+   * version. A draft never saved counts as an empty one.
+   *
+   * @throws {ReadOnlyAnalysisError} If the repository is read-only; nothing is applied.
+   * @throws {Error} If an id appears more than once in one record kind's changes, or the scope's
+   *   record names another source project; nothing is applied.
+   * @throws {Error} If the changes reach a book whose stored analysis could not be read; nothing is
+   *   applied.
+   * @throws {SyntaxError} If the draft's stored value contains invalid JSON.
+   * @throws {Error} If the stored draft was written by a newer build; nothing is applied.
+   * @throws If storage rejects a read or a write. The draft as this repository holds it is
+   *   unchanged, though storage may hold some of the changes until a later save.
+   */
+  apply(changes: ChangeSet): Promise<ApplyResult>;
 }
diff --git a/src/types/interlinearizer.d.ts b/src/types/interlinearizer.d.ts
index 5177060be..06ab18d47 100644
--- a/src/types/interlinearizer.d.ts
+++ b/src/types/interlinearizer.d.ts
@@ -363,6 +363,24 @@ declare module 'papi-shared-types' {
       analysisLanguage: string,
     ) => Promise<void>;
 
+    /**
+     * Reverts a session's latest edit not yet undone.
+     *
+     * @returns The changes that reverted it, as JSON, or `undefined` when there is none.
+     * @throws If the session is read-only or not open, or the changes cannot be applied (logged
+     *   before rethrowing).
+     */
+    'interlinearizer.undoEdit': (sessionId: string) => Promise<string | undefined>;
+
+    /**
+     * Redoes a session's latest undone edit.
+     *
+     * @returns The changes that redid it, as JSON, or `undefined` when there is none.
+     * @throws If the session is read-only or not open, or the changes cannot be applied (logged
+     *   before rethrowing).
+     */
+    'interlinearizer.redoEdit': (sessionId: string) => Promise<string | undefined>;
+
     /**
      * Turns the extension host's timing entries on or off, discarding any it holds. Off until
      * turned on.
diff --git a/src/utils/change-set.ts b/src/utils/change-set.ts
new file mode 100644
index 000000000..ecc046174
--- /dev/null
+++ b/src/utils/change-set.ts
@@ -0,0 +1,140 @@
+import type { DraftProject } from 'interlinearizer';
+import type { ChangeSet, RecordChanges, ScopeRecord } from '../types/analysis-repository';
+
+/** A draft with a {@link ChangeSet} applied, and the change set that restores what it replaced. */
+export type AppliedChanges = {
+  draft: DraftProject;
+  inverse: ChangeSet;
+};
+
+/** A copy of a JSON-plain value that shares nothing with it. */
+function copyOf<T>(value: T): T {
+  return JSON.parse(JSON.stringify(value));
+}
+
+/** The draft's record, without its analysis. */
+// eslint-disable-next-line @typescript-eslint/no-unused-vars -- named only to leave it out
+export function scopeRecordOf({ analysis, ...scope }: DraftProject): ScopeRecord {
+  return scope;
+}
+
+/**
+ * Applies one record kind's changes to `records`.
+ *
+ * @returns The records the changes leave, and the changes that restore what they replaced, absent
+ *   when the changes replaced nothing and added nothing.
+ * @throws {Error} If an id appears more than once in the changes.
+ */
+function applyRecordChanges<T extends { id: string }>(
+  records: T[],
+  changes: RecordChanges<T> | undefined,
+  kind: string,
+): { records: T[]; inverse?: RecordChanges<T> } {
+  if (!changes) return { records };
+  const named = new Set<string>();
+  [...changes.puts.map(({ id }) => id), ...changes.deletes].forEach((id) => {
+    if (named.has(id)) {
+      throw new Error(`Interlinearizer: a change set names ${kind} record ${id} more than once`);
+    }
+    named.add(id);
+  });
+
+  const stored = new Map(records.map((record) => [record.id, record]));
+  const deleted = new Set(changes.deletes);
+  const puts = new Map(changes.puts.map((record) => [record.id, copyOf(record)]));
+  const inverse: RecordChanges<T> = { puts: [], deletes: [] };
+  changes.puts.forEach(({ id }) => {
+    const prior = stored.get(id);
+    if (prior) inverse.puts.push(prior);
+    else inverse.deletes.push(id);
+  });
+  changes.deletes.forEach((id) => {
+    const prior = stored.get(id);
+    if (prior) inverse.puts.push(prior);
+  });
+
+  // A replaced record keeps its place, so records nearby are left as they were.
+  const next = records.flatMap((record) => {
+    if (deleted.has(record.id)) return [];
+    return [puts.get(record.id) ?? record];
+  });
+  puts.forEach((record, id) => {
+    if (!stored.has(id)) next.push(record);
+  });
+  return {
+    records: next,
+    ...((inverse.puts.length > 0 || inverse.deletes.length > 0) && { inverse }),
+  };
+}
+
+/**
+ * Applies `changes` to `draft`, leaving `draft` as it was. The result holds copies of the records
+ * the changes put, and shares everything else with `draft`, the records the inverse restores
+ * included.
+ *
+ * @throws {Error} If an id appears more than once in one record kind's changes, or the scope's
+ *   record names another source project.
+ */
+export function applyChangeSet(draft: DraftProject, changes: ChangeSet): AppliedChanges {
+  if (changes.scope && changes.scope.sourceProjectId !== draft.sourceProjectId) {
+    throw new Error(
+      `Interlinearizer: a change set for source project ${changes.scope.sourceProjectId} cannot apply to the draft of ${draft.sourceProjectId}`,
+    );
+  }
+  const { analysis } = draft;
+  const segmentAnalyses = applyRecordChanges(
+    analysis.segmentAnalyses,
+    changes.segmentAnalyses,
+    'segment analysis',
+  );
+  const segmentAnalysisLinks = applyRecordChanges(
+    analysis.segmentAnalysisLinks,
+    changes.segmentAnalysisLinks,
+    'segment analysis link',
+  );
+  const tokenAnalyses = applyRecordChanges(
+    analysis.tokenAnalyses,
+    changes.tokenAnalyses,
+    'token analysis',
+  );
+  const tokenAnalysisLinks = applyRecordChanges(
+    analysis.tokenAnalysisLinks,
+    changes.tokenAnalysisLinks,
+    'token analysis link',
+  );
+  const phraseAnalyses = applyRecordChanges(
+    analysis.phraseAnalyses,
+    changes.phraseAnalyses,
+    'phrase analysis',
+  );
+  const phraseAnalysisLinks = applyRecordChanges(
+    analysis.phraseAnalysisLinks,
+    changes.phraseAnalysisLinks,
+    'phrase analysis link',
+  );
+
+  const inverse: ChangeSet = {
+    intent: changes.intent,
+    ...(changes.scope && { scope: scopeRecordOf(draft) }),
+    ...(segmentAnalyses.inverse && { segmentAnalyses: segmentAnalyses.inverse }),
+    ...(segmentAnalysisLinks.inverse && { segmentAnalysisLinks: segmentAnalysisLinks.inverse }),
+    ...(tokenAnalyses.inverse && { tokenAnalyses: tokenAnalyses.inverse }),
+    ...(tokenAnalysisLinks.inverse && { tokenAnalysisLinks: tokenAnalysisLinks.inverse }),
+    ...(phraseAnalyses.inverse && { phraseAnalyses: phraseAnalyses.inverse }),
+    ...(phraseAnalysisLinks.inverse && { phraseAnalysisLinks: phraseAnalysisLinks.inverse }),
+  };
+  return {
+    draft: {
+      ...(changes.scope ? copyOf(changes.scope) : scopeRecordOf(draft)),
+      analysis: {
+        segmentAnalyses: segmentAnalyses.records,
+        segmentAnalysisLinks: segmentAnalysisLinks.records,
+        tokenAnalyses: tokenAnalyses.records,
+        tokenAnalysisLinks: tokenAnalysisLinks.records,
+        phraseAnalyses: phraseAnalyses.records,
+        phraseAnalysisLinks: phraseAnalysisLinks.records,
+      },
+    },
+    inverse,
+  };
+}

From a11b7b4b65ab49ed2d10a957833747ca84ab3cd5 Mon Sep 17 00:00:00 2001
From: Alex Rawlings <alex.rawlings@wycliffe.ca>
Date: Thu, 22 Oct 2026 10:20:18 -0600
Subject: [PATCH 05/22] Add derived indexes with a rebuild-and-diff command
 (#442)

---
 AGENTS.md                                     |   2 +-
 .../analysis-repository-conformance.ts        | 238 +++++++++++++++++-
 src/__tests__/main.test.ts                    |  38 +++
 src/__tests__/services/analysisIndex.test.ts  | 177 +++++++++++++
 .../services/draftRepository.test.ts          |  41 +++
 .../services/indexedRepository.test.ts        |  70 ++++++
 src/__tests__/services/projectStorage.test.ts |  37 +++
 .../services/pt9ImportRepository.test.ts      |  52 ++++
 src/__tests__/services/recordTable.test.ts    |  96 +++++++
 src/__tests__/utils/change-set.test.ts        |  16 --
 src/__tests__/utils/json-copy.test.ts         |  16 ++
 src/main.ts                                   |  37 +++
 src/services/analysisIndex.ts                 | 186 ++++++++++++++
 src/services/draftRepository.ts               |  50 +++-
 src/services/indexedRepository.ts             |  95 +++++++
 src/services/projectStorage.ts                |  15 ++
 src/services/pt9ImportRepository.ts           |  67 +++--
 src/services/recordTable.ts                   | 122 +++++++++
 src/types/analysis-repository.ts              |  69 ++++-
 src/types/interlinearizer.d.ts                |   9 +
 src/utils/change-set.ts                       |  13 +-
 src/utils/json-copy.ts                        |   4 +
 22 files changed, 1388 insertions(+), 62 deletions(-)
 create mode 100644 src/__tests__/services/analysisIndex.test.ts
 create mode 100644 src/__tests__/services/indexedRepository.test.ts
 create mode 100644 src/__tests__/services/recordTable.test.ts
 create mode 100644 src/__tests__/utils/json-copy.test.ts
 create mode 100644 src/services/analysisIndex.ts
 create mode 100644 src/services/indexedRepository.ts
 create mode 100644 src/services/recordTable.ts
 create mode 100644 src/utils/json-copy.ts

diff --git a/AGENTS.md b/AGENTS.md
index 1a3163569..435e6c976 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 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)). [Pt9ImportRepository](src/services/pt9ImportRepository.ts) serves a Paratext 9 import through the same seam, read-only.
+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)). [Pt9ImportRepository](src/services/pt9ImportRepository.ts) serves a Paratext 9 import through the same seam, read-only. Both answer the seam's lookups (by token ref, segment id, analysis id, normalized form, and book and status) from an [AnalysisIndex](src/services/analysisIndex.ts) built from the records on first use and kept current by `apply`; `checkIndexes` rebuilds it and reports any difference.
 
 [The conformance suite](src/__tests__/analysis-repository-conformance.ts) defines the seam: every `AnalysisRepository` implementation must pass it, and [draftRepository.conformance.test.ts](src/__tests__/services/draftRepository.conformance.test.ts) runs it against `DraftRepository` and `Pt9ImportRepository`. A behavior every implementation owes goes in the suite; one particular to an implementation, such as which shards a save rewrites, goes in that implementation's own tests. A later backend runs the suite by passing `describeAnalysisRepositoryConformance` a factory that returns a fresh `ConformanceStore` for each test.
 
diff --git a/src/__tests__/analysis-repository-conformance.ts b/src/__tests__/analysis-repository-conformance.ts
index 455e8e1f0..b9c6682a8 100644
--- a/src/__tests__/analysis-repository-conformance.ts
+++ b/src/__tests__/analysis-repository-conformance.ts
@@ -1,10 +1,16 @@
 /// <reference types="jest" />
 
 import type { DraftProject, TextAnalysis } from 'interlinearizer';
-import type { AnalysisRepository, ChangeSet, DraftExport } from '../types/analysis-repository';
+import type {
+  AnalysisLinks,
+  AnalysisRepository,
+  ChangeSet,
+  DraftExport,
+} from '../types/analysis-repository';
 import { emptyAnalysis, emptyDraft } from '../types/empty-factories';
 import { CURRENT_MODEL_VERSION } from '../types/model-version';
 import { ReadOnlyAnalysisError } from '../types/read-only-analysis-error';
+import { normalizeSurfaceForm } from '../utils/analysis-identity';
 import { scopeRecordOf } from '../utils/change-set';
 import { FIXTURE_STAMPS, makePhraseLink } from './test-helpers';
 
@@ -362,6 +368,22 @@ function changeInPlace(draft: DraftProject): void {
   });
 }
 
+/** The ids of `records`, sorted, since lookups promise no order. */
+function idsOf(records: readonly { id: string }[]): string[] {
+  return records.map(({ id }) => id).sort();
+}
+
+/** The ids of each kind of link in `links`, sorted, since lookups promise no order. */
+function linkIdsOf(links: Partial<AnalysisLinks>) {
+  return {
+    ...(links.tokenAnalysisLinks && { tokenAnalysisLinks: idsOf(links.tokenAnalysisLinks) }),
+    ...(links.phraseAnalysisLinks && { phraseAnalysisLinks: idsOf(links.phraseAnalysisLinks) }),
+    ...(links.segmentAnalysisLinks && {
+      segmentAnalysisLinks: idsOf(links.segmentAnalysisLinks),
+    }),
+  };
+}
+
 /** Expects `value` to survive a JSON round trip unchanged and to hold no `null`. */
 function expectJsonPlain(value: unknown): void {
   expect(JSON.parse(JSON.stringify(value))).toStrictEqual(value);
@@ -1097,6 +1119,220 @@ export function describeAnalysisRepositoryConformance(
       });
     });
 
+    describe('lookups', () => {
+      /** A repository over {@link fullDraft}, saved through another one so its lookups load it. */
+      async function overFullDraft(): Promise<AnalysisRepository> {
+        await (await store.open(SOURCE)).replaceAll(fullDraft());
+        return store.open(SOURCE);
+      }
+
+      it('gets each payload kind by id, once per id, skipping ids with nothing stored', async () => {
+        const repository = await overFullDraft();
+
+        await expect(
+          repository.getTokenAnalyses(['ta-and', 'ta-missing', 'ta-and']).then(idsOf),
+        ).resolves.toStrictEqual(['ta-and']);
+        await expect(repository.getPhraseAnalyses(['pa-in-the'])).resolves.toStrictEqual(
+          fullAnalysis().phraseAnalyses,
+        );
+        await expect(
+          repository.getSegmentAnalyses(['sa-exo', 'sa-missing']),
+        ).resolves.toStrictEqual(fullAnalysis().segmentAnalyses);
+      });
+
+      it('finds the token links on tokens, and the phrase links touching them, each once', async () => {
+        const repository = await overFullDraft();
+
+        await expect(
+          repository.findLinksByToken(['GEN 1:1:0', 'GEN 1:1:2', 'GEN 1:1:4']).then(linkIdsOf),
+        ).resolves.toStrictEqual({
+          tokenAnalysisLinks: ['tl-gen-and'],
+          phraseAnalysisLinks: ['pa-in-the'],
+        });
+      });
+
+      it('finds the segment links on segments', async () => {
+        const repository = await overFullDraft();
+
+        await expect(
+          repository.findLinksBySegment(['EXO 1:1', 'GEN 1:1']).then(idsOf),
+        ).resolves.toStrictEqual(['sl-exo']);
+      });
+
+      it('finds the links of every kind to analyses', async () => {
+        const repository = await overFullDraft();
+
+        await expect(
+          repository.findLinksToAnalyses(['ta-and', 'pa-in-the', 'sa-exo']).then(linkIdsOf),
+        ).resolves.toStrictEqual({
+          tokenAnalysisLinks: ['tl-exo-and', 'tl-gen-and'],
+          phraseAnalysisLinks: ['pa-in-the'],
+          segmentAnalysisLinks: ['sl-exo'],
+        });
+      });
+
+      it('finds the links of every kind into books', async () => {
+        const repository = await overFullDraft();
+
+        await expect(repository.findLinksInBooks(['GEN']).then(linkIdsOf)).resolves.toStrictEqual({
+          tokenAnalysisLinks: ['tl-gen-and', 'tl-gen-beginning'],
+          phraseAnalysisLinks: ['pa-in-the'],
+          segmentAnalysisLinks: [],
+        });
+      });
+
+      it('finds the links into books with the statuses asked for', async () => {
+        const repository = await overFullDraft();
+
+        await expect(
+          repository.findLinksInBooks(['GEN', 'EXO'], ['suggested']).then(linkIdsOf),
+        ).resolves.toStrictEqual({
+          tokenAnalysisLinks: ['tl-gen-beginning'],
+          phraseAnalysisLinks: [],
+          segmentAnalysisLinks: [],
+        });
+      });
+
+      it('finds the payloads whose surface text normalizes to a form', async () => {
+        const repository = await overFullDraft();
+        await repository.apply({
+          intent: 'addCapitalized',
+          tokenAnalyses: {
+            puts: [{ id: 'ta-And', ...FIXTURE_STAMPS, surfaceText: 'And' }],
+            deletes: [],
+          },
+        });
+
+        await expect(
+          repository.findTokenAnalysesByForm([normalizeSurfaceForm('AND')]).then(idsOf),
+        ).resolves.toStrictEqual(['ta-And', 'ta-and']);
+        await expect(
+          repository.findPhraseAnalysesByForm([normalizeSurfaceForm('In The')]).then(idsOf),
+        ).resolves.toStrictEqual(['pa-in-the']);
+      });
+
+      it('finds nothing in a draft never saved', async () => {
+        const repository = await store.open(SOURCE);
+
+        await expect(repository.findLinksInBooks(['GEN']).then(linkIdsOf)).resolves.toStrictEqual({
+          tokenAnalysisLinks: [],
+          phraseAnalysisLinks: [],
+          segmentAnalysisLinks: [],
+        });
+        await expect(repository.getTokenAnalyses(['ta-and'])).resolves.toStrictEqual([]);
+      });
+
+      it('answers from the records the applied changes leave', async () => {
+        const repository = await overFullDraft();
+        await repository.findLinksInBooks(['GEN']);
+
+        await repository.apply(mixedChanges());
+
+        await expect(
+          repository.findLinksToAnalyses(['ta-beginning', 'ta-god']).then(linkIdsOf),
+        ).resolves.toStrictEqual({
+          tokenAnalysisLinks: ['tl-gen-god'],
+          phraseAnalysisLinks: [],
+          segmentAnalysisLinks: [],
+        });
+        await expect(
+          repository.findLinksBySegment(['GEN 1:1', 'EXO 1:1']).then(idsOf),
+        ).resolves.toStrictEqual(['sl-gen']);
+        await expect(
+          repository.findLinksByToken(['GEN 1:1:2', 'GEN 1:1:13']).then(linkIdsOf),
+        ).resolves.toStrictEqual({
+          tokenAnalysisLinks: [],
+          phraseAnalysisLinks: ['pa-the-beginning'],
+        });
+        await expect(repository.getTokenAnalyses(['ta-and'])).resolves.toStrictEqual([
+          { ...fullAnalysis().tokenAnalyses[0], gloss: { en: 'and then' } },
+        ]);
+      });
+
+      it('files an edited record under its new keys only', async () => {
+        const repository = await overFullDraft();
+        await repository.findLinksInBooks(['GEN']);
+        const [, , beginning] = fullAnalysis().tokenAnalysisLinks;
+
+        await repository.apply({
+          intent: 'approve',
+          tokenAnalysisLinks: { puts: [{ ...beginning, status: 'approved' }], deletes: [] },
+        });
+
+        await expect(
+          repository.findLinksInBooks(['GEN'], ['suggested']).then(linkIdsOf),
+        ).resolves.toMatchObject({ tokenAnalysisLinks: [] });
+        await expect(
+          repository.findLinksInBooks(['GEN'], ['approved']).then(linkIdsOf),
+        ).resolves.toMatchObject({ tokenAnalysisLinks: ['tl-gen-and', 'tl-gen-beginning'] });
+      });
+
+      it('answers from a draft another repository replaced, once reloaded', async () => {
+        const repository = await overFullDraft();
+        await repository.findLinksInBooks(['GEN']);
+        await (await store.open(SOURCE)).replaceAll(exodusOnlyDraft());
+
+        await repository.exportAll();
+
+        await expect(
+          repository.findLinksInBooks(['GEN', 'EXO']).then(linkIdsOf),
+        ).resolves.toStrictEqual({
+          tokenAnalysisLinks: ['tl-exo-and'],
+          phraseAnalysisLinks: [],
+          segmentAnalysisLinks: ['sl-exo'],
+        });
+      });
+
+      it('keeps the records of different source projects apart', async () => {
+        await overFullDraft();
+
+        const other = await store.open('other-project');
+
+        await expect(other.getTokenAnalyses(['ta-and'])).resolves.toStrictEqual([]);
+      });
+
+      it('returns records the caller may change without changing what is stored', async () => {
+        const repository = await overFullDraft();
+
+        const [and] = await repository.getTokenAnalyses(['ta-and']);
+        and.surfaceText = 'changed';
+        const { tokenAnalysisLinks } = await repository.findLinksToAnalyses(['ta-and']);
+        tokenAnalysisLinks[0].status = 'rejected';
+
+        await expect(repository.getTokenAnalyses(['ta-and'])).resolves.toStrictEqual([
+          fullAnalysis().tokenAnalyses[0],
+        ]);
+        await expect(
+          repository.findLinksInBooks(['GEN', 'EXO'], ['rejected']).then(linkIdsOf),
+        ).resolves.toMatchObject({ tokenAnalysisLinks: [] });
+      });
+
+      it('keeps indexes that match its records through applies, undo and redo', async () => {
+        const repository = await overFullDraft();
+        await repository.findLinksInBooks(['GEN']);
+
+        const { inverse } = await repository.apply(mixedChanges());
+        const { inverse: redo } = await repository.apply(inverse);
+        await repository.apply(redo);
+        await repository.apply(puttingNewRecords());
+
+        await expect(repository.checkIndexes()).resolves.toStrictEqual([]);
+      });
+
+      it('answers from a read-only repository', async () => {
+        const repository = await store.openReadOnly(fullDraft());
+
+        await expect(
+          repository.findLinksToAnalyses(['ta-and']).then(linkIdsOf),
+        ).resolves.toStrictEqual({
+          tokenAnalysisLinks: ['tl-exo-and', 'tl-gen-and'],
+          phraseAnalysisLinks: [],
+          segmentAnalysisLinks: [],
+        });
+        await expect(repository.checkIndexes()).resolves.toStrictEqual([]);
+      });
+    });
+
     describe('capabilities', () => {
       it("lets a source project's draft be written", async () => {
         expect((await store.open(SOURCE)).capabilities.readOnly).toBe(false);
diff --git a/src/__tests__/main.test.ts b/src/__tests__/main.test.ts
index 5d00fe95b..b24169bbe 100644
--- a/src/__tests__/main.test.ts
+++ b/src/__tests__/main.test.ts
@@ -400,6 +400,7 @@ describe('main', () => {
           'interlinearizer.setAnalysisLanguage',
           'interlinearizer.undoEdit',
           'interlinearizer.redoEdit',
+          'interlinearizer.checkIndexes',
           'interlinearizer.openSelectProjectModal',
           'interlinearizer.openNewProjectModal',
           'interlinearizer.openProjectInfoModal',
@@ -1827,6 +1828,7 @@ describe('main', () => {
   describe('session commands', () => {
     /** A repository handing out `draft`, as storage would open one. */
     function stubRepository(draft: DraftProject, readOnly = false): AnalysisRepository {
+      const noLinks = { tokenAnalysisLinks: [], phraseAnalysisLinks: [], segmentAnalysisLinks: [] };
       return {
         capabilities: { readOnly },
         exportAll: async () => ({ draft, unreadableBooks: [] }),
@@ -1834,6 +1836,18 @@ describe('main', () => {
         replaceAll: async () => [],
         markClean: async () => {},
         apply: async (changes) => ({ inverse: changes }),
+        getTokenAnalyses: async () => [],
+        getPhraseAnalyses: async () => [],
+        getSegmentAnalyses: async () => [],
+        findLinksByToken: async () => noLinks,
+        findLinksBySegment: async () => [],
+        findLinksToAnalyses: async () => noLinks,
+        findLinksInBooks: async () => noLinks,
+        findTokenAnalysesByForm: async () => [],
+        findPhraseAnalysesByForm: async () => [],
+        checkIndexes: async () => [
+          { index: 'tokenAnalyses', key: 'ta-1', missing: ['ta-1'], extra: [] },
+        ],
       };
     }
 
@@ -1860,6 +1874,9 @@ describe('main', () => {
         redoEdit: handler<(sessionId: string) => Promise<string | undefined>>(
           'interlinearizer.redoEdit',
         ),
+        checkIndexes: handler<(sessionId: string) => Promise<string>>(
+          'interlinearizer.checkIndexes',
+        ),
       };
     }
 
@@ -2022,6 +2039,27 @@ describe('main', () => {
       );
     });
 
+    it("replies with the differences the session's repository finds in its indexes", async () => {
+      const { openSession, checkIndexes } = await activateSessionCommands();
+      const { sessionId } = JSON.parse(await openSession('src-project'));
+
+      await expect(checkIndexes(sessionId)).resolves.toBe(
+        JSON.stringify([{ index: 'tokenAnalyses', key: 'ta-1', missing: ['ta-1'], extra: [] }]),
+      );
+    });
+
+    it('logs the error and rethrows when the indexes cannot be checked', async () => {
+      const { checkIndexes } = await activateSessionCommands();
+
+      await expect(checkIndexes('not-a-session')).rejects.toThrow(
+        'no session not-a-session is open',
+      );
+      expect(__mockLogger.error).toHaveBeenCalledWith(
+        'Interlinearizer: failed to check the indexes of session not-a-session',
+        expect.any(Error),
+      );
+    });
+
     it('closes every session on deactivation', async () => {
       const { openSession } = await activateSessionCommands();
       await openSession('src-project');
diff --git a/src/__tests__/services/analysisIndex.test.ts b/src/__tests__/services/analysisIndex.test.ts
new file mode 100644
index 000000000..61529869a
--- /dev/null
+++ b/src/__tests__/services/analysisIndex.test.ts
@@ -0,0 +1,177 @@
+/// <reference types="jest" />
+
+import type { TextAnalysis } from 'interlinearizer';
+import { AnalysisIndex } from '../../services/analysisIndex';
+import { emptyAnalysis } from '../../types/empty-factories';
+import { normalizeSurfaceForm } from '../../utils/analysis-identity';
+import { FIXTURE_STAMPS, makePhraseLink } from '../test-helpers';
+
+const link = { ...FIXTURE_STAMPS, status: 'approved' as const };
+
+/** Records in GEN and EXO, with a heading's segment in GEN and a suggested link in EXO. */
+function analysis(): TextAnalysis {
+  return {
+    segmentAnalyses: [{ id: 'sa-1', ...FIXTURE_STAMPS, surfaceText: 'The Creation' }],
+    segmentAnalysisLinks: [{ ...link, id: 'sl-1', analysisId: 'sa-1', segmentId: 'GEN 1:1/s1' }],
+    tokenAnalyses: [
+      { id: 'ta-and', ...FIXTURE_STAMPS, surfaceText: 'and' },
+      { id: 'ta-And', ...FIXTURE_STAMPS, surfaceText: 'And' },
+    ],
+    tokenAnalysisLinks: [
+      {
+        ...link,
+        id: 'tl-gen',
+        analysisId: 'ta-and',
+        token: { tokenRef: 'GEN 1:1:0', surfaceText: 'and' },
+      },
+      {
+        ...link,
+        id: 'tl-exo',
+        analysisId: 'ta-And',
+        status: 'suggested',
+        token: { tokenRef: 'EXO 1:1:0', surfaceText: 'And' },
+      },
+    ],
+    phraseAnalyses: [{ id: 'pa-1', ...FIXTURE_STAMPS, surfaceText: 'In the' }],
+    phraseAnalysisLinks: [makePhraseLink('pa-1', ['GEN 1:1:4', 'GEN 1:1:7'])],
+  };
+}
+
+const ids = (records: readonly { id: string }[]) => records.map(({ id }) => id).sort();
+
+describe('AnalysisIndex', () => {
+  it('gets payloads of each kind by id', () => {
+    const index = new AnalysisIndex(analysis());
+
+    expect(ids(index.getTokenAnalyses(['ta-and', 'missing']))).toStrictEqual(['ta-and']);
+    expect(ids(index.getPhraseAnalyses(['pa-1']))).toStrictEqual(['pa-1']);
+    expect(ids(index.getSegmentAnalyses(['sa-1']))).toStrictEqual(['sa-1']);
+  });
+
+  it('finds token links by token ref, and phrase links by any of their tokens', () => {
+    const { tokenAnalysisLinks, phraseAnalysisLinks } = new AnalysisIndex(
+      analysis(),
+    ).findLinksByToken(['GEN 1:1:0', 'GEN 1:1:7']);
+
+    expect(ids(tokenAnalysisLinks)).toStrictEqual(['tl-gen']);
+    expect(ids(phraseAnalysisLinks)).toStrictEqual(['pa-1']);
+  });
+
+  it('finds segment links by segment id', () => {
+    expect(ids(new AnalysisIndex(analysis()).findLinksBySegment(['GEN 1:1/s1']))).toStrictEqual([
+      'sl-1',
+    ]);
+  });
+
+  it('finds the links of every kind to analyses', () => {
+    const links = new AnalysisIndex(analysis()).findLinksToAnalyses(['ta-and', 'pa-1', 'sa-1']);
+
+    expect(ids(links.tokenAnalysisLinks)).toStrictEqual(['tl-gen']);
+    expect(ids(links.phraseAnalysisLinks)).toStrictEqual(['pa-1']);
+    expect(ids(links.segmentAnalysisLinks)).toStrictEqual(['sl-1']);
+  });
+
+  it('files a heading segment link and a phrase link under their books', () => {
+    const links = new AnalysisIndex(analysis()).findLinksInBooks(['GEN']);
+
+    expect(ids(links.tokenAnalysisLinks)).toStrictEqual(['tl-gen']);
+    expect(ids(links.phraseAnalysisLinks)).toStrictEqual(['pa-1']);
+    expect(ids(links.segmentAnalysisLinks)).toStrictEqual(['sl-1']);
+  });
+
+  it('finds the links into books with the statuses asked for', () => {
+    const links = new AnalysisIndex(analysis()).findLinksInBooks(['GEN', 'EXO'], ['suggested']);
+
+    expect(ids(links.tokenAnalysisLinks)).toStrictEqual(['tl-exo']);
+    expect(links.phraseAnalysisLinks).toStrictEqual([]);
+    expect(links.segmentAnalysisLinks).toStrictEqual([]);
+  });
+
+  it('finds payloads by normalized form', () => {
+    const index = new AnalysisIndex(analysis());
+
+    expect(ids(index.findTokenAnalysesByForm([normalizeSurfaceForm('AND')]))).toStrictEqual([
+      'ta-And',
+      'ta-and',
+    ]);
+    expect(ids(index.findPhraseAnalysesByForm(['in the']))).toStrictEqual(['pa-1']);
+  });
+
+  it('keeps every lookup current as changes apply', () => {
+    const index = new AnalysisIndex(analysis());
+
+    index.apply({
+      intent: 'edit',
+      tokenAnalyses: {
+        puts: [{ id: 'ta-and', ...FIXTURE_STAMPS, surfaceText: 'but' }],
+        deletes: [],
+      },
+      tokenAnalysisLinks: { puts: [], deletes: ['tl-exo'] },
+      phraseAnalyses: { puts: [], deletes: ['pa-1'] },
+      phraseAnalysisLinks: { puts: [], deletes: ['pa-1'] },
+      segmentAnalyses: { puts: [], deletes: ['sa-1'] },
+      segmentAnalysisLinks: { puts: [], deletes: ['sl-1'] },
+    });
+
+    expect(ids(index.findTokenAnalysesByForm(['and']))).toStrictEqual(['ta-And']);
+    expect(ids(index.findTokenAnalysesByForm(['but']))).toStrictEqual(['ta-and']);
+    expect(index.findLinksInBooks(['GEN', 'EXO'])).toStrictEqual({
+      tokenAnalysisLinks: [analysis().tokenAnalysisLinks[0]],
+      phraseAnalysisLinks: [],
+      segmentAnalysisLinks: [],
+    });
+    expect(index.findPhraseAnalysesByForm(['in the'])).toStrictEqual([]);
+    expect(index.getSegmentAnalyses(['sa-1'])).toStrictEqual([]);
+  });
+
+  describe('differencesFrom', () => {
+    it('reports none against the analysis it was built from', () => {
+      expect(new AnalysisIndex(analysis()).differencesFrom(analysis())).toStrictEqual([]);
+    });
+
+    it('reports none once kept current through changes the analysis also took', () => {
+      const index = new AnalysisIndex(analysis());
+      const changed = analysis();
+      changed.tokenAnalysisLinks.pop();
+
+      index.apply({ intent: 'delete', tokenAnalysisLinks: { puts: [], deletes: ['tl-exo'] } });
+
+      expect(index.differencesFrom(changed)).toStrictEqual([]);
+    });
+
+    it('reports the records and entries of every kind that an analysis holds differently', () => {
+      const differences = new AnalysisIndex(emptyAnalysis()).differencesFrom(analysis());
+
+      expect(new Set(differences.map(({ index }) => index))).toStrictEqual(
+        new Set([
+          'tokenAnalyses',
+          'tokenAnalyses by form',
+          'phraseAnalyses',
+          'phraseAnalyses by form',
+          'segmentAnalyses',
+          'tokenAnalysisLinks',
+          'tokenAnalysisLinks by analysisId',
+          'tokenAnalysisLinks by book',
+          'tokenAnalysisLinks by bookStatus',
+          'tokenAnalysisLinks by tokenRef',
+          'phraseAnalysisLinks',
+          'phraseAnalysisLinks by analysisId',
+          'phraseAnalysisLinks by book',
+          'phraseAnalysisLinks by bookStatus',
+          'phraseAnalysisLinks by tokenRef',
+          'segmentAnalysisLinks',
+          'segmentAnalysisLinks by analysisId',
+          'segmentAnalysisLinks by book',
+          'segmentAnalysisLinks by bookStatus',
+          'segmentAnalysisLinks by segmentId',
+        ]),
+      );
+      expect(differences).toContainEqual({
+        index: 'tokenAnalysisLinks by bookStatus',
+        key: 'EXO/suggested',
+        missing: ['tl-exo'],
+        extra: [],
+      });
+    });
+  });
+});
diff --git a/src/__tests__/services/draftRepository.test.ts b/src/__tests__/services/draftRepository.test.ts
index e12aec981..38e0e8d7b 100644
--- a/src/__tests__/services/draftRepository.test.ts
+++ b/src/__tests__/services/draftRepository.test.ts
@@ -377,4 +377,45 @@ describe('DraftRepository', () => {
       expect(records.get(draftAnalysisKey('src', 'GEN'))).not.toContain('and then');
     });
   });
+
+  describe('lookups', () => {
+    it('load the draft once, answering later lookups from what they kept', async () => {
+      const { storage } = memoryStorage();
+      await new DraftRepository(storage, 'src', silentLogger()).replaceAll(twoBookDraft());
+      const repository = new DraftRepository(storage, 'src', silentLogger());
+      const read = jest.spyOn(storage, 'read');
+
+      await repository.findLinksInBooks(['GEN']);
+      const readsAfterFirst = read.mock.calls.length;
+      await repository.findLinksToAnalyses(['ta-and']);
+
+      expect(readsAfterFirst).toBeGreaterThan(0);
+      expect(read).toHaveBeenCalledTimes(readsAfterFirst);
+    });
+
+    it('answer from what an apply left without loading the draft again', async () => {
+      const { storage } = memoryStorage();
+      const repository = new DraftRepository(storage, 'src', silentLogger());
+      await repository.apply({
+        intent: 'add',
+        tokenAnalyses: { puts: twoBookAnalysis().tokenAnalyses, deletes: [] },
+      });
+      const read = jest.spyOn(storage, 'read');
+
+      await expect(repository.getTokenAnalyses(['ta-and'])).resolves.toStrictEqual(
+        twoBookAnalysis().tokenAnalyses,
+      );
+      expect(read).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('checkIndexes', () => {
+    it('reports nothing while it keeps no index', async () => {
+      const { storage } = memoryStorage();
+      const repository = new DraftRepository(storage, 'src', silentLogger());
+      await repository.replaceAll(twoBookDraft());
+
+      await expect(repository.checkIndexes()).resolves.toStrictEqual([]);
+    });
+  });
 });
diff --git a/src/__tests__/services/indexedRepository.test.ts b/src/__tests__/services/indexedRepository.test.ts
new file mode 100644
index 000000000..290a6cb98
--- /dev/null
+++ b/src/__tests__/services/indexedRepository.test.ts
@@ -0,0 +1,70 @@
+/// <reference types="jest" />
+
+import type { TextAnalysis } from 'interlinearizer';
+import { AnalysisIndex } from '../../services/analysisIndex';
+import { type IndexedAnalysis, IndexedRepository } from '../../services/indexedRepository';
+import { emptyAnalysis } from '../../types/empty-factories';
+import { FIXTURE_STAMPS } from '../test-helpers';
+
+/** Answers lookups from an index over `records`, keeping it as `keep` says. */
+class StubRepository extends IndexedRepository {
+  readonly kept: IndexedAnalysis | undefined;
+
+  private readonly index: AnalysisIndex;
+
+  constructor(records: TextAnalysis, keep: 'kept' | 'none') {
+    super();
+    this.index = new AnalysisIndex(records);
+    this.kept = keep === 'kept' ? { analysis: records, index: this.index } : undefined;
+  }
+
+  protected async indexed(): Promise<AnalysisIndex> {
+    return this.index;
+  }
+
+  protected keptIndex(): IndexedAnalysis | undefined {
+    return this.kept;
+  }
+}
+
+function analysis(): TextAnalysis {
+  return {
+    ...emptyAnalysis(),
+    tokenAnalyses: [{ id: 'ta-and', ...FIXTURE_STAMPS, surfaceText: 'and' }],
+  };
+}
+
+describe('IndexedRepository', () => {
+  it('answers lookups from its index', async () => {
+    await expect(
+      new StubRepository(analysis(), 'none').getTokenAnalyses(['ta-and']),
+    ).resolves.toStrictEqual(analysis().tokenAnalyses);
+  });
+
+  it('hands out copies of the records its index holds', async () => {
+    const repository = new StubRepository(analysis(), 'none');
+
+    const [and] = await repository.getTokenAnalyses(['ta-and']);
+    and.surfaceText = 'changed';
+
+    await expect(repository.getTokenAnalyses(['ta-and'])).resolves.toStrictEqual(
+      analysis().tokenAnalyses,
+    );
+  });
+
+  it('reports the differences of the index it keeps from its analysis', async () => {
+    const repository = new StubRepository(analysis(), 'kept');
+    repository.kept?.analysis.tokenAnalyses.pop();
+
+    await expect(repository.checkIndexes()).resolves.toContainEqual({
+      index: 'tokenAnalyses',
+      key: 'ta-and',
+      missing: [],
+      extra: ['ta-and'],
+    });
+  });
+
+  it('reports nothing while it keeps no index', async () => {
+    await expect(new StubRepository(analysis(), 'none').checkIndexes()).resolves.toStrictEqual([]);
+  });
+});
diff --git a/src/__tests__/services/projectStorage.test.ts b/src/__tests__/services/projectStorage.test.ts
index 24a6a63ab..948c16f9e 100644
--- a/src/__tests__/services/projectStorage.test.ts
+++ b/src/__tests__/services/projectStorage.test.ts
@@ -24,6 +24,7 @@ import {
   updateProjectMetadata,
 } from '../../services/projectStorage';
 import { summarizeProject } from '../../services/projectSummaries';
+import type { AnalysisRepository } from '../../types/analysis-repository';
 import { ReadOnlyAnalysisError } from '../../types/read-only-analysis-error';
 import { emptyAnalysis, emptyDraft } from '../../types/empty-factories';
 import { removeBookFromAnalysis } from '../../utils/analysis-book';
@@ -2915,6 +2916,42 @@ describe('projectStorage', () => {
       expect(analysis.tokenAnalysisLinks).toStrictEqual([]);
     });
 
+    it.each([
+      ['getTokenAnalyses', (r: AnalysisRepository) => r.getTokenAnalyses(['analysis-GEN']), 1],
+      ['getPhraseAnalyses', (r: AnalysisRepository) => r.getPhraseAnalyses(['p']), 0],
+      ['getSegmentAnalyses', (r: AnalysisRepository) => r.getSegmentAnalyses(['s']), 0],
+      ['findLinksBySegment', (r: AnalysisRepository) => r.findLinksBySegment(['GEN 1:1']), 0],
+      [
+        'findLinksByToken',
+        (r: AnalysisRepository) =>
+          r.findLinksByToken(['GEN 1:1!0']).then((l) => l.tokenAnalysisLinks),
+        1,
+      ],
+      [
+        'findLinksToAnalyses',
+        (r: AnalysisRepository) =>
+          r.findLinksToAnalyses(['analysis-GEN']).then((l) => l.tokenAnalysisLinks),
+        1,
+      ],
+      [
+        'findLinksInBooks',
+        (r: AnalysisRepository) =>
+          r.findLinksInBooks(['GEN'], ['approved']).then((l) => l.tokenAnalysisLinks),
+        1,
+      ],
+      [
+        'findTokenAnalysesByForm',
+        (r: AnalysisRepository) => r.findTokenAnalysesByForm(['word-gen']),
+        1,
+      ],
+      ['findPhraseAnalysesByForm', (r: AnalysisRepository) => r.findPhraseAnalysesByForm(['x']), 0],
+      ['checkIndexes', (r: AnalysisRepository) => r.checkIndexes(), 0],
+    ])('answers %s from the draft saveDraft saved', async (_name, lookup, count) => {
+      await saveDraft(token, 'src-proj', makeDraftSpanningBooks('src-proj', 'GEN'));
+
+      await expect(lookup(openDraftRepository(token, 'src-proj'))).resolves.toHaveLength(count);
+    });
+
     it('waits for a draft call already made before reading', async () => {
       let finishWrite: () => void = () => {};
       __mockWriteUserData.mockImplementationOnce(
diff --git a/src/__tests__/services/pt9ImportRepository.test.ts b/src/__tests__/services/pt9ImportRepository.test.ts
index 25a85d471..52723ed37 100644
--- a/src/__tests__/services/pt9ImportRepository.test.ts
+++ b/src/__tests__/services/pt9ImportRepository.test.ts
@@ -124,4 +124,56 @@ describe('Pt9ImportRepository', () => {
       expect(readProject).not.toHaveBeenCalled();
     });
   });
+
+  describe('lookups', () => {
+    const imported = () =>
+      makeImport({
+        analysis: {
+          ...emptyAnalysis(),
+          tokenAnalyses: [{ id: 'ta-1', ...FIXTURE_STAMPS, surfaceText: 'and' }],
+        },
+      });
+
+    it("answer from the import's records, reading it once", async () => {
+      const readProject = jest.fn(async () => imported());
+      const repository = new Pt9ImportRepository('import-id', readProject);
+
+      await expect(repository.getTokenAnalyses(['ta-1'])).resolves.toStrictEqual(
+        imported().analysis.tokenAnalyses,
+      );
+      await repository.findTokenAnalysesByForm(['and']);
+
+      expect(readProject).toHaveBeenCalledTimes(1);
+    });
+
+    it('read the import again after a load', async () => {
+      const readProject = jest.fn(async () => imported());
+      const repository = new Pt9ImportRepository('import-id', readProject);
+      await repository.getTokenAnalyses(['ta-1']);
+
+      await repository.exportAll();
+      await repository.getTokenAnalyses(['ta-1']);
+
+      expect(readProject).toHaveBeenCalledTimes(3);
+    });
+
+    it('refuse when no import is stored', async () => {
+      await expect(repositoryOver(undefined).getTokenAnalyses(['ta-1'])).rejects.toThrow(
+        'no Paratext 9 import is stored as project import-id',
+      );
+    });
+  });
+
+  describe('checkIndexes', () => {
+    it('reports nothing before a lookup', async () => {
+      await expect(repositoryOver(makeImport()).checkIndexes()).resolves.toStrictEqual([]);
+    });
+
+    it('reports nothing after a lookup, since an import never changes', async () => {
+      const repository = repositoryOver(makeImport());
+      await repository.getTokenAnalyses(['ta-1']);
+
+      await expect(repository.checkIndexes()).resolves.toStrictEqual([]);
+    });
+  });
 });
diff --git a/src/__tests__/services/recordTable.test.ts b/src/__tests__/services/recordTable.test.ts
new file mode 100644
index 000000000..b4245db81
--- /dev/null
+++ b/src/__tests__/services/recordTable.test.ts
@@ -0,0 +1,96 @@
+/// <reference types="jest" />
+
+import { RecordTable } from '../../services/recordTable';
+
+type Item = { id: string; tags: string[]; note?: string };
+
+const keyers = { tag: (item: Item) => item.tags };
+
+function tableOf(...items: Item[]) {
+  return new RecordTable('items', keyers, items);
+}
+
+describe('RecordTable', () => {
+  it('gets records by id, once per id, skipping ids with nothing stored', () => {
+    const a = { id: 'a', tags: [] };
+
+    expect(tableOf(a).get(['a', 'missing', 'a'])).toStrictEqual([a]);
+  });
+
+  it('finds the records filed under any of the keys, each once', () => {
+    const a = { id: 'a', tags: ['x', 'y'] };
+    const b = { id: 'b', tags: ['y'] };
+    const c = { id: 'c', tags: ['z'] };
+
+    expect(tableOf(a, b, c).find('tag', ['x', 'y', 'missing'])).toStrictEqual([a, b]);
+  });
+
+  it('files a record once under a key its keyer returns twice', () => {
+    const table = tableOf({ id: 'a', tags: ['x', 'x'] });
+
+    table.apply({ puts: [], deletes: ['a'] });
+
+    expect(table.find('tag', ['x'])).toStrictEqual([]);
+    expect(table.differencesFrom(tableOf())).toStrictEqual([]);
+  });
+
+  it('files a put record under its new keys only', () => {
+    const table = tableOf({ id: 'a', tags: ['x'] });
+    const moved = { id: 'a', tags: ['y'] };
+
+    table.apply({ puts: [moved], deletes: [] });
+
+    expect(table.find('tag', ['x'])).toStrictEqual([]);
+    expect(table.find('tag', ['y'])).toStrictEqual([moved]);
+  });
+
+  it('unfiles a deleted record, skipping an id with nothing stored', () => {
+    const table = tableOf({ id: 'a', tags: ['x'] });
+
+    table.apply({ puts: [], deletes: ['a', 'missing'] });
+
+    expect(table.get(['a'])).toStrictEqual([]);
+    expect(table.find('tag', ['x'])).toStrictEqual([]);
+  });
+
+  it('applies nothing for absent changes', () => {
+    const table = tableOf({ id: 'a', tags: ['x'] });
+
+    table.apply(undefined);
+
+    expect(table.differencesFrom(tableOf({ id: 'a', tags: ['x'] }))).toStrictEqual([]);
+  });
+
+  describe('differencesFrom', () => {
+    it('reports none against a table holding the same records', () => {
+      const items = [
+        { id: 'a', tags: ['x'] },
+        { id: 'b', tags: ['x', 'y'] },
+      ];
+
+      expect(tableOf(...items).differencesFrom(tableOf(...items))).toStrictEqual([]);
+    });
+
+    it('reports a record the kept table lacks, and the entries filing it', () => {
+      expect(tableOf().differencesFrom(tableOf({ id: 'a', tags: ['x'] }))).toStrictEqual([
+        { index: 'items', key: 'a', missing: ['a'], extra: [] },
+        { index: 'items by tag', key: 'x', missing: ['a'], extra: [] },
+      ]);
+    });
+
+    it('reports a record only the kept table holds, and the entries filing it', () => {
+      expect(tableOf({ id: 'a', tags: ['x'] }).differencesFrom(tableOf())).toStrictEqual([
+        { index: 'items', key: 'a', missing: [], extra: ['a'] },
+        { index: 'items by tag', key: 'x', missing: [], extra: ['a'] },
+      ]);
+    });
+
+    it('reports a record whose kept copy differs as both missing and extra', () => {
+      const kept = tableOf({ id: 'a', tags: [], note: 'old' });
+
+      expect(kept.differencesFrom(tableOf({ id: 'a', tags: [], note: 'new' }))).toStrictEqual([
+        { index: 'items', key: 'a', missing: ['a'], extra: ['a'] },
+      ]);
+    });
+  });
+});
diff --git a/src/__tests__/utils/change-set.test.ts b/src/__tests__/utils/change-set.test.ts
index e07b209f8..7e6e57d1d 100644
--- a/src/__tests__/utils/change-set.test.ts
+++ b/src/__tests__/utils/change-set.test.ts
@@ -103,22 +103,6 @@ describe('applyChangeSet', () => {
     expect(stored).toStrictEqual(draftOf(payload('a')));
   });
 
-  it('holds copies of the records the changes put', () => {
-    const put = payload('b');
-    const scope = scopeRecordOf(draftOf());
-    const { draft } = applyChangeSet(draftOf(), {
-      intent: 'add',
-      scope,
-      tokenAnalyses: { puts: [put], deletes: [] },
-    });
-
-    put.surfaceText = 'changed';
-    scope.analysisLanguages.push('fr');
-
-    expect(draft.analysis.tokenAnalyses).toStrictEqual([payload('b')]);
-    expect(draft.analysisLanguages).toStrictEqual(['en']);
-  });
-
   it('refuses an id both put and deleted', () => {
     expect(() =>
       applyChangeSet(draftOf(payload('a')), {
diff --git a/src/__tests__/utils/json-copy.test.ts b/src/__tests__/utils/json-copy.test.ts
new file mode 100644
index 000000000..1ecdd4b5f
--- /dev/null
+++ b/src/__tests__/utils/json-copy.test.ts
@@ -0,0 +1,16 @@
+/// <reference types="jest" />
+
+import { jsonCopy } from '../../utils/json-copy';
+
+describe('jsonCopy', () => {
+  it('copies a JSON-plain value deeply, sharing nothing with it', () => {
+    const value = { gloss: { en: 'and' }, morphemes: [{ form: 'and' }] };
+
+    const copy = jsonCopy(value);
+    copy.gloss.en = 'changed';
+    copy.morphemes[0].form = 'changed';
+
+    expect(copy).not.toBe(value);
+    expect(value).toStrictEqual({ gloss: { en: 'and' }, morphemes: [{ form: 'and' }] });
+  });
+});
diff --git a/src/main.ts b/src/main.ts
index bade29711..e1a6953a2 100644
--- a/src/main.ts
+++ b/src/main.ts
@@ -806,6 +806,25 @@ async function redoEdit(sessionId: string): Promise<string | undefined> {
   }
 }
 
+/**
+ * Rebuilds a session's derived indexes from its records and reports where the kept ones differ, for
+ * debugging.
+ *
+ * @returns A JSON string of the differences, empty when there are none.
+ * @throws If the session is not open, or its records cannot be read. The error is logged before
+ *   rethrowing.
+ */
+async function checkIndexes(sessionId: string): Promise<string> {
+  try {
+    return JSON.stringify(
+      await sessions.run(sessionId, (session) => session.repository.checkIndexes()),
+    );
+  } catch (e) {
+    logger.error(`Interlinearizer: failed to check the indexes of session ${sessionId}`, e);
+    throw e;
+  }
+}
+
 /**
  * Returns a summary of every interlinearizer project for the given source project as a JSON string.
  * The WebView deserializes this to populate its project picker and to decide whether to prompt
@@ -1411,6 +1430,23 @@ export async function activate(context: ExecutionActivationContext): Promise<voi
     },
   );
 
+  const checkIndexesCommandRegistration = await papi.commands.registerCommand(
+    'interlinearizer.checkIndexes',
+    checkIndexes,
+    {
+      method: {
+        summary:
+          "Rebuild a session's derived indexes from its records and report where the kept ones differ, for debugging",
+        params: [sessionIdParam],
+        result: {
+          name: 'return value',
+          summary: 'JSON-stringified [{ index, key, missing, extra }]; empty when none differ',
+          schema: { type: 'string' },
+        },
+      },
+    },
+  );
+
   const setPerfMarksCommandRegistration = await papi.commands.registerCommand(
     'interlinearizer.setPerfMarks',
     async (enabled: boolean) => setHostPerfMarks(enabled),
@@ -1786,6 +1822,7 @@ export async function activate(context: ExecutionActivationContext): Promise<voi
     setAnalysisLanguageCommandRegistration,
     undoEditCommandRegistration,
     redoEditCommandRegistration,
+    checkIndexesCommandRegistration,
     setPerfMarksCommandRegistration,
     readPerfCommandRegistration,
     updateProjectMetadataCommandRegistration,
diff --git a/src/services/analysisIndex.ts b/src/services/analysisIndex.ts
new file mode 100644
index 000000000..a611b2915
--- /dev/null
+++ b/src/services/analysisIndex.ts
@@ -0,0 +1,186 @@
+import type {
+  AssignmentStatus,
+  PhraseAnalysis,
+  PhraseAnalysisLink,
+  SegmentAnalysis,
+  SegmentAnalysisLink,
+  TextAnalysis,
+  TokenAnalysis,
+  TokenAnalysisLink,
+} from 'interlinearizer';
+import type { AnalysisLinks, ChangeSet, IndexDifference } from '../types/analysis-repository';
+import { bookOfRef } from '../utils/analysis-book';
+import { normalizeSurfaceForm } from '../utils/analysis-identity';
+import { RecordTable } from './recordTable';
+
+/** The key filing a link by its book and status. */
+function bookStatusKey(bookCode: string, status: AssignmentStatus): string {
+  return `${bookCode}/${status}`;
+}
+
+/** The indexes every kind of link is filed in, given where a link of that kind sits. */
+function linkKeyers<Link extends { analysisId: string; status: AssignmentStatus }>(
+  bookOf: (link: Link) => string,
+) {
+  return {
+    analysisId: (link: Link) => [link.analysisId],
+    book: (link: Link) => [bookOf(link)],
+    bookStatus: (link: Link) => [bookStatusKey(bookOf(link), link.status)],
+  };
+}
+
+const formKeyers = {
+  form: (payload: { surfaceText: string }) => [normalizeSurfaceForm(payload.surfaceText)],
+};
+
+/**
+ * An analysis's records by id, with the derived indexes its lookups answer from. Built from the
+ * records and kept current as changes are applied; the records it hands out are its own.
+ */
+export class AnalysisIndex {
+  private readonly tokenAnalyses: RecordTable<TokenAnalysis, 'form'>;
+
+  private readonly phraseAnalyses: RecordTable<PhraseAnalysis, 'form'>;
+
+  private readonly segmentAnalyses: RecordTable<SegmentAnalysis, never>;
+
+  private readonly tokenLinks: RecordTable<
+    TokenAnalysisLink,
+    'analysisId' | 'book' | 'bookStatus' | 'tokenRef'
+  >;
+
+  private readonly phraseLinks: RecordTable<
+    PhraseAnalysisLink,
+    'analysisId' | 'book' | 'bookStatus' | 'tokenRef'
+  >;
+
+  private readonly segmentLinks: RecordTable<
+    SegmentAnalysisLink,
+    'analysisId' | 'book' | 'bookStatus' | 'segmentId'
+  >;
+
+  constructor(analysis: TextAnalysis) {
+    this.tokenAnalyses = new RecordTable('tokenAnalyses', formKeyers, analysis.tokenAnalyses);
+    this.phraseAnalyses = new RecordTable('phraseAnalyses', formKeyers, analysis.phraseAnalyses);
+    this.segmentAnalyses = new RecordTable('segmentAnalyses', {}, analysis.segmentAnalyses);
+    this.tokenLinks = new RecordTable(
+      'tokenAnalysisLinks',
+      {
+        ...linkKeyers((link: TokenAnalysisLink) => bookOfRef(link.token.tokenRef)),
+        tokenRef: (link) => [link.token.tokenRef],
+      },
+      analysis.tokenAnalysisLinks,
+    );
+    this.phraseLinks = new RecordTable(
+      'phraseAnalysisLinks',
+      {
+        // Every token of a phrase shares a book, so the first one places the whole run.
+        ...linkKeyers((link: PhraseAnalysisLink) => bookOfRef(link.tokens[0].tokenRef)),
+        tokenRef: (link) => link.tokens.map(({ tokenRef }) => tokenRef),
+      },
+      analysis.phraseAnalysisLinks,
+    );
+    this.segmentLinks = new RecordTable(
+      'segmentAnalysisLinks',
+      {
+        ...linkKeyers((link: SegmentAnalysisLink) => bookOfRef(link.segmentId)),
+        segmentId: (link) => [link.segmentId],
+      },
+      analysis.segmentAnalysisLinks,
+    );
+  }
+
+  /** Applies `changes`, whose ids appear at most once in each record kind, taking their records. */
+  apply(changes: ChangeSet): void {
+    this.tokenAnalyses.apply(changes.tokenAnalyses);
+    this.phraseAnalyses.apply(changes.phraseAnalyses);
+    this.segmentAnalyses.apply(changes.segmentAnalyses);
+    this.tokenLinks.apply(changes.tokenAnalysisLinks);
+    this.phraseLinks.apply(changes.phraseAnalysisLinks);
+    this.segmentLinks.apply(changes.segmentAnalysisLinks);
+  }
+
+  /** The token analyses stored under `ids`, each once; an id with none stored is skipped. */
+  getTokenAnalyses(ids: readonly string[]): TokenAnalysis[] {
+    return this.tokenAnalyses.get(ids);
+  }
+
+  /** The phrase analyses stored under `ids`, each once; an id with none stored is skipped. */
+  getPhraseAnalyses(ids: readonly string[]): PhraseAnalysis[] {
+    return this.phraseAnalyses.get(ids);
+  }
+
+  /** The segment analyses stored under `ids`, each once; an id with none stored is skipped. */
+  getSegmentAnalyses(ids: readonly string[]): SegmentAnalysis[] {
+    return this.segmentAnalyses.get(ids);
+  }
+
+  /** The token links on the tokens `tokenRefs` names, and the phrase links touching any of them. */
+  findLinksByToken(
+    tokenRefs: readonly string[],
+  ): Pick<AnalysisLinks, 'tokenAnalysisLinks' | 'phraseAnalysisLinks'> {
+    return {
+      tokenAnalysisLinks: this.tokenLinks.find('tokenRef', tokenRefs),
+      phraseAnalysisLinks: this.phraseLinks.find('tokenRef', tokenRefs),
+    };
+  }
+
+  /** The segment links on the segments `segmentIds` names. */
+  findLinksBySegment(segmentIds: readonly string[]): SegmentAnalysisLink[] {
+    return this.segmentLinks.find('segmentId', segmentIds);
+  }
+
+  /** The links of every kind to the analyses `analysisIds` names. */
+  findLinksToAnalyses(analysisIds: readonly string[]): AnalysisLinks {
+    return {
+      tokenAnalysisLinks: this.tokenLinks.find('analysisId', analysisIds),
+      phraseAnalysisLinks: this.phraseLinks.find('analysisId', analysisIds),
+      segmentAnalysisLinks: this.segmentLinks.find('analysisId', analysisIds),
+    };
+  }
+
+  /** The links into the books `bookCodes` names, of any status when `statuses` is absent. */
+  findLinksInBooks(
+    bookCodes: readonly string[],
+    statuses?: readonly AssignmentStatus[],
+  ): AnalysisLinks {
+    if (!statuses) {
+      return {
+        tokenAnalysisLinks: this.tokenLinks.find('book', bookCodes),
+        phraseAnalysisLinks: this.phraseLinks.find('book', bookCodes),
+        segmentAnalysisLinks: this.segmentLinks.find('book', bookCodes),
+      };
+    }
+    const keys = bookCodes.flatMap((bookCode) =>
+      statuses.map((status) => bookStatusKey(bookCode, status)),
+    );
+    return {
+      tokenAnalysisLinks: this.tokenLinks.find('bookStatus', keys),
+      phraseAnalysisLinks: this.phraseLinks.find('bookStatus', keys),
+      segmentAnalysisLinks: this.segmentLinks.find('bookStatus', keys),
+    };
+  }
+
+  /** The token analyses whose surface text normalizes to one of `normalizedForms`. */
+  findTokenAnalysesByForm(normalizedForms: readonly string[]): TokenAnalysis[] {
+    return this.tokenAnalyses.find('form', normalizedForms);
+  }
+
+  /** The phrase analyses whose surface text normalizes to one of `normalizedForms`. */
+  findPhraseAnalysesByForm(normalizedForms: readonly string[]): PhraseAnalysis[] {
+    return this.phraseAnalyses.find('form', normalizedForms);
+  }
+
+  /** Where this index differs from one built afresh from `analysis`. */
+  differencesFrom(analysis: TextAnalysis): IndexDifference[] {
+    const rebuilt = new AnalysisIndex(analysis);
+    return [
+      ...this.tokenAnalyses.differencesFrom(rebuilt.tokenAnalyses),
+      ...this.phraseAnalyses.differencesFrom(rebuilt.phraseAnalyses),
+      ...this.segmentAnalyses.differencesFrom(rebuilt.segmentAnalyses),
+      ...this.tokenLinks.differencesFrom(rebuilt.tokenLinks),
+      ...this.phraseLinks.differencesFrom(rebuilt.phraseLinks),
+      ...this.segmentLinks.differencesFrom(rebuilt.segmentLinks),
+    ];
+  }
+}
diff --git a/src/services/draftRepository.ts b/src/services/draftRepository.ts
index a81e8f72d..8b4fb3c9a 100644
--- a/src/services/draftRepository.ts
+++ b/src/services/draftRepository.ts
@@ -20,7 +20,10 @@ import {
 import { mergeAnalyses, splitAnalysisByBook } from '../utils/analysis-book';
 import { reportAnalysisViolations } from '../utils/analysis-violations';
 import { applyChangeSet } from '../utils/change-set';
+import { jsonCopy } from '../utils/json-copy';
 import { perfTime, perfTimeAsync, perfTimeAsyncExcluding } from '../utils/perf-marks';
+import { AnalysisIndex } from './analysisIndex';
+import { IndexedRepository, type IndexedAnalysis } from './indexedRepository';
 import { draftAnalysisKey, draftJournalKey, draftKey } from './storageKeys';
 
 /**
@@ -104,7 +107,7 @@ type LoadedShard = {
  *
  * Calls on one instance must not overlap.
  */
-export class DraftRepository implements AnalysisRepository {
+export class DraftRepository extends IndexedRepository implements AnalysisRepository {
   readonly capabilities: RepositoryCapabilities = { readOnly: false };
 
   private readonly storage: KeyValueStorage;
@@ -129,13 +132,14 @@ export class DraftRepository implements AnalysisRepository {
   private loaded = false;
 
   /**
-   * The draft as this instance's last apply left it, which the next apply builds on. Dropped by
-   * every load and by every write but an apply, since each may come from a caller holding another
-   * draft.
+   * The draft as this instance last applied changes to it or answered a lookup from it, with the
+   * index over its records. Dropped by every load and by every write but an apply, since each may
+   * come from a caller holding another draft.
    */
-  private current: DraftProject | undefined;
+  private current: { draft: DraftProject; index: AnalysisIndex } | undefined;
 
   constructor(storage: KeyValueStorage, sourceProjectId: string, logger: WarningLogger) {
+    super();
     this.storage = storage;
     this.logger = logger;
     this.sourceProjectId = sourceProjectId;
@@ -252,9 +256,10 @@ export class DraftRepository implements AnalysisRepository {
   }
 
   /**
-   * Applies the changes to the draft as this instance's last apply left it, or to the stored draft
-   * when it has made none since its last whole load or save. Only the books whose content the
-   * changes alter are rewritten, so an edit to a payload rewrites every book linking it.
+   * Applies the changes to the draft as this instance last applied changes to it or answered a
+   * lookup from it, or to the stored draft when it has done neither since its last whole load or
+   * save. Only the books whose content the changes alter are rewritten, so an edit to a payload
+   * rewrites every book linking it.
    *
    * @throws {Error} If an id appears more than once in one record kind's changes, or the scope's
    *   record names another source project; nothing is written.
@@ -265,13 +270,36 @@ export class DraftRepository implements AnalysisRepository {
    *   is left as it was.
    */
   async apply(changes: ChangeSet): Promise<ApplyResult> {
-    this.current ??= (await this.exportAll()).draft;
-    const { draft, inverse } = applyChangeSet(this.current, changes);
+    const { draft: base, index } = await this.keptDraft();
+    const copied = jsonCopy(changes);
+    const { draft, inverse } = applyChangeSet(base, copied);
     await this.writeDraft(draft, undefined, { refuseUnreadable: true });
-    this.current = draft;
+    index.apply(copied);
+    this.current = { draft, index };
     return { inverse };
   }
 
+  protected async indexed(): Promise<AnalysisIndex> {
+    return (await this.keptDraft()).index;
+  }
+
+  protected keptIndex(): IndexedAnalysis | undefined {
+    return this.current && { analysis: this.current.draft.analysis, index: this.current.index };
+  }
+
+  /**
+   * The draft this instance keeps, loaded from storage first when it keeps none.
+   *
+   * @throws Whatever {@link exportAll} throws.
+   */
+  private async keptDraft(): Promise<{ draft: DraftProject; index: AnalysisIndex }> {
+    if (!this.current) {
+      const { draft } = await this.exportAll();
+      this.current = { draft, index: new AnalysisIndex(draft.analysis) };
+    }
+    return this.current;
+  }
+
   /**
    * Saves `draft` as {@link replaceAll} describes.
    *
diff --git a/src/services/indexedRepository.ts b/src/services/indexedRepository.ts
new file mode 100644
index 000000000..d8b774446
--- /dev/null
+++ b/src/services/indexedRepository.ts
@@ -0,0 +1,95 @@
+import type {
+  AssignmentStatus,
+  PhraseAnalysis,
+  SegmentAnalysis,
+  SegmentAnalysisLink,
+  TextAnalysis,
+  TokenAnalysis,
+} from 'interlinearizer';
+import type {
+  AnalysisLinks,
+  AnalysisRepository,
+  IndexDifference,
+} from '../types/analysis-repository';
+import { jsonCopy } from '../utils/json-copy';
+import type { AnalysisIndex } from './analysisIndex';
+
+/** An index, with the analysis whose records it is kept over. */
+export type IndexedAnalysis = {
+  analysis: TextAnalysis;
+  index: AnalysisIndex;
+};
+
+/** The lookups of a repository that answers them from an {@link AnalysisIndex} over its records. */
+export abstract class IndexedRepository implements Pick<
+  AnalysisRepository,
+  | 'getTokenAnalyses'
+  | 'getPhraseAnalyses'
+  | 'getSegmentAnalyses'
+  | 'findLinksByToken'
+  | 'findLinksBySegment'
+  | 'findLinksToAnalyses'
+  | 'findLinksInBooks'
+  | 'findTokenAnalysesByForm'
+  | 'findPhraseAnalysesByForm'
+  | 'checkIndexes'
+> {
+  getTokenAnalyses(ids: string[]): Promise<TokenAnalysis[]> {
+    return this.query((index) => index.getTokenAnalyses(ids));
+  }
+
+  getPhraseAnalyses(ids: string[]): Promise<PhraseAnalysis[]> {
+    return this.query((index) => index.getPhraseAnalyses(ids));
+  }
+
+  getSegmentAnalyses(ids: string[]): Promise<SegmentAnalysis[]> {
+    return this.query((index) => index.getSegmentAnalyses(ids));
+  }
+
+  findLinksByToken(
+    tokenRefs: string[],
+  ): Promise<Pick<AnalysisLinks, 'tokenAnalysisLinks' | 'phraseAnalysisLinks'>> {
+    return this.query((index) => index.findLinksByToken(tokenRefs));
+  }
+
+  findLinksBySegment(segmentIds: string[]): Promise<SegmentAnalysisLink[]> {
+    return this.query((index) => index.findLinksBySegment(segmentIds));
+  }
+
+  findLinksToAnalyses(analysisIds: string[]): Promise<AnalysisLinks> {
+    return this.query((index) => index.findLinksToAnalyses(analysisIds));
+  }
+
+  findLinksInBooks(bookCodes: string[], statuses?: AssignmentStatus[]): Promise<AnalysisLinks> {
+    return this.query((index) => index.findLinksInBooks(bookCodes, statuses));
+  }
+
+  findTokenAnalysesByForm(normalizedForms: string[]): Promise<TokenAnalysis[]> {
+    return this.query((index) => index.findTokenAnalysesByForm(normalizedForms));
+  }
+
+  findPhraseAnalysesByForm(normalizedForms: string[]): Promise<PhraseAnalysis[]> {
+    return this.query((index) => index.findPhraseAnalysesByForm(normalizedForms));
+  }
+
+  /** Reports nothing while no index is kept. */
+  async checkIndexes(): Promise<IndexDifference[]> {
+    const kept = this.keptIndex();
+    return kept ? kept.index.differencesFrom(kept.analysis) : [];
+  }
+
+  /** Answers `read` from the kept index, with copies of the records it finds. */
+  private async query<T>(read: (index: AnalysisIndex) => T): Promise<T> {
+    return jsonCopy(read(await this.indexed()));
+  }
+
+  /**
+   * The kept index, built over the stored records first when none is kept.
+   *
+   * @throws Whatever loading the stored records throws.
+   */
+  protected abstract indexed(): Promise<AnalysisIndex>;
+
+  /** The kept index and the analysis it is kept over, or `undefined` when none is kept. */
+  protected abstract keptIndex(): IndexedAnalysis | undefined;
+}
diff --git a/src/services/projectStorage.ts b/src/services/projectStorage.ts
index e6eefe7a3..185bf6ed0 100644
--- a/src/services/projectStorage.ts
+++ b/src/services/projectStorage.ts
@@ -1133,6 +1133,21 @@ export function openDraftRepository(
     replaceAll: (draft, options) => counted((repository) => repository.replaceAll(draft, options)),
     markClean: () => queued((repository) => repository.markClean()),
     apply: (changes) => counted((repository) => repository.apply(changes)),
+    getTokenAnalyses: (ids) => queued((repository) => repository.getTokenAnalyses(ids)),
+    getPhraseAnalyses: (ids) => queued((repository) => repository.getPhraseAnalyses(ids)),
+    getSegmentAnalyses: (ids) => queued((repository) => repository.getSegmentAnalyses(ids)),
+    findLinksByToken: (tokenRefs) => queued((repository) => repository.findLinksByToken(tokenRefs)),
+    findLinksBySegment: (segmentIds) =>
+      queued((repository) => repository.findLinksBySegment(segmentIds)),
+    findLinksToAnalyses: (analysisIds) =>
+      queued((repository) => repository.findLinksToAnalyses(analysisIds)),
+    findLinksInBooks: (bookCodes, statuses) =>
+      queued((repository) => repository.findLinksInBooks(bookCodes, statuses)),
+    findTokenAnalysesByForm: (normalizedForms) =>
+      queued((repository) => repository.findTokenAnalysesByForm(normalizedForms)),
+    findPhraseAnalysesByForm: (normalizedForms) =>
+      queued((repository) => repository.findPhraseAnalysesByForm(normalizedForms)),
+    checkIndexes: () => queued((repository) => repository.checkIndexes()),
   };
 }
 
diff --git a/src/services/pt9ImportRepository.ts b/src/services/pt9ImportRepository.ts
index e8c7d4c4f..5a47ccddc 100644
--- a/src/services/pt9ImportRepository.ts
+++ b/src/services/pt9ImportRepository.ts
@@ -1,4 +1,4 @@
-import type { InterlinearProject } from 'interlinearizer';
+import type { DraftProject, InterlinearProject } from 'interlinearizer';
 import type {
   AnalysisRepository,
   ApplyResult,
@@ -7,18 +7,23 @@ import type {
 } from '../types/analysis-repository';
 import { CURRENT_MODEL_VERSION } from '../types/model-version';
 import { ReadOnlyAnalysisError } from '../types/read-only-analysis-error';
+import { AnalysisIndex } from './analysisIndex';
+import { IndexedRepository, type IndexedAnalysis } from './indexedRepository';
 
 /**
  * A Paratext 9 import's analysis, read in a draft's shape. Only a sync replaces an import's
  * content, so every write is refused.
  */
-export class Pt9ImportRepository implements AnalysisRepository {
+export class Pt9ImportRepository extends IndexedRepository implements AnalysisRepository {
   readonly capabilities: RepositoryCapabilities = { readOnly: true };
 
   private readonly interlinearProjectId: string;
 
   private readonly readProject: () => Promise<InterlinearProject | undefined>;
 
+  /** The import as a lookup last read it, with the index over its records; dropped by every load. */
+  private loaded: IndexedAnalysis | undefined;
+
   /**
    * @param interlinearProjectId - Id of the project to read, which must be a Paratext 9 import.
    * @param readProject - Reads the project stored under that id afresh, resolving `undefined` when
@@ -28,6 +33,7 @@ export class Pt9ImportRepository implements AnalysisRepository {
     interlinearProjectId: string,
     readProject: () => Promise<InterlinearProject | undefined>,
   ) {
+    super();
     this.interlinearProjectId = interlinearProjectId;
     this.readProject = readProject;
   }
@@ -41,25 +47,8 @@ export class Pt9ImportRepository implements AnalysisRepository {
    * @throws Whatever reading the project throws.
    */
   async exportAll(): Promise<DraftExport> {
-    const project = await this.readProject();
-    if (!project?.pt9Import) {
-      throw new Error(
-        `Interlinearizer: no Paratext 9 import is stored as project ${this.interlinearProjectId}`,
-      );
-    }
-    const { sourceProjectId, analysisLanguages, targetProjectId, analysis, segmentation } = project;
-    return {
-      draft: {
-        sourceProjectId,
-        modelVersion: CURRENT_MODEL_VERSION,
-        analysisLanguages,
-        ...(targetProjectId !== undefined && { targetProjectId }),
-        analysis,
-        dirty: false,
-        ...(segmentation !== undefined && { segmentation }),
-      },
-      unreadableBooks: [],
-    };
+    this.loaded = undefined;
+    return { draft: await this.readImport(), unreadableBooks: [] };
   }
 
   /**
@@ -86,6 +75,42 @@ export class Pt9ImportRepository implements AnalysisRepository {
     throw this.readOnlyError();
   }
 
+  protected async indexed(): Promise<AnalysisIndex> {
+    if (!this.loaded) {
+      const { analysis } = await this.readImport();
+      this.loaded = { analysis, index: new AnalysisIndex(analysis) };
+    }
+    return this.loaded.index;
+  }
+
+  protected keptIndex(): IndexedAnalysis | undefined {
+    return this.loaded;
+  }
+
+  /**
+   * Reads the import as {@link exportAll} describes.
+   *
+   * @throws Whatever {@link exportAll} throws.
+   */
+  private async readImport(): Promise<DraftProject> {
+    const project = await this.readProject();
+    if (!project?.pt9Import) {
+      throw new Error(
+        `Interlinearizer: no Paratext 9 import is stored as project ${this.interlinearProjectId}`,
+      );
+    }
+    const { sourceProjectId, analysisLanguages, targetProjectId, analysis, segmentation } = project;
+    return {
+      sourceProjectId,
+      modelVersion: CURRENT_MODEL_VERSION,
+      analysisLanguages,
+      ...(targetProjectId !== undefined && { targetProjectId }),
+      analysis,
+      dirty: false,
+      ...(segmentation !== undefined && { segmentation }),
+    };
+  }
+
   private readOnlyError(): ReadOnlyAnalysisError {
     return new ReadOnlyAnalysisError(
       `Interlinearizer: Paratext 9 import ${this.interlinearProjectId} is read-only`,
diff --git a/src/services/recordTable.ts b/src/services/recordTable.ts
new file mode 100644
index 000000000..0878bec01
--- /dev/null
+++ b/src/services/recordTable.ts
@@ -0,0 +1,122 @@
+import type { IndexDifference, RecordChanges } from '../types/analysis-repository';
+
+/** The keys a derived index files a record under. */
+export type KeysOf<T> = (record: T) => readonly string[];
+
+/** Ids filed under keys. */
+type IdsByKey = Map<string, Set<string>>;
+
+function fileId(index: IdsByKey, key: string, id: string): void {
+  const ids = index.get(key);
+  if (ids) ids.add(id);
+  else index.set(key, new Set([id]));
+}
+
+function unfileId(index: IdsByKey, key: string, id: string): void {
+  const ids = index.get(key);
+  /* v8 ignore next -- a record's keys were filed when it was put */
+  if (!ids) return;
+  ids.delete(id);
+  if (ids.size === 0) index.delete(key);
+}
+
+/** The ids in `a` that `b` lacks. */
+function idsLacking(a: ReadonlySet<string> | undefined, b: ReadonlySet<string> | undefined) {
+  return [...(a ?? [])].filter((id) => !b?.has(id));
+}
+
+/** One record kind's records by id, with the derived indexes kept over them. */
+export class RecordTable<T extends { id: string }, Index extends string> {
+  private readonly kind: string;
+
+  private readonly keyers: Record<Index, KeysOf<T>>;
+
+  private readonly records = new Map<string, T>();
+
+  private readonly indexes = new Map<Index, IdsByKey>();
+
+  constructor(kind: string, keyers: Record<Index, KeysOf<T>>, records: readonly T[]) {
+    this.kind = kind;
+    this.keyers = keyers;
+    this.indexNames().forEach((index) => this.indexes.set(index, new Map()));
+    records.forEach((record) => this.put(record));
+  }
+
+  /** The records stored under `ids`, each once. */
+  get(ids: readonly string[]): T[] {
+    return [...new Set(ids)].flatMap((id) => this.records.get(id) ?? []);
+  }
+
+  /** The records `index` files under any of `keys`, each once. */
+  find(index: Index, keys: readonly string[]): T[] {
+    const filed = this.filed(index);
+    const ids = new Set(keys.flatMap((key) => [...(filed.get(key) ?? [])]));
+    return this.get([...ids]);
+  }
+
+  /** Applies one record kind's puts and deletes; absent changes apply nothing. */
+  apply(changes: RecordChanges<T> | undefined): void {
+    changes?.puts.forEach((record) => this.put(record));
+    changes?.deletes.forEach((id) => this.remove(id));
+  }
+
+  /**
+   * Where this table differs from `rebuilt`, a table of the same kind built afresh. A record whose
+   * kept copy differs from the rebuilt one is both missing and extra.
+   */
+  differencesFrom(rebuilt: RecordTable<T, Index>): IndexDifference[] {
+    const ids = new Set([...this.records.keys(), ...rebuilt.records.keys()]);
+    const recordDifferences = [...ids].flatMap((id): IndexDifference[] => {
+      const kept = this.records.get(id);
+      const stored = rebuilt.records.get(id);
+      if (JSON.stringify(kept) === JSON.stringify(stored)) return [];
+      return [{ index: this.kind, key: id, missing: stored ? [id] : [], extra: kept ? [id] : [] }];
+    });
+    const indexDifferences = this.indexNames().flatMap((index) => {
+      const kept = this.filed(index);
+      const fresh = rebuilt.filed(index);
+      const keys = new Set([...kept.keys(), ...fresh.keys()]);
+      return [...keys].flatMap((key): IndexDifference[] => {
+        const missing = idsLacking(fresh.get(key), kept.get(key));
+        const extra = idsLacking(kept.get(key), fresh.get(key));
+        if (missing.length === 0 && extra.length === 0) return [];
+        return [{ index: `${this.kind} by ${index}`, key, missing, extra }];
+      });
+    });
+    return [...recordDifferences, ...indexDifferences];
+  }
+
+  private indexNames(): Index[] {
+    // Object.keys widens to string[]; the keys are exactly the keyers' index names.
+    return Object.keys(this.keyers).filter((name): name is Index => name in this.keyers);
+  }
+
+  private filed(index: Index): IdsByKey {
+    const filed = this.indexes.get(index);
+    /* v8 ignore next -- the constructor gives every index its map */
+    if (!filed) throw new Error(`Interlinearizer: ${this.kind} has no index by ${index}`);
+    return filed;
+  }
+
+  /** The keys `index` files `record` under, each once. */
+  private keysOf(index: Index, record: T): Set<string> {
+    return new Set(this.keyers[index](record));
+  }
+
+  private put(record: T): void {
+    this.remove(record.id);
+    this.records.set(record.id, record);
+    this.indexNames().forEach((index) =>
+      this.keysOf(index, record).forEach((key) => fileId(this.filed(index), key, record.id)),
+    );
+  }
+
+  private remove(id: string): void {
+    const record = this.records.get(id);
+    if (!record) return;
+    this.records.delete(id);
+    this.indexNames().forEach((index) =>
+      this.keysOf(index, record).forEach((key) => unfileId(this.filed(index), key, id)),
+    );
+  }
+}
diff --git a/src/types/analysis-repository.ts b/src/types/analysis-repository.ts
index e19571e19..355dcf100 100644
--- a/src/types/analysis-repository.ts
+++ b/src/types/analysis-repository.ts
@@ -1,4 +1,12 @@
-import type { DraftProject, TextAnalysis } from 'interlinearizer';
+import type {
+  AssignmentStatus,
+  DraftProject,
+  PhraseAnalysis,
+  SegmentAnalysis,
+  SegmentAnalysisLink,
+  TextAnalysis,
+  TokenAnalysis,
+} from 'interlinearizer';
 
 /** Text records by key. */
 export interface KeyValueStorage {
@@ -86,12 +94,29 @@ export type ApplyResult = {
   inverse: ChangeSet;
 };
 
+/** Links of every kind, one list per kind. */
+export type AnalysisLinks = Pick<
+  TextAnalysis,
+  'tokenAnalysisLinks' | 'phraseAnalysisLinks' | 'segmentAnalysisLinks'
+>;
+
+/** Where a derived index a repository keeps differs from one rebuilt from its records. */
+export type IndexDifference = {
+  index: string;
+  /** The key whose entries differ. */
+  key: string;
+  /** Ids the rebuilt index files under the key that the kept one lacks. */
+  missing: string[];
+  /** Ids the kept index files under the key that the rebuilt one lacks. */
+  extra: string[];
+};
+
 /**
  * Reads and writes one source project's draft, or, when read-only, reads analysis in a draft's
  * shape. Every call is async and takes and returns only JSON-plain values, so an implementation may
  * sit behind a network boundary or another language. Once a call settles, the caller may change a
- * draft it passed in or got back without changing what is stored. Lists of records come back in no
- * promised order.
+ * draft or records it passed in or got back without changing what is stored. Lists of records come
+ * back in no promised order, and a lookup by several keys returns each record once.
  *
  * Calls for one draft must not overlap, whether on one repository or several. After one repository
  * saves a draft, any other that had already loaded or saved it must load it again before its next
@@ -168,4 +193,42 @@ export interface AnalysisRepository {
    *   unchanged, though storage may hold some of the changes until a later save.
    */
   apply(changes: ChangeSet): Promise<ApplyResult>;
+
+  /** The token analyses stored under `ids`; an id with none stored under it is skipped. */
+  getTokenAnalyses(ids: string[]): Promise<TokenAnalysis[]>;
+
+  /** The phrase analyses stored under `ids`; an id with none stored under it is skipped. */
+  getPhraseAnalyses(ids: string[]): Promise<PhraseAnalysis[]>;
+
+  /** The segment analyses stored under `ids`; an id with none stored under it is skipped. */
+  getSegmentAnalyses(ids: string[]): Promise<SegmentAnalysis[]>;
+
+  /** The token links on the tokens `tokenRefs` names, and the phrase links touching any of them. */
+  findLinksByToken(
+    tokenRefs: string[],
+  ): Promise<Pick<AnalysisLinks, 'tokenAnalysisLinks' | 'phraseAnalysisLinks'>>;
+
+  /** The segment links on the segments `segmentIds` names. */
+  findLinksBySegment(segmentIds: string[]): Promise<SegmentAnalysisLink[]>;
+
+  /** The links of every kind to the analyses `analysisIds` names. */
+  findLinksToAnalyses(analysisIds: string[]): Promise<AnalysisLinks>;
+
+  /**
+   * The links of every kind into the books `bookCodes` names, of any status when `statuses` is
+   * absent.
+   */
+  findLinksInBooks(bookCodes: string[], statuses?: AssignmentStatus[]): Promise<AnalysisLinks>;
+
+  /** The token analyses whose surface text normalizes to one of `normalizedForms`. */
+  findTokenAnalysesByForm(normalizedForms: string[]): Promise<TokenAnalysis[]>;
+
+  /** The phrase analyses whose surface text normalizes to one of `normalizedForms`. */
+  findPhraseAnalysesByForm(normalizedForms: string[]): Promise<PhraseAnalysis[]>;
+
+  /**
+   * Rebuilds the derived indexes the repository keeps from its records and reports where the kept
+   * ones differ, for debugging. A repository keeping none reports nothing.
+   */
+  checkIndexes(): Promise<IndexDifference[]>;
 }
diff --git a/src/types/interlinearizer.d.ts b/src/types/interlinearizer.d.ts
index 06ab18d47..b7be3e07c 100644
--- a/src/types/interlinearizer.d.ts
+++ b/src/types/interlinearizer.d.ts
@@ -381,6 +381,15 @@ declare module 'papi-shared-types' {
      */
     'interlinearizer.redoEdit': (sessionId: string) => Promise<string | undefined>;
 
+    /**
+     * Rebuilds a session's derived indexes from its records and reports where the kept ones differ,
+     * for debugging.
+     *
+     * @returns A JSON string of `[{ index, key, missing, extra }]`, empty when none differ.
+     * @throws If the session is not open, or its records cannot be read (logged before rethrowing).
+     */
+    'interlinearizer.checkIndexes': (sessionId: string) => Promise<string>;
+
     /**
      * Turns the extension host's timing entries on or off, discarding any it holds. Off until
      * turned on.
diff --git a/src/utils/change-set.ts b/src/utils/change-set.ts
index ecc046174..9d3ee463b 100644
--- a/src/utils/change-set.ts
+++ b/src/utils/change-set.ts
@@ -7,11 +7,6 @@ export type AppliedChanges = {
   inverse: ChangeSet;
 };
 
-/** A copy of a JSON-plain value that shares nothing with it. */
-function copyOf<T>(value: T): T {
-  return JSON.parse(JSON.stringify(value));
-}
-
 /** The draft's record, without its analysis. */
 // eslint-disable-next-line @typescript-eslint/no-unused-vars -- named only to leave it out
 export function scopeRecordOf({ analysis, ...scope }: DraftProject): ScopeRecord {
@@ -41,7 +36,7 @@ function applyRecordChanges<T extends { id: string }>(
 
   const stored = new Map(records.map((record) => [record.id, record]));
   const deleted = new Set(changes.deletes);
-  const puts = new Map(changes.puts.map((record) => [record.id, copyOf(record)]));
+  const puts = new Map(changes.puts.map((record) => [record.id, record]));
   const inverse: RecordChanges<T> = { puts: [], deletes: [] };
   changes.puts.forEach(({ id }) => {
     const prior = stored.get(id);
@@ -68,8 +63,8 @@ function applyRecordChanges<T extends { id: string }>(
 }
 
 /**
- * Applies `changes` to `draft`, leaving `draft` as it was. The result holds copies of the records
- * the changes put, and shares everything else with `draft`, the records the inverse restores
+ * Applies `changes` to `draft`, leaving `draft` as it was. The result shares the records the
+ * changes put with `changes`, and everything else with `draft`, the records the inverse restores
  * included.
  *
  * @throws {Error} If an id appears more than once in one record kind's changes, or the scope's
@@ -125,7 +120,7 @@ export function applyChangeSet(draft: DraftProject, changes: ChangeSet): Applied
   };
   return {
     draft: {
-      ...(changes.scope ? copyOf(changes.scope) : scopeRecordOf(draft)),
+      ...(changes.scope ?? scopeRecordOf(draft)),
       analysis: {
         segmentAnalyses: segmentAnalyses.records,
         segmentAnalysisLinks: segmentAnalysisLinks.records,
diff --git a/src/utils/json-copy.ts b/src/utils/json-copy.ts
new file mode 100644
index 000000000..eb6d43879
--- /dev/null
+++ b/src/utils/json-copy.ts
@@ -0,0 +1,4 @@
+/** A deep copy of a JSON-plain value, sharing nothing with it. */
+export function jsonCopy<T>(value: T): T {
+  return JSON.parse(JSON.stringify(value));
+}

From 72432035d08a31655143b97207fe779cc3d0afce Mon Sep 17 00:00:00 2001
From: Alex Rawlings <alex.rawlings@wycliffe.ca>
Date: Thu, 22 Oct 2026 10:49:50 -0600
Subject: [PATCH 06/22] Add token commands with parity tests (#443)

---
 AGENTS.md                                     |   2 +
 .../analysis-repository-conformance.ts        |  21 +
 src/__tests__/main.test.ts                    |  58 ++
 .../services/analysisSessions.test.ts         |  96 +++
 .../services/commands/approvalRule.test.ts    |  92 +++
 .../services/commands/changeBuffer.test.ts    | 192 ++++++
 src/__tests__/services/commands/parity.ts     |  75 +++
 .../commands/tokenCommands.parity.test.ts     | 548 ++++++++++++++++++
 .../services/commands/tokenCommands.test.ts   |  92 +++
 .../services/indexedRepository.test.ts        |  32 +-
 src/__tests__/services/projectStorage.test.ts |   5 +
 src/__tests__/utils/change-set.test.ts        |  18 +-
 .../utils/token-analysis-content.test.ts      |  59 ++
 src/main.ts                                   | 144 ++++-
 src/services/analysisSessions.ts              |  32 +
 src/services/commands/approvalRule.ts         |  69 +++
 src/services/commands/changeBuffer.ts         | 214 +++++++
 src/services/commands/tokenCommands.ts        | 291 ++++++++++
 src/services/draftRepository.ts               |  26 +-
 src/services/indexedRepository.ts             |  29 +-
 src/services/projectStorage.ts                |   1 +
 src/services/pt9ImportRepository.ts           |  15 +-
 src/store/analysisSlice.ts                    |  41 +-
 src/types/analysis-repository.ts              |   7 +
 src/types/interlinearizer.d.ts                |  28 +
 src/utils/change-set.ts                       |   5 +
 src/utils/token-analysis-content.ts           |  42 ++
 27 files changed, 2147 insertions(+), 87 deletions(-)
 create mode 100644 src/__tests__/services/commands/approvalRule.test.ts
 create mode 100644 src/__tests__/services/commands/changeBuffer.test.ts
 create mode 100644 src/__tests__/services/commands/parity.ts
 create mode 100644 src/__tests__/services/commands/tokenCommands.parity.test.ts
 create mode 100644 src/__tests__/services/commands/tokenCommands.test.ts
 create mode 100644 src/__tests__/utils/token-analysis-content.test.ts
 create mode 100644 src/services/commands/approvalRule.ts
 create mode 100644 src/services/commands/changeBuffer.ts
 create mode 100644 src/services/commands/tokenCommands.ts
 create mode 100644 src/utils/token-analysis-content.ts

diff --git a/AGENTS.md b/AGENTS.md
index 435e6c976..9cb9c55dd 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -87,6 +87,8 @@ Saved projects are listed through [ProjectSummaries](src/services/projectSummari
 
 [AnalysisSessions](src/services/analysisSessions.ts) keeps the host's sessions, behind the `openSession`, `closeSession` and `setAnalysisLanguage` commands. A session is a handle on one source project's draft, paired with the interlinear project it saves to, or on a Paratext 9 import alone, read-only. A source has at most one session: opening another closes it. Each session runs its commands one at a time, through `run`, or `runEdit` for a command that changes stored analysis, which a read-only session refuses. An edit reaches the repository as a `ChangeSet` of whole-record puts and deletes, applied through the session's [EditHistory](src/services/editHistory.ts) so that undo can revert it; boundary changes ride in the change set's scope record. The WebView doesn't use sessions yet.
 
+Host commands live in [src/services/commands/](src/services/commands/), one module per family. A command stages its changes in a [ChangeBuffer](src/services/commands/changeBuffer.ts), whose reads answer as the repository will once those changes apply, and `AnalysisSessions.edit` applies what it staged as one undo step after the approval rule passes. Each command copies the reducer it replaces, step for step, and its parity tests run one input through both with [runParity](src/__tests__/services/commands/parity.ts); a reducer change in Phase 3 updates its command and parity tests in the same PR.
+
 ### 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/src/__tests__/analysis-repository-conformance.ts b/src/__tests__/analysis-repository-conformance.ts
index b9c6682a8..acf66c79c 100644
--- a/src/__tests__/analysis-repository-conformance.ts
+++ b/src/__tests__/analysis-repository-conformance.ts
@@ -1126,6 +1126,27 @@ export function describeAnalysisRepositoryConformance(
         return store.open(SOURCE);
       }
 
+      it("reads the draft's own record", async () => {
+        const repository = await overFullDraft();
+
+        await expect(repository.getScope()).resolves.toStrictEqual(scopeRecordOf(fullDraft()));
+      });
+
+      it("reads the record of a draft never saved as an empty draft's", async () => {
+        await expect((await store.open(SOURCE)).getScope()).resolves.toStrictEqual(
+          scopeRecordOf(emptyDraft(SOURCE)),
+        );
+      });
+
+      it('reads the record the applied changes leave', async () => {
+        const repository = await overFullDraft();
+        const scope = { ...scopeRecordOf(fullDraft()), dirty: false, analysisLanguages: ['de'] };
+
+        await repository.apply({ intent: 'rescope', scope });
+
+        await expect(repository.getScope()).resolves.toStrictEqual(scope);
+      });
+
       it('gets each payload kind by id, once per id, skipping ids with nothing stored', async () => {
         const repository = await overFullDraft();
 
diff --git a/src/__tests__/main.test.ts b/src/__tests__/main.test.ts
index b24169bbe..7973e5b8d 100644
--- a/src/__tests__/main.test.ts
+++ b/src/__tests__/main.test.ts
@@ -12,6 +12,7 @@ import * as projectStorage from '../services/projectStorage';
 import * as pt9ImportService from '../services/pt9ImportService';
 import { type AnalysisRepository, UnreadableBooksError } from '../types/analysis-repository';
 import { emptyDraft } from '../types/empty-factories';
+import { scopeRecordOf } from '../utils/change-set';
 import { toProjectSummary } from '../types/interlinear-project-summary';
 import { createTestActivationContext, makeStubProject } from './test-helpers';
 
@@ -401,6 +402,8 @@ describe('main', () => {
           'interlinearizer.undoEdit',
           'interlinearizer.redoEdit',
           'interlinearizer.checkIndexes',
+          'interlinearizer.writeGloss',
+          'interlinearizer.approveAnalysisForToken',
           'interlinearizer.openSelectProjectModal',
           'interlinearizer.openNewProjectModal',
           'interlinearizer.openProjectInfoModal',
@@ -1848,6 +1851,7 @@ describe('main', () => {
         checkIndexes: async () => [
           { index: 'tokenAnalyses', key: 'ta-1', missing: ['ta-1'], extra: [] },
         ],
+        getScope: async () => scopeRecordOf(draft),
       };
     }
 
@@ -1877,6 +1881,22 @@ describe('main', () => {
         checkIndexes: handler<(sessionId: string) => Promise<string>>(
           'interlinearizer.checkIndexes',
         ),
+        writeGloss: handler<
+          (
+            sessionId: string,
+            tokenRef: string,
+            surfaceText: string,
+            value: string,
+          ) => Promise<string>
+        >('interlinearizer.writeGloss'),
+        approveAnalysisForToken: handler<
+          (
+            sessionId: string,
+            tokenRef: string,
+            surfaceText: string,
+            analysisId: string,
+          ) => Promise<string>
+        >('interlinearizer.approveAnalysisForToken'),
       };
     }
 
@@ -2060,6 +2080,44 @@ describe('main', () => {
       );
     });
 
+    it("writes a token's gloss in the session's language, replying with the changes", async () => {
+      const { openSession, setAnalysisLanguage, writeGloss } = await activateSessionCommands();
+      const { sessionId } = JSON.parse(await openSession('src-project'));
+      await setAnalysisLanguage(sessionId, 'fr');
+
+      const changes = JSON.parse(await writeGloss(sessionId, 'GEN 1:1:0', 'In', 'au'));
+
+      expect(changes).toMatchObject({
+        intent: 'writeGloss',
+        tokenAnalyses: { puts: [{ surfaceText: 'In', gloss: { fr: 'au' } }], deletes: [] },
+        tokenAnalysisLinks: {
+          puts: [{ status: 'approved', token: { tokenRef: 'GEN 1:1:0', surfaceText: 'In' } }],
+          deletes: [],
+        },
+      });
+    });
+
+    it('logs the error and rethrows when an edit fails', async () => {
+      const { writeGloss } = await activateSessionCommands();
+
+      await expect(writeGloss('not-a-session', 'GEN 1:1:0', 'In', 'at')).rejects.toThrow(
+        'no session not-a-session is open',
+      );
+      expect(__mockLogger.error).toHaveBeenCalledWith(
+        'Interlinearizer: failed to writeGloss in session not-a-session',
+        expect.any(Error),
+      );
+    });
+
+    it('approves an analysis for a token, replying with the changes', async () => {
+      const { openSession, approveAnalysisForToken } = await activateSessionCommands();
+      const { sessionId } = JSON.parse(await openSession('src-project'));
+
+      await expect(
+        approveAnalysisForToken(sessionId, 'GEN 1:1:0', 'In', 'ta-unknown').then(JSON.parse),
+      ).resolves.toStrictEqual({ intent: 'approveAnalysisForToken' });
+    });
+
     it('closes every session on deactivation', async () => {
       const { openSession } = await activateSessionCommands();
       await openSession('src-project');
diff --git a/src/__tests__/services/analysisSessions.test.ts b/src/__tests__/services/analysisSessions.test.ts
index 22a981587..61c367e53 100644
--- a/src/__tests__/services/analysisSessions.test.ts
+++ b/src/__tests__/services/analysisSessions.test.ts
@@ -6,6 +6,7 @@ import {
   type SessionHost,
   UNDETERMINED_LANGUAGE,
 } from '../../services/analysisSessions';
+import { ApprovalRuleError } from '../../services/commands/approvalRule';
 import { DraftRepository } from '../../services/draftRepository';
 import { Pt9ImportRepository } from '../../services/pt9ImportRepository';
 import { draftKey } from '../../services/storageKeys';
@@ -451,6 +452,101 @@ describe('AnalysisSessions', () => {
     });
   });
 
+  describe('edit', () => {
+    const payload = (id: string) => ({ id, ...FIXTURE_STAMPS, surfaceText: id });
+    const approvedLink = (id: string) => ({
+      id,
+      analysisId: 'a',
+      ...FIXTURE_STAMPS,
+      status: 'approved' as const,
+      token: { tokenRef: 'GEN 1:1:0', surfaceText: 'a' },
+    });
+
+    /** The source project's draft as stored. */
+    const stored = async (storage: ReturnType<typeof makeSessions>['storage']) =>
+      (await new DraftRepository(storage, SOURCE, silentLogger()).exportAll()).draft;
+
+    it('applies what the command stages as one undo step, marking the draft dirty', async () => {
+      const { sessions, storage } = makeSessions();
+      const { sessionId } = await sessions.open(SOURCE);
+
+      const changes = await sessions.edit(sessionId, 'add', async (buffer) => {
+        buffer.create('tokenAnalyses', payload('a'));
+        buffer.create('tokenAnalyses', payload('b'));
+      });
+
+      expect(changes).toMatchObject({ intent: 'add', scope: { dirty: true } });
+      await expect(stored(storage)).resolves.toMatchObject({
+        dirty: true,
+        analysis: { tokenAnalyses: [payload('a'), payload('b')] },
+      });
+      await sessions.undo(sessionId);
+      await expect(stored(storage)).resolves.toMatchObject({
+        dirty: false,
+        analysis: { tokenAnalyses: [] },
+      });
+    });
+
+    it('leaves the scope alone on a draft already dirty', async () => {
+      const { sessions, saveDraft } = makeSessions();
+      await saveDraft({ ...emptyDraft(SOURCE), dirty: true });
+      const { sessionId } = await sessions.open(SOURCE);
+
+      const changes = await sessions.edit(sessionId, 'add', async (buffer) => {
+        buffer.create('tokenAnalyses', payload('a'));
+      });
+
+      expect(changes).not.toHaveProperty('scope');
+    });
+
+    it('applies nothing, and records no undo step, for a command staging nothing', async () => {
+      const { sessions, storage } = makeSessions();
+      const { sessionId } = await sessions.open(SOURCE);
+
+      await expect(sessions.edit(sessionId, 'nothing', async () => {})).resolves.toStrictEqual({
+        intent: 'nothing',
+      });
+
+      await expect(sessions.undo(sessionId)).resolves.toBeUndefined();
+      await expect(stored(storage)).resolves.toMatchObject({ dirty: false });
+    });
+
+    it('gives the command the session it runs on', async () => {
+      const { sessions } = makeSessions();
+      const { sessionId } = await sessions.open(SOURCE);
+      await sessions.setAnalysisLanguage(sessionId, 'fr');
+
+      await sessions.edit(sessionId, 'read', async (_buffer, session) => {
+        expect(session.analysisLanguage).toBe('fr');
+      });
+    });
+
+    it('refuses changes that would approve a second analysis for a token, applying nothing', async () => {
+      const { sessions, storage } = makeSessions();
+      const { sessionId } = await sessions.open(SOURCE);
+
+      await expect(
+        sessions.edit(sessionId, 'approveTwice', async (buffer) => {
+          buffer.create('tokenAnalysisLinks', approvedLink('l-1'));
+          buffer.create('tokenAnalysisLinks', approvedLink('l-2'));
+        }),
+      ).rejects.toThrow(ApprovalRuleError);
+
+      await expect(stored(storage)).resolves.toMatchObject({
+        analysis: { tokenAnalysisLinks: [] },
+      });
+    });
+
+    it("refuses an edit on a Paratext 9 import's session without running it", async () => {
+      const { sessions } = makeSessions([makeImport()]);
+      const { sessionId } = await sessions.open(SOURCE, 'import-id');
+      const command = jest.fn(async () => {});
+
+      await expect(sessions.edit(sessionId, 'add', command)).rejects.toThrow(ReadOnlyAnalysisError);
+      expect(command).not.toHaveBeenCalled();
+    });
+  });
+
   describe('setAnalysisLanguage', () => {
     it('sets the language the commands sent after it read', async () => {
       const { sessions } = makeSessions();
diff --git a/src/__tests__/services/commands/approvalRule.test.ts b/src/__tests__/services/commands/approvalRule.test.ts
new file mode 100644
index 000000000..3c37315dd
--- /dev/null
+++ b/src/__tests__/services/commands/approvalRule.test.ts
@@ -0,0 +1,92 @@
+/// <reference types="jest" />
+
+import type { SegmentAnalysisLink, TextAnalysis, TokenAnalysisLink } from 'interlinearizer';
+import { ApprovalRuleError, assertApprovalRule } from '../../../services/commands/approvalRule';
+import { ChangeBuffer } from '../../../services/commands/changeBuffer';
+import { DraftRepository } from '../../../services/draftRepository';
+import { emptyAnalysis, emptyDraft } from '../../../types/empty-factories';
+import { FIXTURE_STAMPS, memoryStorage, silentLogger } from '../../test-helpers';
+
+function tokenLink(
+  id: string,
+  status: TokenAnalysisLink['status'] = 'approved',
+): TokenAnalysisLink {
+  return {
+    id,
+    analysisId: `ta-${id}`,
+    ...FIXTURE_STAMPS,
+    status,
+    token: { tokenRef: 'GEN 1:1:0', surfaceText: 'In' },
+  };
+}
+
+function segmentLink(id: string): SegmentAnalysisLink {
+  return {
+    id,
+    analysisId: `sa-${id}`,
+    ...FIXTURE_STAMPS,
+    status: 'approved',
+    segmentId: 'GEN 1:1',
+  };
+}
+
+async function over(analysis: Partial<TextAnalysis>) {
+  const { storage } = memoryStorage();
+  const repository = new DraftRepository(storage, 'src', silentLogger());
+  await repository.replaceAll({
+    ...emptyDraft('src'),
+    analysis: { ...emptyAnalysis(), ...analysis },
+  });
+  return { repository, buffer: new ChangeBuffer(repository) };
+}
+
+describe('assertApprovalRule', () => {
+  it('accepts changes that leave each token one approval', async () => {
+    const { repository, buffer } = await over({ tokenAnalysisLinks: [tokenLink('a')] });
+
+    buffer.delete('tokenAnalysisLinks', tokenLink('a'));
+    buffer.create('tokenAnalysisLinks', tokenLink('b'));
+
+    await expect(assertApprovalRule(buffer, repository)).resolves.toBeUndefined();
+  });
+
+  it('refuses a second approval for a token', async () => {
+    const { repository, buffer } = await over({ tokenAnalysisLinks: [tokenLink('a')] });
+
+    buffer.create('tokenAnalysisLinks', tokenLink('b'));
+
+    await expect(assertApprovalRule(buffer, repository)).rejects.toThrow(
+      new ApprovalRuleError(['GEN 1:1:0']),
+    );
+  });
+
+  it('refuses a second approval for a segment', async () => {
+    const { repository, buffer } = await over({ segmentAnalysisLinks: [segmentLink('a')] });
+
+    buffer.create('segmentAnalysisLinks', segmentLink('b'));
+
+    await expect(assertApprovalRule(buffer, repository)).rejects.toThrow(ApprovalRuleError);
+  });
+
+  it('accepts changes that leave a stored breach no worse', async () => {
+    const { repository, buffer } = await over({
+      tokenAnalysisLinks: [tokenLink('a'), tokenLink('b'), tokenLink('c', 'suggested')],
+    });
+
+    buffer.put('tokenAnalysisLinks', { ...tokenLink('a'), updatedAt: '2026-06-01T00:00:00.000Z' });
+    buffer.put('tokenAnalysisLinks', tokenLink('c', 'rejected'));
+
+    await expect(assertApprovalRule(buffer, repository)).resolves.toBeUndefined();
+  });
+
+  it('names the places it refuses on the error', async () => {
+    const { repository, buffer } = await over({});
+
+    buffer.create('tokenAnalysisLinks', tokenLink('a'));
+    buffer.create('tokenAnalysisLinks', tokenLink('b'));
+
+    await expect(assertApprovalRule(buffer, repository)).rejects.toMatchObject({
+      places: ['GEN 1:1:0'],
+    });
+  });
+});
diff --git a/src/__tests__/services/commands/changeBuffer.test.ts b/src/__tests__/services/commands/changeBuffer.test.ts
new file mode 100644
index 000000000..b6862527b
--- /dev/null
+++ b/src/__tests__/services/commands/changeBuffer.test.ts
@@ -0,0 +1,192 @@
+/// <reference types="jest" />
+
+import type { TextAnalysis, TokenAnalysis, TokenAnalysisLink } from 'interlinearizer';
+import { ChangeBuffer } from '../../../services/commands/changeBuffer';
+import { DraftRepository } from '../../../services/draftRepository';
+import { emptyAnalysis, emptyDraft } from '../../../types/empty-factories';
+import { FIXTURE_STAMPS, makePhraseLink, memoryStorage, silentLogger } from '../../test-helpers';
+
+function payload(id: string, surfaceText = id): TokenAnalysis {
+  return { id, ...FIXTURE_STAMPS, surfaceText };
+}
+
+function link(id: string, analysisId: string, tokenRef: string): TokenAnalysisLink {
+  return {
+    id,
+    analysisId,
+    ...FIXTURE_STAMPS,
+    status: 'approved',
+    token: { tokenRef, surfaceText: 'In' },
+  };
+}
+
+/** A buffer over a draft holding `analysis`. */
+async function bufferOver(analysis: Partial<TextAnalysis> = {}): Promise<ChangeBuffer> {
+  const { storage } = memoryStorage();
+  const repository = new DraftRepository(storage, 'src', silentLogger());
+  await repository.replaceAll({
+    ...emptyDraft('src'),
+    analysis: { ...emptyAnalysis(), ...analysis },
+  });
+  return new ChangeBuffer(repository);
+}
+
+const ids = (records: readonly { id: string }[]) => records.map(({ id }) => id).sort();
+
+describe('ChangeBuffer', () => {
+  it('reads stored records as the repository does while nothing is staged', async () => {
+    const buffer = await bufferOver({
+      tokenAnalyses: [payload('ta-1')],
+      tokenAnalysisLinks: [link('tl-1', 'ta-1', 'GEN 1:1:0')],
+    });
+
+    await expect(buffer.getTokenAnalyses(['ta-1'])).resolves.toStrictEqual([payload('ta-1')]);
+    await expect(buffer.findLinksToAnalyses(['ta-1'])).resolves.toStrictEqual({
+      tokenAnalysisLinks: [link('tl-1', 'ta-1', 'GEN 1:1:0')],
+      phraseAnalysisLinks: [],
+      segmentAnalysisLinks: [],
+    });
+  });
+
+  it('answers with a staged put in place of the stored record', async () => {
+    const buffer = await bufferOver({ tokenAnalyses: [payload('ta-1')] });
+
+    buffer.put('tokenAnalyses', { ...payload('ta-1'), gloss: { en: 'one' } });
+
+    await expect(buffer.getTokenAnalyses(['ta-1'])).resolves.toStrictEqual([
+      { ...payload('ta-1'), gloss: { en: 'one' } },
+    ]);
+  });
+
+  it('leaves a staged removal out of every read', async () => {
+    const stored = link('tl-1', 'ta-1', 'GEN 1:1:0');
+    const buffer = await bufferOver({ tokenAnalysisLinks: [stored] });
+
+    buffer.delete('tokenAnalysisLinks', stored);
+
+    await expect(buffer.findLinksByToken(['GEN 1:1:0'])).resolves.toStrictEqual({
+      tokenAnalysisLinks: [],
+      phraseAnalysisLinks: [],
+    });
+  });
+
+  it('finds a record a staged put moves into a lookup, and not one it moves out', async () => {
+    const buffer = await bufferOver({
+      tokenAnalysisLinks: [link('tl-1', 'ta-1', 'GEN 1:1:0'), link('tl-2', 'ta-2', 'GEN 1:1:0')],
+    });
+
+    buffer.put('tokenAnalysisLinks', link('tl-1', 'ta-2', 'GEN 1:1:0'));
+
+    await expect(buffer.findLinksToAnalyses(['ta-1'])).resolves.toMatchObject({
+      tokenAnalysisLinks: [],
+    });
+    const { tokenAnalysisLinks } = await buffer.findLinksToAnalyses(['ta-2']);
+    expect(ids(tokenAnalysisLinks)).toStrictEqual(['tl-1', 'tl-2']);
+  });
+
+  it('answers every lookup through the staged changes', async () => {
+    const phrase = makePhraseLink('pa-1', ['GEN 1:1:0', 'GEN 1:1:3']);
+    const segmentLink = {
+      id: 'sl-1',
+      analysisId: 'sa-1',
+      ...FIXTURE_STAMPS,
+      status: 'approved' as const,
+      segmentId: 'GEN 1:1',
+    };
+    const buffer = await bufferOver({
+      phraseAnalyses: [{ id: 'pa-1', ...FIXTURE_STAMPS, surfaceText: 'In the' }],
+      phraseAnalysisLinks: [phrase],
+      segmentAnalyses: [{ id: 'sa-1', ...FIXTURE_STAMPS, surfaceText: 'In the beginning' }],
+      segmentAnalysisLinks: [segmentLink],
+    });
+
+    buffer.create('tokenAnalyses', payload('ta-new', 'In'));
+
+    await expect(buffer.findTokenAnalysesByForm(['in'])).resolves.toStrictEqual([
+      payload('ta-new', 'In'),
+    ]);
+    await expect(buffer.findPhraseAnalysesByForm(['in the']).then(ids)).resolves.toStrictEqual([
+      'pa-1',
+    ]);
+    await expect(buffer.getPhraseAnalyses(['pa-1']).then(ids)).resolves.toStrictEqual(['pa-1']);
+    await expect(buffer.getSegmentAnalyses(['sa-1']).then(ids)).resolves.toStrictEqual(['sa-1']);
+    await expect(buffer.findLinksBySegment(['GEN 1:1'])).resolves.toStrictEqual([segmentLink]);
+    await expect(buffer.findLinksByToken(['GEN 1:1:3'])).resolves.toStrictEqual({
+      tokenAnalysisLinks: [],
+      phraseAnalysisLinks: [phrase],
+    });
+    await expect(buffer.findLinksToAnalyses(['pa-1', 'sa-1'])).resolves.toStrictEqual({
+      tokenAnalysisLinks: [],
+      phraseAnalysisLinks: [phrase],
+      segmentAnalysisLinks: [segmentLink],
+    });
+  });
+
+  it('hands out copies, so changing a record read stages nothing', async () => {
+    const buffer = await bufferOver({ tokenAnalyses: [payload('ta-1')] });
+    const [read] = await buffer.getTokenAnalyses(['ta-1']);
+
+    read.surfaceText = 'changed';
+
+    expect(buffer.toChangeSet('nothing')).toStrictEqual({ intent: 'nothing' });
+    await expect(buffer.getTokenAnalyses(['ta-1'])).resolves.toStrictEqual([payload('ta-1')]);
+  });
+
+  it('keeps a staged record as it stood when staged', async () => {
+    const buffer = await bufferOver();
+    const created = payload('ta-1');
+
+    buffer.create('tokenAnalyses', created);
+    created.surfaceText = 'changed';
+
+    expect(buffer.toChangeSet('create').tokenAnalyses?.puts).toStrictEqual([payload('ta-1')]);
+  });
+
+  it('collects the staged puts and removals of each kind into one change set', async () => {
+    const stored = link('tl-1', 'ta-1', 'GEN 1:1:0');
+    const buffer = await bufferOver({
+      tokenAnalyses: [payload('ta-1')],
+      tokenAnalysisLinks: [stored],
+    });
+
+    buffer.put('tokenAnalyses', { ...payload('ta-1'), gloss: { en: 'one' } });
+    buffer.delete('tokenAnalysisLinks', stored);
+
+    expect(buffer.toChangeSet('edit')).toStrictEqual({
+      intent: 'edit',
+      tokenAnalyses: { puts: [{ ...payload('ta-1'), gloss: { en: 'one' } }], deletes: [] },
+      tokenAnalysisLinks: { puts: [], deletes: ['tl-1'] },
+    });
+  });
+
+  it('stages nothing for a record it created and then removed', async () => {
+    const buffer = await bufferOver();
+
+    buffer.create('tokenAnalyses', payload('ta-new'));
+    buffer.delete('tokenAnalyses', payload('ta-new'));
+
+    expect(buffer.toChangeSet('none')).toStrictEqual({ intent: 'none' });
+  });
+
+  it('stages a put again after a removal of a stored record', async () => {
+    const buffer = await bufferOver({ tokenAnalyses: [payload('ta-1')] });
+
+    buffer.delete('tokenAnalyses', payload('ta-1'));
+    buffer.put('tokenAnalyses', payload('ta-1'));
+
+    expect(buffer.toChangeSet('restore').tokenAnalyses).toStrictEqual({
+      puts: [payload('ta-1')],
+      deletes: [],
+    });
+  });
+
+  it('lists the records it touches as they stood before a removal or will stand after a put', async () => {
+    const stored = link('tl-1', 'ta-1', 'GEN 1:1:0');
+    const buffer = await bufferOver({ tokenAnalysisLinks: [stored] });
+
+    buffer.delete('tokenAnalysisLinks', stored);
+    buffer.create('tokenAnalysisLinks', link('tl-2', 'ta-1', 'GEN 1:1:3'));
+
+    expect(ids(buffer.touched('tokenAnalysisLinks'))).toStrictEqual(['tl-1', 'tl-2']);
+  });
+});
diff --git a/src/__tests__/services/commands/parity.ts b/src/__tests__/services/commands/parity.ts
new file mode 100644
index 000000000..4307d22d1
--- /dev/null
+++ b/src/__tests__/services/commands/parity.ts
@@ -0,0 +1,75 @@
+/// <reference types="jest" />
+
+import type { UnknownAction } from '@reduxjs/toolkit';
+import type { TextAnalysis } from 'interlinearizer';
+import { ChangeBuffer } from '../../../services/commands/changeBuffer';
+import { DraftRepository } from '../../../services/draftRepository';
+import reducer from '../../../store/analysisSlice';
+import type { ChangeSet, IndexDifference } from '../../../types/analysis-repository';
+import { emptyDraft } from '../../../types/empty-factories';
+import { memoryStorage, silentLogger } from '../../test-helpers';
+
+/** What one input gives through the store's reducer and through the host's command. */
+export type ParityOutcome = {
+  /** The analysis the reducer leaves, its record lists in id order. */
+  store: TextAnalysis;
+  /** The analysis the command's changes leave once applied and reloaded, in id order. */
+  host: TextAnalysis;
+  /** The changes the command staged. */
+  changes: ChangeSet;
+  /** Where the repository's kept indexes differ from its records after applying the changes. */
+  indexDifferences: IndexDifference[];
+};
+
+/** `analysis` as JSON holds it, with each record list in id order. */
+function normalized(analysis: TextAnalysis): TextAnalysis {
+  const plain: TextAnalysis = JSON.parse(JSON.stringify(analysis));
+  const byId = <T extends { id: string }>(records: T[]) =>
+    [...records].sort((a, b) => a.id.localeCompare(b.id));
+  return {
+    segmentAnalyses: byId(plain.segmentAnalyses),
+    segmentAnalysisLinks: byId(plain.segmentAnalysisLinks),
+    tokenAnalyses: byId(plain.tokenAnalyses),
+    tokenAnalysisLinks: byId(plain.tokenAnalysisLinks),
+    phraseAnalyses: byId(plain.phraseAnalyses),
+    phraseAnalysisLinks: byId(plain.phraseAnalysisLinks),
+  };
+}
+
+/**
+ * Runs one input both ways over `analysis`: `action` through the store's reducer, working in
+ * `analysisLanguage`, and `command` staging changes over a draft holding the same analysis, which
+ * are then applied and the draft reloaded from storage.
+ */
+export async function runParity(
+  analysis: TextAnalysis,
+  analysisLanguage: string,
+  action: UnknownAction,
+  command: (buffer: ChangeBuffer) => Promise<void>,
+): Promise<ParityOutcome> {
+  const store = reducer(
+    { analysis: JSON.parse(JSON.stringify(analysis)), analysisLanguage },
+    action,
+  );
+
+  const { storage } = memoryStorage();
+  const logger = silentLogger();
+  await new DraftRepository(storage, 'src', logger).replaceAll({
+    ...emptyDraft('src'),
+    analysisLanguages: [analysisLanguage],
+    analysis: JSON.parse(JSON.stringify(analysis)),
+  });
+  const repository = new DraftRepository(storage, 'src', logger);
+  const buffer = new ChangeBuffer(repository);
+  await command(buffer);
+  const changes = buffer.toChangeSet('parity');
+  await repository.apply(changes);
+  const { draft: reloaded } = await new DraftRepository(storage, 'src', logger).exportAll();
+
+  return {
+    store: normalized(store.analysis),
+    host: normalized(reloaded.analysis),
+    changes,
+    indexDifferences: await repository.checkIndexes(),
+  };
+}
diff --git a/src/__tests__/services/commands/tokenCommands.parity.test.ts b/src/__tests__/services/commands/tokenCommands.parity.test.ts
new file mode 100644
index 000000000..a00234a54
--- /dev/null
+++ b/src/__tests__/services/commands/tokenCommands.parity.test.ts
@@ -0,0 +1,548 @@
+/// <reference types="jest" />
+
+import type { TextAnalysis, TokenAnalysis, TokenAnalysisLink } from 'interlinearizer';
+import {
+  approveAnalysisForToken as approveCommand,
+  writeGloss as writeGlossCommand,
+} from '../../../services/commands/tokenCommands';
+import { approveAnalysisForToken, writeGloss } from '../../../store/analysisSlice';
+import { emptyAnalysis } from '../../../types/empty-factories';
+import { FIXTURE_STAMPS } from '../../test-helpers';
+import { runParity } from './parity';
+
+const NOW = '2026-06-01T00:00:00.000Z';
+const EARLIER = { createdAt: '2025-06-01T00:00:00.000Z', updatedAt: '2025-06-01T00:00:00.000Z' };
+const LATER = { createdAt: '2026-03-01T00:00:00.000Z', updatedAt: '2026-03-01T00:00:00.000Z' };
+
+function payload(id: string, surfaceText: string, fields: Partial<TokenAnalysis> = {}) {
+  return { id, ...FIXTURE_STAMPS, surfaceText, ...fields };
+}
+
+function link(
+  id: string,
+  analysisId: string,
+  tokenRef: string,
+  fields: Partial<TokenAnalysisLink> = {},
+): TokenAnalysisLink {
+  return {
+    id,
+    analysisId,
+    ...FIXTURE_STAMPS,
+    status: 'approved',
+    token: { tokenRef, surfaceText: 'in' },
+    ...fields,
+  };
+}
+
+function analysisOf(
+  tokenAnalyses: TokenAnalysis[],
+  tokenAnalysisLinks: TokenAnalysisLink[],
+): TextAnalysis {
+  return { ...emptyAnalysis(), tokenAnalyses, tokenAnalysisLinks };
+}
+
+const TOKEN = 'GEN 1:1:0';
+const OTHER_TOKEN = 'GEN 1:2:0';
+
+type ParityCase<Input> = {
+  analysis: TextAnalysis;
+  input: Input;
+  /** What the reducer's result must show, so the case exercises the path it names. */
+  expectStore: (store: TextAnalysis) => void;
+};
+
+type GlossInput = { surfaceText?: string; value: string };
+
+const ids = (records: readonly { id: string }[]) => records.map(({ id }) => id).sort();
+
+describe('writeGloss parity with the reducer', () => {
+  const cases: [string, ParityCase<GlossInput>][] = [
+    [
+      'creates a payload and an approved link for an unglossed token',
+      {
+        analysis: emptyAnalysis(),
+        input: { value: 'at' },
+        expectStore: (store) => {
+          expect(ids(store.tokenAnalyses)).toStrictEqual(['new-analysis']);
+          expect(ids(store.tokenAnalysisLinks)).toStrictEqual(['new-link']);
+        },
+      },
+    ],
+    [
+      'shares a stored payload whose content matches',
+      {
+        analysis: analysisOf(
+          [payload('ta-in', 'in', { gloss: { en: 'at' } })],
+          [link('tl-other', 'ta-in', OTHER_TOKEN)],
+        ),
+        input: { value: 'at' },
+        expectStore: (store) => {
+          expect(ids(store.tokenAnalyses)).toStrictEqual(['ta-in']);
+          expect(store.tokenAnalysisLinks.find(({ id }) => id === 'new-link')?.analysisId).toBe(
+            'ta-in',
+          );
+        },
+      },
+    ],
+    [
+      "approves the token's held link to the matching payload rather than adding one",
+      {
+        analysis: analysisOf(
+          [payload('ta-in', 'in', { gloss: { en: 'at' } })],
+          [link('tl-held', 'ta-in', TOKEN, { status: 'suggested', confidence: 'low' })],
+        ),
+        input: { value: 'at' },
+        expectStore: (store) => {
+          expect(store.tokenAnalysisLinks).toHaveLength(1);
+          expect(store.tokenAnalysisLinks[0].status).toBe('approved');
+        },
+      },
+    ],
+    [
+      'edits an unshared payload in place, refreshing surface text and dropping its sense',
+      {
+        analysis: analysisOf(
+          [
+            payload('ta-in', 'In', {
+              gloss: { en: 'at', fr: 'à' },
+              glossSenseRef: { authority: 'fwlite', senseId: 's-at' },
+            }),
+          ],
+          [link('tl-in', 'ta-in', TOKEN)],
+        ),
+        input: { surfaceText: 'In,', value: 'at first' },
+        expectStore: (store) => {
+          expect(store.tokenAnalyses).toStrictEqual([
+            payload('ta-in', 'In,', { gloss: { en: 'at first', fr: 'à' }, updatedAt: NOW }),
+          ]);
+        },
+      },
+    ],
+    [
+      'forks a payload other tokens share, editing only the fork',
+      {
+        analysis: analysisOf(
+          [payload('ta-in', 'In', { gloss: { en: 'at' } })],
+          [link('tl-in', 'ta-in', TOKEN), link('tl-other', 'ta-in', OTHER_TOKEN)],
+        ),
+        input: { value: 'start' },
+        expectStore: (store) => {
+          expect(ids(store.tokenAnalyses)).toStrictEqual(['new-analysis', 'ta-in']);
+        },
+      },
+    ],
+    [
+      "folds an edit matching another payload into it, clearing the survivor's stale breakdown",
+      {
+        analysis: analysisOf(
+          [
+            payload('ta-at', 'in', { gloss: { en: 'at' } }),
+            payload('ta-within', 'In', {
+              ...EARLIER,
+              gloss: { en: 'within' },
+              morphemesStale: true,
+            }),
+          ],
+          [link('tl-in', 'ta-at', TOKEN), link('tl-other', 'ta-within', OTHER_TOKEN)],
+        ),
+        input: { value: 'within' },
+        expectStore: (store) => {
+          expect(ids(store.tokenAnalyses)).toStrictEqual(['ta-within']);
+          expect(store.tokenAnalyses[0].morphemesStale).toBeUndefined();
+        },
+      },
+    ],
+    [
+      'leaves a token linking both folded payloads one link, dated by the earlier',
+      {
+        analysis: analysisOf(
+          [
+            payload('ta-at', 'In', { gloss: { en: 'at' } }),
+            payload('ta-within', 'In', { ...EARLIER, gloss: { en: 'within' } }),
+          ],
+          [
+            link('tl-in', 'ta-at', TOKEN, LATER),
+            link('tl-offered', 'ta-within', TOKEN, { ...EARLIER, status: 'suggested' }),
+          ],
+        ),
+        input: { value: 'within' },
+        expectStore: (store) => {
+          expect(store.tokenAnalysisLinks).toHaveLength(1);
+          expect(store.tokenAnalysisLinks[0]).toMatchObject({
+            id: 'tl-in',
+            status: 'approved',
+            createdAt: EARLIER.createdAt,
+          });
+        },
+      },
+    ],
+    [
+      'folds into a payload another token was offered, leaving that offer as it was',
+      {
+        analysis: analysisOf(
+          [
+            payload('ta-at', 'In', { gloss: { en: 'at' } }),
+            payload('ta-within', 'In', { ...EARLIER, gloss: { en: 'within' } }),
+          ],
+          [
+            link('tl-in', 'ta-at', TOKEN),
+            link('tl-offered', 'ta-within', OTHER_TOKEN, { status: 'suggested' }),
+          ],
+        ),
+        input: { value: 'within' },
+        expectStore: (store) => {
+          expect(store.tokenAnalysisLinks).toStrictEqual(
+            expect.arrayContaining([
+              expect.objectContaining({ id: 'tl-offered', status: 'suggested' }),
+            ]),
+          );
+          expect(ids(store.tokenAnalyses)).toStrictEqual(['ta-within']);
+        },
+      },
+    ],
+    [
+      'clears the gloss, removing the payload it empties and its link',
+      {
+        analysis: analysisOf(
+          [payload('ta-in', 'In', { gloss: { en: 'at' } })],
+          [link('tl-in', 'ta-in', TOKEN)],
+        ),
+        input: { value: '' },
+        expectStore: (store) => {
+          expect(store).toStrictEqual(emptyAnalysis());
+        },
+      },
+    ],
+    [
+      'clears one language, keeping the others and the sense',
+      {
+        analysis: analysisOf(
+          [
+            payload('ta-in', 'In', {
+              gloss: { en: 'at', fr: 'à' },
+              glossSenseRef: { authority: 'fwlite', senseId: 's-at' },
+            }),
+          ],
+          [link('tl-in', 'ta-in', TOKEN)],
+        ),
+        input: { value: '  ' },
+        expectStore: (store) => {
+          expect(store.tokenAnalyses[0].gloss).toStrictEqual({ fr: 'à' });
+          expect(store.tokenAnalyses[0].glossSenseRef).toBeDefined();
+        },
+      },
+    ],
+    [
+      'clears a shared payload by dropping only this token’s link',
+      {
+        analysis: analysisOf(
+          [payload('ta-in', 'In', { gloss: { en: 'at' } })],
+          [link('tl-in', 'ta-in', TOKEN), link('tl-other', 'ta-in', OTHER_TOKEN)],
+        ),
+        input: { value: '' },
+        expectStore: (store) => {
+          expect(ids(store.tokenAnalyses)).toStrictEqual(['ta-in']);
+          expect(ids(store.tokenAnalysisLinks)).toStrictEqual(['tl-other']);
+        },
+      },
+    ],
+    [
+      'keeps an emptied payload another of the token’s links still names',
+      {
+        analysis: analysisOf(
+          [payload('ta-in', 'In', { gloss: { en: 'at' } })],
+          [
+            link('tl-in', 'ta-in', TOKEN),
+            link('tl-rejected', 'ta-in', TOKEN, { status: 'rejected' }),
+          ],
+        ),
+        input: { value: '' },
+        expectStore: (store) => {
+          expect(store.tokenAnalyses).toStrictEqual([payload('ta-in', 'In', { updatedAt: NOW })]);
+          expect(ids(store.tokenAnalysisLinks)).toStrictEqual(['tl-rejected']);
+        },
+      },
+    ],
+    [
+      'folds a cleared payload into another its remaining content matches',
+      {
+        analysis: analysisOf(
+          [
+            payload('ta-in', 'In', { gloss: { en: 'at' }, pos: 'prep' }),
+            payload('ta-bare', 'in', { ...EARLIER, pos: 'prep' }),
+          ],
+          [link('tl-in', 'ta-in', TOKEN)],
+        ),
+        input: { value: '' },
+        expectStore: (store) => {
+          expect(ids(store.tokenAnalyses)).toStrictEqual(['ta-bare']);
+          expect(store.tokenAnalysisLinks[0].analysisId).toBe('ta-bare');
+        },
+      },
+    ],
+    [
+      'folds a fork back onto the shared payload when the write leaves it unchanged',
+      {
+        analysis: analysisOf(
+          [payload('ta-in', 'In', { gloss: { en: 'at' } })],
+          [link('tl-in', 'ta-in', TOKEN), link('tl-other', 'ta-in', OTHER_TOKEN)],
+        ),
+        input: { value: 'at' },
+        expectStore: (store) => {
+          expect(ids(store.tokenAnalyses)).toStrictEqual(['ta-in']);
+          expect(store.tokenAnalysisLinks.every(({ analysisId }) => analysisId === 'ta-in')).toBe(
+            true,
+          );
+        },
+      },
+    ],
+    [
+      'edits the payload an approval tie picks among several approved links',
+      {
+        analysis: analysisOf(
+          [
+            payload('ta-old', 'In', { gloss: { en: 'old' } }),
+            payload('ta-new', 'In', { gloss: { en: 'new' } }),
+          ],
+          [link('tl-old', 'ta-old', TOKEN, EARLIER), link('tl-new', 'ta-new', TOKEN, LATER)],
+        ),
+        input: { value: 'newer' },
+        expectStore: (store) => {
+          expect(store.tokenAnalyses.find(({ id }) => id === 'ta-new')?.gloss).toStrictEqual({
+            en: 'newer',
+          });
+        },
+      },
+    ],
+    [
+      'stages nothing for a blank write to an unglossed token',
+      {
+        analysis: analysisOf([payload('ta-in', 'In', { gloss: { en: 'at' } })], []),
+        input: { value: '' },
+        expectStore: (store) => {
+          expect(ids(store.tokenAnalyses)).toStrictEqual(['ta-in']);
+        },
+      },
+    ],
+    [
+      'removes an approved link whose payload is gone before writing',
+      {
+        analysis: analysisOf([], [link('tl-orphan', 'ta-missing', TOKEN)]),
+        input: { value: 'at' },
+        expectStore: (store) => {
+          expect(ids(store.tokenAnalysisLinks)).toStrictEqual(['new-link']);
+        },
+      },
+    ],
+    [
+      'removes an approved link whose payload is gone even on a blank write',
+      {
+        analysis: analysisOf([], [link('tl-orphan', 'ta-missing', TOKEN)]),
+        input: { value: '' },
+        expectStore: (store) => {
+          expect(store).toStrictEqual(emptyAnalysis());
+        },
+      },
+    ],
+  ];
+
+  it.each(cases)('%s', async (_name, { analysis, input, expectStore }) => {
+    const surfaceText = input.surfaceText ?? 'In';
+    const outcome = await runParity(
+      analysis,
+      'en',
+      {
+        type: writeGloss.type,
+        payload: {
+          tokenRef: TOKEN,
+          surfaceText,
+          value: input.value,
+          id: 'new-analysis',
+          linkId: 'new-link',
+          now: NOW,
+        },
+      },
+      (buffer) =>
+        writeGlossCommand(buffer, {
+          tokenRef: TOKEN,
+          surfaceText,
+          value: input.value,
+          analysisLanguage: 'en',
+          analysisId: 'new-analysis',
+          linkId: 'new-link',
+          now: NOW,
+        }),
+    );
+
+    expectStore(outcome.store);
+    expect(outcome.host).toStrictEqual(outcome.store);
+    expect(outcome.indexDifferences).toStrictEqual([]);
+  });
+});
+
+type ApproveInput = { analysisId: string };
+
+describe('approveAnalysisForToken parity with the reducer', () => {
+  const cases: [string, ParityCase<ApproveInput>][] = [
+    [
+      'gives a token with no approval a new approved link',
+      {
+        analysis: analysisOf([payload('ta-in', 'In', { gloss: { en: 'at' } })], []),
+        input: { analysisId: 'ta-in' },
+        expectStore: (store) => {
+          expect(store.tokenAnalysisLinks).toStrictEqual([
+            {
+              id: 'new-link',
+              analysisId: 'ta-in',
+              createdAt: NOW,
+              updatedAt: NOW,
+              status: 'approved',
+              token: { tokenRef: TOKEN, surfaceText: 'In' },
+            },
+          ]);
+        },
+      },
+    ],
+    [
+      'approves the link the token holds to the payload rather than adding one',
+      {
+        analysis: analysisOf(
+          [payload('ta-in', 'In', { gloss: { en: 'at' } })],
+          [link('tl-held', 'ta-in', TOKEN, { status: 'candidate', confidence: 'guess' })],
+        ),
+        input: { analysisId: 'ta-in' },
+        expectStore: (store) => {
+          expect(store.tokenAnalysisLinks).toHaveLength(1);
+          expect(store.tokenAnalysisLinks[0]).toMatchObject({
+            status: 'approved',
+            confidence: 'guess',
+          });
+        },
+      },
+    ],
+    [
+      'moves the approval off a payload, removing it once nothing links it',
+      {
+        analysis: analysisOf(
+          [
+            payload('ta-at', 'In', { gloss: { en: 'at' } }),
+            payload('ta-on', 'In', { gloss: { en: 'on' } }),
+          ],
+          [link('tl-in', 'ta-at', TOKEN)],
+        ),
+        input: { analysisId: 'ta-on' },
+        expectStore: (store) => {
+          expect(ids(store.tokenAnalyses)).toStrictEqual(['ta-on']);
+          expect(store.tokenAnalysisLinks[0].analysisId).toBe('ta-on');
+        },
+      },
+    ],
+    [
+      'keeps the payload the approval leaves when another token links it',
+      {
+        analysis: analysisOf(
+          [
+            payload('ta-at', 'In', { gloss: { en: 'at' } }),
+            payload('ta-on', 'In', { gloss: { en: 'on' } }),
+          ],
+          [link('tl-in', 'ta-at', TOKEN), link('tl-other', 'ta-at', OTHER_TOKEN)],
+        ),
+        input: { analysisId: 'ta-on' },
+        expectStore: (store) => {
+          expect(ids(store.tokenAnalyses)).toStrictEqual(['ta-at', 'ta-on']);
+        },
+      },
+    ],
+    [
+      'approves a held link in place of the approval, keeping the earlier creation date',
+      {
+        analysis: analysisOf(
+          [
+            payload('ta-at', 'In', { gloss: { en: 'at' } }),
+            payload('ta-on', 'In', { gloss: { en: 'on' } }),
+          ],
+          [
+            link('tl-in', 'ta-at', TOKEN, EARLIER),
+            link('tl-held', 'ta-on', TOKEN, { ...LATER, status: 'suggested' }),
+          ],
+        ),
+        input: { analysisId: 'ta-on' },
+        expectStore: (store) => {
+          expect(store.tokenAnalysisLinks).toStrictEqual([
+            expect.objectContaining({
+              id: 'tl-held',
+              status: 'approved',
+              createdAt: EARLIER.createdAt,
+            }),
+          ]);
+          expect(ids(store.tokenAnalyses)).toStrictEqual(['ta-on']);
+        },
+      },
+    ],
+    [
+      'stages nothing for a payload not stored',
+      {
+        analysis: analysisOf([], [link('tl-orphan', 'ta-missing', TOKEN)]),
+        input: { analysisId: 'ta-unknown' },
+        expectStore: (store) => {
+          expect(ids(store.tokenAnalysisLinks)).toStrictEqual(['tl-orphan']);
+        },
+      },
+    ],
+    [
+      'removes orphaned approvals even when the payload is already approved',
+      {
+        analysis: analysisOf(
+          [payload('ta-in', 'In', { gloss: { en: 'at' } })],
+          [link('tl-in', 'ta-in', TOKEN, LATER), link('tl-orphan', 'ta-missing', TOKEN, EARLIER)],
+        ),
+        input: { analysisId: 'ta-in' },
+        expectStore: (store) => {
+          expect(ids(store.tokenAnalysisLinks)).toStrictEqual(['tl-in']);
+        },
+      },
+    ],
+    [
+      'removes orphaned approvals before approving',
+      {
+        analysis: analysisOf(
+          [payload('ta-in', 'In', { gloss: { en: 'at' } })],
+          [link('tl-orphan', 'ta-missing', TOKEN)],
+        ),
+        input: { analysisId: 'ta-in' },
+        expectStore: (store) => {
+          expect(ids(store.tokenAnalysisLinks)).toStrictEqual(['new-link']);
+        },
+      },
+    ],
+  ];
+
+  it.each(cases)('%s', async (_name, { analysis, input, expectStore }) => {
+    const outcome = await runParity(
+      analysis,
+      'en',
+      {
+        type: approveAnalysisForToken.type,
+        payload: {
+          tokenRef: TOKEN,
+          surfaceText: 'In',
+          analysisId: input.analysisId,
+          linkId: 'new-link',
+          now: NOW,
+        },
+      },
+      (buffer) =>
+        approveCommand(buffer, {
+          tokenRef: TOKEN,
+          surfaceText: 'In',
+          analysisId: input.analysisId,
+          linkId: 'new-link',
+          now: NOW,
+        }),
+    );
+
+    expectStore(outcome.store);
+    expect(outcome.host).toStrictEqual(outcome.store);
+    expect(outcome.indexDifferences).toStrictEqual([]);
+  });
+});
diff --git a/src/__tests__/services/commands/tokenCommands.test.ts b/src/__tests__/services/commands/tokenCommands.test.ts
new file mode 100644
index 000000000..7550f665e
--- /dev/null
+++ b/src/__tests__/services/commands/tokenCommands.test.ts
@@ -0,0 +1,92 @@
+/// <reference types="jest" />
+
+import type { TextAnalysis, TokenAnalysis, TokenAnalysisLink } from 'interlinearizer';
+import { ChangeBuffer } from '../../../services/commands/changeBuffer';
+import { approveAnalysisForToken, writeGloss } from '../../../services/commands/tokenCommands';
+import { DraftRepository } from '../../../services/draftRepository';
+import { emptyAnalysis, emptyDraft } from '../../../types/empty-factories';
+import { FIXTURE_STAMPS, memoryStorage, silentLogger } from '../../test-helpers';
+
+const NOW = '2026-06-01T00:00:00.000Z';
+const STAMP = { analysisId: 'new-analysis', linkId: 'new-link', now: NOW };
+
+const shared: TokenAnalysis = {
+  id: 'ta-in',
+  ...FIXTURE_STAMPS,
+  surfaceText: 'In',
+  gloss: { en: 'at' },
+};
+
+function link(id: string, tokenRef: string): TokenAnalysisLink {
+  return {
+    id,
+    analysisId: 'ta-in',
+    ...FIXTURE_STAMPS,
+    status: 'approved',
+    token: { tokenRef, surfaceText: 'In' },
+  };
+}
+
+async function bufferOver(analysis: Partial<TextAnalysis>): Promise<ChangeBuffer> {
+  const { storage } = memoryStorage();
+  const repository = new DraftRepository(storage, 'src', silentLogger());
+  await repository.replaceAll({
+    ...emptyDraft('src'),
+    analysis: { ...emptyAnalysis(), ...analysis },
+  });
+  return new ChangeBuffer(repository);
+}
+
+describe('writeGloss', () => {
+  it("stages only the link's removal when clearing a shared payload, never its fork", async () => {
+    const buffer = await bufferOver({
+      tokenAnalyses: [shared],
+      tokenAnalysisLinks: [link('tl-1', 'GEN 1:1:0'), link('tl-2', 'GEN 1:2:0')],
+    });
+
+    await writeGloss(buffer, {
+      ...STAMP,
+      tokenRef: 'GEN 1:1:0',
+      surfaceText: 'In',
+      value: '',
+      analysisLanguage: 'en',
+    });
+
+    expect(buffer.toChangeSet('writeGloss')).toStrictEqual({
+      intent: 'writeGloss',
+      tokenAnalysisLinks: { puts: [], deletes: ['tl-1'] },
+    });
+  });
+
+  it('stages nothing for a blank write to an unglossed token', async () => {
+    const buffer = await bufferOver({ tokenAnalyses: [shared] });
+
+    await writeGloss(buffer, {
+      ...STAMP,
+      tokenRef: 'GEN 1:1:0',
+      surfaceText: 'In',
+      value: ' ',
+      analysisLanguage: 'en',
+    });
+
+    expect(buffer.toChangeSet('writeGloss')).toStrictEqual({ intent: 'writeGloss' });
+  });
+});
+
+describe('approveAnalysisForToken', () => {
+  it('stages nothing for a payload already approved for the token', async () => {
+    const buffer = await bufferOver({
+      tokenAnalyses: [shared],
+      tokenAnalysisLinks: [link('tl-1', 'GEN 1:1:0')],
+    });
+
+    await approveAnalysisForToken(buffer, {
+      ...STAMP,
+      tokenRef: 'GEN 1:1:0',
+      surfaceText: 'In',
+      analysisId: 'ta-in',
+    });
+
+    expect(buffer.toChangeSet('approve')).toStrictEqual({ intent: 'approve' });
+  });
+});
diff --git a/src/__tests__/services/indexedRepository.test.ts b/src/__tests__/services/indexedRepository.test.ts
index 290a6cb98..dd3de6988 100644
--- a/src/__tests__/services/indexedRepository.test.ts
+++ b/src/__tests__/services/indexedRepository.test.ts
@@ -2,27 +2,30 @@
 
 import type { TextAnalysis } from 'interlinearizer';
 import { AnalysisIndex } from '../../services/analysisIndex';
-import { type IndexedAnalysis, IndexedRepository } from '../../services/indexedRepository';
-import { emptyAnalysis } from '../../types/empty-factories';
+import { type IndexedDraft, IndexedRepository } from '../../services/indexedRepository';
+import { emptyAnalysis, emptyDraft } from '../../types/empty-factories';
 import { FIXTURE_STAMPS } from '../test-helpers';
 
 /** Answers lookups from an index over `records`, keeping it as `keep` says. */
 class StubRepository extends IndexedRepository {
-  readonly kept: IndexedAnalysis | undefined;
+  readonly kept: IndexedDraft | undefined;
 
-  private readonly index: AnalysisIndex;
+  private readonly indexedDraft: IndexedDraft;
 
   constructor(records: TextAnalysis, keep: 'kept' | 'none') {
     super();
-    this.index = new AnalysisIndex(records);
-    this.kept = keep === 'kept' ? { analysis: records, index: this.index } : undefined;
+    this.indexedDraft = {
+      draft: { ...emptyDraft('src'), analysisLanguages: ['en'], analysis: records },
+      index: new AnalysisIndex(records),
+    };
+    this.kept = keep === 'kept' ? this.indexedDraft : undefined;
   }
 
-  protected async indexed(): Promise<AnalysisIndex> {
-    return this.index;
+  protected async indexed(): Promise<IndexedDraft> {
+    return this.indexedDraft;
   }
 
-  protected keptIndex(): IndexedAnalysis | undefined {
+  protected keptIndex(): IndexedDraft | undefined {
     return this.kept;
   }
 }
@@ -54,7 +57,7 @@ describe('IndexedRepository', () => {
 
   it('reports the differences of the index it keeps from its analysis', async () => {
     const repository = new StubRepository(analysis(), 'kept');
-    repository.kept?.analysis.tokenAnalyses.pop();
+    repository.kept?.draft.analysis.tokenAnalyses.pop();
 
     await expect(repository.checkIndexes()).resolves.toContainEqual({
       index: 'tokenAnalyses',
@@ -64,6 +67,15 @@ describe('IndexedRepository', () => {
     });
   });
 
+  it("reads the draft's own record without its analysis", async () => {
+    await expect(new StubRepository(analysis(), 'none').getScope()).resolves.toStrictEqual({
+      sourceProjectId: 'src',
+      modelVersion: emptyDraft('src').modelVersion,
+      analysisLanguages: ['en'],
+      dirty: false,
+    });
+  });
+
   it('reports nothing while it keeps no index', async () => {
     await expect(new StubRepository(analysis(), 'none').checkIndexes()).resolves.toStrictEqual([]);
   });
diff --git a/src/__tests__/services/projectStorage.test.ts b/src/__tests__/services/projectStorage.test.ts
index 948c16f9e..b2cdae455 100644
--- a/src/__tests__/services/projectStorage.test.ts
+++ b/src/__tests__/services/projectStorage.test.ts
@@ -2946,6 +2946,11 @@ describe('projectStorage', () => {
       ],
       ['findPhraseAnalysesByForm', (r: AnalysisRepository) => r.findPhraseAnalysesByForm(['x']), 0],
       ['checkIndexes', (r: AnalysisRepository) => r.checkIndexes(), 0],
+      [
+        'getScope',
+        (r: AnalysisRepository) => r.getScope().then(({ analysisLanguages }) => analysisLanguages),
+        0,
+      ],
     ])('answers %s from the draft saveDraft saved', async (_name, lookup, count) => {
       await saveDraft(token, 'src-proj', makeDraftSpanningBooks('src-proj', 'GEN'));
 
diff --git a/src/__tests__/utils/change-set.test.ts b/src/__tests__/utils/change-set.test.ts
index 7e6e57d1d..6d3802ee5 100644
--- a/src/__tests__/utils/change-set.test.ts
+++ b/src/__tests__/utils/change-set.test.ts
@@ -2,7 +2,7 @@
 
 import type { DraftProject, TokenAnalysis } from 'interlinearizer';
 import { emptyAnalysis, emptyDraft } from '../../types/empty-factories';
-import { applyChangeSet, scopeRecordOf } from '../../utils/change-set';
+import { applyChangeSet, isEmptyChangeSet, scopeRecordOf } from '../../utils/change-set';
 import { FIXTURE_STAMPS } from '../test-helpers';
 
 function payload(id: string, gloss?: string): TokenAnalysis {
@@ -179,3 +179,19 @@ describe('applyChangeSet', () => {
     ).toStrictEqual([['sa'], ['sl'], ['a'], ['tl'], ['pa'], ['pl']]);
   });
 });
+
+describe('isEmptyChangeSet', () => {
+  it('finds a change set naming only its intent empty', () => {
+    expect(isEmptyChangeSet({ intent: 'none' })).toBe(true);
+  });
+
+  it('finds a change set with record changes not empty', () => {
+    expect(isEmptyChangeSet({ intent: 'edit', tokenAnalyses: { puts: [], deletes: ['a'] } })).toBe(
+      false,
+    );
+  });
+
+  it("finds a change set putting the scope's record not empty", () => {
+    expect(isEmptyChangeSet({ intent: 'edit', scope: scopeRecordOf(draftOf()) })).toBe(false);
+  });
+});
diff --git a/src/__tests__/utils/token-analysis-content.test.ts b/src/__tests__/utils/token-analysis-content.test.ts
new file mode 100644
index 000000000..5625fd3a3
--- /dev/null
+++ b/src/__tests__/utils/token-analysis-content.test.ts
@@ -0,0 +1,59 @@
+/// <reference types="jest" />
+
+import type { TokenAnalysis } from 'interlinearizer';
+import { clearAnalysisGloss, isEmptyTokenAnalysis } from '../../utils/token-analysis-content';
+import { FIXTURE_STAMPS } from '../test-helpers';
+
+function analysis(fields: Partial<TokenAnalysis> = {}): TokenAnalysis {
+  return { id: 'ta-1', ...FIXTURE_STAMPS, surfaceText: 'In', ...fields };
+}
+
+describe('isEmptyTokenAnalysis', () => {
+  it('finds a record holding only blank glosses and provenance empty', () => {
+    expect(isEmptyTokenAnalysis(analysis({ gloss: { en: ' ' }, confidence: 'high' }))).toBe(true);
+  });
+
+  it.each([
+    ['a gloss', { gloss: { en: 'at' } }],
+    ['morphemes', { morphemes: [{ id: 'm-1', form: 'in', writingSystem: 'en' }] }],
+    ['a part of speech', { pos: 'prep' }],
+    ['features', { features: { case: 'loc' } }],
+    ['a gloss sense', { glossSenseRef: { authority: 'fwlite', senseId: 's-1' } }],
+  ])('finds a record holding %s not empty', (_field, fields) => {
+    expect(isEmptyTokenAnalysis(analysis(fields))).toBe(false);
+  });
+});
+
+describe('clearAnalysisGloss', () => {
+  it('clears one language, keeping the others and the sense', () => {
+    const record = analysis({
+      gloss: { en: 'at', fr: 'à' },
+      glossSenseRef: { authority: 'fwlite', senseId: 's-1' },
+    });
+
+    clearAnalysisGloss(record, 'en');
+
+    expect(record).toStrictEqual(
+      analysis({ gloss: { fr: 'à' }, glossSenseRef: { authority: 'fwlite', senseId: 's-1' } }),
+    );
+  });
+
+  it('drops the gloss and the sense once no language holds usable text', () => {
+    const record = analysis({
+      gloss: { en: 'at', fr: ' ' },
+      glossSenseRef: { authority: 'fwlite', senseId: 's-1' },
+    });
+
+    clearAnalysisGloss(record, 'en');
+
+    expect(record).toStrictEqual(analysis());
+  });
+
+  it('drops a sense left with no gloss at all', () => {
+    const record = analysis({ glossSenseRef: { authority: 'fwlite', senseId: 's-1' } });
+
+    clearAnalysisGloss(record, 'en');
+
+    expect(record).toStrictEqual(analysis());
+  });
+});
diff --git a/src/main.ts b/src/main.ts
index e1a6953a2..abc254b1a 100644
--- a/src/main.ts
+++ b/src/main.ts
@@ -11,8 +11,10 @@ import type { ProjectConfig } from 'interlinearizer';
 import { formatReplacementString, type LocalizeKey } from 'platform-bible-utils';
 import interlinearizerReact from './interlinearizer.web-view?inline';
 import interlinearizerStyles from './interlinearizer.web-view.scss?inline';
-import { AnalysisSessions } from './services/analysisSessions';
+import { AnalysisSessions, type Session } from './services/analysisSessions';
 import * as bookService from './services/bookService';
+import type { ChangeBuffer } from './services/commands/changeBuffer';
+import * as tokenCommands from './services/commands/tokenCommands';
 import { readHostPerf, setHostPerfMarks } from './services/hostPerf';
 import * as projectStorage from './services/projectStorage';
 import * as pt9ImportService from './services/pt9ImportService';
@@ -825,6 +827,80 @@ async function checkIndexes(sessionId: string): Promise<string> {
   }
 }
 
+/**
+ * Runs `command` as one edit of a session's analysis.
+ *
+ * @returns The changes it applied, as JSON.
+ * @throws If the session is read-only or not open, or the edit is refused or fails. The error is
+ *   logged before rethrowing.
+ */
+async function runSessionEdit(
+  sessionId: string,
+  intent: string,
+  command: (buffer: ChangeBuffer, session: Session) => Promise<void>,
+): Promise<string> {
+  try {
+    return JSON.stringify(await sessions.edit(sessionId, intent, command));
+  } catch (e) {
+    logger.error(`Interlinearizer: failed to ${intent} in session ${sessionId}`, e);
+    throw e;
+  }
+}
+
+/** Ids a new record or link would take, and the time an edit lands. */
+function editStamp() {
+  return {
+    analysisId: crypto.randomUUID(),
+    linkId: crypto.randomUUID(),
+    now: new Date().toISOString(),
+  };
+}
+
+/**
+ * Writes a token's gloss in the session's analysis language; a blank value clears it.
+ *
+ * @returns The changes it applied, as JSON.
+ * @throws As {@link runSessionEdit} does.
+ */
+function writeGloss(
+  sessionId: string,
+  tokenRef: string,
+  surfaceText: string,
+  value: string,
+): Promise<string> {
+  return runSessionEdit(sessionId, 'writeGloss', (buffer, session) =>
+    tokenCommands.writeGloss(buffer, {
+      ...editStamp(),
+      tokenRef,
+      surfaceText,
+      value,
+      analysisLanguage: session.analysisLanguage,
+    }),
+  );
+}
+
+/**
+ * Approves a stored token analysis for a token, in place of any approval it held.
+ *
+ * @returns The changes it applied, as JSON.
+ * @throws As {@link runSessionEdit} does.
+ */
+function approveAnalysisForToken(
+  sessionId: string,
+  tokenRef: string,
+  surfaceText: string,
+  analysisId: string,
+): Promise<string> {
+  return runSessionEdit(sessionId, 'approveAnalysisForToken', (buffer) =>
+    tokenCommands.approveAnalysisForToken(buffer, {
+      ...editStamp(),
+      tokenRef,
+      surfaceText,
+      analysisId,
+    }),
+  );
+}
+
 /**
  * Returns a summary of every interlinearizer project for the given source project as a JSON string.
  * The WebView deserializes this to populate its project picker and to decide whether to prompt
@@ -1430,6 +1506,70 @@ export async function activate(context: ExecutionActivationContext): Promise<voi
     },
   );
 
+  /** The parameters naming the token a token edit acts on. */
+  const tokenParams = [
+    {
+      name: 'tokenRef',
+      required: true,
+      summary: 'Token.ref of the token edited',
+      schema: { type: 'string' },
+    },
+    {
+      name: 'surfaceText',
+      required: true,
+      summary: "The token's current surface text",
+      schema: { type: 'string' },
+    },
+  ] as const;
+
+  const editResult = {
+    name: 'return value',
+    summary: 'JSON-stringified ChangeSet the edit applied',
+    schema: { type: 'string' },
+  } as const;
+
+  const writeGlossCommandRegistration = await papi.commands.registerCommand(
+    'interlinearizer.writeGloss',
+    writeGloss,
+    {
+      method: {
+        summary: "Write a token's gloss in a session's analysis language; a blank value clears it",
+        params: [
+          sessionIdParam,
+          ...tokenParams,
+          {
+            name: 'value',
+            required: true,
+            summary: 'The gloss',
+            schema: { type: 'string' },
+          },
+        ],
+        result: editResult,
+      },
+    },
+  );
+
+  const approveAnalysisForTokenCommandRegistration = await papi.commands.registerCommand(
+    'interlinearizer.approveAnalysisForToken',
+    approveAnalysisForToken,
+    {
+      method: {
+        summary: 'Approve a stored token analysis for a token, in place of any approval it held',
+        params: [
+          sessionIdParam,
+          ...tokenParams,
+          {
+            name: 'analysisId',
+            required: true,
+            summary: 'Id of the stored token analysis to approve',
+            schema: { type: 'string' },
+          },
+        ],
+        result: editResult,
+      },
+    },
+  );
+
   const checkIndexesCommandRegistration = await papi.commands.registerCommand(
     'interlinearizer.checkIndexes',
     checkIndexes,
@@ -1823,6 +1963,8 @@ export async function activate(context: ExecutionActivationContext): Promise<voi
     undoEditCommandRegistration,
     redoEditCommandRegistration,
     checkIndexesCommandRegistration,
+    writeGlossCommandRegistration,
+    approveAnalysisForTokenCommandRegistration,
     setPerfMarksCommandRegistration,
     readPerfCommandRegistration,
     updateProjectMetadataCommandRegistration,
diff --git a/src/services/analysisSessions.ts b/src/services/analysisSessions.ts
index 964ed062a..b84b46ddd 100644
--- a/src/services/analysisSessions.ts
+++ b/src/services/analysisSessions.ts
@@ -1,7 +1,10 @@
 import type { AnalysisRepository, ChangeSet } from '../types/analysis-repository';
 import { ReadOnlyAnalysisError } from '../types/read-only-analysis-error';
 import type { InterlinearProjectSummary } from '../types/interlinear-project-summary';
+import { isEmptyChangeSet } from '../utils/change-set';
 import { analysisHasFreeTranslations } from '../utils/free-translations';
+import { assertApprovalRule } from './commands/approvalRule';
+import { ChangeBuffer } from './commands/changeBuffer';
 import { EditHistory } from './editHistory';
 
 /** BCP 47 tag for a language that cannot be determined. */
@@ -201,6 +204,35 @@ export class AnalysisSessions {
     return this.run(sessionId, edit);
   }
 
+  /**
+   * Runs `command` as one edit of the session's analysis, in the session's turn. What it stages
+   * applies as one undo step, marking the draft dirty; a command staging nothing applies nothing.
+   *
+   * @returns The changes applied, naming `intent`.
+   * @throws {ReadOnlyAnalysisError} If the session is read-only.
+   * @throws {ApprovalRuleError} If the changes would give a token or segment a second approved
+   *   link; nothing is applied.
+   * @throws {Error} If the session is not open.
+   * @throws Whatever the command or applying its changes throws; nothing is applied.
+   */
+  edit(
+    sessionId: string,
+    intent: string,
+    command: (buffer: ChangeBuffer, session: Session) => Promise<void>,
+  ): Promise<ChangeSet> {
+    return this.runEdit(sessionId, async (session) => {
+      const buffer = new ChangeBuffer(session.repository);
+      await command(buffer, session);
+      const changes = buffer.toChangeSet(intent);
+      if (isEmptyChangeSet(changes)) return changes;
+      await assertApprovalRule(buffer, session.repository);
+      const scope = await session.repository.getScope();
+      if (!scope.dirty) changes.scope = { ...scope, dirty: true };
+      await session.history.apply(changes);
+      return changes;
+    });
+  }
+
   /**
    * Reverts the session's latest edit not yet undone.
    *
diff --git a/src/services/commands/approvalRule.ts b/src/services/commands/approvalRule.ts
new file mode 100644
index 000000000..e0477069d
--- /dev/null
+++ b/src/services/commands/approvalRule.ts
@@ -0,0 +1,69 @@
+import type { AnalysisRepository } from '../../types/analysis-repository';
+import type { ChangeBuffer } from './changeBuffer';
+
+/** Thrown by an edit that would give a token or segment a second approved link. */
+export class ApprovalRuleError extends Error {
+  /** The token refs and segment ids the edit would leave holding several approved links. */
+  readonly places: readonly string[];
+
+  constructor(places: readonly string[]) {
+    super(`Interlinearizer: an edit would approve several analyses at ${places.join(', ')}`);
+    this.name = 'ApprovalRuleError';
+    this.places = places;
+  }
+}
+
+/** How many approved links each place holds, placing each link by `placeOf`. */
+function approvedCounts<Link extends { status: string }>(
+  links: readonly Link[],
+  placeOf: (link: Link) => string,
+): Map<string, number> {
+  const counts = new Map<string, number>();
+  links.forEach((link) => {
+    if (link.status !== 'approved') return;
+    counts.set(placeOf(link), (counts.get(placeOf(link)) ?? 0) + 1);
+  });
+  return counts;
+}
+
+/** The places where `after` holds more than one approved link, and more than `before` held. */
+function breaches<Link extends { status: string }>(
+  before: readonly Link[],
+  after: readonly Link[],
+  placeOf: (link: Link) => string,
+): string[] {
+  const held = approvedCounts(before, placeOf);
+  return [...approvedCounts(after, placeOf)].flatMap(([place, count]) =>
+    count > 1 && count > (held.get(place) ?? 0) ? [place] : [],
+  );
+}
+
+/**
+ * Refuses the changes staged in `buffer` over `repository` when they would leave a token or segment
+ * holding more approved links than one, and more than it held before them. A place the stored
+ * analysis already breaches is left to the edits that repair it.
+ *
+ * @throws {ApprovalRuleError} If the changes breach the rule anywhere.
+ */
+export async function assertApprovalRule(
+  buffer: ChangeBuffer,
+  repository: AnalysisRepository,
+): Promise<void> {
+  const tokenRefs = [
+    ...new Set(buffer.touched('tokenAnalysisLinks').map(({ token }) => token.tokenRef)),
+  ];
+  const segmentIds = [...new Set(buffer.touched('segmentAnalysisLinks').map((l) => l.segmentId))];
+  const found = [
+    ...breaches(
+      (await repository.findLinksByToken(tokenRefs)).tokenAnalysisLinks,
+      (await buffer.findLinksByToken(tokenRefs)).tokenAnalysisLinks,
+      ({ token }) => token.tokenRef,
+    ),
+    ...breaches(
+      await repository.findLinksBySegment(segmentIds),
+      await buffer.findLinksBySegment(segmentIds),
+      ({ segmentId }) => segmentId,
+    ),
+  ];
+  if (found.length > 0) throw new ApprovalRuleError(found);
+}
diff --git a/src/services/commands/changeBuffer.ts b/src/services/commands/changeBuffer.ts
new file mode 100644
index 000000000..5a5392fa5
--- /dev/null
+++ b/src/services/commands/changeBuffer.ts
@@ -0,0 +1,214 @@
+import type {
+  PhraseAnalysis,
+  SegmentAnalysis,
+  SegmentAnalysisLink,
+  TextAnalysis,
+  TokenAnalysis,
+} from 'interlinearizer';
+import type { AnalysisLinks, AnalysisRepository, ChangeSet } from '../../types/analysis-repository';
+import { normalizeSurfaceForm } from '../../utils/analysis-identity';
+import { jsonCopy } from '../../utils/json-copy';
+
+/** A record kind, named as {@link TextAnalysis} names its list. */
+export type RecordKind = keyof TextAnalysis;
+
+/** A record of one kind. */
+export type RecordOf<Kind extends RecordKind> = TextAnalysis[Kind][number];
+
+/** One kind's staged changes. */
+type Staged<T> = {
+  /** Records to store, by id. */
+  puts: Map<string, T>;
+  /** Records to remove, as they stood before the removal, by id. */
+  deletes: Map<string, T>;
+  /** Ids of the staged puts that no stored record shares, so removing one stages nothing. */
+  created: Set<string>;
+};
+
+function emptyStaged<T>(): Staged<T> {
+  return { puts: new Map(), deletes: new Map(), created: new Set() };
+}
+
+/**
+ * Changes a command stages before they apply, over a repository it reads through. Every read
+ * answers as the repository would once the staged changes applied, and hands out copies the command
+ * may change before staging them.
+ */
+export class ChangeBuffer {
+  private readonly repository: AnalysisRepository;
+
+  private readonly staged: { [Kind in RecordKind]: Staged<RecordOf<Kind>> } = {
+    segmentAnalyses: emptyStaged(),
+    segmentAnalysisLinks: emptyStaged(),
+    tokenAnalyses: emptyStaged(),
+    tokenAnalysisLinks: emptyStaged(),
+    phraseAnalyses: emptyStaged(),
+    phraseAnalysisLinks: emptyStaged(),
+  };
+
+  constructor(repository: AnalysisRepository) {
+    this.repository = repository;
+  }
+
+  /** The token analyses stored under `ids` once the staged changes apply. */
+  async getTokenAnalyses(ids: string[]): Promise<TokenAnalysis[]> {
+    const wanted = new Set(ids);
+    const stored = await this.repository.getTokenAnalyses(ids);
+    return this.overlay('tokenAnalyses', stored, ({ id }) => wanted.has(id));
+  }
+
+  /** The phrase analyses stored under `ids` once the staged changes apply. */
+  async getPhraseAnalyses(ids: string[]): Promise<PhraseAnalysis[]> {
+    const wanted = new Set(ids);
+    const stored = await this.repository.getPhraseAnalyses(ids);
+    return this.overlay('phraseAnalyses', stored, ({ id }) => wanted.has(id));
+  }
+
+  /** The segment analyses stored under `ids` once the staged changes apply. */
+  async getSegmentAnalyses(ids: string[]): Promise<SegmentAnalysis[]> {
+    const wanted = new Set(ids);
+    const stored = await this.repository.getSegmentAnalyses(ids);
+    return this.overlay('segmentAnalyses', stored, ({ id }) => wanted.has(id));
+  }
+
+  /**
+   * The token links on the tokens `tokenRefs` names, and the phrase links touching any of them,
+   * once the staged changes apply.
+   */
+  async findLinksByToken(
+    tokenRefs: string[],
+  ): Promise<Pick<AnalysisLinks, 'tokenAnalysisLinks' | 'phraseAnalysisLinks'>> {
+    const wanted = new Set(tokenRefs);
+    const stored = await this.repository.findLinksByToken(tokenRefs);
+    return {
+      tokenAnalysisLinks: this.overlay('tokenAnalysisLinks', stored.tokenAnalysisLinks, (link) =>
+        wanted.has(link.token.tokenRef),
+      ),
+      phraseAnalysisLinks: this.overlay('phraseAnalysisLinks', stored.phraseAnalysisLinks, (link) =>
+        link.tokens.some(({ tokenRef }) => wanted.has(tokenRef)),
+      ),
+    };
+  }
+
+  /** The segment links on the segments `segmentIds` names once the staged changes apply. */
+  async findLinksBySegment(segmentIds: string[]): Promise<SegmentAnalysisLink[]> {
+    const wanted = new Set(segmentIds);
+    const stored = await this.repository.findLinksBySegment(segmentIds);
+    return this.overlay('segmentAnalysisLinks', stored, (link) => wanted.has(link.segmentId));
+  }
+
+  /** The links of every kind to the analyses `analysisIds` names once the staged changes apply. */
+  async findLinksToAnalyses(analysisIds: string[]): Promise<AnalysisLinks> {
+    const wanted = new Set(analysisIds);
+    const stored = await this.repository.findLinksToAnalyses(analysisIds);
+    const linksTo = ({ analysisId }: { analysisId: string }) => wanted.has(analysisId);
+    return {
+      tokenAnalysisLinks: this.overlay('tokenAnalysisLinks', stored.tokenAnalysisLinks, linksTo),
+      phraseAnalysisLinks: this.overlay('phraseAnalysisLinks', stored.phraseAnalysisLinks, linksTo),
+      segmentAnalysisLinks: this.overlay(
+        'segmentAnalysisLinks',
+        stored.segmentAnalysisLinks,
+        linksTo,
+      ),
+    };
+  }
+
+  /**
+   * The token analyses whose surface text normalizes to one of `normalizedForms` once the staged
+   * changes apply.
+   */
+  async findTokenAnalysesByForm(normalizedForms: string[]): Promise<TokenAnalysis[]> {
+    const wanted = new Set(normalizedForms);
+    const stored = await this.repository.findTokenAnalysesByForm(normalizedForms);
+    return this.overlay('tokenAnalyses', stored, ({ surfaceText }) =>
+      wanted.has(normalizeSurfaceForm(surfaceText)),
+    );
+  }
+
+  /**
+   * The phrase analyses whose surface text normalizes to one of `normalizedForms` once the staged
+   * changes apply.
+   */
+  async findPhraseAnalysesByForm(normalizedForms: string[]): Promise<PhraseAnalysis[]> {
+    const wanted = new Set(normalizedForms);
+    const stored = await this.repository.findPhraseAnalysesByForm(normalizedForms);
+    return this.overlay('phraseAnalyses', stored, ({ surfaceText }) =>
+      wanted.has(normalizeSurfaceForm(surfaceText)),
+    );
+  }
+
+  /** Stages a new record of `kind`, under an id no stored record has. */
+  create<Kind extends RecordKind>(kind: Kind, record: RecordOf<Kind>): void {
+    this.stagedOf(kind).created.add(record.id);
+    this.put(kind, record);
+  }
+
+  /** Stages `record` to be stored whole under its id. */
+  put<Kind extends RecordKind>(kind: Kind, record: RecordOf<Kind>): void {
+    const staged = this.stagedOf(kind);
+    staged.deletes.delete(record.id);
+    staged.puts.set(record.id, jsonCopy(record));
+  }
+
+  /** Stages `record`'s removal; removing one the buffer created stages nothing for it. */
+  delete<Kind extends RecordKind>(kind: Kind, record: RecordOf<Kind>): void {
+    const staged = this.stagedOf(kind);
+    staged.puts.delete(record.id);
+    if (staged.created.delete(record.id)) return;
+    staged.deletes.set(record.id, jsonCopy(record));
+  }
+
+  /** Every record of `kind` the staged changes put or remove, as each stood before or will stand. */
+  touched<Kind extends RecordKind>(kind: Kind): RecordOf<Kind>[] {
+    const staged = this.stagedOf(kind);
+    return [...staged.puts.values(), ...staged.deletes.values()].map((record) => jsonCopy(record));
+  }
+
+  /** The staged changes as one change set; a kind with nothing staged is left out. */
+  toChangeSet(intent: string): ChangeSet {
+    const changes: ChangeSet = { intent };
+    const kinds: RecordKind[] = [
+      'segmentAnalyses',
+      'segmentAnalysisLinks',
+      'tokenAnalyses',
+      'tokenAnalysisLinks',
+      'phraseAnalyses',
+      'phraseAnalysisLinks',
+    ];
+    kinds.forEach((kind) => this.collect(changes, kind));
+    return changes;
+  }
+
+  /**
+   * `stored` as it stands once the staged changes of `kind` apply, keeping only the records
+   * `matches` accepts; `stored` must hold every stored record `matches` accepts.
+   */
+  private overlay<Kind extends RecordKind>(
+    kind: Kind,
+    stored: readonly RecordOf<Kind>[],
+    matches: (record: RecordOf<Kind>) => boolean,
+  ): RecordOf<Kind>[] {
+    const staged = this.stagedOf(kind);
+    const latest = new Map<string, RecordOf<Kind>>();
+    stored.forEach((record) => {
+      if (!staged.deletes.has(record.id)) latest.set(record.id, record);
+    });
+    staged.puts.forEach((record, id) => latest.set(id, record));
+    return [...latest.values()].filter(matches).map((record) => jsonCopy(record));
+  }
+
+  private collect<Kind extends RecordKind>(changes: ChangeSet, kind: Kind): void {
+    const { puts, deletes } = this.stagedOf(kind);
+    if (puts.size === 0 && deletes.size === 0) return;
+    Object.assign(changes, {
+      [kind]: {
+        puts: [...puts.values()].map((record) => jsonCopy(record)),
+        deletes: [...deletes.keys()],
+      },
+    });
+  }
+
+  private stagedOf<Kind extends RecordKind>(kind: Kind): Staged<RecordOf<Kind>> {
+    return this.staged[kind];
+  }
+}
diff --git a/src/services/commands/tokenCommands.ts b/src/services/commands/tokenCommands.ts
new file mode 100644
index 000000000..a1921ad4e
--- /dev/null
+++ b/src/services/commands/tokenCommands.ts
@@ -0,0 +1,291 @@
+import type { TokenAnalysis, TokenAnalysisLink } from 'interlinearizer';
+import { analysesAreIdentical, normalizeSurfaceForm } from '../../utils/analysis-identity';
+import { preferredLink, preferredPayload } from '../../utils/pick-rules';
+import { clearAnalysisGloss, isEmptyTokenAnalysis } from '../../utils/token-analysis-content';
+import type { ChangeBuffer } from './changeBuffer';
+
+/** Where and when a token edit lands. */
+type TokenEdit = {
+  /** `Token.ref` of the token edited. */
+  tokenRef: string;
+  /** The token's current surface text, refreshed on the records the edit touches. */
+  surfaceText: string;
+  /** ISO 8601 time of the edit, stamped on the records it touches. */
+  now: string;
+  /** Id a new link takes, spent only when the edit makes one. */
+  linkId: string;
+};
+
+/** What writing a token's gloss needs. */
+export type WriteGlossRequest = TokenEdit & {
+  /** The gloss; blank clears the token's gloss in `analysisLanguage`. */
+  value: string;
+  /** BCP 47 tag of the language the gloss is written in. */
+  analysisLanguage: string;
+  /** Id a new token analysis takes, spent only when the write makes one. */
+  analysisId: string;
+};
+
+/** What approving a stored analysis for a token needs. */
+export type ApproveAnalysisRequest = TokenEdit & {
+  /** The stored token analysis to approve. */
+  analysisId: string;
+};
+
+/**
+ * The token's approved link an approval tie picks, with its payload. Approved links naming no
+ * stored payload are removed first, so they never persist or crowd the pick.
+ */
+async function resolveApprovedAnalysis(
+  buffer: ChangeBuffer,
+  tokenRef: string,
+): Promise<{ link: TokenAnalysisLink; analysis: TokenAnalysis } | undefined> {
+  const { tokenAnalysisLinks } = await buffer.findLinksByToken([tokenRef]);
+  const approved = tokenAnalysisLinks.filter(({ status }) => status === 'approved');
+  const payloads = new Map(
+    (await buffer.getTokenAnalyses(approved.map(({ analysisId }) => analysisId))).map(
+      (analysis) => [analysis.id, analysis],
+    ),
+  );
+  approved
+    .filter(({ analysisId }) => !payloads.has(analysisId))
+    .forEach((orphan) => buffer.delete('tokenAnalysisLinks', orphan));
+  const link = preferredLink(approved.filter(({ analysisId }) => payloads.has(analysisId)));
+  const analysis = link && payloads.get(link.analysisId);
+  return link && analysis ? { link, analysis } : undefined;
+}
+
+/** Whether a token other than `link`'s links the payload `analysisId`, at any status. */
+async function isSharedByOtherTokens(
+  buffer: ChangeBuffer,
+  link: TokenAnalysisLink,
+  analysisId: string,
+): Promise<boolean> {
+  const { tokenAnalysisLinks } = await buffer.findLinksToAnalyses([analysisId]);
+  return tokenAnalysisLinks.some(({ token }) => token.tokenRef !== link.token.tokenRef);
+}
+
+/**
+ * Moves `link` onto a private copy of its shared payload, so an edit aimed at its token leaves the
+ * others reading what they did. The copy is dated by the edit, being a record of its own.
+ *
+ * @returns The copy, staged; `link` is repointed but left for the caller to stage.
+ */
+function forkSharedAnalysis(
+  buffer: ChangeBuffer,
+  link: TokenAnalysisLink,
+  analysis: TokenAnalysis,
+  forkId: string,
+  now: string,
+): TokenAnalysis {
+  const fork: TokenAnalysis = { ...analysis, id: forkId, createdAt: now, updatedAt: now };
+  buffer.create('tokenAnalyses', fork);
+  link.analysisId = forkId;
+  return fork;
+}
+
+/**
+ * Approves the non-approved link `tokenRef` holds to `analysisId`, so a token taking on a record it
+ * was offered keeps one link to it. The link keeps its creation date and `confidence`.
+ *
+ * @returns The approved link, staged, or `undefined` when the token holds no such link.
+ */
+async function approveHeldLink(
+  buffer: ChangeBuffer,
+  tokenRef: string,
+  analysisId: string,
+  surfaceText: string,
+  now: string,
+): Promise<TokenAnalysisLink | undefined> {
+  const { tokenAnalysisLinks } = await buffer.findLinksByToken([tokenRef]);
+  const held = preferredLink(
+    tokenAnalysisLinks.filter((l) => l.status !== 'approved' && l.analysisId === analysisId),
+  );
+  if (!held) return undefined;
+  held.status = 'approved';
+  held.token.surfaceText = surfaceText;
+  held.updatedAt = now;
+  buffer.put('tokenAnalysisLinks', held);
+  return held;
+}
+
+/** Removes the payload once no link of any status names it. */
+async function reclaimIfUnlinked(buffer: ChangeBuffer, analysis: TokenAnalysis): Promise<void> {
+  const { tokenAnalysisLinks } = await buffer.findLinksToAnalyses([analysis.id]);
+  if (tokenAnalysisLinks.length === 0) buffer.delete('tokenAnalyses', analysis);
+}
+
+/**
+ * Leaves each token holding one link to `analysisId` where it held several. The token keeps its
+ * approved link over any other, then the one an approval tie picks, and the survivor keeps the
+ * token's first annotation date.
+ */
+async function coalesceLinksPerToken(buffer: ChangeBuffer, analysisId: string): Promise<void> {
+  const { tokenAnalysisLinks } = await buffer.findLinksToAnalyses([analysisId]);
+  const byToken = new Map<string, TokenAnalysisLink[]>();
+  tokenAnalysisLinks.forEach((link) => {
+    byToken.set(link.token.tokenRef, [...(byToken.get(link.token.tokenRef) ?? []), link]);
+  });
+  byToken.forEach((links) => {
+    const kept =
+      preferredLink(links.filter(({ status }) => status === 'approved')) ?? preferredLink(links);
+    /* v8 ignore next -- every token's group holds a link */
+    if (!kept) return;
+    const createdAt = links.reduce(
+      (earliest, link) => (link.createdAt < earliest ? link.createdAt : earliest),
+      kept.createdAt,
+    );
+    links.forEach((link) => {
+      if (link !== kept) buffer.delete('tokenAnalysisLinks', link);
+    });
+    if (kept.createdAt !== createdAt) buffer.put('tokenAnalysisLinks', { ...kept, createdAt });
+  });
+}
+
+/**
+ * Folds the just-edited payload into a content-identical one where the edit made one, so an edit
+ * never leaves the duplicate a first write's find-or-create avoids. Every link to the edited
+ * payload moves to the survivor, which keeps its own timestamps, and a token linking both keeps one
+ * link. The survivor's breakdown stays stale only when both payloads' were.
+ */
+async function mergeIntoIdenticalPayload(
+  buffer: ChangeBuffer,
+  analysis: TokenAnalysis,
+  now: string,
+): Promise<void> {
+  const candidates = await buffer.findTokenAnalysesByForm([
+    normalizeSurfaceForm(analysis.surfaceText),
+  ]);
+  const other = preferredPayload(
+    candidates.filter((ta) => ta.id !== analysis.id && analysesAreIdentical(ta, analysis)),
+  );
+  if (!other) return;
+  if (other.morphemesStale && !analysis.morphemesStale) {
+    delete other.morphemesStale;
+    other.updatedAt = now;
+    buffer.put('tokenAnalyses', other);
+  }
+  const { tokenAnalysisLinks } = await buffer.findLinksToAnalyses([analysis.id]);
+  tokenAnalysisLinks.forEach((link) =>
+    buffer.put('tokenAnalysisLinks', { ...link, analysisId: other.id }),
+  );
+  await coalesceLinksPerToken(buffer, other.id);
+  buffer.delete('tokenAnalyses', analysis);
+}
+
+/**
+ * Links a token to an approved payload holding `analysis`'s content, sharing a content-identical
+ * stored one where there is one and staging `analysis` otherwise. A non-approved link the token
+ * holds to the shared payload is approved rather than joined by a second.
+ */
+async function appendApprovedAnalysis(
+  buffer: ChangeBuffer,
+  analysis: TokenAnalysis,
+  { tokenRef, now, linkId }: TokenEdit,
+): Promise<void> {
+  const candidates = await buffer.findTokenAnalysesByForm([
+    normalizeSurfaceForm(analysis.surfaceText),
+  ]);
+  const existing = preferredPayload(candidates.filter((ta) => analysesAreIdentical(ta, analysis)));
+  if (!existing) buffer.create('tokenAnalyses', analysis);
+  else if (await approveHeldLink(buffer, tokenRef, existing.id, analysis.surfaceText, now)) return;
+  buffer.create('tokenAnalysisLinks', {
+    id: linkId,
+    analysisId: existing?.id ?? analysis.id,
+    createdAt: now,
+    updatedAt: now,
+    status: 'approved',
+    token: { tokenRef, surfaceText: analysis.surfaceText },
+  });
+}
+
+/**
+ * Stages writing a token's gloss. The edit is per token: a payload other tokens share is forked
+ * first. An edit that makes the payload identical to another folds it in. A token with no approved
+ * analysis takes a content-identical stored one, or a new one. A blank value clears the gloss, and
+ * a payload left empty goes once nothing links it; a blank write to a token with no approved
+ * analysis stages nothing.
+ */
+export async function writeGloss(buffer: ChangeBuffer, request: WriteGlossRequest): Promise<void> {
+  const { tokenRef, surfaceText, value, analysisLanguage: lang, analysisId, now } = request;
+  const isBlank = value.trim() === '';
+
+  const resolved = await resolveApprovedAnalysis(buffer, tokenRef);
+  if (resolved) {
+    const { link, analysis } = resolved;
+    const target = (await isSharedByOtherTokens(buffer, link, analysis.id))
+      ? forkSharedAnalysis(buffer, link, analysis, analysisId, now)
+      : analysis;
+    target.surfaceText = surfaceText;
+    target.updatedAt = now;
+    link.token.surfaceText = surfaceText;
+    link.updatedAt = now;
+    if (isBlank) {
+      clearAnalysisGloss(target, lang);
+      if (isEmptyTokenAnalysis(target)) {
+        buffer.delete('tokenAnalysisLinks', link);
+        const { tokenAnalysisLinks } = await buffer.findLinksToAnalyses([target.id]);
+        if (tokenAnalysisLinks.length === 0) buffer.delete('tokenAnalyses', target);
+        else buffer.put('tokenAnalyses', target);
+        return;
+      }
+    } else {
+      target.gloss = { ...target.gloss, [lang]: value };
+      delete target.glossSenseRef;
+    }
+    buffer.put('tokenAnalyses', target);
+    buffer.put('tokenAnalysisLinks', link);
+    await mergeIntoIdenticalPayload(buffer, target, now);
+    return;
+  }
+
+  if (isBlank) return;
+  await appendApprovedAnalysis(
+    buffer,
+    { id: analysisId, createdAt: now, updatedAt: now, surfaceText, gloss: { [lang]: value } },
+    request,
+  );
+}
+
+/**
+ * Stages approving the stored payload `analysisId` for a token, in place of any approval it held.
+ * The payload that approval named goes once nothing links it. A token holding a non-approved link
+ * to the payload has that link approved, keeping the earlier creation date of the two; one holding
+ * neither gets a new link. It stages nothing for a payload not stored, or one already approved for
+ * the token.
+ */
+export async function approveAnalysisForToken(
+  buffer: ChangeBuffer,
+  { tokenRef, surfaceText, analysisId, now, linkId }: ApproveAnalysisRequest,
+): Promise<void> {
+  if ((await buffer.getTokenAnalyses([analysisId])).length === 0) return;
+  const resolved = await resolveApprovedAnalysis(buffer, tokenRef);
+  if (resolved?.link.analysisId === analysisId) return;
+
+  const pending = await approveHeldLink(buffer, tokenRef, analysisId, surfaceText, now);
+  if (pending) {
+    if (resolved) {
+      if (resolved.link.createdAt < pending.createdAt) {
+        buffer.put('tokenAnalysisLinks', { ...pending, createdAt: resolved.link.createdAt });
+      }
+      buffer.delete('tokenAnalysisLinks', resolved.link);
+    }
+  } else if (resolved) {
+    const { link } = resolved;
+    link.analysisId = analysisId;
+    link.token.surfaceText = surfaceText;
+    link.updatedAt = now;
+    buffer.put('tokenAnalysisLinks', link);
+  } else {
+    buffer.create('tokenAnalysisLinks', {
+      id: linkId,
+      analysisId,
+      createdAt: now,
+      updatedAt: now,
+      status: 'approved',
+      token: { tokenRef, surfaceText },
+    });
+  }
+
+  if (resolved) await reclaimIfUnlinked(buffer, resolved.analysis);
+}
diff --git a/src/services/draftRepository.ts b/src/services/draftRepository.ts
index 8b4fb3c9a..2075e102f 100644
--- a/src/services/draftRepository.ts
+++ b/src/services/draftRepository.ts
@@ -23,7 +23,7 @@ import { applyChangeSet } from '../utils/change-set';
 import { jsonCopy } from '../utils/json-copy';
 import { perfTime, perfTimeAsync, perfTimeAsyncExcluding } from '../utils/perf-marks';
 import { AnalysisIndex } from './analysisIndex';
-import { IndexedRepository, type IndexedAnalysis } from './indexedRepository';
+import { IndexedRepository, type IndexedDraft } from './indexedRepository';
 import { draftAnalysisKey, draftJournalKey, draftKey } from './storageKeys';
 
 /**
@@ -136,7 +136,7 @@ export class DraftRepository extends IndexedRepository implements AnalysisReposi
    * index over its records. Dropped by every load and by every write but an apply, since each may
    * come from a caller holding another draft.
    */
-  private current: { draft: DraftProject; index: AnalysisIndex } | undefined;
+  private current: IndexedDraft | undefined;
 
   constructor(storage: KeyValueStorage, sourceProjectId: string, logger: WarningLogger) {
     super();
@@ -270,7 +270,7 @@ export class DraftRepository extends IndexedRepository implements AnalysisReposi
    *   is left as it was.
    */
   async apply(changes: ChangeSet): Promise<ApplyResult> {
-    const { draft: base, index } = await this.keptDraft();
+    const { draft: base, index } = await this.indexed();
     const copied = jsonCopy(changes);
     const { draft, inverse } = applyChangeSet(base, copied);
     await this.writeDraft(draft, undefined, { refuseUnreadable: true });
@@ -279,20 +279,8 @@ export class DraftRepository extends IndexedRepository implements AnalysisReposi
     return { inverse };
   }
 
-  protected async indexed(): Promise<AnalysisIndex> {
-    return (await this.keptDraft()).index;
-  }
-
-  protected keptIndex(): IndexedAnalysis | undefined {
-    return this.current && { analysis: this.current.draft.analysis, index: this.current.index };
-  }
-
-  /**
-   * The draft this instance keeps, loaded from storage first when it keeps none.
-   *
-   * @throws Whatever {@link exportAll} throws.
-   */
-  private async keptDraft(): Promise<{ draft: DraftProject; index: AnalysisIndex }> {
+  /** @throws Whatever {@link exportAll} throws. */
+  protected async indexed(): Promise<IndexedDraft> {
     if (!this.current) {
       const { draft } = await this.exportAll();
       this.current = { draft, index: new AnalysisIndex(draft.analysis) };
@@ -300,6 +288,10 @@ export class DraftRepository extends IndexedRepository implements AnalysisReposi
     return this.current;
   }
 
+  protected keptIndex(): IndexedDraft | undefined {
+    return this.current;
+  }
+
   /**
    * Saves `draft` as {@link replaceAll} describes.
    *
diff --git a/src/services/indexedRepository.ts b/src/services/indexedRepository.ts
index d8b774446..92569a54a 100644
--- a/src/services/indexedRepository.ts
+++ b/src/services/indexedRepository.ts
@@ -1,28 +1,31 @@
 import type {
   AssignmentStatus,
+  DraftProject,
   PhraseAnalysis,
   SegmentAnalysis,
   SegmentAnalysisLink,
-  TextAnalysis,
   TokenAnalysis,
 } from 'interlinearizer';
 import type {
   AnalysisLinks,
   AnalysisRepository,
   IndexDifference,
+  ScopeRecord,
 } from '../types/analysis-repository';
+import { scopeRecordOf } from '../utils/change-set';
 import { jsonCopy } from '../utils/json-copy';
 import type { AnalysisIndex } from './analysisIndex';
 
-/** An index, with the analysis whose records it is kept over. */
-export type IndexedAnalysis = {
-  analysis: TextAnalysis;
+/** An index, with the draft whose records it is kept over. */
+export type IndexedDraft = {
+  draft: DraftProject;
   index: AnalysisIndex;
 };
 
-/** The lookups of a repository that answers them from an {@link AnalysisIndex} over its records. */
+/** The reads of a repository that answers them from an {@link AnalysisIndex} over its records. */
 export abstract class IndexedRepository implements Pick<
   AnalysisRepository,
+  | 'getScope'
   | 'getTokenAnalyses'
   | 'getPhraseAnalyses'
   | 'getSegmentAnalyses'
@@ -34,6 +37,10 @@ export abstract class IndexedRepository implements Pick<
   | 'findPhraseAnalysesByForm'
   | 'checkIndexes'
 > {
+  async getScope(): Promise<ScopeRecord> {
+    return jsonCopy(scopeRecordOf((await this.indexed()).draft));
+  }
+
   getTokenAnalyses(ids: string[]): Promise<TokenAnalysis[]> {
     return this.query((index) => index.getTokenAnalyses(ids));
   }
@@ -75,21 +82,21 @@ export abstract class IndexedRepository implements Pick<
   /** Reports nothing while no index is kept. */
   async checkIndexes(): Promise<IndexDifference[]> {
     const kept = this.keptIndex();
-    return kept ? kept.index.differencesFrom(kept.analysis) : [];
+    return kept ? kept.index.differencesFrom(kept.draft.analysis) : [];
   }
 
   /** Answers `read` from the kept index, with copies of the records it finds. */
   private async query<T>(read: (index: AnalysisIndex) => T): Promise<T> {
-    return jsonCopy(read(await this.indexed()));
+    return jsonCopy(read((await this.indexed()).index));
   }
 
   /**
-   * The kept index, built over the stored records first when none is kept.
+   * The kept index and its draft, loaded from storage first when none is kept.
    *
    * @throws Whatever loading the stored records throws.
    */
-  protected abstract indexed(): Promise<AnalysisIndex>;
+  protected abstract indexed(): Promise<IndexedDraft>;
 
-  /** The kept index and the analysis it is kept over, or `undefined` when none is kept. */
-  protected abstract keptIndex(): IndexedAnalysis | undefined;
+  /** The kept index and the draft it is kept over, or `undefined` when none is kept. */
+  protected abstract keptIndex(): IndexedDraft | undefined;
 }
diff --git a/src/services/projectStorage.ts b/src/services/projectStorage.ts
index 185bf6ed0..519c97a6e 100644
--- a/src/services/projectStorage.ts
+++ b/src/services/projectStorage.ts
@@ -1133,6 +1133,7 @@ export function openDraftRepository(
     replaceAll: (draft, options) => counted((repository) => repository.replaceAll(draft, options)),
     markClean: () => queued((repository) => repository.markClean()),
     apply: (changes) => counted((repository) => repository.apply(changes)),
+    getScope: () => queued((repository) => repository.getScope()),
     getTokenAnalyses: (ids) => queued((repository) => repository.getTokenAnalyses(ids)),
     getPhraseAnalyses: (ids) => queued((repository) => repository.getPhraseAnalyses(ids)),
     getSegmentAnalyses: (ids) => queued((repository) => repository.getSegmentAnalyses(ids)),
diff --git a/src/services/pt9ImportRepository.ts b/src/services/pt9ImportRepository.ts
index 5a47ccddc..eacbede0a 100644
--- a/src/services/pt9ImportRepository.ts
+++ b/src/services/pt9ImportRepository.ts
@@ -8,7 +8,7 @@ import type {
 import { CURRENT_MODEL_VERSION } from '../types/model-version';
 import { ReadOnlyAnalysisError } from '../types/read-only-analysis-error';
 import { AnalysisIndex } from './analysisIndex';
-import { IndexedRepository, type IndexedAnalysis } from './indexedRepository';
+import { IndexedRepository, type IndexedDraft } from './indexedRepository';
 
 /**
  * A Paratext 9 import's analysis, read in a draft's shape. Only a sync replaces an import's
@@ -22,7 +22,7 @@ export class Pt9ImportRepository extends IndexedRepository implements AnalysisRe
   private readonly readProject: () => Promise<InterlinearProject | undefined>;
 
   /** The import as a lookup last read it, with the index over its records; dropped by every load. */
-  private loaded: IndexedAnalysis | undefined;
+  private loaded: IndexedDraft | undefined;
 
   /**
    * @param interlinearProjectId - Id of the project to read, which must be a Paratext 9 import.
@@ -75,15 +75,16 @@ export class Pt9ImportRepository extends IndexedRepository implements AnalysisRe
     throw this.readOnlyError();
   }
 
-  protected async indexed(): Promise<AnalysisIndex> {
+  /** @throws Whatever {@link exportAll} throws. */
+  protected async indexed(): Promise<IndexedDraft> {
     if (!this.loaded) {
-      const { analysis } = await this.readImport();
-      this.loaded = { analysis, index: new AnalysisIndex(analysis) };
+      const draft = await this.readImport();
+      this.loaded = { draft, index: new AnalysisIndex(draft.analysis) };
     }
-    return this.loaded.index;
+    return this.loaded;
   }
 
-  protected keptIndex(): IndexedAnalysis | undefined {
+  protected keptIndex(): IndexedDraft | undefined {
     return this.loaded;
   }
 
diff --git a/src/store/analysisSlice.ts b/src/store/analysisSlice.ts
index f2635e7b4..49e5b8e38 100644
--- a/src/store/analysisSlice.ts
+++ b/src/store/analysisSlice.ts
@@ -22,6 +22,7 @@ import {
 import { buildCatalogRows, type HeadingPlacement } from '../utils/analysis-query';
 import type { StaleFreeTranslation } from '../utils/stale-free-translations';
 import { isEmptyMultiString } from '../utils/multi-string';
+import { clearAnalysisGloss, isEmptyTokenAnalysis } from '../utils/token-analysis-content';
 import {
   preferredLink,
   preferredLinkByKey,
@@ -868,46 +869,6 @@ function writeGlossOntoAnalysis(
   mergeIntoIdenticalPayload(state, analysis, now);
 }
 
-/**
- * Determines whether a `TokenAnalysis` carries no analysis content, so a reducer that just emptied
- * one field can decide to drop the whole record instead of letting empty records accumulate in
- * storage. Checks every content field of the type — `gloss`, `morphemes`, `pos`, `features`, and
- * `glossSenseRef` — not only the field the caller emptied, so records carrying imported
- * morphosyntactic or lexicon data are never discarded by an unrelated edit. A gloss counts as empty
- * when it has no entries or every entry is blank, so a record left holding only whitespace glosses
- * (junk from clearing a gloss field) is treated the same as one with no gloss at all.
- *
- * Provenance fields (`confidence`, `producer`, `sourceUser`) are intentionally NOT treated as
- * content: they describe who/what produced an analysis, not an analysis worth keeping on their own.
- * A record holding only provenance and no glosses/morphemes/pos/features is therefore considered
- * empty and may be dropped when its last content field is cleared. This is a deliberate choice — if
- * a future workflow needs provenance-only records (e.g. imported parser metadata) to survive a
- * gloss clear, add the relevant fields to the check below.
- */
-function isEmptyTokenAnalysis(analysis: TokenAnalysis): boolean {
-  return (
-    isEmptyMultiString(analysis.gloss) &&
-    /* v8 ignore next -- the length===0 sub-branch needs an empty-but-defined morphemes array, which no caller produces */
-    (!analysis.morphemes || analysis.morphemes.length === 0) &&
-    analysis.pos === undefined &&
-    analysis.features === undefined &&
-    analysis.glossSenseRef === undefined
-  );
-}
-
-/**
- * Empties one language's gloss, dropping the gloss and the analysis-wide `glossSenseRef` once no
- * language is left holding usable text — a sibling left holding only whitespace counts for neither,
- * so the sense is never stranded on a gloss nothing renders.
- */
-function clearAnalysisGloss(analysis: TokenAnalysis, lang: string): void {
-  if (analysis.gloss) {
-    delete analysis.gloss[lang];
-    if (isEmptyMultiString(analysis.gloss)) delete analysis.gloss;
-  }
-  if (!analysis.gloss) delete analysis.glossSenseRef;
-}
-
 /**
  * The annotated forms a re-split to `forms` would strand: those whose morpheme carries a gloss or a
  * lexicon reference and which the new breakdown leaves no morpheme to hold, in the order the old
diff --git a/src/types/analysis-repository.ts b/src/types/analysis-repository.ts
index 355dcf100..c8c20f4cd 100644
--- a/src/types/analysis-repository.ts
+++ b/src/types/analysis-repository.ts
@@ -194,6 +194,13 @@ export interface AnalysisRepository {
    */
   apply(changes: ChangeSet): Promise<ApplyResult>;
 
+  /**
+   * The draft's own record, as {@link exportAll} would load it without its analysis.
+   *
+   * @throws Whatever {@link exportAll} throws.
+   */
+  getScope(): Promise<ScopeRecord>;
+
   /** The token analyses stored under `ids`; an id with none stored under it is skipped. */
   getTokenAnalyses(ids: string[]): Promise<TokenAnalysis[]>;
 
diff --git a/src/types/interlinearizer.d.ts b/src/types/interlinearizer.d.ts
index b7be3e07c..8355e47de 100644
--- a/src/types/interlinearizer.d.ts
+++ b/src/types/interlinearizer.d.ts
@@ -390,6 +390,34 @@ declare module 'papi-shared-types' {
      */
     'interlinearizer.checkIndexes': (sessionId: string) => Promise<string>;
 
+    /**
+     * Writes a token's gloss in a session's analysis language; a blank value clears it.
+     *
+     * @returns A JSON string of the changes it applied.
+     * @throws If the session is read-only or not open, or the edit is refused or fails (logged
+     *   before rethrowing).
+     */
+    'interlinearizer.writeGloss': (
+      sessionId: string,
+      tokenRef: string,
+      surfaceText: string,
+      value: string,
+    ) => Promise<string>;
+
+    /**
+     * Approves a stored token analysis for a token, in place of any approval it held.
+     *
+     * @returns A JSON string of the changes it applied.
+     * @throws If the session is read-only or not open, or the edit is refused or fails (logged
+     *   before rethrowing).
+     */
+    'interlinearizer.approveAnalysisForToken': (
+      sessionId: string,
+      tokenRef: string,
+      surfaceText: string,
+      analysisId: string,
+    ) => Promise<string>;
+
     /**
      * Turns the extension host's timing entries on or off, discarding any it holds. Off until
      * turned on.
diff --git a/src/utils/change-set.ts b/src/utils/change-set.ts
index 9d3ee463b..785c96dc3 100644
--- a/src/utils/change-set.ts
+++ b/src/utils/change-set.ts
@@ -7,6 +7,11 @@ export type AppliedChanges = {
   inverse: ChangeSet;
 };
 
+/** Whether `changes` change no record, the scope's record included. */
+export function isEmptyChangeSet(changes: ChangeSet): boolean {
+  return Object.keys(changes).every((key) => key === 'intent');
+}
+
 /** The draft's record, without its analysis. */
 // eslint-disable-next-line @typescript-eslint/no-unused-vars -- named only to leave it out
 export function scopeRecordOf({ analysis, ...scope }: DraftProject): ScopeRecord {
diff --git a/src/utils/token-analysis-content.ts b/src/utils/token-analysis-content.ts
new file mode 100644
index 000000000..81f65e855
--- /dev/null
+++ b/src/utils/token-analysis-content.ts
@@ -0,0 +1,42 @@
+import type { TokenAnalysis } from 'interlinearizer';
+import { isEmptyMultiString } from './multi-string';
+
+/**
+ * Determines whether a `TokenAnalysis` carries no analysis content, so an edit that just emptied
+ * one field can drop the whole record instead of letting empty records accumulate in storage.
+ * Checks every content field of the type — `gloss`, `morphemes`, `pos`, `features`, and
+ * `glossSenseRef` — not only the field the caller emptied, so records carrying imported
+ * morphosyntactic or lexicon data are never discarded by an unrelated edit. A gloss counts as empty
+ * when it has no entries or every entry is blank, so a record left holding only whitespace glosses
+ * (junk from clearing a gloss field) is treated the same as one with no gloss at all.
+ *
+ * Provenance fields (`confidence`, `producer`, `sourceUser`) are intentionally NOT treated as
+ * content: they describe who/what produced an analysis, not an analysis worth keeping on their own.
+ * A record holding only provenance and no glosses/morphemes/pos/features is therefore considered
+ * empty and may be dropped when its last content field is cleared. This is a deliberate choice — if
+ * a future workflow needs provenance-only records (e.g. imported parser metadata) to survive a
+ * gloss clear, add the relevant fields to the check below.
+ */
+export function isEmptyTokenAnalysis(analysis: TokenAnalysis): boolean {
+  return (
+    isEmptyMultiString(analysis.gloss) &&
+    /* v8 ignore next -- the length===0 sub-branch needs an empty-but-defined morphemes array, which no caller produces */
+    (!analysis.morphemes || analysis.morphemes.length === 0) &&
+    analysis.pos === undefined &&
+    analysis.features === undefined &&
+    analysis.glossSenseRef === undefined
+  );
+}
+
+/**
+ * Empties one language's gloss, dropping the gloss and the analysis-wide `glossSenseRef` once no
+ * language is left holding usable text — a sibling left holding only whitespace counts for neither,
+ * so the sense is never stranded on a gloss nothing renders.
+ */
+export function clearAnalysisGloss(analysis: TokenAnalysis, lang: string): void {
+  if (analysis.gloss) {
+    delete analysis.gloss[lang];
+    if (isEmptyMultiString(analysis.gloss)) delete analysis.gloss;
+  }
+  if (!analysis.gloss) delete analysis.glossSenseRef;
+}

From 57d0b84a0eed06e65faf0935e1ffc10ce3272b39 Mon Sep 17 00:00:00 2001
From: Tim Haasdyk <tim_haasdyk@sil.org>
Date: Fri, 23 Oct 2026 17:19:48 +0200
Subject: [PATCH 07/22] Add morpheme commands with parity tests (#444)

Host-side copies of the writeMorphemes, deleteMorphemes and
writeMorphemeGloss reducers, registered as session commands. Exports the
token-command helpers they reuse and extracts detachEmptiedAnalysis from
writeGloss.

main.test.ts's session stub now serves its draft through a real in-memory
DraftRepository, so the approve and morpheme command tests assert real
changes instead of an empty ChangeSet.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 src/__tests__/main.test.ts                    | 220 ++++-
 .../commands/morphemeCommands.parity.test.ts  | 818 ++++++++++++++++++
 .../commands/morphemeCommands.test.ts         | 160 ++++
 src/main.ts                                   | 131 +++
 src/services/commands/morphemeCommands.ts     | 160 ++++
 src/services/commands/tokenCommands.ts        |  32 +-
 src/types/interlinearizer.d.ts                |  39 +
 7 files changed, 1510 insertions(+), 50 deletions(-)
 create mode 100644 src/__tests__/services/commands/morphemeCommands.parity.test.ts
 create mode 100644 src/__tests__/services/commands/morphemeCommands.test.ts
 create mode 100644 src/services/commands/morphemeCommands.ts

diff --git a/src/__tests__/main.test.ts b/src/__tests__/main.test.ts
index 7973e5b8d..fc75239a6 100644
--- a/src/__tests__/main.test.ts
+++ b/src/__tests__/main.test.ts
@@ -4,17 +4,28 @@ import type { OpenWebViewOptions, SavedWebViewDefinition, WebViewDefinition } fr
 import papiBackendMock from '@papi/backend';
 import { activate, deactivate } from '@main';
 import type { InterlinearizerOpenOptions } from '@main';
-import type { DraftProject, ProjectConfig } from 'interlinearizer';
+import type { DraftProject, ProjectConfig, TextAnalysis } from 'interlinearizer';
 import { AnalysisSessions } from '../services/analysisSessions';
 import * as bookService from '../services/bookService';
+import { DraftRepository } from '../services/draftRepository';
 import * as hostPerf from '../services/hostPerf';
 import * as projectStorage from '../services/projectStorage';
 import * as pt9ImportService from '../services/pt9ImportService';
-import { type AnalysisRepository, UnreadableBooksError } from '../types/analysis-repository';
-import { emptyDraft } from '../types/empty-factories';
-import { scopeRecordOf } from '../utils/change-set';
+import {
+  type IndexDifference,
+  type KeyValueStorage,
+  type RepositoryCapabilities,
+  UnreadableBooksError,
+} from '../types/analysis-repository';
+import { emptyAnalysis, emptyDraft } from '../types/empty-factories';
 import { toProjectSummary } from '../types/interlinear-project-summary';
-import { createTestActivationContext, makeStubProject } from './test-helpers';
+import {
+  createTestActivationContext,
+  FIXTURE_STAMPS,
+  makeStubProject,
+  memoryStorage,
+  silentLogger,
+} from './test-helpers';
 
 jest.mock('../services/bookService');
 jest.mock('../services/hostPerf');
@@ -404,6 +415,9 @@ describe('main', () => {
           'interlinearizer.checkIndexes',
           'interlinearizer.writeGloss',
           'interlinearizer.approveAnalysisForToken',
+          'interlinearizer.writeMorphemes',
+          'interlinearizer.deleteMorphemes',
+          'interlinearizer.writeMorphemeGloss',
           'interlinearizer.openSelectProjectModal',
           'interlinearizer.openNewProjectModal',
           'interlinearizer.openProjectInfoModal',
@@ -1829,30 +1843,60 @@ describe('main', () => {
   });
 
   describe('session commands', () => {
-    /** A repository handing out `draft`, as storage would open one. */
-    function stubRepository(draft: DraftProject, readOnly = false): AnalysisRepository {
-      const noLinks = { tokenAnalysisLinks: [], phraseAnalysisLinks: [], segmentAnalysisLinks: [] };
-      return {
-        capabilities: { readOnly },
-        exportAll: async () => ({ draft, unreadableBooks: [] }),
-        exportForCopy: async () => ({ draft, unreadableBooks: [] }),
-        replaceAll: async () => [],
-        markClean: async () => {},
-        apply: async (changes) => ({ inverse: changes }),
-        getTokenAnalyses: async () => [],
-        getPhraseAnalyses: async () => [],
-        getSegmentAnalyses: async () => [],
-        findLinksByToken: async () => noLinks,
-        findLinksBySegment: async () => [],
-        findLinksToAnalyses: async () => noLinks,
-        findLinksInBooks: async () => noLinks,
-        findTokenAnalysesByForm: async () => [],
-        findPhraseAnalysesByForm: async () => [],
-        checkIndexes: async () => [
-          { index: 'tokenAnalyses', key: 'ta-1', missing: ['ta-1'], extra: [] },
-        ],
-        getScope: async () => scopeRecordOf(draft),
-      };
+    /** A draft repository in memory whose indexes always report one difference. */
+    class StubRepository extends DraftRepository {
+      override readonly capabilities: RepositoryCapabilities;
+
+      constructor(storage: KeyValueStorage, sourceProjectId: string, readOnly: boolean) {
+        super(storage, sourceProjectId, silentLogger());
+        this.capabilities = { readOnly };
+      }
+
+      override async checkIndexes(): Promise<IndexDifference[]> {
+        return [{ index: 'tokenAnalyses', key: 'ta-1', missing: ['ta-1'], extra: [] }];
+      }
+    }
+
+    /** A repository holding `draft`, as storage would open one. */
+    async function stubRepository(draft: DraftProject, readOnly = false): Promise<StubRepository> {
+      const { storage } = memoryStorage();
+      await new DraftRepository(storage, draft.sourceProjectId, silentLogger()).replaceAll(draft);
+      return new StubRepository(storage, draft.sourceProjectId, readOnly);
+    }
+
+    /** "cats" on GEN 1:1:0, approved with a breakdown and nothing else. */
+    const CATS_BREAKDOWN: Partial<TextAnalysis> = {
+      tokenAnalyses: [
+        {
+          id: 'ta-cats',
+          ...FIXTURE_STAMPS,
+          surfaceText: 'cats',
+          morphemes: [
+            { id: 'm-cat', form: 'cat', writingSystem: 'en' },
+            { id: 'm-s', form: '-s', writingSystem: 'en' },
+          ],
+        },
+      ],
+      tokenAnalysisLinks: [
+        {
+          id: 'tl-cats',
+          analysisId: 'ta-cats',
+          ...FIXTURE_STAMPS,
+          status: 'approved',
+          token: { tokenRef: 'GEN 1:1:0', surfaceText: 'cats' },
+        },
+      ],
+    };
+
+    /** Opens the source project's draft holding `analysis`, its analysis language English. */
+    async function seedDraft(analysis: Partial<TextAnalysis> = {}): Promise<void> {
+      jest.mocked(projectStorage.openDraftRepository).mockReturnValue(
+        await stubRepository({
+          ...emptyDraft('src-project'),
+          analysisLanguages: ['en'],
+          analysis: { ...emptyAnalysis(), ...analysis },
+        }),
+      );
     }
 
     /** Activates the extension and returns the session commands' handlers. */
@@ -1897,15 +1941,31 @@ describe('main', () => {
             analysisId: string,
           ) => Promise<string>
         >('interlinearizer.approveAnalysisForToken'),
+        writeMorphemes: handler<
+          (
+            sessionId: string,
+            tokenRef: string,
+            surfaceText: string,
+            forms: string[],
+            writingSystem: string,
+          ) => Promise<string>
+        >('interlinearizer.writeMorphemes'),
+        deleteMorphemes: handler<(sessionId: string, tokenRef: string) => Promise<string>>(
+          'interlinearizer.deleteMorphemes',
+        ),
+        writeMorphemeGloss: handler<
+          (
+            sessionId: string,
+            tokenRef: string,
+            morphemeId: string,
+            value: string,
+          ) => Promise<string>
+        >('interlinearizer.writeMorphemeGloss'),
       };
     }
 
-    beforeEach(() => {
-      jest
-        .mocked(projectStorage.openDraftRepository)
-        .mockReturnValue(
-          stubRepository({ ...emptyDraft('src-project'), analysisLanguages: ['en'] }),
-        );
+    beforeEach(async () => {
+      await seedDraft();
       __mockSettingsGet.mockResolvedValue(['en']);
     });
 
@@ -1938,7 +1998,7 @@ describe('main', () => {
         ]);
       jest
         .mocked(projectStorage.openPt9ImportRepository)
-        .mockReturnValue(stubRepository(emptyDraft('src-project'), true));
+        .mockReturnValue(await stubRepository(emptyDraft('src-project'), true));
       const { openSession } = await activateSessionCommands();
 
       const opened = JSON.parse(await openSession('src-project', 'import-id'));
@@ -1957,7 +2017,7 @@ describe('main', () => {
     it('reads the interface languages for a draft that lists no analysis language', async () => {
       jest
         .mocked(projectStorage.openDraftRepository)
-        .mockReturnValue(stubRepository(emptyDraft('src-project')));
+        .mockReturnValue(await stubRepository(emptyDraft('src-project')));
       __mockSettingsGet.mockResolvedValue(['fr']);
       const { openSession } = await activateSessionCommands();
 
@@ -2110,12 +2170,92 @@ describe('main', () => {
     });
 
     it('approves an analysis for a token, replying with the changes', async () => {
+      await seedDraft({
+        tokenAnalyses: [{ id: 'ta-in', ...FIXTURE_STAMPS, surfaceText: 'In', gloss: { en: 'at' } }],
+      });
       const { openSession, approveAnalysisForToken } = await activateSessionCommands();
       const { sessionId } = JSON.parse(await openSession('src-project'));
 
-      await expect(
-        approveAnalysisForToken(sessionId, 'GEN 1:1:0', 'In', 'ta-unknown').then(JSON.parse),
-      ).resolves.toStrictEqual({ intent: 'approveAnalysisForToken' });
+      const changes = JSON.parse(
+        await approveAnalysisForToken(sessionId, 'GEN 1:1:0', 'In', 'ta-in'),
+      );
+
+      expect(changes).toMatchObject({
+        intent: 'approveAnalysisForToken',
+        tokenAnalysisLinks: {
+          puts: [
+            {
+              analysisId: 'ta-in',
+              status: 'approved',
+              token: { tokenRef: 'GEN 1:1:0', surfaceText: 'In' },
+            },
+          ],
+          deletes: [],
+        },
+      });
+    });
+
+    it("writes a token's morpheme breakdown, replying with the changes", async () => {
+      const { openSession, writeMorphemes } = await activateSessionCommands();
+      const { sessionId } = JSON.parse(await openSession('src-project'));
+
+      const changes = JSON.parse(
+        await writeMorphemes(sessionId, 'GEN 1:1:0', 'cats', ['cat', '-s'], 'en'),
+      );
+
+      expect(changes).toMatchObject({
+        intent: 'writeMorphemes',
+        tokenAnalyses: {
+          puts: [
+            {
+              surfaceText: 'cats',
+              morphemes: [
+                { id: expect.any(String), form: 'cat', writingSystem: 'en' },
+                { id: expect.any(String), form: '-s', writingSystem: 'en' },
+              ],
+            },
+          ],
+          deletes: [],
+        },
+        tokenAnalysisLinks: {
+          puts: [{ status: 'approved', token: { tokenRef: 'GEN 1:1:0', surfaceText: 'cats' } }],
+          deletes: [],
+        },
+      });
+    });
+
+    it("removes a token's morpheme breakdown, replying with the changes", async () => {
+      await seedDraft(CATS_BREAKDOWN);
+      const { openSession, deleteMorphemes } = await activateSessionCommands();
+      const { sessionId } = JSON.parse(await openSession('src-project'));
+
+      const changes = JSON.parse(await deleteMorphemes(sessionId, 'GEN 1:1:0'));
+
+      expect(changes).toMatchObject({
+        intent: 'deleteMorphemes',
+        tokenAnalyses: { puts: [], deletes: ['ta-cats'] },
+        tokenAnalysisLinks: { puts: [], deletes: ['tl-cats'] },
+      });
+    });
+
+    it("glosses a morpheme in the session's language, replying with the changes", async () => {
+      await seedDraft(CATS_BREAKDOWN);
+      const { openSession, setAnalysisLanguage, writeMorphemeGloss } =
+        await activateSessionCommands();
+      const { sessionId } = JSON.parse(await openSession('src-project'));
+      await setAnalysisLanguage(sessionId, 'fr');
+
+      const changes = JSON.parse(await writeMorphemeGloss(sessionId, 'GEN 1:1:0', 'm-cat', 'chat'));
+
+      expect(changes).toMatchObject({
+        intent: 'writeMorphemeGloss',
+        tokenAnalyses: {
+          puts: [
+            { id: 'ta-cats', morphemes: [{ id: 'm-cat', gloss: { fr: 'chat' } }, { id: 'm-s' }] },
+          ],
+          deletes: [],
+        },
+      });
     });
 
     it('closes every session on deactivation', async () => {
diff --git a/src/__tests__/services/commands/morphemeCommands.parity.test.ts b/src/__tests__/services/commands/morphemeCommands.parity.test.ts
new file mode 100644
index 000000000..beb27d4ea
--- /dev/null
+++ b/src/__tests__/services/commands/morphemeCommands.parity.test.ts
@@ -0,0 +1,818 @@
+/// <reference types="jest" />
+
+import type {
+  MorphemeAnalysis,
+  TextAnalysis,
+  TokenAnalysis,
+  TokenAnalysisLink,
+} from 'interlinearizer';
+import {
+  deleteMorphemes as deleteMorphemesCommand,
+  writeMorphemeGloss as writeMorphemeGlossCommand,
+  writeMorphemes as writeMorphemesCommand,
+} from '../../../services/commands/morphemeCommands';
+import { deleteMorphemes, writeMorphemeGloss, writeMorphemes } from '../../../store/analysisSlice';
+import { emptyAnalysis } from '../../../types/empty-factories';
+import { FIXTURE_STAMPS } from '../../test-helpers';
+import { runParity } from './parity';
+
+const NOW = '2026-06-01T00:00:00.000Z';
+const EARLIER = { createdAt: '2025-06-01T00:00:00.000Z', updatedAt: '2025-06-01T00:00:00.000Z' };
+const LATER = { createdAt: '2026-03-01T00:00:00.000Z', updatedAt: '2026-03-01T00:00:00.000Z' };
+
+function payload(id: string, surfaceText: string, fields: Partial<TokenAnalysis> = {}) {
+  return { id, ...FIXTURE_STAMPS, surfaceText, ...fields };
+}
+
+function morpheme(id: string, form: string, fields: Partial<MorphemeAnalysis> = {}) {
+  return { id, form, writingSystem: 'en', ...fields };
+}
+
+function link(
+  id: string,
+  analysisId: string,
+  tokenRef: string,
+  fields: Partial<TokenAnalysisLink> = {},
+): TokenAnalysisLink {
+  return {
+    id,
+    analysisId,
+    ...FIXTURE_STAMPS,
+    status: 'approved',
+    token: { tokenRef, surfaceText: 'cats' },
+    ...fields,
+  };
+}
+
+function analysisOf(
+  tokenAnalyses: TokenAnalysis[],
+  tokenAnalysisLinks: TokenAnalysisLink[],
+): TextAnalysis {
+  return { ...emptyAnalysis(), tokenAnalyses, tokenAnalysisLinks };
+}
+
+const TOKEN = 'GEN 1:1:0';
+const OTHER_TOKEN = 'GEN 1:2:0';
+
+/** A breakdown as the WebView prepares one: a fresh id per form. */
+const forms = (...list: string[]) => list.map((form, i) => ({ id: `new-m-${i}`, form }));
+const CAT_S = [morpheme('m-cat', 'cat'), morpheme('m-s', '-s')];
+
+type ParityCase<Input> = {
+  analysis: TextAnalysis;
+  input: Input;
+  /** What the reducer's result must show, so the case exercises the path it names. */
+  expectStore: (store: TextAnalysis) => void;
+};
+
+const ids = (records: readonly { id: string }[]) => records.map(({ id }) => id).sort();
+
+type MorphemesInput = {
+  surfaceText?: string;
+  writingSystem?: string;
+  morphemes: { id: string; form: string }[];
+};
+
+describe('writeMorphemes parity with the reducer', () => {
+  const cases: [string, ParityCase<MorphemesInput>][] = [
+    [
+      'creates a payload and an approved link for an unanalyzed token',
+      {
+        analysis: emptyAnalysis(),
+        input: { morphemes: forms('cat', '-s') },
+        expectStore: (store) => {
+          expect(store.tokenAnalyses).toStrictEqual([
+            payload('new-analysis', 'cats', {
+              createdAt: NOW,
+              updatedAt: NOW,
+              morphemes: [morpheme('new-m-0', 'cat'), morpheme('new-m-1', '-s')],
+            }),
+          ]);
+          expect(ids(store.tokenAnalysisLinks)).toStrictEqual(['new-link']);
+        },
+      },
+    ],
+    [
+      'shares a stored payload whose breakdown matches, whatever its morpheme ids',
+      {
+        analysis: analysisOf(
+          [payload('ta-cats', 'cats', { morphemes: CAT_S })],
+          [link('tl-other', 'ta-cats', OTHER_TOKEN)],
+        ),
+        input: { morphemes: forms('cat', '-s') },
+        expectStore: (store) => {
+          expect(ids(store.tokenAnalyses)).toStrictEqual(['ta-cats']);
+          expect(store.tokenAnalysisLinks.find(({ id }) => id === 'new-link')?.analysisId).toBe(
+            'ta-cats',
+          );
+        },
+      },
+    ],
+    [
+      "approves the token's held link to the matching payload rather than adding one",
+      {
+        analysis: analysisOf(
+          [payload('ta-cats', 'cats', { morphemes: CAT_S })],
+          [link('tl-held', 'ta-cats', TOKEN, { status: 'suggested', confidence: 'low' })],
+        ),
+        input: { morphemes: forms('cat', '-s') },
+        expectStore: (store) => {
+          expect(store.tokenAnalysisLinks).toStrictEqual([
+            expect.objectContaining({ id: 'tl-held', status: 'approved', confidence: 'low' }),
+          ]);
+        },
+      },
+    ],
+    [
+      'adds a breakdown to an unshared payload holding none',
+      {
+        analysis: analysisOf(
+          [payload('ta-cats', 'cats', { gloss: { en: 'cats' } })],
+          [link('tl-cats', 'ta-cats', TOKEN)],
+        ),
+        input: { morphemes: forms('cat', '-s') },
+        expectStore: (store) => {
+          expect(store.tokenAnalyses).toStrictEqual([
+            payload('ta-cats', 'cats', {
+              updatedAt: NOW,
+              gloss: { en: 'cats' },
+              morphemes: [morpheme('new-m-0', 'cat'), morpheme('new-m-1', '-s')],
+            }),
+          ]);
+        },
+      },
+    ],
+    [
+      're-splits an unshared payload in place, keeping unchanged morphemes whole',
+      {
+        analysis: analysisOf(
+          [
+            payload('ta-cats', 'cats', {
+              morphemes: [
+                morpheme('m-cat', 'cat', {
+                  gloss: { en: 'feline' },
+                  senseRef: { authority: 'fwlite', senseId: 's-cat' },
+                }),
+                morpheme('m-s', '-s', { gloss: { en: 'PL' } }),
+              ],
+              morphemesStale: true,
+            }),
+          ],
+          [link('tl-cats', 'ta-cats', TOKEN)],
+        ),
+        input: { surfaceText: 'cats,', morphemes: forms('cat', 's') },
+        expectStore: (store) => {
+          expect(store.tokenAnalyses).toStrictEqual([
+            payload('ta-cats', 'cats,', {
+              updatedAt: NOW,
+              morphemes: [
+                morpheme('m-cat', 'cat', {
+                  gloss: { en: 'feline' },
+                  senseRef: { authority: 'fwlite', senseId: 's-cat' },
+                }),
+                morpheme('new-m-1', 's'),
+              ],
+            }),
+          ]);
+          expect(store.tokenAnalysisLinks[0].token.surfaceText).toBe('cats,');
+        },
+      },
+    ],
+    [
+      'keeps a distinct old morpheme per repeated form',
+      {
+        analysis: analysisOf(
+          [
+            payload('ta-baba', 'baba', {
+              morphemes: [
+                morpheme('m-1', 'ba', { gloss: { en: 'first' } }),
+                morpheme('m-2', 'ba', { gloss: { en: 'second' } }),
+              ],
+            }),
+          ],
+          [link('tl-baba', 'ta-baba', TOKEN, { token: { tokenRef: TOKEN, surfaceText: 'baba' } })],
+        ),
+        input: { surfaceText: 'baba', morphemes: forms('ba', 'ba', 'ba') },
+        expectStore: (store) => {
+          expect(store.tokenAnalyses[0].morphemes?.map(({ id }) => id)).toStrictEqual([
+            'm-1',
+            'm-2',
+            'new-m-2',
+          ]);
+        },
+      },
+    ],
+    [
+      'stamps the writing system on kept morphemes too',
+      {
+        analysis: analysisOf(
+          [
+            payload('ta-cats', 'cats', {
+              morphemes: [morpheme('m-cat', 'cat', { gloss: { en: 'feline' } })],
+            }),
+          ],
+          [link('tl-cats', 'ta-cats', TOKEN)],
+        ),
+        input: { writingSystem: 'en-Latn', morphemes: forms('cat', '-s') },
+        expectStore: (store) => {
+          expect(store.tokenAnalyses[0].morphemes).toStrictEqual([
+            morpheme('m-cat', 'cat', { writingSystem: 'en-Latn', gloss: { en: 'feline' } }),
+            morpheme('new-m-1', '-s', { writingSystem: 'en-Latn' }),
+          ]);
+        },
+      },
+    ],
+    [
+      'forks a payload other tokens share, re-splitting only the fork',
+      {
+        analysis: analysisOf(
+          [payload('ta-cats', 'cats', { morphemes: CAT_S })],
+          [link('tl-cats', 'ta-cats', TOKEN), link('tl-other', 'ta-cats', OTHER_TOKEN)],
+        ),
+        input: { morphemes: forms('ca', 'ts') },
+        expectStore: (store) => {
+          expect(ids(store.tokenAnalyses)).toStrictEqual(['new-analysis', 'ta-cats']);
+          expect(store.tokenAnalyses.find(({ id }) => id === 'ta-cats')?.morphemes).toStrictEqual(
+            CAT_S,
+          );
+        },
+      },
+    ],
+    [
+      'folds a fork back onto the shared payload when the re-split leaves it unchanged',
+      {
+        analysis: analysisOf(
+          [payload('ta-cats', 'cats', { morphemes: CAT_S })],
+          [link('tl-cats', 'ta-cats', TOKEN), link('tl-other', 'ta-cats', OTHER_TOKEN)],
+        ),
+        input: { morphemes: forms('cat', '-s') },
+        expectStore: (store) => {
+          expect(ids(store.tokenAnalyses)).toStrictEqual(['ta-cats']);
+          expect(store.tokenAnalysisLinks.every(({ analysisId }) => analysisId === 'ta-cats')).toBe(
+            true,
+          );
+        },
+      },
+    ],
+    [
+      "folds a re-split matching another payload into it, clearing the survivor's stale mark",
+      {
+        analysis: analysisOf(
+          [
+            payload('ta-split', 'cats', {
+              morphemes: [morpheme('m-ca', 'ca'), morpheme('m-ts', 'ts')],
+            }),
+            payload('ta-cats', 'Cats', { ...EARLIER, morphemes: CAT_S, morphemesStale: true }),
+          ],
+          [link('tl-split', 'ta-split', TOKEN), link('tl-other', 'ta-cats', OTHER_TOKEN)],
+        ),
+        input: { morphemes: forms('cat', '-s') },
+        expectStore: (store) => {
+          expect(ids(store.tokenAnalyses)).toStrictEqual(['ta-cats']);
+          expect(store.tokenAnalyses[0].morphemesStale).toBeUndefined();
+          expect(store.tokenAnalysisLinks.every(({ analysisId }) => analysisId === 'ta-cats')).toBe(
+            true,
+          );
+        },
+      },
+    ],
+    [
+      'leaves a token linking both folded payloads one link, dated by the earlier',
+      {
+        analysis: analysisOf(
+          [
+            payload('ta-split', 'cats', {
+              morphemes: [morpheme('m-ca', 'ca'), morpheme('m-ts', 'ts')],
+            }),
+            payload('ta-cats', 'cats', { ...EARLIER, morphemes: CAT_S }),
+          ],
+          [
+            link('tl-split', 'ta-split', TOKEN, LATER),
+            link('tl-offered', 'ta-cats', TOKEN, { ...EARLIER, status: 'suggested' }),
+          ],
+        ),
+        input: { morphemes: forms('cat', '-s') },
+        expectStore: (store) => {
+          expect(store.tokenAnalysisLinks).toStrictEqual([
+            expect.objectContaining({
+              id: 'tl-split',
+              status: 'approved',
+              createdAt: EARLIER.createdAt,
+            }),
+          ]);
+        },
+      },
+    ],
+    [
+      'edits the payload an approval tie picks among several approved links',
+      {
+        analysis: analysisOf(
+          [
+            payload('ta-old', 'cats', { morphemes: [morpheme('m-old', 'cats')] }),
+            payload('ta-new', 'cats', { morphemes: CAT_S }),
+          ],
+          [link('tl-old', 'ta-old', TOKEN, EARLIER), link('tl-new', 'ta-new', TOKEN, LATER)],
+        ),
+        input: { morphemes: forms('ca', 'ts') },
+        expectStore: (store) => {
+          expect(
+            store.tokenAnalyses.find(({ id }) => id === 'ta-new')?.morphemes?.map((m) => m.form),
+          ).toStrictEqual(['ca', 'ts']);
+          expect(store.tokenAnalyses.find(({ id }) => id === 'ta-old')?.morphemes).toStrictEqual([
+            morpheme('m-old', 'cats'),
+          ]);
+        },
+      },
+    ],
+    [
+      'leaves an empty breakdown where no forms are given',
+      {
+        analysis: analysisOf(
+          [payload('ta-cats', 'cats', { gloss: { en: 'cats' }, morphemes: CAT_S })],
+          [link('tl-cats', 'ta-cats', TOKEN)],
+        ),
+        input: { morphemes: [] },
+        expectStore: (store) => {
+          expect(store.tokenAnalyses[0].morphemes).toStrictEqual([]);
+        },
+      },
+    ],
+    [
+      'removes an approved link whose payload is gone before writing',
+      {
+        analysis: analysisOf([], [link('tl-orphan', 'ta-missing', TOKEN)]),
+        input: { morphemes: forms('cat', '-s') },
+        expectStore: (store) => {
+          expect(ids(store.tokenAnalysisLinks)).toStrictEqual(['new-link']);
+        },
+      },
+    ],
+  ];
+
+  it.each(cases)('%s', async (_name, { analysis, input, expectStore }) => {
+    const surfaceText = input.surfaceText ?? 'cats';
+    const writingSystem = input.writingSystem ?? 'en';
+    const outcome = await runParity(
+      analysis,
+      'en',
+      {
+        type: writeMorphemes.type,
+        payload: {
+          tokenRef: TOKEN,
+          surfaceText,
+          writingSystem,
+          analysisId: 'new-analysis',
+          linkId: 'new-link',
+          morphemes: input.morphemes,
+          now: NOW,
+        },
+      },
+      (buffer) =>
+        writeMorphemesCommand(buffer, {
+          tokenRef: TOKEN,
+          surfaceText,
+          writingSystem,
+          analysisId: 'new-analysis',
+          linkId: 'new-link',
+          morphemes: input.morphemes,
+          now: NOW,
+        }),
+    );
+
+    expectStore(outcome.store);
+    expect(outcome.host).toStrictEqual(outcome.store);
+    expect(outcome.indexDifferences).toStrictEqual([]);
+  });
+});
+
+type GlossInput = { morphemeId?: string; value: string };
+
+describe('writeMorphemeGloss parity with the reducer', () => {
+  const cases: [string, ParityCase<GlossInput>][] = [
+    [
+      'glosses an unglossed morpheme on an unshared payload, leaving its stale mark',
+      {
+        analysis: analysisOf(
+          [payload('ta-cats', 'cats', { morphemes: CAT_S, morphemesStale: true })],
+          [link('tl-cats', 'ta-cats', TOKEN)],
+        ),
+        input: { value: 'feline' },
+        expectStore: (store) => {
+          expect(store.tokenAnalyses).toStrictEqual([
+            payload('ta-cats', 'cats', {
+              updatedAt: NOW,
+              morphemes: [
+                morpheme('m-cat', 'cat', { gloss: { en: 'feline' } }),
+                morpheme('m-s', '-s'),
+              ],
+              morphemesStale: true,
+            }),
+          ]);
+          expect(store.tokenAnalysisLinks[0].updatedAt).toBe(NOW);
+        },
+      },
+    ],
+    [
+      'rewrites the gloss in one language, keeping the others',
+      {
+        analysis: analysisOf(
+          [
+            payload('ta-cats', 'cats', {
+              morphemes: [morpheme('m-cat', 'cat', { gloss: { en: 'feline', fr: 'chat' } })],
+            }),
+          ],
+          [link('tl-cats', 'ta-cats', TOKEN)],
+        ),
+        input: { value: 'cat' },
+        expectStore: (store) => {
+          expect(store.tokenAnalyses[0].morphemes?.[0].gloss).toStrictEqual({
+            en: 'cat',
+            fr: 'chat',
+          });
+        },
+      },
+    ],
+    [
+      'clears the gloss, dropping it once its only entry goes',
+      {
+        analysis: analysisOf(
+          [
+            payload('ta-cats', 'cats', {
+              morphemes: [morpheme('m-cat', 'cat', { gloss: { en: 'feline' } })],
+            }),
+          ],
+          [link('tl-cats', 'ta-cats', TOKEN)],
+        ),
+        input: { value: '  ' },
+        expectStore: (store) => {
+          expect(store.tokenAnalyses).toStrictEqual([
+            payload('ta-cats', 'cats', { updatedAt: NOW, morphemes: [morpheme('m-cat', 'cat')] }),
+          ]);
+        },
+      },
+    ],
+    [
+      'clears one language, keeping the others',
+      {
+        analysis: analysisOf(
+          [
+            payload('ta-cats', 'cats', {
+              morphemes: [morpheme('m-cat', 'cat', { gloss: { en: 'feline', fr: 'chat' } })],
+            }),
+          ],
+          [link('tl-cats', 'ta-cats', TOKEN)],
+        ),
+        input: { value: '' },
+        expectStore: (store) => {
+          expect(store.tokenAnalyses[0].morphemes?.[0].gloss).toStrictEqual({ fr: 'chat' });
+        },
+      },
+    ],
+    [
+      'stamps the payload and link even when a blank value finds no gloss to clear',
+      {
+        analysis: analysisOf(
+          [payload('ta-cats', 'cats', { morphemes: CAT_S })],
+          [link('tl-cats', 'ta-cats', TOKEN)],
+        ),
+        input: { value: '' },
+        expectStore: (store) => {
+          expect(store.tokenAnalyses[0]).toMatchObject({ updatedAt: NOW, morphemes: CAT_S });
+          expect(store.tokenAnalysisLinks[0].updatedAt).toBe(NOW);
+        },
+      },
+    ],
+    [
+      'forks a payload other tokens share, glossing only the fork',
+      {
+        analysis: analysisOf(
+          [payload('ta-cats', 'cats', { morphemes: CAT_S })],
+          [link('tl-cats', 'ta-cats', TOKEN), link('tl-other', 'ta-cats', OTHER_TOKEN)],
+        ),
+        input: { value: 'feline' },
+        expectStore: (store) => {
+          expect(ids(store.tokenAnalyses)).toStrictEqual(['new-analysis', 'ta-cats']);
+          expect(
+            store.tokenAnalyses.find(({ id }) => id === 'new-analysis')?.morphemes?.[0].gloss,
+          ).toStrictEqual({ en: 'feline' });
+          expect(store.tokenAnalyses.find(({ id }) => id === 'ta-cats')?.morphemes).toStrictEqual(
+            CAT_S,
+          );
+        },
+      },
+    ],
+    [
+      "folds a gloss matching another payload into it, clearing the survivor's stale mark",
+      {
+        analysis: analysisOf(
+          [
+            payload('ta-bare', 'cats', { morphemes: CAT_S }),
+            payload('ta-glossed', 'cats', {
+              ...EARLIER,
+              morphemes: [
+                morpheme('m-cat-2', 'cat', { gloss: { en: 'feline' } }),
+                morpheme('m-s-2', '-s'),
+              ],
+              morphemesStale: true,
+            }),
+          ],
+          [link('tl-bare', 'ta-bare', TOKEN), link('tl-other', 'ta-glossed', OTHER_TOKEN)],
+        ),
+        input: { value: 'feline' },
+        expectStore: (store) => {
+          expect(ids(store.tokenAnalyses)).toStrictEqual(['ta-glossed']);
+          expect(store.tokenAnalyses[0].morphemesStale).toBeUndefined();
+          expect(
+            store.tokenAnalysisLinks.every(({ analysisId }) => analysisId === 'ta-glossed'),
+          ).toBe(true);
+        },
+      },
+    ],
+    [
+      'folds a clear matching another payload into it',
+      {
+        analysis: analysisOf(
+          [
+            payload('ta-glossed', 'cats', {
+              morphemes: [
+                morpheme('m-cat', 'cat', { gloss: { en: 'feline' } }),
+                morpheme('m-s', '-s'),
+              ],
+            }),
+            payload('ta-bare', 'cats', {
+              ...EARLIER,
+              morphemes: [morpheme('m-cat-2', 'cat'), morpheme('m-s-2', '-s')],
+            }),
+          ],
+          [link('tl-glossed', 'ta-glossed', TOKEN), link('tl-other', 'ta-bare', OTHER_TOKEN)],
+        ),
+        input: { value: '' },
+        expectStore: (store) => {
+          expect(ids(store.tokenAnalyses)).toStrictEqual(['ta-bare']);
+          expect(store.tokenAnalysisLinks.every(({ analysisId }) => analysisId === 'ta-bare')).toBe(
+            true,
+          );
+        },
+      },
+    ],
+    [
+      'stages nothing for a token with no approved analysis',
+      {
+        analysis: analysisOf(
+          [payload('ta-cats', 'cats', { morphemes: CAT_S })],
+          [link('tl-other', 'ta-cats', OTHER_TOKEN)],
+        ),
+        input: { value: 'feline' },
+        expectStore: (store) => {
+          expect(store.tokenAnalyses[0].updatedAt).toBe(FIXTURE_STAMPS.updatedAt);
+        },
+      },
+    ],
+    [
+      'stages nothing for a morpheme the breakdown lacks',
+      {
+        analysis: analysisOf(
+          [payload('ta-cats', 'cats', { morphemes: CAT_S })],
+          [link('tl-cats', 'ta-cats', TOKEN)],
+        ),
+        input: { morphemeId: 'm-missing', value: 'feline' },
+        expectStore: (store) => {
+          expect(store.tokenAnalyses[0].updatedAt).toBe(FIXTURE_STAMPS.updatedAt);
+        },
+      },
+    ],
+    [
+      'stages nothing for a payload with no breakdown',
+      {
+        analysis: analysisOf(
+          [payload('ta-cats', 'cats', { gloss: { en: 'cats' } })],
+          [link('tl-cats', 'ta-cats', TOKEN)],
+        ),
+        input: { value: 'feline' },
+        expectStore: (store) => {
+          expect(store.tokenAnalyses[0].updatedAt).toBe(FIXTURE_STAMPS.updatedAt);
+        },
+      },
+    ],
+    [
+      'removes an approved link whose payload is gone, and nothing else',
+      {
+        analysis: analysisOf([], [link('tl-orphan', 'ta-missing', TOKEN)]),
+        input: { value: 'feline' },
+        expectStore: (store) => {
+          expect(store).toStrictEqual(emptyAnalysis());
+        },
+      },
+    ],
+  ];
+
+  it.each(cases)('%s', async (_name, { analysis, input, expectStore }) => {
+    const morphemeId = input.morphemeId ?? 'm-cat';
+    const outcome = await runParity(
+      analysis,
+      'en',
+      {
+        type: writeMorphemeGloss.type,
+        payload: { tokenRef: TOKEN, morphemeId, value: input.value, id: 'new-analysis', now: NOW },
+      },
+      (buffer) =>
+        writeMorphemeGlossCommand(buffer, {
+          tokenRef: TOKEN,
+          morphemeId,
+          value: input.value,
+          analysisLanguage: 'en',
+          analysisId: 'new-analysis',
+          now: NOW,
+        }),
+    );
+
+    expectStore(outcome.store);
+    expect(outcome.host).toStrictEqual(outcome.store);
+    expect(outcome.indexDifferences).toStrictEqual([]);
+  });
+});
+
+describe('deleteMorphemes parity with the reducer', () => {
+  const cases: [string, Omit<ParityCase<undefined>, 'input'>][] = [
+    [
+      'removes the breakdown, keeping a payload with a gloss',
+      {
+        analysis: analysisOf(
+          [
+            payload('ta-cats', 'cats', {
+              gloss: { en: 'cats' },
+              morphemes: CAT_S,
+              morphemesStale: true,
+            }),
+          ],
+          [link('tl-cats', 'ta-cats', TOKEN)],
+        ),
+        expectStore: (store) => {
+          expect(store.tokenAnalyses).toStrictEqual([
+            payload('ta-cats', 'cats', { updatedAt: NOW, gloss: { en: 'cats' } }),
+          ]);
+          expect(store.tokenAnalysisLinks[0].updatedAt).toBe(NOW);
+        },
+      },
+    ],
+    [
+      'removes the payload and its link when the breakdown was its only content',
+      {
+        analysis: analysisOf(
+          [payload('ta-cats', 'cats', { morphemes: CAT_S })],
+          [link('tl-cats', 'ta-cats', TOKEN)],
+        ),
+        expectStore: (store) => {
+          expect(store).toStrictEqual(emptyAnalysis());
+        },
+      },
+    ],
+    [
+      'removes an empty breakdown',
+      {
+        analysis: analysisOf(
+          [payload('ta-cats', 'cats', { gloss: { en: 'cats' }, morphemes: [] })],
+          [link('tl-cats', 'ta-cats', TOKEN)],
+        ),
+        expectStore: (store) => {
+          expect(store.tokenAnalyses).toStrictEqual([
+            payload('ta-cats', 'cats', { updatedAt: NOW, gloss: { en: 'cats' } }),
+          ]);
+        },
+      },
+    ],
+    [
+      "keeps an emptied payload another of the token's links still names",
+      {
+        analysis: analysisOf(
+          [payload('ta-cats', 'cats', { morphemes: CAT_S })],
+          [
+            link('tl-cats', 'ta-cats', TOKEN),
+            link('tl-rejected', 'ta-cats', TOKEN, { status: 'rejected' }),
+          ],
+        ),
+        expectStore: (store) => {
+          expect(store.tokenAnalyses).toStrictEqual([
+            payload('ta-cats', 'cats', { updatedAt: NOW }),
+          ]);
+          expect(ids(store.tokenAnalysisLinks)).toStrictEqual(['tl-rejected']);
+        },
+      },
+    ],
+    [
+      'keeps a payload holding other content',
+      {
+        analysis: analysisOf(
+          [
+            payload('ta-cats', 'cats', {
+              morphemes: CAT_S,
+              pos: 'n',
+              features: { Number: 'Pl' },
+              glossSenseRef: { authority: 'fwlite', senseId: 's-cat' },
+            }),
+          ],
+          [link('tl-cats', 'ta-cats', TOKEN)],
+        ),
+        expectStore: (store) => {
+          expect(store.tokenAnalyses[0]).toMatchObject({ pos: 'n', updatedAt: NOW });
+          expect(store.tokenAnalyses[0].morphemes).toBeUndefined();
+        },
+      },
+    ],
+    [
+      "forks a payload other tokens share, removing only the fork's breakdown",
+      {
+        analysis: analysisOf(
+          [payload('ta-cats', 'cats', { gloss: { en: 'cats' }, morphemes: CAT_S })],
+          [link('tl-cats', 'ta-cats', TOKEN), link('tl-other', 'ta-cats', OTHER_TOKEN)],
+        ),
+        expectStore: (store) => {
+          expect(ids(store.tokenAnalyses)).toStrictEqual(['new-analysis', 'ta-cats']);
+          expect(store.tokenAnalyses.find(({ id }) => id === 'ta-cats')?.morphemes).toStrictEqual(
+            CAT_S,
+          );
+        },
+      },
+    ],
+    [
+      "drops only this token's link from a shared payload the removal would empty",
+      {
+        analysis: analysisOf(
+          [payload('ta-cats', 'cats', { morphemes: CAT_S })],
+          [link('tl-cats', 'ta-cats', TOKEN), link('tl-other', 'ta-cats', OTHER_TOKEN)],
+        ),
+        expectStore: (store) => {
+          expect(store.tokenAnalyses).toStrictEqual([
+            payload('ta-cats', 'cats', { morphemes: CAT_S }),
+          ]);
+          expect(ids(store.tokenAnalysisLinks)).toStrictEqual(['tl-other']);
+        },
+      },
+    ],
+    [
+      'folds the stripped payload into another its remaining content matches',
+      {
+        analysis: analysisOf(
+          [
+            payload('ta-split', 'cats', { gloss: { en: 'cats' }, morphemes: CAT_S }),
+            payload('ta-plain', 'Cats', { ...EARLIER, gloss: { en: 'cats' } }),
+          ],
+          [link('tl-split', 'ta-split', TOKEN), link('tl-other', 'ta-plain', OTHER_TOKEN)],
+        ),
+        expectStore: (store) => {
+          expect(ids(store.tokenAnalyses)).toStrictEqual(['ta-plain']);
+          expect(
+            store.tokenAnalysisLinks.every(({ analysisId }) => analysisId === 'ta-plain'),
+          ).toBe(true);
+        },
+      },
+    ],
+    [
+      'stages nothing for a token with no approved analysis',
+      {
+        analysis: analysisOf(
+          [payload('ta-cats', 'cats', { morphemes: CAT_S })],
+          [link('tl-other', 'ta-cats', OTHER_TOKEN)],
+        ),
+        expectStore: (store) => {
+          expect(store.tokenAnalyses[0].updatedAt).toBe(FIXTURE_STAMPS.updatedAt);
+        },
+      },
+    ],
+    [
+      'stages nothing for a payload with no breakdown',
+      {
+        analysis: analysisOf(
+          [payload('ta-cats', 'cats', { gloss: { en: 'cats' } })],
+          [link('tl-cats', 'ta-cats', TOKEN)],
+        ),
+        expectStore: (store) => {
+          expect(store.tokenAnalyses[0].updatedAt).toBe(FIXTURE_STAMPS.updatedAt);
+        },
+      },
+    ],
+    [
+      'removes an approved link whose payload is gone, and nothing else',
+      {
+        analysis: analysisOf([], [link('tl-orphan', 'ta-missing', TOKEN)]),
+        expectStore: (store) => {
+          expect(store).toStrictEqual(emptyAnalysis());
+        },
+      },
+    ],
+  ];
+
+  it.each(cases)('%s', async (_name, { analysis, expectStore }) => {
+    const outcome = await runParity(
+      analysis,
+      'en',
+      { type: deleteMorphemes.type, payload: { tokenRef: TOKEN, id: 'new-analysis', now: NOW } },
+      (buffer) =>
+        deleteMorphemesCommand(buffer, { tokenRef: TOKEN, analysisId: 'new-analysis', now: NOW }),
+    );
+
+    expectStore(outcome.store);
+    expect(outcome.host).toStrictEqual(outcome.store);
+    expect(outcome.indexDifferences).toStrictEqual([]);
+  });
+});
diff --git a/src/__tests__/services/commands/morphemeCommands.test.ts b/src/__tests__/services/commands/morphemeCommands.test.ts
new file mode 100644
index 000000000..d7df54d61
--- /dev/null
+++ b/src/__tests__/services/commands/morphemeCommands.test.ts
@@ -0,0 +1,160 @@
+/// <reference types="jest" />
+
+import type { TextAnalysis, TokenAnalysis, TokenAnalysisLink } from 'interlinearizer';
+import { ChangeBuffer } from '../../../services/commands/changeBuffer';
+import {
+  deleteMorphemes,
+  writeMorphemeGloss,
+  writeMorphemes,
+} from '../../../services/commands/morphemeCommands';
+import { DraftRepository } from '../../../services/draftRepository';
+import { emptyAnalysis, emptyDraft } from '../../../types/empty-factories';
+import { FIXTURE_STAMPS, memoryStorage, silentLogger } from '../../test-helpers';
+
+const NOW = '2026-06-01T00:00:00.000Z';
+const STAMP = { analysisId: 'new-analysis', linkId: 'new-link', now: NOW };
+
+const shared: TokenAnalysis = {
+  id: 'ta-cats',
+  ...FIXTURE_STAMPS,
+  surfaceText: 'cats',
+  morphemes: [
+    { id: 'm-cat', form: 'cat', writingSystem: 'en' },
+    { id: 'm-s', form: '-s', writingSystem: 'en' },
+  ],
+};
+
+function link(id: string, tokenRef: string): TokenAnalysisLink {
+  return {
+    id,
+    analysisId: 'ta-cats',
+    ...FIXTURE_STAMPS,
+    status: 'approved',
+    token: { tokenRef, surfaceText: 'cats' },
+  };
+}
+
+async function bufferOver(analysis: Partial<TextAnalysis>): Promise<ChangeBuffer> {
+  const { storage } = memoryStorage();
+  const repository = new DraftRepository(storage, 'src', silentLogger());
+  await repository.replaceAll({
+    ...emptyDraft('src'),
+    analysis: { ...emptyAnalysis(), ...analysis },
+  });
+  return new ChangeBuffer(repository);
+}
+
+describe('writeMorphemes', () => {
+  it('stages only the link when a re-split leaves a shared breakdown unchanged', async () => {
+    const buffer = await bufferOver({
+      tokenAnalyses: [shared],
+      tokenAnalysisLinks: [link('tl-1', 'GEN 1:1:0'), link('tl-2', 'GEN 1:2:0')],
+    });
+
+    await writeMorphemes(buffer, {
+      ...STAMP,
+      tokenRef: 'GEN 1:1:0',
+      surfaceText: 'cats',
+      writingSystem: 'en',
+      morphemes: [
+        { id: 'new-m-0', form: 'cat' },
+        { id: 'new-m-1', form: '-s' },
+      ],
+    });
+
+    expect(buffer.toChangeSet('writeMorphemes')).toStrictEqual({
+      intent: 'writeMorphemes',
+      tokenAnalysisLinks: {
+        puts: [{ ...link('tl-1', 'GEN 1:1:0'), updatedAt: NOW }],
+        deletes: [],
+      },
+    });
+  });
+});
+
+describe('writeMorphemeGloss', () => {
+  it('stages nothing for a token with no approved analysis', async () => {
+    const buffer = await bufferOver({ tokenAnalyses: [shared] });
+
+    await writeMorphemeGloss(buffer, {
+      ...STAMP,
+      tokenRef: 'GEN 1:1:0',
+      morphemeId: 'm-cat',
+      value: 'feline',
+      analysisLanguage: 'en',
+    });
+
+    expect(buffer.toChangeSet('writeMorphemeGloss')).toStrictEqual({
+      intent: 'writeMorphemeGloss',
+    });
+  });
+
+  it('stages only the link when a gloss leaves a shared breakdown unchanged', async () => {
+    const buffer = await bufferOver({
+      tokenAnalyses: [shared],
+      tokenAnalysisLinks: [link('tl-1', 'GEN 1:1:0'), link('tl-2', 'GEN 1:2:0')],
+    });
+
+    await writeMorphemeGloss(buffer, {
+      ...STAMP,
+      tokenRef: 'GEN 1:1:0',
+      morphemeId: 'm-cat',
+      value: '',
+      analysisLanguage: 'en',
+    });
+
+    expect(buffer.toChangeSet('writeMorphemeGloss')).toStrictEqual({
+      intent: 'writeMorphemeGloss',
+      tokenAnalysisLinks: {
+        puts: [{ ...link('tl-1', 'GEN 1:1:0'), updatedAt: NOW }],
+        deletes: [],
+      },
+    });
+  });
+
+  it('stages nothing for a morpheme the breakdown lacks', async () => {
+    const buffer = await bufferOver({
+      tokenAnalyses: [shared],
+      tokenAnalysisLinks: [link('tl-1', 'GEN 1:1:0')],
+    });
+
+    await writeMorphemeGloss(buffer, {
+      ...STAMP,
+      tokenRef: 'GEN 1:1:0',
+      morphemeId: 'm-missing',
+      value: 'feline',
+      analysisLanguage: 'en',
+    });
+
+    expect(buffer.toChangeSet('writeMorphemeGloss')).toStrictEqual({
+      intent: 'writeMorphemeGloss',
+    });
+  });
+});
+
+describe('deleteMorphemes', () => {
+  it("stages only the link's removal when stripping a shared payload empties it", async () => {
+    const buffer = await bufferOver({
+      tokenAnalyses: [shared],
+      tokenAnalysisLinks: [link('tl-1', 'GEN 1:1:0'), link('tl-2', 'GEN 1:2:0')],
+    });
+
+    await deleteMorphemes(buffer, { ...STAMP, tokenRef: 'GEN 1:1:0' });
+
+    expect(buffer.toChangeSet('deleteMorphemes')).toStrictEqual({
+      intent: 'deleteMorphemes',
+      tokenAnalysisLinks: { puts: [], deletes: ['tl-1'] },
+    });
+  });
+
+  it('stages nothing for a payload with no breakdown', async () => {
+    const buffer = await bufferOver({
+      tokenAnalyses: [{ ...shared, morphemes: undefined, gloss: { en: 'cats' } }],
+      tokenAnalysisLinks: [link('tl-1', 'GEN 1:1:0')],
+    });
+
+    await deleteMorphemes(buffer, { ...STAMP, tokenRef: 'GEN 1:1:0' });
+
+    expect(buffer.toChangeSet('deleteMorphemes')).toStrictEqual({ intent: 'deleteMorphemes' });
+  });
+});
diff --git a/src/main.ts b/src/main.ts
index abc254b1a..7af855c28 100644
--- a/src/main.ts
+++ b/src/main.ts
@@ -14,6 +14,7 @@ import interlinearizerStyles from './interlinearizer.web-view.scss?inline';
 import { AnalysisSessions, type Session } from './services/analysisSessions';
 import * as bookService from './services/bookService';
 import type { ChangeBuffer } from './services/commands/changeBuffer';
+import * as morphemeCommands from './services/commands/morphemeCommands';
 import * as tokenCommands from './services/commands/tokenCommands';
 import { readHostPerf, setHostPerfMarks } from './services/hostPerf';
 import * as projectStorage from './services/projectStorage';
@@ -901,6 +902,66 @@ function approveAnalysisForToken(
   );
 }
 
+/**
+ * Writes a token's morpheme breakdown, each form in `writingSystem`.
+ *
+ * @returns The changes it applied, as JSON.
+ * @throws As {@link runSessionEdit} does.
+ */
+function writeMorphemes(
+  sessionId: string,
+  tokenRef: string,
+  surfaceText: string,
+  forms: string[],
+  writingSystem: string,
+): Promise<string> {
+  return runSessionEdit(sessionId, 'writeMorphemes', (buffer) =>
+    morphemeCommands.writeMorphemes(buffer, {
+      ...editStamp(),
+      tokenRef,
+      surfaceText,
+      writingSystem,
+      morphemes: forms.map((form) => ({ id: crypto.randomUUID(), form })),
+    }),
+  );
+}
+
+/**
+ * Removes a token's morpheme breakdown.
+ *
+ * @returns The changes it applied, as JSON.
+ * @throws As {@link runSessionEdit} does.
+ */
+function deleteMorphemes(sessionId: string, tokenRef: string): Promise<string> {
+  return runSessionEdit(sessionId, 'deleteMorphemes', (buffer) =>
+    morphemeCommands.deleteMorphemes(buffer, { ...editStamp(), tokenRef }),
+  );
+}
+
+/**
+ * Glosses one morpheme of a token's breakdown in the session's analysis language; a blank value
+ * clears it.
+ *
+ * @returns The changes it applied, as JSON.
+ * @throws As {@link runSessionEdit} does.
+ */
+function writeMorphemeGloss(
+  sessionId: string,
+  tokenRef: string,
+  morphemeId: string,
+  value: string,
+): Promise<string> {
+  return runSessionEdit(sessionId, 'writeMorphemeGloss', (buffer, session) =>
+    morphemeCommands.writeMorphemeGloss(buffer, {
+      ...editStamp(),
+      tokenRef,
+      morphemeId,
+      value,
+      analysisLanguage: session.analysisLanguage,
+    }),
+  );
+}
+
 /**
  * Returns a summary of every interlinearizer project for the given source project as a JSON string.
  * The WebView deserializes this to populate its project picker and to decide whether to prompt
@@ -1570,6 +1631,73 @@ export async function activate(context: ExecutionActivationContext): Promise<voi
     },
   );
 
+  const writeMorphemesCommandRegistration = await papi.commands.registerCommand(
+    'interlinearizer.writeMorphemes',
+    writeMorphemes,
+    {
+      method: {
+        summary: "Write a token's morpheme breakdown",
+        params: [
+          sessionIdParam,
+          ...tokenParams,
+          {
+            name: 'forms',
+            required: true,
+            summary: 'The morpheme forms, in order',
+            schema: { type: 'array', items: { type: 'string' } },
+          },
+          {
+            name: 'writingSystem',
+            required: true,
+            summary: 'BCP 47 tag of the writing system the forms are in',
+            schema: { type: 'string' },
+          },
+        ],
+        result: editResult,
+      },
+    },
+  );
+
+  const deleteMorphemesCommandRegistration = await papi.commands.registerCommand(
+    'interlinearizer.deleteMorphemes',
+    deleteMorphemes,
+    {
+      method: {
+        summary: "Remove a token's morpheme breakdown",
+        params: [sessionIdParam, tokenParams[0]],
+        result: editResult,
+      },
+    },
+  );
+
+  const writeMorphemeGlossCommandRegistration = await papi.commands.registerCommand(
+    'interlinearizer.writeMorphemeGloss',
+    writeMorphemeGloss,
+    {
+      method: {
+        summary:
+          "Gloss one morpheme of a token's breakdown in a session's analysis language; a blank value clears it",
+        params: [
+          sessionIdParam,
+          tokenParams[0],
+          {
+            name: 'morphemeId',
+            required: true,
+            summary: 'MorphemeAnalysis.id of the morpheme glossed',
+            schema: { type: 'string' },
+          },
+          {
+            name: 'value',
+            required: true,
+            summary: 'The gloss',
+            schema: { type: 'string' },
+          },
+        ],
+        result: editResult,
+      },
+    },
+  );
+
   const checkIndexesCommandRegistration = await papi.commands.registerCommand(
     'interlinearizer.checkIndexes',
     checkIndexes,
@@ -1965,6 +2093,9 @@ export async function activate(context: ExecutionActivationContext): Promise<voi
     checkIndexesCommandRegistration,
     writeGlossCommandRegistration,
     approveAnalysisForTokenCommandRegistration,
+    writeMorphemesCommandRegistration,
+    deleteMorphemesCommandRegistration,
+    writeMorphemeGlossCommandRegistration,
     setPerfMarksCommandRegistration,
     readPerfCommandRegistration,
     updateProjectMetadataCommandRegistration,
diff --git a/src/services/commands/morphemeCommands.ts b/src/services/commands/morphemeCommands.ts
new file mode 100644
index 000000000..cae199a7f
--- /dev/null
+++ b/src/services/commands/morphemeCommands.ts
@@ -0,0 +1,160 @@
+import { reconcileMorphemes } from '../../utils/analysis-identity';
+import { isEmptyTokenAnalysis } from '../../utils/token-analysis-content';
+import type { ChangeBuffer } from './changeBuffer';
+import {
+  appendApprovedAnalysis,
+  detachEmptiedAnalysis,
+  forkSharedAnalysis,
+  isSharedByOtherTokens,
+  mergeIntoIdenticalPayload,
+  resolveApprovedAnalysis,
+  type TokenEdit,
+} from './tokenCommands';
+
+/** What writing a token's morpheme breakdown needs. */
+export type WriteMorphemesRequest = TokenEdit & {
+  /** BCP 47 tag of the writing system the forms are in, stamped on every morpheme. */
+  writingSystem: string;
+  /** Id a new or forked token analysis takes, spent only when the write makes one. */
+  analysisId: string;
+  /** The breakdown, in order; a form the token's breakdown already holds keeps its morpheme. */
+  morphemes: readonly { id: string; form: string }[];
+};
+
+/** What removing a token's morpheme breakdown needs. */
+export type DeleteMorphemesRequest = Pick<TokenEdit, 'tokenRef' | 'now'> & {
+  /** Id a forked token analysis takes, spent only when the removal forks a shared payload. */
+  analysisId: string;
+};
+
+/** What glossing one morpheme of a token's breakdown needs. */
+export type WriteMorphemeGlossRequest = Pick<TokenEdit, 'tokenRef' | 'now'> & {
+  /** `MorphemeAnalysis.id` of the morpheme glossed. */
+  morphemeId: string;
+  /** The gloss; blank clears the morpheme's gloss in `analysisLanguage`. */
+  value: string;
+  /** BCP 47 tag of the language the gloss is written in. */
+  analysisLanguage: string;
+  /** Id a forked token analysis takes, spent only when the edit forks a shared payload. */
+  analysisId: string;
+};
+
+/**
+ * Stages writing a token's morpheme breakdown. The edit is per token: a payload other tokens share
+ * is forked first. A form the breakdown already carried keeps its morpheme whole, so links to it
+ * survive; every morpheme takes `writingSystem`, and the breakdown is never left marked stale. An
+ * edit that makes the payload identical to another folds it in. A token with no approved analysis
+ * takes a content-identical stored one, or a new one.
+ */
+export async function writeMorphemes(
+  buffer: ChangeBuffer,
+  request: WriteMorphemesRequest,
+): Promise<void> {
+  const { tokenRef, surfaceText, writingSystem, analysisId, morphemes, now } = request;
+
+  const resolved = await resolveApprovedAnalysis(buffer, tokenRef);
+  if (resolved) {
+    const { link, analysis } = resolved;
+    const target = (await isSharedByOtherTokens(buffer, link, analysis.id))
+      ? forkSharedAnalysis(buffer, link, analysis, analysisId, now)
+      : analysis;
+    target.surfaceText = surfaceText;
+    target.updatedAt = now;
+    link.token.surfaceText = surfaceText;
+    link.updatedAt = now;
+    target.morphemes = reconcileMorphemes(target.morphemes, morphemes, writingSystem);
+    delete target.morphemesStale;
+    buffer.put('tokenAnalyses', target);
+    buffer.put('tokenAnalysisLinks', link);
+    await mergeIntoIdenticalPayload(buffer, target, now);
+    return;
+  }
+
+  await appendApprovedAnalysis(
+    buffer,
+    {
+      id: analysisId,
+      createdAt: now,
+      updatedAt: now,
+      surfaceText,
+      morphemes: morphemes.map(({ id, form }) => ({ id, form, writingSystem })),
+    },
+    request,
+  );
+}
+
+/**
+ * Stages removing a token's morpheme breakdown and its stale mark. The edit is per token: a payload
+ * other tokens share is forked first. A payload the removal leaves empty is detached from the token
+ * and goes once nothing links it; one left with content folds into an identical payload where there
+ * is one. It stages nothing for a token with no approved analysis, or one with no breakdown.
+ */
+export async function deleteMorphemes(
+  buffer: ChangeBuffer,
+  { tokenRef, analysisId, now }: DeleteMorphemesRequest,
+): Promise<void> {
+  const resolved = await resolveApprovedAnalysis(buffer, tokenRef);
+  if (!resolved?.analysis.morphemes) return;
+  const { link, analysis } = resolved;
+
+  const target = (await isSharedByOtherTokens(buffer, link, analysis.id))
+    ? forkSharedAnalysis(buffer, link, analysis, analysisId, now)
+    : analysis;
+  delete target.morphemes;
+  delete target.morphemesStale;
+  target.updatedAt = now;
+  link.updatedAt = now;
+  if (isEmptyTokenAnalysis(target)) {
+    await detachEmptiedAnalysis(buffer, target, link);
+    return;
+  }
+  buffer.put('tokenAnalyses', target);
+  buffer.put('tokenAnalysisLinks', link);
+  await mergeIntoIdenticalPayload(buffer, target, now);
+}
+
+/**
+ * Stages glossing one morpheme of a token's approved breakdown. The edit is per token: a payload
+ * other tokens share is forked first, the morpheme keeping its id on the fork. A blank value clears
+ * the gloss in `analysisLanguage`, dropping a gloss it leaves empty; the morpheme and its analysis
+ * stay. An edit or clear that makes the payload identical to another folds it in. It stages nothing
+ * for a token with no approved analysis, or one whose breakdown lacks the morpheme.
+ */
+export async function writeMorphemeGloss(
+  buffer: ChangeBuffer,
+  {
+    tokenRef,
+    morphemeId,
+    value,
+    analysisLanguage: lang,
+    analysisId,
+    now,
+  }: WriteMorphemeGlossRequest,
+): Promise<void> {
+  const resolved = await resolveApprovedAnalysis(buffer, tokenRef);
+  if (!resolved) return;
+  const { link, analysis } = resolved;
+  if (!analysis.morphemes?.some((m) => m.id === morphemeId)) return;
+
+  const target = (await isSharedByOtherTokens(buffer, link, analysis.id))
+    ? forkSharedAnalysis(buffer, link, analysis, analysisId, now)
+    : analysis;
+  const morpheme = target.morphemes?.find((m) => m.id === morphemeId);
+  /* v8 ignore next -- the fork keeps every morpheme id, so this always resolves */
+  if (!morpheme) return;
+
+  if (value.trim() === '') {
+    if (morpheme.gloss) {
+      delete morpheme.gloss[lang];
+      if (Object.keys(morpheme.gloss).length === 0) delete morpheme.gloss;
+    }
+  } else {
+    if (!morpheme.gloss) morpheme.gloss = {};
+    morpheme.gloss[lang] = value;
+  }
+  target.updatedAt = now;
+  link.updatedAt = now;
+  buffer.put('tokenAnalyses', target);
+  buffer.put('tokenAnalysisLinks', link);
+  await mergeIntoIdenticalPayload(buffer, target, now);
+}
diff --git a/src/services/commands/tokenCommands.ts b/src/services/commands/tokenCommands.ts
index a1921ad4e..c951c057c 100644
--- a/src/services/commands/tokenCommands.ts
+++ b/src/services/commands/tokenCommands.ts
@@ -5,7 +5,7 @@ import { clearAnalysisGloss, isEmptyTokenAnalysis } from '../../utils/token-anal
 import type { ChangeBuffer } from './changeBuffer';
 
 /** Where and when a token edit lands. */
-type TokenEdit = {
+export type TokenEdit = {
   /** `Token.ref` of the token edited. */
   tokenRef: string;
   /** The token's current surface text, refreshed on the records the edit touches. */
@@ -36,7 +36,7 @@ export type ApproveAnalysisRequest = TokenEdit & {
  * The token's approved link an approval tie picks, with its payload. Approved links naming no
  * stored payload are removed first, so they never persist or crowd the pick.
  */
-async function resolveApprovedAnalysis(
+export async function resolveApprovedAnalysis(
   buffer: ChangeBuffer,
   tokenRef: string,
 ): Promise<{ link: TokenAnalysisLink; analysis: TokenAnalysis } | undefined> {
@@ -56,7 +56,7 @@ async function resolveApprovedAnalysis(
 }
 
 /** Whether a token other than `link`'s links the payload `analysisId`, at any status. */
-async function isSharedByOtherTokens(
+export async function isSharedByOtherTokens(
   buffer: ChangeBuffer,
   link: TokenAnalysisLink,
   analysisId: string,
@@ -71,7 +71,7 @@ async function isSharedByOtherTokens(
  *
  * @returns The copy, staged; `link` is repointed but left for the caller to stage.
  */
-function forkSharedAnalysis(
+export function forkSharedAnalysis(
   buffer: ChangeBuffer,
   link: TokenAnalysisLink,
   analysis: TokenAnalysis,
@@ -109,6 +109,21 @@ async function approveHeldLink(
   return held;
 }
 
+/**
+ * Detaches `link` from the payload an edit through it emptied, which goes once nothing links it and
+ * otherwise stays, emptied, as the edit left it.
+ */
+export async function detachEmptiedAnalysis(
+  buffer: ChangeBuffer,
+  analysis: TokenAnalysis,
+  link: TokenAnalysisLink,
+): Promise<void> {
+  buffer.delete('tokenAnalysisLinks', link);
+  const { tokenAnalysisLinks } = await buffer.findLinksToAnalyses([analysis.id]);
+  if (tokenAnalysisLinks.length === 0) buffer.delete('tokenAnalyses', analysis);
+  else buffer.put('tokenAnalyses', analysis);
+}
+
 /** Removes the payload once no link of any status names it. */
 async function reclaimIfUnlinked(buffer: ChangeBuffer, analysis: TokenAnalysis): Promise<void> {
   const { tokenAnalysisLinks } = await buffer.findLinksToAnalyses([analysis.id]);
@@ -148,7 +163,7 @@ async function coalesceLinksPerToken(buffer: ChangeBuffer, analysisId: string):
  * payload moves to the survivor, which keeps its own timestamps, and a token linking both keeps one
  * link. The survivor's breakdown stays stale only when both payloads' were.
  */
-async function mergeIntoIdenticalPayload(
+export async function mergeIntoIdenticalPayload(
   buffer: ChangeBuffer,
   analysis: TokenAnalysis,
   now: string,
@@ -178,7 +193,7 @@ async function mergeIntoIdenticalPayload(
  * stored one where there is one and staging `analysis` otherwise. A non-approved link the token
  * holds to the shared payload is approved rather than joined by a second.
  */
-async function appendApprovedAnalysis(
+export async function appendApprovedAnalysis(
   buffer: ChangeBuffer,
   analysis: TokenAnalysis,
   { tokenRef, now, linkId }: TokenEdit,
@@ -223,10 +238,7 @@ export async function writeGloss(buffer: ChangeBuffer, request: WriteGlossReques
     if (isBlank) {
       clearAnalysisGloss(target, lang);
       if (isEmptyTokenAnalysis(target)) {
-        buffer.delete('tokenAnalysisLinks', link);
-        const { tokenAnalysisLinks } = await buffer.findLinksToAnalyses([target.id]);
-        if (tokenAnalysisLinks.length === 0) buffer.delete('tokenAnalyses', target);
-        else buffer.put('tokenAnalyses', target);
+        await detachEmptiedAnalysis(buffer, target, link);
         return;
       }
     } else {
diff --git a/src/types/interlinearizer.d.ts b/src/types/interlinearizer.d.ts
index 8355e47de..084dcee03 100644
--- a/src/types/interlinearizer.d.ts
+++ b/src/types/interlinearizer.d.ts
@@ -418,6 +418,45 @@ declare module 'papi-shared-types' {
       analysisId: string,
     ) => Promise<string>;
 
+    /**
+     * Writes a token's morpheme breakdown, each form in `writingSystem`.
+     *
+     * @returns A JSON string of the changes it applied.
+     * @throws If the session is read-only or not open, or the edit is refused or fails (logged
+     *   before rethrowing).
+     */
+    'interlinearizer.writeMorphemes': (
+      sessionId: string,
+      tokenRef: string,
+      surfaceText: string,
+      forms: string[],
+      writingSystem: string,
+    ) => Promise<string>;
+
+    /**
+     * Removes a token's morpheme breakdown.
+     *
+     * @returns A JSON string of the changes it applied.
+     * @throws If the session is read-only or not open, or the edit is refused or fails (logged
+     *   before rethrowing).
+     */
+    'interlinearizer.deleteMorphemes': (sessionId: string, tokenRef: string) => Promise<string>;
+
+    /**
+     * Glosses one morpheme of a token's breakdown in a session's analysis language; a blank value
+     * clears it.
+     *
+     * @returns A JSON string of the changes it applied.
+     * @throws If the session is read-only or not open, or the edit is refused or fails (logged
+     *   before rethrowing).
+     */
+    'interlinearizer.writeMorphemeGloss': (
+      sessionId: string,
+      tokenRef: string,
+      morphemeId: string,
+      value: string,
+    ) => Promise<string>;
+
     /**
      * Turns the extension host's timing entries on or off, discarding any it holds. Off until
      * turned on.

From e3561eec683125bc8972ddc99f0fdf349a45c499 Mon Sep 17 00:00:00 2001
From: Tim Haasdyk <tim_haasdyk@sil.org>
Date: Fri, 23 Oct 2026 18:07:11 +0200
Subject: [PATCH 08/22] Pin each keep case and the empty-gloss removal in
 deleteMorphemes parity

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../commands/morphemeCommands.parity.test.ts  | 52 +++++++++++++++++--
 1 file changed, 47 insertions(+), 5 deletions(-)

diff --git a/src/__tests__/services/commands/morphemeCommands.parity.test.ts b/src/__tests__/services/commands/morphemeCommands.parity.test.ts
index beb27d4ea..3df7ef29f 100644
--- a/src/__tests__/services/commands/morphemeCommands.parity.test.ts
+++ b/src/__tests__/services/commands/morphemeCommands.parity.test.ts
@@ -700,22 +700,64 @@ describe('deleteMorphemes parity with the reducer', () => {
       },
     ],
     [
-      'keeps a payload holding other content',
+      'removes the payload and its link when its gloss object is empty',
+      {
+        analysis: analysisOf(
+          [payload('ta-cats', 'cats', { gloss: {}, morphemes: CAT_S })],
+          [link('tl-cats', 'ta-cats', TOKEN)],
+        ),
+        expectStore: (store) => {
+          expect(store).toStrictEqual(emptyAnalysis());
+        },
+      },
+    ],
+    [
+      'keeps a payload holding a part of speech',
+      {
+        analysis: analysisOf(
+          [payload('ta-cats', 'cats', { morphemes: CAT_S, pos: 'n' })],
+          [link('tl-cats', 'ta-cats', TOKEN)],
+        ),
+        expectStore: (store) => {
+          expect(store.tokenAnalyses).toStrictEqual([
+            payload('ta-cats', 'cats', { updatedAt: NOW, pos: 'n' }),
+          ]);
+        },
+      },
+    ],
+    [
+      'keeps a payload holding features',
+      {
+        analysis: analysisOf(
+          [payload('ta-cats', 'cats', { morphemes: CAT_S, features: { Number: 'Pl' } })],
+          [link('tl-cats', 'ta-cats', TOKEN)],
+        ),
+        expectStore: (store) => {
+          expect(store.tokenAnalyses).toStrictEqual([
+            payload('ta-cats', 'cats', { updatedAt: NOW, features: { Number: 'Pl' } }),
+          ]);
+        },
+      },
+    ],
+    [
+      'keeps a payload holding a sense reference',
       {
         analysis: analysisOf(
           [
             payload('ta-cats', 'cats', {
               morphemes: CAT_S,
-              pos: 'n',
-              features: { Number: 'Pl' },
               glossSenseRef: { authority: 'fwlite', senseId: 's-cat' },
             }),
           ],
           [link('tl-cats', 'ta-cats', TOKEN)],
         ),
         expectStore: (store) => {
-          expect(store.tokenAnalyses[0]).toMatchObject({ pos: 'n', updatedAt: NOW });
-          expect(store.tokenAnalyses[0].morphemes).toBeUndefined();
+          expect(store.tokenAnalyses).toStrictEqual([
+            payload('ta-cats', 'cats', {
+              updatedAt: NOW,
+              glossSenseRef: { authority: 'fwlite', senseId: 's-cat' },
+            }),
+          ]);
         },
       },
     ],

From 6c59416211f494b0d002a354ce6a11314f5db429 Mon Sep 17 00:00:00 2001
From: Alex Rawlings <alex.rawlings@wycliffe.ca>
Date: Thu, 22 Oct 2026 09:55:36 -0600
Subject: [PATCH 09/22] Add apply with inverse capture and per-session undo
 (#441)

---
 AGENTS.md                                     |   2 +-
 .../analysis-repository-conformance.ts        | 420 +++++++++++++++++-
 src/__tests__/main.test.ts                    |  62 +++
 .../services/analysisSessions.test.ts         |  51 +++
 .../services/draftRepository.test.ts          | 129 ++++++
 src/__tests__/services/editHistory.test.ts    | 122 +++++
 src/__tests__/services/projectStorage.test.ts |  32 ++
 .../services/pt9ImportRepository.test.ts      |  12 +
 src/__tests__/utils/change-set.test.ts        | 197 ++++++++
 src/main.ts                                   |  67 +++
 src/services/analysisSessions.ts              |  32 +-
 src/services/draftRepository.ts               |  55 +++
 src/services/editHistory.ts                   |  60 +++
 src/services/projectStorage.ts                |  11 +-
 src/services/pt9ImportRepository.ts           |   6 +
 src/types/analysis-repository.ts              |  48 +-
 src/types/interlinearizer.d.ts                |  18 +
 src/utils/change-set.ts                       | 140 ++++++
 18 files changed, 1455 insertions(+), 9 deletions(-)
 create mode 100644 src/__tests__/services/editHistory.test.ts
 create mode 100644 src/__tests__/utils/change-set.test.ts
 create mode 100644 src/services/editHistory.ts
 create mode 100644 src/utils/change-set.ts

diff --git a/AGENTS.md b/AGENTS.md
index 12823d9a8..1a3163569 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -85,7 +85,7 @@ Saved projects are listed through [ProjectSummaries](src/services/projectSummari
 
 ### Sessions
 
-[AnalysisSessions](src/services/analysisSessions.ts) keeps the host's sessions, behind the `openSession`, `closeSession` and `setAnalysisLanguage` commands. A session is a handle on one source project's draft, paired with the interlinear project it saves to, or on a Paratext 9 import alone, read-only. A source has at most one session: opening another closes it. Each session runs its commands one at a time, through `run`, or `runEdit` for a command that changes stored analysis, which a read-only session refuses. The WebView doesn't use sessions yet.
+[AnalysisSessions](src/services/analysisSessions.ts) keeps the host's sessions, behind the `openSession`, `closeSession` and `setAnalysisLanguage` commands. A session is a handle on one source project's draft, paired with the interlinear project it saves to, or on a Paratext 9 import alone, read-only. A source has at most one session: opening another closes it. Each session runs its commands one at a time, through `run`, or `runEdit` for a command that changes stored analysis, which a read-only session refuses. An edit reaches the repository as a `ChangeSet` of whole-record puts and deletes, applied through the session's [EditHistory](src/services/editHistory.ts) so that undo can revert it; boundary changes ride in the change set's scope record. The WebView doesn't use sessions yet.
 
 ### Components
 
diff --git a/src/__tests__/analysis-repository-conformance.ts b/src/__tests__/analysis-repository-conformance.ts
index 13db04eed..1a35629bf 100644
--- a/src/__tests__/analysis-repository-conformance.ts
+++ b/src/__tests__/analysis-repository-conformance.ts
@@ -1,10 +1,11 @@
 /// <reference types="jest" />
 
 import type { DraftProject, TextAnalysis } from 'interlinearizer';
-import type { AnalysisRepository, DraftExport } from '../types/analysis-repository';
+import type { AnalysisRepository, ChangeSet, DraftExport } from '../types/analysis-repository';
 import { emptyAnalysis, emptyDraft } from '../types/empty-factories';
 import { CURRENT_MODEL_VERSION } from '../types/model-version';
 import { ReadOnlyAnalysisError } from '../types/read-only-analysis-error';
+import { scopeRecordOf } from '../utils/change-set';
 import { FIXTURE_STAMPS, makePhraseLink } from './test-helpers';
 
 /** One empty store an {@link AnalysisRepository} implementation keeps drafts in. */
@@ -203,6 +204,99 @@ function fullDraftWithoutGenesis(): DraftProject {
   };
 }
 
+/** One record of every kind in GEN, none of which {@link fullDraft} holds. */
+function newRecords() {
+  return {
+    segmentAnalyses: [
+      {
+        id: 'sa-gen',
+        ...FIXTURE_STAMPS,
+        surfaceText: 'In the beginning',
+        freeTranslation: { en: 'At first' },
+      },
+    ],
+    segmentAnalysisLinks: [
+      {
+        id: 'sl-gen',
+        analysisId: 'sa-gen',
+        ...FIXTURE_STAMPS,
+        status: 'approved' as const,
+        segmentId: 'GEN 1:1',
+      },
+    ],
+    tokenAnalyses: [{ id: 'ta-god', ...FIXTURE_STAMPS, surfaceText: 'God', gloss: { en: 'God' } }],
+    tokenAnalysisLinks: [tokenLink('tl-gen-god', 'ta-god', 'GEN 1:1:17', 'God')],
+    phraseAnalyses: [
+      {
+        id: 'pa-the-beginning',
+        ...FIXTURE_STAMPS,
+        surfaceText: 'the beginning',
+        gloss: { en: 'start' },
+      },
+    ],
+    phraseAnalysisLinks: [
+      makePhraseLink('pa-the-beginning', ['GEN 1:1:9', 'GEN 1:1:13'], ['the', 'beginning']),
+    ],
+  };
+}
+
+/** Puts {@link newRecords}, one list per record kind. */
+function puttingNewRecords(): ChangeSet {
+  const records = newRecords();
+  return {
+    intent: 'putNewRecords',
+    segmentAnalyses: { puts: records.segmentAnalyses, deletes: [] },
+    segmentAnalysisLinks: { puts: records.segmentAnalysisLinks, deletes: [] },
+    tokenAnalyses: { puts: records.tokenAnalyses, deletes: [] },
+    tokenAnalysisLinks: { puts: records.tokenAnalysisLinks, deletes: [] },
+    phraseAnalyses: { puts: records.phraseAnalyses, deletes: [] },
+    phraseAnalysisLinks: { puts: records.phraseAnalysisLinks, deletes: [] },
+  };
+}
+
+/** {@link fullDraft} holding {@link newRecords} as well. */
+function fullDraftWithNewRecords(): DraftProject {
+  const draft = fullDraft();
+  const records = newRecords();
+  const { analysis } = draft;
+  analysis.segmentAnalyses.push(...records.segmentAnalyses);
+  analysis.segmentAnalysisLinks.push(...records.segmentAnalysisLinks);
+  analysis.tokenAnalyses.push(...records.tokenAnalyses);
+  analysis.tokenAnalysisLinks.push(...records.tokenAnalysisLinks);
+  analysis.phraseAnalyses.push(...records.phraseAnalyses);
+  analysis.phraseAnalysisLinks.push(...records.phraseAnalysisLinks);
+  return draft;
+}
+
+/**
+ * Changes to {@link fullDraft} of every sort: new records and deleted ones in every kind, a replaced
+ * payload, and new boundaries in the scope's record.
+ */
+function mixedChanges(): ChangeSet {
+  const { analysis } = fullDraft();
+  const records = newRecords();
+  return {
+    intent: 'mixedChanges',
+    scope: {
+      ...scopeRecordOf(fullDraft()),
+      dirty: false,
+      segmentation: {
+        removedVerseStarts: [],
+        addedStarts: [{ tokenRef: 'GEN 1:1:9', surfaceText: 'beginning' }],
+      },
+    },
+    segmentAnalyses: { puts: records.segmentAnalyses, deletes: ['sa-exo'] },
+    segmentAnalysisLinks: { puts: records.segmentAnalysisLinks, deletes: ['sl-exo'] },
+    tokenAnalyses: {
+      puts: [{ ...analysis.tokenAnalyses[0], gloss: { en: 'and then' } }, ...records.tokenAnalyses],
+      deletes: ['ta-unlinked'],
+    },
+    tokenAnalysisLinks: { puts: records.tokenAnalysisLinks, deletes: ['tl-gen-beginning'] },
+    phraseAnalyses: { puts: records.phraseAnalyses, deletes: ['pa-in-the'] },
+    phraseAnalysisLinks: { puts: records.phraseAnalysisLinks, deletes: ['pa-in-the'] },
+  };
+}
+
 /**
  * The draft with each record list sorted by id. Lists of records promise no order, but the arrays
  * inside a record keep theirs.
@@ -689,6 +783,320 @@ export function describeAnalysisRepositoryConformance(
       });
     });
 
+    describe('apply', () => {
+      it('puts new records of every kind, for the same repository and a newly opened one to load', async () => {
+        const repository = await store.open(SOURCE);
+        await repository.replaceAll(fullDraft());
+
+        await repository.apply(puttingNewRecords());
+
+        await expect(load(repository)).resolves.toStrictEqual(inIdOrder(fullDraftWithNewRecords()));
+        await expect(reload(store)).resolves.toStrictEqual(inIdOrder(fullDraftWithNewRecords()));
+      });
+
+      it('replaces a stored record whole, dropping fields the put lacks', async () => {
+        const repository = await store.open(SOURCE);
+        await repository.replaceAll(fullDraft());
+        const bare = { id: 'ta-beginning', ...FIXTURE_STAMPS, surfaceText: 'beginning' };
+
+        await repository.apply({ intent: 'replace', tokenAnalyses: { puts: [bare], deletes: [] } });
+
+        const { analysis } = await reload(store);
+        expect(analysis.tokenAnalyses.find(({ id }) => id === 'ta-beginning')).toStrictEqual(bare);
+      });
+
+      it('deletes records of every kind', async () => {
+        const repository = await store.open(SOURCE);
+        await repository.replaceAll(fullDraft());
+
+        await repository.apply({
+          intent: 'deleteExodus',
+          segmentAnalyses: { puts: [], deletes: ['sa-exo'] },
+          segmentAnalysisLinks: { puts: [], deletes: ['sl-exo'] },
+          tokenAnalysisLinks: { puts: [], deletes: ['tl-exo-and'] },
+        });
+
+        await expect(reload(store)).resolves.toStrictEqual(
+          inIdOrder({
+            ...fullDraft(),
+            analysis: {
+              ...fullAnalysis(),
+              segmentAnalyses: [],
+              segmentAnalysisLinks: [],
+              tokenAnalysisLinks: fullAnalysis().tokenAnalysisLinks.filter(
+                ({ id }) => id !== 'tl-exo-and',
+              ),
+            },
+          }),
+        );
+      });
+
+      it('skips a delete of a record that is not stored, with nothing for its inverse to restore', async () => {
+        const repository = await store.open(SOURCE);
+        await repository.replaceAll(fullDraft());
+
+        const { inverse } = await repository.apply({
+          intent: 'deleteMissing',
+          tokenAnalyses: { puts: [], deletes: ['ta-missing'] },
+        });
+
+        expect(inverse).toStrictEqual({ intent: 'deleteMissing' });
+        await expect(reload(store)).resolves.toStrictEqual(inIdOrder(fullDraft()));
+      });
+
+      it('applies to a draft this repository never loaded', async () => {
+        await (await store.open(SOURCE)).replaceAll(fullDraft());
+
+        await (await store.open(SOURCE)).apply(puttingNewRecords());
+
+        await expect(reload(store)).resolves.toStrictEqual(inIdOrder(fullDraftWithNewRecords()));
+      });
+
+      it('applies to a draft never saved as to an empty one', async () => {
+        await (await store.open(SOURCE)).apply(puttingNewRecords());
+
+        await expect(reload(store)).resolves.toStrictEqual(
+          inIdOrder({ ...emptyDraft(SOURCE), analysis: { ...emptyAnalysis(), ...newRecords() } }),
+        );
+      });
+
+      it('builds each apply on the one before it', async () => {
+        const repository = await store.open(SOURCE);
+        const { tokenAnalyses, tokenAnalysisLinks } = newRecords();
+
+        await repository.apply({
+          intent: 'first',
+          tokenAnalyses: { puts: tokenAnalyses, deletes: [] },
+        });
+        await repository.apply({
+          intent: 'second',
+          tokenAnalysisLinks: { puts: tokenAnalysisLinks, deletes: [] },
+        });
+
+        await expect(reload(store)).resolves.toStrictEqual(
+          inIdOrder({
+            ...emptyDraft(SOURCE),
+            analysis: { ...emptyAnalysis(), tokenAnalyses, tokenAnalysisLinks },
+          }),
+        );
+      });
+
+      it('builds on a whole save made since the last apply', async () => {
+        const repository = await store.open(SOURCE);
+        await repository.apply(puttingNewRecords());
+        await repository.replaceAll(fullDraft());
+
+        await repository.apply({
+          intent: 'deleteUnlinked',
+          tokenAnalyses: { puts: [], deletes: ['ta-unlinked'] },
+        });
+
+        await expect(reload(store)).resolves.toStrictEqual(
+          inIdOrder({
+            ...fullDraft(),
+            analysis: {
+              ...fullAnalysis(),
+              tokenAnalyses: fullAnalysis().tokenAnalyses.filter(({ id }) => id !== 'ta-unlinked'),
+            },
+          }),
+        );
+      });
+
+      it('applies over a draft another repository replaced, once reloaded', async () => {
+        const repository = await store.open(SOURCE);
+        await repository.apply(puttingNewRecords());
+        await (await store.open(SOURCE)).replaceAll(fullDraft());
+        await repository.exportAll();
+
+        await repository.apply({
+          intent: 'deleteUnlinked',
+          tokenAnalyses: { puts: [], deletes: ['ta-unlinked'] },
+        });
+
+        await expect(reload(store)).resolves.toStrictEqual(
+          inIdOrder({
+            ...fullDraft(),
+            analysis: {
+              ...fullAnalysis(),
+              tokenAnalyses: fullAnalysis().tokenAnalyses.filter(({ id }) => id !== 'ta-unlinked'),
+            },
+          }),
+        );
+      });
+
+      it('saves an edit to a payload linked from several books, for both books to load', async () => {
+        const repository = await store.open(SOURCE);
+        await repository.replaceAll(fullDraft());
+        const edited = { ...fullAnalysis().tokenAnalyses[0], gloss: { en: 'and then' } };
+
+        await repository.apply({
+          intent: 'writeGloss',
+          tokenAnalyses: { puts: [edited], deletes: [] },
+        });
+
+        const { analysis } = await reload(store);
+        expect(analysis.tokenAnalyses.filter(({ id }) => id === 'ta-and')).toStrictEqual([edited]);
+        expect(
+          analysis.tokenAnalysisLinks.filter(({ analysisId }) => analysisId === 'ta-and'),
+        ).toHaveLength(2);
+      });
+
+      it("carries boundary changes in the scope's record", async () => {
+        const repository = await store.open(SOURCE);
+        await repository.replaceAll(fullDraft());
+        const segmentation = {
+          removedVerseStarts: [],
+          addedStarts: [{ tokenRef: 'GEN 1:1:9', surfaceText: 'beginning' }],
+        };
+
+        await repository.apply({
+          intent: 'splitSegment',
+          scope: { ...scopeRecordOf(fullDraft()), segmentation },
+        });
+
+        await expect(reload(store)).resolves.toStrictEqual(
+          inIdOrder({ ...fullDraft(), segmentation }),
+        );
+      });
+
+      it("clears the boundaries when the scope's record carries none", async () => {
+        const repository = await store.open(SOURCE);
+        await repository.replaceAll(fullDraft());
+        const { segmentation, ...withoutBoundaries } = scopeRecordOf(fullDraft());
+
+        await repository.apply({ intent: 'resetBoundaries', scope: withoutBoundaries });
+
+        const reloaded = await reload(store);
+        expect(segmentation).toBeDefined();
+        expect(reloaded).not.toHaveProperty('segmentation');
+      });
+
+      it('stamps what it applies with the current model version', async () => {
+        await (
+          await store.open(SOURCE)
+        ).apply({
+          intent: 'stamp',
+          scope: { ...scopeRecordOf(fullDraft()), modelVersion: CURRENT_MODEL_VERSION - 1 },
+        });
+
+        const { modelVersion } = await reload(store);
+
+        expect(modelVersion).toBe(CURRENT_MODEL_VERSION);
+      });
+
+      it('returns an inverse that undoes the changes, boundaries included', async () => {
+        const repository = await store.open(SOURCE);
+        await repository.replaceAll(fullDraft());
+
+        const { inverse } = await repository.apply(mixedChanges());
+        await repository.apply(inverse);
+
+        await expect(reload(store)).resolves.toStrictEqual(inIdOrder(fullDraft()));
+      });
+
+      it("redoes the changes when the inverse's inverse is applied", async () => {
+        const repository = await store.open(SOURCE);
+        await repository.replaceAll(fullDraft());
+        const { inverse } = await repository.apply(mixedChanges());
+        const changed = await reload(store);
+        const { inverse: redo } = await repository.apply(inverse);
+
+        await repository.apply(redo);
+
+        await expect(reload(store)).resolves.toStrictEqual(changed);
+      });
+
+      it('undoes the changes through a newly opened repository', async () => {
+        await (await store.open(SOURCE)).replaceAll(fullDraft());
+        const { inverse } = await (await store.open(SOURCE)).apply(mixedChanges());
+
+        await (await store.open(SOURCE)).apply(inverse);
+
+        await expect(reload(store)).resolves.toStrictEqual(inIdOrder(fullDraft()));
+      });
+
+      it('names the intent of the changes in their inverse, as JSON-plain values', async () => {
+        const repository = await store.open(SOURCE);
+        await repository.replaceAll(fullDraft());
+
+        const { inverse } = await repository.apply(mixedChanges());
+
+        expect(inverse.intent).toBe('mixedChanges');
+        expectJsonPlain(inverse);
+      });
+
+      it('stores what it was given, unaffected by later changes to the changes or their inverse', async () => {
+        const repository = await store.open(SOURCE);
+        const changes = puttingNewRecords();
+        const { inverse } = await repository.apply(changes);
+        const applied = await reload(store);
+
+        changes.tokenAnalyses?.puts.push({
+          id: 'ta-later',
+          ...FIXTURE_STAMPS,
+          surfaceText: 'later',
+        });
+        inverse.tokenAnalyses?.deletes.push('ta-later');
+        const [god] = changes.tokenAnalyses?.puts ?? [];
+        god.surfaceText = 'changed';
+
+        await expect(load(repository)).resolves.toStrictEqual(applied);
+        await repository.apply({ intent: 'nothing' });
+        await expect(reload(store)).resolves.toStrictEqual(applied);
+      });
+
+      it('refuses an id named twice in one record kind, applying nothing', async () => {
+        const repository = await store.open(SOURCE);
+        await repository.replaceAll(fullDraft());
+        const [and] = fullAnalysis().tokenAnalyses;
+
+        await expect(
+          repository.apply({
+            intent: 'conflicting',
+            tokenAnalyses: { puts: [{ ...and, gloss: { en: 'also' } }], deletes: ['ta-and'] },
+          }),
+        ).rejects.toThrow();
+
+        await expect(load(repository)).resolves.toStrictEqual(inIdOrder(fullDraft()));
+      });
+
+      it("refuses a scope's record of another source project, applying nothing", async () => {
+        const repository = await store.open(SOURCE);
+        await repository.replaceAll(fullDraft());
+
+        await expect(
+          repository.apply({
+            intent: 'wrongScope',
+            scope: { ...scopeRecordOf(fullDraft()), sourceProjectId: 'other-project' },
+          }),
+        ).rejects.toThrow();
+
+        await expect(reload(store)).resolves.toStrictEqual(inIdOrder(fullDraft()));
+      });
+
+      it('keeps the drafts of different source projects apart', async () => {
+        await (await store.open(SOURCE)).replaceAll(fullDraft());
+
+        await (await store.open('other-project')).apply(puttingNewRecords());
+
+        await expect(reload(store)).resolves.toStrictEqual(inIdOrder(fullDraft()));
+        await expect(reload(store, 'other-project')).resolves.toStrictEqual(
+          inIdOrder({
+            ...emptyDraft('other-project'),
+            analysis: { ...emptyAnalysis(), ...newRecords() },
+          }),
+        );
+      });
+
+      it('leaves a draft written by a newer build in place, refusing to apply over it', async () => {
+        await store.storeNewerBuildDraft(SOURCE);
+
+        await expect((await store.open(SOURCE)).apply(puttingNewRecords())).rejects.toThrow();
+
+        await expect((await store.open(SOURCE)).exportAll()).rejects.toThrow();
+      });
+    });
+
     describe('capabilities', () => {
       it("lets a source project's draft be written", async () => {
         expect((await store.open(SOURCE)).capabilities.readOnly).toBe(false);
@@ -755,6 +1163,16 @@ export function describeAnalysisRepositoryConformance(
         await expect(repository.markClean()).rejects.toThrow(ReadOnlyAnalysisError);
       });
 
+      it('refuses to apply changes, leaving what it loads unchanged', async () => {
+        const repository = await store.openReadOnly(fullDraft());
+
+        await expect(repository.apply(puttingNewRecords())).rejects.toThrow(ReadOnlyAnalysisError);
+
+        await expect(analysisOf(repository)).resolves.toStrictEqual(
+          inIdOrder(fullDraft()).analysis,
+        );
+      });
+
       it("keeps apart from the source project's draft", async () => {
         await (await store.open(SOURCE)).replaceAll(exodusOnlyDraft());
 
diff --git a/src/__tests__/main.test.ts b/src/__tests__/main.test.ts
index ca39346ab..5d00fe95b 100644
--- a/src/__tests__/main.test.ts
+++ b/src/__tests__/main.test.ts
@@ -5,6 +5,7 @@ import papiBackendMock from '@papi/backend';
 import { activate, deactivate } from '@main';
 import type { InterlinearizerOpenOptions } from '@main';
 import type { DraftProject, ProjectConfig } from 'interlinearizer';
+import { AnalysisSessions } from '../services/analysisSessions';
 import * as bookService from '../services/bookService';
 import * as hostPerf from '../services/hostPerf';
 import * as projectStorage from '../services/projectStorage';
@@ -397,6 +398,8 @@ describe('main', () => {
           'interlinearizer.openSession',
           'interlinearizer.closeSession',
           'interlinearizer.setAnalysisLanguage',
+          'interlinearizer.undoEdit',
+          'interlinearizer.redoEdit',
           'interlinearizer.openSelectProjectModal',
           'interlinearizer.openNewProjectModal',
           'interlinearizer.openProjectInfoModal',
@@ -1830,6 +1833,7 @@ describe('main', () => {
         exportForCopy: async () => ({ draft, unreadableBooks: [] }),
         replaceAll: async () => [],
         markClean: async () => {},
+        apply: async (changes) => ({ inverse: changes }),
       };
     }
 
@@ -1850,6 +1854,12 @@ describe('main', () => {
         setAnalysisLanguage: handler<
           (sessionId: string, analysisLanguage: string) => Promise<void>
         >('interlinearizer.setAnalysisLanguage'),
+        undoEdit: handler<(sessionId: string) => Promise<string | undefined>>(
+          'interlinearizer.undoEdit',
+        ),
+        redoEdit: handler<(sessionId: string) => Promise<string | undefined>>(
+          'interlinearizer.redoEdit',
+        ),
       };
     }
 
@@ -1960,6 +1970,58 @@ describe('main', () => {
       );
     });
 
+    it('replies to an undo with the changes it applied', async () => {
+      const reverted = { intent: 'writeGloss', tokenAnalyses: { puts: [], deletes: ['ta-1'] } };
+      jest.spyOn(AnalysisSessions.prototype, 'undo').mockResolvedValue(reverted);
+      const { undoEdit } = await activateSessionCommands();
+
+      await expect(undoEdit('session-id')).resolves.toBe(JSON.stringify(reverted));
+      expect(AnalysisSessions.prototype.undo).toHaveBeenCalledWith('session-id');
+    });
+
+    it('replies to an undo with nothing when there is no edit to undo', async () => {
+      const { openSession, undoEdit } = await activateSessionCommands();
+      const { sessionId } = JSON.parse(await openSession('src-project'));
+
+      await expect(undoEdit(sessionId)).resolves.toBeUndefined();
+    });
+
+    it('logs the error and rethrows when an undo fails', async () => {
+      const { undoEdit } = await activateSessionCommands();
+
+      await expect(undoEdit('not-a-session')).rejects.toThrow('no session not-a-session is open');
+      expect(__mockLogger.error).toHaveBeenCalledWith(
+        'Interlinearizer: failed to undo an edit in session not-a-session',
+        expect.any(Error),
+      );
+    });
+
+    it('replies to a redo with the changes it applied', async () => {
+      const remade = { intent: 'writeGloss', tokenAnalyses: { puts: [], deletes: ['ta-1'] } };
+      jest.spyOn(AnalysisSessions.prototype, 'redo').mockResolvedValue(remade);
+      const { redoEdit } = await activateSessionCommands();
+
+      await expect(redoEdit('session-id')).resolves.toBe(JSON.stringify(remade));
+      expect(AnalysisSessions.prototype.redo).toHaveBeenCalledWith('session-id');
+    });
+
+    it('replies to a redo with nothing when there is no undone edit', async () => {
+      const { openSession, redoEdit } = await activateSessionCommands();
+      const { sessionId } = JSON.parse(await openSession('src-project'));
+
+      await expect(redoEdit(sessionId)).resolves.toBeUndefined();
+    });
+
+    it('logs the error and rethrows when a redo fails', async () => {
+      const { redoEdit } = await activateSessionCommands();
+
+      await expect(redoEdit('not-a-session')).rejects.toThrow('no session not-a-session is open');
+      expect(__mockLogger.error).toHaveBeenCalledWith(
+        'Interlinearizer: failed to redo an edit in session not-a-session',
+        expect.any(Error),
+      );
+    });
+
     it('closes every session on deactivation', async () => {
       const { openSession } = await activateSessionCommands();
       await openSession('src-project');
diff --git a/src/__tests__/services/analysisSessions.test.ts b/src/__tests__/services/analysisSessions.test.ts
index 55c51a7c7..0d5688c03 100644
--- a/src/__tests__/services/analysisSessions.test.ts
+++ b/src/__tests__/services/analysisSessions.test.ts
@@ -422,6 +422,57 @@ describe('AnalysisSessions', () => {
     });
   });
 
+  describe('undo and redo', () => {
+    const putting = (id: string) => ({
+      intent: `put ${id}`,
+      tokenAnalyses: { puts: [{ id, ...FIXTURE_STAMPS, surfaceText: id }], deletes: [] },
+    });
+
+    /** The ids of the token payloads the source project's stored draft holds. */
+    async function storedIds(storage: ReturnType<typeof makeSessions>['storage']) {
+      const { draft } = await new DraftRepository(storage, SOURCE, silentLogger()).exportAll();
+      return draft.analysis.tokenAnalyses.map(({ id }) => id);
+    }
+
+    it("undoes and redoes an edit applied through the session's history", async () => {
+      const { sessions, storage } = makeSessions();
+      const { sessionId } = await sessions.open(SOURCE);
+      await sessions.runEdit(sessionId, (session) => session.history.apply(putting('a')));
+
+      await expect(sessions.undo(sessionId)).resolves.toStrictEqual({
+        intent: 'put a',
+        tokenAnalyses: { puts: [], deletes: ['a'] },
+      });
+      await expect(storedIds(storage)).resolves.toStrictEqual([]);
+      await expect(sessions.redo(sessionId)).resolves.toStrictEqual(putting('a'));
+      await expect(storedIds(storage)).resolves.toStrictEqual(['a']);
+    });
+
+    it('starts a reopened source with nothing to undo', async () => {
+      const { sessions } = makeSessions();
+      const earlier = await sessions.open(SOURCE);
+      await sessions.runEdit(earlier.sessionId, (session) => session.history.apply(putting('a')));
+
+      const { sessionId } = await sessions.open(SOURCE);
+
+      await expect(sessions.undo(sessionId)).resolves.toBeUndefined();
+    });
+
+    it("refuses an undo on a Paratext 9 import's session", async () => {
+      const { sessions } = makeSessions([makeImport()]);
+      const { sessionId } = await sessions.open(SOURCE, 'import-id');
+
+      await expect(sessions.undo(sessionId)).rejects.toThrow(ReadOnlyAnalysisError);
+    });
+
+    it("refuses a redo on a Paratext 9 import's session", async () => {
+      const { sessions } = makeSessions([makeImport()]);
+      const { sessionId } = await sessions.open(SOURCE, 'import-id');
+
+      await expect(sessions.redo(sessionId)).rejects.toThrow(ReadOnlyAnalysisError);
+    });
+  });
+
   describe('setAnalysisLanguage', () => {
     it('sets the language the commands sent after it read', async () => {
       const { sessions } = makeSessions();
diff --git a/src/__tests__/services/draftRepository.test.ts b/src/__tests__/services/draftRepository.test.ts
index 7fdbbb88f..e12aec981 100644
--- a/src/__tests__/services/draftRepository.test.ts
+++ b/src/__tests__/services/draftRepository.test.ts
@@ -248,4 +248,133 @@ describe('DraftRepository', () => {
       expect(records.has(draftAnalysisKey('src', 'GEN'))).toBe(false);
     });
   });
+
+  describe('apply', () => {
+    it('rewrites only the books whose records the changes alter', async () => {
+      const { storage, writes } = memoryStorage();
+      const repository = new DraftRepository(storage, 'src', silentLogger());
+      await repository.replaceAll(twoBookDraft());
+      writes.length = 0;
+      const [segment] = twoBookAnalysis().segmentAnalyses;
+
+      await repository.apply({
+        intent: 'writeFreeTranslation',
+        segmentAnalyses: {
+          puts: [{ ...segment, freeTranslation: { en: 'And then.' } }],
+          deletes: [],
+        },
+      });
+
+      expect(writes).toContain(draftAnalysisKey('src', 'EXO'));
+      expect(writes).not.toContain(draftAnalysisKey('src', 'GEN'));
+    });
+
+    it('builds on the stored draft after it was marked clean, keeping it clean', async () => {
+      const { storage } = memoryStorage();
+      const repository = new DraftRepository(storage, 'src', silentLogger());
+      await repository.replaceAll({ ...twoBookDraft(), dirty: true });
+      await repository.apply({ intent: 'nothing' });
+
+      await repository.markClean();
+      await repository.apply({
+        intent: 'deleteLink',
+        tokenAnalysisLinks: { puts: [], deletes: ['tl-GEN'] },
+      });
+
+      const { draft } = await new DraftRepository(storage, 'src', silentLogger()).exportAll();
+      expect(draft.dirty).toBe(false);
+      expect(draft.analysis.tokenAnalysisLinks.map(({ id }) => id)).toEqual(['tl-EXO']);
+    });
+
+    it('rewrites every book linking a payload it edits', async () => {
+      const { storage, records } = memoryStorage();
+      const repository = new DraftRepository(storage, 'src', silentLogger());
+      await repository.replaceAll(twoBookDraft());
+      const [payload] = twoBookAnalysis().tokenAnalyses;
+
+      await repository.apply({
+        intent: 'writeGloss',
+        tokenAnalyses: { puts: [{ ...payload, gloss: { en: 'and then' } }], deletes: [] },
+      });
+
+      expect(records.get(draftAnalysisKey('src', 'GEN'))).toContain('and then');
+      expect(records.get(draftAnalysisKey('src', 'EXO'))).toContain('and then');
+    });
+
+    describe('with a book whose shard could not be read', () => {
+      /** A repository that loaded {@link twoBookDraft} with its GEN shard unusable. */
+      async function loadedWithUnusableGenesis() {
+        const { storage, records, writes } = memoryStorage();
+        await new DraftRepository(storage, 'src', silentLogger()).replaceAll(twoBookDraft());
+        records.set(draftAnalysisKey('src', 'GEN'), 'not json');
+        const repository = new DraftRepository(storage, 'src', silentLogger());
+        await repository.exportAll();
+        writes.length = 0;
+        return { repository, records, writes };
+      }
+
+      it('refuses changes that reach that book, writing nothing', async () => {
+        const { repository, records, writes } = await loadedWithUnusableGenesis();
+        const [payload] = twoBookAnalysis().tokenAnalyses;
+
+        await expect(
+          repository.apply({
+            intent: 'writeGloss',
+            tokenAnalyses: { puts: [{ ...payload, gloss: { en: 'and then' } }], deletes: [] },
+            tokenAnalysisLinks: { puts: twoBookAnalysis().tokenAnalysisLinks, deletes: [] },
+          }),
+        ).rejects.toThrow('could not read the stored analysis of GEN');
+
+        expect(writes).toEqual([]);
+        expect(records.get(draftAnalysisKey('src', 'GEN'))).toBe('not json');
+      });
+
+      it('applies changes elsewhere, keeping its shard', async () => {
+        const { repository, records } = await loadedWithUnusableGenesis();
+        const [segment] = twoBookAnalysis().segmentAnalyses;
+
+        await repository.apply({
+          intent: 'writeFreeTranslation',
+          segmentAnalyses: {
+            puts: [{ ...segment, freeTranslation: { en: 'And then.' } }],
+            deletes: [],
+          },
+        });
+
+        expect(records.get(draftAnalysisKey('src', 'EXO'))).toContain('And then.');
+        expect(records.get(draftAnalysisKey('src', 'GEN'))).toBe('not json');
+      });
+    });
+
+    it('keeps its draft as it was when a write fails, so the next apply leaves the failed one out', async () => {
+      const { storage, records } = memoryStorage();
+      const repository = new DraftRepository(storage, 'src', silentLogger());
+      await repository.replaceAll(twoBookDraft());
+      const [payload] = twoBookAnalysis().tokenAnalyses;
+      const [segment] = twoBookAnalysis().segmentAnalyses;
+      const write = jest.spyOn(storage, 'write').mockRejectedValueOnce(new Error('disk full'));
+
+      await expect(
+        repository.apply({
+          intent: 'writeGloss',
+          tokenAnalyses: { puts: [{ ...payload, gloss: { en: 'and then' } }], deletes: [] },
+        }),
+      ).rejects.toThrow('disk full');
+      write.mockRestore();
+      await repository.apply({
+        intent: 'writeFreeTranslation',
+        segmentAnalyses: {
+          puts: [{ ...segment, freeTranslation: { en: 'And then.' } }],
+          deletes: [],
+        },
+      });
+
+      const {
+        draft: { analysis },
+      } = await new DraftRepository(storage, 'src', silentLogger()).exportAll();
+      expect(analysis.tokenAnalyses[0].gloss).toEqual({ en: 'and' });
+      expect(analysis.segmentAnalyses[0].freeTranslation).toEqual({ en: 'And then.' });
+      expect(records.get(draftAnalysisKey('src', 'GEN'))).not.toContain('and then');
+    });
+  });
 });
diff --git a/src/__tests__/services/editHistory.test.ts b/src/__tests__/services/editHistory.test.ts
new file mode 100644
index 000000000..a1f15d58d
--- /dev/null
+++ b/src/__tests__/services/editHistory.test.ts
@@ -0,0 +1,122 @@
+/// <reference types="jest" />
+
+import type { TokenAnalysis } from 'interlinearizer';
+import { DraftRepository } from '../../services/draftRepository';
+import { EditHistory } from '../../services/editHistory';
+import type { ChangeSet } from '../../types/analysis-repository';
+import { FIXTURE_STAMPS, memoryStorage, silentLogger } from '../test-helpers';
+
+function payload(id: string): TokenAnalysis {
+  return { id, ...FIXTURE_STAMPS, surfaceText: id };
+}
+
+function putting(id: string): ChangeSet {
+  return { intent: `put ${id}`, tokenAnalyses: { puts: [payload(id)], deletes: [] } };
+}
+
+/** A history over an empty draft in memory, with a way to read back the stored payload ids. */
+function makeHistory() {
+  const { storage } = memoryStorage();
+  const repository = new DraftRepository(storage, 'src', silentLogger());
+  const storedIds = async () =>
+    (
+      await new DraftRepository(storage, 'src', silentLogger()).exportAll()
+    ).draft.analysis.tokenAnalyses
+      .map(({ id }) => id)
+      .sort();
+  return { history: new EditHistory(repository), repository, storedIds };
+}
+
+describe('EditHistory', () => {
+  it('applies an edit through its repository', async () => {
+    const { history, storedIds } = makeHistory();
+
+    await history.apply(putting('a'));
+
+    await expect(storedIds()).resolves.toStrictEqual(['a']);
+  });
+
+  it('undoes edits latest first, returning what reverted each', async () => {
+    const { history, storedIds } = makeHistory();
+    await history.apply(putting('a'));
+    await history.apply(putting('b'));
+
+    await expect(history.undo()).resolves.toStrictEqual({
+      intent: 'put b',
+      tokenAnalyses: { puts: [], deletes: ['b'] },
+    });
+    await expect(storedIds()).resolves.toStrictEqual(['a']);
+    await history.undo();
+    await expect(storedIds()).resolves.toStrictEqual([]);
+  });
+
+  it('redoes undone edits latest undone first, returning what made each again', async () => {
+    const { history, storedIds } = makeHistory();
+    await history.apply(putting('a'));
+    await history.apply(putting('b'));
+    await history.undo();
+    await history.undo();
+
+    await expect(history.redo()).resolves.toStrictEqual({
+      intent: 'put a',
+      tokenAnalyses: { puts: [payload('a')], deletes: [] },
+    });
+    await expect(storedIds()).resolves.toStrictEqual(['a']);
+    await history.redo();
+    await expect(storedIds()).resolves.toStrictEqual(['a', 'b']);
+  });
+
+  it('has nothing to undo before any edit', async () => {
+    await expect(makeHistory().history.undo()).resolves.toBeUndefined();
+  });
+
+  it('has nothing to redo before any undo', async () => {
+    const { history } = makeHistory();
+    await history.apply(putting('a'));
+
+    await expect(history.redo()).resolves.toBeUndefined();
+  });
+
+  it('drops the undone edits when a new edit is applied', async () => {
+    const { history, storedIds } = makeHistory();
+    await history.apply(putting('a'));
+    await history.undo();
+
+    await history.apply(putting('b'));
+
+    await expect(history.redo()).resolves.toBeUndefined();
+    await expect(storedIds()).resolves.toStrictEqual(['b']);
+  });
+
+  it('records no step for an edit that fails', async () => {
+    const { history, repository } = makeHistory();
+    jest.spyOn(repository, 'apply').mockRejectedValueOnce(new Error('disk full'));
+
+    await expect(history.apply(putting('a'))).rejects.toThrow('disk full');
+
+    await expect(history.undo()).resolves.toBeUndefined();
+  });
+
+  it('keeps an edit to undo when undoing it fails', async () => {
+    const { history, repository, storedIds } = makeHistory();
+    await history.apply(putting('a'));
+    jest.spyOn(repository, 'apply').mockRejectedValueOnce(new Error('disk full'));
+
+    await expect(history.undo()).rejects.toThrow('disk full');
+
+    await history.undo();
+    await expect(storedIds()).resolves.toStrictEqual([]);
+  });
+
+  it('keeps an undone edit to redo when redoing it fails', async () => {
+    const { history, repository, storedIds } = makeHistory();
+    await history.apply(putting('a'));
+    await history.undo();
+    jest.spyOn(repository, 'apply').mockRejectedValueOnce(new Error('disk full'));
+
+    await expect(history.redo()).rejects.toThrow('disk full');
+
+    await history.redo();
+    await expect(storedIds()).resolves.toStrictEqual(['a']);
+  });
+});
diff --git a/src/__tests__/services/projectStorage.test.ts b/src/__tests__/services/projectStorage.test.ts
index 40664973a..24a6a63ab 100644
--- a/src/__tests__/services/projectStorage.test.ts
+++ b/src/__tests__/services/projectStorage.test.ts
@@ -1574,6 +1574,24 @@ describe('projectStorage', () => {
         });
       });
 
+      it('leaves the stored draft dirty when changes were applied after the copy read it', async () => {
+        const stored = backStorageWithMap();
+        storeListedProject(stored, makeStubProject('proj-id'));
+        await saveDraft(token, 'src-proj', {
+          ...makeDraftSpanningBooks('src-proj', 'GEN'),
+          dirty: true,
+        });
+
+        const save = saveDraftToProject(token, 'src-proj', 'proj-id');
+        const apply = openDraftRepository(token, 'src-proj').apply({
+          intent: 'deleteLink',
+          tokenAnalysisLinks: { puts: [], deletes: ['link-GEN'] },
+        });
+        await Promise.all([save, apply]);
+
+        expect((await getDraft(token, 'src-proj')).draft.dirty).toBe(true);
+      });
+
       it('does not mark the draft clean when the project is gone', async () => {
         backStorageWithMap();
         await saveDraft(token, 'src-proj', {
@@ -2883,6 +2901,20 @@ describe('projectStorage', () => {
       expect(writtenKeys()).not.toContain('draft:src-proj:analysis:JHN');
     });
 
+    it('applies changes to the draft saveDraft saved', async () => {
+      await saveDraft(token, 'src-proj', makeDraftSpanningBooks('src-proj', 'GEN'));
+
+      await openDraftRepository(token, 'src-proj').apply({
+        intent: 'deleteLink',
+        tokenAnalysisLinks: { puts: [], deletes: ['link-GEN'] },
+      });
+
+      const {
+        draft: { analysis },
+      } = await getDraft(token, 'src-proj');
+      expect(analysis.tokenAnalysisLinks).toStrictEqual([]);
+    });
+
     it('waits for a draft call already made before reading', async () => {
       let finishWrite: () => void = () => {};
       __mockWriteUserData.mockImplementationOnce(
diff --git a/src/__tests__/services/pt9ImportRepository.test.ts b/src/__tests__/services/pt9ImportRepository.test.ts
index 111d87f06..8a8c29420 100644
--- a/src/__tests__/services/pt9ImportRepository.test.ts
+++ b/src/__tests__/services/pt9ImportRepository.test.ts
@@ -115,4 +115,16 @@ describe('Pt9ImportRepository', () => {
       expect(readProject).not.toHaveBeenCalled();
     });
   });
+
+  describe('apply', () => {
+    it('refuses every change', async () => {
+      const readProject = jest.fn(async () => makeImport());
+      const repository: AnalysisRepository = new Pt9ImportRepository('import-id', readProject);
+
+      await expect(repository.apply({ intent: 'writeGloss' })).rejects.toThrow(
+        ReadOnlyAnalysisError,
+      );
+      expect(readProject).not.toHaveBeenCalled();
+    });
+  });
 });
diff --git a/src/__tests__/utils/change-set.test.ts b/src/__tests__/utils/change-set.test.ts
new file mode 100644
index 000000000..e07b209f8
--- /dev/null
+++ b/src/__tests__/utils/change-set.test.ts
@@ -0,0 +1,197 @@
+/// <reference types="jest" />
+
+import type { DraftProject, TokenAnalysis } from 'interlinearizer';
+import { emptyAnalysis, emptyDraft } from '../../types/empty-factories';
+import { applyChangeSet, scopeRecordOf } from '../../utils/change-set';
+import { FIXTURE_STAMPS } from '../test-helpers';
+
+function payload(id: string, gloss?: string): TokenAnalysis {
+  return { id, ...FIXTURE_STAMPS, surfaceText: id, ...(gloss && { gloss: { en: gloss } }) };
+}
+
+function draftOf(...tokenAnalyses: TokenAnalysis[]): DraftProject {
+  return {
+    ...emptyDraft('src'),
+    analysisLanguages: ['en'],
+    analysis: { ...emptyAnalysis(), tokenAnalyses },
+  };
+}
+
+describe('scopeRecordOf', () => {
+  it("returns the draft's record without its analysis", () => {
+    const draft = { ...draftOf(payload('a')), suggestedName: 'Draft' };
+
+    expect(scopeRecordOf(draft)).toStrictEqual({
+      sourceProjectId: 'src',
+      modelVersion: draft.modelVersion,
+      analysisLanguages: ['en'],
+      suggestedName: 'Draft',
+      dirty: false,
+    });
+  });
+});
+
+describe('applyChangeSet', () => {
+  it('puts a new record after those stored, restored by deleting it', () => {
+    const { draft, inverse } = applyChangeSet(draftOf(payload('a')), {
+      intent: 'add',
+      tokenAnalyses: { puts: [payload('b')], deletes: [] },
+    });
+
+    expect(draft.analysis.tokenAnalyses).toStrictEqual([payload('a'), payload('b')]);
+    expect(inverse).toStrictEqual({
+      intent: 'add',
+      tokenAnalyses: { puts: [], deletes: ['b'] },
+    });
+  });
+
+  it('replaces a stored record in its place, restored by putting it back', () => {
+    const { draft, inverse } = applyChangeSet(draftOf(payload('a'), payload('b'), payload('c')), {
+      intent: 'edit',
+      tokenAnalyses: { puts: [payload('b', 'bee')], deletes: [] },
+    });
+
+    expect(draft.analysis.tokenAnalyses).toStrictEqual([
+      payload('a'),
+      payload('b', 'bee'),
+      payload('c'),
+    ]);
+    expect(inverse.tokenAnalyses).toStrictEqual({ puts: [payload('b')], deletes: [] });
+  });
+
+  it('deletes a stored record, restored by putting it back', () => {
+    const { draft, inverse } = applyChangeSet(draftOf(payload('a'), payload('b')), {
+      intent: 'delete',
+      tokenAnalyses: { puts: [], deletes: ['a'] },
+    });
+
+    expect(draft.analysis.tokenAnalyses).toStrictEqual([payload('b')]);
+    expect(inverse.tokenAnalyses).toStrictEqual({ puts: [payload('a')], deletes: [] });
+  });
+
+  it('leaves out of the inverse a kind whose changes replaced and added nothing', () => {
+    const { inverse } = applyChangeSet(draftOf(payload('a')), {
+      intent: 'deleteMissing',
+      tokenAnalyses: { puts: [], deletes: ['missing'] },
+    });
+
+    expect(inverse).toStrictEqual({ intent: 'deleteMissing' });
+  });
+
+  it("puts the scope's record, restored by putting the one it replaced", () => {
+    const stored = { ...draftOf(), dirty: true, suggestedName: 'Old' };
+    const scope = {
+      ...scopeRecordOf(draftOf()),
+      segmentation: { removedVerseStarts: ['GEN 1:2'], addedStarts: [] },
+    };
+
+    const { draft, inverse } = applyChangeSet(stored, { intent: 'boundaries', scope });
+
+    expect(draft).toStrictEqual({ ...scope, analysis: stored.analysis });
+    expect(inverse.scope).toStrictEqual(scopeRecordOf(stored));
+  });
+
+  it('leaves the draft it was given as it was', () => {
+    const stored = draftOf(payload('a'));
+
+    applyChangeSet(stored, {
+      intent: 'edit',
+      scope: { ...scopeRecordOf(stored), dirty: true },
+      tokenAnalyses: { puts: [payload('a', 'ay'), payload('b')], deletes: [] },
+    });
+
+    expect(stored).toStrictEqual(draftOf(payload('a')));
+  });
+
+  it('holds copies of the records the changes put', () => {
+    const put = payload('b');
+    const scope = scopeRecordOf(draftOf());
+    const { draft } = applyChangeSet(draftOf(), {
+      intent: 'add',
+      scope,
+      tokenAnalyses: { puts: [put], deletes: [] },
+    });
+
+    put.surfaceText = 'changed';
+    scope.analysisLanguages.push('fr');
+
+    expect(draft.analysis.tokenAnalyses).toStrictEqual([payload('b')]);
+    expect(draft.analysisLanguages).toStrictEqual(['en']);
+  });
+
+  it('refuses an id both put and deleted', () => {
+    expect(() =>
+      applyChangeSet(draftOf(payload('a')), {
+        intent: 'conflict',
+        tokenAnalyses: { puts: [payload('a', 'ay')], deletes: ['a'] },
+      }),
+    ).toThrow('a change set names token analysis record a more than once');
+  });
+
+  it('refuses an id put twice', () => {
+    expect(() =>
+      applyChangeSet(draftOf(), {
+        intent: 'conflict',
+        tokenAnalyses: { puts: [payload('a'), payload('a', 'ay')], deletes: [] },
+      }),
+    ).toThrow('a change set names token analysis record a more than once');
+  });
+
+  it("refuses a scope's record of another source project", () => {
+    expect(() =>
+      applyChangeSet(draftOf(), {
+        intent: 'wrongScope',
+        scope: { ...scopeRecordOf(draftOf()), sourceProjectId: 'other' },
+      }),
+    ).toThrow('a change set for source project other cannot apply to the draft of src');
+  });
+
+  it('applies the changes of every record kind', () => {
+    const link = {
+      id: 'link',
+      analysisId: 'a',
+      ...FIXTURE_STAMPS,
+      status: 'approved' as const,
+    };
+    const { draft } = applyChangeSet(draftOf(), {
+      intent: 'everyKind',
+      segmentAnalyses: { puts: [{ id: 'sa', ...FIXTURE_STAMPS, surfaceText: 'In' }], deletes: [] },
+      segmentAnalysisLinks: {
+        puts: [{ ...link, id: 'sl', analysisId: 'sa', segmentId: 'GEN 1:1' }],
+        deletes: [],
+      },
+      tokenAnalyses: { puts: [payload('a')], deletes: [] },
+      tokenAnalysisLinks: {
+        puts: [{ ...link, id: 'tl', token: { tokenRef: 'GEN 1:1:0', surfaceText: 'In' } }],
+        deletes: [],
+      },
+      phraseAnalyses: {
+        puts: [{ id: 'pa', ...FIXTURE_STAMPS, surfaceText: 'In the' }],
+        deletes: [],
+      },
+      phraseAnalysisLinks: {
+        puts: [
+          {
+            ...link,
+            id: 'pl',
+            analysisId: 'pa',
+            tokens: [{ tokenRef: 'GEN 1:1:0', surfaceText: 'In' }],
+          },
+        ],
+        deletes: [],
+      },
+    });
+
+    const { analysis } = draft;
+    expect(
+      [
+        analysis.segmentAnalyses,
+        analysis.segmentAnalysisLinks,
+        analysis.tokenAnalyses,
+        analysis.tokenAnalysisLinks,
+        analysis.phraseAnalyses,
+        analysis.phraseAnalysisLinks,
+      ].map((records) => records.map(({ id }) => id)),
+    ).toStrictEqual([['sa'], ['sl'], ['a'], ['tl'], ['pa'], ['pl']]);
+  });
+});
diff --git a/src/main.ts b/src/main.ts
index 2a0ee018f..6d5af1dcb 100644
--- a/src/main.ts
+++ b/src/main.ts
@@ -773,6 +773,40 @@ async function setAnalysisLanguage(sessionId: string, analysisLanguage: string):
   }
 }
 
+/**
+ * Reverts a session's latest edit not yet undone.
+ *
+ * @returns The changes that reverted it, as JSON, or `undefined` when there is none.
+ * @throws If the session is read-only or not open, or the changes cannot be applied. The error is
+ *   logged before rethrowing.
+ */
+async function undoEdit(sessionId: string): Promise<string | undefined> {
+  try {
+    const changes = await sessions.undo(sessionId);
+    return changes && JSON.stringify(changes);
+  } catch (e) {
+    logger.error(`Interlinearizer: failed to undo an edit in session ${sessionId}`, e);
+    throw e;
+  }
+}
+
+/**
+ * Redoes a session's latest undone edit.
+ *
+ * @returns The changes that redid it, as JSON, or `undefined` when there is none.
+ * @throws If the session is read-only or not open, or the changes cannot be applied. The error is
+ *   logged before rethrowing.
+ */
+async function redoEdit(sessionId: string): Promise<string | undefined> {
+  try {
+    const changes = await sessions.redo(sessionId);
+    return changes && JSON.stringify(changes);
+  } catch (e) {
+    logger.error(`Interlinearizer: failed to redo an edit in session ${sessionId}`, e);
+    throw e;
+  }
+}
+
 /**
  * Returns a summary of every interlinearizer project for the given source project as a JSON string.
  * The WebView deserializes this to populate its project picker and to decide whether to prompt
@@ -1347,6 +1381,37 @@ export async function activate(context: ExecutionActivationContext): Promise<voi
     },
   );
 
+  /** The result of a command that replies with the changes it applied, if any. */
+  const appliedChangesResult = {
+    name: 'return value',
+    summary: 'JSON-stringified ChangeSet it applied; omitted when there was nothing to apply',
+    schema: { type: 'string' },
+  } as const;
+
+  const undoEditCommandRegistration = await papi.commands.registerCommand(
+    'interlinearizer.undoEdit',
+    undoEdit,
+    {
+      method: {
+        summary: "Revert a session's latest edit not yet undone",
+        params: [sessionIdParam],
+        result: appliedChangesResult,
+      },
+    },
+  );
+
+  const redoEditCommandRegistration = await papi.commands.registerCommand(
+    'interlinearizer.redoEdit',
+    redoEdit,
+    {
+      method: {
+        summary: "Make a session's latest undone edit again",
+        params: [sessionIdParam],
+        result: appliedChangesResult,
+      },
+    },
+  );
+
   const setPerfMarksCommandRegistration = await papi.commands.registerCommand(
     'interlinearizer.setPerfMarks',
     async (enabled: boolean) => setHostPerfMarks(enabled),
@@ -1720,6 +1785,8 @@ export async function activate(context: ExecutionActivationContext): Promise<voi
     openSessionCommandRegistration,
     closeSessionCommandRegistration,
     setAnalysisLanguageCommandRegistration,
+    undoEditCommandRegistration,
+    redoEditCommandRegistration,
     setPerfMarksCommandRegistration,
     readPerfCommandRegistration,
     updateProjectMetadataCommandRegistration,
diff --git a/src/services/analysisSessions.ts b/src/services/analysisSessions.ts
index b47e5166f..29bae4c82 100644
--- a/src/services/analysisSessions.ts
+++ b/src/services/analysisSessions.ts
@@ -1,7 +1,8 @@
-import type { AnalysisRepository } from '../types/analysis-repository';
+import type { AnalysisRepository, ChangeSet } from '../types/analysis-repository';
 import { ReadOnlyAnalysisError } from '../types/read-only-analysis-error';
 import type { InterlinearProjectSummary } from '../types/interlinear-project-summary';
 import { analysisHasFreeTranslations } from '../utils/free-translations';
+import { EditHistory } from './editHistory';
 
 /** BCP 47 tag for a language that cannot be determined. */
 export const UNDETERMINED_LANGUAGE = 'und';
@@ -34,6 +35,8 @@ export type Session = {
   readonly id: string;
   readonly scope: SessionScope;
   readonly repository: AnalysisRepository;
+  /** Every edit to the session's analysis is applied through it, so that undo can revert each one. */
+  readonly history: EditHistory;
   /** BCP 47 tag of the language that glosses are read and written in. */
   analysisLanguage: string;
 };
@@ -94,7 +97,7 @@ export class AnalysisSessions {
    * Opens a session read-only on `interlinearProjectId` when it names a Paratext 9 import,
    * otherwise on the source project's draft, which saves to `interlinearProjectId` when given.
    * Opening closes the source's earlier session, if any, and starts the new one on what storage
-   * holds.
+   * holds, with nothing to undo.
    *
    * The session starts on the opened draft's first analysis language. When the draft lists none, it
    * starts on the platform's first interface language, or {@link UNDETERMINED_LANGUAGE} when the
@@ -119,6 +122,7 @@ export class AnalysisSessions {
         id: crypto.randomUUID(),
         scope,
         repository,
+        history: new EditHistory(repository),
         analysisLanguage:
           opened.analysisLanguages[0] ??
           ((await this.host.getInterfaceLanguages())[0] || UNDETERMINED_LANGUAGE),
@@ -198,6 +202,30 @@ export class AnalysisSessions {
     return this.run(sessionId, edit);
   }
 
+  /**
+   * Reverts the session's latest edit not yet undone.
+   *
+   * @returns The changes that reverted it, or `undefined` when there is none.
+   * @throws {ReadOnlyAnalysisError} If the session is read-only.
+   * @throws {Error} If the session is not open.
+   * @throws Whatever applying the changes throws; the edit stays the next to undo.
+   */
+  undo(sessionId: string): Promise<ChangeSet | undefined> {
+    return this.runEdit(sessionId, (session) => session.history.undo());
+  }
+
+  /**
+   * Redoes the session's latest undone edit.
+   *
+   * @returns The changes that redid it, or `undefined` when there is none.
+   * @throws {ReadOnlyAnalysisError} If the session is read-only.
+   * @throws {Error} If the session is not open.
+   * @throws Whatever applying the changes throws; the edit stays the next to redo.
+   */
+  redo(sessionId: string): Promise<ChangeSet | undefined> {
+    return this.runEdit(sessionId, (session) => session.history.redo());
+  }
+
   /**
    * Resolves the scope for a session on the source project, paired with `interlinearProjectId` when
    * given.
diff --git a/src/services/draftRepository.ts b/src/services/draftRepository.ts
index 7b5c71c8e..a81e8f72d 100644
--- a/src/services/draftRepository.ts
+++ b/src/services/draftRepository.ts
@@ -1,6 +1,8 @@
 import type { DraftProject, TextAnalysis } from 'interlinearizer';
 import type {
   AnalysisRepository,
+  ApplyResult,
+  ChangeSet,
   DraftExport,
   KeyValueStorage,
   ReplaceAllOptions,
@@ -17,6 +19,7 @@ import {
 } from '../types/type-guards';
 import { mergeAnalyses, splitAnalysisByBook } from '../utils/analysis-book';
 import { reportAnalysisViolations } from '../utils/analysis-violations';
+import { applyChangeSet } from '../utils/change-set';
 import { perfTime, perfTimeAsync, perfTimeAsyncExcluding } from '../utils/perf-marks';
 import { draftAnalysisKey, draftJournalKey, draftKey } from './storageKeys';
 
@@ -125,6 +128,13 @@ export class DraftRepository implements AnalysisRepository {
   /** Whether this instance has loaded the stored draft, so it knows which shards it cannot read. */
   private loaded = false;
 
+  /**
+   * The draft as this instance's last apply left it, which the next apply builds on. Dropped by
+   * every load and by every write but an apply, since each may come from a caller holding another
+   * draft.
+   */
+  private current: DraftProject | undefined;
+
   constructor(storage: KeyValueStorage, sourceProjectId: string, logger: WarningLogger) {
     this.storage = storage;
     this.logger = logger;
@@ -153,6 +163,7 @@ export class DraftRepository implements AnalysisRepository {
    * @throws If storage rejects a read.
    */
   async exportAll(): Promise<DraftExport> {
+    this.current = undefined;
     const exported = await this.readDraft(false);
     this.loaded = true;
     return exported;
@@ -169,6 +180,7 @@ export class DraftRepository implements AnalysisRepository {
    * @throws If storage rejects a read.
    */
   async exportForCopy(): Promise<DraftExport> {
+    this.current = undefined;
     const exported = await this.readDraft(true);
     this.loaded = true;
     return exported;
@@ -184,6 +196,7 @@ export class DraftRepository implements AnalysisRepository {
    * @throws If storage rejects the read or the write.
    */
   async markClean(): Promise<void> {
+    this.current = undefined;
     const { sourceProjectId, storage } = this;
     const raw = await storage.read(draftKey(sourceProjectId));
     if (raw === undefined) return;
@@ -226,6 +239,7 @@ export class DraftRepository implements AnalysisRepository {
    * @throws If storage rejects a write.
    */
   async replaceAll(draft: DraftProject, options?: ReplaceAllOptions): Promise<string[]> {
+    this.current = undefined;
     if (!this.loaded) {
       try {
         await this.exportAll();
@@ -234,6 +248,42 @@ export class DraftRepository implements AnalysisRepository {
         if (!(e instanceof SyntaxError)) throw e;
       }
     }
+    return this.writeDraft(draft, options, { refuseUnreadable: false });
+  }
+
+  /**
+   * Applies the changes to the draft as this instance's last apply left it, or to the stored draft
+   * when it has made none since its last whole load or save. Only the books whose content the
+   * changes alter are rewritten, so an edit to a payload rewrites every book linking it.
+   *
+   * @throws {Error} If an id appears more than once in one record kind's changes, or the scope's
+   *   record names another source project; nothing is written.
+   * @throws {Error} If the changes reach a book whose shard could not be read; nothing is written.
+   * @throws {SyntaxError} If the draft's stored value contains invalid JSON.
+   * @throws {Error} If the stored draft was written by a newer build; nothing is written.
+   * @throws If storage rejects a read or a write, as {@link replaceAll} does; this instance's draft
+   *   is left as it was.
+   */
+  async apply(changes: ChangeSet): Promise<ApplyResult> {
+    this.current ??= (await this.exportAll()).draft;
+    const { draft, inverse } = applyChangeSet(this.current, changes);
+    await this.writeDraft(draft, undefined, { refuseUnreadable: true });
+    this.current = draft;
+    return { inverse };
+  }
+
+  /**
+   * Saves `draft` as {@link replaceAll} describes.
+   *
+   * @throws {Error} If `refuseUnreadable` is set and the draft carries analysis for a book whose
+   *   shard could not be read; nothing is written.
+   * @throws Whatever {@link replaceAll} throws.
+   */
+  private async writeDraft(
+    draft: DraftProject,
+    options: ReplaceAllOptions | undefined,
+    { refuseUnreadable }: { refuseUnreadable: boolean },
+  ): Promise<string[]> {
     const { sourceProjectId, storage, shardContents: saved, unreadableShards: unreadable } = this;
     const { analysis } = draft;
     const storedBooks = await perfTimeAsync('saveDraft:read', () =>
@@ -242,6 +292,11 @@ export class DraftRepository implements AnalysisRepository {
     const byBook = perfTime('saveDraft:compare', () => splitAnalysisByBook(analysis));
     if (options?.discardUnreadable) unreadable.clear();
     const leftOut = [...unreadable].filter((bookCode) => byBook.has(bookCode));
+    if (refuseUnreadable && leftOut.length > 0) {
+      throw new Error(
+        `Interlinearizer: the draft for ${sourceProjectId} could not read the stored analysis of ${leftOut.join(', ')}, so it refuses changes there`,
+      );
+    }
     leftOut.forEach((bookCode) => byBook.delete(bookCode));
 
     // Books this save no longer carries, less those held back because the load could not read them.
diff --git a/src/services/editHistory.ts b/src/services/editHistory.ts
new file mode 100644
index 000000000..d4c09be60
--- /dev/null
+++ b/src/services/editHistory.ts
@@ -0,0 +1,60 @@
+import type { AnalysisRepository, ChangeSet } from '../types/analysis-repository';
+
+/**
+ * A linear undo history of the edits applied through it to one repository. Each edit is one step,
+ * and a new edit drops every step undone before it.
+ */
+export class EditHistory {
+  private readonly repository: AnalysisRepository;
+
+  /** What reverts each edit not yet undone, latest last. */
+  private readonly undoable: ChangeSet[] = [];
+
+  /** What redoes each undone edit, latest last. */
+  private readonly redoable: ChangeSet[] = [];
+
+  constructor(repository: AnalysisRepository) {
+    this.repository = repository;
+  }
+
+  /**
+   * Applies `changes` as one undo step.
+   *
+   * @throws Whatever applying the changes throws; the history is left as it was.
+   */
+  async apply(changes: ChangeSet): Promise<void> {
+    const { inverse } = await this.repository.apply(changes);
+    this.undoable.push(inverse);
+    this.redoable.length = 0;
+  }
+
+  /**
+   * Reverts the latest edit not yet undone.
+   *
+   * @returns The changes that reverted it, or `undefined` when there is none.
+   * @throws Whatever applying those changes throws; the edit stays the next to undo.
+   */
+  undo(): Promise<ChangeSet | undefined> {
+    return this.step(this.undoable, this.redoable);
+  }
+
+  /**
+   * Redoes the latest undone edit.
+   *
+   * @returns The changes that redid it, or `undefined` when there is none.
+   * @throws Whatever applying those changes throws; the edit stays the next to redo.
+   */
+  redo(): Promise<ChangeSet | undefined> {
+    return this.step(this.redoable, this.undoable);
+  }
+
+  /** Applies the latest changes on `from`, moving what reverts them onto `to`. */
+  private async step(from: ChangeSet[], to: ChangeSet[]): Promise<ChangeSet | undefined> {
+    const changes = from.at(-1);
+    if (!changes) return undefined;
+    const { inverse } = await this.repository.apply(changes);
+    from.pop();
+    to.push(inverse);
+    return changes;
+  }
+}
diff --git a/src/services/projectStorage.ts b/src/services/projectStorage.ts
index 193cd1be5..e6eefe7a3 100644
--- a/src/services/projectStorage.ts
+++ b/src/services/projectStorage.ts
@@ -1121,15 +1121,18 @@ export function openDraftRepository(
     enqueueSerialized(draftQueues, sourceProjectId, () =>
       call(draftRepositoryFor(token, sourceProjectId)),
     );
+  // Counted when queued, so a copy can tell a write was sent after it read the draft.
+  const counted = <T>(call: (repository: DraftRepository) => Promise<T>) => {
+    draftWriteCounts.set(sourceProjectId, (draftWriteCounts.get(sourceProjectId) ?? 0) + 1);
+    return queued(call);
+  };
   return {
     capabilities: { readOnly: false },
     exportAll: () => queued((repository) => repository.exportAll()),
     exportForCopy: () => queued((repository) => repository.exportForCopy()),
-    replaceAll: (draft, options) => {
-      draftWriteCounts.set(sourceProjectId, (draftWriteCounts.get(sourceProjectId) ?? 0) + 1);
-      return queued((repository) => repository.replaceAll(draft, options));
-    },
+    replaceAll: (draft, options) => counted((repository) => repository.replaceAll(draft, options)),
     markClean: () => queued((repository) => repository.markClean()),
+    apply: (changes) => counted((repository) => repository.apply(changes)),
   };
 }
 
diff --git a/src/services/pt9ImportRepository.ts b/src/services/pt9ImportRepository.ts
index 2ad37f180..a8468b5a6 100644
--- a/src/services/pt9ImportRepository.ts
+++ b/src/services/pt9ImportRepository.ts
@@ -1,6 +1,7 @@
 import type { InterlinearProject } from 'interlinearizer';
 import type {
   AnalysisRepository,
+  ApplyResult,
   DraftExport,
   RepositoryCapabilities,
 } from '../types/analysis-repository';
@@ -80,6 +81,11 @@ export class Pt9ImportRepository implements AnalysisRepository {
     throw this.readOnlyError();
   }
 
+  /** @throws {ReadOnlyAnalysisError} Always; nothing is applied. */
+  async apply(): Promise<ApplyResult> {
+    throw this.readOnlyError();
+  }
+
   private readOnlyError(): ReadOnlyAnalysisError {
     return new ReadOnlyAnalysisError(
       `Interlinearizer: Paratext 9 import ${this.interlinearProjectId} is read-only`,
diff --git a/src/types/analysis-repository.ts b/src/types/analysis-repository.ts
index 27014f1c9..e19571e19 100644
--- a/src/types/analysis-repository.ts
+++ b/src/types/analysis-repository.ts
@@ -1,4 +1,4 @@
-import type { DraftProject } from 'interlinearizer';
+import type { DraftProject, TextAnalysis } from 'interlinearizer';
 
 /** Text records by key. */
 export interface KeyValueStorage {
@@ -56,6 +56,36 @@ export type DraftExport = {
   unreadableBooks: string[];
 };
 
+/** A draft's own record: everything in it but its analysis. */
+export type ScopeRecord = Omit<DraftProject, 'analysis'>;
+
+/** Whole-record puts and deletes of one record kind. */
+export type RecordChanges<T> = {
+  /** Records to store whole, each replacing any stored under its id. */
+  puts: T[];
+  /** Ids of records to remove; an id with nothing stored under it is skipped. */
+  deletes: string[];
+};
+
+/**
+ * One command's changes, applied all-or-nothing. A record kind it leaves alone is absent, and an id
+ * appears at most once in a kind's puts and deletes together.
+ */
+export type ChangeSet = {
+  /** Names the command that made the changes. */
+  intent: string;
+  /** The scope's record, whole, which carries boundary changes; absent when it is left alone. */
+  scope?: ScopeRecord;
+} & {
+  [Kind in keyof TextAnalysis]?: RecordChanges<TextAnalysis[Kind][number]>;
+};
+
+/** What applying a {@link ChangeSet} tells its caller. */
+export type ApplyResult = {
+  /** Restores what the applied changes replaced; applying it undoes them. */
+  inverse: ChangeSet;
+};
+
 /**
  * Reads and writes one source project's draft, or, when read-only, reads analysis in a draft's
  * shape. Every call is async and takes and returns only JSON-plain values, so an implementation may
@@ -122,4 +152,20 @@ export interface AnalysisRepository {
    * @throws If storage rejects a read or a write.
    */
   markClean(): Promise<void>;
+
+  /**
+   * Applies `changes` to the stored draft whole or not at all, stamped with this build's model
+   * version. A draft never saved counts as an empty one.
+   *
+   * @throws {ReadOnlyAnalysisError} If the repository is read-only; nothing is applied.
+   * @throws {Error} If an id appears more than once in one record kind's changes, or the scope's
+   *   record names another source project; nothing is applied.
+   * @throws {Error} If the changes reach a book whose stored analysis could not be read; nothing is
+   *   applied.
+   * @throws {SyntaxError} If the draft's stored value contains invalid JSON.
+   * @throws {Error} If the stored draft was written by a newer build; nothing is applied.
+   * @throws If storage rejects a read or a write. The draft as this repository holds it is
+   *   unchanged, though storage may hold some of the changes until a later save.
+   */
+  apply(changes: ChangeSet): Promise<ApplyResult>;
 }
diff --git a/src/types/interlinearizer.d.ts b/src/types/interlinearizer.d.ts
index 5177060be..06ab18d47 100644
--- a/src/types/interlinearizer.d.ts
+++ b/src/types/interlinearizer.d.ts
@@ -363,6 +363,24 @@ declare module 'papi-shared-types' {
       analysisLanguage: string,
     ) => Promise<void>;
 
+    /**
+     * Reverts a session's latest edit not yet undone.
+     *
+     * @returns The changes that reverted it, as JSON, or `undefined` when there is none.
+     * @throws If the session is read-only or not open, or the changes cannot be applied (logged
+     *   before rethrowing).
+     */
+    'interlinearizer.undoEdit': (sessionId: string) => Promise<string | undefined>;
+
+    /**
+     * Redoes a session's latest undone edit.
+     *
+     * @returns The changes that redid it, as JSON, or `undefined` when there is none.
+     * @throws If the session is read-only or not open, or the changes cannot be applied (logged
+     *   before rethrowing).
+     */
+    'interlinearizer.redoEdit': (sessionId: string) => Promise<string | undefined>;
+
     /**
      * Turns the extension host's timing entries on or off, discarding any it holds. Off until
      * turned on.
diff --git a/src/utils/change-set.ts b/src/utils/change-set.ts
new file mode 100644
index 000000000..ecc046174
--- /dev/null
+++ b/src/utils/change-set.ts
@@ -0,0 +1,140 @@
+import type { DraftProject } from 'interlinearizer';
+import type { ChangeSet, RecordChanges, ScopeRecord } from '../types/analysis-repository';
+
+/** A draft with a {@link ChangeSet} applied, and the change set that restores what it replaced. */
+export type AppliedChanges = {
+  draft: DraftProject;
+  inverse: ChangeSet;
+};
+
+/** A copy of a JSON-plain value that shares nothing with it. */
+function copyOf<T>(value: T): T {
+  return JSON.parse(JSON.stringify(value));
+}
+
+/** The draft's record, without its analysis. */
+// eslint-disable-next-line @typescript-eslint/no-unused-vars -- named only to leave it out
+export function scopeRecordOf({ analysis, ...scope }: DraftProject): ScopeRecord {
+  return scope;
+}
+
+/**
+ * Applies one record kind's changes to `records`.
+ *
+ * @returns The records the changes leave, and the changes that restore what they replaced, absent
+ *   when the changes replaced nothing and added nothing.
+ * @throws {Error} If an id appears more than once in the changes.
+ */
+function applyRecordChanges<T extends { id: string }>(
+  records: T[],
+  changes: RecordChanges<T> | undefined,
+  kind: string,
+): { records: T[]; inverse?: RecordChanges<T> } {
+  if (!changes) return { records };
+  const named = new Set<string>();
+  [...changes.puts.map(({ id }) => id), ...changes.deletes].forEach((id) => {
+    if (named.has(id)) {
+      throw new Error(`Interlinearizer: a change set names ${kind} record ${id} more than once`);
+    }
+    named.add(id);
+  });
+
+  const stored = new Map(records.map((record) => [record.id, record]));
+  const deleted = new Set(changes.deletes);
+  const puts = new Map(changes.puts.map((record) => [record.id, copyOf(record)]));
+  const inverse: RecordChanges<T> = { puts: [], deletes: [] };
+  changes.puts.forEach(({ id }) => {
+    const prior = stored.get(id);
+    if (prior) inverse.puts.push(prior);
+    else inverse.deletes.push(id);
+  });
+  changes.deletes.forEach((id) => {
+    const prior = stored.get(id);
+    if (prior) inverse.puts.push(prior);
+  });
+
+  // A replaced record keeps its place, so records nearby are left as they were.
+  const next = records.flatMap((record) => {
+    if (deleted.has(record.id)) return [];
+    return [puts.get(record.id) ?? record];
+  });
+  puts.forEach((record, id) => {
+    if (!stored.has(id)) next.push(record);
+  });
+  return {
+    records: next,
+    ...((inverse.puts.length > 0 || inverse.deletes.length > 0) && { inverse }),
+  };
+}
+
+/**
+ * Applies `changes` to `draft`, leaving `draft` as it was. The result holds copies of the records
+ * the changes put, and shares everything else with `draft`, the records the inverse restores
+ * included.
+ *
+ * @throws {Error} If an id appears more than once in one record kind's changes, or the scope's
+ *   record names another source project.
+ */
+export function applyChangeSet(draft: DraftProject, changes: ChangeSet): AppliedChanges {
+  if (changes.scope && changes.scope.sourceProjectId !== draft.sourceProjectId) {
+    throw new Error(
+      `Interlinearizer: a change set for source project ${changes.scope.sourceProjectId} cannot apply to the draft of ${draft.sourceProjectId}`,
+    );
+  }
+  const { analysis } = draft;
+  const segmentAnalyses = applyRecordChanges(
+    analysis.segmentAnalyses,
+    changes.segmentAnalyses,
+    'segment analysis',
+  );
+  const segmentAnalysisLinks = applyRecordChanges(
+    analysis.segmentAnalysisLinks,
+    changes.segmentAnalysisLinks,
+    'segment analysis link',
+  );
+  const tokenAnalyses = applyRecordChanges(
+    analysis.tokenAnalyses,
+    changes.tokenAnalyses,
+    'token analysis',
+  );
+  const tokenAnalysisLinks = applyRecordChanges(
+    analysis.tokenAnalysisLinks,
+    changes.tokenAnalysisLinks,
+    'token analysis link',
+  );
+  const phraseAnalyses = applyRecordChanges(
+    analysis.phraseAnalyses,
+    changes.phraseAnalyses,
+    'phrase analysis',
+  );
+  const phraseAnalysisLinks = applyRecordChanges(
+    analysis.phraseAnalysisLinks,
+    changes.phraseAnalysisLinks,
+    'phrase analysis link',
+  );
+
+  const inverse: ChangeSet = {
+    intent: changes.intent,
+    ...(changes.scope && { scope: scopeRecordOf(draft) }),
+    ...(segmentAnalyses.inverse && { segmentAnalyses: segmentAnalyses.inverse }),
+    ...(segmentAnalysisLinks.inverse && { segmentAnalysisLinks: segmentAnalysisLinks.inverse }),
+    ...(tokenAnalyses.inverse && { tokenAnalyses: tokenAnalyses.inverse }),
+    ...(tokenAnalysisLinks.inverse && { tokenAnalysisLinks: tokenAnalysisLinks.inverse }),
+    ...(phraseAnalyses.inverse && { phraseAnalyses: phraseAnalyses.inverse }),
+    ...(phraseAnalysisLinks.inverse && { phraseAnalysisLinks: phraseAnalysisLinks.inverse }),
+  };
+  return {
+    draft: {
+      ...(changes.scope ? copyOf(changes.scope) : scopeRecordOf(draft)),
+      analysis: {
+        segmentAnalyses: segmentAnalyses.records,
+        segmentAnalysisLinks: segmentAnalysisLinks.records,
+        tokenAnalyses: tokenAnalyses.records,
+        tokenAnalysisLinks: tokenAnalysisLinks.records,
+        phraseAnalyses: phraseAnalyses.records,
+        phraseAnalysisLinks: phraseAnalysisLinks.records,
+      },
+    },
+    inverse,
+  };
+}

From 8a500492ee1dfa91c54d5c3ba9ed05e57fe30966 Mon Sep 17 00:00:00 2001
From: Alex Rawlings <alex.rawlings@wycliffe.ca>
Date: Thu, 22 Oct 2026 10:20:18 -0600
Subject: [PATCH 10/22] Add derived indexes with a rebuild-and-diff command
 (#442)

---
 AGENTS.md                                     |   2 +-
 .../analysis-repository-conformance.ts        | 238 +++++++++++++++++-
 src/__tests__/main.test.ts                    |  38 +++
 src/__tests__/services/analysisIndex.test.ts  | 177 +++++++++++++
 .../services/draftRepository.test.ts          |  41 +++
 .../services/indexedRepository.test.ts        |  70 ++++++
 src/__tests__/services/projectStorage.test.ts |  37 +++
 .../services/pt9ImportRepository.test.ts      |  52 ++++
 src/__tests__/services/recordTable.test.ts    |  96 +++++++
 src/__tests__/utils/change-set.test.ts        |  16 --
 src/__tests__/utils/json-copy.test.ts         |  16 ++
 src/main.ts                                   |  37 +++
 src/services/analysisIndex.ts                 | 186 ++++++++++++++
 src/services/draftRepository.ts               |  50 +++-
 src/services/indexedRepository.ts             |  95 +++++++
 src/services/projectStorage.ts                |  15 ++
 src/services/pt9ImportRepository.ts           |  67 +++--
 src/services/recordTable.ts                   | 122 +++++++++
 src/types/analysis-repository.ts              |  69 ++++-
 src/types/interlinearizer.d.ts                |   9 +
 src/utils/change-set.ts                       |  13 +-
 src/utils/json-copy.ts                        |   4 +
 22 files changed, 1388 insertions(+), 62 deletions(-)
 create mode 100644 src/__tests__/services/analysisIndex.test.ts
 create mode 100644 src/__tests__/services/indexedRepository.test.ts
 create mode 100644 src/__tests__/services/recordTable.test.ts
 create mode 100644 src/__tests__/utils/json-copy.test.ts
 create mode 100644 src/services/analysisIndex.ts
 create mode 100644 src/services/indexedRepository.ts
 create mode 100644 src/services/recordTable.ts
 create mode 100644 src/utils/json-copy.ts

diff --git a/AGENTS.md b/AGENTS.md
index 1a3163569..435e6c976 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 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)). [Pt9ImportRepository](src/services/pt9ImportRepository.ts) serves a Paratext 9 import through the same seam, read-only.
+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)). [Pt9ImportRepository](src/services/pt9ImportRepository.ts) serves a Paratext 9 import through the same seam, read-only. Both answer the seam's lookups (by token ref, segment id, analysis id, normalized form, and book and status) from an [AnalysisIndex](src/services/analysisIndex.ts) built from the records on first use and kept current by `apply`; `checkIndexes` rebuilds it and reports any difference.
 
 [The conformance suite](src/__tests__/analysis-repository-conformance.ts) defines the seam: every `AnalysisRepository` implementation must pass it, and [draftRepository.conformance.test.ts](src/__tests__/services/draftRepository.conformance.test.ts) runs it against `DraftRepository` and `Pt9ImportRepository`. A behavior every implementation owes goes in the suite; one particular to an implementation, such as which shards a save rewrites, goes in that implementation's own tests. A later backend runs the suite by passing `describeAnalysisRepositoryConformance` a factory that returns a fresh `ConformanceStore` for each test.
 
diff --git a/src/__tests__/analysis-repository-conformance.ts b/src/__tests__/analysis-repository-conformance.ts
index 1a35629bf..3b60706dc 100644
--- a/src/__tests__/analysis-repository-conformance.ts
+++ b/src/__tests__/analysis-repository-conformance.ts
@@ -1,10 +1,16 @@
 /// <reference types="jest" />
 
 import type { DraftProject, TextAnalysis } from 'interlinearizer';
-import type { AnalysisRepository, ChangeSet, DraftExport } from '../types/analysis-repository';
+import type {
+  AnalysisLinks,
+  AnalysisRepository,
+  ChangeSet,
+  DraftExport,
+} from '../types/analysis-repository';
 import { emptyAnalysis, emptyDraft } from '../types/empty-factories';
 import { CURRENT_MODEL_VERSION } from '../types/model-version';
 import { ReadOnlyAnalysisError } from '../types/read-only-analysis-error';
+import { normalizeSurfaceForm } from '../utils/analysis-identity';
 import { scopeRecordOf } from '../utils/change-set';
 import { FIXTURE_STAMPS, makePhraseLink } from './test-helpers';
 
@@ -362,6 +368,22 @@ function changeInPlace(draft: DraftProject): void {
   });
 }
 
+/** The ids of `records`, sorted, since lookups promise no order. */
+function idsOf(records: readonly { id: string }[]): string[] {
+  return records.map(({ id }) => id).sort();
+}
+
+/** The ids of each kind of link in `links`, sorted, since lookups promise no order. */
+function linkIdsOf(links: Partial<AnalysisLinks>) {
+  return {
+    ...(links.tokenAnalysisLinks && { tokenAnalysisLinks: idsOf(links.tokenAnalysisLinks) }),
+    ...(links.phraseAnalysisLinks && { phraseAnalysisLinks: idsOf(links.phraseAnalysisLinks) }),
+    ...(links.segmentAnalysisLinks && {
+      segmentAnalysisLinks: idsOf(links.segmentAnalysisLinks),
+    }),
+  };
+}
+
 /** Expects `value` to survive a JSON round trip unchanged and to hold no `null`. */
 function expectJsonPlain(value: unknown): void {
   expect(JSON.parse(JSON.stringify(value))).toStrictEqual(value);
@@ -1097,6 +1119,220 @@ export function describeAnalysisRepositoryConformance(
       });
     });
 
+    describe('lookups', () => {
+      /** A repository over {@link fullDraft}, saved through another one so its lookups load it. */
+      async function overFullDraft(): Promise<AnalysisRepository> {
+        await (await store.open(SOURCE)).replaceAll(fullDraft());
+        return store.open(SOURCE);
+      }
+
+      it('gets each payload kind by id, once per id, skipping ids with nothing stored', async () => {
+        const repository = await overFullDraft();
+
+        await expect(
+          repository.getTokenAnalyses(['ta-and', 'ta-missing', 'ta-and']).then(idsOf),
+        ).resolves.toStrictEqual(['ta-and']);
+        await expect(repository.getPhraseAnalyses(['pa-in-the'])).resolves.toStrictEqual(
+          fullAnalysis().phraseAnalyses,
+        );
+        await expect(
+          repository.getSegmentAnalyses(['sa-exo', 'sa-missing']),
+        ).resolves.toStrictEqual(fullAnalysis().segmentAnalyses);
+      });
+
+      it('finds the token links on tokens, and the phrase links touching them, each once', async () => {
+        const repository = await overFullDraft();
+
+        await expect(
+          repository.findLinksByToken(['GEN 1:1:0', 'GEN 1:1:2', 'GEN 1:1:4']).then(linkIdsOf),
+        ).resolves.toStrictEqual({
+          tokenAnalysisLinks: ['tl-gen-and'],
+          phraseAnalysisLinks: ['pa-in-the'],
+        });
+      });
+
+      it('finds the segment links on segments', async () => {
+        const repository = await overFullDraft();
+
+        await expect(
+          repository.findLinksBySegment(['EXO 1:1', 'GEN 1:1']).then(idsOf),
+        ).resolves.toStrictEqual(['sl-exo']);
+      });
+
+      it('finds the links of every kind to analyses', async () => {
+        const repository = await overFullDraft();
+
+        await expect(
+          repository.findLinksToAnalyses(['ta-and', 'pa-in-the', 'sa-exo']).then(linkIdsOf),
+        ).resolves.toStrictEqual({
+          tokenAnalysisLinks: ['tl-exo-and', 'tl-gen-and'],
+          phraseAnalysisLinks: ['pa-in-the'],
+          segmentAnalysisLinks: ['sl-exo'],
+        });
+      });
+
+      it('finds the links of every kind into books', async () => {
+        const repository = await overFullDraft();
+
+        await expect(repository.findLinksInBooks(['GEN']).then(linkIdsOf)).resolves.toStrictEqual({
+          tokenAnalysisLinks: ['tl-gen-and', 'tl-gen-beginning'],
+          phraseAnalysisLinks: ['pa-in-the'],
+          segmentAnalysisLinks: [],
+        });
+      });
+
+      it('finds the links into books with the statuses asked for', async () => {
+        const repository = await overFullDraft();
+
+        await expect(
+          repository.findLinksInBooks(['GEN', 'EXO'], ['suggested']).then(linkIdsOf),
+        ).resolves.toStrictEqual({
+          tokenAnalysisLinks: ['tl-gen-beginning'],
+          phraseAnalysisLinks: [],
+          segmentAnalysisLinks: [],
+        });
+      });
+
+      it('finds the payloads whose surface text normalizes to a form', async () => {
+        const repository = await overFullDraft();
+        await repository.apply({
+          intent: 'addCapitalized',
+          tokenAnalyses: {
+            puts: [{ id: 'ta-And', ...FIXTURE_STAMPS, surfaceText: 'And' }],
+            deletes: [],
+          },
+        });
+
+        await expect(
+          repository.findTokenAnalysesByForm([normalizeSurfaceForm('AND')]).then(idsOf),
+        ).resolves.toStrictEqual(['ta-And', 'ta-and']);
+        await expect(
+          repository.findPhraseAnalysesByForm([normalizeSurfaceForm('In The')]).then(idsOf),
+        ).resolves.toStrictEqual(['pa-in-the']);
+      });
+
+      it('finds nothing in a draft never saved', async () => {
+        const repository = await store.open(SOURCE);
+
+        await expect(repository.findLinksInBooks(['GEN']).then(linkIdsOf)).resolves.toStrictEqual({
+          tokenAnalysisLinks: [],
+          phraseAnalysisLinks: [],
+          segmentAnalysisLinks: [],
+        });
+        await expect(repository.getTokenAnalyses(['ta-and'])).resolves.toStrictEqual([]);
+      });
+
+      it('answers from the records the applied changes leave', async () => {
+        const repository = await overFullDraft();
+        await repository.findLinksInBooks(['GEN']);
+
+        await repository.apply(mixedChanges());
+
+        await expect(
+          repository.findLinksToAnalyses(['ta-beginning', 'ta-god']).then(linkIdsOf),
+        ).resolves.toStrictEqual({
+          tokenAnalysisLinks: ['tl-gen-god'],
+          phraseAnalysisLinks: [],
+          segmentAnalysisLinks: [],
+        });
+        await expect(
+          repository.findLinksBySegment(['GEN 1:1', 'EXO 1:1']).then(idsOf),
+        ).resolves.toStrictEqual(['sl-gen']);
+        await expect(
+          repository.findLinksByToken(['GEN 1:1:2', 'GEN 1:1:13']).then(linkIdsOf),
+        ).resolves.toStrictEqual({
+          tokenAnalysisLinks: [],
+          phraseAnalysisLinks: ['pa-the-beginning'],
+        });
+        await expect(repository.getTokenAnalyses(['ta-and'])).resolves.toStrictEqual([
+          { ...fullAnalysis().tokenAnalyses[0], gloss: { en: 'and then' } },
+        ]);
+      });
+
+      it('files an edited record under its new keys only', async () => {
+        const repository = await overFullDraft();
+        await repository.findLinksInBooks(['GEN']);
+        const [, , beginning] = fullAnalysis().tokenAnalysisLinks;
+
+        await repository.apply({
+          intent: 'approve',
+          tokenAnalysisLinks: { puts: [{ ...beginning, status: 'approved' }], deletes: [] },
+        });
+
+        await expect(
+          repository.findLinksInBooks(['GEN'], ['suggested']).then(linkIdsOf),
+        ).resolves.toMatchObject({ tokenAnalysisLinks: [] });
+        await expect(
+          repository.findLinksInBooks(['GEN'], ['approved']).then(linkIdsOf),
+        ).resolves.toMatchObject({ tokenAnalysisLinks: ['tl-gen-and', 'tl-gen-beginning'] });
+      });
+
+      it('answers from a draft another repository replaced, once reloaded', async () => {
+        const repository = await overFullDraft();
+        await repository.findLinksInBooks(['GEN']);
+        await (await store.open(SOURCE)).replaceAll(exodusOnlyDraft());
+
+        await repository.exportAll();
+
+        await expect(
+          repository.findLinksInBooks(['GEN', 'EXO']).then(linkIdsOf),
+        ).resolves.toStrictEqual({
+          tokenAnalysisLinks: ['tl-exo-and'],
+          phraseAnalysisLinks: [],
+          segmentAnalysisLinks: ['sl-exo'],
+        });
+      });
+
+      it('keeps the records of different source projects apart', async () => {
+        await overFullDraft();
+
+        const other = await store.open('other-project');
+
+        await expect(other.getTokenAnalyses(['ta-and'])).resolves.toStrictEqual([]);
+      });
+
+      it('returns records the caller may change without changing what is stored', async () => {
+        const repository = await overFullDraft();
+
+        const [and] = await repository.getTokenAnalyses(['ta-and']);
+        and.surfaceText = 'changed';
+        const { tokenAnalysisLinks } = await repository.findLinksToAnalyses(['ta-and']);
+        tokenAnalysisLinks[0].status = 'rejected';
+
+        await expect(repository.getTokenAnalyses(['ta-and'])).resolves.toStrictEqual([
+          fullAnalysis().tokenAnalyses[0],
+        ]);
+        await expect(
+          repository.findLinksInBooks(['GEN', 'EXO'], ['rejected']).then(linkIdsOf),
+        ).resolves.toMatchObject({ tokenAnalysisLinks: [] });
+      });
+
+      it('keeps indexes that match its records through applies, undo and redo', async () => {
+        const repository = await overFullDraft();
+        await repository.findLinksInBooks(['GEN']);
+
+        const { inverse } = await repository.apply(mixedChanges());
+        const { inverse: redo } = await repository.apply(inverse);
+        await repository.apply(redo);
+        await repository.apply(puttingNewRecords());
+
+        await expect(repository.checkIndexes()).resolves.toStrictEqual([]);
+      });
+
+      it('answers from a read-only repository', async () => {
+        const repository = await store.openReadOnly(fullDraft());
+
+        await expect(
+          repository.findLinksToAnalyses(['ta-and']).then(linkIdsOf),
+        ).resolves.toStrictEqual({
+          tokenAnalysisLinks: ['tl-exo-and', 'tl-gen-and'],
+          phraseAnalysisLinks: [],
+          segmentAnalysisLinks: [],
+        });
+        await expect(repository.checkIndexes()).resolves.toStrictEqual([]);
+      });
+    });
+
     describe('capabilities', () => {
       it("lets a source project's draft be written", async () => {
         expect((await store.open(SOURCE)).capabilities.readOnly).toBe(false);
diff --git a/src/__tests__/main.test.ts b/src/__tests__/main.test.ts
index 5d00fe95b..b24169bbe 100644
--- a/src/__tests__/main.test.ts
+++ b/src/__tests__/main.test.ts
@@ -400,6 +400,7 @@ describe('main', () => {
           'interlinearizer.setAnalysisLanguage',
           'interlinearizer.undoEdit',
           'interlinearizer.redoEdit',
+          'interlinearizer.checkIndexes',
           'interlinearizer.openSelectProjectModal',
           'interlinearizer.openNewProjectModal',
           'interlinearizer.openProjectInfoModal',
@@ -1827,6 +1828,7 @@ describe('main', () => {
   describe('session commands', () => {
     /** A repository handing out `draft`, as storage would open one. */
     function stubRepository(draft: DraftProject, readOnly = false): AnalysisRepository {
+      const noLinks = { tokenAnalysisLinks: [], phraseAnalysisLinks: [], segmentAnalysisLinks: [] };
       return {
         capabilities: { readOnly },
         exportAll: async () => ({ draft, unreadableBooks: [] }),
@@ -1834,6 +1836,18 @@ describe('main', () => {
         replaceAll: async () => [],
         markClean: async () => {},
         apply: async (changes) => ({ inverse: changes }),
+        getTokenAnalyses: async () => [],
+        getPhraseAnalyses: async () => [],
+        getSegmentAnalyses: async () => [],
+        findLinksByToken: async () => noLinks,
+        findLinksBySegment: async () => [],
+        findLinksToAnalyses: async () => noLinks,
+        findLinksInBooks: async () => noLinks,
+        findTokenAnalysesByForm: async () => [],
+        findPhraseAnalysesByForm: async () => [],
+        checkIndexes: async () => [
+          { index: 'tokenAnalyses', key: 'ta-1', missing: ['ta-1'], extra: [] },
+        ],
       };
     }
 
@@ -1860,6 +1874,9 @@ describe('main', () => {
         redoEdit: handler<(sessionId: string) => Promise<string | undefined>>(
           'interlinearizer.redoEdit',
         ),
+        checkIndexes: handler<(sessionId: string) => Promise<string>>(
+          'interlinearizer.checkIndexes',
+        ),
       };
     }
 
@@ -2022,6 +2039,27 @@ describe('main', () => {
       );
     });
 
+    it("replies with the differences the session's repository finds in its indexes", async () => {
+      const { openSession, checkIndexes } = await activateSessionCommands();
+      const { sessionId } = JSON.parse(await openSession('src-project'));
+
+      await expect(checkIndexes(sessionId)).resolves.toBe(
+        JSON.stringify([{ index: 'tokenAnalyses', key: 'ta-1', missing: ['ta-1'], extra: [] }]),
+      );
+    });
+
+    it('logs the error and rethrows when the indexes cannot be checked', async () => {
+      const { checkIndexes } = await activateSessionCommands();
+
+      await expect(checkIndexes('not-a-session')).rejects.toThrow(
+        'no session not-a-session is open',
+      );
+      expect(__mockLogger.error).toHaveBeenCalledWith(
+        'Interlinearizer: failed to check the indexes of session not-a-session',
+        expect.any(Error),
+      );
+    });
+
     it('closes every session on deactivation', async () => {
       const { openSession } = await activateSessionCommands();
       await openSession('src-project');
diff --git a/src/__tests__/services/analysisIndex.test.ts b/src/__tests__/services/analysisIndex.test.ts
new file mode 100644
index 000000000..61529869a
--- /dev/null
+++ b/src/__tests__/services/analysisIndex.test.ts
@@ -0,0 +1,177 @@
+/// <reference types="jest" />
+
+import type { TextAnalysis } from 'interlinearizer';
+import { AnalysisIndex } from '../../services/analysisIndex';
+import { emptyAnalysis } from '../../types/empty-factories';
+import { normalizeSurfaceForm } from '../../utils/analysis-identity';
+import { FIXTURE_STAMPS, makePhraseLink } from '../test-helpers';
+
+const link = { ...FIXTURE_STAMPS, status: 'approved' as const };
+
+/** Records in GEN and EXO, with a heading's segment in GEN and a suggested link in EXO. */
+function analysis(): TextAnalysis {
+  return {
+    segmentAnalyses: [{ id: 'sa-1', ...FIXTURE_STAMPS, surfaceText: 'The Creation' }],
+    segmentAnalysisLinks: [{ ...link, id: 'sl-1', analysisId: 'sa-1', segmentId: 'GEN 1:1/s1' }],
+    tokenAnalyses: [
+      { id: 'ta-and', ...FIXTURE_STAMPS, surfaceText: 'and' },
+      { id: 'ta-And', ...FIXTURE_STAMPS, surfaceText: 'And' },
+    ],
+    tokenAnalysisLinks: [
+      {
+        ...link,
+        id: 'tl-gen',
+        analysisId: 'ta-and',
+        token: { tokenRef: 'GEN 1:1:0', surfaceText: 'and' },
+      },
+      {
+        ...link,
+        id: 'tl-exo',
+        analysisId: 'ta-And',
+        status: 'suggested',
+        token: { tokenRef: 'EXO 1:1:0', surfaceText: 'And' },
+      },
+    ],
+    phraseAnalyses: [{ id: 'pa-1', ...FIXTURE_STAMPS, surfaceText: 'In the' }],
+    phraseAnalysisLinks: [makePhraseLink('pa-1', ['GEN 1:1:4', 'GEN 1:1:7'])],
+  };
+}
+
+const ids = (records: readonly { id: string }[]) => records.map(({ id }) => id).sort();
+
+describe('AnalysisIndex', () => {
+  it('gets payloads of each kind by id', () => {
+    const index = new AnalysisIndex(analysis());
+
+    expect(ids(index.getTokenAnalyses(['ta-and', 'missing']))).toStrictEqual(['ta-and']);
+    expect(ids(index.getPhraseAnalyses(['pa-1']))).toStrictEqual(['pa-1']);
+    expect(ids(index.getSegmentAnalyses(['sa-1']))).toStrictEqual(['sa-1']);
+  });
+
+  it('finds token links by token ref, and phrase links by any of their tokens', () => {
+    const { tokenAnalysisLinks, phraseAnalysisLinks } = new AnalysisIndex(
+      analysis(),
+    ).findLinksByToken(['GEN 1:1:0', 'GEN 1:1:7']);
+
+    expect(ids(tokenAnalysisLinks)).toStrictEqual(['tl-gen']);
+    expect(ids(phraseAnalysisLinks)).toStrictEqual(['pa-1']);
+  });
+
+  it('finds segment links by segment id', () => {
+    expect(ids(new AnalysisIndex(analysis()).findLinksBySegment(['GEN 1:1/s1']))).toStrictEqual([
+      'sl-1',
+    ]);
+  });
+
+  it('finds the links of every kind to analyses', () => {
+    const links = new AnalysisIndex(analysis()).findLinksToAnalyses(['ta-and', 'pa-1', 'sa-1']);
+
+    expect(ids(links.tokenAnalysisLinks)).toStrictEqual(['tl-gen']);
+    expect(ids(links.phraseAnalysisLinks)).toStrictEqual(['pa-1']);
+    expect(ids(links.segmentAnalysisLinks)).toStrictEqual(['sl-1']);
+  });
+
+  it('files a heading segment link and a phrase link under their books', () => {
+    const links = new AnalysisIndex(analysis()).findLinksInBooks(['GEN']);
+
+    expect(ids(links.tokenAnalysisLinks)).toStrictEqual(['tl-gen']);
+    expect(ids(links.phraseAnalysisLinks)).toStrictEqual(['pa-1']);
+    expect(ids(links.segmentAnalysisLinks)).toStrictEqual(['sl-1']);
+  });
+
+  it('finds the links into books with the statuses asked for', () => {
+    const links = new AnalysisIndex(analysis()).findLinksInBooks(['GEN', 'EXO'], ['suggested']);
+
+    expect(ids(links.tokenAnalysisLinks)).toStrictEqual(['tl-exo']);
+    expect(links.phraseAnalysisLinks).toStrictEqual([]);
+    expect(links.segmentAnalysisLinks).toStrictEqual([]);
+  });
+
+  it('finds payloads by normalized form', () => {
+    const index = new AnalysisIndex(analysis());
+
+    expect(ids(index.findTokenAnalysesByForm([normalizeSurfaceForm('AND')]))).toStrictEqual([
+      'ta-And',
+      'ta-and',
+    ]);
+    expect(ids(index.findPhraseAnalysesByForm(['in the']))).toStrictEqual(['pa-1']);
+  });
+
+  it('keeps every lookup current as changes apply', () => {
+    const index = new AnalysisIndex(analysis());
+
+    index.apply({
+      intent: 'edit',
+      tokenAnalyses: {
+        puts: [{ id: 'ta-and', ...FIXTURE_STAMPS, surfaceText: 'but' }],
+        deletes: [],
+      },
+      tokenAnalysisLinks: { puts: [], deletes: ['tl-exo'] },
+      phraseAnalyses: { puts: [], deletes: ['pa-1'] },
+      phraseAnalysisLinks: { puts: [], deletes: ['pa-1'] },
+      segmentAnalyses: { puts: [], deletes: ['sa-1'] },
+      segmentAnalysisLinks: { puts: [], deletes: ['sl-1'] },
+    });
+
+    expect(ids(index.findTokenAnalysesByForm(['and']))).toStrictEqual(['ta-And']);
+    expect(ids(index.findTokenAnalysesByForm(['but']))).toStrictEqual(['ta-and']);
+    expect(index.findLinksInBooks(['GEN', 'EXO'])).toStrictEqual({
+      tokenAnalysisLinks: [analysis().tokenAnalysisLinks[0]],
+      phraseAnalysisLinks: [],
+      segmentAnalysisLinks: [],
+    });
+    expect(index.findPhraseAnalysesByForm(['in the'])).toStrictEqual([]);
+    expect(index.getSegmentAnalyses(['sa-1'])).toStrictEqual([]);
+  });
+
+  describe('differencesFrom', () => {
+    it('reports none against the analysis it was built from', () => {
+      expect(new AnalysisIndex(analysis()).differencesFrom(analysis())).toStrictEqual([]);
+    });
+
+    it('reports none once kept current through changes the analysis also took', () => {
+      const index = new AnalysisIndex(analysis());
+      const changed = analysis();
+      changed.tokenAnalysisLinks.pop();
+
+      index.apply({ intent: 'delete', tokenAnalysisLinks: { puts: [], deletes: ['tl-exo'] } });
+
+      expect(index.differencesFrom(changed)).toStrictEqual([]);
+    });
+
+    it('reports the records and entries of every kind that an analysis holds differently', () => {
+      const differences = new AnalysisIndex(emptyAnalysis()).differencesFrom(analysis());
+
+      expect(new Set(differences.map(({ index }) => index))).toStrictEqual(
+        new Set([
+          'tokenAnalyses',
+          'tokenAnalyses by form',
+          'phraseAnalyses',
+          'phraseAnalyses by form',
+          'segmentAnalyses',
+          'tokenAnalysisLinks',
+          'tokenAnalysisLinks by analysisId',
+          'tokenAnalysisLinks by book',
+          'tokenAnalysisLinks by bookStatus',
+          'tokenAnalysisLinks by tokenRef',
+          'phraseAnalysisLinks',
+          'phraseAnalysisLinks by analysisId',
+          'phraseAnalysisLinks by book',
+          'phraseAnalysisLinks by bookStatus',
+          'phraseAnalysisLinks by tokenRef',
+          'segmentAnalysisLinks',
+          'segmentAnalysisLinks by analysisId',
+          'segmentAnalysisLinks by book',
+          'segmentAnalysisLinks by bookStatus',
+          'segmentAnalysisLinks by segmentId',
+        ]),
+      );
+      expect(differences).toContainEqual({
+        index: 'tokenAnalysisLinks by bookStatus',
+        key: 'EXO/suggested',
+        missing: ['tl-exo'],
+        extra: [],
+      });
+    });
+  });
+});
diff --git a/src/__tests__/services/draftRepository.test.ts b/src/__tests__/services/draftRepository.test.ts
index e12aec981..38e0e8d7b 100644
--- a/src/__tests__/services/draftRepository.test.ts
+++ b/src/__tests__/services/draftRepository.test.ts
@@ -377,4 +377,45 @@ describe('DraftRepository', () => {
       expect(records.get(draftAnalysisKey('src', 'GEN'))).not.toContain('and then');
     });
   });
+
+  describe('lookups', () => {
+    it('load the draft once, answering later lookups from what they kept', async () => {
+      const { storage } = memoryStorage();
+      await new DraftRepository(storage, 'src', silentLogger()).replaceAll(twoBookDraft());
+      const repository = new DraftRepository(storage, 'src', silentLogger());
+      const read = jest.spyOn(storage, 'read');
+
+      await repository.findLinksInBooks(['GEN']);
+      const readsAfterFirst = read.mock.calls.length;
+      await repository.findLinksToAnalyses(['ta-and']);
+
+      expect(readsAfterFirst).toBeGreaterThan(0);
+      expect(read).toHaveBeenCalledTimes(readsAfterFirst);
+    });
+
+    it('answer from what an apply left without loading the draft again', async () => {
+      const { storage } = memoryStorage();
+      const repository = new DraftRepository(storage, 'src', silentLogger());
+      await repository.apply({
+        intent: 'add',
+        tokenAnalyses: { puts: twoBookAnalysis().tokenAnalyses, deletes: [] },
+      });
+      const read = jest.spyOn(storage, 'read');
+
+      await expect(repository.getTokenAnalyses(['ta-and'])).resolves.toStrictEqual(
+        twoBookAnalysis().tokenAnalyses,
+      );
+      expect(read).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('checkIndexes', () => {
+    it('reports nothing while it keeps no index', async () => {
+      const { storage } = memoryStorage();
+      const repository = new DraftRepository(storage, 'src', silentLogger());
+      await repository.replaceAll(twoBookDraft());
+
+      await expect(repository.checkIndexes()).resolves.toStrictEqual([]);
+    });
+  });
 });
diff --git a/src/__tests__/services/indexedRepository.test.ts b/src/__tests__/services/indexedRepository.test.ts
new file mode 100644
index 000000000..290a6cb98
--- /dev/null
+++ b/src/__tests__/services/indexedRepository.test.ts
@@ -0,0 +1,70 @@
+/// <reference types="jest" />
+
+import type { TextAnalysis } from 'interlinearizer';
+import { AnalysisIndex } from '../../services/analysisIndex';
+import { type IndexedAnalysis, IndexedRepository } from '../../services/indexedRepository';
+import { emptyAnalysis } from '../../types/empty-factories';
+import { FIXTURE_STAMPS } from '../test-helpers';
+
+/** Answers lookups from an index over `records`, keeping it as `keep` says. */
+class StubRepository extends IndexedRepository {
+  readonly kept: IndexedAnalysis | undefined;
+
+  private readonly index: AnalysisIndex;
+
+  constructor(records: TextAnalysis, keep: 'kept' | 'none') {
+    super();
+    this.index = new AnalysisIndex(records);
+    this.kept = keep === 'kept' ? { analysis: records, index: this.index } : undefined;
+  }
+
+  protected async indexed(): Promise<AnalysisIndex> {
+    return this.index;
+  }
+
+  protected keptIndex(): IndexedAnalysis | undefined {
+    return this.kept;
+  }
+}
+
+function analysis(): TextAnalysis {
+  return {
+    ...emptyAnalysis(),
+    tokenAnalyses: [{ id: 'ta-and', ...FIXTURE_STAMPS, surfaceText: 'and' }],
+  };
+}
+
+describe('IndexedRepository', () => {
+  it('answers lookups from its index', async () => {
+    await expect(
+      new StubRepository(analysis(), 'none').getTokenAnalyses(['ta-and']),
+    ).resolves.toStrictEqual(analysis().tokenAnalyses);
+  });
+
+  it('hands out copies of the records its index holds', async () => {
+    const repository = new StubRepository(analysis(), 'none');
+
+    const [and] = await repository.getTokenAnalyses(['ta-and']);
+    and.surfaceText = 'changed';
+
+    await expect(repository.getTokenAnalyses(['ta-and'])).resolves.toStrictEqual(
+      analysis().tokenAnalyses,
+    );
+  });
+
+  it('reports the differences of the index it keeps from its analysis', async () => {
+    const repository = new StubRepository(analysis(), 'kept');
+    repository.kept?.analysis.tokenAnalyses.pop();
+
+    await expect(repository.checkIndexes()).resolves.toContainEqual({
+      index: 'tokenAnalyses',
+      key: 'ta-and',
+      missing: [],
+      extra: ['ta-and'],
+    });
+  });
+
+  it('reports nothing while it keeps no index', async () => {
+    await expect(new StubRepository(analysis(), 'none').checkIndexes()).resolves.toStrictEqual([]);
+  });
+});
diff --git a/src/__tests__/services/projectStorage.test.ts b/src/__tests__/services/projectStorage.test.ts
index 24a6a63ab..948c16f9e 100644
--- a/src/__tests__/services/projectStorage.test.ts
+++ b/src/__tests__/services/projectStorage.test.ts
@@ -24,6 +24,7 @@ import {
   updateProjectMetadata,
 } from '../../services/projectStorage';
 import { summarizeProject } from '../../services/projectSummaries';
+import type { AnalysisRepository } from '../../types/analysis-repository';
 import { ReadOnlyAnalysisError } from '../../types/read-only-analysis-error';
 import { emptyAnalysis, emptyDraft } from '../../types/empty-factories';
 import { removeBookFromAnalysis } from '../../utils/analysis-book';
@@ -2915,6 +2916,42 @@ describe('projectStorage', () => {
       expect(analysis.tokenAnalysisLinks).toStrictEqual([]);
     });
 
+    it.each([
+      ['getTokenAnalyses', (r: AnalysisRepository) => r.getTokenAnalyses(['analysis-GEN']), 1],
+      ['getPhraseAnalyses', (r: AnalysisRepository) => r.getPhraseAnalyses(['p']), 0],
+      ['getSegmentAnalyses', (r: AnalysisRepository) => r.getSegmentAnalyses(['s']), 0],
+      ['findLinksBySegment', (r: AnalysisRepository) => r.findLinksBySegment(['GEN 1:1']), 0],
+      [
+        'findLinksByToken',
+        (r: AnalysisRepository) =>
+          r.findLinksByToken(['GEN 1:1!0']).then((l) => l.tokenAnalysisLinks),
+        1,
+      ],
+      [
+        'findLinksToAnalyses',
+        (r: AnalysisRepository) =>
+          r.findLinksToAnalyses(['analysis-GEN']).then((l) => l.tokenAnalysisLinks),
+        1,
+      ],
+      [
+        'findLinksInBooks',
+        (r: AnalysisRepository) =>
+          r.findLinksInBooks(['GEN'], ['approved']).then((l) => l.tokenAnalysisLinks),
+        1,
+      ],
+      [
+        'findTokenAnalysesByForm',
+        (r: AnalysisRepository) => r.findTokenAnalysesByForm(['word-gen']),
+        1,
+      ],
+      ['findPhraseAnalysesByForm', (r: AnalysisRepository) => r.findPhraseAnalysesByForm(['x']), 0],
+      ['checkIndexes', (r: AnalysisRepository) => r.checkIndexes(), 0],
+    ])('answers %s from the draft saveDraft saved', async (_name, lookup, count) => {
+      await saveDraft(token, 'src-proj', makeDraftSpanningBooks('src-proj', 'GEN'));
+
+      await expect(lookup(openDraftRepository(token, 'src-proj'))).resolves.toHaveLength(count);
+    });
+
     it('waits for a draft call already made before reading', async () => {
       let finishWrite: () => void = () => {};
       __mockWriteUserData.mockImplementationOnce(
diff --git a/src/__tests__/services/pt9ImportRepository.test.ts b/src/__tests__/services/pt9ImportRepository.test.ts
index 8a8c29420..62bb986eb 100644
--- a/src/__tests__/services/pt9ImportRepository.test.ts
+++ b/src/__tests__/services/pt9ImportRepository.test.ts
@@ -127,4 +127,56 @@ describe('Pt9ImportRepository', () => {
       expect(readProject).not.toHaveBeenCalled();
     });
   });
+
+  describe('lookups', () => {
+    const imported = () =>
+      makeImport({
+        analysis: {
+          ...emptyAnalysis(),
+          tokenAnalyses: [{ id: 'ta-1', ...FIXTURE_STAMPS, surfaceText: 'and' }],
+        },
+      });
+
+    it("answer from the import's records, reading it once", async () => {
+      const readProject = jest.fn(async () => imported());
+      const repository = new Pt9ImportRepository('import-id', readProject);
+
+      await expect(repository.getTokenAnalyses(['ta-1'])).resolves.toStrictEqual(
+        imported().analysis.tokenAnalyses,
+      );
+      await repository.findTokenAnalysesByForm(['and']);
+
+      expect(readProject).toHaveBeenCalledTimes(1);
+    });
+
+    it('read the import again after a load', async () => {
+      const readProject = jest.fn(async () => imported());
+      const repository = new Pt9ImportRepository('import-id', readProject);
+      await repository.getTokenAnalyses(['ta-1']);
+
+      await repository.exportAll();
+      await repository.getTokenAnalyses(['ta-1']);
+
+      expect(readProject).toHaveBeenCalledTimes(3);
+    });
+
+    it('refuse when no import is stored', async () => {
+      await expect(repositoryOver(undefined).getTokenAnalyses(['ta-1'])).rejects.toThrow(
+        'no Paratext 9 import is stored as project import-id',
+      );
+    });
+  });
+
+  describe('checkIndexes', () => {
+    it('reports nothing before a lookup', async () => {
+      await expect(repositoryOver(makeImport()).checkIndexes()).resolves.toStrictEqual([]);
+    });
+
+    it('reports nothing after a lookup, since an import never changes', async () => {
+      const repository = repositoryOver(makeImport());
+      await repository.getTokenAnalyses(['ta-1']);
+
+      await expect(repository.checkIndexes()).resolves.toStrictEqual([]);
+    });
+  });
 });
diff --git a/src/__tests__/services/recordTable.test.ts b/src/__tests__/services/recordTable.test.ts
new file mode 100644
index 000000000..b4245db81
--- /dev/null
+++ b/src/__tests__/services/recordTable.test.ts
@@ -0,0 +1,96 @@
+/// <reference types="jest" />
+
+import { RecordTable } from '../../services/recordTable';
+
+type Item = { id: string; tags: string[]; note?: string };
+
+const keyers = { tag: (item: Item) => item.tags };
+
+function tableOf(...items: Item[]) {
+  return new RecordTable('items', keyers, items);
+}
+
+describe('RecordTable', () => {
+  it('gets records by id, once per id, skipping ids with nothing stored', () => {
+    const a = { id: 'a', tags: [] };
+
+    expect(tableOf(a).get(['a', 'missing', 'a'])).toStrictEqual([a]);
+  });
+
+  it('finds the records filed under any of the keys, each once', () => {
+    const a = { id: 'a', tags: ['x', 'y'] };
+    const b = { id: 'b', tags: ['y'] };
+    const c = { id: 'c', tags: ['z'] };
+
+    expect(tableOf(a, b, c).find('tag', ['x', 'y', 'missing'])).toStrictEqual([a, b]);
+  });
+
+  it('files a record once under a key its keyer returns twice', () => {
+    const table = tableOf({ id: 'a', tags: ['x', 'x'] });
+
+    table.apply({ puts: [], deletes: ['a'] });
+
+    expect(table.find('tag', ['x'])).toStrictEqual([]);
+    expect(table.differencesFrom(tableOf())).toStrictEqual([]);
+  });
+
+  it('files a put record under its new keys only', () => {
+    const table = tableOf({ id: 'a', tags: ['x'] });
+    const moved = { id: 'a', tags: ['y'] };
+
+    table.apply({ puts: [moved], deletes: [] });
+
+    expect(table.find('tag', ['x'])).toStrictEqual([]);
+    expect(table.find('tag', ['y'])).toStrictEqual([moved]);
+  });
+
+  it('unfiles a deleted record, skipping an id with nothing stored', () => {
+    const table = tableOf({ id: 'a', tags: ['x'] });
+
+    table.apply({ puts: [], deletes: ['a', 'missing'] });
+
+    expect(table.get(['a'])).toStrictEqual([]);
+    expect(table.find('tag', ['x'])).toStrictEqual([]);
+  });
+
+  it('applies nothing for absent changes', () => {
+    const table = tableOf({ id: 'a', tags: ['x'] });
+
+    table.apply(undefined);
+
+    expect(table.differencesFrom(tableOf({ id: 'a', tags: ['x'] }))).toStrictEqual([]);
+  });
+
+  describe('differencesFrom', () => {
+    it('reports none against a table holding the same records', () => {
+      const items = [
+        { id: 'a', tags: ['x'] },
+        { id: 'b', tags: ['x', 'y'] },
+      ];
+
+      expect(tableOf(...items).differencesFrom(tableOf(...items))).toStrictEqual([]);
+    });
+
+    it('reports a record the kept table lacks, and the entries filing it', () => {
+      expect(tableOf().differencesFrom(tableOf({ id: 'a', tags: ['x'] }))).toStrictEqual([
+        { index: 'items', key: 'a', missing: ['a'], extra: [] },
+        { index: 'items by tag', key: 'x', missing: ['a'], extra: [] },
+      ]);
+    });
+
+    it('reports a record only the kept table holds, and the entries filing it', () => {
+      expect(tableOf({ id: 'a', tags: ['x'] }).differencesFrom(tableOf())).toStrictEqual([
+        { index: 'items', key: 'a', missing: [], extra: ['a'] },
+        { index: 'items by tag', key: 'x', missing: [], extra: ['a'] },
+      ]);
+    });
+
+    it('reports a record whose kept copy differs as both missing and extra', () => {
+      const kept = tableOf({ id: 'a', tags: [], note: 'old' });
+
+      expect(kept.differencesFrom(tableOf({ id: 'a', tags: [], note: 'new' }))).toStrictEqual([
+        { index: 'items', key: 'a', missing: ['a'], extra: ['a'] },
+      ]);
+    });
+  });
+});
diff --git a/src/__tests__/utils/change-set.test.ts b/src/__tests__/utils/change-set.test.ts
index e07b209f8..7e6e57d1d 100644
--- a/src/__tests__/utils/change-set.test.ts
+++ b/src/__tests__/utils/change-set.test.ts
@@ -103,22 +103,6 @@ describe('applyChangeSet', () => {
     expect(stored).toStrictEqual(draftOf(payload('a')));
   });
 
-  it('holds copies of the records the changes put', () => {
-    const put = payload('b');
-    const scope = scopeRecordOf(draftOf());
-    const { draft } = applyChangeSet(draftOf(), {
-      intent: 'add',
-      scope,
-      tokenAnalyses: { puts: [put], deletes: [] },
-    });
-
-    put.surfaceText = 'changed';
-    scope.analysisLanguages.push('fr');
-
-    expect(draft.analysis.tokenAnalyses).toStrictEqual([payload('b')]);
-    expect(draft.analysisLanguages).toStrictEqual(['en']);
-  });
-
   it('refuses an id both put and deleted', () => {
     expect(() =>
       applyChangeSet(draftOf(payload('a')), {
diff --git a/src/__tests__/utils/json-copy.test.ts b/src/__tests__/utils/json-copy.test.ts
new file mode 100644
index 000000000..1ecdd4b5f
--- /dev/null
+++ b/src/__tests__/utils/json-copy.test.ts
@@ -0,0 +1,16 @@
+/// <reference types="jest" />
+
+import { jsonCopy } from '../../utils/json-copy';
+
+describe('jsonCopy', () => {
+  it('copies a JSON-plain value deeply, sharing nothing with it', () => {
+    const value = { gloss: { en: 'and' }, morphemes: [{ form: 'and' }] };
+
+    const copy = jsonCopy(value);
+    copy.gloss.en = 'changed';
+    copy.morphemes[0].form = 'changed';
+
+    expect(copy).not.toBe(value);
+    expect(value).toStrictEqual({ gloss: { en: 'and' }, morphemes: [{ form: 'and' }] });
+  });
+});
diff --git a/src/main.ts b/src/main.ts
index 6d5af1dcb..1ec3369aa 100644
--- a/src/main.ts
+++ b/src/main.ts
@@ -807,6 +807,25 @@ async function redoEdit(sessionId: string): Promise<string | undefined> {
   }
 }
 
+/**
+ * Rebuilds a session's derived indexes from its records and reports where the kept ones differ, for
+ * debugging.
+ *
+ * @returns A JSON string of the differences, empty when there are none.
+ * @throws If the session is not open, or its records cannot be read. The error is logged before
+ *   rethrowing.
+ */
+async function checkIndexes(sessionId: string): Promise<string> {
+  try {
+    return JSON.stringify(
+      await sessions.run(sessionId, (session) => session.repository.checkIndexes()),
+    );
+  } catch (e) {
+    logger.error(`Interlinearizer: failed to check the indexes of session ${sessionId}`, e);
+    throw e;
+  }
+}
+
 /**
  * Returns a summary of every interlinearizer project for the given source project as a JSON string.
  * The WebView deserializes this to populate its project picker and to decide whether to prompt
@@ -1412,6 +1431,23 @@ export async function activate(context: ExecutionActivationContext): Promise<voi
     },
   );
 
+  const checkIndexesCommandRegistration = await papi.commands.registerCommand(
+    'interlinearizer.checkIndexes',
+    checkIndexes,
+    {
+      method: {
+        summary:
+          "Rebuild a session's derived indexes from its records and report where the kept ones differ, for debugging",
+        params: [sessionIdParam],
+        result: {
+          name: 'return value',
+          summary: 'JSON-stringified [{ index, key, missing, extra }]; empty when none differ',
+          schema: { type: 'string' },
+        },
+      },
+    },
+  );
+
   const setPerfMarksCommandRegistration = await papi.commands.registerCommand(
     'interlinearizer.setPerfMarks',
     async (enabled: boolean) => setHostPerfMarks(enabled),
@@ -1787,6 +1823,7 @@ export async function activate(context: ExecutionActivationContext): Promise<voi
     setAnalysisLanguageCommandRegistration,
     undoEditCommandRegistration,
     redoEditCommandRegistration,
+    checkIndexesCommandRegistration,
     setPerfMarksCommandRegistration,
     readPerfCommandRegistration,
     updateProjectMetadataCommandRegistration,
diff --git a/src/services/analysisIndex.ts b/src/services/analysisIndex.ts
new file mode 100644
index 000000000..a611b2915
--- /dev/null
+++ b/src/services/analysisIndex.ts
@@ -0,0 +1,186 @@
+import type {
+  AssignmentStatus,
+  PhraseAnalysis,
+  PhraseAnalysisLink,
+  SegmentAnalysis,
+  SegmentAnalysisLink,
+  TextAnalysis,
+  TokenAnalysis,
+  TokenAnalysisLink,
+} from 'interlinearizer';
+import type { AnalysisLinks, ChangeSet, IndexDifference } from '../types/analysis-repository';
+import { bookOfRef } from '../utils/analysis-book';
+import { normalizeSurfaceForm } from '../utils/analysis-identity';
+import { RecordTable } from './recordTable';
+
+/** The key filing a link by its book and status. */
+function bookStatusKey(bookCode: string, status: AssignmentStatus): string {
+  return `${bookCode}/${status}`;
+}
+
+/** The indexes every kind of link is filed in, given where a link of that kind sits. */
+function linkKeyers<Link extends { analysisId: string; status: AssignmentStatus }>(
+  bookOf: (link: Link) => string,
+) {
+  return {
+    analysisId: (link: Link) => [link.analysisId],
+    book: (link: Link) => [bookOf(link)],
+    bookStatus: (link: Link) => [bookStatusKey(bookOf(link), link.status)],
+  };
+}
+
+const formKeyers = {
+  form: (payload: { surfaceText: string }) => [normalizeSurfaceForm(payload.surfaceText)],
+};
+
+/**
+ * An analysis's records by id, with the derived indexes its lookups answer from. Built from the
+ * records and kept current as changes are applied; the records it hands out are its own.
+ */
+export class AnalysisIndex {
+  private readonly tokenAnalyses: RecordTable<TokenAnalysis, 'form'>;
+
+  private readonly phraseAnalyses: RecordTable<PhraseAnalysis, 'form'>;
+
+  private readonly segmentAnalyses: RecordTable<SegmentAnalysis, never>;
+
+  private readonly tokenLinks: RecordTable<
+    TokenAnalysisLink,
+    'analysisId' | 'book' | 'bookStatus' | 'tokenRef'
+  >;
+
+  private readonly phraseLinks: RecordTable<
+    PhraseAnalysisLink,
+    'analysisId' | 'book' | 'bookStatus' | 'tokenRef'
+  >;
+
+  private readonly segmentLinks: RecordTable<
+    SegmentAnalysisLink,
+    'analysisId' | 'book' | 'bookStatus' | 'segmentId'
+  >;
+
+  constructor(analysis: TextAnalysis) {
+    this.tokenAnalyses = new RecordTable('tokenAnalyses', formKeyers, analysis.tokenAnalyses);
+    this.phraseAnalyses = new RecordTable('phraseAnalyses', formKeyers, analysis.phraseAnalyses);
+    this.segmentAnalyses = new RecordTable('segmentAnalyses', {}, analysis.segmentAnalyses);
+    this.tokenLinks = new RecordTable(
+      'tokenAnalysisLinks',
+      {
+        ...linkKeyers((link: TokenAnalysisLink) => bookOfRef(link.token.tokenRef)),
+        tokenRef: (link) => [link.token.tokenRef],
+      },
+      analysis.tokenAnalysisLinks,
+    );
+    this.phraseLinks = new RecordTable(
+      'phraseAnalysisLinks',
+      {
+        // Every token of a phrase shares a book, so the first one places the whole run.
+        ...linkKeyers((link: PhraseAnalysisLink) => bookOfRef(link.tokens[0].tokenRef)),
+        tokenRef: (link) => link.tokens.map(({ tokenRef }) => tokenRef),
+      },
+      analysis.phraseAnalysisLinks,
+    );
+    this.segmentLinks = new RecordTable(
+      'segmentAnalysisLinks',
+      {
+        ...linkKeyers((link: SegmentAnalysisLink) => bookOfRef(link.segmentId)),
+        segmentId: (link) => [link.segmentId],
+      },
+      analysis.segmentAnalysisLinks,
+    );
+  }
+
+  /** Applies `changes`, whose ids appear at most once in each record kind, taking their records. */
+  apply(changes: ChangeSet): void {
+    this.tokenAnalyses.apply(changes.tokenAnalyses);
+    this.phraseAnalyses.apply(changes.phraseAnalyses);
+    this.segmentAnalyses.apply(changes.segmentAnalyses);
+    this.tokenLinks.apply(changes.tokenAnalysisLinks);
+    this.phraseLinks.apply(changes.phraseAnalysisLinks);
+    this.segmentLinks.apply(changes.segmentAnalysisLinks);
+  }
+
+  /** The token analyses stored under `ids`, each once; an id with none stored is skipped. */
+  getTokenAnalyses(ids: readonly string[]): TokenAnalysis[] {
+    return this.tokenAnalyses.get(ids);
+  }
+
+  /** The phrase analyses stored under `ids`, each once; an id with none stored is skipped. */
+  getPhraseAnalyses(ids: readonly string[]): PhraseAnalysis[] {
+    return this.phraseAnalyses.get(ids);
+  }
+
+  /** The segment analyses stored under `ids`, each once; an id with none stored is skipped. */
+  getSegmentAnalyses(ids: readonly string[]): SegmentAnalysis[] {
+    return this.segmentAnalyses.get(ids);
+  }
+
+  /** The token links on the tokens `tokenRefs` names, and the phrase links touching any of them. */
+  findLinksByToken(
+    tokenRefs: readonly string[],
+  ): Pick<AnalysisLinks, 'tokenAnalysisLinks' | 'phraseAnalysisLinks'> {
+    return {
+      tokenAnalysisLinks: this.tokenLinks.find('tokenRef', tokenRefs),
+      phraseAnalysisLinks: this.phraseLinks.find('tokenRef', tokenRefs),
+    };
+  }
+
+  /** The segment links on the segments `segmentIds` names. */
+  findLinksBySegment(segmentIds: readonly string[]): SegmentAnalysisLink[] {
+    return this.segmentLinks.find('segmentId', segmentIds);
+  }
+
+  /** The links of every kind to the analyses `analysisIds` names. */
+  findLinksToAnalyses(analysisIds: readonly string[]): AnalysisLinks {
+    return {
+      tokenAnalysisLinks: this.tokenLinks.find('analysisId', analysisIds),
+      phraseAnalysisLinks: this.phraseLinks.find('analysisId', analysisIds),
+      segmentAnalysisLinks: this.segmentLinks.find('analysisId', analysisIds),
+    };
+  }
+
+  /** The links into the books `bookCodes` names, of any status when `statuses` is absent. */
+  findLinksInBooks(
+    bookCodes: readonly string[],
+    statuses?: readonly AssignmentStatus[],
+  ): AnalysisLinks {
+    if (!statuses) {
+      return {
+        tokenAnalysisLinks: this.tokenLinks.find('book', bookCodes),
+        phraseAnalysisLinks: this.phraseLinks.find('book', bookCodes),
+        segmentAnalysisLinks: this.segmentLinks.find('book', bookCodes),
+      };
+    }
+    const keys = bookCodes.flatMap((bookCode) =>
+      statuses.map((status) => bookStatusKey(bookCode, status)),
+    );
+    return {
+      tokenAnalysisLinks: this.tokenLinks.find('bookStatus', keys),
+      phraseAnalysisLinks: this.phraseLinks.find('bookStatus', keys),
+      segmentAnalysisLinks: this.segmentLinks.find('bookStatus', keys),
+    };
+  }
+
+  /** The token analyses whose surface text normalizes to one of `normalizedForms`. */
+  findTokenAnalysesByForm(normalizedForms: readonly string[]): TokenAnalysis[] {
+    return this.tokenAnalyses.find('form', normalizedForms);
+  }
+
+  /** The phrase analyses whose surface text normalizes to one of `normalizedForms`. */
+  findPhraseAnalysesByForm(normalizedForms: readonly string[]): PhraseAnalysis[] {
+    return this.phraseAnalyses.find('form', normalizedForms);
+  }
+
+  /** Where this index differs from one built afresh from `analysis`. */
+  differencesFrom(analysis: TextAnalysis): IndexDifference[] {
+    const rebuilt = new AnalysisIndex(analysis);
+    return [
+      ...this.tokenAnalyses.differencesFrom(rebuilt.tokenAnalyses),
+      ...this.phraseAnalyses.differencesFrom(rebuilt.phraseAnalyses),
+      ...this.segmentAnalyses.differencesFrom(rebuilt.segmentAnalyses),
+      ...this.tokenLinks.differencesFrom(rebuilt.tokenLinks),
+      ...this.phraseLinks.differencesFrom(rebuilt.phraseLinks),
+      ...this.segmentLinks.differencesFrom(rebuilt.segmentLinks),
+    ];
+  }
+}
diff --git a/src/services/draftRepository.ts b/src/services/draftRepository.ts
index a81e8f72d..8b4fb3c9a 100644
--- a/src/services/draftRepository.ts
+++ b/src/services/draftRepository.ts
@@ -20,7 +20,10 @@ import {
 import { mergeAnalyses, splitAnalysisByBook } from '../utils/analysis-book';
 import { reportAnalysisViolations } from '../utils/analysis-violations';
 import { applyChangeSet } from '../utils/change-set';
+import { jsonCopy } from '../utils/json-copy';
 import { perfTime, perfTimeAsync, perfTimeAsyncExcluding } from '../utils/perf-marks';
+import { AnalysisIndex } from './analysisIndex';
+import { IndexedRepository, type IndexedAnalysis } from './indexedRepository';
 import { draftAnalysisKey, draftJournalKey, draftKey } from './storageKeys';
 
 /**
@@ -104,7 +107,7 @@ type LoadedShard = {
  *
  * Calls on one instance must not overlap.
  */
-export class DraftRepository implements AnalysisRepository {
+export class DraftRepository extends IndexedRepository implements AnalysisRepository {
   readonly capabilities: RepositoryCapabilities = { readOnly: false };
 
   private readonly storage: KeyValueStorage;
@@ -129,13 +132,14 @@ export class DraftRepository implements AnalysisRepository {
   private loaded = false;
 
   /**
-   * The draft as this instance's last apply left it, which the next apply builds on. Dropped by
-   * every load and by every write but an apply, since each may come from a caller holding another
-   * draft.
+   * The draft as this instance last applied changes to it or answered a lookup from it, with the
+   * index over its records. Dropped by every load and by every write but an apply, since each may
+   * come from a caller holding another draft.
    */
-  private current: DraftProject | undefined;
+  private current: { draft: DraftProject; index: AnalysisIndex } | undefined;
 
   constructor(storage: KeyValueStorage, sourceProjectId: string, logger: WarningLogger) {
+    super();
     this.storage = storage;
     this.logger = logger;
     this.sourceProjectId = sourceProjectId;
@@ -252,9 +256,10 @@ export class DraftRepository implements AnalysisRepository {
   }
 
   /**
-   * Applies the changes to the draft as this instance's last apply left it, or to the stored draft
-   * when it has made none since its last whole load or save. Only the books whose content the
-   * changes alter are rewritten, so an edit to a payload rewrites every book linking it.
+   * Applies the changes to the draft as this instance last applied changes to it or answered a
+   * lookup from it, or to the stored draft when it has done neither since its last whole load or
+   * save. Only the books whose content the changes alter are rewritten, so an edit to a payload
+   * rewrites every book linking it.
    *
    * @throws {Error} If an id appears more than once in one record kind's changes, or the scope's
    *   record names another source project; nothing is written.
@@ -265,13 +270,36 @@ export class DraftRepository implements AnalysisRepository {
    *   is left as it was.
    */
   async apply(changes: ChangeSet): Promise<ApplyResult> {
-    this.current ??= (await this.exportAll()).draft;
-    const { draft, inverse } = applyChangeSet(this.current, changes);
+    const { draft: base, index } = await this.keptDraft();
+    const copied = jsonCopy(changes);
+    const { draft, inverse } = applyChangeSet(base, copied);
     await this.writeDraft(draft, undefined, { refuseUnreadable: true });
-    this.current = draft;
+    index.apply(copied);
+    this.current = { draft, index };
     return { inverse };
   }
 
+  protected async indexed(): Promise<AnalysisIndex> {
+    return (await this.keptDraft()).index;
+  }
+
+  protected keptIndex(): IndexedAnalysis | undefined {
+    return this.current && { analysis: this.current.draft.analysis, index: this.current.index };
+  }
+
+  /**
+   * The draft this instance keeps, loaded from storage first when it keeps none.
+   *
+   * @throws Whatever {@link exportAll} throws.
+   */
+  private async keptDraft(): Promise<{ draft: DraftProject; index: AnalysisIndex }> {
+    if (!this.current) {
+      const { draft } = await this.exportAll();
+      this.current = { draft, index: new AnalysisIndex(draft.analysis) };
+    }
+    return this.current;
+  }
+
   /**
    * Saves `draft` as {@link replaceAll} describes.
    *
diff --git a/src/services/indexedRepository.ts b/src/services/indexedRepository.ts
new file mode 100644
index 000000000..d8b774446
--- /dev/null
+++ b/src/services/indexedRepository.ts
@@ -0,0 +1,95 @@
+import type {
+  AssignmentStatus,
+  PhraseAnalysis,
+  SegmentAnalysis,
+  SegmentAnalysisLink,
+  TextAnalysis,
+  TokenAnalysis,
+} from 'interlinearizer';
+import type {
+  AnalysisLinks,
+  AnalysisRepository,
+  IndexDifference,
+} from '../types/analysis-repository';
+import { jsonCopy } from '../utils/json-copy';
+import type { AnalysisIndex } from './analysisIndex';
+
+/** An index, with the analysis whose records it is kept over. */
+export type IndexedAnalysis = {
+  analysis: TextAnalysis;
+  index: AnalysisIndex;
+};
+
+/** The lookups of a repository that answers them from an {@link AnalysisIndex} over its records. */
+export abstract class IndexedRepository implements Pick<
+  AnalysisRepository,
+  | 'getTokenAnalyses'
+  | 'getPhraseAnalyses'
+  | 'getSegmentAnalyses'
+  | 'findLinksByToken'
+  | 'findLinksBySegment'
+  | 'findLinksToAnalyses'
+  | 'findLinksInBooks'
+  | 'findTokenAnalysesByForm'
+  | 'findPhraseAnalysesByForm'
+  | 'checkIndexes'
+> {
+  getTokenAnalyses(ids: string[]): Promise<TokenAnalysis[]> {
+    return this.query((index) => index.getTokenAnalyses(ids));
+  }
+
+  getPhraseAnalyses(ids: string[]): Promise<PhraseAnalysis[]> {
+    return this.query((index) => index.getPhraseAnalyses(ids));
+  }
+
+  getSegmentAnalyses(ids: string[]): Promise<SegmentAnalysis[]> {
+    return this.query((index) => index.getSegmentAnalyses(ids));
+  }
+
+  findLinksByToken(
+    tokenRefs: string[],
+  ): Promise<Pick<AnalysisLinks, 'tokenAnalysisLinks' | 'phraseAnalysisLinks'>> {
+    return this.query((index) => index.findLinksByToken(tokenRefs));
+  }
+
+  findLinksBySegment(segmentIds: string[]): Promise<SegmentAnalysisLink[]> {
+    return this.query((index) => index.findLinksBySegment(segmentIds));
+  }
+
+  findLinksToAnalyses(analysisIds: string[]): Promise<AnalysisLinks> {
+    return this.query((index) => index.findLinksToAnalyses(analysisIds));
+  }
+
+  findLinksInBooks(bookCodes: string[], statuses?: AssignmentStatus[]): Promise<AnalysisLinks> {
+    return this.query((index) => index.findLinksInBooks(bookCodes, statuses));
+  }
+
+  findTokenAnalysesByForm(normalizedForms: string[]): Promise<TokenAnalysis[]> {
+    return this.query((index) => index.findTokenAnalysesByForm(normalizedForms));
+  }
+
+  findPhraseAnalysesByForm(normalizedForms: string[]): Promise<PhraseAnalysis[]> {
+    return this.query((index) => index.findPhraseAnalysesByForm(normalizedForms));
+  }
+
+  /** Reports nothing while no index is kept. */
+  async checkIndexes(): Promise<IndexDifference[]> {
+    const kept = this.keptIndex();
+    return kept ? kept.index.differencesFrom(kept.analysis) : [];
+  }
+
+  /** Answers `read` from the kept index, with copies of the records it finds. */
+  private async query<T>(read: (index: AnalysisIndex) => T): Promise<T> {
+    return jsonCopy(read(await this.indexed()));
+  }
+
+  /**
+   * The kept index, built over the stored records first when none is kept.
+   *
+   * @throws Whatever loading the stored records throws.
+   */
+  protected abstract indexed(): Promise<AnalysisIndex>;
+
+  /** The kept index and the analysis it is kept over, or `undefined` when none is kept. */
+  protected abstract keptIndex(): IndexedAnalysis | undefined;
+}
diff --git a/src/services/projectStorage.ts b/src/services/projectStorage.ts
index e6eefe7a3..185bf6ed0 100644
--- a/src/services/projectStorage.ts
+++ b/src/services/projectStorage.ts
@@ -1133,6 +1133,21 @@ export function openDraftRepository(
     replaceAll: (draft, options) => counted((repository) => repository.replaceAll(draft, options)),
     markClean: () => queued((repository) => repository.markClean()),
     apply: (changes) => counted((repository) => repository.apply(changes)),
+    getTokenAnalyses: (ids) => queued((repository) => repository.getTokenAnalyses(ids)),
+    getPhraseAnalyses: (ids) => queued((repository) => repository.getPhraseAnalyses(ids)),
+    getSegmentAnalyses: (ids) => queued((repository) => repository.getSegmentAnalyses(ids)),
+    findLinksByToken: (tokenRefs) => queued((repository) => repository.findLinksByToken(tokenRefs)),
+    findLinksBySegment: (segmentIds) =>
+      queued((repository) => repository.findLinksBySegment(segmentIds)),
+    findLinksToAnalyses: (analysisIds) =>
+      queued((repository) => repository.findLinksToAnalyses(analysisIds)),
+    findLinksInBooks: (bookCodes, statuses) =>
+      queued((repository) => repository.findLinksInBooks(bookCodes, statuses)),
+    findTokenAnalysesByForm: (normalizedForms) =>
+      queued((repository) => repository.findTokenAnalysesByForm(normalizedForms)),
+    findPhraseAnalysesByForm: (normalizedForms) =>
+      queued((repository) => repository.findPhraseAnalysesByForm(normalizedForms)),
+    checkIndexes: () => queued((repository) => repository.checkIndexes()),
   };
 }
 
diff --git a/src/services/pt9ImportRepository.ts b/src/services/pt9ImportRepository.ts
index a8468b5a6..4ef0c3494 100644
--- a/src/services/pt9ImportRepository.ts
+++ b/src/services/pt9ImportRepository.ts
@@ -1,4 +1,4 @@
-import type { InterlinearProject } from 'interlinearizer';
+import type { DraftProject, InterlinearProject } from 'interlinearizer';
 import type {
   AnalysisRepository,
   ApplyResult,
@@ -7,18 +7,23 @@ import type {
 } from '../types/analysis-repository';
 import { CURRENT_MODEL_VERSION } from '../types/model-version';
 import { ReadOnlyAnalysisError } from '../types/read-only-analysis-error';
+import { AnalysisIndex } from './analysisIndex';
+import { IndexedRepository, type IndexedAnalysis } from './indexedRepository';
 
 /**
  * A Paratext 9 import's analysis, read in a draft's shape. Only a sync replaces an import's
  * content, so every write is refused.
  */
-export class Pt9ImportRepository implements AnalysisRepository {
+export class Pt9ImportRepository extends IndexedRepository implements AnalysisRepository {
   readonly capabilities: RepositoryCapabilities = { readOnly: true };
 
   private readonly interlinearProjectId: string;
 
   private readonly readProject: () => Promise<InterlinearProject | undefined>;
 
+  /** The import as a lookup last read it, with the index over its records; dropped by every load. */
+  private loaded: IndexedAnalysis | undefined;
+
   /**
    * @param interlinearProjectId - Id of the project to read, which must be a Paratext 9 import.
    * @param readProject - Reads the project stored under that id afresh, as a new object that the
@@ -28,6 +33,7 @@ export class Pt9ImportRepository implements AnalysisRepository {
     interlinearProjectId: string,
     readProject: () => Promise<InterlinearProject | undefined>,
   ) {
+    super();
     this.interlinearProjectId = interlinearProjectId;
     this.readProject = readProject;
   }
@@ -41,25 +47,8 @@ export class Pt9ImportRepository implements AnalysisRepository {
    * @throws Whatever reading the project throws.
    */
   async exportAll(): Promise<DraftExport> {
-    const project = await this.readProject();
-    if (!project?.pt9Import) {
-      throw new Error(
-        `Interlinearizer: no Paratext 9 import is stored as project ${this.interlinearProjectId}`,
-      );
-    }
-    const { sourceProjectId, analysisLanguages, targetProjectId, analysis, segmentation } = project;
-    return {
-      draft: {
-        sourceProjectId,
-        modelVersion: CURRENT_MODEL_VERSION,
-        analysisLanguages,
-        ...(targetProjectId !== undefined && { targetProjectId }),
-        analysis,
-        dirty: false,
-        ...(segmentation !== undefined && { segmentation }),
-      },
-      unreadableBooks: [],
-    };
+    this.loaded = undefined;
+    return { draft: await this.readImport(), unreadableBooks: [] };
   }
 
   /**
@@ -86,6 +75,42 @@ export class Pt9ImportRepository implements AnalysisRepository {
     throw this.readOnlyError();
   }
 
+  protected async indexed(): Promise<AnalysisIndex> {
+    if (!this.loaded) {
+      const { analysis } = await this.readImport();
+      this.loaded = { analysis, index: new AnalysisIndex(analysis) };
+    }
+    return this.loaded.index;
+  }
+
+  protected keptIndex(): IndexedAnalysis | undefined {
+    return this.loaded;
+  }
+
+  /**
+   * Reads the import as {@link exportAll} describes.
+   *
+   * @throws Whatever {@link exportAll} throws.
+   */
+  private async readImport(): Promise<DraftProject> {
+    const project = await this.readProject();
+    if (!project?.pt9Import) {
+      throw new Error(
+        `Interlinearizer: no Paratext 9 import is stored as project ${this.interlinearProjectId}`,
+      );
+    }
+    const { sourceProjectId, analysisLanguages, targetProjectId, analysis, segmentation } = project;
+    return {
+      sourceProjectId,
+      modelVersion: CURRENT_MODEL_VERSION,
+      analysisLanguages,
+      ...(targetProjectId !== undefined && { targetProjectId }),
+      analysis,
+      dirty: false,
+      ...(segmentation !== undefined && { segmentation }),
+    };
+  }
+
   private readOnlyError(): ReadOnlyAnalysisError {
     return new ReadOnlyAnalysisError(
       `Interlinearizer: Paratext 9 import ${this.interlinearProjectId} is read-only`,
diff --git a/src/services/recordTable.ts b/src/services/recordTable.ts
new file mode 100644
index 000000000..0878bec01
--- /dev/null
+++ b/src/services/recordTable.ts
@@ -0,0 +1,122 @@
+import type { IndexDifference, RecordChanges } from '../types/analysis-repository';
+
+/** The keys a derived index files a record under. */
+export type KeysOf<T> = (record: T) => readonly string[];
+
+/** Ids filed under keys. */
+type IdsByKey = Map<string, Set<string>>;
+
+function fileId(index: IdsByKey, key: string, id: string): void {
+  const ids = index.get(key);
+  if (ids) ids.add(id);
+  else index.set(key, new Set([id]));
+}
+
+function unfileId(index: IdsByKey, key: string, id: string): void {
+  const ids = index.get(key);
+  /* v8 ignore next -- a record's keys were filed when it was put */
+  if (!ids) return;
+  ids.delete(id);
+  if (ids.size === 0) index.delete(key);
+}
+
+/** The ids in `a` that `b` lacks. */
+function idsLacking(a: ReadonlySet<string> | undefined, b: ReadonlySet<string> | undefined) {
+  return [...(a ?? [])].filter((id) => !b?.has(id));
+}
+
+/** One record kind's records by id, with the derived indexes kept over them. */
+export class RecordTable<T extends { id: string }, Index extends string> {
+  private readonly kind: string;
+
+  private readonly keyers: Record<Index, KeysOf<T>>;
+
+  private readonly records = new Map<string, T>();
+
+  private readonly indexes = new Map<Index, IdsByKey>();
+
+  constructor(kind: string, keyers: Record<Index, KeysOf<T>>, records: readonly T[]) {
+    this.kind = kind;
+    this.keyers = keyers;
+    this.indexNames().forEach((index) => this.indexes.set(index, new Map()));
+    records.forEach((record) => this.put(record));
+  }
+
+  /** The records stored under `ids`, each once. */
+  get(ids: readonly string[]): T[] {
+    return [...new Set(ids)].flatMap((id) => this.records.get(id) ?? []);
+  }
+
+  /** The records `index` files under any of `keys`, each once. */
+  find(index: Index, keys: readonly string[]): T[] {
+    const filed = this.filed(index);
+    const ids = new Set(keys.flatMap((key) => [...(filed.get(key) ?? [])]));
+    return this.get([...ids]);
+  }
+
+  /** Applies one record kind's puts and deletes; absent changes apply nothing. */
+  apply(changes: RecordChanges<T> | undefined): void {
+    changes?.puts.forEach((record) => this.put(record));
+    changes?.deletes.forEach((id) => this.remove(id));
+  }
+
+  /**
+   * Where this table differs from `rebuilt`, a table of the same kind built afresh. A record whose
+   * kept copy differs from the rebuilt one is both missing and extra.
+   */
+  differencesFrom(rebuilt: RecordTable<T, Index>): IndexDifference[] {
+    const ids = new Set([...this.records.keys(), ...rebuilt.records.keys()]);
+    const recordDifferences = [...ids].flatMap((id): IndexDifference[] => {
+      const kept = this.records.get(id);
+      const stored = rebuilt.records.get(id);
+      if (JSON.stringify(kept) === JSON.stringify(stored)) return [];
+      return [{ index: this.kind, key: id, missing: stored ? [id] : [], extra: kept ? [id] : [] }];
+    });
+    const indexDifferences = this.indexNames().flatMap((index) => {
+      const kept = this.filed(index);
+      const fresh = rebuilt.filed(index);
+      const keys = new Set([...kept.keys(), ...fresh.keys()]);
+      return [...keys].flatMap((key): IndexDifference[] => {
+        const missing = idsLacking(fresh.get(key), kept.get(key));
+        const extra = idsLacking(kept.get(key), fresh.get(key));
+        if (missing.length === 0 && extra.length === 0) return [];
+        return [{ index: `${this.kind} by ${index}`, key, missing, extra }];
+      });
+    });
+    return [...recordDifferences, ...indexDifferences];
+  }
+
+  private indexNames(): Index[] {
+    // Object.keys widens to string[]; the keys are exactly the keyers' index names.
+    return Object.keys(this.keyers).filter((name): name is Index => name in this.keyers);
+  }
+
+  private filed(index: Index): IdsByKey {
+    const filed = this.indexes.get(index);
+    /* v8 ignore next -- the constructor gives every index its map */
+    if (!filed) throw new Error(`Interlinearizer: ${this.kind} has no index by ${index}`);
+    return filed;
+  }
+
+  /** The keys `index` files `record` under, each once. */
+  private keysOf(index: Index, record: T): Set<string> {
+    return new Set(this.keyers[index](record));
+  }
+
+  private put(record: T): void {
+    this.remove(record.id);
+    this.records.set(record.id, record);
+    this.indexNames().forEach((index) =>
+      this.keysOf(index, record).forEach((key) => fileId(this.filed(index), key, record.id)),
+    );
+  }
+
+  private remove(id: string): void {
+    const record = this.records.get(id);
+    if (!record) return;
+    this.records.delete(id);
+    this.indexNames().forEach((index) =>
+      this.keysOf(index, record).forEach((key) => unfileId(this.filed(index), key, id)),
+    );
+  }
+}
diff --git a/src/types/analysis-repository.ts b/src/types/analysis-repository.ts
index e19571e19..355dcf100 100644
--- a/src/types/analysis-repository.ts
+++ b/src/types/analysis-repository.ts
@@ -1,4 +1,12 @@
-import type { DraftProject, TextAnalysis } from 'interlinearizer';
+import type {
+  AssignmentStatus,
+  DraftProject,
+  PhraseAnalysis,
+  SegmentAnalysis,
+  SegmentAnalysisLink,
+  TextAnalysis,
+  TokenAnalysis,
+} from 'interlinearizer';
 
 /** Text records by key. */
 export interface KeyValueStorage {
@@ -86,12 +94,29 @@ export type ApplyResult = {
   inverse: ChangeSet;
 };
 
+/** Links of every kind, one list per kind. */
+export type AnalysisLinks = Pick<
+  TextAnalysis,
+  'tokenAnalysisLinks' | 'phraseAnalysisLinks' | 'segmentAnalysisLinks'
+>;
+
+/** Where a derived index a repository keeps differs from one rebuilt from its records. */
+export type IndexDifference = {
+  index: string;
+  /** The key whose entries differ. */
+  key: string;
+  /** Ids the rebuilt index files under the key that the kept one lacks. */
+  missing: string[];
+  /** Ids the kept index files under the key that the rebuilt one lacks. */
+  extra: string[];
+};
+
 /**
  * Reads and writes one source project's draft, or, when read-only, reads analysis in a draft's
  * shape. Every call is async and takes and returns only JSON-plain values, so an implementation may
  * sit behind a network boundary or another language. Once a call settles, the caller may change a
- * draft it passed in or got back without changing what is stored. Lists of records come back in no
- * promised order.
+ * draft or records it passed in or got back without changing what is stored. Lists of records come
+ * back in no promised order, and a lookup by several keys returns each record once.
  *
  * Calls for one draft must not overlap, whether on one repository or several. After one repository
  * saves a draft, any other that had already loaded or saved it must load it again before its next
@@ -168,4 +193,42 @@ export interface AnalysisRepository {
    *   unchanged, though storage may hold some of the changes until a later save.
    */
   apply(changes: ChangeSet): Promise<ApplyResult>;
+
+  /** The token analyses stored under `ids`; an id with none stored under it is skipped. */
+  getTokenAnalyses(ids: string[]): Promise<TokenAnalysis[]>;
+
+  /** The phrase analyses stored under `ids`; an id with none stored under it is skipped. */
+  getPhraseAnalyses(ids: string[]): Promise<PhraseAnalysis[]>;
+
+  /** The segment analyses stored under `ids`; an id with none stored under it is skipped. */
+  getSegmentAnalyses(ids: string[]): Promise<SegmentAnalysis[]>;
+
+  /** The token links on the tokens `tokenRefs` names, and the phrase links touching any of them. */
+  findLinksByToken(
+    tokenRefs: string[],
+  ): Promise<Pick<AnalysisLinks, 'tokenAnalysisLinks' | 'phraseAnalysisLinks'>>;
+
+  /** The segment links on the segments `segmentIds` names. */
+  findLinksBySegment(segmentIds: string[]): Promise<SegmentAnalysisLink[]>;
+
+  /** The links of every kind to the analyses `analysisIds` names. */
+  findLinksToAnalyses(analysisIds: string[]): Promise<AnalysisLinks>;
+
+  /**
+   * The links of every kind into the books `bookCodes` names, of any status when `statuses` is
+   * absent.
+   */
+  findLinksInBooks(bookCodes: string[], statuses?: AssignmentStatus[]): Promise<AnalysisLinks>;
+
+  /** The token analyses whose surface text normalizes to one of `normalizedForms`. */
+  findTokenAnalysesByForm(normalizedForms: string[]): Promise<TokenAnalysis[]>;
+
+  /** The phrase analyses whose surface text normalizes to one of `normalizedForms`. */
+  findPhraseAnalysesByForm(normalizedForms: string[]): Promise<PhraseAnalysis[]>;
+
+  /**
+   * Rebuilds the derived indexes the repository keeps from its records and reports where the kept
+   * ones differ, for debugging. A repository keeping none reports nothing.
+   */
+  checkIndexes(): Promise<IndexDifference[]>;
 }
diff --git a/src/types/interlinearizer.d.ts b/src/types/interlinearizer.d.ts
index 06ab18d47..b7be3e07c 100644
--- a/src/types/interlinearizer.d.ts
+++ b/src/types/interlinearizer.d.ts
@@ -381,6 +381,15 @@ declare module 'papi-shared-types' {
      */
     'interlinearizer.redoEdit': (sessionId: string) => Promise<string | undefined>;
 
+    /**
+     * Rebuilds a session's derived indexes from its records and reports where the kept ones differ,
+     * for debugging.
+     *
+     * @returns A JSON string of `[{ index, key, missing, extra }]`, empty when none differ.
+     * @throws If the session is not open, or its records cannot be read (logged before rethrowing).
+     */
+    'interlinearizer.checkIndexes': (sessionId: string) => Promise<string>;
+
     /**
      * Turns the extension host's timing entries on or off, discarding any it holds. Off until
      * turned on.
diff --git a/src/utils/change-set.ts b/src/utils/change-set.ts
index ecc046174..9d3ee463b 100644
--- a/src/utils/change-set.ts
+++ b/src/utils/change-set.ts
@@ -7,11 +7,6 @@ export type AppliedChanges = {
   inverse: ChangeSet;
 };
 
-/** A copy of a JSON-plain value that shares nothing with it. */
-function copyOf<T>(value: T): T {
-  return JSON.parse(JSON.stringify(value));
-}
-
 /** The draft's record, without its analysis. */
 // eslint-disable-next-line @typescript-eslint/no-unused-vars -- named only to leave it out
 export function scopeRecordOf({ analysis, ...scope }: DraftProject): ScopeRecord {
@@ -41,7 +36,7 @@ function applyRecordChanges<T extends { id: string }>(
 
   const stored = new Map(records.map((record) => [record.id, record]));
   const deleted = new Set(changes.deletes);
-  const puts = new Map(changes.puts.map((record) => [record.id, copyOf(record)]));
+  const puts = new Map(changes.puts.map((record) => [record.id, record]));
   const inverse: RecordChanges<T> = { puts: [], deletes: [] };
   changes.puts.forEach(({ id }) => {
     const prior = stored.get(id);
@@ -68,8 +63,8 @@ function applyRecordChanges<T extends { id: string }>(
 }
 
 /**
- * Applies `changes` to `draft`, leaving `draft` as it was. The result holds copies of the records
- * the changes put, and shares everything else with `draft`, the records the inverse restores
+ * Applies `changes` to `draft`, leaving `draft` as it was. The result shares the records the
+ * changes put with `changes`, and everything else with `draft`, the records the inverse restores
  * included.
  *
  * @throws {Error} If an id appears more than once in one record kind's changes, or the scope's
@@ -125,7 +120,7 @@ export function applyChangeSet(draft: DraftProject, changes: ChangeSet): Applied
   };
   return {
     draft: {
-      ...(changes.scope ? copyOf(changes.scope) : scopeRecordOf(draft)),
+      ...(changes.scope ?? scopeRecordOf(draft)),
       analysis: {
         segmentAnalyses: segmentAnalyses.records,
         segmentAnalysisLinks: segmentAnalysisLinks.records,
diff --git a/src/utils/json-copy.ts b/src/utils/json-copy.ts
new file mode 100644
index 000000000..eb6d43879
--- /dev/null
+++ b/src/utils/json-copy.ts
@@ -0,0 +1,4 @@
+/** A deep copy of a JSON-plain value, sharing nothing with it. */
+export function jsonCopy<T>(value: T): T {
+  return JSON.parse(JSON.stringify(value));
+}

From f539ff4b00a37b0467b1a5e2f6ff84c63257f703 Mon Sep 17 00:00:00 2001
From: Alex Rawlings <alex.rawlings@wycliffe.ca>
Date: Thu, 22 Oct 2026 10:49:50 -0600
Subject: [PATCH 11/22] Add token commands with parity tests (#443)

---
 AGENTS.md                                     |   2 +
 .../analysis-repository-conformance.ts        |  21 +
 src/__tests__/main.test.ts                    |  58 ++
 .../services/analysisSessions.test.ts         |  96 +++
 .../services/commands/approvalRule.test.ts    |  92 +++
 .../services/commands/changeBuffer.test.ts    | 192 ++++++
 src/__tests__/services/commands/parity.ts     |  75 +++
 .../commands/tokenCommands.parity.test.ts     | 548 ++++++++++++++++++
 .../services/commands/tokenCommands.test.ts   |  92 +++
 .../services/indexedRepository.test.ts        |  32 +-
 src/__tests__/services/projectStorage.test.ts |   5 +
 src/__tests__/utils/change-set.test.ts        |  18 +-
 .../utils/token-analysis-content.test.ts      |  59 ++
 src/main.ts                                   | 144 ++++-
 src/services/analysisSessions.ts              |  32 +
 src/services/commands/approvalRule.ts         |  69 +++
 src/services/commands/changeBuffer.ts         | 214 +++++++
 src/services/commands/tokenCommands.ts        | 291 ++++++++++
 src/services/draftRepository.ts               |  26 +-
 src/services/indexedRepository.ts             |  29 +-
 src/services/projectStorage.ts                |   1 +
 src/services/pt9ImportRepository.ts           |  15 +-
 src/store/analysisSlice.ts                    |  41 +-
 src/types/analysis-repository.ts              |   7 +
 src/types/interlinearizer.d.ts                |  28 +
 src/utils/change-set.ts                       |   5 +
 src/utils/token-analysis-content.ts           |  42 ++
 27 files changed, 2147 insertions(+), 87 deletions(-)
 create mode 100644 src/__tests__/services/commands/approvalRule.test.ts
 create mode 100644 src/__tests__/services/commands/changeBuffer.test.ts
 create mode 100644 src/__tests__/services/commands/parity.ts
 create mode 100644 src/__tests__/services/commands/tokenCommands.parity.test.ts
 create mode 100644 src/__tests__/services/commands/tokenCommands.test.ts
 create mode 100644 src/__tests__/utils/token-analysis-content.test.ts
 create mode 100644 src/services/commands/approvalRule.ts
 create mode 100644 src/services/commands/changeBuffer.ts
 create mode 100644 src/services/commands/tokenCommands.ts
 create mode 100644 src/utils/token-analysis-content.ts

diff --git a/AGENTS.md b/AGENTS.md
index 435e6c976..9cb9c55dd 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -87,6 +87,8 @@ Saved projects are listed through [ProjectSummaries](src/services/projectSummari
 
 [AnalysisSessions](src/services/analysisSessions.ts) keeps the host's sessions, behind the `openSession`, `closeSession` and `setAnalysisLanguage` commands. A session is a handle on one source project's draft, paired with the interlinear project it saves to, or on a Paratext 9 import alone, read-only. A source has at most one session: opening another closes it. Each session runs its commands one at a time, through `run`, or `runEdit` for a command that changes stored analysis, which a read-only session refuses. An edit reaches the repository as a `ChangeSet` of whole-record puts and deletes, applied through the session's [EditHistory](src/services/editHistory.ts) so that undo can revert it; boundary changes ride in the change set's scope record. The WebView doesn't use sessions yet.
 
+Host commands live in [src/services/commands/](src/services/commands/), one module per family. A command stages its changes in a [ChangeBuffer](src/services/commands/changeBuffer.ts), whose reads answer as the repository will once those changes apply, and `AnalysisSessions.edit` applies what it staged as one undo step after the approval rule passes. Each command copies the reducer it replaces, step for step, and its parity tests run one input through both with [runParity](src/__tests__/services/commands/parity.ts); a reducer change in Phase 3 updates its command and parity tests in the same PR.
+
 ### 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/src/__tests__/analysis-repository-conformance.ts b/src/__tests__/analysis-repository-conformance.ts
index 3b60706dc..373a3a724 100644
--- a/src/__tests__/analysis-repository-conformance.ts
+++ b/src/__tests__/analysis-repository-conformance.ts
@@ -1126,6 +1126,27 @@ export function describeAnalysisRepositoryConformance(
         return store.open(SOURCE);
       }
 
+      it("reads the draft's own record", async () => {
+        const repository = await overFullDraft();
+
+        await expect(repository.getScope()).resolves.toStrictEqual(scopeRecordOf(fullDraft()));
+      });
+
+      it("reads the record of a draft never saved as an empty draft's", async () => {
+        await expect((await store.open(SOURCE)).getScope()).resolves.toStrictEqual(
+          scopeRecordOf(emptyDraft(SOURCE)),
+        );
+      });
+
+      it('reads the record the applied changes leave', async () => {
+        const repository = await overFullDraft();
+        const scope = { ...scopeRecordOf(fullDraft()), dirty: false, analysisLanguages: ['de'] };
+
+        await repository.apply({ intent: 'rescope', scope });
+
+        await expect(repository.getScope()).resolves.toStrictEqual(scope);
+      });
+
       it('gets each payload kind by id, once per id, skipping ids with nothing stored', async () => {
         const repository = await overFullDraft();
 
diff --git a/src/__tests__/main.test.ts b/src/__tests__/main.test.ts
index b24169bbe..7973e5b8d 100644
--- a/src/__tests__/main.test.ts
+++ b/src/__tests__/main.test.ts
@@ -12,6 +12,7 @@ import * as projectStorage from '../services/projectStorage';
 import * as pt9ImportService from '../services/pt9ImportService';
 import { type AnalysisRepository, UnreadableBooksError } from '../types/analysis-repository';
 import { emptyDraft } from '../types/empty-factories';
+import { scopeRecordOf } from '../utils/change-set';
 import { toProjectSummary } from '../types/interlinear-project-summary';
 import { createTestActivationContext, makeStubProject } from './test-helpers';
 
@@ -401,6 +402,8 @@ describe('main', () => {
           'interlinearizer.undoEdit',
           'interlinearizer.redoEdit',
           'interlinearizer.checkIndexes',
+          'interlinearizer.writeGloss',
+          'interlinearizer.approveAnalysisForToken',
           'interlinearizer.openSelectProjectModal',
           'interlinearizer.openNewProjectModal',
           'interlinearizer.openProjectInfoModal',
@@ -1848,6 +1851,7 @@ describe('main', () => {
         checkIndexes: async () => [
           { index: 'tokenAnalyses', key: 'ta-1', missing: ['ta-1'], extra: [] },
         ],
+        getScope: async () => scopeRecordOf(draft),
       };
     }
 
@@ -1877,6 +1881,22 @@ describe('main', () => {
         checkIndexes: handler<(sessionId: string) => Promise<string>>(
           'interlinearizer.checkIndexes',
         ),
+        writeGloss: handler<
+          (
+            sessionId: string,
+            tokenRef: string,
+            surfaceText: string,
+            value: string,
+          ) => Promise<string>
+        >('interlinearizer.writeGloss'),
+        approveAnalysisForToken: handler<
+          (
+            sessionId: string,
+            tokenRef: string,
+            surfaceText: string,
+            analysisId: string,
+          ) => Promise<string>
+        >('interlinearizer.approveAnalysisForToken'),
       };
     }
 
@@ -2060,6 +2080,44 @@ describe('main', () => {
       );
     });
 
+    it("writes a token's gloss in the session's language, replying with the changes", async () => {
+      const { openSession, setAnalysisLanguage, writeGloss } = await activateSessionCommands();
+      const { sessionId } = JSON.parse(await openSession('src-project'));
+      await setAnalysisLanguage(sessionId, 'fr');
+
+      const changes = JSON.parse(await writeGloss(sessionId, 'GEN 1:1:0', 'In', 'au'));
+
+      expect(changes).toMatchObject({
+        intent: 'writeGloss',
+        tokenAnalyses: { puts: [{ surfaceText: 'In', gloss: { fr: 'au' } }], deletes: [] },
+        tokenAnalysisLinks: {
+          puts: [{ status: 'approved', token: { tokenRef: 'GEN 1:1:0', surfaceText: 'In' } }],
+          deletes: [],
+        },
+      });
+    });
+
+    it('logs the error and rethrows when an edit fails', async () => {
+      const { writeGloss } = await activateSessionCommands();
+
+      await expect(writeGloss('not-a-session', 'GEN 1:1:0', 'In', 'at')).rejects.toThrow(
+        'no session not-a-session is open',
+      );
+      expect(__mockLogger.error).toHaveBeenCalledWith(
+        'Interlinearizer: failed to writeGloss in session not-a-session',
+        expect.any(Error),
+      );
+    });
+
+    it('approves an analysis for a token, replying with the changes', async () => {
+      const { openSession, approveAnalysisForToken } = await activateSessionCommands();
+      const { sessionId } = JSON.parse(await openSession('src-project'));
+
+      await expect(
+        approveAnalysisForToken(sessionId, 'GEN 1:1:0', 'In', 'ta-unknown').then(JSON.parse),
+      ).resolves.toStrictEqual({ intent: 'approveAnalysisForToken' });
+    });
+
     it('closes every session on deactivation', async () => {
       const { openSession } = await activateSessionCommands();
       await openSession('src-project');
diff --git a/src/__tests__/services/analysisSessions.test.ts b/src/__tests__/services/analysisSessions.test.ts
index 0d5688c03..f5e19487a 100644
--- a/src/__tests__/services/analysisSessions.test.ts
+++ b/src/__tests__/services/analysisSessions.test.ts
@@ -6,6 +6,7 @@ import {
   type SessionHost,
   UNDETERMINED_LANGUAGE,
 } from '../../services/analysisSessions';
+import { ApprovalRuleError } from '../../services/commands/approvalRule';
 import { DraftRepository } from '../../services/draftRepository';
 import { Pt9ImportRepository } from '../../services/pt9ImportRepository';
 import { draftKey } from '../../services/storageKeys';
@@ -473,6 +474,101 @@ describe('AnalysisSessions', () => {
     });
   });
 
+  describe('edit', () => {
+    const payload = (id: string) => ({ id, ...FIXTURE_STAMPS, surfaceText: id });
+    const approvedLink = (id: string) => ({
+      id,
+      analysisId: 'a',
+      ...FIXTURE_STAMPS,
+      status: 'approved' as const,
+      token: { tokenRef: 'GEN 1:1:0', surfaceText: 'a' },
+    });
+
+    /** The source project's draft as stored. */
+    const stored = async (storage: ReturnType<typeof makeSessions>['storage']) =>
+      (await new DraftRepository(storage, SOURCE, silentLogger()).exportAll()).draft;
+
+    it('applies what the command stages as one undo step, marking the draft dirty', async () => {
+      const { sessions, storage } = makeSessions();
+      const { sessionId } = await sessions.open(SOURCE);
+
+      const changes = await sessions.edit(sessionId, 'add', async (buffer) => {
+        buffer.create('tokenAnalyses', payload('a'));
+        buffer.create('tokenAnalyses', payload('b'));
+      });
+
+      expect(changes).toMatchObject({ intent: 'add', scope: { dirty: true } });
+      await expect(stored(storage)).resolves.toMatchObject({
+        dirty: true,
+        analysis: { tokenAnalyses: [payload('a'), payload('b')] },
+      });
+      await sessions.undo(sessionId);
+      await expect(stored(storage)).resolves.toMatchObject({
+        dirty: false,
+        analysis: { tokenAnalyses: [] },
+      });
+    });
+
+    it('leaves the scope alone on a draft already dirty', async () => {
+      const { sessions, saveDraft } = makeSessions();
+      await saveDraft({ ...emptyDraft(SOURCE), dirty: true });
+      const { sessionId } = await sessions.open(SOURCE);
+
+      const changes = await sessions.edit(sessionId, 'add', async (buffer) => {
+        buffer.create('tokenAnalyses', payload('a'));
+      });
+
+      expect(changes).not.toHaveProperty('scope');
+    });
+
+    it('applies nothing, and records no undo step, for a command staging nothing', async () => {
+      const { sessions, storage } = makeSessions();
+      const { sessionId } = await sessions.open(SOURCE);
+
+      await expect(sessions.edit(sessionId, 'nothing', async () => {})).resolves.toStrictEqual({
+        intent: 'nothing',
+      });
+
+      await expect(sessions.undo(sessionId)).resolves.toBeUndefined();
+      await expect(stored(storage)).resolves.toMatchObject({ dirty: false });
+    });
+
+    it('gives the command the session it runs on', async () => {
+      const { sessions } = makeSessions();
+      const { sessionId } = await sessions.open(SOURCE);
+      await sessions.setAnalysisLanguage(sessionId, 'fr');
+
+      await sessions.edit(sessionId, 'read', async (_buffer, session) => {
+        expect(session.analysisLanguage).toBe('fr');
+      });
+    });
+
+    it('refuses changes that would approve a second analysis for a token, applying nothing', async () => {
+      const { sessions, storage } = makeSessions();
+      const { sessionId } = await sessions.open(SOURCE);
+
+      await expect(
+        sessions.edit(sessionId, 'approveTwice', async (buffer) => {
+          buffer.create('tokenAnalysisLinks', approvedLink('l-1'));
+          buffer.create('tokenAnalysisLinks', approvedLink('l-2'));
+        }),
+      ).rejects.toThrow(ApprovalRuleError);
+
+      await expect(stored(storage)).resolves.toMatchObject({
+        analysis: { tokenAnalysisLinks: [] },
+      });
+    });
+
+    it("refuses an edit on a Paratext 9 import's session without running it", async () => {
+      const { sessions } = makeSessions([makeImport()]);
+      const { sessionId } = await sessions.open(SOURCE, 'import-id');
+      const command = jest.fn(async () => {});
+
+      await expect(sessions.edit(sessionId, 'add', command)).rejects.toThrow(ReadOnlyAnalysisError);
+      expect(command).not.toHaveBeenCalled();
+    });
+  });
+
   describe('setAnalysisLanguage', () => {
     it('sets the language the commands sent after it read', async () => {
       const { sessions } = makeSessions();
diff --git a/src/__tests__/services/commands/approvalRule.test.ts b/src/__tests__/services/commands/approvalRule.test.ts
new file mode 100644
index 000000000..3c37315dd
--- /dev/null
+++ b/src/__tests__/services/commands/approvalRule.test.ts
@@ -0,0 +1,92 @@
+/// <reference types="jest" />
+
+import type { SegmentAnalysisLink, TextAnalysis, TokenAnalysisLink } from 'interlinearizer';
+import { ApprovalRuleError, assertApprovalRule } from '../../../services/commands/approvalRule';
+import { ChangeBuffer } from '../../../services/commands/changeBuffer';
+import { DraftRepository } from '../../../services/draftRepository';
+import { emptyAnalysis, emptyDraft } from '../../../types/empty-factories';
+import { FIXTURE_STAMPS, memoryStorage, silentLogger } from '../../test-helpers';
+
+function tokenLink(
+  id: string,
+  status: TokenAnalysisLink['status'] = 'approved',
+): TokenAnalysisLink {
+  return {
+    id,
+    analysisId: `ta-${id}`,
+    ...FIXTURE_STAMPS,
+    status,
+    token: { tokenRef: 'GEN 1:1:0', surfaceText: 'In' },
+  };
+}
+
+function segmentLink(id: string): SegmentAnalysisLink {
+  return {
+    id,
+    analysisId: `sa-${id}`,
+    ...FIXTURE_STAMPS,
+    status: 'approved',
+    segmentId: 'GEN 1:1',
+  };
+}
+
+async function over(analysis: Partial<TextAnalysis>) {
+  const { storage } = memoryStorage();
+  const repository = new DraftRepository(storage, 'src', silentLogger());
+  await repository.replaceAll({
+    ...emptyDraft('src'),
+    analysis: { ...emptyAnalysis(), ...analysis },
+  });
+  return { repository, buffer: new ChangeBuffer(repository) };
+}
+
+describe('assertApprovalRule', () => {
+  it('accepts changes that leave each token one approval', async () => {
+    const { repository, buffer } = await over({ tokenAnalysisLinks: [tokenLink('a')] });
+
+    buffer.delete('tokenAnalysisLinks', tokenLink('a'));
+    buffer.create('tokenAnalysisLinks', tokenLink('b'));
+
+    await expect(assertApprovalRule(buffer, repository)).resolves.toBeUndefined();
+  });
+
+  it('refuses a second approval for a token', async () => {
+    const { repository, buffer } = await over({ tokenAnalysisLinks: [tokenLink('a')] });
+
+    buffer.create('tokenAnalysisLinks', tokenLink('b'));
+
+    await expect(assertApprovalRule(buffer, repository)).rejects.toThrow(
+      new ApprovalRuleError(['GEN 1:1:0']),
+    );
+  });
+
+  it('refuses a second approval for a segment', async () => {
+    const { repository, buffer } = await over({ segmentAnalysisLinks: [segmentLink('a')] });
+
+    buffer.create('segmentAnalysisLinks', segmentLink('b'));
+
+    await expect(assertApprovalRule(buffer, repository)).rejects.toThrow(ApprovalRuleError);
+  });
+
+  it('accepts changes that leave a stored breach no worse', async () => {
+    const { repository, buffer } = await over({
+      tokenAnalysisLinks: [tokenLink('a'), tokenLink('b'), tokenLink('c', 'suggested')],
+    });
+
+    buffer.put('tokenAnalysisLinks', { ...tokenLink('a'), updatedAt: '2026-06-01T00:00:00.000Z' });
+    buffer.put('tokenAnalysisLinks', tokenLink('c', 'rejected'));
+
+    await expect(assertApprovalRule(buffer, repository)).resolves.toBeUndefined();
+  });
+
+  it('names the places it refuses on the error', async () => {
+    const { repository, buffer } = await over({});
+
+    buffer.create('tokenAnalysisLinks', tokenLink('a'));
+    buffer.create('tokenAnalysisLinks', tokenLink('b'));
+
+    await expect(assertApprovalRule(buffer, repository)).rejects.toMatchObject({
+      places: ['GEN 1:1:0'],
+    });
+  });
+});
diff --git a/src/__tests__/services/commands/changeBuffer.test.ts b/src/__tests__/services/commands/changeBuffer.test.ts
new file mode 100644
index 000000000..b6862527b
--- /dev/null
+++ b/src/__tests__/services/commands/changeBuffer.test.ts
@@ -0,0 +1,192 @@
+/// <reference types="jest" />
+
+import type { TextAnalysis, TokenAnalysis, TokenAnalysisLink } from 'interlinearizer';
+import { ChangeBuffer } from '../../../services/commands/changeBuffer';
+import { DraftRepository } from '../../../services/draftRepository';
+import { emptyAnalysis, emptyDraft } from '../../../types/empty-factories';
+import { FIXTURE_STAMPS, makePhraseLink, memoryStorage, silentLogger } from '../../test-helpers';
+
+function payload(id: string, surfaceText = id): TokenAnalysis {
+  return { id, ...FIXTURE_STAMPS, surfaceText };
+}
+
+function link(id: string, analysisId: string, tokenRef: string): TokenAnalysisLink {
+  return {
+    id,
+    analysisId,
+    ...FIXTURE_STAMPS,
+    status: 'approved',
+    token: { tokenRef, surfaceText: 'In' },
+  };
+}
+
+/** A buffer over a draft holding `analysis`. */
+async function bufferOver(analysis: Partial<TextAnalysis> = {}): Promise<ChangeBuffer> {
+  const { storage } = memoryStorage();
+  const repository = new DraftRepository(storage, 'src', silentLogger());
+  await repository.replaceAll({
+    ...emptyDraft('src'),
+    analysis: { ...emptyAnalysis(), ...analysis },
+  });
+  return new ChangeBuffer(repository);
+}
+
+const ids = (records: readonly { id: string }[]) => records.map(({ id }) => id).sort();
+
+describe('ChangeBuffer', () => {
+  it('reads stored records as the repository does while nothing is staged', async () => {
+    const buffer = await bufferOver({
+      tokenAnalyses: [payload('ta-1')],
+      tokenAnalysisLinks: [link('tl-1', 'ta-1', 'GEN 1:1:0')],
+    });
+
+    await expect(buffer.getTokenAnalyses(['ta-1'])).resolves.toStrictEqual([payload('ta-1')]);
+    await expect(buffer.findLinksToAnalyses(['ta-1'])).resolves.toStrictEqual({
+      tokenAnalysisLinks: [link('tl-1', 'ta-1', 'GEN 1:1:0')],
+      phraseAnalysisLinks: [],
+      segmentAnalysisLinks: [],
+    });
+  });
+
+  it('answers with a staged put in place of the stored record', async () => {
+    const buffer = await bufferOver({ tokenAnalyses: [payload('ta-1')] });
+
+    buffer.put('tokenAnalyses', { ...payload('ta-1'), gloss: { en: 'one' } });
+
+    await expect(buffer.getTokenAnalyses(['ta-1'])).resolves.toStrictEqual([
+      { ...payload('ta-1'), gloss: { en: 'one' } },
+    ]);
+  });
+
+  it('leaves a staged removal out of every read', async () => {
+    const stored = link('tl-1', 'ta-1', 'GEN 1:1:0');
+    const buffer = await bufferOver({ tokenAnalysisLinks: [stored] });
+
+    buffer.delete('tokenAnalysisLinks', stored);
+
+    await expect(buffer.findLinksByToken(['GEN 1:1:0'])).resolves.toStrictEqual({
+      tokenAnalysisLinks: [],
+      phraseAnalysisLinks: [],
+    });
+  });
+
+  it('finds a record a staged put moves into a lookup, and not one it moves out', async () => {
+    const buffer = await bufferOver({
+      tokenAnalysisLinks: [link('tl-1', 'ta-1', 'GEN 1:1:0'), link('tl-2', 'ta-2', 'GEN 1:1:0')],
+    });
+
+    buffer.put('tokenAnalysisLinks', link('tl-1', 'ta-2', 'GEN 1:1:0'));
+
+    await expect(buffer.findLinksToAnalyses(['ta-1'])).resolves.toMatchObject({
+      tokenAnalysisLinks: [],
+    });
+    const { tokenAnalysisLinks } = await buffer.findLinksToAnalyses(['ta-2']);
+    expect(ids(tokenAnalysisLinks)).toStrictEqual(['tl-1', 'tl-2']);
+  });
+
+  it('answers every lookup through the staged changes', async () => {
+    const phrase = makePhraseLink('pa-1', ['GEN 1:1:0', 'GEN 1:1:3']);
+    const segmentLink = {
+      id: 'sl-1',
+      analysisId: 'sa-1',
+      ...FIXTURE_STAMPS,
+      status: 'approved' as const,
+      segmentId: 'GEN 1:1',
+    };
+    const buffer = await bufferOver({
+      phraseAnalyses: [{ id: 'pa-1', ...FIXTURE_STAMPS, surfaceText: 'In the' }],
+      phraseAnalysisLinks: [phrase],
+      segmentAnalyses: [{ id: 'sa-1', ...FIXTURE_STAMPS, surfaceText: 'In the beginning' }],
+      segmentAnalysisLinks: [segmentLink],
+    });
+
+    buffer.create('tokenAnalyses', payload('ta-new', 'In'));
+
+    await expect(buffer.findTokenAnalysesByForm(['in'])).resolves.toStrictEqual([
+      payload('ta-new', 'In'),
+    ]);
+    await expect(buffer.findPhraseAnalysesByForm(['in the']).then(ids)).resolves.toStrictEqual([
+      'pa-1',
+    ]);
+    await expect(buffer.getPhraseAnalyses(['pa-1']).then(ids)).resolves.toStrictEqual(['pa-1']);
+    await expect(buffer.getSegmentAnalyses(['sa-1']).then(ids)).resolves.toStrictEqual(['sa-1']);
+    await expect(buffer.findLinksBySegment(['GEN 1:1'])).resolves.toStrictEqual([segmentLink]);
+    await expect(buffer.findLinksByToken(['GEN 1:1:3'])).resolves.toStrictEqual({
+      tokenAnalysisLinks: [],
+      phraseAnalysisLinks: [phrase],
+    });
+    await expect(buffer.findLinksToAnalyses(['pa-1', 'sa-1'])).resolves.toStrictEqual({
+      tokenAnalysisLinks: [],
+      phraseAnalysisLinks: [phrase],
+      segmentAnalysisLinks: [segmentLink],
+    });
+  });
+
+  it('hands out copies, so changing a record read stages nothing', async () => {
+    const buffer = await bufferOver({ tokenAnalyses: [payload('ta-1')] });
+    const [read] = await buffer.getTokenAnalyses(['ta-1']);
+
+    read.surfaceText = 'changed';
+
+    expect(buffer.toChangeSet('nothing')).toStrictEqual({ intent: 'nothing' });
+    await expect(buffer.getTokenAnalyses(['ta-1'])).resolves.toStrictEqual([payload('ta-1')]);
+  });
+
+  it('keeps a staged record as it stood when staged', async () => {
+    const buffer = await bufferOver();
+    const created = payload('ta-1');
+
+    buffer.create('tokenAnalyses', created);
+    created.surfaceText = 'changed';
+
+    expect(buffer.toChangeSet('create').tokenAnalyses?.puts).toStrictEqual([payload('ta-1')]);
+  });
+
+  it('collects the staged puts and removals of each kind into one change set', async () => {
+    const stored = link('tl-1', 'ta-1', 'GEN 1:1:0');
+    const buffer = await bufferOver({
+      tokenAnalyses: [payload('ta-1')],
+      tokenAnalysisLinks: [stored],
+    });
+
+    buffer.put('tokenAnalyses', { ...payload('ta-1'), gloss: { en: 'one' } });
+    buffer.delete('tokenAnalysisLinks', stored);
+
+    expect(buffer.toChangeSet('edit')).toStrictEqual({
+      intent: 'edit',
+      tokenAnalyses: { puts: [{ ...payload('ta-1'), gloss: { en: 'one' } }], deletes: [] },
+      tokenAnalysisLinks: { puts: [], deletes: ['tl-1'] },
+    });
+  });
+
+  it('stages nothing for a record it created and then removed', async () => {
+    const buffer = await bufferOver();
+
+    buffer.create('tokenAnalyses', payload('ta-new'));
+    buffer.delete('tokenAnalyses', payload('ta-new'));
+
+    expect(buffer.toChangeSet('none')).toStrictEqual({ intent: 'none' });
+  });
+
+  it('stages a put again after a removal of a stored record', async () => {
+    const buffer = await bufferOver({ tokenAnalyses: [payload('ta-1')] });
+
+    buffer.delete('tokenAnalyses', payload('ta-1'));
+    buffer.put('tokenAnalyses', payload('ta-1'));
+
+    expect(buffer.toChangeSet('restore').tokenAnalyses).toStrictEqual({
+      puts: [payload('ta-1')],
+      deletes: [],
+    });
+  });
+
+  it('lists the records it touches as they stood before a removal or will stand after a put', async () => {
+    const stored = link('tl-1', 'ta-1', 'GEN 1:1:0');
+    const buffer = await bufferOver({ tokenAnalysisLinks: [stored] });
+
+    buffer.delete('tokenAnalysisLinks', stored);
+    buffer.create('tokenAnalysisLinks', link('tl-2', 'ta-1', 'GEN 1:1:3'));
+
+    expect(ids(buffer.touched('tokenAnalysisLinks'))).toStrictEqual(['tl-1', 'tl-2']);
+  });
+});
diff --git a/src/__tests__/services/commands/parity.ts b/src/__tests__/services/commands/parity.ts
new file mode 100644
index 000000000..4307d22d1
--- /dev/null
+++ b/src/__tests__/services/commands/parity.ts
@@ -0,0 +1,75 @@
+/// <reference types="jest" />
+
+import type { UnknownAction } from '@reduxjs/toolkit';
+import type { TextAnalysis } from 'interlinearizer';
+import { ChangeBuffer } from '../../../services/commands/changeBuffer';
+import { DraftRepository } from '../../../services/draftRepository';
+import reducer from '../../../store/analysisSlice';
+import type { ChangeSet, IndexDifference } from '../../../types/analysis-repository';
+import { emptyDraft } from '../../../types/empty-factories';
+import { memoryStorage, silentLogger } from '../../test-helpers';
+
+/** What one input gives through the store's reducer and through the host's command. */
+export type ParityOutcome = {
+  /** The analysis the reducer leaves, its record lists in id order. */
+  store: TextAnalysis;
+  /** The analysis the command's changes leave once applied and reloaded, in id order. */
+  host: TextAnalysis;
+  /** The changes the command staged. */
+  changes: ChangeSet;
+  /** Where the repository's kept indexes differ from its records after applying the changes. */
+  indexDifferences: IndexDifference[];
+};
+
+/** `analysis` as JSON holds it, with each record list in id order. */
+function normalized(analysis: TextAnalysis): TextAnalysis {
+  const plain: TextAnalysis = JSON.parse(JSON.stringify(analysis));
+  const byId = <T extends { id: string }>(records: T[]) =>
+    [...records].sort((a, b) => a.id.localeCompare(b.id));
+  return {
+    segmentAnalyses: byId(plain.segmentAnalyses),
+    segmentAnalysisLinks: byId(plain.segmentAnalysisLinks),
+    tokenAnalyses: byId(plain.tokenAnalyses),
+    tokenAnalysisLinks: byId(plain.tokenAnalysisLinks),
+    phraseAnalyses: byId(plain.phraseAnalyses),
+    phraseAnalysisLinks: byId(plain.phraseAnalysisLinks),
+  };
+}
+
+/**
+ * Runs one input both ways over `analysis`: `action` through the store's reducer, working in
+ * `analysisLanguage`, and `command` staging changes over a draft holding the same analysis, which
+ * are then applied and the draft reloaded from storage.
+ */
+export async function runParity(
+  analysis: TextAnalysis,
+  analysisLanguage: string,
+  action: UnknownAction,
+  command: (buffer: ChangeBuffer) => Promise<void>,
+): Promise<ParityOutcome> {
+  const store = reducer(
+    { analysis: JSON.parse(JSON.stringify(analysis)), analysisLanguage },
+    action,
+  );
+
+  const { storage } = memoryStorage();
+  const logger = silentLogger();
+  await new DraftRepository(storage, 'src', logger).replaceAll({
+    ...emptyDraft('src'),
+    analysisLanguages: [analysisLanguage],
+    analysis: JSON.parse(JSON.stringify(analysis)),
+  });
+  const repository = new DraftRepository(storage, 'src', logger);
+  const buffer = new ChangeBuffer(repository);
+  await command(buffer);
+  const changes = buffer.toChangeSet('parity');
+  await repository.apply(changes);
+  const { draft: reloaded } = await new DraftRepository(storage, 'src', logger).exportAll();
+
+  return {
+    store: normalized(store.analysis),
+    host: normalized(reloaded.analysis),
+    changes,
+    indexDifferences: await repository.checkIndexes(),
+  };
+}
diff --git a/src/__tests__/services/commands/tokenCommands.parity.test.ts b/src/__tests__/services/commands/tokenCommands.parity.test.ts
new file mode 100644
index 000000000..a00234a54
--- /dev/null
+++ b/src/__tests__/services/commands/tokenCommands.parity.test.ts
@@ -0,0 +1,548 @@
+/// <reference types="jest" />
+
+import type { TextAnalysis, TokenAnalysis, TokenAnalysisLink } from 'interlinearizer';
+import {
+  approveAnalysisForToken as approveCommand,
+  writeGloss as writeGlossCommand,
+} from '../../../services/commands/tokenCommands';
+import { approveAnalysisForToken, writeGloss } from '../../../store/analysisSlice';
+import { emptyAnalysis } from '../../../types/empty-factories';
+import { FIXTURE_STAMPS } from '../../test-helpers';
+import { runParity } from './parity';
+
+const NOW = '2026-06-01T00:00:00.000Z';
+const EARLIER = { createdAt: '2025-06-01T00:00:00.000Z', updatedAt: '2025-06-01T00:00:00.000Z' };
+const LATER = { createdAt: '2026-03-01T00:00:00.000Z', updatedAt: '2026-03-01T00:00:00.000Z' };
+
+function payload(id: string, surfaceText: string, fields: Partial<TokenAnalysis> = {}) {
+  return { id, ...FIXTURE_STAMPS, surfaceText, ...fields };
+}
+
+function link(
+  id: string,
+  analysisId: string,
+  tokenRef: string,
+  fields: Partial<TokenAnalysisLink> = {},
+): TokenAnalysisLink {
+  return {
+    id,
+    analysisId,
+    ...FIXTURE_STAMPS,
+    status: 'approved',
+    token: { tokenRef, surfaceText: 'in' },
+    ...fields,
+  };
+}
+
+function analysisOf(
+  tokenAnalyses: TokenAnalysis[],
+  tokenAnalysisLinks: TokenAnalysisLink[],
+): TextAnalysis {
+  return { ...emptyAnalysis(), tokenAnalyses, tokenAnalysisLinks };
+}
+
+const TOKEN = 'GEN 1:1:0';
+const OTHER_TOKEN = 'GEN 1:2:0';
+
+type ParityCase<Input> = {
+  analysis: TextAnalysis;
+  input: Input;
+  /** What the reducer's result must show, so the case exercises the path it names. */
+  expectStore: (store: TextAnalysis) => void;
+};
+
+type GlossInput = { surfaceText?: string; value: string };
+
+const ids = (records: readonly { id: string }[]) => records.map(({ id }) => id).sort();
+
+describe('writeGloss parity with the reducer', () => {
+  const cases: [string, ParityCase<GlossInput>][] = [
+    [
+      'creates a payload and an approved link for an unglossed token',
+      {
+        analysis: emptyAnalysis(),
+        input: { value: 'at' },
+        expectStore: (store) => {
+          expect(ids(store.tokenAnalyses)).toStrictEqual(['new-analysis']);
+          expect(ids(store.tokenAnalysisLinks)).toStrictEqual(['new-link']);
+        },
+      },
+    ],
+    [
+      'shares a stored payload whose content matches',
+      {
+        analysis: analysisOf(
+          [payload('ta-in', 'in', { gloss: { en: 'at' } })],
+          [link('tl-other', 'ta-in', OTHER_TOKEN)],
+        ),
+        input: { value: 'at' },
+        expectStore: (store) => {
+          expect(ids(store.tokenAnalyses)).toStrictEqual(['ta-in']);
+          expect(store.tokenAnalysisLinks.find(({ id }) => id === 'new-link')?.analysisId).toBe(
+            'ta-in',
+          );
+        },
+      },
+    ],
+    [
+      "approves the token's held link to the matching payload rather than adding one",
+      {
+        analysis: analysisOf(
+          [payload('ta-in', 'in', { gloss: { en: 'at' } })],
+          [link('tl-held', 'ta-in', TOKEN, { status: 'suggested', confidence: 'low' })],
+        ),
+        input: { value: 'at' },
+        expectStore: (store) => {
+          expect(store.tokenAnalysisLinks).toHaveLength(1);
+          expect(store.tokenAnalysisLinks[0].status).toBe('approved');
+        },
+      },
+    ],
+    [
+      'edits an unshared payload in place, refreshing surface text and dropping its sense',
+      {
+        analysis: analysisOf(
+          [
+            payload('ta-in', 'In', {
+              gloss: { en: 'at', fr: 'à' },
+              glossSenseRef: { authority: 'fwlite', senseId: 's-at' },
+            }),
+          ],
+          [link('tl-in', 'ta-in', TOKEN)],
+        ),
+        input: { surfaceText: 'In,', value: 'at first' },
+        expectStore: (store) => {
+          expect(store.tokenAnalyses).toStrictEqual([
+            payload('ta-in', 'In,', { gloss: { en: 'at first', fr: 'à' }, updatedAt: NOW }),
+          ]);
+        },
+      },
+    ],
+    [
+      'forks a payload other tokens share, editing only the fork',
+      {
+        analysis: analysisOf(
+          [payload('ta-in', 'In', { gloss: { en: 'at' } })],
+          [link('tl-in', 'ta-in', TOKEN), link('tl-other', 'ta-in', OTHER_TOKEN)],
+        ),
+        input: { value: 'start' },
+        expectStore: (store) => {
+          expect(ids(store.tokenAnalyses)).toStrictEqual(['new-analysis', 'ta-in']);
+        },
+      },
+    ],
+    [
+      "folds an edit matching another payload into it, clearing the survivor's stale breakdown",
+      {
+        analysis: analysisOf(
+          [
+            payload('ta-at', 'in', { gloss: { en: 'at' } }),
+            payload('ta-within', 'In', {
+              ...EARLIER,
+              gloss: { en: 'within' },
+              morphemesStale: true,
+            }),
+          ],
+          [link('tl-in', 'ta-at', TOKEN), link('tl-other', 'ta-within', OTHER_TOKEN)],
+        ),
+        input: { value: 'within' },
+        expectStore: (store) => {
+          expect(ids(store.tokenAnalyses)).toStrictEqual(['ta-within']);
+          expect(store.tokenAnalyses[0].morphemesStale).toBeUndefined();
+        },
+      },
+    ],
+    [
+      'leaves a token linking both folded payloads one link, dated by the earlier',
+      {
+        analysis: analysisOf(
+          [
+            payload('ta-at', 'In', { gloss: { en: 'at' } }),
+            payload('ta-within', 'In', { ...EARLIER, gloss: { en: 'within' } }),
+          ],
+          [
+            link('tl-in', 'ta-at', TOKEN, LATER),
+            link('tl-offered', 'ta-within', TOKEN, { ...EARLIER, status: 'suggested' }),
+          ],
+        ),
+        input: { value: 'within' },
+        expectStore: (store) => {
+          expect(store.tokenAnalysisLinks).toHaveLength(1);
+          expect(store.tokenAnalysisLinks[0]).toMatchObject({
+            id: 'tl-in',
+            status: 'approved',
+            createdAt: EARLIER.createdAt,
+          });
+        },
+      },
+    ],
+    [
+      'folds into a payload another token was offered, leaving that offer as it was',
+      {
+        analysis: analysisOf(
+          [
+            payload('ta-at', 'In', { gloss: { en: 'at' } }),
+            payload('ta-within', 'In', { ...EARLIER, gloss: { en: 'within' } }),
+          ],
+          [
+            link('tl-in', 'ta-at', TOKEN),
+            link('tl-offered', 'ta-within', OTHER_TOKEN, { status: 'suggested' }),
+          ],
+        ),
+        input: { value: 'within' },
+        expectStore: (store) => {
+          expect(store.tokenAnalysisLinks).toStrictEqual(
+            expect.arrayContaining([
+              expect.objectContaining({ id: 'tl-offered', status: 'suggested' }),
+            ]),
+          );
+          expect(ids(store.tokenAnalyses)).toStrictEqual(['ta-within']);
+        },
+      },
+    ],
+    [
+      'clears the gloss, removing the payload it empties and its link',
+      {
+        analysis: analysisOf(
+          [payload('ta-in', 'In', { gloss: { en: 'at' } })],
+          [link('tl-in', 'ta-in', TOKEN)],
+        ),
+        input: { value: '' },
+        expectStore: (store) => {
+          expect(store).toStrictEqual(emptyAnalysis());
+        },
+      },
+    ],
+    [
+      'clears one language, keeping the others and the sense',
+      {
+        analysis: analysisOf(
+          [
+            payload('ta-in', 'In', {
+              gloss: { en: 'at', fr: 'à' },
+              glossSenseRef: { authority: 'fwlite', senseId: 's-at' },
+            }),
+          ],
+          [link('tl-in', 'ta-in', TOKEN)],
+        ),
+        input: { value: '  ' },
+        expectStore: (store) => {
+          expect(store.tokenAnalyses[0].gloss).toStrictEqual({ fr: 'à' });
+          expect(store.tokenAnalyses[0].glossSenseRef).toBeDefined();
+        },
+      },
+    ],
+    [
+      'clears a shared payload by dropping only this token’s link',
+      {
+        analysis: analysisOf(
+          [payload('ta-in', 'In', { gloss: { en: 'at' } })],
+          [link('tl-in', 'ta-in', TOKEN), link('tl-other', 'ta-in', OTHER_TOKEN)],
+        ),
+        input: { value: '' },
+        expectStore: (store) => {
+          expect(ids(store.tokenAnalyses)).toStrictEqual(['ta-in']);
+          expect(ids(store.tokenAnalysisLinks)).toStrictEqual(['tl-other']);
+        },
+      },
+    ],
+    [
+      'keeps an emptied payload another of the token’s links still names',
+      {
+        analysis: analysisOf(
+          [payload('ta-in', 'In', { gloss: { en: 'at' } })],
+          [
+            link('tl-in', 'ta-in', TOKEN),
+            link('tl-rejected', 'ta-in', TOKEN, { status: 'rejected' }),
+          ],
+        ),
+        input: { value: '' },
+        expectStore: (store) => {
+          expect(store.tokenAnalyses).toStrictEqual([payload('ta-in', 'In', { updatedAt: NOW })]);
+          expect(ids(store.tokenAnalysisLinks)).toStrictEqual(['tl-rejected']);
+        },
+      },
+    ],
+    [
+      'folds a cleared payload into another its remaining content matches',
+      {
+        analysis: analysisOf(
+          [
+            payload('ta-in', 'In', { gloss: { en: 'at' }, pos: 'prep' }),
+            payload('ta-bare', 'in', { ...EARLIER, pos: 'prep' }),
+          ],
+          [link('tl-in', 'ta-in', TOKEN)],
+        ),
+        input: { value: '' },
+        expectStore: (store) => {
+          expect(ids(store.tokenAnalyses)).toStrictEqual(['ta-bare']);
+          expect(store.tokenAnalysisLinks[0].analysisId).toBe('ta-bare');
+        },
+      },
+    ],
+    [
+      'folds a fork back onto the shared payload when the write leaves it unchanged',
+      {
+        analysis: analysisOf(
+          [payload('ta-in', 'In', { gloss: { en: 'at' } })],
+          [link('tl-in', 'ta-in', TOKEN), link('tl-other', 'ta-in', OTHER_TOKEN)],
+        ),
+        input: { value: 'at' },
+        expectStore: (store) => {
+          expect(ids(store.tokenAnalyses)).toStrictEqual(['ta-in']);
+          expect(store.tokenAnalysisLinks.every(({ analysisId }) => analysisId === 'ta-in')).toBe(
+            true,
+          );
+        },
+      },
+    ],
+    [
+      'edits the payload an approval tie picks among several approved links',
+      {
+        analysis: analysisOf(
+          [
+            payload('ta-old', 'In', { gloss: { en: 'old' } }),
+            payload('ta-new', 'In', { gloss: { en: 'new' } }),
+          ],
+          [link('tl-old', 'ta-old', TOKEN, EARLIER), link('tl-new', 'ta-new', TOKEN, LATER)],
+        ),
+        input: { value: 'newer' },
+        expectStore: (store) => {
+          expect(store.tokenAnalyses.find(({ id }) => id === 'ta-new')?.gloss).toStrictEqual({
+            en: 'newer',
+          });
+        },
+      },
+    ],
+    [
+      'stages nothing for a blank write to an unglossed token',
+      {
+        analysis: analysisOf([payload('ta-in', 'In', { gloss: { en: 'at' } })], []),
+        input: { value: '' },
+        expectStore: (store) => {
+          expect(ids(store.tokenAnalyses)).toStrictEqual(['ta-in']);
+        },
+      },
+    ],
+    [
+      'removes an approved link whose payload is gone before writing',
+      {
+        analysis: analysisOf([], [link('tl-orphan', 'ta-missing', TOKEN)]),
+        input: { value: 'at' },
+        expectStore: (store) => {
+          expect(ids(store.tokenAnalysisLinks)).toStrictEqual(['new-link']);
+        },
+      },
+    ],
+    [
+      'removes an approved link whose payload is gone even on a blank write',
+      {
+        analysis: analysisOf([], [link('tl-orphan', 'ta-missing', TOKEN)]),
+        input: { value: '' },
+        expectStore: (store) => {
+          expect(store).toStrictEqual(emptyAnalysis());
+        },
+      },
+    ],
+  ];
+
+  it.each(cases)('%s', async (_name, { analysis, input, expectStore }) => {
+    const surfaceText = input.surfaceText ?? 'In';
+    const outcome = await runParity(
+      analysis,
+      'en',
+      {
+        type: writeGloss.type,
+        payload: {
+          tokenRef: TOKEN,
+          surfaceText,
+          value: input.value,
+          id: 'new-analysis',
+          linkId: 'new-link',
+          now: NOW,
+        },
+      },
+      (buffer) =>
+        writeGlossCommand(buffer, {
+          tokenRef: TOKEN,
+          surfaceText,
+          value: input.value,
+          analysisLanguage: 'en',
+          analysisId: 'new-analysis',
+          linkId: 'new-link',
+          now: NOW,
+        }),
+    );
+
+    expectStore(outcome.store);
+    expect(outcome.host).toStrictEqual(outcome.store);
+    expect(outcome.indexDifferences).toStrictEqual([]);
+  });
+});
+
+type ApproveInput = { analysisId: string };
+
+describe('approveAnalysisForToken parity with the reducer', () => {
+  const cases: [string, ParityCase<ApproveInput>][] = [
+    [
+      'gives a token with no approval a new approved link',
+      {
+        analysis: analysisOf([payload('ta-in', 'In', { gloss: { en: 'at' } })], []),
+        input: { analysisId: 'ta-in' },
+        expectStore: (store) => {
+          expect(store.tokenAnalysisLinks).toStrictEqual([
+            {
+              id: 'new-link',
+              analysisId: 'ta-in',
+              createdAt: NOW,
+              updatedAt: NOW,
+              status: 'approved',
+              token: { tokenRef: TOKEN, surfaceText: 'In' },
+            },
+          ]);
+        },
+      },
+    ],
+    [
+      'approves the link the token holds to the payload rather than adding one',
+      {
+        analysis: analysisOf(
+          [payload('ta-in', 'In', { gloss: { en: 'at' } })],
+          [link('tl-held', 'ta-in', TOKEN, { status: 'candidate', confidence: 'guess' })],
+        ),
+        input: { analysisId: 'ta-in' },
+        expectStore: (store) => {
+          expect(store.tokenAnalysisLinks).toHaveLength(1);
+          expect(store.tokenAnalysisLinks[0]).toMatchObject({
+            status: 'approved',
+            confidence: 'guess',
+          });
+        },
+      },
+    ],
+    [
+      'moves the approval off a payload, removing it once nothing links it',
+      {
+        analysis: analysisOf(
+          [
+            payload('ta-at', 'In', { gloss: { en: 'at' } }),
+            payload('ta-on', 'In', { gloss: { en: 'on' } }),
+          ],
+          [link('tl-in', 'ta-at', TOKEN)],
+        ),
+        input: { analysisId: 'ta-on' },
+        expectStore: (store) => {
+          expect(ids(store.tokenAnalyses)).toStrictEqual(['ta-on']);
+          expect(store.tokenAnalysisLinks[0].analysisId).toBe('ta-on');
+        },
+      },
+    ],
+    [
+      'keeps the payload the approval leaves when another token links it',
+      {
+        analysis: analysisOf(
+          [
+            payload('ta-at', 'In', { gloss: { en: 'at' } }),
+            payload('ta-on', 'In', { gloss: { en: 'on' } }),
+          ],
+          [link('tl-in', 'ta-at', TOKEN), link('tl-other', 'ta-at', OTHER_TOKEN)],
+        ),
+        input: { analysisId: 'ta-on' },
+        expectStore: (store) => {
+          expect(ids(store.tokenAnalyses)).toStrictEqual(['ta-at', 'ta-on']);
+        },
+      },
+    ],
+    [
+      'approves a held link in place of the approval, keeping the earlier creation date',
+      {
+        analysis: analysisOf(
+          [
+            payload('ta-at', 'In', { gloss: { en: 'at' } }),
+            payload('ta-on', 'In', { gloss: { en: 'on' } }),
+          ],
+          [
+            link('tl-in', 'ta-at', TOKEN, EARLIER),
+            link('tl-held', 'ta-on', TOKEN, { ...LATER, status: 'suggested' }),
+          ],
+        ),
+        input: { analysisId: 'ta-on' },
+        expectStore: (store) => {
+          expect(store.tokenAnalysisLinks).toStrictEqual([
+            expect.objectContaining({
+              id: 'tl-held',
+              status: 'approved',
+              createdAt: EARLIER.createdAt,
+            }),
+          ]);
+          expect(ids(store.tokenAnalyses)).toStrictEqual(['ta-on']);
+        },
+      },
+    ],
+    [
+      'stages nothing for a payload not stored',
+      {
+        analysis: analysisOf([], [link('tl-orphan', 'ta-missing', TOKEN)]),
+        input: { analysisId: 'ta-unknown' },
+        expectStore: (store) => {
+          expect(ids(store.tokenAnalysisLinks)).toStrictEqual(['tl-orphan']);
+        },
+      },
+    ],
+    [
+      'removes orphaned approvals even when the payload is already approved',
+      {
+        analysis: analysisOf(
+          [payload('ta-in', 'In', { gloss: { en: 'at' } })],
+          [link('tl-in', 'ta-in', TOKEN, LATER), link('tl-orphan', 'ta-missing', TOKEN, EARLIER)],
+        ),
+        input: { analysisId: 'ta-in' },
+        expectStore: (store) => {
+          expect(ids(store.tokenAnalysisLinks)).toStrictEqual(['tl-in']);
+        },
+      },
+    ],
+    [
+      'removes orphaned approvals before approving',
+      {
+        analysis: analysisOf(
+          [payload('ta-in', 'In', { gloss: { en: 'at' } })],
+          [link('tl-orphan', 'ta-missing', TOKEN)],
+        ),
+        input: { analysisId: 'ta-in' },
+        expectStore: (store) => {
+          expect(ids(store.tokenAnalysisLinks)).toStrictEqual(['new-link']);
+        },
+      },
+    ],
+  ];
+
+  it.each(cases)('%s', async (_name, { analysis, input, expectStore }) => {
+    const outcome = await runParity(
+      analysis,
+      'en',
+      {
+        type: approveAnalysisForToken.type,
+        payload: {
+          tokenRef: TOKEN,
+          surfaceText: 'In',
+          analysisId: input.analysisId,
+          linkId: 'new-link',
+          now: NOW,
+        },
+      },
+      (buffer) =>
+        approveCommand(buffer, {
+          tokenRef: TOKEN,
+          surfaceText: 'In',
+          analysisId: input.analysisId,
+          linkId: 'new-link',
+          now: NOW,
+        }),
+    );
+
+    expectStore(outcome.store);
+    expect(outcome.host).toStrictEqual(outcome.store);
+    expect(outcome.indexDifferences).toStrictEqual([]);
+  });
+});
diff --git a/src/__tests__/services/commands/tokenCommands.test.ts b/src/__tests__/services/commands/tokenCommands.test.ts
new file mode 100644
index 000000000..7550f665e
--- /dev/null
+++ b/src/__tests__/services/commands/tokenCommands.test.ts
@@ -0,0 +1,92 @@
+/// <reference types="jest" />
+
+import type { TextAnalysis, TokenAnalysis, TokenAnalysisLink } from 'interlinearizer';
+import { ChangeBuffer } from '../../../services/commands/changeBuffer';
+import { approveAnalysisForToken, writeGloss } from '../../../services/commands/tokenCommands';
+import { DraftRepository } from '../../../services/draftRepository';
+import { emptyAnalysis, emptyDraft } from '../../../types/empty-factories';
+import { FIXTURE_STAMPS, memoryStorage, silentLogger } from '../../test-helpers';
+
+const NOW = '2026-06-01T00:00:00.000Z';
+const STAMP = { analysisId: 'new-analysis', linkId: 'new-link', now: NOW };
+
+const shared: TokenAnalysis = {
+  id: 'ta-in',
+  ...FIXTURE_STAMPS,
+  surfaceText: 'In',
+  gloss: { en: 'at' },
+};
+
+function link(id: string, tokenRef: string): TokenAnalysisLink {
+  return {
+    id,
+    analysisId: 'ta-in',
+    ...FIXTURE_STAMPS,
+    status: 'approved',
+    token: { tokenRef, surfaceText: 'In' },
+  };
+}
+
+async function bufferOver(analysis: Partial<TextAnalysis>): Promise<ChangeBuffer> {
+  const { storage } = memoryStorage();
+  const repository = new DraftRepository(storage, 'src', silentLogger());
+  await repository.replaceAll({
+    ...emptyDraft('src'),
+    analysis: { ...emptyAnalysis(), ...analysis },
+  });
+  return new ChangeBuffer(repository);
+}
+
+describe('writeGloss', () => {
+  it("stages only the link's removal when clearing a shared payload, never its fork", async () => {
+    const buffer = await bufferOver({
+      tokenAnalyses: [shared],
+      tokenAnalysisLinks: [link('tl-1', 'GEN 1:1:0'), link('tl-2', 'GEN 1:2:0')],
+    });
+
+    await writeGloss(buffer, {
+      ...STAMP,
+      tokenRef: 'GEN 1:1:0',
+      surfaceText: 'In',
+      value: '',
+      analysisLanguage: 'en',
+    });
+
+    expect(buffer.toChangeSet('writeGloss')).toStrictEqual({
+      intent: 'writeGloss',
+      tokenAnalysisLinks: { puts: [], deletes: ['tl-1'] },
+    });
+  });
+
+  it('stages nothing for a blank write to an unglossed token', async () => {
+    const buffer = await bufferOver({ tokenAnalyses: [shared] });
+
+    await writeGloss(buffer, {
+      ...STAMP,
+      tokenRef: 'GEN 1:1:0',
+      surfaceText: 'In',
+      value: ' ',
+      analysisLanguage: 'en',
+    });
+
+    expect(buffer.toChangeSet('writeGloss')).toStrictEqual({ intent: 'writeGloss' });
+  });
+});
+
+describe('approveAnalysisForToken', () => {
+  it('stages nothing for a payload already approved for the token', async () => {
+    const buffer = await bufferOver({
+      tokenAnalyses: [shared],
+      tokenAnalysisLinks: [link('tl-1', 'GEN 1:1:0')],
+    });
+
+    await approveAnalysisForToken(buffer, {
+      ...STAMP,
+      tokenRef: 'GEN 1:1:0',
+      surfaceText: 'In',
+      analysisId: 'ta-in',
+    });
+
+    expect(buffer.toChangeSet('approve')).toStrictEqual({ intent: 'approve' });
+  });
+});
diff --git a/src/__tests__/services/indexedRepository.test.ts b/src/__tests__/services/indexedRepository.test.ts
index 290a6cb98..dd3de6988 100644
--- a/src/__tests__/services/indexedRepository.test.ts
+++ b/src/__tests__/services/indexedRepository.test.ts
@@ -2,27 +2,30 @@
 
 import type { TextAnalysis } from 'interlinearizer';
 import { AnalysisIndex } from '../../services/analysisIndex';
-import { type IndexedAnalysis, IndexedRepository } from '../../services/indexedRepository';
-import { emptyAnalysis } from '../../types/empty-factories';
+import { type IndexedDraft, IndexedRepository } from '../../services/indexedRepository';
+import { emptyAnalysis, emptyDraft } from '../../types/empty-factories';
 import { FIXTURE_STAMPS } from '../test-helpers';
 
 /** Answers lookups from an index over `records`, keeping it as `keep` says. */
 class StubRepository extends IndexedRepository {
-  readonly kept: IndexedAnalysis | undefined;
+  readonly kept: IndexedDraft | undefined;
 
-  private readonly index: AnalysisIndex;
+  private readonly indexedDraft: IndexedDraft;
 
   constructor(records: TextAnalysis, keep: 'kept' | 'none') {
     super();
-    this.index = new AnalysisIndex(records);
-    this.kept = keep === 'kept' ? { analysis: records, index: this.index } : undefined;
+    this.indexedDraft = {
+      draft: { ...emptyDraft('src'), analysisLanguages: ['en'], analysis: records },
+      index: new AnalysisIndex(records),
+    };
+    this.kept = keep === 'kept' ? this.indexedDraft : undefined;
   }
 
-  protected async indexed(): Promise<AnalysisIndex> {
-    return this.index;
+  protected async indexed(): Promise<IndexedDraft> {
+    return this.indexedDraft;
   }
 
-  protected keptIndex(): IndexedAnalysis | undefined {
+  protected keptIndex(): IndexedDraft | undefined {
     return this.kept;
   }
 }
@@ -54,7 +57,7 @@ describe('IndexedRepository', () => {
 
   it('reports the differences of the index it keeps from its analysis', async () => {
     const repository = new StubRepository(analysis(), 'kept');
-    repository.kept?.analysis.tokenAnalyses.pop();
+    repository.kept?.draft.analysis.tokenAnalyses.pop();
 
     await expect(repository.checkIndexes()).resolves.toContainEqual({
       index: 'tokenAnalyses',
@@ -64,6 +67,15 @@ describe('IndexedRepository', () => {
     });
   });
 
+  it("reads the draft's own record without its analysis", async () => {
+    await expect(new StubRepository(analysis(), 'none').getScope()).resolves.toStrictEqual({
+      sourceProjectId: 'src',
+      modelVersion: emptyDraft('src').modelVersion,
+      analysisLanguages: ['en'],
+      dirty: false,
+    });
+  });
+
   it('reports nothing while it keeps no index', async () => {
     await expect(new StubRepository(analysis(), 'none').checkIndexes()).resolves.toStrictEqual([]);
   });
diff --git a/src/__tests__/services/projectStorage.test.ts b/src/__tests__/services/projectStorage.test.ts
index 948c16f9e..b2cdae455 100644
--- a/src/__tests__/services/projectStorage.test.ts
+++ b/src/__tests__/services/projectStorage.test.ts
@@ -2946,6 +2946,11 @@ describe('projectStorage', () => {
       ],
       ['findPhraseAnalysesByForm', (r: AnalysisRepository) => r.findPhraseAnalysesByForm(['x']), 0],
       ['checkIndexes', (r: AnalysisRepository) => r.checkIndexes(), 0],
+      [
+        'getScope',
+        (r: AnalysisRepository) => r.getScope().then(({ analysisLanguages }) => analysisLanguages),
+        0,
+      ],
     ])('answers %s from the draft saveDraft saved', async (_name, lookup, count) => {
       await saveDraft(token, 'src-proj', makeDraftSpanningBooks('src-proj', 'GEN'));
 
diff --git a/src/__tests__/utils/change-set.test.ts b/src/__tests__/utils/change-set.test.ts
index 7e6e57d1d..6d3802ee5 100644
--- a/src/__tests__/utils/change-set.test.ts
+++ b/src/__tests__/utils/change-set.test.ts
@@ -2,7 +2,7 @@
 
 import type { DraftProject, TokenAnalysis } from 'interlinearizer';
 import { emptyAnalysis, emptyDraft } from '../../types/empty-factories';
-import { applyChangeSet, scopeRecordOf } from '../../utils/change-set';
+import { applyChangeSet, isEmptyChangeSet, scopeRecordOf } from '../../utils/change-set';
 import { FIXTURE_STAMPS } from '../test-helpers';
 
 function payload(id: string, gloss?: string): TokenAnalysis {
@@ -179,3 +179,19 @@ describe('applyChangeSet', () => {
     ).toStrictEqual([['sa'], ['sl'], ['a'], ['tl'], ['pa'], ['pl']]);
   });
 });
+
+describe('isEmptyChangeSet', () => {
+  it('finds a change set naming only its intent empty', () => {
+    expect(isEmptyChangeSet({ intent: 'none' })).toBe(true);
+  });
+
+  it('finds a change set with record changes not empty', () => {
+    expect(isEmptyChangeSet({ intent: 'edit', tokenAnalyses: { puts: [], deletes: ['a'] } })).toBe(
+      false,
+    );
+  });
+
+  it("finds a change set putting the scope's record not empty", () => {
+    expect(isEmptyChangeSet({ intent: 'edit', scope: scopeRecordOf(draftOf()) })).toBe(false);
+  });
+});
diff --git a/src/__tests__/utils/token-analysis-content.test.ts b/src/__tests__/utils/token-analysis-content.test.ts
new file mode 100644
index 000000000..5625fd3a3
--- /dev/null
+++ b/src/__tests__/utils/token-analysis-content.test.ts
@@ -0,0 +1,59 @@
+/// <reference types="jest" />
+
+import type { TokenAnalysis } from 'interlinearizer';
+import { clearAnalysisGloss, isEmptyTokenAnalysis } from '../../utils/token-analysis-content';
+import { FIXTURE_STAMPS } from '../test-helpers';
+
+function analysis(fields: Partial<TokenAnalysis> = {}): TokenAnalysis {
+  return { id: 'ta-1', ...FIXTURE_STAMPS, surfaceText: 'In', ...fields };
+}
+
+describe('isEmptyTokenAnalysis', () => {
+  it('finds a record holding only blank glosses and provenance empty', () => {
+    expect(isEmptyTokenAnalysis(analysis({ gloss: { en: ' ' }, confidence: 'high' }))).toBe(true);
+  });
+
+  it.each([
+    ['a gloss', { gloss: { en: 'at' } }],
+    ['morphemes', { morphemes: [{ id: 'm-1', form: 'in', writingSystem: 'en' }] }],
+    ['a part of speech', { pos: 'prep' }],
+    ['features', { features: { case: 'loc' } }],
+    ['a gloss sense', { glossSenseRef: { authority: 'fwlite', senseId: 's-1' } }],
+  ])('finds a record holding %s not empty', (_field, fields) => {
+    expect(isEmptyTokenAnalysis(analysis(fields))).toBe(false);
+  });
+});
+
+describe('clearAnalysisGloss', () => {
+  it('clears one language, keeping the others and the sense', () => {
+    const record = analysis({
+      gloss: { en: 'at', fr: 'à' },
+      glossSenseRef: { authority: 'fwlite', senseId: 's-1' },
+    });
+
+    clearAnalysisGloss(record, 'en');
+
+    expect(record).toStrictEqual(
+      analysis({ gloss: { fr: 'à' }, glossSenseRef: { authority: 'fwlite', senseId: 's-1' } }),
+    );
+  });
+
+  it('drops the gloss and the sense once no language holds usable text', () => {
+    const record = analysis({
+      gloss: { en: 'at', fr: ' ' },
+      glossSenseRef: { authority: 'fwlite', senseId: 's-1' },
+    });
+
+    clearAnalysisGloss(record, 'en');
+
+    expect(record).toStrictEqual(analysis());
+  });
+
+  it('drops a sense left with no gloss at all', () => {
+    const record = analysis({ glossSenseRef: { authority: 'fwlite', senseId: 's-1' } });
+
+    clearAnalysisGloss(record, 'en');
+
+    expect(record).toStrictEqual(analysis());
+  });
+});
diff --git a/src/main.ts b/src/main.ts
index 1ec3369aa..d4e440d68 100644
--- a/src/main.ts
+++ b/src/main.ts
@@ -11,8 +11,10 @@ import type { ProjectConfig } from 'interlinearizer';
 import { formatReplacementString, type LocalizeKey } from 'platform-bible-utils';
 import interlinearizerReact from './interlinearizer.web-view?inline';
 import interlinearizerStyles from './interlinearizer.web-view.scss?inline';
-import { AnalysisSessions, type OpenedSession } from './services/analysisSessions';
+import { AnalysisSessions, type OpenedSession, type Session } from './services/analysisSessions';
 import * as bookService from './services/bookService';
+import type { ChangeBuffer } from './services/commands/changeBuffer';
+import * as tokenCommands from './services/commands/tokenCommands';
 import { readHostPerf, setHostPerfMarks } from './services/hostPerf';
 import * as projectStorage from './services/projectStorage';
 import * as pt9ImportService from './services/pt9ImportService';
@@ -826,6 +828,80 @@ async function checkIndexes(sessionId: string): Promise<string> {
   }
 }
 
+/**
+ * Runs `command` as one edit of a session's analysis.
+ *
+ * @returns The changes it applied, as JSON.
+ * @throws If the session is read-only or not open, or the edit is refused or fails. The error is
+ *   logged before rethrowing.
+ */
+async function runSessionEdit(
+  sessionId: string,
+  intent: string,
+  command: (buffer: ChangeBuffer, session: Session) => Promise<void>,
+): Promise<string> {
+  try {
+    return JSON.stringify(await sessions.edit(sessionId, intent, command));
+  } catch (e) {
+    logger.error(`Interlinearizer: failed to ${intent} in session ${sessionId}`, e);
+    throw e;
+  }
+}
+
+/** Ids a new record or link would take, and the time an edit lands. */
+function editStamp() {
+  return {
+    analysisId: crypto.randomUUID(),
+    linkId: crypto.randomUUID(),
+    now: new Date().toISOString(),
+  };
+}
+
+/**
+ * Writes a token's gloss in the session's analysis language; a blank value clears it.
+ *
+ * @returns The changes it applied, as JSON.
+ * @throws As {@link runSessionEdit} does.
+ */
+function writeGloss(
+  sessionId: string,
+  tokenRef: string,
+  surfaceText: string,
+  value: string,
+): Promise<string> {
+  return runSessionEdit(sessionId, 'writeGloss', (buffer, session) =>
+    tokenCommands.writeGloss(buffer, {
+      ...editStamp(),
+      tokenRef,
+      surfaceText,
+      value,
+      analysisLanguage: session.analysisLanguage,
+    }),
+  );
+}
+
+/**
+ * Approves a stored token analysis for a token, in place of any approval it held.
+ *
+ * @returns The changes it applied, as JSON.
+ * @throws As {@link runSessionEdit} does.
+ */
+function approveAnalysisForToken(
+  sessionId: string,
+  tokenRef: string,
+  surfaceText: string,
+  analysisId: string,
+): Promise<string> {
+  return runSessionEdit(sessionId, 'approveAnalysisForToken', (buffer) =>
+    tokenCommands.approveAnalysisForToken(buffer, {
+      ...editStamp(),
+      tokenRef,
+      surfaceText,
+      analysisId,
+    }),
+  );
+}
+
 /**
  * Returns a summary of every interlinearizer project for the given source project as a JSON string.
  * The WebView deserializes this to populate its project picker and to decide whether to prompt
@@ -1431,6 +1507,70 @@ export async function activate(context: ExecutionActivationContext): Promise<voi
     },
   );
 
+  /** The parameters naming the token a token edit acts on. */
+  const tokenParams = [
+    {
+      name: 'tokenRef',
+      required: true,
+      summary: 'Token.ref of the token edited',
+      schema: { type: 'string' },
+    },
+    {
+      name: 'surfaceText',
+      required: true,
+      summary: "The token's current surface text",
+      schema: { type: 'string' },
+    },
+  ] as const;
+
+  const editResult = {
+    name: 'return value',
+    summary: 'JSON-stringified ChangeSet the edit applied',
+    schema: { type: 'string' },
+  } as const;
+
+  const writeGlossCommandRegistration = await papi.commands.registerCommand(
+    'interlinearizer.writeGloss',
+    writeGloss,
+    {
+      method: {
+        summary: "Write a token's gloss in a session's analysis language; a blank value clears it",
+        params: [
+          sessionIdParam,
+          ...tokenParams,
+          {
+            name: 'value',
+            required: true,
+            summary: 'The gloss',
+            schema: { type: 'string' },
+          },
+        ],
+        result: editResult,
+      },
+    },
+  );
+
+  const approveAnalysisForTokenCommandRegistration = await papi.commands.registerCommand(
+    'interlinearizer.approveAnalysisForToken',
+    approveAnalysisForToken,
+    {
+      method: {
+        summary: 'Approve a stored token analysis for a token, in place of any approval it held',
+        params: [
+          sessionIdParam,
+          ...tokenParams,
+          {
+            name: 'analysisId',
+            required: true,
+            summary: 'Id of the stored token analysis to approve',
+            schema: { type: 'string' },
+          },
+        ],
+        result: editResult,
+      },
+    },
+  );
+
   const checkIndexesCommandRegistration = await papi.commands.registerCommand(
     'interlinearizer.checkIndexes',
     checkIndexes,
@@ -1824,6 +1964,8 @@ export async function activate(context: ExecutionActivationContext): Promise<voi
     undoEditCommandRegistration,
     redoEditCommandRegistration,
     checkIndexesCommandRegistration,
+    writeGlossCommandRegistration,
+    approveAnalysisForTokenCommandRegistration,
     setPerfMarksCommandRegistration,
     readPerfCommandRegistration,
     updateProjectMetadataCommandRegistration,
diff --git a/src/services/analysisSessions.ts b/src/services/analysisSessions.ts
index 29bae4c82..42f7774e3 100644
--- a/src/services/analysisSessions.ts
+++ b/src/services/analysisSessions.ts
@@ -1,7 +1,10 @@
 import type { AnalysisRepository, ChangeSet } from '../types/analysis-repository';
 import { ReadOnlyAnalysisError } from '../types/read-only-analysis-error';
 import type { InterlinearProjectSummary } from '../types/interlinear-project-summary';
+import { isEmptyChangeSet } from '../utils/change-set';
 import { analysisHasFreeTranslations } from '../utils/free-translations';
+import { assertApprovalRule } from './commands/approvalRule';
+import { ChangeBuffer } from './commands/changeBuffer';
 import { EditHistory } from './editHistory';
 
 /** BCP 47 tag for a language that cannot be determined. */
@@ -202,6 +205,35 @@ export class AnalysisSessions {
     return this.run(sessionId, edit);
   }
 
+  /**
+   * Runs `command` as one edit of the session's analysis, in the session's turn. What it stages
+   * applies as one undo step, marking the draft dirty; a command staging nothing applies nothing.
+   *
+   * @returns The changes applied, naming `intent`.
+   * @throws {ReadOnlyAnalysisError} If the session is read-only.
+   * @throws {ApprovalRuleError} If the changes would give a token or segment a second approved
+   *   link; nothing is applied.
+   * @throws {Error} If the session is not open.
+   * @throws Whatever the command or applying its changes throws; nothing is applied.
+   */
+  edit(
+    sessionId: string,
+    intent: string,
+    command: (buffer: ChangeBuffer, session: Session) => Promise<void>,
+  ): Promise<ChangeSet> {
+    return this.runEdit(sessionId, async (session) => {
+      const buffer = new ChangeBuffer(session.repository);
+      await command(buffer, session);
+      const changes = buffer.toChangeSet(intent);
+      if (isEmptyChangeSet(changes)) return changes;
+      await assertApprovalRule(buffer, session.repository);
+      const scope = await session.repository.getScope();
+      if (!scope.dirty) changes.scope = { ...scope, dirty: true };
+      await session.history.apply(changes);
+      return changes;
+    });
+  }
+
   /**
    * Reverts the session's latest edit not yet undone.
    *
diff --git a/src/services/commands/approvalRule.ts b/src/services/commands/approvalRule.ts
new file mode 100644
index 000000000..e0477069d
--- /dev/null
+++ b/src/services/commands/approvalRule.ts
@@ -0,0 +1,69 @@
+import type { AnalysisRepository } from '../../types/analysis-repository';
+import type { ChangeBuffer } from './changeBuffer';
+
+/** Thrown by an edit that would give a token or segment a second approved link. */
+export class ApprovalRuleError extends Error {
+  /** The token refs and segment ids the edit would leave holding several approved links. */
+  readonly places: readonly string[];
+
+  constructor(places: readonly string[]) {
+    super(`Interlinearizer: an edit would approve several analyses at ${places.join(', ')}`);
+    this.name = 'ApprovalRuleError';
+    this.places = places;
+  }
+}
+
+/** How many approved links each place holds, placing each link by `placeOf`. */
+function approvedCounts<Link extends { status: string }>(
+  links: readonly Link[],
+  placeOf: (link: Link) => string,
+): Map<string, number> {
+  const counts = new Map<string, number>();
+  links.forEach((link) => {
+    if (link.status !== 'approved') return;
+    counts.set(placeOf(link), (counts.get(placeOf(link)) ?? 0) + 1);
+  });
+  return counts;
+}
+
+/** The places where `after` holds more than one approved link, and more than `before` held. */
+function breaches<Link extends { status: string }>(
+  before: readonly Link[],
+  after: readonly Link[],
+  placeOf: (link: Link) => string,
+): string[] {
+  const held = approvedCounts(before, placeOf);
+  return [...approvedCounts(after, placeOf)].flatMap(([place, count]) =>
+    count > 1 && count > (held.get(place) ?? 0) ? [place] : [],
+  );
+}
+
+/**
+ * Refuses the changes staged in `buffer` over `repository` when they would leave a token or segment
+ * holding more approved links than one, and more than it held before them. A place the stored
+ * analysis already breaches is left to the edits that repair it.
+ *
+ * @throws {ApprovalRuleError} If the changes breach the rule anywhere.
+ */
+export async function assertApprovalRule(
+  buffer: ChangeBuffer,
+  repository: AnalysisRepository,
+): Promise<void> {
+  const tokenRefs = [
+    ...new Set(buffer.touched('tokenAnalysisLinks').map(({ token }) => token.tokenRef)),
+  ];
+  const segmentIds = [...new Set(buffer.touched('segmentAnalysisLinks').map((l) => l.segmentId))];
+  const found = [
+    ...breaches(
+      (await repository.findLinksByToken(tokenRefs)).tokenAnalysisLinks,
+      (await buffer.findLinksByToken(tokenRefs)).tokenAnalysisLinks,
+      ({ token }) => token.tokenRef,
+    ),
+    ...breaches(
+      await repository.findLinksBySegment(segmentIds),
+      await buffer.findLinksBySegment(segmentIds),
+      ({ segmentId }) => segmentId,
+    ),
+  ];
+  if (found.length > 0) throw new ApprovalRuleError(found);
+}
diff --git a/src/services/commands/changeBuffer.ts b/src/services/commands/changeBuffer.ts
new file mode 100644
index 000000000..5a5392fa5
--- /dev/null
+++ b/src/services/commands/changeBuffer.ts
@@ -0,0 +1,214 @@
+import type {
+  PhraseAnalysis,
+  SegmentAnalysis,
+  SegmentAnalysisLink,
+  TextAnalysis,
+  TokenAnalysis,
+} from 'interlinearizer';
+import type { AnalysisLinks, AnalysisRepository, ChangeSet } from '../../types/analysis-repository';
+import { normalizeSurfaceForm } from '../../utils/analysis-identity';
+import { jsonCopy } from '../../utils/json-copy';
+
+/** A record kind, named as {@link TextAnalysis} names its list. */
+export type RecordKind = keyof TextAnalysis;
+
+/** A record of one kind. */
+export type RecordOf<Kind extends RecordKind> = TextAnalysis[Kind][number];
+
+/** One kind's staged changes. */
+type Staged<T> = {
+  /** Records to store, by id. */
+  puts: Map<string, T>;
+  /** Records to remove, as they stood before the removal, by id. */
+  deletes: Map<string, T>;
+  /** Ids of the staged puts that no stored record shares, so removing one stages nothing. */
+  created: Set<string>;
+};
+
+function emptyStaged<T>(): Staged<T> {
+  return { puts: new Map(), deletes: new Map(), created: new Set() };
+}
+
+/**
+ * Changes a command stages before they apply, over a repository it reads through. Every read
+ * answers as the repository would once the staged changes applied, and hands out copies the command
+ * may change before staging them.
+ */
+export class ChangeBuffer {
+  private readonly repository: AnalysisRepository;
+
+  private readonly staged: { [Kind in RecordKind]: Staged<RecordOf<Kind>> } = {
+    segmentAnalyses: emptyStaged(),
+    segmentAnalysisLinks: emptyStaged(),
+    tokenAnalyses: emptyStaged(),
+    tokenAnalysisLinks: emptyStaged(),
+    phraseAnalyses: emptyStaged(),
+    phraseAnalysisLinks: emptyStaged(),
+  };
+
+  constructor(repository: AnalysisRepository) {
+    this.repository = repository;
+  }
+
+  /** The token analyses stored under `ids` once the staged changes apply. */
+  async getTokenAnalyses(ids: string[]): Promise<TokenAnalysis[]> {
+    const wanted = new Set(ids);
+    const stored = await this.repository.getTokenAnalyses(ids);
+    return this.overlay('tokenAnalyses', stored, ({ id }) => wanted.has(id));
+  }
+
+  /** The phrase analyses stored under `ids` once the staged changes apply. */
+  async getPhraseAnalyses(ids: string[]): Promise<PhraseAnalysis[]> {
+    const wanted = new Set(ids);
+    const stored = await this.repository.getPhraseAnalyses(ids);
+    return this.overlay('phraseAnalyses', stored, ({ id }) => wanted.has(id));
+  }
+
+  /** The segment analyses stored under `ids` once the staged changes apply. */
+  async getSegmentAnalyses(ids: string[]): Promise<SegmentAnalysis[]> {
+    const wanted = new Set(ids);
+    const stored = await this.repository.getSegmentAnalyses(ids);
+    return this.overlay('segmentAnalyses', stored, ({ id }) => wanted.has(id));
+  }
+
+  /**
+   * The token links on the tokens `tokenRefs` names, and the phrase links touching any of them,
+   * once the staged changes apply.
+   */
+  async findLinksByToken(
+    tokenRefs: string[],
+  ): Promise<Pick<AnalysisLinks, 'tokenAnalysisLinks' | 'phraseAnalysisLinks'>> {
+    const wanted = new Set(tokenRefs);
+    const stored = await this.repository.findLinksByToken(tokenRefs);
+    return {
+      tokenAnalysisLinks: this.overlay('tokenAnalysisLinks', stored.tokenAnalysisLinks, (link) =>
+        wanted.has(link.token.tokenRef),
+      ),
+      phraseAnalysisLinks: this.overlay('phraseAnalysisLinks', stored.phraseAnalysisLinks, (link) =>
+        link.tokens.some(({ tokenRef }) => wanted.has(tokenRef)),
+      ),
+    };
+  }
+
+  /** The segment links on the segments `segmentIds` names once the staged changes apply. */
+  async findLinksBySegment(segmentIds: string[]): Promise<SegmentAnalysisLink[]> {
+    const wanted = new Set(segmentIds);
+    const stored = await this.repository.findLinksBySegment(segmentIds);
+    return this.overlay('segmentAnalysisLinks', stored, (link) => wanted.has(link.segmentId));
+  }
+
+  /** The links of every kind to the analyses `analysisIds` names once the staged changes apply. */
+  async findLinksToAnalyses(analysisIds: string[]): Promise<AnalysisLinks> {
+    const wanted = new Set(analysisIds);
+    const stored = await this.repository.findLinksToAnalyses(analysisIds);
+    const linksTo = ({ analysisId }: { analysisId: string }) => wanted.has(analysisId);
+    return {
+      tokenAnalysisLinks: this.overlay('tokenAnalysisLinks', stored.tokenAnalysisLinks, linksTo),
+      phraseAnalysisLinks: this.overlay('phraseAnalysisLinks', stored.phraseAnalysisLinks, linksTo),
+      segmentAnalysisLinks: this.overlay(
+        'segmentAnalysisLinks',
+        stored.segmentAnalysisLinks,
+        linksTo,
+      ),
+    };
+  }
+
+  /**
+   * The token analyses whose surface text normalizes to one of `normalizedForms` once the staged
+   * changes apply.
+   */
+  async findTokenAnalysesByForm(normalizedForms: string[]): Promise<TokenAnalysis[]> {
+    const wanted = new Set(normalizedForms);
+    const stored = await this.repository.findTokenAnalysesByForm(normalizedForms);
+    return this.overlay('tokenAnalyses', stored, ({ surfaceText }) =>
+      wanted.has(normalizeSurfaceForm(surfaceText)),
+    );
+  }
+
+  /**
+   * The phrase analyses whose surface text normalizes to one of `normalizedForms` once the staged
+   * changes apply.
+   */
+  async findPhraseAnalysesByForm(normalizedForms: string[]): Promise<PhraseAnalysis[]> {
+    const wanted = new Set(normalizedForms);
+    const stored = await this.repository.findPhraseAnalysesByForm(normalizedForms);
+    return this.overlay('phraseAnalyses', stored, ({ surfaceText }) =>
+      wanted.has(normalizeSurfaceForm(surfaceText)),
+    );
+  }
+
+  /** Stages a new record of `kind`, under an id no stored record has. */
+  create<Kind extends RecordKind>(kind: Kind, record: RecordOf<Kind>): void {
+    this.stagedOf(kind).created.add(record.id);
+    this.put(kind, record);
+  }
+
+  /** Stages `record` to be stored whole under its id. */
+  put<Kind extends RecordKind>(kind: Kind, record: RecordOf<Kind>): void {
+    const staged = this.stagedOf(kind);
+    staged.deletes.delete(record.id);
+    staged.puts.set(record.id, jsonCopy(record));
+  }
+
+  /** Stages `record`'s removal; removing one the buffer created stages nothing for it. */
+  delete<Kind extends RecordKind>(kind: Kind, record: RecordOf<Kind>): void {
+    const staged = this.stagedOf(kind);
+    staged.puts.delete(record.id);
+    if (staged.created.delete(record.id)) return;
+    staged.deletes.set(record.id, jsonCopy(record));
+  }
+
+  /** Every record of `kind` the staged changes put or remove, as each stood before or will stand. */
+  touched<Kind extends RecordKind>(kind: Kind): RecordOf<Kind>[] {
+    const staged = this.stagedOf(kind);
+    return [...staged.puts.values(), ...staged.deletes.values()].map((record) => jsonCopy(record));
+  }
+
+  /** The staged changes as one change set; a kind with nothing staged is left out. */
+  toChangeSet(intent: string): ChangeSet {
+    const changes: ChangeSet = { intent };
+    const kinds: RecordKind[] = [
+      'segmentAnalyses',
+      'segmentAnalysisLinks',
+      'tokenAnalyses',
+      'tokenAnalysisLinks',
+      'phraseAnalyses',
+      'phraseAnalysisLinks',
+    ];
+    kinds.forEach((kind) => this.collect(changes, kind));
+    return changes;
+  }
+
+  /**
+   * `stored` as it stands once the staged changes of `kind` apply, keeping only the records
+   * `matches` accepts; `stored` must hold every stored record `matches` accepts.
+   */
+  private overlay<Kind extends RecordKind>(
+    kind: Kind,
+    stored: readonly RecordOf<Kind>[],
+    matches: (record: RecordOf<Kind>) => boolean,
+  ): RecordOf<Kind>[] {
+    const staged = this.stagedOf(kind);
+    const latest = new Map<string, RecordOf<Kind>>();
+    stored.forEach((record) => {
+      if (!staged.deletes.has(record.id)) latest.set(record.id, record);
+    });
+    staged.puts.forEach((record, id) => latest.set(id, record));
+    return [...latest.values()].filter(matches).map((record) => jsonCopy(record));
+  }
+
+  private collect<Kind extends RecordKind>(changes: ChangeSet, kind: Kind): void {
+    const { puts, deletes } = this.stagedOf(kind);
+    if (puts.size === 0 && deletes.size === 0) return;
+    Object.assign(changes, {
+      [kind]: {
+        puts: [...puts.values()].map((record) => jsonCopy(record)),
+        deletes: [...deletes.keys()],
+      },
+    });
+  }
+
+  private stagedOf<Kind extends RecordKind>(kind: Kind): Staged<RecordOf<Kind>> {
+    return this.staged[kind];
+  }
+}
diff --git a/src/services/commands/tokenCommands.ts b/src/services/commands/tokenCommands.ts
new file mode 100644
index 000000000..a1921ad4e
--- /dev/null
+++ b/src/services/commands/tokenCommands.ts
@@ -0,0 +1,291 @@
+import type { TokenAnalysis, TokenAnalysisLink } from 'interlinearizer';
+import { analysesAreIdentical, normalizeSurfaceForm } from '../../utils/analysis-identity';
+import { preferredLink, preferredPayload } from '../../utils/pick-rules';
+import { clearAnalysisGloss, isEmptyTokenAnalysis } from '../../utils/token-analysis-content';
+import type { ChangeBuffer } from './changeBuffer';
+
+/** Where and when a token edit lands. */
+type TokenEdit = {
+  /** `Token.ref` of the token edited. */
+  tokenRef: string;
+  /** The token's current surface text, refreshed on the records the edit touches. */
+  surfaceText: string;
+  /** ISO 8601 time of the edit, stamped on the records it touches. */
+  now: string;
+  /** Id a new link takes, spent only when the edit makes one. */
+  linkId: string;
+};
+
+/** What writing a token's gloss needs. */
+export type WriteGlossRequest = TokenEdit & {
+  /** The gloss; blank clears the token's gloss in `analysisLanguage`. */
+  value: string;
+  /** BCP 47 tag of the language the gloss is written in. */
+  analysisLanguage: string;
+  /** Id a new token analysis takes, spent only when the write makes one. */
+  analysisId: string;
+};
+
+/** What approving a stored analysis for a token needs. */
+export type ApproveAnalysisRequest = TokenEdit & {
+  /** The stored token analysis to approve. */
+  analysisId: string;
+};
+
+/**
+ * The token's approved link an approval tie picks, with its payload. Approved links naming no
+ * stored payload are removed first, so they never persist or crowd the pick.
+ */
+async function resolveApprovedAnalysis(
+  buffer: ChangeBuffer,
+  tokenRef: string,
+): Promise<{ link: TokenAnalysisLink; analysis: TokenAnalysis } | undefined> {
+  const { tokenAnalysisLinks } = await buffer.findLinksByToken([tokenRef]);
+  const approved = tokenAnalysisLinks.filter(({ status }) => status === 'approved');
+  const payloads = new Map(
+    (await buffer.getTokenAnalyses(approved.map(({ analysisId }) => analysisId))).map(
+      (analysis) => [analysis.id, analysis],
+    ),
+  );
+  approved
+    .filter(({ analysisId }) => !payloads.has(analysisId))
+    .forEach((orphan) => buffer.delete('tokenAnalysisLinks', orphan));
+  const link = preferredLink(approved.filter(({ analysisId }) => payloads.has(analysisId)));
+  const analysis = link && payloads.get(link.analysisId);
+  return link && analysis ? { link, analysis } : undefined;
+}
+
+/** Whether a token other than `link`'s links the payload `analysisId`, at any status. */
+async function isSharedByOtherTokens(
+  buffer: ChangeBuffer,
+  link: TokenAnalysisLink,
+  analysisId: string,
+): Promise<boolean> {
+  const { tokenAnalysisLinks } = await buffer.findLinksToAnalyses([analysisId]);
+  return tokenAnalysisLinks.some(({ token }) => token.tokenRef !== link.token.tokenRef);
+}
+
+/**
+ * Moves `link` onto a private copy of its shared payload, so an edit aimed at its token leaves the
+ * others reading what they did. The copy is dated by the edit, being a record of its own.
+ *
+ * @returns The copy, staged; `link` is repointed but left for the caller to stage.
+ */
+function forkSharedAnalysis(
+  buffer: ChangeBuffer,
+  link: TokenAnalysisLink,
+  analysis: TokenAnalysis,
+  forkId: string,
+  now: string,
+): TokenAnalysis {
+  const fork: TokenAnalysis = { ...analysis, id: forkId, createdAt: now, updatedAt: now };
+  buffer.create('tokenAnalyses', fork);
+  link.analysisId = forkId;
+  return fork;
+}
+
+/**
+ * Approves the non-approved link `tokenRef` holds to `analysisId`, so a token taking on a record it
+ * was offered keeps one link to it. The link keeps its creation date and `confidence`.
+ *
+ * @returns The approved link, staged, or `undefined` when the token holds no such link.
+ */
+async function approveHeldLink(
+  buffer: ChangeBuffer,
+  tokenRef: string,
+  analysisId: string,
+  surfaceText: string,
+  now: string,
+): Promise<TokenAnalysisLink | undefined> {
+  const { tokenAnalysisLinks } = await buffer.findLinksByToken([tokenRef]);
+  const held = preferredLink(
+    tokenAnalysisLinks.filter((l) => l.status !== 'approved' && l.analysisId === analysisId),
+  );
+  if (!held) return undefined;
+  held.status = 'approved';
+  held.token.surfaceText = surfaceText;
+  held.updatedAt = now;
+  buffer.put('tokenAnalysisLinks', held);
+  return held;
+}
+
+/** Removes the payload once no link of any status names it. */
+async function reclaimIfUnlinked(buffer: ChangeBuffer, analysis: TokenAnalysis): Promise<void> {
+  const { tokenAnalysisLinks } = await buffer.findLinksToAnalyses([analysis.id]);
+  if (tokenAnalysisLinks.length === 0) buffer.delete('tokenAnalyses', analysis);
+}
+
+/**
+ * Leaves each token holding one link to `analysisId` where it held several. The token keeps its
+ * approved link over any other, then the one an approval tie picks, and the survivor keeps the
+ * token's first annotation date.
+ */
+async function coalesceLinksPerToken(buffer: ChangeBuffer, analysisId: string): Promise<void> {
+  const { tokenAnalysisLinks } = await buffer.findLinksToAnalyses([analysisId]);
+  const byToken = new Map<string, TokenAnalysisLink[]>();
+  tokenAnalysisLinks.forEach((link) => {
+    byToken.set(link.token.tokenRef, [...(byToken.get(link.token.tokenRef) ?? []), link]);
+  });
+  byToken.forEach((links) => {
+    const kept =
+      preferredLink(links.filter(({ status }) => status === 'approved')) ?? preferredLink(links);
+    /* v8 ignore next -- every token's group holds a link */
+    if (!kept) return;
+    const createdAt = links.reduce(
+      (earliest, link) => (link.createdAt < earliest ? link.createdAt : earliest),
+      kept.createdAt,
+    );
+    links.forEach((link) => {
+      if (link !== kept) buffer.delete('tokenAnalysisLinks', link);
+    });
+    if (kept.createdAt !== createdAt) buffer.put('tokenAnalysisLinks', { ...kept, createdAt });
+  });
+}
+
+/**
+ * Folds the just-edited payload into a content-identical one where the edit made one, so an edit
+ * never leaves the duplicate a first write's find-or-create avoids. Every link to the edited
+ * payload moves to the survivor, which keeps its own timestamps, and a token linking both keeps one
+ * link. The survivor's breakdown stays stale only when both payloads' were.
+ */
+async function mergeIntoIdenticalPayload(
+  buffer: ChangeBuffer,
+  analysis: TokenAnalysis,
+  now: string,
+): Promise<void> {
+  const candidates = await buffer.findTokenAnalysesByForm([
+    normalizeSurfaceForm(analysis.surfaceText),
+  ]);
+  const other = preferredPayload(
+    candidates.filter((ta) => ta.id !== analysis.id && analysesAreIdentical(ta, analysis)),
+  );
+  if (!other) return;
+  if (other.morphemesStale && !analysis.morphemesStale) {
+    delete other.morphemesStale;
+    other.updatedAt = now;
+    buffer.put('tokenAnalyses', other);
+  }
+  const { tokenAnalysisLinks } = await buffer.findLinksToAnalyses([analysis.id]);
+  tokenAnalysisLinks.forEach((link) =>
+    buffer.put('tokenAnalysisLinks', { ...link, analysisId: other.id }),
+  );
+  await coalesceLinksPerToken(buffer, other.id);
+  buffer.delete('tokenAnalyses', analysis);
+}
+
+/**
+ * Links a token to an approved payload holding `analysis`'s content, sharing a content-identical
+ * stored one where there is one and staging `analysis` otherwise. A non-approved link the token
+ * holds to the shared payload is approved rather than joined by a second.
+ */
+async function appendApprovedAnalysis(
+  buffer: ChangeBuffer,
+  analysis: TokenAnalysis,
+  { tokenRef, now, linkId }: TokenEdit,
+): Promise<void> {
+  const candidates = await buffer.findTokenAnalysesByForm([
+    normalizeSurfaceForm(analysis.surfaceText),
+  ]);
+  const existing = preferredPayload(candidates.filter((ta) => analysesAreIdentical(ta, analysis)));
+  if (!existing) buffer.create('tokenAnalyses', analysis);
+  else if (await approveHeldLink(buffer, tokenRef, existing.id, analysis.surfaceText, now)) return;
+  buffer.create('tokenAnalysisLinks', {
+    id: linkId,
+    analysisId: existing?.id ?? analysis.id,
+    createdAt: now,
+    updatedAt: now,
+    status: 'approved',
+    token: { tokenRef, surfaceText: analysis.surfaceText },
+  });
+}
+
+/**
+ * Stages writing a token's gloss. The edit is per token: a payload other tokens share is forked
+ * first. An edit that makes the payload identical to another folds it in. A token with no approved
+ * analysis takes a content-identical stored one, or a new one. A blank value clears the gloss, and
+ * a payload left empty goes once nothing links it; a blank write to a token with no approved
+ * analysis stages nothing.
+ */
+export async function writeGloss(buffer: ChangeBuffer, request: WriteGlossRequest): Promise<void> {
+  const { tokenRef, surfaceText, value, analysisLanguage: lang, analysisId, now } = request;
+  const isBlank = value.trim() === '';
+
+  const resolved = await resolveApprovedAnalysis(buffer, tokenRef);
+  if (resolved) {
+    const { link, analysis } = resolved;
+    const target = (await isSharedByOtherTokens(buffer, link, analysis.id))
+      ? forkSharedAnalysis(buffer, link, analysis, analysisId, now)
+      : analysis;
+    target.surfaceText = surfaceText;
+    target.updatedAt = now;
+    link.token.surfaceText = surfaceText;
+    link.updatedAt = now;
+    if (isBlank) {
+      clearAnalysisGloss(target, lang);
+      if (isEmptyTokenAnalysis(target)) {
+        buffer.delete('tokenAnalysisLinks', link);
+        const { tokenAnalysisLinks } = await buffer.findLinksToAnalyses([target.id]);
+        if (tokenAnalysisLinks.length === 0) buffer.delete('tokenAnalyses', target);
+        else buffer.put('tokenAnalyses', target);
+        return;
+      }
+    } else {
+      target.gloss = { ...target.gloss, [lang]: value };
+      delete target.glossSenseRef;
+    }
+    buffer.put('tokenAnalyses', target);
+    buffer.put('tokenAnalysisLinks', link);
+    await mergeIntoIdenticalPayload(buffer, target, now);
+    return;
+  }
+
+  if (isBlank) return;
+  await appendApprovedAnalysis(
+    buffer,
+    { id: analysisId, createdAt: now, updatedAt: now, surfaceText, gloss: { [lang]: value } },
+    request,
+  );
+}
+
+/**
+ * Stages approving the stored payload `analysisId` for a token, in place of any approval it held.
+ * The payload that approval named goes once nothing links it. A token holding a non-approved link
+ * to the payload has that link approved, keeping the earlier creation date of the two; one holding
+ * neither gets a new link. It stages nothing for a payload not stored, or one already approved for
+ * the token.
+ */
+export async function approveAnalysisForToken(
+  buffer: ChangeBuffer,
+  { tokenRef, surfaceText, analysisId, now, linkId }: ApproveAnalysisRequest,
+): Promise<void> {
+  if ((await buffer.getTokenAnalyses([analysisId])).length === 0) return;
+  const resolved = await resolveApprovedAnalysis(buffer, tokenRef);
+  if (resolved?.link.analysisId === analysisId) return;
+
+  const pending = await approveHeldLink(buffer, tokenRef, analysisId, surfaceText, now);
+  if (pending) {
+    if (resolved) {
+      if (resolved.link.createdAt < pending.createdAt) {
+        buffer.put('tokenAnalysisLinks', { ...pending, createdAt: resolved.link.createdAt });
+      }
+      buffer.delete('tokenAnalysisLinks', resolved.link);
+    }
+  } else if (resolved) {
+    const { link } = resolved;
+    link.analysisId = analysisId;
+    link.token.surfaceText = surfaceText;
+    link.updatedAt = now;
+    buffer.put('tokenAnalysisLinks', link);
+  } else {
+    buffer.create('tokenAnalysisLinks', {
+      id: linkId,
+      analysisId,
+      createdAt: now,
+      updatedAt: now,
+      status: 'approved',
+      token: { tokenRef, surfaceText },
+    });
+  }
+
+  if (resolved) await reclaimIfUnlinked(buffer, resolved.analysis);
+}
diff --git a/src/services/draftRepository.ts b/src/services/draftRepository.ts
index 8b4fb3c9a..2075e102f 100644
--- a/src/services/draftRepository.ts
+++ b/src/services/draftRepository.ts
@@ -23,7 +23,7 @@ import { applyChangeSet } from '../utils/change-set';
 import { jsonCopy } from '../utils/json-copy';
 import { perfTime, perfTimeAsync, perfTimeAsyncExcluding } from '../utils/perf-marks';
 import { AnalysisIndex } from './analysisIndex';
-import { IndexedRepository, type IndexedAnalysis } from './indexedRepository';
+import { IndexedRepository, type IndexedDraft } from './indexedRepository';
 import { draftAnalysisKey, draftJournalKey, draftKey } from './storageKeys';
 
 /**
@@ -136,7 +136,7 @@ export class DraftRepository extends IndexedRepository implements AnalysisReposi
    * index over its records. Dropped by every load and by every write but an apply, since each may
    * come from a caller holding another draft.
    */
-  private current: { draft: DraftProject; index: AnalysisIndex } | undefined;
+  private current: IndexedDraft | undefined;
 
   constructor(storage: KeyValueStorage, sourceProjectId: string, logger: WarningLogger) {
     super();
@@ -270,7 +270,7 @@ export class DraftRepository extends IndexedRepository implements AnalysisReposi
    *   is left as it was.
    */
   async apply(changes: ChangeSet): Promise<ApplyResult> {
-    const { draft: base, index } = await this.keptDraft();
+    const { draft: base, index } = await this.indexed();
     const copied = jsonCopy(changes);
     const { draft, inverse } = applyChangeSet(base, copied);
     await this.writeDraft(draft, undefined, { refuseUnreadable: true });
@@ -279,20 +279,8 @@ export class DraftRepository extends IndexedRepository implements AnalysisReposi
     return { inverse };
   }
 
-  protected async indexed(): Promise<AnalysisIndex> {
-    return (await this.keptDraft()).index;
-  }
-
-  protected keptIndex(): IndexedAnalysis | undefined {
-    return this.current && { analysis: this.current.draft.analysis, index: this.current.index };
-  }
-
-  /**
-   * The draft this instance keeps, loaded from storage first when it keeps none.
-   *
-   * @throws Whatever {@link exportAll} throws.
-   */
-  private async keptDraft(): Promise<{ draft: DraftProject; index: AnalysisIndex }> {
+  /** @throws Whatever {@link exportAll} throws. */
+  protected async indexed(): Promise<IndexedDraft> {
     if (!this.current) {
       const { draft } = await this.exportAll();
       this.current = { draft, index: new AnalysisIndex(draft.analysis) };
@@ -300,6 +288,10 @@ export class DraftRepository extends IndexedRepository implements AnalysisReposi
     return this.current;
   }
 
+  protected keptIndex(): IndexedDraft | undefined {
+    return this.current;
+  }
+
   /**
    * Saves `draft` as {@link replaceAll} describes.
    *
diff --git a/src/services/indexedRepository.ts b/src/services/indexedRepository.ts
index d8b774446..92569a54a 100644
--- a/src/services/indexedRepository.ts
+++ b/src/services/indexedRepository.ts
@@ -1,28 +1,31 @@
 import type {
   AssignmentStatus,
+  DraftProject,
   PhraseAnalysis,
   SegmentAnalysis,
   SegmentAnalysisLink,
-  TextAnalysis,
   TokenAnalysis,
 } from 'interlinearizer';
 import type {
   AnalysisLinks,
   AnalysisRepository,
   IndexDifference,
+  ScopeRecord,
 } from '../types/analysis-repository';
+import { scopeRecordOf } from '../utils/change-set';
 import { jsonCopy } from '../utils/json-copy';
 import type { AnalysisIndex } from './analysisIndex';
 
-/** An index, with the analysis whose records it is kept over. */
-export type IndexedAnalysis = {
-  analysis: TextAnalysis;
+/** An index, with the draft whose records it is kept over. */
+export type IndexedDraft = {
+  draft: DraftProject;
   index: AnalysisIndex;
 };
 
-/** The lookups of a repository that answers them from an {@link AnalysisIndex} over its records. */
+/** The reads of a repository that answers them from an {@link AnalysisIndex} over its records. */
 export abstract class IndexedRepository implements Pick<
   AnalysisRepository,
+  | 'getScope'
   | 'getTokenAnalyses'
   | 'getPhraseAnalyses'
   | 'getSegmentAnalyses'
@@ -34,6 +37,10 @@ export abstract class IndexedRepository implements Pick<
   | 'findPhraseAnalysesByForm'
   | 'checkIndexes'
 > {
+  async getScope(): Promise<ScopeRecord> {
+    return jsonCopy(scopeRecordOf((await this.indexed()).draft));
+  }
+
   getTokenAnalyses(ids: string[]): Promise<TokenAnalysis[]> {
     return this.query((index) => index.getTokenAnalyses(ids));
   }
@@ -75,21 +82,21 @@ export abstract class IndexedRepository implements Pick<
   /** Reports nothing while no index is kept. */
   async checkIndexes(): Promise<IndexDifference[]> {
     const kept = this.keptIndex();
-    return kept ? kept.index.differencesFrom(kept.analysis) : [];
+    return kept ? kept.index.differencesFrom(kept.draft.analysis) : [];
   }
 
   /** Answers `read` from the kept index, with copies of the records it finds. */
   private async query<T>(read: (index: AnalysisIndex) => T): Promise<T> {
-    return jsonCopy(read(await this.indexed()));
+    return jsonCopy(read((await this.indexed()).index));
   }
 
   /**
-   * The kept index, built over the stored records first when none is kept.
+   * The kept index and its draft, loaded from storage first when none is kept.
    *
    * @throws Whatever loading the stored records throws.
    */
-  protected abstract indexed(): Promise<AnalysisIndex>;
+  protected abstract indexed(): Promise<IndexedDraft>;
 
-  /** The kept index and the analysis it is kept over, or `undefined` when none is kept. */
-  protected abstract keptIndex(): IndexedAnalysis | undefined;
+  /** The kept index and the draft it is kept over, or `undefined` when none is kept. */
+  protected abstract keptIndex(): IndexedDraft | undefined;
 }
diff --git a/src/services/projectStorage.ts b/src/services/projectStorage.ts
index 185bf6ed0..519c97a6e 100644
--- a/src/services/projectStorage.ts
+++ b/src/services/projectStorage.ts
@@ -1133,6 +1133,7 @@ export function openDraftRepository(
     replaceAll: (draft, options) => counted((repository) => repository.replaceAll(draft, options)),
     markClean: () => queued((repository) => repository.markClean()),
     apply: (changes) => counted((repository) => repository.apply(changes)),
+    getScope: () => queued((repository) => repository.getScope()),
     getTokenAnalyses: (ids) => queued((repository) => repository.getTokenAnalyses(ids)),
     getPhraseAnalyses: (ids) => queued((repository) => repository.getPhraseAnalyses(ids)),
     getSegmentAnalyses: (ids) => queued((repository) => repository.getSegmentAnalyses(ids)),
diff --git a/src/services/pt9ImportRepository.ts b/src/services/pt9ImportRepository.ts
index 4ef0c3494..fa4fc8be9 100644
--- a/src/services/pt9ImportRepository.ts
+++ b/src/services/pt9ImportRepository.ts
@@ -8,7 +8,7 @@ import type {
 import { CURRENT_MODEL_VERSION } from '../types/model-version';
 import { ReadOnlyAnalysisError } from '../types/read-only-analysis-error';
 import { AnalysisIndex } from './analysisIndex';
-import { IndexedRepository, type IndexedAnalysis } from './indexedRepository';
+import { IndexedRepository, type IndexedDraft } from './indexedRepository';
 
 /**
  * A Paratext 9 import's analysis, read in a draft's shape. Only a sync replaces an import's
@@ -22,7 +22,7 @@ export class Pt9ImportRepository extends IndexedRepository implements AnalysisRe
   private readonly readProject: () => Promise<InterlinearProject | undefined>;
 
   /** The import as a lookup last read it, with the index over its records; dropped by every load. */
-  private loaded: IndexedAnalysis | undefined;
+  private loaded: IndexedDraft | undefined;
 
   /**
    * @param interlinearProjectId - Id of the project to read, which must be a Paratext 9 import.
@@ -75,15 +75,16 @@ export class Pt9ImportRepository extends IndexedRepository implements AnalysisRe
     throw this.readOnlyError();
   }
 
-  protected async indexed(): Promise<AnalysisIndex> {
+  /** @throws Whatever {@link exportAll} throws. */
+  protected async indexed(): Promise<IndexedDraft> {
     if (!this.loaded) {
-      const { analysis } = await this.readImport();
-      this.loaded = { analysis, index: new AnalysisIndex(analysis) };
+      const draft = await this.readImport();
+      this.loaded = { draft, index: new AnalysisIndex(draft.analysis) };
     }
-    return this.loaded.index;
+    return this.loaded;
   }
 
-  protected keptIndex(): IndexedAnalysis | undefined {
+  protected keptIndex(): IndexedDraft | undefined {
     return this.loaded;
   }
 
diff --git a/src/store/analysisSlice.ts b/src/store/analysisSlice.ts
index f2635e7b4..49e5b8e38 100644
--- a/src/store/analysisSlice.ts
+++ b/src/store/analysisSlice.ts
@@ -22,6 +22,7 @@ import {
 import { buildCatalogRows, type HeadingPlacement } from '../utils/analysis-query';
 import type { StaleFreeTranslation } from '../utils/stale-free-translations';
 import { isEmptyMultiString } from '../utils/multi-string';
+import { clearAnalysisGloss, isEmptyTokenAnalysis } from '../utils/token-analysis-content';
 import {
   preferredLink,
   preferredLinkByKey,
@@ -868,46 +869,6 @@ function writeGlossOntoAnalysis(
   mergeIntoIdenticalPayload(state, analysis, now);
 }
 
-/**
- * Determines whether a `TokenAnalysis` carries no analysis content, so a reducer that just emptied
- * one field can decide to drop the whole record instead of letting empty records accumulate in
- * storage. Checks every content field of the type — `gloss`, `morphemes`, `pos`, `features`, and
- * `glossSenseRef` — not only the field the caller emptied, so records carrying imported
- * morphosyntactic or lexicon data are never discarded by an unrelated edit. A gloss counts as empty
- * when it has no entries or every entry is blank, so a record left holding only whitespace glosses
- * (junk from clearing a gloss field) is treated the same as one with no gloss at all.
- *
- * Provenance fields (`confidence`, `producer`, `sourceUser`) are intentionally NOT treated as
- * content: they describe who/what produced an analysis, not an analysis worth keeping on their own.
- * A record holding only provenance and no glosses/morphemes/pos/features is therefore considered
- * empty and may be dropped when its last content field is cleared. This is a deliberate choice — if
- * a future workflow needs provenance-only records (e.g. imported parser metadata) to survive a
- * gloss clear, add the relevant fields to the check below.
- */
-function isEmptyTokenAnalysis(analysis: TokenAnalysis): boolean {
-  return (
-    isEmptyMultiString(analysis.gloss) &&
-    /* v8 ignore next -- the length===0 sub-branch needs an empty-but-defined morphemes array, which no caller produces */
-    (!analysis.morphemes || analysis.morphemes.length === 0) &&
-    analysis.pos === undefined &&
-    analysis.features === undefined &&
-    analysis.glossSenseRef === undefined
-  );
-}
-
-/**
- * Empties one language's gloss, dropping the gloss and the analysis-wide `glossSenseRef` once no
- * language is left holding usable text — a sibling left holding only whitespace counts for neither,
- * so the sense is never stranded on a gloss nothing renders.
- */
-function clearAnalysisGloss(analysis: TokenAnalysis, lang: string): void {
-  if (analysis.gloss) {
-    delete analysis.gloss[lang];
-    if (isEmptyMultiString(analysis.gloss)) delete analysis.gloss;
-  }
-  if (!analysis.gloss) delete analysis.glossSenseRef;
-}
-
 /**
  * The annotated forms a re-split to `forms` would strand: those whose morpheme carries a gloss or a
  * lexicon reference and which the new breakdown leaves no morpheme to hold, in the order the old
diff --git a/src/types/analysis-repository.ts b/src/types/analysis-repository.ts
index 355dcf100..c8c20f4cd 100644
--- a/src/types/analysis-repository.ts
+++ b/src/types/analysis-repository.ts
@@ -194,6 +194,13 @@ export interface AnalysisRepository {
    */
   apply(changes: ChangeSet): Promise<ApplyResult>;
 
+  /**
+   * The draft's own record, as {@link exportAll} would load it without its analysis.
+   *
+   * @throws Whatever {@link exportAll} throws.
+   */
+  getScope(): Promise<ScopeRecord>;
+
   /** The token analyses stored under `ids`; an id with none stored under it is skipped. */
   getTokenAnalyses(ids: string[]): Promise<TokenAnalysis[]>;
 
diff --git a/src/types/interlinearizer.d.ts b/src/types/interlinearizer.d.ts
index b7be3e07c..8355e47de 100644
--- a/src/types/interlinearizer.d.ts
+++ b/src/types/interlinearizer.d.ts
@@ -390,6 +390,34 @@ declare module 'papi-shared-types' {
      */
     'interlinearizer.checkIndexes': (sessionId: string) => Promise<string>;
 
+    /**
+     * Writes a token's gloss in a session's analysis language; a blank value clears it.
+     *
+     * @returns A JSON string of the changes it applied.
+     * @throws If the session is read-only or not open, or the edit is refused or fails (logged
+     *   before rethrowing).
+     */
+    'interlinearizer.writeGloss': (
+      sessionId: string,
+      tokenRef: string,
+      surfaceText: string,
+      value: string,
+    ) => Promise<string>;
+
+    /**
+     * Approves a stored token analysis for a token, in place of any approval it held.
+     *
+     * @returns A JSON string of the changes it applied.
+     * @throws If the session is read-only or not open, or the edit is refused or fails (logged
+     *   before rethrowing).
+     */
+    'interlinearizer.approveAnalysisForToken': (
+      sessionId: string,
+      tokenRef: string,
+      surfaceText: string,
+      analysisId: string,
+    ) => Promise<string>;
+
     /**
      * Turns the extension host's timing entries on or off, discarding any it holds. Off until
      * turned on.
diff --git a/src/utils/change-set.ts b/src/utils/change-set.ts
index 9d3ee463b..785c96dc3 100644
--- a/src/utils/change-set.ts
+++ b/src/utils/change-set.ts
@@ -7,6 +7,11 @@ export type AppliedChanges = {
   inverse: ChangeSet;
 };
 
+/** Whether `changes` change no record, the scope's record included. */
+export function isEmptyChangeSet(changes: ChangeSet): boolean {
+  return Object.keys(changes).every((key) => key === 'intent');
+}
+
 /** The draft's record, without its analysis. */
 // eslint-disable-next-line @typescript-eslint/no-unused-vars -- named only to leave it out
 export function scopeRecordOf({ analysis, ...scope }: DraftProject): ScopeRecord {
diff --git a/src/utils/token-analysis-content.ts b/src/utils/token-analysis-content.ts
new file mode 100644
index 000000000..81f65e855
--- /dev/null
+++ b/src/utils/token-analysis-content.ts
@@ -0,0 +1,42 @@
+import type { TokenAnalysis } from 'interlinearizer';
+import { isEmptyMultiString } from './multi-string';
+
+/**
+ * Determines whether a `TokenAnalysis` carries no analysis content, so an edit that just emptied
+ * one field can drop the whole record instead of letting empty records accumulate in storage.
+ * Checks every content field of the type — `gloss`, `morphemes`, `pos`, `features`, and
+ * `glossSenseRef` — not only the field the caller emptied, so records carrying imported
+ * morphosyntactic or lexicon data are never discarded by an unrelated edit. A gloss counts as empty
+ * when it has no entries or every entry is blank, so a record left holding only whitespace glosses
+ * (junk from clearing a gloss field) is treated the same as one with no gloss at all.
+ *
+ * Provenance fields (`confidence`, `producer`, `sourceUser`) are intentionally NOT treated as
+ * content: they describe who/what produced an analysis, not an analysis worth keeping on their own.
+ * A record holding only provenance and no glosses/morphemes/pos/features is therefore considered
+ * empty and may be dropped when its last content field is cleared. This is a deliberate choice — if
+ * a future workflow needs provenance-only records (e.g. imported parser metadata) to survive a
+ * gloss clear, add the relevant fields to the check below.
+ */
+export function isEmptyTokenAnalysis(analysis: TokenAnalysis): boolean {
+  return (
+    isEmptyMultiString(analysis.gloss) &&
+    /* v8 ignore next -- the length===0 sub-branch needs an empty-but-defined morphemes array, which no caller produces */
+    (!analysis.morphemes || analysis.morphemes.length === 0) &&
+    analysis.pos === undefined &&
+    analysis.features === undefined &&
+    analysis.glossSenseRef === undefined
+  );
+}
+
+/**
+ * Empties one language's gloss, dropping the gloss and the analysis-wide `glossSenseRef` once no
+ * language is left holding usable text — a sibling left holding only whitespace counts for neither,
+ * so the sense is never stranded on a gloss nothing renders.
+ */
+export function clearAnalysisGloss(analysis: TokenAnalysis, lang: string): void {
+  if (analysis.gloss) {
+    delete analysis.gloss[lang];
+    if (isEmptyMultiString(analysis.gloss)) delete analysis.gloss;
+  }
+  if (!analysis.gloss) delete analysis.glossSenseRef;
+}

From 132a68270f88ab16c41f05fd82a422911c41fdfc Mon Sep 17 00:00:00 2001
From: Alex Rawlings <alex.rawlings@wycliffe.ca>
Date: Fri, 23 Oct 2026 12:49:00 -0600
Subject: [PATCH 12/22] Add derived indexes with a rebuild-and-diff command
 (#442)

---
 AGENTS.md                                     |   2 +-
 .../analysis-repository-conformance.ts        | 238 +++++++++++++++++-
 src/__tests__/main.test.ts                    |  38 +++
 src/__tests__/services/analysisIndex.test.ts  | 177 +++++++++++++
 .../services/draftRepository.test.ts          |  41 +++
 .../services/indexedRepository.test.ts        |  70 ++++++
 src/__tests__/services/projectStorage.test.ts |  37 +++
 .../services/pt9ImportRepository.test.ts      |  52 ++++
 src/__tests__/services/recordTable.test.ts    |  96 +++++++
 src/__tests__/utils/change-set.test.ts        |  16 --
 src/__tests__/utils/json-copy.test.ts         |  16 ++
 src/main.ts                                   |  37 +++
 src/services/analysisIndex.ts                 | 186 ++++++++++++++
 src/services/draftRepository.ts               |  49 +++-
 src/services/indexedRepository.ts             |  95 +++++++
 src/services/projectStorage.ts                |  15 ++
 src/services/pt9ImportRepository.ts           |  67 +++--
 src/services/recordTable.ts                   | 122 +++++++++
 src/types/analysis-repository.ts              |  69 ++++-
 src/types/interlinearizer.d.ts                |   9 +
 src/utils/change-set.ts                       |  13 +-
 src/utils/json-copy.ts                        |   4 +
 22 files changed, 1388 insertions(+), 61 deletions(-)
 create mode 100644 src/__tests__/services/analysisIndex.test.ts
 create mode 100644 src/__tests__/services/indexedRepository.test.ts
 create mode 100644 src/__tests__/services/recordTable.test.ts
 create mode 100644 src/__tests__/utils/json-copy.test.ts
 create mode 100644 src/services/analysisIndex.ts
 create mode 100644 src/services/indexedRepository.ts
 create mode 100644 src/services/recordTable.ts
 create mode 100644 src/utils/json-copy.ts

diff --git a/AGENTS.md b/AGENTS.md
index 1a3163569..435e6c976 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 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)). [Pt9ImportRepository](src/services/pt9ImportRepository.ts) serves a Paratext 9 import through the same seam, read-only.
+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)). [Pt9ImportRepository](src/services/pt9ImportRepository.ts) serves a Paratext 9 import through the same seam, read-only. Both answer the seam's lookups (by token ref, segment id, analysis id, normalized form, and book and status) from an [AnalysisIndex](src/services/analysisIndex.ts) built from the records on first use and kept current by `apply`; `checkIndexes` rebuilds it and reports any difference.
 
 [The conformance suite](src/__tests__/analysis-repository-conformance.ts) defines the seam: every `AnalysisRepository` implementation must pass it, and [draftRepository.conformance.test.ts](src/__tests__/services/draftRepository.conformance.test.ts) runs it against `DraftRepository` and `Pt9ImportRepository`. A behavior every implementation owes goes in the suite; one particular to an implementation, such as which shards a save rewrites, goes in that implementation's own tests. A later backend runs the suite by passing `describeAnalysisRepositoryConformance` a factory that returns a fresh `ConformanceStore` for each test.
 
diff --git a/src/__tests__/analysis-repository-conformance.ts b/src/__tests__/analysis-repository-conformance.ts
index 5205a8e66..e938a7abc 100644
--- a/src/__tests__/analysis-repository-conformance.ts
+++ b/src/__tests__/analysis-repository-conformance.ts
@@ -1,10 +1,16 @@
 /// <reference types="jest" />
 
 import type { DraftProject, TextAnalysis } from 'interlinearizer';
-import type { AnalysisRepository, ChangeSet, DraftExport } from '../types/analysis-repository';
+import type {
+  AnalysisLinks,
+  AnalysisRepository,
+  ChangeSet,
+  DraftExport,
+} from '../types/analysis-repository';
 import { emptyAnalysis, emptyDraft } from '../types/empty-factories';
 import { CURRENT_MODEL_VERSION } from '../types/model-version';
 import { ReadOnlyAnalysisError } from '../types/read-only-analysis-error';
+import { normalizeSurfaceForm } from '../utils/analysis-identity';
 import { scopeRecordOf } from '../utils/change-set';
 import { FIXTURE_STAMPS, makePhraseLink, makeTokenLink } from './test-helpers';
 
@@ -393,6 +399,22 @@ function changeInPlace(draft: DraftProject): void {
   });
 }
 
+/** The ids of `records`, sorted, since lookups promise no order. */
+function idsOf(records: readonly { id: string }[]): string[] {
+  return records.map(({ id }) => id).sort();
+}
+
+/** The ids of each kind of link in `links`, sorted, since lookups promise no order. */
+function linkIdsOf(links: Partial<AnalysisLinks>) {
+  return {
+    ...(links.tokenAnalysisLinks && { tokenAnalysisLinks: idsOf(links.tokenAnalysisLinks) }),
+    ...(links.phraseAnalysisLinks && { phraseAnalysisLinks: idsOf(links.phraseAnalysisLinks) }),
+    ...(links.segmentAnalysisLinks && {
+      segmentAnalysisLinks: idsOf(links.segmentAnalysisLinks),
+    }),
+  };
+}
+
 /** Expects `value` to survive a JSON round trip unchanged and to hold no `null`. */
 function expectJsonPlain(value: unknown): void {
   expect(JSON.parse(JSON.stringify(value))).toStrictEqual(value);
@@ -1197,6 +1219,220 @@ export function describeAnalysisRepositoryConformance(
       });
     });
 
+    describe('lookups', () => {
+      /** A repository over {@link fullDraft}, saved through another one so its lookups load it. */
+      async function overFullDraft(): Promise<AnalysisRepository> {
+        await (await store.open(SOURCE)).replaceAll(fullDraft());
+        return store.open(SOURCE);
+      }
+
+      it('gets each payload kind by id, once per id, skipping ids with nothing stored', async () => {
+        const repository = await overFullDraft();
+
+        await expect(
+          repository.getTokenAnalyses(['ta-and', 'ta-missing', 'ta-and']).then(idsOf),
+        ).resolves.toStrictEqual(['ta-and']);
+        await expect(repository.getPhraseAnalyses(['pa-in-the'])).resolves.toStrictEqual(
+          fullAnalysis().phraseAnalyses,
+        );
+        await expect(
+          repository.getSegmentAnalyses(['sa-exo', 'sa-missing']),
+        ).resolves.toStrictEqual(fullAnalysis().segmentAnalyses);
+      });
+
+      it('finds the token links on tokens, and the phrase links touching them, each once', async () => {
+        const repository = await overFullDraft();
+
+        await expect(
+          repository.findLinksByToken(['GEN 1:1:0', 'GEN 1:1:2', 'GEN 1:1:4']).then(linkIdsOf),
+        ).resolves.toStrictEqual({
+          tokenAnalysisLinks: ['tl-gen-and'],
+          phraseAnalysisLinks: ['pa-in-the'],
+        });
+      });
+
+      it('finds the segment links on segments', async () => {
+        const repository = await overFullDraft();
+
+        await expect(
+          repository.findLinksBySegment(['EXO 1:1', 'GEN 1:1']).then(idsOf),
+        ).resolves.toStrictEqual(['sl-exo']);
+      });
+
+      it('finds the links of every kind to analyses', async () => {
+        const repository = await overFullDraft();
+
+        await expect(
+          repository.findLinksToAnalyses(['ta-and', 'pa-in-the', 'sa-exo']).then(linkIdsOf),
+        ).resolves.toStrictEqual({
+          tokenAnalysisLinks: ['tl-exo-and', 'tl-gen-and'],
+          phraseAnalysisLinks: ['pa-in-the'],
+          segmentAnalysisLinks: ['sl-exo'],
+        });
+      });
+
+      it('finds the links of every kind into books', async () => {
+        const repository = await overFullDraft();
+
+        await expect(repository.findLinksInBooks(['GEN']).then(linkIdsOf)).resolves.toStrictEqual({
+          tokenAnalysisLinks: ['tl-gen-and', 'tl-gen-beginning'],
+          phraseAnalysisLinks: ['pa-in-the'],
+          segmentAnalysisLinks: [],
+        });
+      });
+
+      it('finds the links into books with the statuses asked for', async () => {
+        const repository = await overFullDraft();
+
+        await expect(
+          repository.findLinksInBooks(['GEN', 'EXO'], ['suggested']).then(linkIdsOf),
+        ).resolves.toStrictEqual({
+          tokenAnalysisLinks: ['tl-gen-beginning'],
+          phraseAnalysisLinks: [],
+          segmentAnalysisLinks: [],
+        });
+      });
+
+      it('finds the payloads whose surface text normalizes to a form', async () => {
+        const repository = await overFullDraft();
+        await repository.apply({
+          intent: 'addCapitalized',
+          tokenAnalyses: {
+            puts: [{ id: 'ta-And', ...FIXTURE_STAMPS, surfaceText: 'And' }],
+            deletes: [],
+          },
+        });
+
+        await expect(
+          repository.findTokenAnalysesByForm([normalizeSurfaceForm('AND')]).then(idsOf),
+        ).resolves.toStrictEqual(['ta-And', 'ta-and']);
+        await expect(
+          repository.findPhraseAnalysesByForm([normalizeSurfaceForm('In The')]).then(idsOf),
+        ).resolves.toStrictEqual(['pa-in-the']);
+      });
+
+      it('finds nothing in a draft never saved', async () => {
+        const repository = await store.open(SOURCE);
+
+        await expect(repository.findLinksInBooks(['GEN']).then(linkIdsOf)).resolves.toStrictEqual({
+          tokenAnalysisLinks: [],
+          phraseAnalysisLinks: [],
+          segmentAnalysisLinks: [],
+        });
+        await expect(repository.getTokenAnalyses(['ta-and'])).resolves.toStrictEqual([]);
+      });
+
+      it('answers from the records the applied changes leave', async () => {
+        const repository = await overFullDraft();
+        await repository.findLinksInBooks(['GEN']);
+
+        await repository.apply(mixedChanges());
+
+        await expect(
+          repository.findLinksToAnalyses(['ta-beginning', 'ta-god']).then(linkIdsOf),
+        ).resolves.toStrictEqual({
+          tokenAnalysisLinks: ['tl-gen-god'],
+          phraseAnalysisLinks: [],
+          segmentAnalysisLinks: [],
+        });
+        await expect(
+          repository.findLinksBySegment(['GEN 1:1', 'EXO 1:1']).then(idsOf),
+        ).resolves.toStrictEqual(['sl-gen']);
+        await expect(
+          repository.findLinksByToken(['GEN 1:1:2', 'GEN 1:1:13']).then(linkIdsOf),
+        ).resolves.toStrictEqual({
+          tokenAnalysisLinks: [],
+          phraseAnalysisLinks: ['pa-the-beginning'],
+        });
+        await expect(repository.getTokenAnalyses(['ta-and'])).resolves.toStrictEqual([
+          { ...fullAnalysis().tokenAnalyses[0], gloss: { en: 'and then' } },
+        ]);
+      });
+
+      it('files an edited record under its new keys only', async () => {
+        const repository = await overFullDraft();
+        await repository.findLinksInBooks(['GEN']);
+        const [, , beginning] = fullAnalysis().tokenAnalysisLinks;
+
+        await repository.apply({
+          intent: 'approve',
+          tokenAnalysisLinks: { puts: [{ ...beginning, status: 'approved' }], deletes: [] },
+        });
+
+        await expect(
+          repository.findLinksInBooks(['GEN'], ['suggested']).then(linkIdsOf),
+        ).resolves.toMatchObject({ tokenAnalysisLinks: [] });
+        await expect(
+          repository.findLinksInBooks(['GEN'], ['approved']).then(linkIdsOf),
+        ).resolves.toMatchObject({ tokenAnalysisLinks: ['tl-gen-and', 'tl-gen-beginning'] });
+      });
+
+      it('answers from a draft another repository replaced, once reloaded', async () => {
+        const repository = await overFullDraft();
+        await repository.findLinksInBooks(['GEN']);
+        await (await store.open(SOURCE)).replaceAll(exodusOnlyDraft());
+
+        await repository.exportAll();
+
+        await expect(
+          repository.findLinksInBooks(['GEN', 'EXO']).then(linkIdsOf),
+        ).resolves.toStrictEqual({
+          tokenAnalysisLinks: ['tl-exo-and'],
+          phraseAnalysisLinks: [],
+          segmentAnalysisLinks: ['sl-exo'],
+        });
+      });
+
+      it('keeps the records of different source projects apart', async () => {
+        await overFullDraft();
+
+        const other = await store.open('other-project');
+
+        await expect(other.getTokenAnalyses(['ta-and'])).resolves.toStrictEqual([]);
+      });
+
+      it('returns records the caller may change without changing what is stored', async () => {
+        const repository = await overFullDraft();
+
+        const [and] = await repository.getTokenAnalyses(['ta-and']);
+        and.surfaceText = 'changed';
+        const { tokenAnalysisLinks } = await repository.findLinksToAnalyses(['ta-and']);
+        tokenAnalysisLinks[0].status = 'rejected';
+
+        await expect(repository.getTokenAnalyses(['ta-and'])).resolves.toStrictEqual([
+          fullAnalysis().tokenAnalyses[0],
+        ]);
+        await expect(
+          repository.findLinksInBooks(['GEN', 'EXO'], ['rejected']).then(linkIdsOf),
+        ).resolves.toMatchObject({ tokenAnalysisLinks: [] });
+      });
+
+      it('keeps indexes that match its records through applies, undo and redo', async () => {
+        const repository = await overFullDraft();
+        await repository.findLinksInBooks(['GEN']);
+
+        const { inverse } = await repository.apply(mixedChanges());
+        const { inverse: redo } = await repository.apply(inverse);
+        await repository.apply(redo);
+        await repository.apply(puttingNewRecords());
+
+        await expect(repository.checkIndexes()).resolves.toStrictEqual([]);
+      });
+
+      it('answers from a read-only repository', async () => {
+        const repository = await store.openReadOnly(fullDraft());
+
+        await expect(
+          repository.findLinksToAnalyses(['ta-and']).then(linkIdsOf),
+        ).resolves.toStrictEqual({
+          tokenAnalysisLinks: ['tl-exo-and', 'tl-gen-and'],
+          phraseAnalysisLinks: [],
+          segmentAnalysisLinks: [],
+        });
+        await expect(repository.checkIndexes()).resolves.toStrictEqual([]);
+      });
+    });
+
     describe('capabilities', () => {
       it("lets a source project's draft be written", async () => {
         expect((await store.open(SOURCE)).capabilities.readOnly).toBe(false);
diff --git a/src/__tests__/main.test.ts b/src/__tests__/main.test.ts
index 5d00fe95b..b24169bbe 100644
--- a/src/__tests__/main.test.ts
+++ b/src/__tests__/main.test.ts
@@ -400,6 +400,7 @@ describe('main', () => {
           'interlinearizer.setAnalysisLanguage',
           'interlinearizer.undoEdit',
           'interlinearizer.redoEdit',
+          'interlinearizer.checkIndexes',
           'interlinearizer.openSelectProjectModal',
           'interlinearizer.openNewProjectModal',
           'interlinearizer.openProjectInfoModal',
@@ -1827,6 +1828,7 @@ describe('main', () => {
   describe('session commands', () => {
     /** A repository handing out `draft`, as storage would open one. */
     function stubRepository(draft: DraftProject, readOnly = false): AnalysisRepository {
+      const noLinks = { tokenAnalysisLinks: [], phraseAnalysisLinks: [], segmentAnalysisLinks: [] };
       return {
         capabilities: { readOnly },
         exportAll: async () => ({ draft, unreadableBooks: [] }),
@@ -1834,6 +1836,18 @@ describe('main', () => {
         replaceAll: async () => [],
         markClean: async () => {},
         apply: async (changes) => ({ inverse: changes }),
+        getTokenAnalyses: async () => [],
+        getPhraseAnalyses: async () => [],
+        getSegmentAnalyses: async () => [],
+        findLinksByToken: async () => noLinks,
+        findLinksBySegment: async () => [],
+        findLinksToAnalyses: async () => noLinks,
+        findLinksInBooks: async () => noLinks,
+        findTokenAnalysesByForm: async () => [],
+        findPhraseAnalysesByForm: async () => [],
+        checkIndexes: async () => [
+          { index: 'tokenAnalyses', key: 'ta-1', missing: ['ta-1'], extra: [] },
+        ],
       };
     }
 
@@ -1860,6 +1874,9 @@ describe('main', () => {
         redoEdit: handler<(sessionId: string) => Promise<string | undefined>>(
           'interlinearizer.redoEdit',
         ),
+        checkIndexes: handler<(sessionId: string) => Promise<string>>(
+          'interlinearizer.checkIndexes',
+        ),
       };
     }
 
@@ -2022,6 +2039,27 @@ describe('main', () => {
       );
     });
 
+    it("replies with the differences the session's repository finds in its indexes", async () => {
+      const { openSession, checkIndexes } = await activateSessionCommands();
+      const { sessionId } = JSON.parse(await openSession('src-project'));
+
+      await expect(checkIndexes(sessionId)).resolves.toBe(
+        JSON.stringify([{ index: 'tokenAnalyses', key: 'ta-1', missing: ['ta-1'], extra: [] }]),
+      );
+    });
+
+    it('logs the error and rethrows when the indexes cannot be checked', async () => {
+      const { checkIndexes } = await activateSessionCommands();
+
+      await expect(checkIndexes('not-a-session')).rejects.toThrow(
+        'no session not-a-session is open',
+      );
+      expect(__mockLogger.error).toHaveBeenCalledWith(
+        'Interlinearizer: failed to check the indexes of session not-a-session',
+        expect.any(Error),
+      );
+    });
+
     it('closes every session on deactivation', async () => {
       const { openSession } = await activateSessionCommands();
       await openSession('src-project');
diff --git a/src/__tests__/services/analysisIndex.test.ts b/src/__tests__/services/analysisIndex.test.ts
new file mode 100644
index 000000000..61529869a
--- /dev/null
+++ b/src/__tests__/services/analysisIndex.test.ts
@@ -0,0 +1,177 @@
+/// <reference types="jest" />
+
+import type { TextAnalysis } from 'interlinearizer';
+import { AnalysisIndex } from '../../services/analysisIndex';
+import { emptyAnalysis } from '../../types/empty-factories';
+import { normalizeSurfaceForm } from '../../utils/analysis-identity';
+import { FIXTURE_STAMPS, makePhraseLink } from '../test-helpers';
+
+const link = { ...FIXTURE_STAMPS, status: 'approved' as const };
+
+/** Records in GEN and EXO, with a heading's segment in GEN and a suggested link in EXO. */
+function analysis(): TextAnalysis {
+  return {
+    segmentAnalyses: [{ id: 'sa-1', ...FIXTURE_STAMPS, surfaceText: 'The Creation' }],
+    segmentAnalysisLinks: [{ ...link, id: 'sl-1', analysisId: 'sa-1', segmentId: 'GEN 1:1/s1' }],
+    tokenAnalyses: [
+      { id: 'ta-and', ...FIXTURE_STAMPS, surfaceText: 'and' },
+      { id: 'ta-And', ...FIXTURE_STAMPS, surfaceText: 'And' },
+    ],
+    tokenAnalysisLinks: [
+      {
+        ...link,
+        id: 'tl-gen',
+        analysisId: 'ta-and',
+        token: { tokenRef: 'GEN 1:1:0', surfaceText: 'and' },
+      },
+      {
+        ...link,
+        id: 'tl-exo',
+        analysisId: 'ta-And',
+        status: 'suggested',
+        token: { tokenRef: 'EXO 1:1:0', surfaceText: 'And' },
+      },
+    ],
+    phraseAnalyses: [{ id: 'pa-1', ...FIXTURE_STAMPS, surfaceText: 'In the' }],
+    phraseAnalysisLinks: [makePhraseLink('pa-1', ['GEN 1:1:4', 'GEN 1:1:7'])],
+  };
+}
+
+const ids = (records: readonly { id: string }[]) => records.map(({ id }) => id).sort();
+
+describe('AnalysisIndex', () => {
+  it('gets payloads of each kind by id', () => {
+    const index = new AnalysisIndex(analysis());
+
+    expect(ids(index.getTokenAnalyses(['ta-and', 'missing']))).toStrictEqual(['ta-and']);
+    expect(ids(index.getPhraseAnalyses(['pa-1']))).toStrictEqual(['pa-1']);
+    expect(ids(index.getSegmentAnalyses(['sa-1']))).toStrictEqual(['sa-1']);
+  });
+
+  it('finds token links by token ref, and phrase links by any of their tokens', () => {
+    const { tokenAnalysisLinks, phraseAnalysisLinks } = new AnalysisIndex(
+      analysis(),
+    ).findLinksByToken(['GEN 1:1:0', 'GEN 1:1:7']);
+
+    expect(ids(tokenAnalysisLinks)).toStrictEqual(['tl-gen']);
+    expect(ids(phraseAnalysisLinks)).toStrictEqual(['pa-1']);
+  });
+
+  it('finds segment links by segment id', () => {
+    expect(ids(new AnalysisIndex(analysis()).findLinksBySegment(['GEN 1:1/s1']))).toStrictEqual([
+      'sl-1',
+    ]);
+  });
+
+  it('finds the links of every kind to analyses', () => {
+    const links = new AnalysisIndex(analysis()).findLinksToAnalyses(['ta-and', 'pa-1', 'sa-1']);
+
+    expect(ids(links.tokenAnalysisLinks)).toStrictEqual(['tl-gen']);
+    expect(ids(links.phraseAnalysisLinks)).toStrictEqual(['pa-1']);
+    expect(ids(links.segmentAnalysisLinks)).toStrictEqual(['sl-1']);
+  });
+
+  it('files a heading segment link and a phrase link under their books', () => {
+    const links = new AnalysisIndex(analysis()).findLinksInBooks(['GEN']);
+
+    expect(ids(links.tokenAnalysisLinks)).toStrictEqual(['tl-gen']);
+    expect(ids(links.phraseAnalysisLinks)).toStrictEqual(['pa-1']);
+    expect(ids(links.segmentAnalysisLinks)).toStrictEqual(['sl-1']);
+  });
+
+  it('finds the links into books with the statuses asked for', () => {
+    const links = new AnalysisIndex(analysis()).findLinksInBooks(['GEN', 'EXO'], ['suggested']);
+
+    expect(ids(links.tokenAnalysisLinks)).toStrictEqual(['tl-exo']);
+    expect(links.phraseAnalysisLinks).toStrictEqual([]);
+    expect(links.segmentAnalysisLinks).toStrictEqual([]);
+  });
+
+  it('finds payloads by normalized form', () => {
+    const index = new AnalysisIndex(analysis());
+
+    expect(ids(index.findTokenAnalysesByForm([normalizeSurfaceForm('AND')]))).toStrictEqual([
+      'ta-And',
+      'ta-and',
+    ]);
+    expect(ids(index.findPhraseAnalysesByForm(['in the']))).toStrictEqual(['pa-1']);
+  });
+
+  it('keeps every lookup current as changes apply', () => {
+    const index = new AnalysisIndex(analysis());
+
+    index.apply({
+      intent: 'edit',
+      tokenAnalyses: {
+        puts: [{ id: 'ta-and', ...FIXTURE_STAMPS, surfaceText: 'but' }],
+        deletes: [],
+      },
+      tokenAnalysisLinks: { puts: [], deletes: ['tl-exo'] },
+      phraseAnalyses: { puts: [], deletes: ['pa-1'] },
+      phraseAnalysisLinks: { puts: [], deletes: ['pa-1'] },
+      segmentAnalyses: { puts: [], deletes: ['sa-1'] },
+      segmentAnalysisLinks: { puts: [], deletes: ['sl-1'] },
+    });
+
+    expect(ids(index.findTokenAnalysesByForm(['and']))).toStrictEqual(['ta-And']);
+    expect(ids(index.findTokenAnalysesByForm(['but']))).toStrictEqual(['ta-and']);
+    expect(index.findLinksInBooks(['GEN', 'EXO'])).toStrictEqual({
+      tokenAnalysisLinks: [analysis().tokenAnalysisLinks[0]],
+      phraseAnalysisLinks: [],
+      segmentAnalysisLinks: [],
+    });
+    expect(index.findPhraseAnalysesByForm(['in the'])).toStrictEqual([]);
+    expect(index.getSegmentAnalyses(['sa-1'])).toStrictEqual([]);
+  });
+
+  describe('differencesFrom', () => {
+    it('reports none against the analysis it was built from', () => {
+      expect(new AnalysisIndex(analysis()).differencesFrom(analysis())).toStrictEqual([]);
+    });
+
+    it('reports none once kept current through changes the analysis also took', () => {
+      const index = new AnalysisIndex(analysis());
+      const changed = analysis();
+      changed.tokenAnalysisLinks.pop();
+
+      index.apply({ intent: 'delete', tokenAnalysisLinks: { puts: [], deletes: ['tl-exo'] } });
+
+      expect(index.differencesFrom(changed)).toStrictEqual([]);
+    });
+
+    it('reports the records and entries of every kind that an analysis holds differently', () => {
+      const differences = new AnalysisIndex(emptyAnalysis()).differencesFrom(analysis());
+
+      expect(new Set(differences.map(({ index }) => index))).toStrictEqual(
+        new Set([
+          'tokenAnalyses',
+          'tokenAnalyses by form',
+          'phraseAnalyses',
+          'phraseAnalyses by form',
+          'segmentAnalyses',
+          'tokenAnalysisLinks',
+          'tokenAnalysisLinks by analysisId',
+          'tokenAnalysisLinks by book',
+          'tokenAnalysisLinks by bookStatus',
+          'tokenAnalysisLinks by tokenRef',
+          'phraseAnalysisLinks',
+          'phraseAnalysisLinks by analysisId',
+          'phraseAnalysisLinks by book',
+          'phraseAnalysisLinks by bookStatus',
+          'phraseAnalysisLinks by tokenRef',
+          'segmentAnalysisLinks',
+          'segmentAnalysisLinks by analysisId',
+          'segmentAnalysisLinks by book',
+          'segmentAnalysisLinks by bookStatus',
+          'segmentAnalysisLinks by segmentId',
+        ]),
+      );
+      expect(differences).toContainEqual({
+        index: 'tokenAnalysisLinks by bookStatus',
+        key: 'EXO/suggested',
+        missing: ['tl-exo'],
+        extra: [],
+      });
+    });
+  });
+});
diff --git a/src/__tests__/services/draftRepository.test.ts b/src/__tests__/services/draftRepository.test.ts
index 04c4561ea..c14c50da2 100644
--- a/src/__tests__/services/draftRepository.test.ts
+++ b/src/__tests__/services/draftRepository.test.ts
@@ -360,4 +360,45 @@ describe('DraftRepository', () => {
       expect(records.get(draftAnalysisKey('src', 'GEN'))).not.toContain('and then');
     });
   });
+
+  describe('lookups', () => {
+    it('load the draft once, answering later lookups from what they kept', async () => {
+      const { storage } = memoryStorage();
+      await new DraftRepository(storage, 'src', silentLogger()).replaceAll(twoBookDraft());
+      const repository = new DraftRepository(storage, 'src', silentLogger());
+      const read = jest.spyOn(storage, 'read');
+
+      await repository.findLinksInBooks(['GEN']);
+      const readsAfterFirst = read.mock.calls.length;
+      await repository.findLinksToAnalyses(['ta-and']);
+
+      expect(readsAfterFirst).toBeGreaterThan(0);
+      expect(read).toHaveBeenCalledTimes(readsAfterFirst);
+    });
+
+    it('answer from what an apply left without loading the draft again', async () => {
+      const { storage } = memoryStorage();
+      const repository = new DraftRepository(storage, 'src', silentLogger());
+      await repository.apply({
+        intent: 'add',
+        tokenAnalyses: { puts: twoBookAnalysis().tokenAnalyses, deletes: [] },
+      });
+      const read = jest.spyOn(storage, 'read');
+
+      await expect(repository.getTokenAnalyses(['ta-and'])).resolves.toStrictEqual(
+        twoBookAnalysis().tokenAnalyses,
+      );
+      expect(read).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('checkIndexes', () => {
+    it('reports nothing while it keeps no index', async () => {
+      const { storage } = memoryStorage();
+      const repository = new DraftRepository(storage, 'src', silentLogger());
+      await repository.replaceAll(twoBookDraft());
+
+      await expect(repository.checkIndexes()).resolves.toStrictEqual([]);
+    });
+  });
 });
diff --git a/src/__tests__/services/indexedRepository.test.ts b/src/__tests__/services/indexedRepository.test.ts
new file mode 100644
index 000000000..290a6cb98
--- /dev/null
+++ b/src/__tests__/services/indexedRepository.test.ts
@@ -0,0 +1,70 @@
+/// <reference types="jest" />
+
+import type { TextAnalysis } from 'interlinearizer';
+import { AnalysisIndex } from '../../services/analysisIndex';
+import { type IndexedAnalysis, IndexedRepository } from '../../services/indexedRepository';
+import { emptyAnalysis } from '../../types/empty-factories';
+import { FIXTURE_STAMPS } from '../test-helpers';
+
+/** Answers lookups from an index over `records`, keeping it as `keep` says. */
+class StubRepository extends IndexedRepository {
+  readonly kept: IndexedAnalysis | undefined;
+
+  private readonly index: AnalysisIndex;
+
+  constructor(records: TextAnalysis, keep: 'kept' | 'none') {
+    super();
+    this.index = new AnalysisIndex(records);
+    this.kept = keep === 'kept' ? { analysis: records, index: this.index } : undefined;
+  }
+
+  protected async indexed(): Promise<AnalysisIndex> {
+    return this.index;
+  }
+
+  protected keptIndex(): IndexedAnalysis | undefined {
+    return this.kept;
+  }
+}
+
+function analysis(): TextAnalysis {
+  return {
+    ...emptyAnalysis(),
+    tokenAnalyses: [{ id: 'ta-and', ...FIXTURE_STAMPS, surfaceText: 'and' }],
+  };
+}
+
+describe('IndexedRepository', () => {
+  it('answers lookups from its index', async () => {
+    await expect(
+      new StubRepository(analysis(), 'none').getTokenAnalyses(['ta-and']),
+    ).resolves.toStrictEqual(analysis().tokenAnalyses);
+  });
+
+  it('hands out copies of the records its index holds', async () => {
+    const repository = new StubRepository(analysis(), 'none');
+
+    const [and] = await repository.getTokenAnalyses(['ta-and']);
+    and.surfaceText = 'changed';
+
+    await expect(repository.getTokenAnalyses(['ta-and'])).resolves.toStrictEqual(
+      analysis().tokenAnalyses,
+    );
+  });
+
+  it('reports the differences of the index it keeps from its analysis', async () => {
+    const repository = new StubRepository(analysis(), 'kept');
+    repository.kept?.analysis.tokenAnalyses.pop();
+
+    await expect(repository.checkIndexes()).resolves.toContainEqual({
+      index: 'tokenAnalyses',
+      key: 'ta-and',
+      missing: [],
+      extra: ['ta-and'],
+    });
+  });
+
+  it('reports nothing while it keeps no index', async () => {
+    await expect(new StubRepository(analysis(), 'none').checkIndexes()).resolves.toStrictEqual([]);
+  });
+});
diff --git a/src/__tests__/services/projectStorage.test.ts b/src/__tests__/services/projectStorage.test.ts
index 24a6a63ab..948c16f9e 100644
--- a/src/__tests__/services/projectStorage.test.ts
+++ b/src/__tests__/services/projectStorage.test.ts
@@ -24,6 +24,7 @@ import {
   updateProjectMetadata,
 } from '../../services/projectStorage';
 import { summarizeProject } from '../../services/projectSummaries';
+import type { AnalysisRepository } from '../../types/analysis-repository';
 import { ReadOnlyAnalysisError } from '../../types/read-only-analysis-error';
 import { emptyAnalysis, emptyDraft } from '../../types/empty-factories';
 import { removeBookFromAnalysis } from '../../utils/analysis-book';
@@ -2915,6 +2916,42 @@ describe('projectStorage', () => {
       expect(analysis.tokenAnalysisLinks).toStrictEqual([]);
     });
 
+    it.each([
+      ['getTokenAnalyses', (r: AnalysisRepository) => r.getTokenAnalyses(['analysis-GEN']), 1],
+      ['getPhraseAnalyses', (r: AnalysisRepository) => r.getPhraseAnalyses(['p']), 0],
+      ['getSegmentAnalyses', (r: AnalysisRepository) => r.getSegmentAnalyses(['s']), 0],
+      ['findLinksBySegment', (r: AnalysisRepository) => r.findLinksBySegment(['GEN 1:1']), 0],
+      [
+        'findLinksByToken',
+        (r: AnalysisRepository) =>
+          r.findLinksByToken(['GEN 1:1!0']).then((l) => l.tokenAnalysisLinks),
+        1,
+      ],
+      [
+        'findLinksToAnalyses',
+        (r: AnalysisRepository) =>
+          r.findLinksToAnalyses(['analysis-GEN']).then((l) => l.tokenAnalysisLinks),
+        1,
+      ],
+      [
+        'findLinksInBooks',
+        (r: AnalysisRepository) =>
+          r.findLinksInBooks(['GEN'], ['approved']).then((l) => l.tokenAnalysisLinks),
+        1,
+      ],
+      [
+        'findTokenAnalysesByForm',
+        (r: AnalysisRepository) => r.findTokenAnalysesByForm(['word-gen']),
+        1,
+      ],
+      ['findPhraseAnalysesByForm', (r: AnalysisRepository) => r.findPhraseAnalysesByForm(['x']), 0],
+      ['checkIndexes', (r: AnalysisRepository) => r.checkIndexes(), 0],
+    ])('answers %s from the draft saveDraft saved', async (_name, lookup, count) => {
+      await saveDraft(token, 'src-proj', makeDraftSpanningBooks('src-proj', 'GEN'));
+
+      await expect(lookup(openDraftRepository(token, 'src-proj'))).resolves.toHaveLength(count);
+    });
+
     it('waits for a draft call already made before reading', async () => {
       let finishWrite: () => void = () => {};
       __mockWriteUserData.mockImplementationOnce(
diff --git a/src/__tests__/services/pt9ImportRepository.test.ts b/src/__tests__/services/pt9ImportRepository.test.ts
index 8a8c29420..62bb986eb 100644
--- a/src/__tests__/services/pt9ImportRepository.test.ts
+++ b/src/__tests__/services/pt9ImportRepository.test.ts
@@ -127,4 +127,56 @@ describe('Pt9ImportRepository', () => {
       expect(readProject).not.toHaveBeenCalled();
     });
   });
+
+  describe('lookups', () => {
+    const imported = () =>
+      makeImport({
+        analysis: {
+          ...emptyAnalysis(),
+          tokenAnalyses: [{ id: 'ta-1', ...FIXTURE_STAMPS, surfaceText: 'and' }],
+        },
+      });
+
+    it("answer from the import's records, reading it once", async () => {
+      const readProject = jest.fn(async () => imported());
+      const repository = new Pt9ImportRepository('import-id', readProject);
+
+      await expect(repository.getTokenAnalyses(['ta-1'])).resolves.toStrictEqual(
+        imported().analysis.tokenAnalyses,
+      );
+      await repository.findTokenAnalysesByForm(['and']);
+
+      expect(readProject).toHaveBeenCalledTimes(1);
+    });
+
+    it('read the import again after a load', async () => {
+      const readProject = jest.fn(async () => imported());
+      const repository = new Pt9ImportRepository('import-id', readProject);
+      await repository.getTokenAnalyses(['ta-1']);
+
+      await repository.exportAll();
+      await repository.getTokenAnalyses(['ta-1']);
+
+      expect(readProject).toHaveBeenCalledTimes(3);
+    });
+
+    it('refuse when no import is stored', async () => {
+      await expect(repositoryOver(undefined).getTokenAnalyses(['ta-1'])).rejects.toThrow(
+        'no Paratext 9 import is stored as project import-id',
+      );
+    });
+  });
+
+  describe('checkIndexes', () => {
+    it('reports nothing before a lookup', async () => {
+      await expect(repositoryOver(makeImport()).checkIndexes()).resolves.toStrictEqual([]);
+    });
+
+    it('reports nothing after a lookup, since an import never changes', async () => {
+      const repository = repositoryOver(makeImport());
+      await repository.getTokenAnalyses(['ta-1']);
+
+      await expect(repository.checkIndexes()).resolves.toStrictEqual([]);
+    });
+  });
 });
diff --git a/src/__tests__/services/recordTable.test.ts b/src/__tests__/services/recordTable.test.ts
new file mode 100644
index 000000000..b4245db81
--- /dev/null
+++ b/src/__tests__/services/recordTable.test.ts
@@ -0,0 +1,96 @@
+/// <reference types="jest" />
+
+import { RecordTable } from '../../services/recordTable';
+
+type Item = { id: string; tags: string[]; note?: string };
+
+const keyers = { tag: (item: Item) => item.tags };
+
+function tableOf(...items: Item[]) {
+  return new RecordTable('items', keyers, items);
+}
+
+describe('RecordTable', () => {
+  it('gets records by id, once per id, skipping ids with nothing stored', () => {
+    const a = { id: 'a', tags: [] };
+
+    expect(tableOf(a).get(['a', 'missing', 'a'])).toStrictEqual([a]);
+  });
+
+  it('finds the records filed under any of the keys, each once', () => {
+    const a = { id: 'a', tags: ['x', 'y'] };
+    const b = { id: 'b', tags: ['y'] };
+    const c = { id: 'c', tags: ['z'] };
+
+    expect(tableOf(a, b, c).find('tag', ['x', 'y', 'missing'])).toStrictEqual([a, b]);
+  });
+
+  it('files a record once under a key its keyer returns twice', () => {
+    const table = tableOf({ id: 'a', tags: ['x', 'x'] });
+
+    table.apply({ puts: [], deletes: ['a'] });
+
+    expect(table.find('tag', ['x'])).toStrictEqual([]);
+    expect(table.differencesFrom(tableOf())).toStrictEqual([]);
+  });
+
+  it('files a put record under its new keys only', () => {
+    const table = tableOf({ id: 'a', tags: ['x'] });
+    const moved = { id: 'a', tags: ['y'] };
+
+    table.apply({ puts: [moved], deletes: [] });
+
+    expect(table.find('tag', ['x'])).toStrictEqual([]);
+    expect(table.find('tag', ['y'])).toStrictEqual([moved]);
+  });
+
+  it('unfiles a deleted record, skipping an id with nothing stored', () => {
+    const table = tableOf({ id: 'a', tags: ['x'] });
+
+    table.apply({ puts: [], deletes: ['a', 'missing'] });
+
+    expect(table.get(['a'])).toStrictEqual([]);
+    expect(table.find('tag', ['x'])).toStrictEqual([]);
+  });
+
+  it('applies nothing for absent changes', () => {
+    const table = tableOf({ id: 'a', tags: ['x'] });
+
+    table.apply(undefined);
+
+    expect(table.differencesFrom(tableOf({ id: 'a', tags: ['x'] }))).toStrictEqual([]);
+  });
+
+  describe('differencesFrom', () => {
+    it('reports none against a table holding the same records', () => {
+      const items = [
+        { id: 'a', tags: ['x'] },
+        { id: 'b', tags: ['x', 'y'] },
+      ];
+
+      expect(tableOf(...items).differencesFrom(tableOf(...items))).toStrictEqual([]);
+    });
+
+    it('reports a record the kept table lacks, and the entries filing it', () => {
+      expect(tableOf().differencesFrom(tableOf({ id: 'a', tags: ['x'] }))).toStrictEqual([
+        { index: 'items', key: 'a', missing: ['a'], extra: [] },
+        { index: 'items by tag', key: 'x', missing: ['a'], extra: [] },
+      ]);
+    });
+
+    it('reports a record only the kept table holds, and the entries filing it', () => {
+      expect(tableOf({ id: 'a', tags: ['x'] }).differencesFrom(tableOf())).toStrictEqual([
+        { index: 'items', key: 'a', missing: [], extra: ['a'] },
+        { index: 'items by tag', key: 'x', missing: [], extra: ['a'] },
+      ]);
+    });
+
+    it('reports a record whose kept copy differs as both missing and extra', () => {
+      const kept = tableOf({ id: 'a', tags: [], note: 'old' });
+
+      expect(kept.differencesFrom(tableOf({ id: 'a', tags: [], note: 'new' }))).toStrictEqual([
+        { index: 'items', key: 'a', missing: ['a'], extra: ['a'] },
+      ]);
+    });
+  });
+});
diff --git a/src/__tests__/utils/change-set.test.ts b/src/__tests__/utils/change-set.test.ts
index 26f0cb087..a8f19f1ec 100644
--- a/src/__tests__/utils/change-set.test.ts
+++ b/src/__tests__/utils/change-set.test.ts
@@ -113,22 +113,6 @@ describe('applyChangeSet', () => {
     expect(stored).toStrictEqual(draftOf(payload('a')));
   });
 
-  it('holds copies of the records the changes put', () => {
-    const put = payload('b');
-    const scope = scopeRecordOf(draftOf());
-    const { draft } = applyChangeSet(draftOf(), {
-      intent: 'add',
-      scope,
-      tokenAnalyses: { puts: [put], deletes: [] },
-    });
-
-    put.surfaceText = 'changed';
-    scope.analysisLanguages.push('fr');
-
-    expect(draft.analysis.tokenAnalyses).toStrictEqual([payload('b')]);
-    expect(draft.analysisLanguages).toStrictEqual(['en']);
-  });
-
   it('refuses an id both put and deleted', () => {
     expect(() =>
       applyChangeSet(draftOf(payload('a')), {
diff --git a/src/__tests__/utils/json-copy.test.ts b/src/__tests__/utils/json-copy.test.ts
new file mode 100644
index 000000000..1ecdd4b5f
--- /dev/null
+++ b/src/__tests__/utils/json-copy.test.ts
@@ -0,0 +1,16 @@
+/// <reference types="jest" />
+
+import { jsonCopy } from '../../utils/json-copy';
+
+describe('jsonCopy', () => {
+  it('copies a JSON-plain value deeply, sharing nothing with it', () => {
+    const value = { gloss: { en: 'and' }, morphemes: [{ form: 'and' }] };
+
+    const copy = jsonCopy(value);
+    copy.gloss.en = 'changed';
+    copy.morphemes[0].form = 'changed';
+
+    expect(copy).not.toBe(value);
+    expect(value).toStrictEqual({ gloss: { en: 'and' }, morphemes: [{ form: 'and' }] });
+  });
+});
diff --git a/src/main.ts b/src/main.ts
index 6d5af1dcb..1ec3369aa 100644
--- a/src/main.ts
+++ b/src/main.ts
@@ -807,6 +807,25 @@ async function redoEdit(sessionId: string): Promise<string | undefined> {
   }
 }
 
+/**
+ * Rebuilds a session's derived indexes from its records and reports where the kept ones differ, for
+ * debugging.
+ *
+ * @returns A JSON string of the differences, empty when there are none.
+ * @throws If the session is not open, or its records cannot be read. The error is logged before
+ *   rethrowing.
+ */
+async function checkIndexes(sessionId: string): Promise<string> {
+  try {
+    return JSON.stringify(
+      await sessions.run(sessionId, (session) => session.repository.checkIndexes()),
+    );
+  } catch (e) {
+    logger.error(`Interlinearizer: failed to check the indexes of session ${sessionId}`, e);
+    throw e;
+  }
+}
+
 /**
  * Returns a summary of every interlinearizer project for the given source project as a JSON string.
  * The WebView deserializes this to populate its project picker and to decide whether to prompt
@@ -1412,6 +1431,23 @@ export async function activate(context: ExecutionActivationContext): Promise<voi
     },
   );
 
+  const checkIndexesCommandRegistration = await papi.commands.registerCommand(
+    'interlinearizer.checkIndexes',
+    checkIndexes,
+    {
+      method: {
+        summary:
+          "Rebuild a session's derived indexes from its records and report where the kept ones differ, for debugging",
+        params: [sessionIdParam],
+        result: {
+          name: 'return value',
+          summary: 'JSON-stringified [{ index, key, missing, extra }]; empty when none differ',
+          schema: { type: 'string' },
+        },
+      },
+    },
+  );
+
   const setPerfMarksCommandRegistration = await papi.commands.registerCommand(
     'interlinearizer.setPerfMarks',
     async (enabled: boolean) => setHostPerfMarks(enabled),
@@ -1787,6 +1823,7 @@ export async function activate(context: ExecutionActivationContext): Promise<voi
     setAnalysisLanguageCommandRegistration,
     undoEditCommandRegistration,
     redoEditCommandRegistration,
+    checkIndexesCommandRegistration,
     setPerfMarksCommandRegistration,
     readPerfCommandRegistration,
     updateProjectMetadataCommandRegistration,
diff --git a/src/services/analysisIndex.ts b/src/services/analysisIndex.ts
new file mode 100644
index 000000000..a611b2915
--- /dev/null
+++ b/src/services/analysisIndex.ts
@@ -0,0 +1,186 @@
+import type {
+  AssignmentStatus,
+  PhraseAnalysis,
+  PhraseAnalysisLink,
+  SegmentAnalysis,
+  SegmentAnalysisLink,
+  TextAnalysis,
+  TokenAnalysis,
+  TokenAnalysisLink,
+} from 'interlinearizer';
+import type { AnalysisLinks, ChangeSet, IndexDifference } from '../types/analysis-repository';
+import { bookOfRef } from '../utils/analysis-book';
+import { normalizeSurfaceForm } from '../utils/analysis-identity';
+import { RecordTable } from './recordTable';
+
+/** The key filing a link by its book and status. */
+function bookStatusKey(bookCode: string, status: AssignmentStatus): string {
+  return `${bookCode}/${status}`;
+}
+
+/** The indexes every kind of link is filed in, given where a link of that kind sits. */
+function linkKeyers<Link extends { analysisId: string; status: AssignmentStatus }>(
+  bookOf: (link: Link) => string,
+) {
+  return {
+    analysisId: (link: Link) => [link.analysisId],
+    book: (link: Link) => [bookOf(link)],
+    bookStatus: (link: Link) => [bookStatusKey(bookOf(link), link.status)],
+  };
+}
+
+const formKeyers = {
+  form: (payload: { surfaceText: string }) => [normalizeSurfaceForm(payload.surfaceText)],
+};
+
+/**
+ * An analysis's records by id, with the derived indexes its lookups answer from. Built from the
+ * records and kept current as changes are applied; the records it hands out are its own.
+ */
+export class AnalysisIndex {
+  private readonly tokenAnalyses: RecordTable<TokenAnalysis, 'form'>;
+
+  private readonly phraseAnalyses: RecordTable<PhraseAnalysis, 'form'>;
+
+  private readonly segmentAnalyses: RecordTable<SegmentAnalysis, never>;
+
+  private readonly tokenLinks: RecordTable<
+    TokenAnalysisLink,
+    'analysisId' | 'book' | 'bookStatus' | 'tokenRef'
+  >;
+
+  private readonly phraseLinks: RecordTable<
+    PhraseAnalysisLink,
+    'analysisId' | 'book' | 'bookStatus' | 'tokenRef'
+  >;
+
+  private readonly segmentLinks: RecordTable<
+    SegmentAnalysisLink,
+    'analysisId' | 'book' | 'bookStatus' | 'segmentId'
+  >;
+
+  constructor(analysis: TextAnalysis) {
+    this.tokenAnalyses = new RecordTable('tokenAnalyses', formKeyers, analysis.tokenAnalyses);
+    this.phraseAnalyses = new RecordTable('phraseAnalyses', formKeyers, analysis.phraseAnalyses);
+    this.segmentAnalyses = new RecordTable('segmentAnalyses', {}, analysis.segmentAnalyses);
+    this.tokenLinks = new RecordTable(
+      'tokenAnalysisLinks',
+      {
+        ...linkKeyers((link: TokenAnalysisLink) => bookOfRef(link.token.tokenRef)),
+        tokenRef: (link) => [link.token.tokenRef],
+      },
+      analysis.tokenAnalysisLinks,
+    );
+    this.phraseLinks = new RecordTable(
+      'phraseAnalysisLinks',
+      {
+        // Every token of a phrase shares a book, so the first one places the whole run.
+        ...linkKeyers((link: PhraseAnalysisLink) => bookOfRef(link.tokens[0].tokenRef)),
+        tokenRef: (link) => link.tokens.map(({ tokenRef }) => tokenRef),
+      },
+      analysis.phraseAnalysisLinks,
+    );
+    this.segmentLinks = new RecordTable(
+      'segmentAnalysisLinks',
+      {
+        ...linkKeyers((link: SegmentAnalysisLink) => bookOfRef(link.segmentId)),
+        segmentId: (link) => [link.segmentId],
+      },
+      analysis.segmentAnalysisLinks,
+    );
+  }
+
+  /** Applies `changes`, whose ids appear at most once in each record kind, taking their records. */
+  apply(changes: ChangeSet): void {
+    this.tokenAnalyses.apply(changes.tokenAnalyses);
+    this.phraseAnalyses.apply(changes.phraseAnalyses);
+    this.segmentAnalyses.apply(changes.segmentAnalyses);
+    this.tokenLinks.apply(changes.tokenAnalysisLinks);
+    this.phraseLinks.apply(changes.phraseAnalysisLinks);
+    this.segmentLinks.apply(changes.segmentAnalysisLinks);
+  }
+
+  /** The token analyses stored under `ids`, each once; an id with none stored is skipped. */
+  getTokenAnalyses(ids: readonly string[]): TokenAnalysis[] {
+    return this.tokenAnalyses.get(ids);
+  }
+
+  /** The phrase analyses stored under `ids`, each once; an id with none stored is skipped. */
+  getPhraseAnalyses(ids: readonly string[]): PhraseAnalysis[] {
+    return this.phraseAnalyses.get(ids);
+  }
+
+  /** The segment analyses stored under `ids`, each once; an id with none stored is skipped. */
+  getSegmentAnalyses(ids: readonly string[]): SegmentAnalysis[] {
+    return this.segmentAnalyses.get(ids);
+  }
+
+  /** The token links on the tokens `tokenRefs` names, and the phrase links touching any of them. */
+  findLinksByToken(
+    tokenRefs: readonly string[],
+  ): Pick<AnalysisLinks, 'tokenAnalysisLinks' | 'phraseAnalysisLinks'> {
+    return {
+      tokenAnalysisLinks: this.tokenLinks.find('tokenRef', tokenRefs),
+      phraseAnalysisLinks: this.phraseLinks.find('tokenRef', tokenRefs),
+    };
+  }
+
+  /** The segment links on the segments `segmentIds` names. */
+  findLinksBySegment(segmentIds: readonly string[]): SegmentAnalysisLink[] {
+    return this.segmentLinks.find('segmentId', segmentIds);
+  }
+
+  /** The links of every kind to the analyses `analysisIds` names. */
+  findLinksToAnalyses(analysisIds: readonly string[]): AnalysisLinks {
+    return {
+      tokenAnalysisLinks: this.tokenLinks.find('analysisId', analysisIds),
+      phraseAnalysisLinks: this.phraseLinks.find('analysisId', analysisIds),
+      segmentAnalysisLinks: this.segmentLinks.find('analysisId', analysisIds),
+    };
+  }
+
+  /** The links into the books `bookCodes` names, of any status when `statuses` is absent. */
+  findLinksInBooks(
+    bookCodes: readonly string[],
+    statuses?: readonly AssignmentStatus[],
+  ): AnalysisLinks {
+    if (!statuses) {
+      return {
+        tokenAnalysisLinks: this.tokenLinks.find('book', bookCodes),
+        phraseAnalysisLinks: this.phraseLinks.find('book', bookCodes),
+        segmentAnalysisLinks: this.segmentLinks.find('book', bookCodes),
+      };
+    }
+    const keys = bookCodes.flatMap((bookCode) =>
+      statuses.map((status) => bookStatusKey(bookCode, status)),
+    );
+    return {
+      tokenAnalysisLinks: this.tokenLinks.find('bookStatus', keys),
+      phraseAnalysisLinks: this.phraseLinks.find('bookStatus', keys),
+      segmentAnalysisLinks: this.segmentLinks.find('bookStatus', keys),
+    };
+  }
+
+  /** The token analyses whose surface text normalizes to one of `normalizedForms`. */
+  findTokenAnalysesByForm(normalizedForms: readonly string[]): TokenAnalysis[] {
+    return this.tokenAnalyses.find('form', normalizedForms);
+  }
+
+  /** The phrase analyses whose surface text normalizes to one of `normalizedForms`. */
+  findPhraseAnalysesByForm(normalizedForms: readonly string[]): PhraseAnalysis[] {
+    return this.phraseAnalyses.find('form', normalizedForms);
+  }
+
+  /** Where this index differs from one built afresh from `analysis`. */
+  differencesFrom(analysis: TextAnalysis): IndexDifference[] {
+    const rebuilt = new AnalysisIndex(analysis);
+    return [
+      ...this.tokenAnalyses.differencesFrom(rebuilt.tokenAnalyses),
+      ...this.phraseAnalyses.differencesFrom(rebuilt.phraseAnalyses),
+      ...this.segmentAnalyses.differencesFrom(rebuilt.segmentAnalyses),
+      ...this.tokenLinks.differencesFrom(rebuilt.tokenLinks),
+      ...this.phraseLinks.differencesFrom(rebuilt.phraseLinks),
+      ...this.segmentLinks.differencesFrom(rebuilt.segmentLinks),
+    ];
+  }
+}
diff --git a/src/services/draftRepository.ts b/src/services/draftRepository.ts
index 6f2f2cf9b..898fe3969 100644
--- a/src/services/draftRepository.ts
+++ b/src/services/draftRepository.ts
@@ -20,7 +20,10 @@ import {
 import { mergeAnalyses, splitAnalysisByBook } from '../utils/analysis-book';
 import { reportAnalysisViolations } from '../utils/analysis-violations';
 import { applyChangeSet } from '../utils/change-set';
+import { jsonCopy } from '../utils/json-copy';
 import { perfTime, perfTimeAsync, perfTimeAsyncExcluding } from '../utils/perf-marks';
+import { AnalysisIndex } from './analysisIndex';
+import { IndexedRepository, type IndexedAnalysis } from './indexedRepository';
 import { draftAnalysisKey, draftJournalKey, draftKey } from './storageKeys';
 
 /**
@@ -104,7 +107,7 @@ type LoadedShard = {
  *
  * Calls on one instance must not overlap.
  */
-export class DraftRepository implements AnalysisRepository {
+export class DraftRepository extends IndexedRepository implements AnalysisRepository {
   readonly capabilities: RepositoryCapabilities = { readOnly: false };
 
   private readonly storage: KeyValueStorage;
@@ -129,12 +132,14 @@ export class DraftRepository implements AnalysisRepository {
   private loaded = false;
 
   /**
-   * The draft as this instance's last apply left it, which the next apply builds on. Dropped by
-   * every load and every whole save, since either may come from a caller holding another draft.
+   * The draft as this instance last applied changes to it or answered a lookup from it, with the
+   * index over its records. Dropped by every load and every whole save, since either may come from
+   * a caller holding another draft.
    */
-  private current: DraftProject | undefined;
+  private current: { draft: DraftProject; index: AnalysisIndex } | undefined;
 
   constructor(storage: KeyValueStorage, sourceProjectId: string, logger: WarningLogger) {
+    super();
     this.storage = storage;
     this.logger = logger;
     this.sourceProjectId = sourceProjectId;
@@ -250,9 +255,10 @@ export class DraftRepository implements AnalysisRepository {
   }
 
   /**
-   * Applies the changes to the draft as this instance's last apply left it, or to the stored draft
-   * when it has made none since its last whole load or save. Only the books whose content the
-   * changes alter are rewritten, so an edit to a payload rewrites every book linking it.
+   * Applies the changes to the draft as this instance last applied changes to it or answered a
+   * lookup from it, or to the stored draft when it has done neither since its last whole load or
+   * save. Only the books whose content the changes alter are rewritten, so an edit to a payload
+   * rewrites every book linking it.
    *
    * @throws {Error} If an id appears more than once in one record kind's changes, or the scope's
    *   record names another source project; nothing is written.
@@ -263,13 +269,36 @@ export class DraftRepository implements AnalysisRepository {
    *   is left as it was.
    */
   async apply(changes: ChangeSet): Promise<ApplyResult> {
-    this.current ??= (await this.exportAll()).draft;
-    const { draft, inverse } = applyChangeSet(this.current, changes);
+    const { draft: base, index } = await this.keptDraft();
+    const copied = jsonCopy(changes);
+    const { draft, inverse } = applyChangeSet(base, copied);
     await this.writeDraft(draft, undefined, { refuseUnreadable: true });
-    this.current = draft;
+    index.apply(copied);
+    this.current = { draft, index };
     return { inverse };
   }
 
+  protected async indexed(): Promise<AnalysisIndex> {
+    return (await this.keptDraft()).index;
+  }
+
+  protected keptIndex(): IndexedAnalysis | undefined {
+    return this.current && { analysis: this.current.draft.analysis, index: this.current.index };
+  }
+
+  /**
+   * The draft this instance keeps, loaded from storage first when it keeps none.
+   *
+   * @throws Whatever {@link exportAll} throws.
+   */
+  private async keptDraft(): Promise<{ draft: DraftProject; index: AnalysisIndex }> {
+    if (!this.current) {
+      const { draft } = await this.exportAll();
+      this.current = { draft, index: new AnalysisIndex(draft.analysis) };
+    }
+    return this.current;
+  }
+
   /**
    * Saves `draft` as {@link replaceAll} describes.
    *
diff --git a/src/services/indexedRepository.ts b/src/services/indexedRepository.ts
new file mode 100644
index 000000000..d8b774446
--- /dev/null
+++ b/src/services/indexedRepository.ts
@@ -0,0 +1,95 @@
+import type {
+  AssignmentStatus,
+  PhraseAnalysis,
+  SegmentAnalysis,
+  SegmentAnalysisLink,
+  TextAnalysis,
+  TokenAnalysis,
+} from 'interlinearizer';
+import type {
+  AnalysisLinks,
+  AnalysisRepository,
+  IndexDifference,
+} from '../types/analysis-repository';
+import { jsonCopy } from '../utils/json-copy';
+import type { AnalysisIndex } from './analysisIndex';
+
+/** An index, with the analysis whose records it is kept over. */
+export type IndexedAnalysis = {
+  analysis: TextAnalysis;
+  index: AnalysisIndex;
+};
+
+/** The lookups of a repository that answers them from an {@link AnalysisIndex} over its records. */
+export abstract class IndexedRepository implements Pick<
+  AnalysisRepository,
+  | 'getTokenAnalyses'
+  | 'getPhraseAnalyses'
+  | 'getSegmentAnalyses'
+  | 'findLinksByToken'
+  | 'findLinksBySegment'
+  | 'findLinksToAnalyses'
+  | 'findLinksInBooks'
+  | 'findTokenAnalysesByForm'
+  | 'findPhraseAnalysesByForm'
+  | 'checkIndexes'
+> {
+  getTokenAnalyses(ids: string[]): Promise<TokenAnalysis[]> {
+    return this.query((index) => index.getTokenAnalyses(ids));
+  }
+
+  getPhraseAnalyses(ids: string[]): Promise<PhraseAnalysis[]> {
+    return this.query((index) => index.getPhraseAnalyses(ids));
+  }
+
+  getSegmentAnalyses(ids: string[]): Promise<SegmentAnalysis[]> {
+    return this.query((index) => index.getSegmentAnalyses(ids));
+  }
+
+  findLinksByToken(
+    tokenRefs: string[],
+  ): Promise<Pick<AnalysisLinks, 'tokenAnalysisLinks' | 'phraseAnalysisLinks'>> {
+    return this.query((index) => index.findLinksByToken(tokenRefs));
+  }
+
+  findLinksBySegment(segmentIds: string[]): Promise<SegmentAnalysisLink[]> {
+    return this.query((index) => index.findLinksBySegment(segmentIds));
+  }
+
+  findLinksToAnalyses(analysisIds: string[]): Promise<AnalysisLinks> {
+    return this.query((index) => index.findLinksToAnalyses(analysisIds));
+  }
+
+  findLinksInBooks(bookCodes: string[], statuses?: AssignmentStatus[]): Promise<AnalysisLinks> {
+    return this.query((index) => index.findLinksInBooks(bookCodes, statuses));
+  }
+
+  findTokenAnalysesByForm(normalizedForms: string[]): Promise<TokenAnalysis[]> {
+    return this.query((index) => index.findTokenAnalysesByForm(normalizedForms));
+  }
+
+  findPhraseAnalysesByForm(normalizedForms: string[]): Promise<PhraseAnalysis[]> {
+    return this.query((index) => index.findPhraseAnalysesByForm(normalizedForms));
+  }
+
+  /** Reports nothing while no index is kept. */
+  async checkIndexes(): Promise<IndexDifference[]> {
+    const kept = this.keptIndex();
+    return kept ? kept.index.differencesFrom(kept.analysis) : [];
+  }
+
+  /** Answers `read` from the kept index, with copies of the records it finds. */
+  private async query<T>(read: (index: AnalysisIndex) => T): Promise<T> {
+    return jsonCopy(read(await this.indexed()));
+  }
+
+  /**
+   * The kept index, built over the stored records first when none is kept.
+   *
+   * @throws Whatever loading the stored records throws.
+   */
+  protected abstract indexed(): Promise<AnalysisIndex>;
+
+  /** The kept index and the analysis it is kept over, or `undefined` when none is kept. */
+  protected abstract keptIndex(): IndexedAnalysis | undefined;
+}
diff --git a/src/services/projectStorage.ts b/src/services/projectStorage.ts
index e6eefe7a3..185bf6ed0 100644
--- a/src/services/projectStorage.ts
+++ b/src/services/projectStorage.ts
@@ -1133,6 +1133,21 @@ export function openDraftRepository(
     replaceAll: (draft, options) => counted((repository) => repository.replaceAll(draft, options)),
     markClean: () => queued((repository) => repository.markClean()),
     apply: (changes) => counted((repository) => repository.apply(changes)),
+    getTokenAnalyses: (ids) => queued((repository) => repository.getTokenAnalyses(ids)),
+    getPhraseAnalyses: (ids) => queued((repository) => repository.getPhraseAnalyses(ids)),
+    getSegmentAnalyses: (ids) => queued((repository) => repository.getSegmentAnalyses(ids)),
+    findLinksByToken: (tokenRefs) => queued((repository) => repository.findLinksByToken(tokenRefs)),
+    findLinksBySegment: (segmentIds) =>
+      queued((repository) => repository.findLinksBySegment(segmentIds)),
+    findLinksToAnalyses: (analysisIds) =>
+      queued((repository) => repository.findLinksToAnalyses(analysisIds)),
+    findLinksInBooks: (bookCodes, statuses) =>
+      queued((repository) => repository.findLinksInBooks(bookCodes, statuses)),
+    findTokenAnalysesByForm: (normalizedForms) =>
+      queued((repository) => repository.findTokenAnalysesByForm(normalizedForms)),
+    findPhraseAnalysesByForm: (normalizedForms) =>
+      queued((repository) => repository.findPhraseAnalysesByForm(normalizedForms)),
+    checkIndexes: () => queued((repository) => repository.checkIndexes()),
   };
 }
 
diff --git a/src/services/pt9ImportRepository.ts b/src/services/pt9ImportRepository.ts
index a8468b5a6..4ef0c3494 100644
--- a/src/services/pt9ImportRepository.ts
+++ b/src/services/pt9ImportRepository.ts
@@ -1,4 +1,4 @@
-import type { InterlinearProject } from 'interlinearizer';
+import type { DraftProject, InterlinearProject } from 'interlinearizer';
 import type {
   AnalysisRepository,
   ApplyResult,
@@ -7,18 +7,23 @@ import type {
 } from '../types/analysis-repository';
 import { CURRENT_MODEL_VERSION } from '../types/model-version';
 import { ReadOnlyAnalysisError } from '../types/read-only-analysis-error';
+import { AnalysisIndex } from './analysisIndex';
+import { IndexedRepository, type IndexedAnalysis } from './indexedRepository';
 
 /**
  * A Paratext 9 import's analysis, read in a draft's shape. Only a sync replaces an import's
  * content, so every write is refused.
  */
-export class Pt9ImportRepository implements AnalysisRepository {
+export class Pt9ImportRepository extends IndexedRepository implements AnalysisRepository {
   readonly capabilities: RepositoryCapabilities = { readOnly: true };
 
   private readonly interlinearProjectId: string;
 
   private readonly readProject: () => Promise<InterlinearProject | undefined>;
 
+  /** The import as a lookup last read it, with the index over its records; dropped by every load. */
+  private loaded: IndexedAnalysis | undefined;
+
   /**
    * @param interlinearProjectId - Id of the project to read, which must be a Paratext 9 import.
    * @param readProject - Reads the project stored under that id afresh, as a new object that the
@@ -28,6 +33,7 @@ export class Pt9ImportRepository implements AnalysisRepository {
     interlinearProjectId: string,
     readProject: () => Promise<InterlinearProject | undefined>,
   ) {
+    super();
     this.interlinearProjectId = interlinearProjectId;
     this.readProject = readProject;
   }
@@ -41,25 +47,8 @@ export class Pt9ImportRepository implements AnalysisRepository {
    * @throws Whatever reading the project throws.
    */
   async exportAll(): Promise<DraftExport> {
-    const project = await this.readProject();
-    if (!project?.pt9Import) {
-      throw new Error(
-        `Interlinearizer: no Paratext 9 import is stored as project ${this.interlinearProjectId}`,
-      );
-    }
-    const { sourceProjectId, analysisLanguages, targetProjectId, analysis, segmentation } = project;
-    return {
-      draft: {
-        sourceProjectId,
-        modelVersion: CURRENT_MODEL_VERSION,
-        analysisLanguages,
-        ...(targetProjectId !== undefined && { targetProjectId }),
-        analysis,
-        dirty: false,
-        ...(segmentation !== undefined && { segmentation }),
-      },
-      unreadableBooks: [],
-    };
+    this.loaded = undefined;
+    return { draft: await this.readImport(), unreadableBooks: [] };
   }
 
   /**
@@ -86,6 +75,42 @@ export class Pt9ImportRepository implements AnalysisRepository {
     throw this.readOnlyError();
   }
 
+  protected async indexed(): Promise<AnalysisIndex> {
+    if (!this.loaded) {
+      const { analysis } = await this.readImport();
+      this.loaded = { analysis, index: new AnalysisIndex(analysis) };
+    }
+    return this.loaded.index;
+  }
+
+  protected keptIndex(): IndexedAnalysis | undefined {
+    return this.loaded;
+  }
+
+  /**
+   * Reads the import as {@link exportAll} describes.
+   *
+   * @throws Whatever {@link exportAll} throws.
+   */
+  private async readImport(): Promise<DraftProject> {
+    const project = await this.readProject();
+    if (!project?.pt9Import) {
+      throw new Error(
+        `Interlinearizer: no Paratext 9 import is stored as project ${this.interlinearProjectId}`,
+      );
+    }
+    const { sourceProjectId, analysisLanguages, targetProjectId, analysis, segmentation } = project;
+    return {
+      sourceProjectId,
+      modelVersion: CURRENT_MODEL_VERSION,
+      analysisLanguages,
+      ...(targetProjectId !== undefined && { targetProjectId }),
+      analysis,
+      dirty: false,
+      ...(segmentation !== undefined && { segmentation }),
+    };
+  }
+
   private readOnlyError(): ReadOnlyAnalysisError {
     return new ReadOnlyAnalysisError(
       `Interlinearizer: Paratext 9 import ${this.interlinearProjectId} is read-only`,
diff --git a/src/services/recordTable.ts b/src/services/recordTable.ts
new file mode 100644
index 000000000..0878bec01
--- /dev/null
+++ b/src/services/recordTable.ts
@@ -0,0 +1,122 @@
+import type { IndexDifference, RecordChanges } from '../types/analysis-repository';
+
+/** The keys a derived index files a record under. */
+export type KeysOf<T> = (record: T) => readonly string[];
+
+/** Ids filed under keys. */
+type IdsByKey = Map<string, Set<string>>;
+
+function fileId(index: IdsByKey, key: string, id: string): void {
+  const ids = index.get(key);
+  if (ids) ids.add(id);
+  else index.set(key, new Set([id]));
+}
+
+function unfileId(index: IdsByKey, key: string, id: string): void {
+  const ids = index.get(key);
+  /* v8 ignore next -- a record's keys were filed when it was put */
+  if (!ids) return;
+  ids.delete(id);
+  if (ids.size === 0) index.delete(key);
+}
+
+/** The ids in `a` that `b` lacks. */
+function idsLacking(a: ReadonlySet<string> | undefined, b: ReadonlySet<string> | undefined) {
+  return [...(a ?? [])].filter((id) => !b?.has(id));
+}
+
+/** One record kind's records by id, with the derived indexes kept over them. */
+export class RecordTable<T extends { id: string }, Index extends string> {
+  private readonly kind: string;
+
+  private readonly keyers: Record<Index, KeysOf<T>>;
+
+  private readonly records = new Map<string, T>();
+
+  private readonly indexes = new Map<Index, IdsByKey>();
+
+  constructor(kind: string, keyers: Record<Index, KeysOf<T>>, records: readonly T[]) {
+    this.kind = kind;
+    this.keyers = keyers;
+    this.indexNames().forEach((index) => this.indexes.set(index, new Map()));
+    records.forEach((record) => this.put(record));
+  }
+
+  /** The records stored under `ids`, each once. */
+  get(ids: readonly string[]): T[] {
+    return [...new Set(ids)].flatMap((id) => this.records.get(id) ?? []);
+  }
+
+  /** The records `index` files under any of `keys`, each once. */
+  find(index: Index, keys: readonly string[]): T[] {
+    const filed = this.filed(index);
+    const ids = new Set(keys.flatMap((key) => [...(filed.get(key) ?? [])]));
+    return this.get([...ids]);
+  }
+
+  /** Applies one record kind's puts and deletes; absent changes apply nothing. */
+  apply(changes: RecordChanges<T> | undefined): void {
+    changes?.puts.forEach((record) => this.put(record));
+    changes?.deletes.forEach((id) => this.remove(id));
+  }
+
+  /**
+   * Where this table differs from `rebuilt`, a table of the same kind built afresh. A record whose
+   * kept copy differs from the rebuilt one is both missing and extra.
+   */
+  differencesFrom(rebuilt: RecordTable<T, Index>): IndexDifference[] {
+    const ids = new Set([...this.records.keys(), ...rebuilt.records.keys()]);
+    const recordDifferences = [...ids].flatMap((id): IndexDifference[] => {
+      const kept = this.records.get(id);
+      const stored = rebuilt.records.get(id);
+      if (JSON.stringify(kept) === JSON.stringify(stored)) return [];
+      return [{ index: this.kind, key: id, missing: stored ? [id] : [], extra: kept ? [id] : [] }];
+    });
+    const indexDifferences = this.indexNames().flatMap((index) => {
+      const kept = this.filed(index);
+      const fresh = rebuilt.filed(index);
+      const keys = new Set([...kept.keys(), ...fresh.keys()]);
+      return [...keys].flatMap((key): IndexDifference[] => {
+        const missing = idsLacking(fresh.get(key), kept.get(key));
+        const extra = idsLacking(kept.get(key), fresh.get(key));
+        if (missing.length === 0 && extra.length === 0) return [];
+        return [{ index: `${this.kind} by ${index}`, key, missing, extra }];
+      });
+    });
+    return [...recordDifferences, ...indexDifferences];
+  }
+
+  private indexNames(): Index[] {
+    // Object.keys widens to string[]; the keys are exactly the keyers' index names.
+    return Object.keys(this.keyers).filter((name): name is Index => name in this.keyers);
+  }
+
+  private filed(index: Index): IdsByKey {
+    const filed = this.indexes.get(index);
+    /* v8 ignore next -- the constructor gives every index its map */
+    if (!filed) throw new Error(`Interlinearizer: ${this.kind} has no index by ${index}`);
+    return filed;
+  }
+
+  /** The keys `index` files `record` under, each once. */
+  private keysOf(index: Index, record: T): Set<string> {
+    return new Set(this.keyers[index](record));
+  }
+
+  private put(record: T): void {
+    this.remove(record.id);
+    this.records.set(record.id, record);
+    this.indexNames().forEach((index) =>
+      this.keysOf(index, record).forEach((key) => fileId(this.filed(index), key, record.id)),
+    );
+  }
+
+  private remove(id: string): void {
+    const record = this.records.get(id);
+    if (!record) return;
+    this.records.delete(id);
+    this.indexNames().forEach((index) =>
+      this.keysOf(index, record).forEach((key) => unfileId(this.filed(index), key, id)),
+    );
+  }
+}
diff --git a/src/types/analysis-repository.ts b/src/types/analysis-repository.ts
index 848f60163..fc198ebe3 100644
--- a/src/types/analysis-repository.ts
+++ b/src/types/analysis-repository.ts
@@ -1,4 +1,12 @@
-import type { DraftProject, TextAnalysis } from 'interlinearizer';
+import type {
+  AssignmentStatus,
+  DraftProject,
+  PhraseAnalysis,
+  SegmentAnalysis,
+  SegmentAnalysisLink,
+  TextAnalysis,
+  TokenAnalysis,
+} from 'interlinearizer';
 
 /** Text records by key. */
 export interface KeyValueStorage {
@@ -89,12 +97,29 @@ export type ApplyResult = {
   inverse: ChangeSet;
 };
 
+/** Links of every kind, one list per kind. */
+export type AnalysisLinks = Pick<
+  TextAnalysis,
+  'tokenAnalysisLinks' | 'phraseAnalysisLinks' | 'segmentAnalysisLinks'
+>;
+
+/** Where a derived index a repository keeps differs from one rebuilt from its records. */
+export type IndexDifference = {
+  index: string;
+  /** The key whose entries differ. */
+  key: string;
+  /** Ids the rebuilt index files under the key that the kept one lacks. */
+  missing: string[];
+  /** Ids the kept index files under the key that the rebuilt one lacks. */
+  extra: string[];
+};
+
 /**
  * Reads and writes one source project's draft, or, when read-only, reads analysis in a draft's
  * shape. Every call is async and takes and returns only JSON-plain values, so an implementation may
  * sit behind a network boundary or another language. Once a call settles, the caller may change a
- * draft it passed in or got back without changing what is stored. Lists of records come back in no
- * promised order.
+ * draft or records it passed in or got back without changing what is stored. Lists of records come
+ * back in no promised order, and a lookup by several keys returns each record once.
  *
  * Calls for one draft must not overlap, whether on one repository or several. After one repository
  * saves a draft, any other that had already loaded or saved it must load it again before its next
@@ -171,4 +196,42 @@ export interface AnalysisRepository {
    *   unchanged, though storage may hold some of the changes until a later save.
    */
   apply(changes: ChangeSet): Promise<ApplyResult>;
+
+  /** The token analyses stored under `ids`; an id with none stored under it is skipped. */
+  getTokenAnalyses(ids: string[]): Promise<TokenAnalysis[]>;
+
+  /** The phrase analyses stored under `ids`; an id with none stored under it is skipped. */
+  getPhraseAnalyses(ids: string[]): Promise<PhraseAnalysis[]>;
+
+  /** The segment analyses stored under `ids`; an id with none stored under it is skipped. */
+  getSegmentAnalyses(ids: string[]): Promise<SegmentAnalysis[]>;
+
+  /** The token links on the tokens `tokenRefs` names, and the phrase links touching any of them. */
+  findLinksByToken(
+    tokenRefs: string[],
+  ): Promise<Pick<AnalysisLinks, 'tokenAnalysisLinks' | 'phraseAnalysisLinks'>>;
+
+  /** The segment links on the segments `segmentIds` names. */
+  findLinksBySegment(segmentIds: string[]): Promise<SegmentAnalysisLink[]>;
+
+  /** The links of every kind to the analyses `analysisIds` names. */
+  findLinksToAnalyses(analysisIds: string[]): Promise<AnalysisLinks>;
+
+  /**
+   * The links of every kind into the books `bookCodes` names, of any status when `statuses` is
+   * absent.
+   */
+  findLinksInBooks(bookCodes: string[], statuses?: AssignmentStatus[]): Promise<AnalysisLinks>;
+
+  /** The token analyses whose surface text normalizes to one of `normalizedForms`. */
+  findTokenAnalysesByForm(normalizedForms: string[]): Promise<TokenAnalysis[]>;
+
+  /** The phrase analyses whose surface text normalizes to one of `normalizedForms`. */
+  findPhraseAnalysesByForm(normalizedForms: string[]): Promise<PhraseAnalysis[]>;
+
+  /**
+   * Rebuilds the derived indexes the repository keeps from its records and reports where the kept
+   * ones differ, for debugging. A repository keeping none reports nothing.
+   */
+  checkIndexes(): Promise<IndexDifference[]>;
 }
diff --git a/src/types/interlinearizer.d.ts b/src/types/interlinearizer.d.ts
index 06ab18d47..b7be3e07c 100644
--- a/src/types/interlinearizer.d.ts
+++ b/src/types/interlinearizer.d.ts
@@ -381,6 +381,15 @@ declare module 'papi-shared-types' {
      */
     'interlinearizer.redoEdit': (sessionId: string) => Promise<string | undefined>;
 
+    /**
+     * Rebuilds a session's derived indexes from its records and reports where the kept ones differ,
+     * for debugging.
+     *
+     * @returns A JSON string of `[{ index, key, missing, extra }]`, empty when none differ.
+     * @throws If the session is not open, or its records cannot be read (logged before rethrowing).
+     */
+    'interlinearizer.checkIndexes': (sessionId: string) => Promise<string>;
+
     /**
      * Turns the extension host's timing entries on or off, discarding any it holds. Off until
      * turned on.
diff --git a/src/utils/change-set.ts b/src/utils/change-set.ts
index e28124d9a..d90e176fc 100644
--- a/src/utils/change-set.ts
+++ b/src/utils/change-set.ts
@@ -7,11 +7,6 @@ export type AppliedChanges = {
   inverse: ChangeSet;
 };
 
-/** A copy of a JSON-plain value that shares nothing with it. */
-function copyOf<T>(value: T): T {
-  return JSON.parse(JSON.stringify(value));
-}
-
 /** The draft's record, without its analysis or its `dirty` flag. */
 // eslint-disable-next-line @typescript-eslint/no-unused-vars -- named only to leave them out
 export function scopeRecordOf({ analysis, dirty, ...scope }: DraftProject): ScopeRecord {
@@ -41,7 +36,7 @@ function applyRecordChanges<T extends { id: string }>(
 
   const stored = new Map(records.map((record) => [record.id, record]));
   const deleted = new Set(changes.deletes);
-  const puts = new Map(changes.puts.map((record) => [record.id, copyOf(record)]));
+  const puts = new Map(changes.puts.map((record) => [record.id, record]));
   const inverse: RecordChanges<T> = { puts: [], deletes: [] };
   changes.puts.forEach(({ id }) => {
     const prior = stored.get(id);
@@ -68,8 +63,8 @@ function applyRecordChanges<T extends { id: string }>(
 }
 
 /**
- * Applies `changes` to `draft`, leaving `draft` as it was. The result is marked unsaved. It holds
- * copies of the records the changes put, and shares everything else with `draft`, the records the
+ * Applies `changes` to `draft`, leaving `draft` as it was. The result is marked unsaved. It shares
+ * the records the changes put with `changes`, and everything else with `draft`, the records the
  * inverse restores included.
  *
  * @throws {Error} If an id appears more than once in one record kind's changes, or the scope's
@@ -125,7 +120,7 @@ export function applyChangeSet(draft: DraftProject, changes: ChangeSet): Applied
   };
   return {
     draft: {
-      ...(changes.scope ? copyOf(changes.scope) : scopeRecordOf(draft)),
+      ...(changes.scope ?? scopeRecordOf(draft)),
       dirty: true,
       analysis: {
         segmentAnalyses: segmentAnalyses.records,
diff --git a/src/utils/json-copy.ts b/src/utils/json-copy.ts
new file mode 100644
index 000000000..eb6d43879
--- /dev/null
+++ b/src/utils/json-copy.ts
@@ -0,0 +1,4 @@
+/** A deep copy of a JSON-plain value, sharing nothing with it. */
+export function jsonCopy<T>(value: T): T {
+  return JSON.parse(JSON.stringify(value));
+}

From 9d5b5ef72fa05efb11e85a6f2721229e07b1d2c4 Mon Sep 17 00:00:00 2001
From: Alex Rawlings <alex.rawlings@wycliffe.ca>
Date: Fri, 23 Oct 2026 13:01:27 -0600
Subject: [PATCH 13/22] Add token commands with parity tests (#443)

---
 AGENTS.md                                     |   2 +
 .../analysis-repository-conformance.ts        |  21 +
 src/__tests__/main.test.ts                    |  58 ++
 .../services/analysisSessions.test.ts         |  81 +++
 .../services/commands/approvalRule.test.ts    |  92 +++
 .../services/commands/changeBuffer.test.ts    | 192 ++++++
 src/__tests__/services/commands/parity.ts     |  75 +++
 .../commands/tokenCommands.parity.test.ts     | 548 ++++++++++++++++++
 .../services/commands/tokenCommands.test.ts   |  92 +++
 .../services/indexedRepository.test.ts        |  31 +-
 src/__tests__/services/projectStorage.test.ts |   5 +
 src/__tests__/utils/change-set.test.ts        |  18 +-
 .../utils/token-analysis-content.test.ts      |  59 ++
 src/main.ts                                   | 144 ++++-
 src/services/analysisSessions.ts              |  30 +
 src/services/commands/approvalRule.ts         |  69 +++
 src/services/commands/changeBuffer.ts         | 214 +++++++
 src/services/commands/tokenCommands.ts        | 291 ++++++++++
 src/services/draftRepository.ts               |  26 +-
 src/services/indexedRepository.ts             |  29 +-
 src/services/projectStorage.ts                |   1 +
 src/services/pt9ImportRepository.ts           |  15 +-
 src/store/analysisSlice.ts                    |  41 +-
 src/types/analysis-repository.ts              |   7 +
 src/types/interlinearizer.d.ts                |  28 +
 src/utils/change-set.ts                       |   5 +
 src/utils/token-analysis-content.ts           |  42 ++
 27 files changed, 2129 insertions(+), 87 deletions(-)
 create mode 100644 src/__tests__/services/commands/approvalRule.test.ts
 create mode 100644 src/__tests__/services/commands/changeBuffer.test.ts
 create mode 100644 src/__tests__/services/commands/parity.ts
 create mode 100644 src/__tests__/services/commands/tokenCommands.parity.test.ts
 create mode 100644 src/__tests__/services/commands/tokenCommands.test.ts
 create mode 100644 src/__tests__/utils/token-analysis-content.test.ts
 create mode 100644 src/services/commands/approvalRule.ts
 create mode 100644 src/services/commands/changeBuffer.ts
 create mode 100644 src/services/commands/tokenCommands.ts
 create mode 100644 src/utils/token-analysis-content.ts

diff --git a/AGENTS.md b/AGENTS.md
index 435e6c976..9cb9c55dd 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -87,6 +87,8 @@ Saved projects are listed through [ProjectSummaries](src/services/projectSummari
 
 [AnalysisSessions](src/services/analysisSessions.ts) keeps the host's sessions, behind the `openSession`, `closeSession` and `setAnalysisLanguage` commands. A session is a handle on one source project's draft, paired with the interlinear project it saves to, or on a Paratext 9 import alone, read-only. A source has at most one session: opening another closes it. Each session runs its commands one at a time, through `run`, or `runEdit` for a command that changes stored analysis, which a read-only session refuses. An edit reaches the repository as a `ChangeSet` of whole-record puts and deletes, applied through the session's [EditHistory](src/services/editHistory.ts) so that undo can revert it; boundary changes ride in the change set's scope record. The WebView doesn't use sessions yet.
 
+Host commands live in [src/services/commands/](src/services/commands/), one module per family. A command stages its changes in a [ChangeBuffer](src/services/commands/changeBuffer.ts), whose reads answer as the repository will once those changes apply, and `AnalysisSessions.edit` applies what it staged as one undo step after the approval rule passes. Each command copies the reducer it replaces, step for step, and its parity tests run one input through both with [runParity](src/__tests__/services/commands/parity.ts); a reducer change in Phase 3 updates its command and parity tests in the same PR.
+
 ### 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/src/__tests__/analysis-repository-conformance.ts b/src/__tests__/analysis-repository-conformance.ts
index e938a7abc..58e157891 100644
--- a/src/__tests__/analysis-repository-conformance.ts
+++ b/src/__tests__/analysis-repository-conformance.ts
@@ -1226,6 +1226,27 @@ export function describeAnalysisRepositoryConformance(
         return store.open(SOURCE);
       }
 
+      it("reads the draft's own record", async () => {
+        const repository = await overFullDraft();
+
+        await expect(repository.getScope()).resolves.toStrictEqual(scopeRecordOf(fullDraft()));
+      });
+
+      it("reads the record of a draft never saved as an empty draft's", async () => {
+        await expect((await store.open(SOURCE)).getScope()).resolves.toStrictEqual(
+          scopeRecordOf(emptyDraft(SOURCE)),
+        );
+      });
+
+      it('reads the record the applied changes leave', async () => {
+        const repository = await overFullDraft();
+        const scope = { ...scopeRecordOf(fullDraft()), analysisLanguages: ['de'] };
+
+        await repository.apply({ intent: 'rescope', scope });
+
+        await expect(repository.getScope()).resolves.toStrictEqual(scope);
+      });
+
       it('gets each payload kind by id, once per id, skipping ids with nothing stored', async () => {
         const repository = await overFullDraft();
 
diff --git a/src/__tests__/main.test.ts b/src/__tests__/main.test.ts
index b24169bbe..7973e5b8d 100644
--- a/src/__tests__/main.test.ts
+++ b/src/__tests__/main.test.ts
@@ -12,6 +12,7 @@ import * as projectStorage from '../services/projectStorage';
 import * as pt9ImportService from '../services/pt9ImportService';
 import { type AnalysisRepository, UnreadableBooksError } from '../types/analysis-repository';
 import { emptyDraft } from '../types/empty-factories';
+import { scopeRecordOf } from '../utils/change-set';
 import { toProjectSummary } from '../types/interlinear-project-summary';
 import { createTestActivationContext, makeStubProject } from './test-helpers';
 
@@ -401,6 +402,8 @@ describe('main', () => {
           'interlinearizer.undoEdit',
           'interlinearizer.redoEdit',
           'interlinearizer.checkIndexes',
+          'interlinearizer.writeGloss',
+          'interlinearizer.approveAnalysisForToken',
           'interlinearizer.openSelectProjectModal',
           'interlinearizer.openNewProjectModal',
           'interlinearizer.openProjectInfoModal',
@@ -1848,6 +1851,7 @@ describe('main', () => {
         checkIndexes: async () => [
           { index: 'tokenAnalyses', key: 'ta-1', missing: ['ta-1'], extra: [] },
         ],
+        getScope: async () => scopeRecordOf(draft),
       };
     }
 
@@ -1877,6 +1881,22 @@ describe('main', () => {
         checkIndexes: handler<(sessionId: string) => Promise<string>>(
           'interlinearizer.checkIndexes',
         ),
+        writeGloss: handler<
+          (
+            sessionId: string,
+            tokenRef: string,
+            surfaceText: string,
+            value: string,
+          ) => Promise<string>
+        >('interlinearizer.writeGloss'),
+        approveAnalysisForToken: handler<
+          (
+            sessionId: string,
+            tokenRef: string,
+            surfaceText: string,
+            analysisId: string,
+          ) => Promise<string>
+        >('interlinearizer.approveAnalysisForToken'),
       };
     }
 
@@ -2060,6 +2080,44 @@ describe('main', () => {
       );
     });
 
+    it("writes a token's gloss in the session's language, replying with the changes", async () => {
+      const { openSession, setAnalysisLanguage, writeGloss } = await activateSessionCommands();
+      const { sessionId } = JSON.parse(await openSession('src-project'));
+      await setAnalysisLanguage(sessionId, 'fr');
+
+      const changes = JSON.parse(await writeGloss(sessionId, 'GEN 1:1:0', 'In', 'au'));
+
+      expect(changes).toMatchObject({
+        intent: 'writeGloss',
+        tokenAnalyses: { puts: [{ surfaceText: 'In', gloss: { fr: 'au' } }], deletes: [] },
+        tokenAnalysisLinks: {
+          puts: [{ status: 'approved', token: { tokenRef: 'GEN 1:1:0', surfaceText: 'In' } }],
+          deletes: [],
+        },
+      });
+    });
+
+    it('logs the error and rethrows when an edit fails', async () => {
+      const { writeGloss } = await activateSessionCommands();
+
+      await expect(writeGloss('not-a-session', 'GEN 1:1:0', 'In', 'at')).rejects.toThrow(
+        'no session not-a-session is open',
+      );
+      expect(__mockLogger.error).toHaveBeenCalledWith(
+        'Interlinearizer: failed to writeGloss in session not-a-session',
+        expect.any(Error),
+      );
+    });
+
+    it('approves an analysis for a token, replying with the changes', async () => {
+      const { openSession, approveAnalysisForToken } = await activateSessionCommands();
+      const { sessionId } = JSON.parse(await openSession('src-project'));
+
+      await expect(
+        approveAnalysisForToken(sessionId, 'GEN 1:1:0', 'In', 'ta-unknown').then(JSON.parse),
+      ).resolves.toStrictEqual({ intent: 'approveAnalysisForToken' });
+    });
+
     it('closes every session on deactivation', async () => {
       const { openSession } = await activateSessionCommands();
       await openSession('src-project');
diff --git a/src/__tests__/services/analysisSessions.test.ts b/src/__tests__/services/analysisSessions.test.ts
index 0d5688c03..8f3be5cb3 100644
--- a/src/__tests__/services/analysisSessions.test.ts
+++ b/src/__tests__/services/analysisSessions.test.ts
@@ -6,6 +6,7 @@ import {
   type SessionHost,
   UNDETERMINED_LANGUAGE,
 } from '../../services/analysisSessions';
+import { ApprovalRuleError } from '../../services/commands/approvalRule';
 import { DraftRepository } from '../../services/draftRepository';
 import { Pt9ImportRepository } from '../../services/pt9ImportRepository';
 import { draftKey } from '../../services/storageKeys';
@@ -473,6 +474,86 @@ describe('AnalysisSessions', () => {
     });
   });
 
+  describe('edit', () => {
+    const payload = (id: string) => ({ id, ...FIXTURE_STAMPS, surfaceText: id });
+    const approvedLink = (id: string) => ({
+      id,
+      analysisId: 'a',
+      ...FIXTURE_STAMPS,
+      status: 'approved' as const,
+      token: { tokenRef: 'GEN 1:1:0', surfaceText: 'a' },
+    });
+
+    /** The source project's draft as stored. */
+    const stored = async (storage: ReturnType<typeof makeSessions>['storage']) =>
+      (await new DraftRepository(storage, SOURCE, silentLogger()).exportAll()).draft;
+
+    it('applies what the command stages as one undo step, marking the draft dirty', async () => {
+      const { sessions, storage } = makeSessions();
+      const { sessionId } = await sessions.open(SOURCE);
+
+      const changes = await sessions.edit(sessionId, 'add', async (buffer) => {
+        buffer.create('tokenAnalyses', payload('a'));
+        buffer.create('tokenAnalyses', payload('b'));
+      });
+
+      expect(changes).toMatchObject({ intent: 'add' });
+      await expect(stored(storage)).resolves.toMatchObject({
+        dirty: true,
+        analysis: { tokenAnalyses: [payload('a'), payload('b')] },
+      });
+      await sessions.undo(sessionId);
+      await expect(stored(storage)).resolves.toMatchObject({ analysis: { tokenAnalyses: [] } });
+    });
+
+    it('applies nothing, and records no undo step, for a command staging nothing', async () => {
+      const { sessions, storage } = makeSessions();
+      const { sessionId } = await sessions.open(SOURCE);
+
+      await expect(sessions.edit(sessionId, 'nothing', async () => {})).resolves.toStrictEqual({
+        intent: 'nothing',
+      });
+
+      await expect(sessions.undo(sessionId)).resolves.toBeUndefined();
+      await expect(stored(storage)).resolves.toMatchObject({ dirty: false });
+    });
+
+    it('gives the command the session it runs on', async () => {
+      const { sessions } = makeSessions();
+      const { sessionId } = await sessions.open(SOURCE);
+      await sessions.setAnalysisLanguage(sessionId, 'fr');
+
+      await sessions.edit(sessionId, 'read', async (_buffer, session) => {
+        expect(session.analysisLanguage).toBe('fr');
+      });
+    });
+
+    it('refuses changes that would approve a second analysis for a token, applying nothing', async () => {
+      const { sessions, storage } = makeSessions();
+      const { sessionId } = await sessions.open(SOURCE);
+
+      await expect(
+        sessions.edit(sessionId, 'approveTwice', async (buffer) => {
+          buffer.create('tokenAnalysisLinks', approvedLink('l-1'));
+          buffer.create('tokenAnalysisLinks', approvedLink('l-2'));
+        }),
+      ).rejects.toThrow(ApprovalRuleError);
+
+      await expect(stored(storage)).resolves.toMatchObject({
+        analysis: { tokenAnalysisLinks: [] },
+      });
+    });
+
+    it("refuses an edit on a Paratext 9 import's session without running it", async () => {
+      const { sessions } = makeSessions([makeImport()]);
+      const { sessionId } = await sessions.open(SOURCE, 'import-id');
+      const command = jest.fn(async () => {});
+
+      await expect(sessions.edit(sessionId, 'add', command)).rejects.toThrow(ReadOnlyAnalysisError);
+      expect(command).not.toHaveBeenCalled();
+    });
+  });
+
   describe('setAnalysisLanguage', () => {
     it('sets the language the commands sent after it read', async () => {
       const { sessions } = makeSessions();
diff --git a/src/__tests__/services/commands/approvalRule.test.ts b/src/__tests__/services/commands/approvalRule.test.ts
new file mode 100644
index 000000000..3c37315dd
--- /dev/null
+++ b/src/__tests__/services/commands/approvalRule.test.ts
@@ -0,0 +1,92 @@
+/// <reference types="jest" />
+
+import type { SegmentAnalysisLink, TextAnalysis, TokenAnalysisLink } from 'interlinearizer';
+import { ApprovalRuleError, assertApprovalRule } from '../../../services/commands/approvalRule';
+import { ChangeBuffer } from '../../../services/commands/changeBuffer';
+import { DraftRepository } from '../../../services/draftRepository';
+import { emptyAnalysis, emptyDraft } from '../../../types/empty-factories';
+import { FIXTURE_STAMPS, memoryStorage, silentLogger } from '../../test-helpers';
+
+function tokenLink(
+  id: string,
+  status: TokenAnalysisLink['status'] = 'approved',
+): TokenAnalysisLink {
+  return {
+    id,
+    analysisId: `ta-${id}`,
+    ...FIXTURE_STAMPS,
+    status,
+    token: { tokenRef: 'GEN 1:1:0', surfaceText: 'In' },
+  };
+}
+
+function segmentLink(id: string): SegmentAnalysisLink {
+  return {
+    id,
+    analysisId: `sa-${id}`,
+    ...FIXTURE_STAMPS,
+    status: 'approved',
+    segmentId: 'GEN 1:1',
+  };
+}
+
+async function over(analysis: Partial<TextAnalysis>) {
+  const { storage } = memoryStorage();
+  const repository = new DraftRepository(storage, 'src', silentLogger());
+  await repository.replaceAll({
+    ...emptyDraft('src'),
+    analysis: { ...emptyAnalysis(), ...analysis },
+  });
+  return { repository, buffer: new ChangeBuffer(repository) };
+}
+
+describe('assertApprovalRule', () => {
+  it('accepts changes that leave each token one approval', async () => {
+    const { repository, buffer } = await over({ tokenAnalysisLinks: [tokenLink('a')] });
+
+    buffer.delete('tokenAnalysisLinks', tokenLink('a'));
+    buffer.create('tokenAnalysisLinks', tokenLink('b'));
+
+    await expect(assertApprovalRule(buffer, repository)).resolves.toBeUndefined();
+  });
+
+  it('refuses a second approval for a token', async () => {
+    const { repository, buffer } = await over({ tokenAnalysisLinks: [tokenLink('a')] });
+
+    buffer.create('tokenAnalysisLinks', tokenLink('b'));
+
+    await expect(assertApprovalRule(buffer, repository)).rejects.toThrow(
+      new ApprovalRuleError(['GEN 1:1:0']),
+    );
+  });
+
+  it('refuses a second approval for a segment', async () => {
+    const { repository, buffer } = await over({ segmentAnalysisLinks: [segmentLink('a')] });
+
+    buffer.create('segmentAnalysisLinks', segmentLink('b'));
+
+    await expect(assertApprovalRule(buffer, repository)).rejects.toThrow(ApprovalRuleError);
+  });
+
+  it('accepts changes that leave a stored breach no worse', async () => {
+    const { repository, buffer } = await over({
+      tokenAnalysisLinks: [tokenLink('a'), tokenLink('b'), tokenLink('c', 'suggested')],
+    });
+
+    buffer.put('tokenAnalysisLinks', { ...tokenLink('a'), updatedAt: '2026-06-01T00:00:00.000Z' });
+    buffer.put('tokenAnalysisLinks', tokenLink('c', 'rejected'));
+
+    await expect(assertApprovalRule(buffer, repository)).resolves.toBeUndefined();
+  });
+
+  it('names the places it refuses on the error', async () => {
+    const { repository, buffer } = await over({});
+
+    buffer.create('tokenAnalysisLinks', tokenLink('a'));
+    buffer.create('tokenAnalysisLinks', tokenLink('b'));
+
+    await expect(assertApprovalRule(buffer, repository)).rejects.toMatchObject({
+      places: ['GEN 1:1:0'],
+    });
+  });
+});
diff --git a/src/__tests__/services/commands/changeBuffer.test.ts b/src/__tests__/services/commands/changeBuffer.test.ts
new file mode 100644
index 000000000..b6862527b
--- /dev/null
+++ b/src/__tests__/services/commands/changeBuffer.test.ts
@@ -0,0 +1,192 @@
+/// <reference types="jest" />
+
+import type { TextAnalysis, TokenAnalysis, TokenAnalysisLink } from 'interlinearizer';
+import { ChangeBuffer } from '../../../services/commands/changeBuffer';
+import { DraftRepository } from '../../../services/draftRepository';
+import { emptyAnalysis, emptyDraft } from '../../../types/empty-factories';
+import { FIXTURE_STAMPS, makePhraseLink, memoryStorage, silentLogger } from '../../test-helpers';
+
+function payload(id: string, surfaceText = id): TokenAnalysis {
+  return { id, ...FIXTURE_STAMPS, surfaceText };
+}
+
+function link(id: string, analysisId: string, tokenRef: string): TokenAnalysisLink {
+  return {
+    id,
+    analysisId,
+    ...FIXTURE_STAMPS,
+    status: 'approved',
+    token: { tokenRef, surfaceText: 'In' },
+  };
+}
+
+/** A buffer over a draft holding `analysis`. */
+async function bufferOver(analysis: Partial<TextAnalysis> = {}): Promise<ChangeBuffer> {
+  const { storage } = memoryStorage();
+  const repository = new DraftRepository(storage, 'src', silentLogger());
+  await repository.replaceAll({
+    ...emptyDraft('src'),
+    analysis: { ...emptyAnalysis(), ...analysis },
+  });
+  return new ChangeBuffer(repository);
+}
+
+const ids = (records: readonly { id: string }[]) => records.map(({ id }) => id).sort();
+
+describe('ChangeBuffer', () => {
+  it('reads stored records as the repository does while nothing is staged', async () => {
+    const buffer = await bufferOver({
+      tokenAnalyses: [payload('ta-1')],
+      tokenAnalysisLinks: [link('tl-1', 'ta-1', 'GEN 1:1:0')],
+    });
+
+    await expect(buffer.getTokenAnalyses(['ta-1'])).resolves.toStrictEqual([payload('ta-1')]);
+    await expect(buffer.findLinksToAnalyses(['ta-1'])).resolves.toStrictEqual({
+      tokenAnalysisLinks: [link('tl-1', 'ta-1', 'GEN 1:1:0')],
+      phraseAnalysisLinks: [],
+      segmentAnalysisLinks: [],
+    });
+  });
+
+  it('answers with a staged put in place of the stored record', async () => {
+    const buffer = await bufferOver({ tokenAnalyses: [payload('ta-1')] });
+
+    buffer.put('tokenAnalyses', { ...payload('ta-1'), gloss: { en: 'one' } });
+
+    await expect(buffer.getTokenAnalyses(['ta-1'])).resolves.toStrictEqual([
+      { ...payload('ta-1'), gloss: { en: 'one' } },
+    ]);
+  });
+
+  it('leaves a staged removal out of every read', async () => {
+    const stored = link('tl-1', 'ta-1', 'GEN 1:1:0');
+    const buffer = await bufferOver({ tokenAnalysisLinks: [stored] });
+
+    buffer.delete('tokenAnalysisLinks', stored);
+
+    await expect(buffer.findLinksByToken(['GEN 1:1:0'])).resolves.toStrictEqual({
+      tokenAnalysisLinks: [],
+      phraseAnalysisLinks: [],
+    });
+  });
+
+  it('finds a record a staged put moves into a lookup, and not one it moves out', async () => {
+    const buffer = await bufferOver({
+      tokenAnalysisLinks: [link('tl-1', 'ta-1', 'GEN 1:1:0'), link('tl-2', 'ta-2', 'GEN 1:1:0')],
+    });
+
+    buffer.put('tokenAnalysisLinks', link('tl-1', 'ta-2', 'GEN 1:1:0'));
+
+    await expect(buffer.findLinksToAnalyses(['ta-1'])).resolves.toMatchObject({
+      tokenAnalysisLinks: [],
+    });
+    const { tokenAnalysisLinks } = await buffer.findLinksToAnalyses(['ta-2']);
+    expect(ids(tokenAnalysisLinks)).toStrictEqual(['tl-1', 'tl-2']);
+  });
+
+  it('answers every lookup through the staged changes', async () => {
+    const phrase = makePhraseLink('pa-1', ['GEN 1:1:0', 'GEN 1:1:3']);
+    const segmentLink = {
+      id: 'sl-1',
+      analysisId: 'sa-1',
+      ...FIXTURE_STAMPS,
+      status: 'approved' as const,
+      segmentId: 'GEN 1:1',
+    };
+    const buffer = await bufferOver({
+      phraseAnalyses: [{ id: 'pa-1', ...FIXTURE_STAMPS, surfaceText: 'In the' }],
+      phraseAnalysisLinks: [phrase],
+      segmentAnalyses: [{ id: 'sa-1', ...FIXTURE_STAMPS, surfaceText: 'In the beginning' }],
+      segmentAnalysisLinks: [segmentLink],
+    });
+
+    buffer.create('tokenAnalyses', payload('ta-new', 'In'));
+
+    await expect(buffer.findTokenAnalysesByForm(['in'])).resolves.toStrictEqual([
+      payload('ta-new', 'In'),
+    ]);
+    await expect(buffer.findPhraseAnalysesByForm(['in the']).then(ids)).resolves.toStrictEqual([
+      'pa-1',
+    ]);
+    await expect(buffer.getPhraseAnalyses(['pa-1']).then(ids)).resolves.toStrictEqual(['pa-1']);
+    await expect(buffer.getSegmentAnalyses(['sa-1']).then(ids)).resolves.toStrictEqual(['sa-1']);
+    await expect(buffer.findLinksBySegment(['GEN 1:1'])).resolves.toStrictEqual([segmentLink]);
+    await expect(buffer.findLinksByToken(['GEN 1:1:3'])).resolves.toStrictEqual({
+      tokenAnalysisLinks: [],
+      phraseAnalysisLinks: [phrase],
+    });
+    await expect(buffer.findLinksToAnalyses(['pa-1', 'sa-1'])).resolves.toStrictEqual({
+      tokenAnalysisLinks: [],
+      phraseAnalysisLinks: [phrase],
+      segmentAnalysisLinks: [segmentLink],
+    });
+  });
+
+  it('hands out copies, so changing a record read stages nothing', async () => {
+    const buffer = await bufferOver({ tokenAnalyses: [payload('ta-1')] });
+    const [read] = await buffer.getTokenAnalyses(['ta-1']);
+
+    read.surfaceText = 'changed';
+
+    expect(buffer.toChangeSet('nothing')).toStrictEqual({ intent: 'nothing' });
+    await expect(buffer.getTokenAnalyses(['ta-1'])).resolves.toStrictEqual([payload('ta-1')]);
+  });
+
+  it('keeps a staged record as it stood when staged', async () => {
+    const buffer = await bufferOver();
+    const created = payload('ta-1');
+
+    buffer.create('tokenAnalyses', created);
+    created.surfaceText = 'changed';
+
+    expect(buffer.toChangeSet('create').tokenAnalyses?.puts).toStrictEqual([payload('ta-1')]);
+  });
+
+  it('collects the staged puts and removals of each kind into one change set', async () => {
+    const stored = link('tl-1', 'ta-1', 'GEN 1:1:0');
+    const buffer = await bufferOver({
+      tokenAnalyses: [payload('ta-1')],
+      tokenAnalysisLinks: [stored],
+    });
+
+    buffer.put('tokenAnalyses', { ...payload('ta-1'), gloss: { en: 'one' } });
+    buffer.delete('tokenAnalysisLinks', stored);
+
+    expect(buffer.toChangeSet('edit')).toStrictEqual({
+      intent: 'edit',
+      tokenAnalyses: { puts: [{ ...payload('ta-1'), gloss: { en: 'one' } }], deletes: [] },
+      tokenAnalysisLinks: { puts: [], deletes: ['tl-1'] },
+    });
+  });
+
+  it('stages nothing for a record it created and then removed', async () => {
+    const buffer = await bufferOver();
+
+    buffer.create('tokenAnalyses', payload('ta-new'));
+    buffer.delete('tokenAnalyses', payload('ta-new'));
+
+    expect(buffer.toChangeSet('none')).toStrictEqual({ intent: 'none' });
+  });
+
+  it('stages a put again after a removal of a stored record', async () => {
+    const buffer = await bufferOver({ tokenAnalyses: [payload('ta-1')] });
+
+    buffer.delete('tokenAnalyses', payload('ta-1'));
+    buffer.put('tokenAnalyses', payload('ta-1'));
+
+    expect(buffer.toChangeSet('restore').tokenAnalyses).toStrictEqual({
+      puts: [payload('ta-1')],
+      deletes: [],
+    });
+  });
+
+  it('lists the records it touches as they stood before a removal or will stand after a put', async () => {
+    const stored = link('tl-1', 'ta-1', 'GEN 1:1:0');
+    const buffer = await bufferOver({ tokenAnalysisLinks: [stored] });
+
+    buffer.delete('tokenAnalysisLinks', stored);
+    buffer.create('tokenAnalysisLinks', link('tl-2', 'ta-1', 'GEN 1:1:3'));
+
+    expect(ids(buffer.touched('tokenAnalysisLinks'))).toStrictEqual(['tl-1', 'tl-2']);
+  });
+});
diff --git a/src/__tests__/services/commands/parity.ts b/src/__tests__/services/commands/parity.ts
new file mode 100644
index 000000000..4307d22d1
--- /dev/null
+++ b/src/__tests__/services/commands/parity.ts
@@ -0,0 +1,75 @@
+/// <reference types="jest" />
+
+import type { UnknownAction } from '@reduxjs/toolkit';
+import type { TextAnalysis } from 'interlinearizer';
+import { ChangeBuffer } from '../../../services/commands/changeBuffer';
+import { DraftRepository } from '../../../services/draftRepository';
+import reducer from '../../../store/analysisSlice';
+import type { ChangeSet, IndexDifference } from '../../../types/analysis-repository';
+import { emptyDraft } from '../../../types/empty-factories';
+import { memoryStorage, silentLogger } from '../../test-helpers';
+
+/** What one input gives through the store's reducer and through the host's command. */
+export type ParityOutcome = {
+  /** The analysis the reducer leaves, its record lists in id order. */
+  store: TextAnalysis;
+  /** The analysis the command's changes leave once applied and reloaded, in id order. */
+  host: TextAnalysis;
+  /** The changes the command staged. */
+  changes: ChangeSet;
+  /** Where the repository's kept indexes differ from its records after applying the changes. */
+  indexDifferences: IndexDifference[];
+};
+
+/** `analysis` as JSON holds it, with each record list in id order. */
+function normalized(analysis: TextAnalysis): TextAnalysis {
+  const plain: TextAnalysis = JSON.parse(JSON.stringify(analysis));
+  const byId = <T extends { id: string }>(records: T[]) =>
+    [...records].sort((a, b) => a.id.localeCompare(b.id));
+  return {
+    segmentAnalyses: byId(plain.segmentAnalyses),
+    segmentAnalysisLinks: byId(plain.segmentAnalysisLinks),
+    tokenAnalyses: byId(plain.tokenAnalyses),
+    tokenAnalysisLinks: byId(plain.tokenAnalysisLinks),
+    phraseAnalyses: byId(plain.phraseAnalyses),
+    phraseAnalysisLinks: byId(plain.phraseAnalysisLinks),
+  };
+}
+
+/**
+ * Runs one input both ways over `analysis`: `action` through the store's reducer, working in
+ * `analysisLanguage`, and `command` staging changes over a draft holding the same analysis, which
+ * are then applied and the draft reloaded from storage.
+ */
+export async function runParity(
+  analysis: TextAnalysis,
+  analysisLanguage: string,
+  action: UnknownAction,
+  command: (buffer: ChangeBuffer) => Promise<void>,
+): Promise<ParityOutcome> {
+  const store = reducer(
+    { analysis: JSON.parse(JSON.stringify(analysis)), analysisLanguage },
+    action,
+  );
+
+  const { storage } = memoryStorage();
+  const logger = silentLogger();
+  await new DraftRepository(storage, 'src', logger).replaceAll({
+    ...emptyDraft('src'),
+    analysisLanguages: [analysisLanguage],
+    analysis: JSON.parse(JSON.stringify(analysis)),
+  });
+  const repository = new DraftRepository(storage, 'src', logger);
+  const buffer = new ChangeBuffer(repository);
+  await command(buffer);
+  const changes = buffer.toChangeSet('parity');
+  await repository.apply(changes);
+  const { draft: reloaded } = await new DraftRepository(storage, 'src', logger).exportAll();
+
+  return {
+    store: normalized(store.analysis),
+    host: normalized(reloaded.analysis),
+    changes,
+    indexDifferences: await repository.checkIndexes(),
+  };
+}
diff --git a/src/__tests__/services/commands/tokenCommands.parity.test.ts b/src/__tests__/services/commands/tokenCommands.parity.test.ts
new file mode 100644
index 000000000..a00234a54
--- /dev/null
+++ b/src/__tests__/services/commands/tokenCommands.parity.test.ts
@@ -0,0 +1,548 @@
+/// <reference types="jest" />
+
+import type { TextAnalysis, TokenAnalysis, TokenAnalysisLink } from 'interlinearizer';
+import {
+  approveAnalysisForToken as approveCommand,
+  writeGloss as writeGlossCommand,
+} from '../../../services/commands/tokenCommands';
+import { approveAnalysisForToken, writeGloss } from '../../../store/analysisSlice';
+import { emptyAnalysis } from '../../../types/empty-factories';
+import { FIXTURE_STAMPS } from '../../test-helpers';
+import { runParity } from './parity';
+
+const NOW = '2026-06-01T00:00:00.000Z';
+const EARLIER = { createdAt: '2025-06-01T00:00:00.000Z', updatedAt: '2025-06-01T00:00:00.000Z' };
+const LATER = { createdAt: '2026-03-01T00:00:00.000Z', updatedAt: '2026-03-01T00:00:00.000Z' };
+
+function payload(id: string, surfaceText: string, fields: Partial<TokenAnalysis> = {}) {
+  return { id, ...FIXTURE_STAMPS, surfaceText, ...fields };
+}
+
+function link(
+  id: string,
+  analysisId: string,
+  tokenRef: string,
+  fields: Partial<TokenAnalysisLink> = {},
+): TokenAnalysisLink {
+  return {
+    id,
+    analysisId,
+    ...FIXTURE_STAMPS,
+    status: 'approved',
+    token: { tokenRef, surfaceText: 'in' },
+    ...fields,
+  };
+}
+
+function analysisOf(
+  tokenAnalyses: TokenAnalysis[],
+  tokenAnalysisLinks: TokenAnalysisLink[],
+): TextAnalysis {
+  return { ...emptyAnalysis(), tokenAnalyses, tokenAnalysisLinks };
+}
+
+const TOKEN = 'GEN 1:1:0';
+const OTHER_TOKEN = 'GEN 1:2:0';
+
+type ParityCase<Input> = {
+  analysis: TextAnalysis;
+  input: Input;
+  /** What the reducer's result must show, so the case exercises the path it names. */
+  expectStore: (store: TextAnalysis) => void;
+};
+
+type GlossInput = { surfaceText?: string; value: string };
+
+const ids = (records: readonly { id: string }[]) => records.map(({ id }) => id).sort();
+
+describe('writeGloss parity with the reducer', () => {
+  const cases: [string, ParityCase<GlossInput>][] = [
+    [
+      'creates a payload and an approved link for an unglossed token',
+      {
+        analysis: emptyAnalysis(),
+        input: { value: 'at' },
+        expectStore: (store) => {
+          expect(ids(store.tokenAnalyses)).toStrictEqual(['new-analysis']);
+          expect(ids(store.tokenAnalysisLinks)).toStrictEqual(['new-link']);
+        },
+      },
+    ],
+    [
+      'shares a stored payload whose content matches',
+      {
+        analysis: analysisOf(
+          [payload('ta-in', 'in', { gloss: { en: 'at' } })],
+          [link('tl-other', 'ta-in', OTHER_TOKEN)],
+        ),
+        input: { value: 'at' },
+        expectStore: (store) => {
+          expect(ids(store.tokenAnalyses)).toStrictEqual(['ta-in']);
+          expect(store.tokenAnalysisLinks.find(({ id }) => id === 'new-link')?.analysisId).toBe(
+            'ta-in',
+          );
+        },
+      },
+    ],
+    [
+      "approves the token's held link to the matching payload rather than adding one",
+      {
+        analysis: analysisOf(
+          [payload('ta-in', 'in', { gloss: { en: 'at' } })],
+          [link('tl-held', 'ta-in', TOKEN, { status: 'suggested', confidence: 'low' })],
+        ),
+        input: { value: 'at' },
+        expectStore: (store) => {
+          expect(store.tokenAnalysisLinks).toHaveLength(1);
+          expect(store.tokenAnalysisLinks[0].status).toBe('approved');
+        },
+      },
+    ],
+    [
+      'edits an unshared payload in place, refreshing surface text and dropping its sense',
+      {
+        analysis: analysisOf(
+          [
+            payload('ta-in', 'In', {
+              gloss: { en: 'at', fr: 'à' },
+              glossSenseRef: { authority: 'fwlite', senseId: 's-at' },
+            }),
+          ],
+          [link('tl-in', 'ta-in', TOKEN)],
+        ),
+        input: { surfaceText: 'In,', value: 'at first' },
+        expectStore: (store) => {
+          expect(store.tokenAnalyses).toStrictEqual([
+            payload('ta-in', 'In,', { gloss: { en: 'at first', fr: 'à' }, updatedAt: NOW }),
+          ]);
+        },
+      },
+    ],
+    [
+      'forks a payload other tokens share, editing only the fork',
+      {
+        analysis: analysisOf(
+          [payload('ta-in', 'In', { gloss: { en: 'at' } })],
+          [link('tl-in', 'ta-in', TOKEN), link('tl-other', 'ta-in', OTHER_TOKEN)],
+        ),
+        input: { value: 'start' },
+        expectStore: (store) => {
+          expect(ids(store.tokenAnalyses)).toStrictEqual(['new-analysis', 'ta-in']);
+        },
+      },
+    ],
+    [
+      "folds an edit matching another payload into it, clearing the survivor's stale breakdown",
+      {
+        analysis: analysisOf(
+          [
+            payload('ta-at', 'in', { gloss: { en: 'at' } }),
+            payload('ta-within', 'In', {
+              ...EARLIER,
+              gloss: { en: 'within' },
+              morphemesStale: true,
+            }),
+          ],
+          [link('tl-in', 'ta-at', TOKEN), link('tl-other', 'ta-within', OTHER_TOKEN)],
+        ),
+        input: { value: 'within' },
+        expectStore: (store) => {
+          expect(ids(store.tokenAnalyses)).toStrictEqual(['ta-within']);
+          expect(store.tokenAnalyses[0].morphemesStale).toBeUndefined();
+        },
+      },
+    ],
+    [
+      'leaves a token linking both folded payloads one link, dated by the earlier',
+      {
+        analysis: analysisOf(
+          [
+            payload('ta-at', 'In', { gloss: { en: 'at' } }),
+            payload('ta-within', 'In', { ...EARLIER, gloss: { en: 'within' } }),
+          ],
+          [
+            link('tl-in', 'ta-at', TOKEN, LATER),
+            link('tl-offered', 'ta-within', TOKEN, { ...EARLIER, status: 'suggested' }),
+          ],
+        ),
+        input: { value: 'within' },
+        expectStore: (store) => {
+          expect(store.tokenAnalysisLinks).toHaveLength(1);
+          expect(store.tokenAnalysisLinks[0]).toMatchObject({
+            id: 'tl-in',
+            status: 'approved',
+            createdAt: EARLIER.createdAt,
+          });
+        },
+      },
+    ],
+    [
+      'folds into a payload another token was offered, leaving that offer as it was',
+      {
+        analysis: analysisOf(
+          [
+            payload('ta-at', 'In', { gloss: { en: 'at' } }),
+            payload('ta-within', 'In', { ...EARLIER, gloss: { en: 'within' } }),
+          ],
+          [
+            link('tl-in', 'ta-at', TOKEN),
+            link('tl-offered', 'ta-within', OTHER_TOKEN, { status: 'suggested' }),
+          ],
+        ),
+        input: { value: 'within' },
+        expectStore: (store) => {
+          expect(store.tokenAnalysisLinks).toStrictEqual(
+            expect.arrayContaining([
+              expect.objectContaining({ id: 'tl-offered', status: 'suggested' }),
+            ]),
+          );
+          expect(ids(store.tokenAnalyses)).toStrictEqual(['ta-within']);
+        },
+      },
+    ],
+    [
+      'clears the gloss, removing the payload it empties and its link',
+      {
+        analysis: analysisOf(
+          [payload('ta-in', 'In', { gloss: { en: 'at' } })],
+          [link('tl-in', 'ta-in', TOKEN)],
+        ),
+        input: { value: '' },
+        expectStore: (store) => {
+          expect(store).toStrictEqual(emptyAnalysis());
+        },
+      },
+    ],
+    [
+      'clears one language, keeping the others and the sense',
+      {
+        analysis: analysisOf(
+          [
+            payload('ta-in', 'In', {
+              gloss: { en: 'at', fr: 'à' },
+              glossSenseRef: { authority: 'fwlite', senseId: 's-at' },
+            }),
+          ],
+          [link('tl-in', 'ta-in', TOKEN)],
+        ),
+        input: { value: '  ' },
+        expectStore: (store) => {
+          expect(store.tokenAnalyses[0].gloss).toStrictEqual({ fr: 'à' });
+          expect(store.tokenAnalyses[0].glossSenseRef).toBeDefined();
+        },
+      },
+    ],
+    [
+      'clears a shared payload by dropping only this token’s link',
+      {
+        analysis: analysisOf(
+          [payload('ta-in', 'In', { gloss: { en: 'at' } })],
+          [link('tl-in', 'ta-in', TOKEN), link('tl-other', 'ta-in', OTHER_TOKEN)],
+        ),
+        input: { value: '' },
+        expectStore: (store) => {
+          expect(ids(store.tokenAnalyses)).toStrictEqual(['ta-in']);
+          expect(ids(store.tokenAnalysisLinks)).toStrictEqual(['tl-other']);
+        },
+      },
+    ],
+    [
+      'keeps an emptied payload another of the token’s links still names',
+      {
+        analysis: analysisOf(
+          [payload('ta-in', 'In', { gloss: { en: 'at' } })],
+          [
+            link('tl-in', 'ta-in', TOKEN),
+            link('tl-rejected', 'ta-in', TOKEN, { status: 'rejected' }),
+          ],
+        ),
+        input: { value: '' },
+        expectStore: (store) => {
+          expect(store.tokenAnalyses).toStrictEqual([payload('ta-in', 'In', { updatedAt: NOW })]);
+          expect(ids(store.tokenAnalysisLinks)).toStrictEqual(['tl-rejected']);
+        },
+      },
+    ],
+    [
+      'folds a cleared payload into another its remaining content matches',
+      {
+        analysis: analysisOf(
+          [
+            payload('ta-in', 'In', { gloss: { en: 'at' }, pos: 'prep' }),
+            payload('ta-bare', 'in', { ...EARLIER, pos: 'prep' }),
+          ],
+          [link('tl-in', 'ta-in', TOKEN)],
+        ),
+        input: { value: '' },
+        expectStore: (store) => {
+          expect(ids(store.tokenAnalyses)).toStrictEqual(['ta-bare']);
+          expect(store.tokenAnalysisLinks[0].analysisId).toBe('ta-bare');
+        },
+      },
+    ],
+    [
+      'folds a fork back onto the shared payload when the write leaves it unchanged',
+      {
+        analysis: analysisOf(
+          [payload('ta-in', 'In', { gloss: { en: 'at' } })],
+          [link('tl-in', 'ta-in', TOKEN), link('tl-other', 'ta-in', OTHER_TOKEN)],
+        ),
+        input: { value: 'at' },
+        expectStore: (store) => {
+          expect(ids(store.tokenAnalyses)).toStrictEqual(['ta-in']);
+          expect(store.tokenAnalysisLinks.every(({ analysisId }) => analysisId === 'ta-in')).toBe(
+            true,
+          );
+        },
+      },
+    ],
+    [
+      'edits the payload an approval tie picks among several approved links',
+      {
+        analysis: analysisOf(
+          [
+            payload('ta-old', 'In', { gloss: { en: 'old' } }),
+            payload('ta-new', 'In', { gloss: { en: 'new' } }),
+          ],
+          [link('tl-old', 'ta-old', TOKEN, EARLIER), link('tl-new', 'ta-new', TOKEN, LATER)],
+        ),
+        input: { value: 'newer' },
+        expectStore: (store) => {
+          expect(store.tokenAnalyses.find(({ id }) => id === 'ta-new')?.gloss).toStrictEqual({
+            en: 'newer',
+          });
+        },
+      },
+    ],
+    [
+      'stages nothing for a blank write to an unglossed token',
+      {
+        analysis: analysisOf([payload('ta-in', 'In', { gloss: { en: 'at' } })], []),
+        input: { value: '' },
+        expectStore: (store) => {
+          expect(ids(store.tokenAnalyses)).toStrictEqual(['ta-in']);
+        },
+      },
+    ],
+    [
+      'removes an approved link whose payload is gone before writing',
+      {
+        analysis: analysisOf([], [link('tl-orphan', 'ta-missing', TOKEN)]),
+        input: { value: 'at' },
+        expectStore: (store) => {
+          expect(ids(store.tokenAnalysisLinks)).toStrictEqual(['new-link']);
+        },
+      },
+    ],
+    [
+      'removes an approved link whose payload is gone even on a blank write',
+      {
+        analysis: analysisOf([], [link('tl-orphan', 'ta-missing', TOKEN)]),
+        input: { value: '' },
+        expectStore: (store) => {
+          expect(store).toStrictEqual(emptyAnalysis());
+        },
+      },
+    ],
+  ];
+
+  it.each(cases)('%s', async (_name, { analysis, input, expectStore }) => {
+    const surfaceText = input.surfaceText ?? 'In';
+    const outcome = await runParity(
+      analysis,
+      'en',
+      {
+        type: writeGloss.type,
+        payload: {
+          tokenRef: TOKEN,
+          surfaceText,
+          value: input.value,
+          id: 'new-analysis',
+          linkId: 'new-link',
+          now: NOW,
+        },
+      },
+      (buffer) =>
+        writeGlossCommand(buffer, {
+          tokenRef: TOKEN,
+          surfaceText,
+          value: input.value,
+          analysisLanguage: 'en',
+          analysisId: 'new-analysis',
+          linkId: 'new-link',
+          now: NOW,
+        }),
+    );
+
+    expectStore(outcome.store);
+    expect(outcome.host).toStrictEqual(outcome.store);
+    expect(outcome.indexDifferences).toStrictEqual([]);
+  });
+});
+
+type ApproveInput = { analysisId: string };
+
+describe('approveAnalysisForToken parity with the reducer', () => {
+  const cases: [string, ParityCase<ApproveInput>][] = [
+    [
+      'gives a token with no approval a new approved link',
+      {
+        analysis: analysisOf([payload('ta-in', 'In', { gloss: { en: 'at' } })], []),
+        input: { analysisId: 'ta-in' },
+        expectStore: (store) => {
+          expect(store.tokenAnalysisLinks).toStrictEqual([
+            {
+              id: 'new-link',
+              analysisId: 'ta-in',
+              createdAt: NOW,
+              updatedAt: NOW,
+              status: 'approved',
+              token: { tokenRef: TOKEN, surfaceText: 'In' },
+            },
+          ]);
+        },
+      },
+    ],
+    [
+      'approves the link the token holds to the payload rather than adding one',
+      {
+        analysis: analysisOf(
+          [payload('ta-in', 'In', { gloss: { en: 'at' } })],
+          [link('tl-held', 'ta-in', TOKEN, { status: 'candidate', confidence: 'guess' })],
+        ),
+        input: { analysisId: 'ta-in' },
+        expectStore: (store) => {
+          expect(store.tokenAnalysisLinks).toHaveLength(1);
+          expect(store.tokenAnalysisLinks[0]).toMatchObject({
+            status: 'approved',
+            confidence: 'guess',
+          });
+        },
+      },
+    ],
+    [
+      'moves the approval off a payload, removing it once nothing links it',
+      {
+        analysis: analysisOf(
+          [
+            payload('ta-at', 'In', { gloss: { en: 'at' } }),
+            payload('ta-on', 'In', { gloss: { en: 'on' } }),
+          ],
+          [link('tl-in', 'ta-at', TOKEN)],
+        ),
+        input: { analysisId: 'ta-on' },
+        expectStore: (store) => {
+          expect(ids(store.tokenAnalyses)).toStrictEqual(['ta-on']);
+          expect(store.tokenAnalysisLinks[0].analysisId).toBe('ta-on');
+        },
+      },
+    ],
+    [
+      'keeps the payload the approval leaves when another token links it',
+      {
+        analysis: analysisOf(
+          [
+            payload('ta-at', 'In', { gloss: { en: 'at' } }),
+            payload('ta-on', 'In', { gloss: { en: 'on' } }),
+          ],
+          [link('tl-in', 'ta-at', TOKEN), link('tl-other', 'ta-at', OTHER_TOKEN)],
+        ),
+        input: { analysisId: 'ta-on' },
+        expectStore: (store) => {
+          expect(ids(store.tokenAnalyses)).toStrictEqual(['ta-at', 'ta-on']);
+        },
+      },
+    ],
+    [
+      'approves a held link in place of the approval, keeping the earlier creation date',
+      {
+        analysis: analysisOf(
+          [
+            payload('ta-at', 'In', { gloss: { en: 'at' } }),
+            payload('ta-on', 'In', { gloss: { en: 'on' } }),
+          ],
+          [
+            link('tl-in', 'ta-at', TOKEN, EARLIER),
+            link('tl-held', 'ta-on', TOKEN, { ...LATER, status: 'suggested' }),
+          ],
+        ),
+        input: { analysisId: 'ta-on' },
+        expectStore: (store) => {
+          expect(store.tokenAnalysisLinks).toStrictEqual([
+            expect.objectContaining({
+              id: 'tl-held',
+              status: 'approved',
+              createdAt: EARLIER.createdAt,
+            }),
+          ]);
+          expect(ids(store.tokenAnalyses)).toStrictEqual(['ta-on']);
+        },
+      },
+    ],
+    [
+      'stages nothing for a payload not stored',
+      {
+        analysis: analysisOf([], [link('tl-orphan', 'ta-missing', TOKEN)]),
+        input: { analysisId: 'ta-unknown' },
+        expectStore: (store) => {
+          expect(ids(store.tokenAnalysisLinks)).toStrictEqual(['tl-orphan']);
+        },
+      },
+    ],
+    [
+      'removes orphaned approvals even when the payload is already approved',
+      {
+        analysis: analysisOf(
+          [payload('ta-in', 'In', { gloss: { en: 'at' } })],
+          [link('tl-in', 'ta-in', TOKEN, LATER), link('tl-orphan', 'ta-missing', TOKEN, EARLIER)],
+        ),
+        input: { analysisId: 'ta-in' },
+        expectStore: (store) => {
+          expect(ids(store.tokenAnalysisLinks)).toStrictEqual(['tl-in']);
+        },
+      },
+    ],
+    [
+      'removes orphaned approvals before approving',
+      {
+        analysis: analysisOf(
+          [payload('ta-in', 'In', { gloss: { en: 'at' } })],
+          [link('tl-orphan', 'ta-missing', TOKEN)],
+        ),
+        input: { analysisId: 'ta-in' },
+        expectStore: (store) => {
+          expect(ids(store.tokenAnalysisLinks)).toStrictEqual(['new-link']);
+        },
+      },
+    ],
+  ];
+
+  it.each(cases)('%s', async (_name, { analysis, input, expectStore }) => {
+    const outcome = await runParity(
+      analysis,
+      'en',
+      {
+        type: approveAnalysisForToken.type,
+        payload: {
+          tokenRef: TOKEN,
+          surfaceText: 'In',
+          analysisId: input.analysisId,
+          linkId: 'new-link',
+          now: NOW,
+        },
+      },
+      (buffer) =>
+        approveCommand(buffer, {
+          tokenRef: TOKEN,
+          surfaceText: 'In',
+          analysisId: input.analysisId,
+          linkId: 'new-link',
+          now: NOW,
+        }),
+    );
+
+    expectStore(outcome.store);
+    expect(outcome.host).toStrictEqual(outcome.store);
+    expect(outcome.indexDifferences).toStrictEqual([]);
+  });
+});
diff --git a/src/__tests__/services/commands/tokenCommands.test.ts b/src/__tests__/services/commands/tokenCommands.test.ts
new file mode 100644
index 000000000..7550f665e
--- /dev/null
+++ b/src/__tests__/services/commands/tokenCommands.test.ts
@@ -0,0 +1,92 @@
+/// <reference types="jest" />
+
+import type { TextAnalysis, TokenAnalysis, TokenAnalysisLink } from 'interlinearizer';
+import { ChangeBuffer } from '../../../services/commands/changeBuffer';
+import { approveAnalysisForToken, writeGloss } from '../../../services/commands/tokenCommands';
+import { DraftRepository } from '../../../services/draftRepository';
+import { emptyAnalysis, emptyDraft } from '../../../types/empty-factories';
+import { FIXTURE_STAMPS, memoryStorage, silentLogger } from '../../test-helpers';
+
+const NOW = '2026-06-01T00:00:00.000Z';
+const STAMP = { analysisId: 'new-analysis', linkId: 'new-link', now: NOW };
+
+const shared: TokenAnalysis = {
+  id: 'ta-in',
+  ...FIXTURE_STAMPS,
+  surfaceText: 'In',
+  gloss: { en: 'at' },
+};
+
+function link(id: string, tokenRef: string): TokenAnalysisLink {
+  return {
+    id,
+    analysisId: 'ta-in',
+    ...FIXTURE_STAMPS,
+    status: 'approved',
+    token: { tokenRef, surfaceText: 'In' },
+  };
+}
+
+async function bufferOver(analysis: Partial<TextAnalysis>): Promise<ChangeBuffer> {
+  const { storage } = memoryStorage();
+  const repository = new DraftRepository(storage, 'src', silentLogger());
+  await repository.replaceAll({
+    ...emptyDraft('src'),
+    analysis: { ...emptyAnalysis(), ...analysis },
+  });
+  return new ChangeBuffer(repository);
+}
+
+describe('writeGloss', () => {
+  it("stages only the link's removal when clearing a shared payload, never its fork", async () => {
+    const buffer = await bufferOver({
+      tokenAnalyses: [shared],
+      tokenAnalysisLinks: [link('tl-1', 'GEN 1:1:0'), link('tl-2', 'GEN 1:2:0')],
+    });
+
+    await writeGloss(buffer, {
+      ...STAMP,
+      tokenRef: 'GEN 1:1:0',
+      surfaceText: 'In',
+      value: '',
+      analysisLanguage: 'en',
+    });
+
+    expect(buffer.toChangeSet('writeGloss')).toStrictEqual({
+      intent: 'writeGloss',
+      tokenAnalysisLinks: { puts: [], deletes: ['tl-1'] },
+    });
+  });
+
+  it('stages nothing for a blank write to an unglossed token', async () => {
+    const buffer = await bufferOver({ tokenAnalyses: [shared] });
+
+    await writeGloss(buffer, {
+      ...STAMP,
+      tokenRef: 'GEN 1:1:0',
+      surfaceText: 'In',
+      value: ' ',
+      analysisLanguage: 'en',
+    });
+
+    expect(buffer.toChangeSet('writeGloss')).toStrictEqual({ intent: 'writeGloss' });
+  });
+});
+
+describe('approveAnalysisForToken', () => {
+  it('stages nothing for a payload already approved for the token', async () => {
+    const buffer = await bufferOver({
+      tokenAnalyses: [shared],
+      tokenAnalysisLinks: [link('tl-1', 'GEN 1:1:0')],
+    });
+
+    await approveAnalysisForToken(buffer, {
+      ...STAMP,
+      tokenRef: 'GEN 1:1:0',
+      surfaceText: 'In',
+      analysisId: 'ta-in',
+    });
+
+    expect(buffer.toChangeSet('approve')).toStrictEqual({ intent: 'approve' });
+  });
+});
diff --git a/src/__tests__/services/indexedRepository.test.ts b/src/__tests__/services/indexedRepository.test.ts
index 290a6cb98..eba1c5666 100644
--- a/src/__tests__/services/indexedRepository.test.ts
+++ b/src/__tests__/services/indexedRepository.test.ts
@@ -2,27 +2,30 @@
 
 import type { TextAnalysis } from 'interlinearizer';
 import { AnalysisIndex } from '../../services/analysisIndex';
-import { type IndexedAnalysis, IndexedRepository } from '../../services/indexedRepository';
-import { emptyAnalysis } from '../../types/empty-factories';
+import { type IndexedDraft, IndexedRepository } from '../../services/indexedRepository';
+import { emptyAnalysis, emptyDraft } from '../../types/empty-factories';
 import { FIXTURE_STAMPS } from '../test-helpers';
 
 /** Answers lookups from an index over `records`, keeping it as `keep` says. */
 class StubRepository extends IndexedRepository {
-  readonly kept: IndexedAnalysis | undefined;
+  readonly kept: IndexedDraft | undefined;
 
-  private readonly index: AnalysisIndex;
+  private readonly indexedDraft: IndexedDraft;
 
   constructor(records: TextAnalysis, keep: 'kept' | 'none') {
     super();
-    this.index = new AnalysisIndex(records);
-    this.kept = keep === 'kept' ? { analysis: records, index: this.index } : undefined;
+    this.indexedDraft = {
+      draft: { ...emptyDraft('src'), analysisLanguages: ['en'], analysis: records },
+      index: new AnalysisIndex(records),
+    };
+    this.kept = keep === 'kept' ? this.indexedDraft : undefined;
   }
 
-  protected async indexed(): Promise<AnalysisIndex> {
-    return this.index;
+  protected async indexed(): Promise<IndexedDraft> {
+    return this.indexedDraft;
   }
 
-  protected keptIndex(): IndexedAnalysis | undefined {
+  protected keptIndex(): IndexedDraft | undefined {
     return this.kept;
   }
 }
@@ -54,7 +57,7 @@ describe('IndexedRepository', () => {
 
   it('reports the differences of the index it keeps from its analysis', async () => {
     const repository = new StubRepository(analysis(), 'kept');
-    repository.kept?.analysis.tokenAnalyses.pop();
+    repository.kept?.draft.analysis.tokenAnalyses.pop();
 
     await expect(repository.checkIndexes()).resolves.toContainEqual({
       index: 'tokenAnalyses',
@@ -64,6 +67,14 @@ describe('IndexedRepository', () => {
     });
   });
 
+  it("reads the draft's own record without its analysis", async () => {
+    await expect(new StubRepository(analysis(), 'none').getScope()).resolves.toStrictEqual({
+      sourceProjectId: 'src',
+      modelVersion: emptyDraft('src').modelVersion,
+      analysisLanguages: ['en'],
+    });
+  });
+
   it('reports nothing while it keeps no index', async () => {
     await expect(new StubRepository(analysis(), 'none').checkIndexes()).resolves.toStrictEqual([]);
   });
diff --git a/src/__tests__/services/projectStorage.test.ts b/src/__tests__/services/projectStorage.test.ts
index 948c16f9e..b2cdae455 100644
--- a/src/__tests__/services/projectStorage.test.ts
+++ b/src/__tests__/services/projectStorage.test.ts
@@ -2946,6 +2946,11 @@ describe('projectStorage', () => {
       ],
       ['findPhraseAnalysesByForm', (r: AnalysisRepository) => r.findPhraseAnalysesByForm(['x']), 0],
       ['checkIndexes', (r: AnalysisRepository) => r.checkIndexes(), 0],
+      [
+        'getScope',
+        (r: AnalysisRepository) => r.getScope().then(({ analysisLanguages }) => analysisLanguages),
+        0,
+      ],
     ])('answers %s from the draft saveDraft saved', async (_name, lookup, count) => {
       await saveDraft(token, 'src-proj', makeDraftSpanningBooks('src-proj', 'GEN'));
 
diff --git a/src/__tests__/utils/change-set.test.ts b/src/__tests__/utils/change-set.test.ts
index a8f19f1ec..b0894f579 100644
--- a/src/__tests__/utils/change-set.test.ts
+++ b/src/__tests__/utils/change-set.test.ts
@@ -2,7 +2,7 @@
 
 import type { DraftProject, TokenAnalysis } from 'interlinearizer';
 import { emptyAnalysis, emptyDraft } from '../../types/empty-factories';
-import { applyChangeSet, scopeRecordOf } from '../../utils/change-set';
+import { applyChangeSet, isEmptyChangeSet, scopeRecordOf } from '../../utils/change-set';
 import { FIXTURE_STAMPS } from '../test-helpers';
 
 function payload(id: string, gloss?: string): TokenAnalysis {
@@ -189,3 +189,19 @@ describe('applyChangeSet', () => {
     ).toStrictEqual([['sa'], ['sl'], ['a'], ['tl'], ['pa'], ['pl']]);
   });
 });
+
+describe('isEmptyChangeSet', () => {
+  it('finds a change set naming only its intent empty', () => {
+    expect(isEmptyChangeSet({ intent: 'none' })).toBe(true);
+  });
+
+  it('finds a change set with record changes not empty', () => {
+    expect(isEmptyChangeSet({ intent: 'edit', tokenAnalyses: { puts: [], deletes: ['a'] } })).toBe(
+      false,
+    );
+  });
+
+  it("finds a change set putting the scope's record not empty", () => {
+    expect(isEmptyChangeSet({ intent: 'edit', scope: scopeRecordOf(draftOf()) })).toBe(false);
+  });
+});
diff --git a/src/__tests__/utils/token-analysis-content.test.ts b/src/__tests__/utils/token-analysis-content.test.ts
new file mode 100644
index 000000000..5625fd3a3
--- /dev/null
+++ b/src/__tests__/utils/token-analysis-content.test.ts
@@ -0,0 +1,59 @@
+/// <reference types="jest" />
+
+import type { TokenAnalysis } from 'interlinearizer';
+import { clearAnalysisGloss, isEmptyTokenAnalysis } from '../../utils/token-analysis-content';
+import { FIXTURE_STAMPS } from '../test-helpers';
+
+function analysis(fields: Partial<TokenAnalysis> = {}): TokenAnalysis {
+  return { id: 'ta-1', ...FIXTURE_STAMPS, surfaceText: 'In', ...fields };
+}
+
+describe('isEmptyTokenAnalysis', () => {
+  it('finds a record holding only blank glosses and provenance empty', () => {
+    expect(isEmptyTokenAnalysis(analysis({ gloss: { en: ' ' }, confidence: 'high' }))).toBe(true);
+  });
+
+  it.each([
+    ['a gloss', { gloss: { en: 'at' } }],
+    ['morphemes', { morphemes: [{ id: 'm-1', form: 'in', writingSystem: 'en' }] }],
+    ['a part of speech', { pos: 'prep' }],
+    ['features', { features: { case: 'loc' } }],
+    ['a gloss sense', { glossSenseRef: { authority: 'fwlite', senseId: 's-1' } }],
+  ])('finds a record holding %s not empty', (_field, fields) => {
+    expect(isEmptyTokenAnalysis(analysis(fields))).toBe(false);
+  });
+});
+
+describe('clearAnalysisGloss', () => {
+  it('clears one language, keeping the others and the sense', () => {
+    const record = analysis({
+      gloss: { en: 'at', fr: 'à' },
+      glossSenseRef: { authority: 'fwlite', senseId: 's-1' },
+    });
+
+    clearAnalysisGloss(record, 'en');
+
+    expect(record).toStrictEqual(
+      analysis({ gloss: { fr: 'à' }, glossSenseRef: { authority: 'fwlite', senseId: 's-1' } }),
+    );
+  });
+
+  it('drops the gloss and the sense once no language holds usable text', () => {
+    const record = analysis({
+      gloss: { en: 'at', fr: ' ' },
+      glossSenseRef: { authority: 'fwlite', senseId: 's-1' },
+    });
+
+    clearAnalysisGloss(record, 'en');
+
+    expect(record).toStrictEqual(analysis());
+  });
+
+  it('drops a sense left with no gloss at all', () => {
+    const record = analysis({ glossSenseRef: { authority: 'fwlite', senseId: 's-1' } });
+
+    clearAnalysisGloss(record, 'en');
+
+    expect(record).toStrictEqual(analysis());
+  });
+});
diff --git a/src/main.ts b/src/main.ts
index 1ec3369aa..d4e440d68 100644
--- a/src/main.ts
+++ b/src/main.ts
@@ -11,8 +11,10 @@ import type { ProjectConfig } from 'interlinearizer';
 import { formatReplacementString, type LocalizeKey } from 'platform-bible-utils';
 import interlinearizerReact from './interlinearizer.web-view?inline';
 import interlinearizerStyles from './interlinearizer.web-view.scss?inline';
-import { AnalysisSessions, type OpenedSession } from './services/analysisSessions';
+import { AnalysisSessions, type OpenedSession, type Session } from './services/analysisSessions';
 import * as bookService from './services/bookService';
+import type { ChangeBuffer } from './services/commands/changeBuffer';
+import * as tokenCommands from './services/commands/tokenCommands';
 import { readHostPerf, setHostPerfMarks } from './services/hostPerf';
 import * as projectStorage from './services/projectStorage';
 import * as pt9ImportService from './services/pt9ImportService';
@@ -826,6 +828,80 @@ async function checkIndexes(sessionId: string): Promise<string> {
   }
 }
 
+/**
+ * Runs `command` as one edit of a session's analysis.
+ *
+ * @returns The changes it applied, as JSON.
+ * @throws If the session is read-only or not open, or the edit is refused or fails. The error is
+ *   logged before rethrowing.
+ */
+async function runSessionEdit(
+  sessionId: string,
+  intent: string,
+  command: (buffer: ChangeBuffer, session: Session) => Promise<void>,
+): Promise<string> {
+  try {
+    return JSON.stringify(await sessions.edit(sessionId, intent, command));
+  } catch (e) {
+    logger.error(`Interlinearizer: failed to ${intent} in session ${sessionId}`, e);
+    throw e;
+  }
+}
+
+/** Ids a new record or link would take, and the time an edit lands. */
+function editStamp() {
+  return {
+    analysisId: crypto.randomUUID(),
+    linkId: crypto.randomUUID(),
+    now: new Date().toISOString(),
+  };
+}
+
+/**
+ * Writes a token's gloss in the session's analysis language; a blank value clears it.
+ *
+ * @returns The changes it applied, as JSON.
+ * @throws As {@link runSessionEdit} does.
+ */
+function writeGloss(
+  sessionId: string,
+  tokenRef: string,
+  surfaceText: string,
+  value: string,
+): Promise<string> {
+  return runSessionEdit(sessionId, 'writeGloss', (buffer, session) =>
+    tokenCommands.writeGloss(buffer, {
+      ...editStamp(),
+      tokenRef,
+      surfaceText,
+      value,
+      analysisLanguage: session.analysisLanguage,
+    }),
+  );
+}
+
+/**
+ * Approves a stored token analysis for a token, in place of any approval it held.
+ *
+ * @returns The changes it applied, as JSON.
+ * @throws As {@link runSessionEdit} does.
+ */
+function approveAnalysisForToken(
+  sessionId: string,
+  tokenRef: string,
+  surfaceText: string,
+  analysisId: string,
+): Promise<string> {
+  return runSessionEdit(sessionId, 'approveAnalysisForToken', (buffer) =>
+    tokenCommands.approveAnalysisForToken(buffer, {
+      ...editStamp(),
+      tokenRef,
+      surfaceText,
+      analysisId,
+    }),
+  );
+}
+
 /**
  * Returns a summary of every interlinearizer project for the given source project as a JSON string.
  * The WebView deserializes this to populate its project picker and to decide whether to prompt
@@ -1431,6 +1507,70 @@ export async function activate(context: ExecutionActivationContext): Promise<voi
     },
   );
 
+  /** The parameters naming the token a token edit acts on. */
+  const tokenParams = [
+    {
+      name: 'tokenRef',
+      required: true,
+      summary: 'Token.ref of the token edited',
+      schema: { type: 'string' },
+    },
+    {
+      name: 'surfaceText',
+      required: true,
+      summary: "The token's current surface text",
+      schema: { type: 'string' },
+    },
+  ] as const;
+
+  const editResult = {
+    name: 'return value',
+    summary: 'JSON-stringified ChangeSet the edit applied',
+    schema: { type: 'string' },
+  } as const;
+
+  const writeGlossCommandRegistration = await papi.commands.registerCommand(
+    'interlinearizer.writeGloss',
+    writeGloss,
+    {
+      method: {
+        summary: "Write a token's gloss in a session's analysis language; a blank value clears it",
+        params: [
+          sessionIdParam,
+          ...tokenParams,
+          {
+            name: 'value',
+            required: true,
+            summary: 'The gloss',
+            schema: { type: 'string' },
+          },
+        ],
+        result: editResult,
+      },
+    },
+  );
+
+  const approveAnalysisForTokenCommandRegistration = await papi.commands.registerCommand(
+    'interlinearizer.approveAnalysisForToken',
+    approveAnalysisForToken,
+    {
+      method: {
+        summary: 'Approve a stored token analysis for a token, in place of any approval it held',
+        params: [
+          sessionIdParam,
+          ...tokenParams,
+          {
+            name: 'analysisId',
+            required: true,
+            summary: 'Id of the stored token analysis to approve',
+            schema: { type: 'string' },
+          },
+        ],
+        result: editResult,
+      },
+    },
+  );
+
   const checkIndexesCommandRegistration = await papi.commands.registerCommand(
     'interlinearizer.checkIndexes',
     checkIndexes,
@@ -1824,6 +1964,8 @@ export async function activate(context: ExecutionActivationContext): Promise<voi
     undoEditCommandRegistration,
     redoEditCommandRegistration,
     checkIndexesCommandRegistration,
+    writeGlossCommandRegistration,
+    approveAnalysisForTokenCommandRegistration,
     setPerfMarksCommandRegistration,
     readPerfCommandRegistration,
     updateProjectMetadataCommandRegistration,
diff --git a/src/services/analysisSessions.ts b/src/services/analysisSessions.ts
index 29bae4c82..7be058f68 100644
--- a/src/services/analysisSessions.ts
+++ b/src/services/analysisSessions.ts
@@ -1,7 +1,10 @@
 import type { AnalysisRepository, ChangeSet } from '../types/analysis-repository';
 import { ReadOnlyAnalysisError } from '../types/read-only-analysis-error';
 import type { InterlinearProjectSummary } from '../types/interlinear-project-summary';
+import { isEmptyChangeSet } from '../utils/change-set';
 import { analysisHasFreeTranslations } from '../utils/free-translations';
+import { assertApprovalRule } from './commands/approvalRule';
+import { ChangeBuffer } from './commands/changeBuffer';
 import { EditHistory } from './editHistory';
 
 /** BCP 47 tag for a language that cannot be determined. */
@@ -202,6 +205,33 @@ export class AnalysisSessions {
     return this.run(sessionId, edit);
   }
 
+  /**
+   * Runs `command` as one edit of the session's analysis, in the session's turn. What it stages
+   * applies as one undo step, marking the draft dirty; a command staging nothing applies nothing.
+   *
+   * @returns The changes applied, naming `intent`.
+   * @throws {ReadOnlyAnalysisError} If the session is read-only.
+   * @throws {ApprovalRuleError} If the changes would give a token or segment a second approved
+   *   link; nothing is applied.
+   * @throws {Error} If the session is not open.
+   * @throws Whatever the command or applying its changes throws; nothing is applied.
+   */
+  edit(
+    sessionId: string,
+    intent: string,
+    command: (buffer: ChangeBuffer, session: Session) => Promise<void>,
+  ): Promise<ChangeSet> {
+    return this.runEdit(sessionId, async (session) => {
+      const buffer = new ChangeBuffer(session.repository);
+      await command(buffer, session);
+      const changes = buffer.toChangeSet(intent);
+      if (isEmptyChangeSet(changes)) return changes;
+      await assertApprovalRule(buffer, session.repository);
+      await session.history.apply(changes);
+      return changes;
+    });
+  }
+
   /**
    * Reverts the session's latest edit not yet undone.
    *
diff --git a/src/services/commands/approvalRule.ts b/src/services/commands/approvalRule.ts
new file mode 100644
index 000000000..e0477069d
--- /dev/null
+++ b/src/services/commands/approvalRule.ts
@@ -0,0 +1,69 @@
+import type { AnalysisRepository } from '../../types/analysis-repository';
+import type { ChangeBuffer } from './changeBuffer';
+
+/** Thrown by an edit that would give a token or segment a second approved link. */
+export class ApprovalRuleError extends Error {
+  /** The token refs and segment ids the edit would leave holding several approved links. */
+  readonly places: readonly string[];
+
+  constructor(places: readonly string[]) {
+    super(`Interlinearizer: an edit would approve several analyses at ${places.join(', ')}`);
+    this.name = 'ApprovalRuleError';
+    this.places = places;
+  }
+}
+
+/** How many approved links each place holds, placing each link by `placeOf`. */
+function approvedCounts<Link extends { status: string }>(
+  links: readonly Link[],
+  placeOf: (link: Link) => string,
+): Map<string, number> {
+  const counts = new Map<string, number>();
+  links.forEach((link) => {
+    if (link.status !== 'approved') return;
+    counts.set(placeOf(link), (counts.get(placeOf(link)) ?? 0) + 1);
+  });
+  return counts;
+}
+
+/** The places where `after` holds more than one approved link, and more than `before` held. */
+function breaches<Link extends { status: string }>(
+  before: readonly Link[],
+  after: readonly Link[],
+  placeOf: (link: Link) => string,
+): string[] {
+  const held = approvedCounts(before, placeOf);
+  return [...approvedCounts(after, placeOf)].flatMap(([place, count]) =>
+    count > 1 && count > (held.get(place) ?? 0) ? [place] : [],
+  );
+}
+
+/**
+ * Refuses the changes staged in `buffer` over `repository` when they would leave a token or segment
+ * holding more approved links than one, and more than it held before them. A place the stored
+ * analysis already breaches is left to the edits that repair it.
+ *
+ * @throws {ApprovalRuleError} If the changes breach the rule anywhere.
+ */
+export async function assertApprovalRule(
+  buffer: ChangeBuffer,
+  repository: AnalysisRepository,
+): Promise<void> {
+  const tokenRefs = [
+    ...new Set(buffer.touched('tokenAnalysisLinks').map(({ token }) => token.tokenRef)),
+  ];
+  const segmentIds = [...new Set(buffer.touched('segmentAnalysisLinks').map((l) => l.segmentId))];
+  const found = [
+    ...breaches(
+      (await repository.findLinksByToken(tokenRefs)).tokenAnalysisLinks,
+      (await buffer.findLinksByToken(tokenRefs)).tokenAnalysisLinks,
+      ({ token }) => token.tokenRef,
+    ),
+    ...breaches(
+      await repository.findLinksBySegment(segmentIds),
+      await buffer.findLinksBySegment(segmentIds),
+      ({ segmentId }) => segmentId,
+    ),
+  ];
+  if (found.length > 0) throw new ApprovalRuleError(found);
+}
diff --git a/src/services/commands/changeBuffer.ts b/src/services/commands/changeBuffer.ts
new file mode 100644
index 000000000..5a5392fa5
--- /dev/null
+++ b/src/services/commands/changeBuffer.ts
@@ -0,0 +1,214 @@
+import type {
+  PhraseAnalysis,
+  SegmentAnalysis,
+  SegmentAnalysisLink,
+  TextAnalysis,
+  TokenAnalysis,
+} from 'interlinearizer';
+import type { AnalysisLinks, AnalysisRepository, ChangeSet } from '../../types/analysis-repository';
+import { normalizeSurfaceForm } from '../../utils/analysis-identity';
+import { jsonCopy } from '../../utils/json-copy';
+
+/** A record kind, named as {@link TextAnalysis} names its list. */
+export type RecordKind = keyof TextAnalysis;
+
+/** A record of one kind. */
+export type RecordOf<Kind extends RecordKind> = TextAnalysis[Kind][number];
+
+/** One kind's staged changes. */
+type Staged<T> = {
+  /** Records to store, by id. */
+  puts: Map<string, T>;
+  /** Records to remove, as they stood before the removal, by id. */
+  deletes: Map<string, T>;
+  /** Ids of the staged puts that no stored record shares, so removing one stages nothing. */
+  created: Set<string>;
+};
+
+function emptyStaged<T>(): Staged<T> {
+  return { puts: new Map(), deletes: new Map(), created: new Set() };
+}
+
+/**
+ * Changes a command stages before they apply, over a repository it reads through. Every read
+ * answers as the repository would once the staged changes applied, and hands out copies the command
+ * may change before staging them.
+ */
+export class ChangeBuffer {
+  private readonly repository: AnalysisRepository;
+
+  private readonly staged: { [Kind in RecordKind]: Staged<RecordOf<Kind>> } = {
+    segmentAnalyses: emptyStaged(),
+    segmentAnalysisLinks: emptyStaged(),
+    tokenAnalyses: emptyStaged(),
+    tokenAnalysisLinks: emptyStaged(),
+    phraseAnalyses: emptyStaged(),
+    phraseAnalysisLinks: emptyStaged(),
+  };
+
+  constructor(repository: AnalysisRepository) {
+    this.repository = repository;
+  }
+
+  /** The token analyses stored under `ids` once the staged changes apply. */
+  async getTokenAnalyses(ids: string[]): Promise<TokenAnalysis[]> {
+    const wanted = new Set(ids);
+    const stored = await this.repository.getTokenAnalyses(ids);
+    return this.overlay('tokenAnalyses', stored, ({ id }) => wanted.has(id));
+  }
+
+  /** The phrase analyses stored under `ids` once the staged changes apply. */
+  async getPhraseAnalyses(ids: string[]): Promise<PhraseAnalysis[]> {
+    const wanted = new Set(ids);
+    const stored = await this.repository.getPhraseAnalyses(ids);
+    return this.overlay('phraseAnalyses', stored, ({ id }) => wanted.has(id));
+  }
+
+  /** The segment analyses stored under `ids` once the staged changes apply. */
+  async getSegmentAnalyses(ids: string[]): Promise<SegmentAnalysis[]> {
+    const wanted = new Set(ids);
+    const stored = await this.repository.getSegmentAnalyses(ids);
+    return this.overlay('segmentAnalyses', stored, ({ id }) => wanted.has(id));
+  }
+
+  /**
+   * The token links on the tokens `tokenRefs` names, and the phrase links touching any of them,
+   * once the staged changes apply.
+   */
+  async findLinksByToken(
+    tokenRefs: string[],
+  ): Promise<Pick<AnalysisLinks, 'tokenAnalysisLinks' | 'phraseAnalysisLinks'>> {
+    const wanted = new Set(tokenRefs);
+    const stored = await this.repository.findLinksByToken(tokenRefs);
+    return {
+      tokenAnalysisLinks: this.overlay('tokenAnalysisLinks', stored.tokenAnalysisLinks, (link) =>
+        wanted.has(link.token.tokenRef),
+      ),
+      phraseAnalysisLinks: this.overlay('phraseAnalysisLinks', stored.phraseAnalysisLinks, (link) =>
+        link.tokens.some(({ tokenRef }) => wanted.has(tokenRef)),
+      ),
+    };
+  }
+
+  /** The segment links on the segments `segmentIds` names once the staged changes apply. */
+  async findLinksBySegment(segmentIds: string[]): Promise<SegmentAnalysisLink[]> {
+    const wanted = new Set(segmentIds);
+    const stored = await this.repository.findLinksBySegment(segmentIds);
+    return this.overlay('segmentAnalysisLinks', stored, (link) => wanted.has(link.segmentId));
+  }
+
+  /** The links of every kind to the analyses `analysisIds` names once the staged changes apply. */
+  async findLinksToAnalyses(analysisIds: string[]): Promise<AnalysisLinks> {
+    const wanted = new Set(analysisIds);
+    const stored = await this.repository.findLinksToAnalyses(analysisIds);
+    const linksTo = ({ analysisId }: { analysisId: string }) => wanted.has(analysisId);
+    return {
+      tokenAnalysisLinks: this.overlay('tokenAnalysisLinks', stored.tokenAnalysisLinks, linksTo),
+      phraseAnalysisLinks: this.overlay('phraseAnalysisLinks', stored.phraseAnalysisLinks, linksTo),
+      segmentAnalysisLinks: this.overlay(
+        'segmentAnalysisLinks',
+        stored.segmentAnalysisLinks,
+        linksTo,
+      ),
+    };
+  }
+
+  /**
+   * The token analyses whose surface text normalizes to one of `normalizedForms` once the staged
+   * changes apply.
+   */
+  async findTokenAnalysesByForm(normalizedForms: string[]): Promise<TokenAnalysis[]> {
+    const wanted = new Set(normalizedForms);
+    const stored = await this.repository.findTokenAnalysesByForm(normalizedForms);
+    return this.overlay('tokenAnalyses', stored, ({ surfaceText }) =>
+      wanted.has(normalizeSurfaceForm(surfaceText)),
+    );
+  }
+
+  /**
+   * The phrase analyses whose surface text normalizes to one of `normalizedForms` once the staged
+   * changes apply.
+   */
+  async findPhraseAnalysesByForm(normalizedForms: string[]): Promise<PhraseAnalysis[]> {
+    const wanted = new Set(normalizedForms);
+    const stored = await this.repository.findPhraseAnalysesByForm(normalizedForms);
+    return this.overlay('phraseAnalyses', stored, ({ surfaceText }) =>
+      wanted.has(normalizeSurfaceForm(surfaceText)),
+    );
+  }
+
+  /** Stages a new record of `kind`, under an id no stored record has. */
+  create<Kind extends RecordKind>(kind: Kind, record: RecordOf<Kind>): void {
+    this.stagedOf(kind).created.add(record.id);
+    this.put(kind, record);
+  }
+
+  /** Stages `record` to be stored whole under its id. */
+  put<Kind extends RecordKind>(kind: Kind, record: RecordOf<Kind>): void {
+    const staged = this.stagedOf(kind);
+    staged.deletes.delete(record.id);
+    staged.puts.set(record.id, jsonCopy(record));
+  }
+
+  /** Stages `record`'s removal; removing one the buffer created stages nothing for it. */
+  delete<Kind extends RecordKind>(kind: Kind, record: RecordOf<Kind>): void {
+    const staged = this.stagedOf(kind);
+    staged.puts.delete(record.id);
+    if (staged.created.delete(record.id)) return;
+    staged.deletes.set(record.id, jsonCopy(record));
+  }
+
+  /** Every record of `kind` the staged changes put or remove, as each stood before or will stand. */
+  touched<Kind extends RecordKind>(kind: Kind): RecordOf<Kind>[] {
+    const staged = this.stagedOf(kind);
+    return [...staged.puts.values(), ...staged.deletes.values()].map((record) => jsonCopy(record));
+  }
+
+  /** The staged changes as one change set; a kind with nothing staged is left out. */
+  toChangeSet(intent: string): ChangeSet {
+    const changes: ChangeSet = { intent };
+    const kinds: RecordKind[] = [
+      'segmentAnalyses',
+      'segmentAnalysisLinks',
+      'tokenAnalyses',
+      'tokenAnalysisLinks',
+      'phraseAnalyses',
+      'phraseAnalysisLinks',
+    ];
+    kinds.forEach((kind) => this.collect(changes, kind));
+    return changes;
+  }
+
+  /**
+   * `stored` as it stands once the staged changes of `kind` apply, keeping only the records
+   * `matches` accepts; `stored` must hold every stored record `matches` accepts.
+   */
+  private overlay<Kind extends RecordKind>(
+    kind: Kind,
+    stored: readonly RecordOf<Kind>[],
+    matches: (record: RecordOf<Kind>) => boolean,
+  ): RecordOf<Kind>[] {
+    const staged = this.stagedOf(kind);
+    const latest = new Map<string, RecordOf<Kind>>();
+    stored.forEach((record) => {
+      if (!staged.deletes.has(record.id)) latest.set(record.id, record);
+    });
+    staged.puts.forEach((record, id) => latest.set(id, record));
+    return [...latest.values()].filter(matches).map((record) => jsonCopy(record));
+  }
+
+  private collect<Kind extends RecordKind>(changes: ChangeSet, kind: Kind): void {
+    const { puts, deletes } = this.stagedOf(kind);
+    if (puts.size === 0 && deletes.size === 0) return;
+    Object.assign(changes, {
+      [kind]: {
+        puts: [...puts.values()].map((record) => jsonCopy(record)),
+        deletes: [...deletes.keys()],
+      },
+    });
+  }
+
+  private stagedOf<Kind extends RecordKind>(kind: Kind): Staged<RecordOf<Kind>> {
+    return this.staged[kind];
+  }
+}
diff --git a/src/services/commands/tokenCommands.ts b/src/services/commands/tokenCommands.ts
new file mode 100644
index 000000000..a1921ad4e
--- /dev/null
+++ b/src/services/commands/tokenCommands.ts
@@ -0,0 +1,291 @@
+import type { TokenAnalysis, TokenAnalysisLink } from 'interlinearizer';
+import { analysesAreIdentical, normalizeSurfaceForm } from '../../utils/analysis-identity';
+import { preferredLink, preferredPayload } from '../../utils/pick-rules';
+import { clearAnalysisGloss, isEmptyTokenAnalysis } from '../../utils/token-analysis-content';
+import type { ChangeBuffer } from './changeBuffer';
+
+/** Where and when a token edit lands. */
+type TokenEdit = {
+  /** `Token.ref` of the token edited. */
+  tokenRef: string;
+  /** The token's current surface text, refreshed on the records the edit touches. */
+  surfaceText: string;
+  /** ISO 8601 time of the edit, stamped on the records it touches. */
+  now: string;
+  /** Id a new link takes, spent only when the edit makes one. */
+  linkId: string;
+};
+
+/** What writing a token's gloss needs. */
+export type WriteGlossRequest = TokenEdit & {
+  /** The gloss; blank clears the token's gloss in `analysisLanguage`. */
+  value: string;
+  /** BCP 47 tag of the language the gloss is written in. */
+  analysisLanguage: string;
+  /** Id a new token analysis takes, spent only when the write makes one. */
+  analysisId: string;
+};
+
+/** What approving a stored analysis for a token needs. */
+export type ApproveAnalysisRequest = TokenEdit & {
+  /** The stored token analysis to approve. */
+  analysisId: string;
+};
+
+/**
+ * The token's approved link an approval tie picks, with its payload. Approved links naming no
+ * stored payload are removed first, so they never persist or crowd the pick.
+ */
+async function resolveApprovedAnalysis(
+  buffer: ChangeBuffer,
+  tokenRef: string,
+): Promise<{ link: TokenAnalysisLink; analysis: TokenAnalysis } | undefined> {
+  const { tokenAnalysisLinks } = await buffer.findLinksByToken([tokenRef]);
+  const approved = tokenAnalysisLinks.filter(({ status }) => status === 'approved');
+  const payloads = new Map(
+    (await buffer.getTokenAnalyses(approved.map(({ analysisId }) => analysisId))).map(
+      (analysis) => [analysis.id, analysis],
+    ),
+  );
+  approved
+    .filter(({ analysisId }) => !payloads.has(analysisId))
+    .forEach((orphan) => buffer.delete('tokenAnalysisLinks', orphan));
+  const link = preferredLink(approved.filter(({ analysisId }) => payloads.has(analysisId)));
+  const analysis = link && payloads.get(link.analysisId);
+  return link && analysis ? { link, analysis } : undefined;
+}
+
+/** Whether a token other than `link`'s links the payload `analysisId`, at any status. */
+async function isSharedByOtherTokens(
+  buffer: ChangeBuffer,
+  link: TokenAnalysisLink,
+  analysisId: string,
+): Promise<boolean> {
+  const { tokenAnalysisLinks } = await buffer.findLinksToAnalyses([analysisId]);
+  return tokenAnalysisLinks.some(({ token }) => token.tokenRef !== link.token.tokenRef);
+}
+
+/**
+ * Moves `link` onto a private copy of its shared payload, so an edit aimed at its token leaves the
+ * others reading what they did. The copy is dated by the edit, being a record of its own.
+ *
+ * @returns The copy, staged; `link` is repointed but left for the caller to stage.
+ */
+function forkSharedAnalysis(
+  buffer: ChangeBuffer,
+  link: TokenAnalysisLink,
+  analysis: TokenAnalysis,
+  forkId: string,
+  now: string,
+): TokenAnalysis {
+  const fork: TokenAnalysis = { ...analysis, id: forkId, createdAt: now, updatedAt: now };
+  buffer.create('tokenAnalyses', fork);
+  link.analysisId = forkId;
+  return fork;
+}
+
+/**
+ * Approves the non-approved link `tokenRef` holds to `analysisId`, so a token taking on a record it
+ * was offered keeps one link to it. The link keeps its creation date and `confidence`.
+ *
+ * @returns The approved link, staged, or `undefined` when the token holds no such link.
+ */
+async function approveHeldLink(
+  buffer: ChangeBuffer,
+  tokenRef: string,
+  analysisId: string,
+  surfaceText: string,
+  now: string,
+): Promise<TokenAnalysisLink | undefined> {
+  const { tokenAnalysisLinks } = await buffer.findLinksByToken([tokenRef]);
+  const held = preferredLink(
+    tokenAnalysisLinks.filter((l) => l.status !== 'approved' && l.analysisId === analysisId),
+  );
+  if (!held) return undefined;
+  held.status = 'approved';
+  held.token.surfaceText = surfaceText;
+  held.updatedAt = now;
+  buffer.put('tokenAnalysisLinks', held);
+  return held;
+}
+
+/** Removes the payload once no link of any status names it. */
+async function reclaimIfUnlinked(buffer: ChangeBuffer, analysis: TokenAnalysis): Promise<void> {
+  const { tokenAnalysisLinks } = await buffer.findLinksToAnalyses([analysis.id]);
+  if (tokenAnalysisLinks.length === 0) buffer.delete('tokenAnalyses', analysis);
+}
+
+/**
+ * Leaves each token holding one link to `analysisId` where it held several. The token keeps its
+ * approved link over any other, then the one an approval tie picks, and the survivor keeps the
+ * token's first annotation date.
+ */
+async function coalesceLinksPerToken(buffer: ChangeBuffer, analysisId: string): Promise<void> {
+  const { tokenAnalysisLinks } = await buffer.findLinksToAnalyses([analysisId]);
+  const byToken = new Map<string, TokenAnalysisLink[]>();
+  tokenAnalysisLinks.forEach((link) => {
+    byToken.set(link.token.tokenRef, [...(byToken.get(link.token.tokenRef) ?? []), link]);
+  });
+  byToken.forEach((links) => {
+    const kept =
+      preferredLink(links.filter(({ status }) => status === 'approved')) ?? preferredLink(links);
+    /* v8 ignore next -- every token's group holds a link */
+    if (!kept) return;
+    const createdAt = links.reduce(
+      (earliest, link) => (link.createdAt < earliest ? link.createdAt : earliest),
+      kept.createdAt,
+    );
+    links.forEach((link) => {
+      if (link !== kept) buffer.delete('tokenAnalysisLinks', link);
+    });
+    if (kept.createdAt !== createdAt) buffer.put('tokenAnalysisLinks', { ...kept, createdAt });
+  });
+}
+
+/**
+ * Folds the just-edited payload into a content-identical one where the edit made one, so an edit
+ * never leaves the duplicate a first write's find-or-create avoids. Every link to the edited
+ * payload moves to the survivor, which keeps its own timestamps, and a token linking both keeps one
+ * link. The survivor's breakdown stays stale only when both payloads' were.
+ */
+async function mergeIntoIdenticalPayload(
+  buffer: ChangeBuffer,
+  analysis: TokenAnalysis,
+  now: string,
+): Promise<void> {
+  const candidates = await buffer.findTokenAnalysesByForm([
+    normalizeSurfaceForm(analysis.surfaceText),
+  ]);
+  const other = preferredPayload(
+    candidates.filter((ta) => ta.id !== analysis.id && analysesAreIdentical(ta, analysis)),
+  );
+  if (!other) return;
+  if (other.morphemesStale && !analysis.morphemesStale) {
+    delete other.morphemesStale;
+    other.updatedAt = now;
+    buffer.put('tokenAnalyses', other);
+  }
+  const { tokenAnalysisLinks } = await buffer.findLinksToAnalyses([analysis.id]);
+  tokenAnalysisLinks.forEach((link) =>
+    buffer.put('tokenAnalysisLinks', { ...link, analysisId: other.id }),
+  );
+  await coalesceLinksPerToken(buffer, other.id);
+  buffer.delete('tokenAnalyses', analysis);
+}
+
+/**
+ * Links a token to an approved payload holding `analysis`'s content, sharing a content-identical
+ * stored one where there is one and staging `analysis` otherwise. A non-approved link the token
+ * holds to the shared payload is approved rather than joined by a second.
+ */
+async function appendApprovedAnalysis(
+  buffer: ChangeBuffer,
+  analysis: TokenAnalysis,
+  { tokenRef, now, linkId }: TokenEdit,
+): Promise<void> {
+  const candidates = await buffer.findTokenAnalysesByForm([
+    normalizeSurfaceForm(analysis.surfaceText),
+  ]);
+  const existing = preferredPayload(candidates.filter((ta) => analysesAreIdentical(ta, analysis)));
+  if (!existing) buffer.create('tokenAnalyses', analysis);
+  else if (await approveHeldLink(buffer, tokenRef, existing.id, analysis.surfaceText, now)) return;
+  buffer.create('tokenAnalysisLinks', {
+    id: linkId,
+    analysisId: existing?.id ?? analysis.id,
+    createdAt: now,
+    updatedAt: now,
+    status: 'approved',
+    token: { tokenRef, surfaceText: analysis.surfaceText },
+  });
+}
+
+/**
+ * Stages writing a token's gloss. The edit is per token: a payload other tokens share is forked
+ * first. An edit that makes the payload identical to another folds it in. A token with no approved
+ * analysis takes a content-identical stored one, or a new one. A blank value clears the gloss, and
+ * a payload left empty goes once nothing links it; a blank write to a token with no approved
+ * analysis stages nothing.
+ */
+export async function writeGloss(buffer: ChangeBuffer, request: WriteGlossRequest): Promise<void> {
+  const { tokenRef, surfaceText, value, analysisLanguage: lang, analysisId, now } = request;
+  const isBlank = value.trim() === '';
+
+  const resolved = await resolveApprovedAnalysis(buffer, tokenRef);
+  if (resolved) {
+    const { link, analysis } = resolved;
+    const target = (await isSharedByOtherTokens(buffer, link, analysis.id))
+      ? forkSharedAnalysis(buffer, link, analysis, analysisId, now)
+      : analysis;
+    target.surfaceText = surfaceText;
+    target.updatedAt = now;
+    link.token.surfaceText = surfaceText;
+    link.updatedAt = now;
+    if (isBlank) {
+      clearAnalysisGloss(target, lang);
+      if (isEmptyTokenAnalysis(target)) {
+        buffer.delete('tokenAnalysisLinks', link);
+        const { tokenAnalysisLinks } = await buffer.findLinksToAnalyses([target.id]);
+        if (tokenAnalysisLinks.length === 0) buffer.delete('tokenAnalyses', target);
+        else buffer.put('tokenAnalyses', target);
+        return;
+      }
+    } else {
+      target.gloss = { ...target.gloss, [lang]: value };
+      delete target.glossSenseRef;
+    }
+    buffer.put('tokenAnalyses', target);
+    buffer.put('tokenAnalysisLinks', link);
+    await mergeIntoIdenticalPayload(buffer, target, now);
+    return;
+  }
+
+  if (isBlank) return;
+  await appendApprovedAnalysis(
+    buffer,
+    { id: analysisId, createdAt: now, updatedAt: now, surfaceText, gloss: { [lang]: value } },
+    request,
+  );
+}
+
+/**
+ * Stages approving the stored payload `analysisId` for a token, in place of any approval it held.
+ * The payload that approval named goes once nothing links it. A token holding a non-approved link
+ * to the payload has that link approved, keeping the earlier creation date of the two; one holding
+ * neither gets a new link. It stages nothing for a payload not stored, or one already approved for
+ * the token.
+ */
+export async function approveAnalysisForToken(
+  buffer: ChangeBuffer,
+  { tokenRef, surfaceText, analysisId, now, linkId }: ApproveAnalysisRequest,
+): Promise<void> {
+  if ((await buffer.getTokenAnalyses([analysisId])).length === 0) return;
+  const resolved = await resolveApprovedAnalysis(buffer, tokenRef);
+  if (resolved?.link.analysisId === analysisId) return;
+
+  const pending = await approveHeldLink(buffer, tokenRef, analysisId, surfaceText, now);
+  if (pending) {
+    if (resolved) {
+      if (resolved.link.createdAt < pending.createdAt) {
+        buffer.put('tokenAnalysisLinks', { ...pending, createdAt: resolved.link.createdAt });
+      }
+      buffer.delete('tokenAnalysisLinks', resolved.link);
+    }
+  } else if (resolved) {
+    const { link } = resolved;
+    link.analysisId = analysisId;
+    link.token.surfaceText = surfaceText;
+    link.updatedAt = now;
+    buffer.put('tokenAnalysisLinks', link);
+  } else {
+    buffer.create('tokenAnalysisLinks', {
+      id: linkId,
+      analysisId,
+      createdAt: now,
+      updatedAt: now,
+      status: 'approved',
+      token: { tokenRef, surfaceText },
+    });
+  }
+
+  if (resolved) await reclaimIfUnlinked(buffer, resolved.analysis);
+}
diff --git a/src/services/draftRepository.ts b/src/services/draftRepository.ts
index 898fe3969..d3b7c5fea 100644
--- a/src/services/draftRepository.ts
+++ b/src/services/draftRepository.ts
@@ -23,7 +23,7 @@ import { applyChangeSet } from '../utils/change-set';
 import { jsonCopy } from '../utils/json-copy';
 import { perfTime, perfTimeAsync, perfTimeAsyncExcluding } from '../utils/perf-marks';
 import { AnalysisIndex } from './analysisIndex';
-import { IndexedRepository, type IndexedAnalysis } from './indexedRepository';
+import { IndexedRepository, type IndexedDraft } from './indexedRepository';
 import { draftAnalysisKey, draftJournalKey, draftKey } from './storageKeys';
 
 /**
@@ -136,7 +136,7 @@ export class DraftRepository extends IndexedRepository implements AnalysisReposi
    * index over its records. Dropped by every load and every whole save, since either may come from
    * a caller holding another draft.
    */
-  private current: { draft: DraftProject; index: AnalysisIndex } | undefined;
+  private current: IndexedDraft | undefined;
 
   constructor(storage: KeyValueStorage, sourceProjectId: string, logger: WarningLogger) {
     super();
@@ -269,7 +269,7 @@ export class DraftRepository extends IndexedRepository implements AnalysisReposi
    *   is left as it was.
    */
   async apply(changes: ChangeSet): Promise<ApplyResult> {
-    const { draft: base, index } = await this.keptDraft();
+    const { draft: base, index } = await this.indexed();
     const copied = jsonCopy(changes);
     const { draft, inverse } = applyChangeSet(base, copied);
     await this.writeDraft(draft, undefined, { refuseUnreadable: true });
@@ -278,20 +278,8 @@ export class DraftRepository extends IndexedRepository implements AnalysisReposi
     return { inverse };
   }
 
-  protected async indexed(): Promise<AnalysisIndex> {
-    return (await this.keptDraft()).index;
-  }
-
-  protected keptIndex(): IndexedAnalysis | undefined {
-    return this.current && { analysis: this.current.draft.analysis, index: this.current.index };
-  }
-
-  /**
-   * The draft this instance keeps, loaded from storage first when it keeps none.
-   *
-   * @throws Whatever {@link exportAll} throws.
-   */
-  private async keptDraft(): Promise<{ draft: DraftProject; index: AnalysisIndex }> {
+  /** @throws Whatever {@link exportAll} throws. */
+  protected async indexed(): Promise<IndexedDraft> {
     if (!this.current) {
       const { draft } = await this.exportAll();
       this.current = { draft, index: new AnalysisIndex(draft.analysis) };
@@ -299,6 +287,10 @@ export class DraftRepository extends IndexedRepository implements AnalysisReposi
     return this.current;
   }
 
+  protected keptIndex(): IndexedDraft | undefined {
+    return this.current;
+  }
+
   /**
    * Saves `draft` as {@link replaceAll} describes.
    *
diff --git a/src/services/indexedRepository.ts b/src/services/indexedRepository.ts
index d8b774446..92569a54a 100644
--- a/src/services/indexedRepository.ts
+++ b/src/services/indexedRepository.ts
@@ -1,28 +1,31 @@
 import type {
   AssignmentStatus,
+  DraftProject,
   PhraseAnalysis,
   SegmentAnalysis,
   SegmentAnalysisLink,
-  TextAnalysis,
   TokenAnalysis,
 } from 'interlinearizer';
 import type {
   AnalysisLinks,
   AnalysisRepository,
   IndexDifference,
+  ScopeRecord,
 } from '../types/analysis-repository';
+import { scopeRecordOf } from '../utils/change-set';
 import { jsonCopy } from '../utils/json-copy';
 import type { AnalysisIndex } from './analysisIndex';
 
-/** An index, with the analysis whose records it is kept over. */
-export type IndexedAnalysis = {
-  analysis: TextAnalysis;
+/** An index, with the draft whose records it is kept over. */
+export type IndexedDraft = {
+  draft: DraftProject;
   index: AnalysisIndex;
 };
 
-/** The lookups of a repository that answers them from an {@link AnalysisIndex} over its records. */
+/** The reads of a repository that answers them from an {@link AnalysisIndex} over its records. */
 export abstract class IndexedRepository implements Pick<
   AnalysisRepository,
+  | 'getScope'
   | 'getTokenAnalyses'
   | 'getPhraseAnalyses'
   | 'getSegmentAnalyses'
@@ -34,6 +37,10 @@ export abstract class IndexedRepository implements Pick<
   | 'findPhraseAnalysesByForm'
   | 'checkIndexes'
 > {
+  async getScope(): Promise<ScopeRecord> {
+    return jsonCopy(scopeRecordOf((await this.indexed()).draft));
+  }
+
   getTokenAnalyses(ids: string[]): Promise<TokenAnalysis[]> {
     return this.query((index) => index.getTokenAnalyses(ids));
   }
@@ -75,21 +82,21 @@ export abstract class IndexedRepository implements Pick<
   /** Reports nothing while no index is kept. */
   async checkIndexes(): Promise<IndexDifference[]> {
     const kept = this.keptIndex();
-    return kept ? kept.index.differencesFrom(kept.analysis) : [];
+    return kept ? kept.index.differencesFrom(kept.draft.analysis) : [];
   }
 
   /** Answers `read` from the kept index, with copies of the records it finds. */
   private async query<T>(read: (index: AnalysisIndex) => T): Promise<T> {
-    return jsonCopy(read(await this.indexed()));
+    return jsonCopy(read((await this.indexed()).index));
   }
 
   /**
-   * The kept index, built over the stored records first when none is kept.
+   * The kept index and its draft, loaded from storage first when none is kept.
    *
    * @throws Whatever loading the stored records throws.
    */
-  protected abstract indexed(): Promise<AnalysisIndex>;
+  protected abstract indexed(): Promise<IndexedDraft>;
 
-  /** The kept index and the analysis it is kept over, or `undefined` when none is kept. */
-  protected abstract keptIndex(): IndexedAnalysis | undefined;
+  /** The kept index and the draft it is kept over, or `undefined` when none is kept. */
+  protected abstract keptIndex(): IndexedDraft | undefined;
 }
diff --git a/src/services/projectStorage.ts b/src/services/projectStorage.ts
index 185bf6ed0..519c97a6e 100644
--- a/src/services/projectStorage.ts
+++ b/src/services/projectStorage.ts
@@ -1133,6 +1133,7 @@ export function openDraftRepository(
     replaceAll: (draft, options) => counted((repository) => repository.replaceAll(draft, options)),
     markClean: () => queued((repository) => repository.markClean()),
     apply: (changes) => counted((repository) => repository.apply(changes)),
+    getScope: () => queued((repository) => repository.getScope()),
     getTokenAnalyses: (ids) => queued((repository) => repository.getTokenAnalyses(ids)),
     getPhraseAnalyses: (ids) => queued((repository) => repository.getPhraseAnalyses(ids)),
     getSegmentAnalyses: (ids) => queued((repository) => repository.getSegmentAnalyses(ids)),
diff --git a/src/services/pt9ImportRepository.ts b/src/services/pt9ImportRepository.ts
index 4ef0c3494..fa4fc8be9 100644
--- a/src/services/pt9ImportRepository.ts
+++ b/src/services/pt9ImportRepository.ts
@@ -8,7 +8,7 @@ import type {
 import { CURRENT_MODEL_VERSION } from '../types/model-version';
 import { ReadOnlyAnalysisError } from '../types/read-only-analysis-error';
 import { AnalysisIndex } from './analysisIndex';
-import { IndexedRepository, type IndexedAnalysis } from './indexedRepository';
+import { IndexedRepository, type IndexedDraft } from './indexedRepository';
 
 /**
  * A Paratext 9 import's analysis, read in a draft's shape. Only a sync replaces an import's
@@ -22,7 +22,7 @@ export class Pt9ImportRepository extends IndexedRepository implements AnalysisRe
   private readonly readProject: () => Promise<InterlinearProject | undefined>;
 
   /** The import as a lookup last read it, with the index over its records; dropped by every load. */
-  private loaded: IndexedAnalysis | undefined;
+  private loaded: IndexedDraft | undefined;
 
   /**
    * @param interlinearProjectId - Id of the project to read, which must be a Paratext 9 import.
@@ -75,15 +75,16 @@ export class Pt9ImportRepository extends IndexedRepository implements AnalysisRe
     throw this.readOnlyError();
   }
 
-  protected async indexed(): Promise<AnalysisIndex> {
+  /** @throws Whatever {@link exportAll} throws. */
+  protected async indexed(): Promise<IndexedDraft> {
     if (!this.loaded) {
-      const { analysis } = await this.readImport();
-      this.loaded = { analysis, index: new AnalysisIndex(analysis) };
+      const draft = await this.readImport();
+      this.loaded = { draft, index: new AnalysisIndex(draft.analysis) };
     }
-    return this.loaded.index;
+    return this.loaded;
   }
 
-  protected keptIndex(): IndexedAnalysis | undefined {
+  protected keptIndex(): IndexedDraft | undefined {
     return this.loaded;
   }
 
diff --git a/src/store/analysisSlice.ts b/src/store/analysisSlice.ts
index f2635e7b4..49e5b8e38 100644
--- a/src/store/analysisSlice.ts
+++ b/src/store/analysisSlice.ts
@@ -22,6 +22,7 @@ import {
 import { buildCatalogRows, type HeadingPlacement } from '../utils/analysis-query';
 import type { StaleFreeTranslation } from '../utils/stale-free-translations';
 import { isEmptyMultiString } from '../utils/multi-string';
+import { clearAnalysisGloss, isEmptyTokenAnalysis } from '../utils/token-analysis-content';
 import {
   preferredLink,
   preferredLinkByKey,
@@ -868,46 +869,6 @@ function writeGlossOntoAnalysis(
   mergeIntoIdenticalPayload(state, analysis, now);
 }
 
-/**
- * Determines whether a `TokenAnalysis` carries no analysis content, so a reducer that just emptied
- * one field can decide to drop the whole record instead of letting empty records accumulate in
- * storage. Checks every content field of the type — `gloss`, `morphemes`, `pos`, `features`, and
- * `glossSenseRef` — not only the field the caller emptied, so records carrying imported
- * morphosyntactic or lexicon data are never discarded by an unrelated edit. A gloss counts as empty
- * when it has no entries or every entry is blank, so a record left holding only whitespace glosses
- * (junk from clearing a gloss field) is treated the same as one with no gloss at all.
- *
- * Provenance fields (`confidence`, `producer`, `sourceUser`) are intentionally NOT treated as
- * content: they describe who/what produced an analysis, not an analysis worth keeping on their own.
- * A record holding only provenance and no glosses/morphemes/pos/features is therefore considered
- * empty and may be dropped when its last content field is cleared. This is a deliberate choice — if
- * a future workflow needs provenance-only records (e.g. imported parser metadata) to survive a
- * gloss clear, add the relevant fields to the check below.
- */
-function isEmptyTokenAnalysis(analysis: TokenAnalysis): boolean {
-  return (
-    isEmptyMultiString(analysis.gloss) &&
-    /* v8 ignore next -- the length===0 sub-branch needs an empty-but-defined morphemes array, which no caller produces */
-    (!analysis.morphemes || analysis.morphemes.length === 0) &&
-    analysis.pos === undefined &&
-    analysis.features === undefined &&
-    analysis.glossSenseRef === undefined
-  );
-}
-
-/**
- * Empties one language's gloss, dropping the gloss and the analysis-wide `glossSenseRef` once no
- * language is left holding usable text — a sibling left holding only whitespace counts for neither,
- * so the sense is never stranded on a gloss nothing renders.
- */
-function clearAnalysisGloss(analysis: TokenAnalysis, lang: string): void {
-  if (analysis.gloss) {
-    delete analysis.gloss[lang];
-    if (isEmptyMultiString(analysis.gloss)) delete analysis.gloss;
-  }
-  if (!analysis.gloss) delete analysis.glossSenseRef;
-}
-
 /**
  * The annotated forms a re-split to `forms` would strand: those whose morpheme carries a gloss or a
  * lexicon reference and which the new breakdown leaves no morpheme to hold, in the order the old
diff --git a/src/types/analysis-repository.ts b/src/types/analysis-repository.ts
index fc198ebe3..71b6fe6dc 100644
--- a/src/types/analysis-repository.ts
+++ b/src/types/analysis-repository.ts
@@ -197,6 +197,13 @@ export interface AnalysisRepository {
    */
   apply(changes: ChangeSet): Promise<ApplyResult>;
 
+  /**
+   * The draft's own record, as {@link exportAll} would load it without its analysis.
+   *
+   * @throws Whatever {@link exportAll} throws.
+   */
+  getScope(): Promise<ScopeRecord>;
+
   /** The token analyses stored under `ids`; an id with none stored under it is skipped. */
   getTokenAnalyses(ids: string[]): Promise<TokenAnalysis[]>;
 
diff --git a/src/types/interlinearizer.d.ts b/src/types/interlinearizer.d.ts
index b7be3e07c..8355e47de 100644
--- a/src/types/interlinearizer.d.ts
+++ b/src/types/interlinearizer.d.ts
@@ -390,6 +390,34 @@ declare module 'papi-shared-types' {
      */
     'interlinearizer.checkIndexes': (sessionId: string) => Promise<string>;
 
+    /**
+     * Writes a token's gloss in a session's analysis language; a blank value clears it.
+     *
+     * @returns A JSON string of the changes it applied.
+     * @throws If the session is read-only or not open, or the edit is refused or fails (logged
+     *   before rethrowing).
+     */
+    'interlinearizer.writeGloss': (
+      sessionId: string,
+      tokenRef: string,
+      surfaceText: string,
+      value: string,
+    ) => Promise<string>;
+
+    /**
+     * Approves a stored token analysis for a token, in place of any approval it held.
+     *
+     * @returns A JSON string of the changes it applied.
+     * @throws If the session is read-only or not open, or the edit is refused or fails (logged
+     *   before rethrowing).
+     */
+    'interlinearizer.approveAnalysisForToken': (
+      sessionId: string,
+      tokenRef: string,
+      surfaceText: string,
+      analysisId: string,
+    ) => Promise<string>;
+
     /**
      * Turns the extension host's timing entries on or off, discarding any it holds. Off until
      * turned on.
diff --git a/src/utils/change-set.ts b/src/utils/change-set.ts
index d90e176fc..eab3001d9 100644
--- a/src/utils/change-set.ts
+++ b/src/utils/change-set.ts
@@ -7,6 +7,11 @@ export type AppliedChanges = {
   inverse: ChangeSet;
 };
 
+/** Whether `changes` change no record, the scope's record included. */
+export function isEmptyChangeSet(changes: ChangeSet): boolean {
+  return Object.keys(changes).every((key) => key === 'intent');
+}
+
 /** The draft's record, without its analysis or its `dirty` flag. */
 // eslint-disable-next-line @typescript-eslint/no-unused-vars -- named only to leave them out
 export function scopeRecordOf({ analysis, dirty, ...scope }: DraftProject): ScopeRecord {
diff --git a/src/utils/token-analysis-content.ts b/src/utils/token-analysis-content.ts
new file mode 100644
index 000000000..81f65e855
--- /dev/null
+++ b/src/utils/token-analysis-content.ts
@@ -0,0 +1,42 @@
+import type { TokenAnalysis } from 'interlinearizer';
+import { isEmptyMultiString } from './multi-string';
+
+/**
+ * Determines whether a `TokenAnalysis` carries no analysis content, so an edit that just emptied
+ * one field can drop the whole record instead of letting empty records accumulate in storage.
+ * Checks every content field of the type — `gloss`, `morphemes`, `pos`, `features`, and
+ * `glossSenseRef` — not only the field the caller emptied, so records carrying imported
+ * morphosyntactic or lexicon data are never discarded by an unrelated edit. A gloss counts as empty
+ * when it has no entries or every entry is blank, so a record left holding only whitespace glosses
+ * (junk from clearing a gloss field) is treated the same as one with no gloss at all.
+ *
+ * Provenance fields (`confidence`, `producer`, `sourceUser`) are intentionally NOT treated as
+ * content: they describe who/what produced an analysis, not an analysis worth keeping on their own.
+ * A record holding only provenance and no glosses/morphemes/pos/features is therefore considered
+ * empty and may be dropped when its last content field is cleared. This is a deliberate choice — if
+ * a future workflow needs provenance-only records (e.g. imported parser metadata) to survive a
+ * gloss clear, add the relevant fields to the check below.
+ */
+export function isEmptyTokenAnalysis(analysis: TokenAnalysis): boolean {
+  return (
+    isEmptyMultiString(analysis.gloss) &&
+    /* v8 ignore next -- the length===0 sub-branch needs an empty-but-defined morphemes array, which no caller produces */
+    (!analysis.morphemes || analysis.morphemes.length === 0) &&
+    analysis.pos === undefined &&
+    analysis.features === undefined &&
+    analysis.glossSenseRef === undefined
+  );
+}
+
+/**
+ * Empties one language's gloss, dropping the gloss and the analysis-wide `glossSenseRef` once no
+ * language is left holding usable text — a sibling left holding only whitespace counts for neither,
+ * so the sense is never stranded on a gloss nothing renders.
+ */
+export function clearAnalysisGloss(analysis: TokenAnalysis, lang: string): void {
+  if (analysis.gloss) {
+    delete analysis.gloss[lang];
+    if (isEmptyMultiString(analysis.gloss)) delete analysis.gloss;
+  }
+  if (!analysis.gloss) delete analysis.glossSenseRef;
+}

From 689bd3c0de7508b5e838aa3f474db513c6328a6a Mon Sep 17 00:00:00 2001
From: Alex Rawlings <alex.rawlings@wycliffe.ca>
Date: Fri, 23 Oct 2026 15:08:08 -0600
Subject: [PATCH 14/22] Add token commands with parity tests (#443)

---
 AGENTS.md                                     |   2 +
 .../analysis-repository-conformance.ts        |  21 +
 src/__tests__/main.test.ts                    |  58 ++
 .../services/analysisSessions.test.ts         |  81 +++
 .../services/commands/approvalRule.test.ts    |  92 +++
 .../services/commands/changeBuffer.test.ts    | 192 ++++++
 src/__tests__/services/commands/parity.ts     |  75 +++
 .../commands/tokenCommands.parity.test.ts     | 548 ++++++++++++++++++
 .../services/commands/tokenCommands.test.ts   |  92 +++
 .../services/indexedRepository.test.ts        |  31 +-
 src/__tests__/services/projectStorage.test.ts |   5 +
 src/__tests__/utils/change-set.test.ts        |  18 +-
 .../utils/token-analysis-content.test.ts      |  59 ++
 src/main.ts                                   | 144 ++++-
 src/services/analysisSessions.ts              |  30 +
 src/services/commands/approvalRule.ts         |  69 +++
 src/services/commands/changeBuffer.ts         | 214 +++++++
 src/services/commands/tokenCommands.ts        | 291 ++++++++++
 src/services/draftRepository.ts               |  20 +-
 src/services/indexedRepository.ts             |  29 +-
 src/services/projectStorage.ts                |   1 +
 src/services/pt9ImportRepository.ts           |  20 +-
 src/store/analysisSlice.ts                    |  41 +-
 src/types/analysis-repository.ts              |   8 +
 src/types/interlinearizer.d.ts                |  28 +
 src/utils/change-set.ts                       |   5 +
 src/utils/token-analysis-content.ts           |  42 ++
 27 files changed, 2129 insertions(+), 87 deletions(-)
 create mode 100644 src/__tests__/services/commands/approvalRule.test.ts
 create mode 100644 src/__tests__/services/commands/changeBuffer.test.ts
 create mode 100644 src/__tests__/services/commands/parity.ts
 create mode 100644 src/__tests__/services/commands/tokenCommands.parity.test.ts
 create mode 100644 src/__tests__/services/commands/tokenCommands.test.ts
 create mode 100644 src/__tests__/utils/token-analysis-content.test.ts
 create mode 100644 src/services/commands/approvalRule.ts
 create mode 100644 src/services/commands/changeBuffer.ts
 create mode 100644 src/services/commands/tokenCommands.ts
 create mode 100644 src/utils/token-analysis-content.ts

diff --git a/AGENTS.md b/AGENTS.md
index 6e34f197c..2e6faaa78 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -88,6 +88,8 @@ Saved projects are listed through [ProjectSummaries](src/services/projectSummari
 
 [AnalysisSessions](src/services/analysisSessions.ts) keeps the host's sessions, behind the `openSession`, `closeSession` and `setAnalysisLanguage` commands. A session is a handle on one source project's draft, paired with the interlinear project it saves to, or on a Paratext 9 import alone, read-only. A source has at most one session: opening another closes it. Each session runs its commands one at a time, through `run`, or `runEdit` for a command that changes stored analysis, which a read-only session refuses. An edit reaches the repository as a `ChangeSet` of whole-record puts and deletes, applied through the session's [EditHistory](src/services/editHistory.ts) so that undo can revert it; boundary changes ride in the change set's scope record. The WebView doesn't use sessions yet.
 
+Host commands live in [src/services/commands/](src/services/commands/), one module per family. A command stages its changes in a [ChangeBuffer](src/services/commands/changeBuffer.ts), whose reads answer as the repository will once those changes apply, and `AnalysisSessions.edit` applies what it staged as one undo step after the approval rule passes. Each command copies the reducer it replaces, step for step, and its parity tests run one input through both with [runParity](src/__tests__/services/commands/parity.ts); a reducer change in Phase 3 updates its command and parity tests in the same PR.
+
 ### 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/src/__tests__/analysis-repository-conformance.ts b/src/__tests__/analysis-repository-conformance.ts
index b4a41e3f8..022aca122 100644
--- a/src/__tests__/analysis-repository-conformance.ts
+++ b/src/__tests__/analysis-repository-conformance.ts
@@ -1229,6 +1229,27 @@ export function describeAnalysisRepositoryConformance(
         return store.open(SOURCE);
       }
 
+      it("reads the draft's own record", async () => {
+        const repository = await overFullDraft();
+
+        await expect(repository.getScope()).resolves.toStrictEqual(scopeRecordOf(fullDraft()));
+      });
+
+      it("reads the record of a draft never saved as an empty draft's", async () => {
+        await expect((await store.open(SOURCE)).getScope()).resolves.toStrictEqual(
+          scopeRecordOf(emptyDraft(SOURCE)),
+        );
+      });
+
+      it('reads the record the applied changes leave', async () => {
+        const repository = await overFullDraft();
+        const scope = { ...scopeRecordOf(fullDraft()), analysisLanguages: ['de'] };
+
+        await repository.apply({ intent: 'rescope', scope });
+
+        await expect(repository.getScope()).resolves.toStrictEqual(scope);
+      });
+
       it('gets each payload kind by id, once per id, skipping ids with nothing stored', async () => {
         const repository = await overFullDraft();
 
diff --git a/src/__tests__/main.test.ts b/src/__tests__/main.test.ts
index b24169bbe..7973e5b8d 100644
--- a/src/__tests__/main.test.ts
+++ b/src/__tests__/main.test.ts
@@ -12,6 +12,7 @@ import * as projectStorage from '../services/projectStorage';
 import * as pt9ImportService from '../services/pt9ImportService';
 import { type AnalysisRepository, UnreadableBooksError } from '../types/analysis-repository';
 import { emptyDraft } from '../types/empty-factories';
+import { scopeRecordOf } from '../utils/change-set';
 import { toProjectSummary } from '../types/interlinear-project-summary';
 import { createTestActivationContext, makeStubProject } from './test-helpers';
 
@@ -401,6 +402,8 @@ describe('main', () => {
           'interlinearizer.undoEdit',
           'interlinearizer.redoEdit',
           'interlinearizer.checkIndexes',
+          'interlinearizer.writeGloss',
+          'interlinearizer.approveAnalysisForToken',
           'interlinearizer.openSelectProjectModal',
           'interlinearizer.openNewProjectModal',
           'interlinearizer.openProjectInfoModal',
@@ -1848,6 +1851,7 @@ describe('main', () => {
         checkIndexes: async () => [
           { index: 'tokenAnalyses', key: 'ta-1', missing: ['ta-1'], extra: [] },
         ],
+        getScope: async () => scopeRecordOf(draft),
       };
     }
 
@@ -1877,6 +1881,22 @@ describe('main', () => {
         checkIndexes: handler<(sessionId: string) => Promise<string>>(
           'interlinearizer.checkIndexes',
         ),
+        writeGloss: handler<
+          (
+            sessionId: string,
+            tokenRef: string,
+            surfaceText: string,
+            value: string,
+          ) => Promise<string>
+        >('interlinearizer.writeGloss'),
+        approveAnalysisForToken: handler<
+          (
+            sessionId: string,
+            tokenRef: string,
+            surfaceText: string,
+            analysisId: string,
+          ) => Promise<string>
+        >('interlinearizer.approveAnalysisForToken'),
       };
     }
 
@@ -2060,6 +2080,44 @@ describe('main', () => {
       );
     });
 
+    it("writes a token's gloss in the session's language, replying with the changes", async () => {
+      const { openSession, setAnalysisLanguage, writeGloss } = await activateSessionCommands();
+      const { sessionId } = JSON.parse(await openSession('src-project'));
+      await setAnalysisLanguage(sessionId, 'fr');
+
+      const changes = JSON.parse(await writeGloss(sessionId, 'GEN 1:1:0', 'In', 'au'));
+
+      expect(changes).toMatchObject({
+        intent: 'writeGloss',
+        tokenAnalyses: { puts: [{ surfaceText: 'In', gloss: { fr: 'au' } }], deletes: [] },
+        tokenAnalysisLinks: {
+          puts: [{ status: 'approved', token: { tokenRef: 'GEN 1:1:0', surfaceText: 'In' } }],
+          deletes: [],
+        },
+      });
+    });
+
+    it('logs the error and rethrows when an edit fails', async () => {
+      const { writeGloss } = await activateSessionCommands();
+
+      await expect(writeGloss('not-a-session', 'GEN 1:1:0', 'In', 'at')).rejects.toThrow(
+        'no session not-a-session is open',
+      );
+      expect(__mockLogger.error).toHaveBeenCalledWith(
+        'Interlinearizer: failed to writeGloss in session not-a-session',
+        expect.any(Error),
+      );
+    });
+
+    it('approves an analysis for a token, replying with the changes', async () => {
+      const { openSession, approveAnalysisForToken } = await activateSessionCommands();
+      const { sessionId } = JSON.parse(await openSession('src-project'));
+
+      await expect(
+        approveAnalysisForToken(sessionId, 'GEN 1:1:0', 'In', 'ta-unknown').then(JSON.parse),
+      ).resolves.toStrictEqual({ intent: 'approveAnalysisForToken' });
+    });
+
     it('closes every session on deactivation', async () => {
       const { openSession } = await activateSessionCommands();
       await openSession('src-project');
diff --git a/src/__tests__/services/analysisSessions.test.ts b/src/__tests__/services/analysisSessions.test.ts
index 0ebc62366..4862f4293 100644
--- a/src/__tests__/services/analysisSessions.test.ts
+++ b/src/__tests__/services/analysisSessions.test.ts
@@ -6,6 +6,7 @@ import {
   type SessionHost,
   UNDETERMINED_LANGUAGE,
 } from '../../services/analysisSessions';
+import { ApprovalRuleError } from '../../services/commands/approvalRule';
 import { DraftRepository } from '../../services/draftRepository';
 import { Pt9ImportRepository } from '../../services/pt9ImportRepository';
 import { draftKey } from '../../services/storageKeys';
@@ -477,6 +478,86 @@ describe('AnalysisSessions', () => {
     });
   });
 
+  describe('edit', () => {
+    const payload = (id: string) => ({ id, ...FIXTURE_STAMPS, surfaceText: id });
+    const approvedLink = (id: string) => ({
+      id,
+      analysisId: 'a',
+      ...FIXTURE_STAMPS,
+      status: 'approved' as const,
+      token: { tokenRef: 'GEN 1:1:0', surfaceText: 'a' },
+    });
+
+    /** The source project's draft as stored. */
+    const stored = async (storage: ReturnType<typeof makeSessions>['storage']) =>
+      (await new DraftRepository(storage, SOURCE, silentLogger()).exportAll()).draft;
+
+    it('applies what the command stages as one undo step, marking the draft dirty', async () => {
+      const { sessions, storage } = makeSessions();
+      const { sessionId } = await sessions.open(SOURCE);
+
+      const changes = await sessions.edit(sessionId, 'add', async (buffer) => {
+        buffer.create('tokenAnalyses', payload('a'));
+        buffer.create('tokenAnalyses', payload('b'));
+      });
+
+      expect(changes).toMatchObject({ intent: 'add' });
+      await expect(stored(storage)).resolves.toMatchObject({
+        dirty: true,
+        analysis: { tokenAnalyses: [payload('a'), payload('b')] },
+      });
+      await sessions.undo(sessionId);
+      await expect(stored(storage)).resolves.toMatchObject({ analysis: { tokenAnalyses: [] } });
+    });
+
+    it('applies nothing, and records no undo step, for a command staging nothing', async () => {
+      const { sessions, storage } = makeSessions();
+      const { sessionId } = await sessions.open(SOURCE);
+
+      await expect(sessions.edit(sessionId, 'nothing', async () => {})).resolves.toStrictEqual({
+        intent: 'nothing',
+      });
+
+      await expect(sessions.undo(sessionId)).resolves.toBeUndefined();
+      await expect(stored(storage)).resolves.toMatchObject({ dirty: false });
+    });
+
+    it('gives the command the session it runs on', async () => {
+      const { sessions } = makeSessions();
+      const { sessionId } = await sessions.open(SOURCE);
+      await sessions.setAnalysisLanguage(sessionId, 'fr');
+
+      await sessions.edit(sessionId, 'read', async (_buffer, session) => {
+        expect(session.analysisLanguage).toBe('fr');
+      });
+    });
+
+    it('refuses changes that would approve a second analysis for a token, applying nothing', async () => {
+      const { sessions, storage } = makeSessions();
+      const { sessionId } = await sessions.open(SOURCE);
+
+      await expect(
+        sessions.edit(sessionId, 'approveTwice', async (buffer) => {
+          buffer.create('tokenAnalysisLinks', approvedLink('l-1'));
+          buffer.create('tokenAnalysisLinks', approvedLink('l-2'));
+        }),
+      ).rejects.toThrow(ApprovalRuleError);
+
+      await expect(stored(storage)).resolves.toMatchObject({
+        analysis: { tokenAnalysisLinks: [] },
+      });
+    });
+
+    it("refuses an edit on a Paratext 9 import's session without running it", async () => {
+      const { sessions } = makeSessions([makeImport()]);
+      const { sessionId } = await sessions.open(SOURCE, 'import-id');
+      const command = jest.fn(async () => {});
+
+      await expect(sessions.edit(sessionId, 'add', command)).rejects.toThrow(ReadOnlyAnalysisError);
+      expect(command).not.toHaveBeenCalled();
+    });
+  });
+
   describe('setAnalysisLanguage', () => {
     it('sets the language the commands sent after it read', async () => {
       const { sessions } = makeSessions();
diff --git a/src/__tests__/services/commands/approvalRule.test.ts b/src/__tests__/services/commands/approvalRule.test.ts
new file mode 100644
index 000000000..3c37315dd
--- /dev/null
+++ b/src/__tests__/services/commands/approvalRule.test.ts
@@ -0,0 +1,92 @@
+/// <reference types="jest" />
+
+import type { SegmentAnalysisLink, TextAnalysis, TokenAnalysisLink } from 'interlinearizer';
+import { ApprovalRuleError, assertApprovalRule } from '../../../services/commands/approvalRule';
+import { ChangeBuffer } from '../../../services/commands/changeBuffer';
+import { DraftRepository } from '../../../services/draftRepository';
+import { emptyAnalysis, emptyDraft } from '../../../types/empty-factories';
+import { FIXTURE_STAMPS, memoryStorage, silentLogger } from '../../test-helpers';
+
+function tokenLink(
+  id: string,
+  status: TokenAnalysisLink['status'] = 'approved',
+): TokenAnalysisLink {
+  return {
+    id,
+    analysisId: `ta-${id}`,
+    ...FIXTURE_STAMPS,
+    status,
+    token: { tokenRef: 'GEN 1:1:0', surfaceText: 'In' },
+  };
+}
+
+function segmentLink(id: string): SegmentAnalysisLink {
+  return {
+    id,
+    analysisId: `sa-${id}`,
+    ...FIXTURE_STAMPS,
+    status: 'approved',
+    segmentId: 'GEN 1:1',
+  };
+}
+
+async function over(analysis: Partial<TextAnalysis>) {
+  const { storage } = memoryStorage();
+  const repository = new DraftRepository(storage, 'src', silentLogger());
+  await repository.replaceAll({
+    ...emptyDraft('src'),
+    analysis: { ...emptyAnalysis(), ...analysis },
+  });
+  return { repository, buffer: new ChangeBuffer(repository) };
+}
+
+describe('assertApprovalRule', () => {
+  it('accepts changes that leave each token one approval', async () => {
+    const { repository, buffer } = await over({ tokenAnalysisLinks: [tokenLink('a')] });
+
+    buffer.delete('tokenAnalysisLinks', tokenLink('a'));
+    buffer.create('tokenAnalysisLinks', tokenLink('b'));
+
+    await expect(assertApprovalRule(buffer, repository)).resolves.toBeUndefined();
+  });
+
+  it('refuses a second approval for a token', async () => {
+    const { repository, buffer } = await over({ tokenAnalysisLinks: [tokenLink('a')] });
+
+    buffer.create('tokenAnalysisLinks', tokenLink('b'));
+
+    await expect(assertApprovalRule(buffer, repository)).rejects.toThrow(
+      new ApprovalRuleError(['GEN 1:1:0']),
+    );
+  });
+
+  it('refuses a second approval for a segment', async () => {
+    const { repository, buffer } = await over({ segmentAnalysisLinks: [segmentLink('a')] });
+
+    buffer.create('segmentAnalysisLinks', segmentLink('b'));
+
+    await expect(assertApprovalRule(buffer, repository)).rejects.toThrow(ApprovalRuleError);
+  });
+
+  it('accepts changes that leave a stored breach no worse', async () => {
+    const { repository, buffer } = await over({
+      tokenAnalysisLinks: [tokenLink('a'), tokenLink('b'), tokenLink('c', 'suggested')],
+    });
+
+    buffer.put('tokenAnalysisLinks', { ...tokenLink('a'), updatedAt: '2026-06-01T00:00:00.000Z' });
+    buffer.put('tokenAnalysisLinks', tokenLink('c', 'rejected'));
+
+    await expect(assertApprovalRule(buffer, repository)).resolves.toBeUndefined();
+  });
+
+  it('names the places it refuses on the error', async () => {
+    const { repository, buffer } = await over({});
+
+    buffer.create('tokenAnalysisLinks', tokenLink('a'));
+    buffer.create('tokenAnalysisLinks', tokenLink('b'));
+
+    await expect(assertApprovalRule(buffer, repository)).rejects.toMatchObject({
+      places: ['GEN 1:1:0'],
+    });
+  });
+});
diff --git a/src/__tests__/services/commands/changeBuffer.test.ts b/src/__tests__/services/commands/changeBuffer.test.ts
new file mode 100644
index 000000000..b6862527b
--- /dev/null
+++ b/src/__tests__/services/commands/changeBuffer.test.ts
@@ -0,0 +1,192 @@
+/// <reference types="jest" />
+
+import type { TextAnalysis, TokenAnalysis, TokenAnalysisLink } from 'interlinearizer';
+import { ChangeBuffer } from '../../../services/commands/changeBuffer';
+import { DraftRepository } from '../../../services/draftRepository';
+import { emptyAnalysis, emptyDraft } from '../../../types/empty-factories';
+import { FIXTURE_STAMPS, makePhraseLink, memoryStorage, silentLogger } from '../../test-helpers';
+
+function payload(id: string, surfaceText = id): TokenAnalysis {
+  return { id, ...FIXTURE_STAMPS, surfaceText };
+}
+
+function link(id: string, analysisId: string, tokenRef: string): TokenAnalysisLink {
+  return {
+    id,
+    analysisId,
+    ...FIXTURE_STAMPS,
+    status: 'approved',
+    token: { tokenRef, surfaceText: 'In' },
+  };
+}
+
+/** A buffer over a draft holding `analysis`. */
+async function bufferOver(analysis: Partial<TextAnalysis> = {}): Promise<ChangeBuffer> {
+  const { storage } = memoryStorage();
+  const repository = new DraftRepository(storage, 'src', silentLogger());
+  await repository.replaceAll({
+    ...emptyDraft('src'),
+    analysis: { ...emptyAnalysis(), ...analysis },
+  });
+  return new ChangeBuffer(repository);
+}
+
+const ids = (records: readonly { id: string }[]) => records.map(({ id }) => id).sort();
+
+describe('ChangeBuffer', () => {
+  it('reads stored records as the repository does while nothing is staged', async () => {
+    const buffer = await bufferOver({
+      tokenAnalyses: [payload('ta-1')],
+      tokenAnalysisLinks: [link('tl-1', 'ta-1', 'GEN 1:1:0')],
+    });
+
+    await expect(buffer.getTokenAnalyses(['ta-1'])).resolves.toStrictEqual([payload('ta-1')]);
+    await expect(buffer.findLinksToAnalyses(['ta-1'])).resolves.toStrictEqual({
+      tokenAnalysisLinks: [link('tl-1', 'ta-1', 'GEN 1:1:0')],
+      phraseAnalysisLinks: [],
+      segmentAnalysisLinks: [],
+    });
+  });
+
+  it('answers with a staged put in place of the stored record', async () => {
+    const buffer = await bufferOver({ tokenAnalyses: [payload('ta-1')] });
+
+    buffer.put('tokenAnalyses', { ...payload('ta-1'), gloss: { en: 'one' } });
+
+    await expect(buffer.getTokenAnalyses(['ta-1'])).resolves.toStrictEqual([
+      { ...payload('ta-1'), gloss: { en: 'one' } },
+    ]);
+  });
+
+  it('leaves a staged removal out of every read', async () => {
+    const stored = link('tl-1', 'ta-1', 'GEN 1:1:0');
+    const buffer = await bufferOver({ tokenAnalysisLinks: [stored] });
+
+    buffer.delete('tokenAnalysisLinks', stored);
+
+    await expect(buffer.findLinksByToken(['GEN 1:1:0'])).resolves.toStrictEqual({
+      tokenAnalysisLinks: [],
+      phraseAnalysisLinks: [],
+    });
+  });
+
+  it('finds a record a staged put moves into a lookup, and not one it moves out', async () => {
+    const buffer = await bufferOver({
+      tokenAnalysisLinks: [link('tl-1', 'ta-1', 'GEN 1:1:0'), link('tl-2', 'ta-2', 'GEN 1:1:0')],
+    });
+
+    buffer.put('tokenAnalysisLinks', link('tl-1', 'ta-2', 'GEN 1:1:0'));
+
+    await expect(buffer.findLinksToAnalyses(['ta-1'])).resolves.toMatchObject({
+      tokenAnalysisLinks: [],
+    });
+    const { tokenAnalysisLinks } = await buffer.findLinksToAnalyses(['ta-2']);
+    expect(ids(tokenAnalysisLinks)).toStrictEqual(['tl-1', 'tl-2']);
+  });
+
+  it('answers every lookup through the staged changes', async () => {
+    const phrase = makePhraseLink('pa-1', ['GEN 1:1:0', 'GEN 1:1:3']);
+    const segmentLink = {
+      id: 'sl-1',
+      analysisId: 'sa-1',
+      ...FIXTURE_STAMPS,
+      status: 'approved' as const,
+      segmentId: 'GEN 1:1',
+    };
+    const buffer = await bufferOver({
+      phraseAnalyses: [{ id: 'pa-1', ...FIXTURE_STAMPS, surfaceText: 'In the' }],
+      phraseAnalysisLinks: [phrase],
+      segmentAnalyses: [{ id: 'sa-1', ...FIXTURE_STAMPS, surfaceText: 'In the beginning' }],
+      segmentAnalysisLinks: [segmentLink],
+    });
+
+    buffer.create('tokenAnalyses', payload('ta-new', 'In'));
+
+    await expect(buffer.findTokenAnalysesByForm(['in'])).resolves.toStrictEqual([
+      payload('ta-new', 'In'),
+    ]);
+    await expect(buffer.findPhraseAnalysesByForm(['in the']).then(ids)).resolves.toStrictEqual([
+      'pa-1',
+    ]);
+    await expect(buffer.getPhraseAnalyses(['pa-1']).then(ids)).resolves.toStrictEqual(['pa-1']);
+    await expect(buffer.getSegmentAnalyses(['sa-1']).then(ids)).resolves.toStrictEqual(['sa-1']);
+    await expect(buffer.findLinksBySegment(['GEN 1:1'])).resolves.toStrictEqual([segmentLink]);
+    await expect(buffer.findLinksByToken(['GEN 1:1:3'])).resolves.toStrictEqual({
+      tokenAnalysisLinks: [],
+      phraseAnalysisLinks: [phrase],
+    });
+    await expect(buffer.findLinksToAnalyses(['pa-1', 'sa-1'])).resolves.toStrictEqual({
+      tokenAnalysisLinks: [],
+      phraseAnalysisLinks: [phrase],
+      segmentAnalysisLinks: [segmentLink],
+    });
+  });
+
+  it('hands out copies, so changing a record read stages nothing', async () => {
+    const buffer = await bufferOver({ tokenAnalyses: [payload('ta-1')] });
+    const [read] = await buffer.getTokenAnalyses(['ta-1']);
+
+    read.surfaceText = 'changed';
+
+    expect(buffer.toChangeSet('nothing')).toStrictEqual({ intent: 'nothing' });
+    await expect(buffer.getTokenAnalyses(['ta-1'])).resolves.toStrictEqual([payload('ta-1')]);
+  });
+
+  it('keeps a staged record as it stood when staged', async () => {
+    const buffer = await bufferOver();
+    const created = payload('ta-1');
+
+    buffer.create('tokenAnalyses', created);
+    created.surfaceText = 'changed';
+
+    expect(buffer.toChangeSet('create').tokenAnalyses?.puts).toStrictEqual([payload('ta-1')]);
+  });
+
+  it('collects the staged puts and removals of each kind into one change set', async () => {
+    const stored = link('tl-1', 'ta-1', 'GEN 1:1:0');
+    const buffer = await bufferOver({
+      tokenAnalyses: [payload('ta-1')],
+      tokenAnalysisLinks: [stored],
+    });
+
+    buffer.put('tokenAnalyses', { ...payload('ta-1'), gloss: { en: 'one' } });
+    buffer.delete('tokenAnalysisLinks', stored);
+
+    expect(buffer.toChangeSet('edit')).toStrictEqual({
+      intent: 'edit',
+      tokenAnalyses: { puts: [{ ...payload('ta-1'), gloss: { en: 'one' } }], deletes: [] },
+      tokenAnalysisLinks: { puts: [], deletes: ['tl-1'] },
+    });
+  });
+
+  it('stages nothing for a record it created and then removed', async () => {
+    const buffer = await bufferOver();
+
+    buffer.create('tokenAnalyses', payload('ta-new'));
+    buffer.delete('tokenAnalyses', payload('ta-new'));
+
+    expect(buffer.toChangeSet('none')).toStrictEqual({ intent: 'none' });
+  });
+
+  it('stages a put again after a removal of a stored record', async () => {
+    const buffer = await bufferOver({ tokenAnalyses: [payload('ta-1')] });
+
+    buffer.delete('tokenAnalyses', payload('ta-1'));
+    buffer.put('tokenAnalyses', payload('ta-1'));
+
+    expect(buffer.toChangeSet('restore').tokenAnalyses).toStrictEqual({
+      puts: [payload('ta-1')],
+      deletes: [],
+    });
+  });
+
+  it('lists the records it touches as they stood before a removal or will stand after a put', async () => {
+    const stored = link('tl-1', 'ta-1', 'GEN 1:1:0');
+    const buffer = await bufferOver({ tokenAnalysisLinks: [stored] });
+
+    buffer.delete('tokenAnalysisLinks', stored);
+    buffer.create('tokenAnalysisLinks', link('tl-2', 'ta-1', 'GEN 1:1:3'));
+
+    expect(ids(buffer.touched('tokenAnalysisLinks'))).toStrictEqual(['tl-1', 'tl-2']);
+  });
+});
diff --git a/src/__tests__/services/commands/parity.ts b/src/__tests__/services/commands/parity.ts
new file mode 100644
index 000000000..4307d22d1
--- /dev/null
+++ b/src/__tests__/services/commands/parity.ts
@@ -0,0 +1,75 @@
+/// <reference types="jest" />
+
+import type { UnknownAction } from '@reduxjs/toolkit';
+import type { TextAnalysis } from 'interlinearizer';
+import { ChangeBuffer } from '../../../services/commands/changeBuffer';
+import { DraftRepository } from '../../../services/draftRepository';
+import reducer from '../../../store/analysisSlice';
+import type { ChangeSet, IndexDifference } from '../../../types/analysis-repository';
+import { emptyDraft } from '../../../types/empty-factories';
+import { memoryStorage, silentLogger } from '../../test-helpers';
+
+/** What one input gives through the store's reducer and through the host's command. */
+export type ParityOutcome = {
+  /** The analysis the reducer leaves, its record lists in id order. */
+  store: TextAnalysis;
+  /** The analysis the command's changes leave once applied and reloaded, in id order. */
+  host: TextAnalysis;
+  /** The changes the command staged. */
+  changes: ChangeSet;
+  /** Where the repository's kept indexes differ from its records after applying the changes. */
+  indexDifferences: IndexDifference[];
+};
+
+/** `analysis` as JSON holds it, with each record list in id order. */
+function normalized(analysis: TextAnalysis): TextAnalysis {
+  const plain: TextAnalysis = JSON.parse(JSON.stringify(analysis));
+  const byId = <T extends { id: string }>(records: T[]) =>
+    [...records].sort((a, b) => a.id.localeCompare(b.id));
+  return {
+    segmentAnalyses: byId(plain.segmentAnalyses),
+    segmentAnalysisLinks: byId(plain.segmentAnalysisLinks),
+    tokenAnalyses: byId(plain.tokenAnalyses),
+    tokenAnalysisLinks: byId(plain.tokenAnalysisLinks),
+    phraseAnalyses: byId(plain.phraseAnalyses),
+    phraseAnalysisLinks: byId(plain.phraseAnalysisLinks),
+  };
+}
+
+/**
+ * Runs one input both ways over `analysis`: `action` through the store's reducer, working in
+ * `analysisLanguage`, and `command` staging changes over a draft holding the same analysis, which
+ * are then applied and the draft reloaded from storage.
+ */
+export async function runParity(
+  analysis: TextAnalysis,
+  analysisLanguage: string,
+  action: UnknownAction,
+  command: (buffer: ChangeBuffer) => Promise<void>,
+): Promise<ParityOutcome> {
+  const store = reducer(
+    { analysis: JSON.parse(JSON.stringify(analysis)), analysisLanguage },
+    action,
+  );
+
+  const { storage } = memoryStorage();
+  const logger = silentLogger();
+  await new DraftRepository(storage, 'src', logger).replaceAll({
+    ...emptyDraft('src'),
+    analysisLanguages: [analysisLanguage],
+    analysis: JSON.parse(JSON.stringify(analysis)),
+  });
+  const repository = new DraftRepository(storage, 'src', logger);
+  const buffer = new ChangeBuffer(repository);
+  await command(buffer);
+  const changes = buffer.toChangeSet('parity');
+  await repository.apply(changes);
+  const { draft: reloaded } = await new DraftRepository(storage, 'src', logger).exportAll();
+
+  return {
+    store: normalized(store.analysis),
+    host: normalized(reloaded.analysis),
+    changes,
+    indexDifferences: await repository.checkIndexes(),
+  };
+}
diff --git a/src/__tests__/services/commands/tokenCommands.parity.test.ts b/src/__tests__/services/commands/tokenCommands.parity.test.ts
new file mode 100644
index 000000000..a00234a54
--- /dev/null
+++ b/src/__tests__/services/commands/tokenCommands.parity.test.ts
@@ -0,0 +1,548 @@
+/// <reference types="jest" />
+
+import type { TextAnalysis, TokenAnalysis, TokenAnalysisLink } from 'interlinearizer';
+import {
+  approveAnalysisForToken as approveCommand,
+  writeGloss as writeGlossCommand,
+} from '../../../services/commands/tokenCommands';
+import { approveAnalysisForToken, writeGloss } from '../../../store/analysisSlice';
+import { emptyAnalysis } from '../../../types/empty-factories';
+import { FIXTURE_STAMPS } from '../../test-helpers';
+import { runParity } from './parity';
+
+const NOW = '2026-06-01T00:00:00.000Z';
+const EARLIER = { createdAt: '2025-06-01T00:00:00.000Z', updatedAt: '2025-06-01T00:00:00.000Z' };
+const LATER = { createdAt: '2026-03-01T00:00:00.000Z', updatedAt: '2026-03-01T00:00:00.000Z' };
+
+function payload(id: string, surfaceText: string, fields: Partial<TokenAnalysis> = {}) {
+  return { id, ...FIXTURE_STAMPS, surfaceText, ...fields };
+}
+
+function link(
+  id: string,
+  analysisId: string,
+  tokenRef: string,
+  fields: Partial<TokenAnalysisLink> = {},
+): TokenAnalysisLink {
+  return {
+    id,
+    analysisId,
+    ...FIXTURE_STAMPS,
+    status: 'approved',
+    token: { tokenRef, surfaceText: 'in' },
+    ...fields,
+  };
+}
+
+function analysisOf(
+  tokenAnalyses: TokenAnalysis[],
+  tokenAnalysisLinks: TokenAnalysisLink[],
+): TextAnalysis {
+  return { ...emptyAnalysis(), tokenAnalyses, tokenAnalysisLinks };
+}
+
+const TOKEN = 'GEN 1:1:0';
+const OTHER_TOKEN = 'GEN 1:2:0';
+
+type ParityCase<Input> = {
+  analysis: TextAnalysis;
+  input: Input;
+  /** What the reducer's result must show, so the case exercises the path it names. */
+  expectStore: (store: TextAnalysis) => void;
+};
+
+type GlossInput = { surfaceText?: string; value: string };
+
+const ids = (records: readonly { id: string }[]) => records.map(({ id }) => id).sort();
+
+describe('writeGloss parity with the reducer', () => {
+  const cases: [string, ParityCase<GlossInput>][] = [
+    [
+      'creates a payload and an approved link for an unglossed token',
+      {
+        analysis: emptyAnalysis(),
+        input: { value: 'at' },
+        expectStore: (store) => {
+          expect(ids(store.tokenAnalyses)).toStrictEqual(['new-analysis']);
+          expect(ids(store.tokenAnalysisLinks)).toStrictEqual(['new-link']);
+        },
+      },
+    ],
+    [
+      'shares a stored payload whose content matches',
+      {
+        analysis: analysisOf(
+          [payload('ta-in', 'in', { gloss: { en: 'at' } })],
+          [link('tl-other', 'ta-in', OTHER_TOKEN)],
+        ),
+        input: { value: 'at' },
+        expectStore: (store) => {
+          expect(ids(store.tokenAnalyses)).toStrictEqual(['ta-in']);
+          expect(store.tokenAnalysisLinks.find(({ id }) => id === 'new-link')?.analysisId).toBe(
+            'ta-in',
+          );
+        },
+      },
+    ],
+    [
+      "approves the token's held link to the matching payload rather than adding one",
+      {
+        analysis: analysisOf(
+          [payload('ta-in', 'in', { gloss: { en: 'at' } })],
+          [link('tl-held', 'ta-in', TOKEN, { status: 'suggested', confidence: 'low' })],
+        ),
+        input: { value: 'at' },
+        expectStore: (store) => {
+          expect(store.tokenAnalysisLinks).toHaveLength(1);
+          expect(store.tokenAnalysisLinks[0].status).toBe('approved');
+        },
+      },
+    ],
+    [
+      'edits an unshared payload in place, refreshing surface text and dropping its sense',
+      {
+        analysis: analysisOf(
+          [
+            payload('ta-in', 'In', {
+              gloss: { en: 'at', fr: 'à' },
+              glossSenseRef: { authority: 'fwlite', senseId: 's-at' },
+            }),
+          ],
+          [link('tl-in', 'ta-in', TOKEN)],
+        ),
+        input: { surfaceText: 'In,', value: 'at first' },
+        expectStore: (store) => {
+          expect(store.tokenAnalyses).toStrictEqual([
+            payload('ta-in', 'In,', { gloss: { en: 'at first', fr: 'à' }, updatedAt: NOW }),
+          ]);
+        },
+      },
+    ],
+    [
+      'forks a payload other tokens share, editing only the fork',
+      {
+        analysis: analysisOf(
+          [payload('ta-in', 'In', { gloss: { en: 'at' } })],
+          [link('tl-in', 'ta-in', TOKEN), link('tl-other', 'ta-in', OTHER_TOKEN)],
+        ),
+        input: { value: 'start' },
+        expectStore: (store) => {
+          expect(ids(store.tokenAnalyses)).toStrictEqual(['new-analysis', 'ta-in']);
+        },
+      },
+    ],
+    [
+      "folds an edit matching another payload into it, clearing the survivor's stale breakdown",
+      {
+        analysis: analysisOf(
+          [
+            payload('ta-at', 'in', { gloss: { en: 'at' } }),
+            payload('ta-within', 'In', {
+              ...EARLIER,
+              gloss: { en: 'within' },
+              morphemesStale: true,
+            }),
+          ],
+          [link('tl-in', 'ta-at', TOKEN), link('tl-other', 'ta-within', OTHER_TOKEN)],
+        ),
+        input: { value: 'within' },
+        expectStore: (store) => {
+          expect(ids(store.tokenAnalyses)).toStrictEqual(['ta-within']);
+          expect(store.tokenAnalyses[0].morphemesStale).toBeUndefined();
+        },
+      },
+    ],
+    [
+      'leaves a token linking both folded payloads one link, dated by the earlier',
+      {
+        analysis: analysisOf(
+          [
+            payload('ta-at', 'In', { gloss: { en: 'at' } }),
+            payload('ta-within', 'In', { ...EARLIER, gloss: { en: 'within' } }),
+          ],
+          [
+            link('tl-in', 'ta-at', TOKEN, LATER),
+            link('tl-offered', 'ta-within', TOKEN, { ...EARLIER, status: 'suggested' }),
+          ],
+        ),
+        input: { value: 'within' },
+        expectStore: (store) => {
+          expect(store.tokenAnalysisLinks).toHaveLength(1);
+          expect(store.tokenAnalysisLinks[0]).toMatchObject({
+            id: 'tl-in',
+            status: 'approved',
+            createdAt: EARLIER.createdAt,
+          });
+        },
+      },
+    ],
+    [
+      'folds into a payload another token was offered, leaving that offer as it was',
+      {
+        analysis: analysisOf(
+          [
+            payload('ta-at', 'In', { gloss: { en: 'at' } }),
+            payload('ta-within', 'In', { ...EARLIER, gloss: { en: 'within' } }),
+          ],
+          [
+            link('tl-in', 'ta-at', TOKEN),
+            link('tl-offered', 'ta-within', OTHER_TOKEN, { status: 'suggested' }),
+          ],
+        ),
+        input: { value: 'within' },
+        expectStore: (store) => {
+          expect(store.tokenAnalysisLinks).toStrictEqual(
+            expect.arrayContaining([
+              expect.objectContaining({ id: 'tl-offered', status: 'suggested' }),
+            ]),
+          );
+          expect(ids(store.tokenAnalyses)).toStrictEqual(['ta-within']);
+        },
+      },
+    ],
+    [
+      'clears the gloss, removing the payload it empties and its link',
+      {
+        analysis: analysisOf(
+          [payload('ta-in', 'In', { gloss: { en: 'at' } })],
+          [link('tl-in', 'ta-in', TOKEN)],
+        ),
+        input: { value: '' },
+        expectStore: (store) => {
+          expect(store).toStrictEqual(emptyAnalysis());
+        },
+      },
+    ],
+    [
+      'clears one language, keeping the others and the sense',
+      {
+        analysis: analysisOf(
+          [
+            payload('ta-in', 'In', {
+              gloss: { en: 'at', fr: 'à' },
+              glossSenseRef: { authority: 'fwlite', senseId: 's-at' },
+            }),
+          ],
+          [link('tl-in', 'ta-in', TOKEN)],
+        ),
+        input: { value: '  ' },
+        expectStore: (store) => {
+          expect(store.tokenAnalyses[0].gloss).toStrictEqual({ fr: 'à' });
+          expect(store.tokenAnalyses[0].glossSenseRef).toBeDefined();
+        },
+      },
+    ],
+    [
+      'clears a shared payload by dropping only this token’s link',
+      {
+        analysis: analysisOf(
+          [payload('ta-in', 'In', { gloss: { en: 'at' } })],
+          [link('tl-in', 'ta-in', TOKEN), link('tl-other', 'ta-in', OTHER_TOKEN)],
+        ),
+        input: { value: '' },
+        expectStore: (store) => {
+          expect(ids(store.tokenAnalyses)).toStrictEqual(['ta-in']);
+          expect(ids(store.tokenAnalysisLinks)).toStrictEqual(['tl-other']);
+        },
+      },
+    ],
+    [
+      'keeps an emptied payload another of the token’s links still names',
+      {
+        analysis: analysisOf(
+          [payload('ta-in', 'In', { gloss: { en: 'at' } })],
+          [
+            link('tl-in', 'ta-in', TOKEN),
+            link('tl-rejected', 'ta-in', TOKEN, { status: 'rejected' }),
+          ],
+        ),
+        input: { value: '' },
+        expectStore: (store) => {
+          expect(store.tokenAnalyses).toStrictEqual([payload('ta-in', 'In', { updatedAt: NOW })]);
+          expect(ids(store.tokenAnalysisLinks)).toStrictEqual(['tl-rejected']);
+        },
+      },
+    ],
+    [
+      'folds a cleared payload into another its remaining content matches',
+      {
+        analysis: analysisOf(
+          [
+            payload('ta-in', 'In', { gloss: { en: 'at' }, pos: 'prep' }),
+            payload('ta-bare', 'in', { ...EARLIER, pos: 'prep' }),
+          ],
+          [link('tl-in', 'ta-in', TOKEN)],
+        ),
+        input: { value: '' },
+        expectStore: (store) => {
+          expect(ids(store.tokenAnalyses)).toStrictEqual(['ta-bare']);
+          expect(store.tokenAnalysisLinks[0].analysisId).toBe('ta-bare');
+        },
+      },
+    ],
+    [
+      'folds a fork back onto the shared payload when the write leaves it unchanged',
+      {
+        analysis: analysisOf(
+          [payload('ta-in', 'In', { gloss: { en: 'at' } })],
+          [link('tl-in', 'ta-in', TOKEN), link('tl-other', 'ta-in', OTHER_TOKEN)],
+        ),
+        input: { value: 'at' },
+        expectStore: (store) => {
+          expect(ids(store.tokenAnalyses)).toStrictEqual(['ta-in']);
+          expect(store.tokenAnalysisLinks.every(({ analysisId }) => analysisId === 'ta-in')).toBe(
+            true,
+          );
+        },
+      },
+    ],
+    [
+      'edits the payload an approval tie picks among several approved links',
+      {
+        analysis: analysisOf(
+          [
+            payload('ta-old', 'In', { gloss: { en: 'old' } }),
+            payload('ta-new', 'In', { gloss: { en: 'new' } }),
+          ],
+          [link('tl-old', 'ta-old', TOKEN, EARLIER), link('tl-new', 'ta-new', TOKEN, LATER)],
+        ),
+        input: { value: 'newer' },
+        expectStore: (store) => {
+          expect(store.tokenAnalyses.find(({ id }) => id === 'ta-new')?.gloss).toStrictEqual({
+            en: 'newer',
+          });
+        },
+      },
+    ],
+    [
+      'stages nothing for a blank write to an unglossed token',
+      {
+        analysis: analysisOf([payload('ta-in', 'In', { gloss: { en: 'at' } })], []),
+        input: { value: '' },
+        expectStore: (store) => {
+          expect(ids(store.tokenAnalyses)).toStrictEqual(['ta-in']);
+        },
+      },
+    ],
+    [
+      'removes an approved link whose payload is gone before writing',
+      {
+        analysis: analysisOf([], [link('tl-orphan', 'ta-missing', TOKEN)]),
+        input: { value: 'at' },
+        expectStore: (store) => {
+          expect(ids(store.tokenAnalysisLinks)).toStrictEqual(['new-link']);
+        },
+      },
+    ],
+    [
+      'removes an approved link whose payload is gone even on a blank write',
+      {
+        analysis: analysisOf([], [link('tl-orphan', 'ta-missing', TOKEN)]),
+        input: { value: '' },
+        expectStore: (store) => {
+          expect(store).toStrictEqual(emptyAnalysis());
+        },
+      },
+    ],
+  ];
+
+  it.each(cases)('%s', async (_name, { analysis, input, expectStore }) => {
+    const surfaceText = input.surfaceText ?? 'In';
+    const outcome = await runParity(
+      analysis,
+      'en',
+      {
+        type: writeGloss.type,
+        payload: {
+          tokenRef: TOKEN,
+          surfaceText,
+          value: input.value,
+          id: 'new-analysis',
+          linkId: 'new-link',
+          now: NOW,
+        },
+      },
+      (buffer) =>
+        writeGlossCommand(buffer, {
+          tokenRef: TOKEN,
+          surfaceText,
+          value: input.value,
+          analysisLanguage: 'en',
+          analysisId: 'new-analysis',
+          linkId: 'new-link',
+          now: NOW,
+        }),
+    );
+
+    expectStore(outcome.store);
+    expect(outcome.host).toStrictEqual(outcome.store);
+    expect(outcome.indexDifferences).toStrictEqual([]);
+  });
+});
+
+type ApproveInput = { analysisId: string };
+
+describe('approveAnalysisForToken parity with the reducer', () => {
+  const cases: [string, ParityCase<ApproveInput>][] = [
+    [
+      'gives a token with no approval a new approved link',
+      {
+        analysis: analysisOf([payload('ta-in', 'In', { gloss: { en: 'at' } })], []),
+        input: { analysisId: 'ta-in' },
+        expectStore: (store) => {
+          expect(store.tokenAnalysisLinks).toStrictEqual([
+            {
+              id: 'new-link',
+              analysisId: 'ta-in',
+              createdAt: NOW,
+              updatedAt: NOW,
+              status: 'approved',
+              token: { tokenRef: TOKEN, surfaceText: 'In' },
+            },
+          ]);
+        },
+      },
+    ],
+    [
+      'approves the link the token holds to the payload rather than adding one',
+      {
+        analysis: analysisOf(
+          [payload('ta-in', 'In', { gloss: { en: 'at' } })],
+          [link('tl-held', 'ta-in', TOKEN, { status: 'candidate', confidence: 'guess' })],
+        ),
+        input: { analysisId: 'ta-in' },
+        expectStore: (store) => {
+          expect(store.tokenAnalysisLinks).toHaveLength(1);
+          expect(store.tokenAnalysisLinks[0]).toMatchObject({
+            status: 'approved',
+            confidence: 'guess',
+          });
+        },
+      },
+    ],
+    [
+      'moves the approval off a payload, removing it once nothing links it',
+      {
+        analysis: analysisOf(
+          [
+            payload('ta-at', 'In', { gloss: { en: 'at' } }),
+            payload('ta-on', 'In', { gloss: { en: 'on' } }),
+          ],
+          [link('tl-in', 'ta-at', TOKEN)],
+        ),
+        input: { analysisId: 'ta-on' },
+        expectStore: (store) => {
+          expect(ids(store.tokenAnalyses)).toStrictEqual(['ta-on']);
+          expect(store.tokenAnalysisLinks[0].analysisId).toBe('ta-on');
+        },
+      },
+    ],
+    [
+      'keeps the payload the approval leaves when another token links it',
+      {
+        analysis: analysisOf(
+          [
+            payload('ta-at', 'In', { gloss: { en: 'at' } }),
+            payload('ta-on', 'In', { gloss: { en: 'on' } }),
+          ],
+          [link('tl-in', 'ta-at', TOKEN), link('tl-other', 'ta-at', OTHER_TOKEN)],
+        ),
+        input: { analysisId: 'ta-on' },
+        expectStore: (store) => {
+          expect(ids(store.tokenAnalyses)).toStrictEqual(['ta-at', 'ta-on']);
+        },
+      },
+    ],
+    [
+      'approves a held link in place of the approval, keeping the earlier creation date',
+      {
+        analysis: analysisOf(
+          [
+            payload('ta-at', 'In', { gloss: { en: 'at' } }),
+            payload('ta-on', 'In', { gloss: { en: 'on' } }),
+          ],
+          [
+            link('tl-in', 'ta-at', TOKEN, EARLIER),
+            link('tl-held', 'ta-on', TOKEN, { ...LATER, status: 'suggested' }),
+          ],
+        ),
+        input: { analysisId: 'ta-on' },
+        expectStore: (store) => {
+          expect(store.tokenAnalysisLinks).toStrictEqual([
+            expect.objectContaining({
+              id: 'tl-held',
+              status: 'approved',
+              createdAt: EARLIER.createdAt,
+            }),
+          ]);
+          expect(ids(store.tokenAnalyses)).toStrictEqual(['ta-on']);
+        },
+      },
+    ],
+    [
+      'stages nothing for a payload not stored',
+      {
+        analysis: analysisOf([], [link('tl-orphan', 'ta-missing', TOKEN)]),
+        input: { analysisId: 'ta-unknown' },
+        expectStore: (store) => {
+          expect(ids(store.tokenAnalysisLinks)).toStrictEqual(['tl-orphan']);
+        },
+      },
+    ],
+    [
+      'removes orphaned approvals even when the payload is already approved',
+      {
+        analysis: analysisOf(
+          [payload('ta-in', 'In', { gloss: { en: 'at' } })],
+          [link('tl-in', 'ta-in', TOKEN, LATER), link('tl-orphan', 'ta-missing', TOKEN, EARLIER)],
+        ),
+        input: { analysisId: 'ta-in' },
+        expectStore: (store) => {
+          expect(ids(store.tokenAnalysisLinks)).toStrictEqual(['tl-in']);
+        },
+      },
+    ],
+    [
+      'removes orphaned approvals before approving',
+      {
+        analysis: analysisOf(
+          [payload('ta-in', 'In', { gloss: { en: 'at' } })],
+          [link('tl-orphan', 'ta-missing', TOKEN)],
+        ),
+        input: { analysisId: 'ta-in' },
+        expectStore: (store) => {
+          expect(ids(store.tokenAnalysisLinks)).toStrictEqual(['new-link']);
+        },
+      },
+    ],
+  ];
+
+  it.each(cases)('%s', async (_name, { analysis, input, expectStore }) => {
+    const outcome = await runParity(
+      analysis,
+      'en',
+      {
+        type: approveAnalysisForToken.type,
+        payload: {
+          tokenRef: TOKEN,
+          surfaceText: 'In',
+          analysisId: input.analysisId,
+          linkId: 'new-link',
+          now: NOW,
+        },
+      },
+      (buffer) =>
+        approveCommand(buffer, {
+          tokenRef: TOKEN,
+          surfaceText: 'In',
+          analysisId: input.analysisId,
+          linkId: 'new-link',
+          now: NOW,
+        }),
+    );
+
+    expectStore(outcome.store);
+    expect(outcome.host).toStrictEqual(outcome.store);
+    expect(outcome.indexDifferences).toStrictEqual([]);
+  });
+});
diff --git a/src/__tests__/services/commands/tokenCommands.test.ts b/src/__tests__/services/commands/tokenCommands.test.ts
new file mode 100644
index 000000000..7550f665e
--- /dev/null
+++ b/src/__tests__/services/commands/tokenCommands.test.ts
@@ -0,0 +1,92 @@
+/// <reference types="jest" />
+
+import type { TextAnalysis, TokenAnalysis, TokenAnalysisLink } from 'interlinearizer';
+import { ChangeBuffer } from '../../../services/commands/changeBuffer';
+import { approveAnalysisForToken, writeGloss } from '../../../services/commands/tokenCommands';
+import { DraftRepository } from '../../../services/draftRepository';
+import { emptyAnalysis, emptyDraft } from '../../../types/empty-factories';
+import { FIXTURE_STAMPS, memoryStorage, silentLogger } from '../../test-helpers';
+
+const NOW = '2026-06-01T00:00:00.000Z';
+const STAMP = { analysisId: 'new-analysis', linkId: 'new-link', now: NOW };
+
+const shared: TokenAnalysis = {
+  id: 'ta-in',
+  ...FIXTURE_STAMPS,
+  surfaceText: 'In',
+  gloss: { en: 'at' },
+};
+
+function link(id: string, tokenRef: string): TokenAnalysisLink {
+  return {
+    id,
+    analysisId: 'ta-in',
+    ...FIXTURE_STAMPS,
+    status: 'approved',
+    token: { tokenRef, surfaceText: 'In' },
+  };
+}
+
+async function bufferOver(analysis: Partial<TextAnalysis>): Promise<ChangeBuffer> {
+  const { storage } = memoryStorage();
+  const repository = new DraftRepository(storage, 'src', silentLogger());
+  await repository.replaceAll({
+    ...emptyDraft('src'),
+    analysis: { ...emptyAnalysis(), ...analysis },
+  });
+  return new ChangeBuffer(repository);
+}
+
+describe('writeGloss', () => {
+  it("stages only the link's removal when clearing a shared payload, never its fork", async () => {
+    const buffer = await bufferOver({
+      tokenAnalyses: [shared],
+      tokenAnalysisLinks: [link('tl-1', 'GEN 1:1:0'), link('tl-2', 'GEN 1:2:0')],
+    });
+
+    await writeGloss(buffer, {
+      ...STAMP,
+      tokenRef: 'GEN 1:1:0',
+      surfaceText: 'In',
+      value: '',
+      analysisLanguage: 'en',
+    });
+
+    expect(buffer.toChangeSet('writeGloss')).toStrictEqual({
+      intent: 'writeGloss',
+      tokenAnalysisLinks: { puts: [], deletes: ['tl-1'] },
+    });
+  });
+
+  it('stages nothing for a blank write to an unglossed token', async () => {
+    const buffer = await bufferOver({ tokenAnalyses: [shared] });
+
+    await writeGloss(buffer, {
+      ...STAMP,
+      tokenRef: 'GEN 1:1:0',
+      surfaceText: 'In',
+      value: ' ',
+      analysisLanguage: 'en',
+    });
+
+    expect(buffer.toChangeSet('writeGloss')).toStrictEqual({ intent: 'writeGloss' });
+  });
+});
+
+describe('approveAnalysisForToken', () => {
+  it('stages nothing for a payload already approved for the token', async () => {
+    const buffer = await bufferOver({
+      tokenAnalyses: [shared],
+      tokenAnalysisLinks: [link('tl-1', 'GEN 1:1:0')],
+    });
+
+    await approveAnalysisForToken(buffer, {
+      ...STAMP,
+      tokenRef: 'GEN 1:1:0',
+      surfaceText: 'In',
+      analysisId: 'ta-in',
+    });
+
+    expect(buffer.toChangeSet('approve')).toStrictEqual({ intent: 'approve' });
+  });
+});
diff --git a/src/__tests__/services/indexedRepository.test.ts b/src/__tests__/services/indexedRepository.test.ts
index 79ca69dbe..d60a4d0bb 100644
--- a/src/__tests__/services/indexedRepository.test.ts
+++ b/src/__tests__/services/indexedRepository.test.ts
@@ -2,27 +2,30 @@
 
 import type { TextAnalysis } from 'interlinearizer';
 import { AnalysisIndex } from '../../services/analysisIndex';
-import { type IndexedAnalysis, IndexedRepository } from '../../services/indexedRepository';
-import { emptyAnalysis } from '../../types/empty-factories';
+import { type IndexedDraft, IndexedRepository } from '../../services/indexedRepository';
+import { emptyAnalysis, emptyDraft } from '../../types/empty-factories';
 import { FIXTURE_STAMPS } from '../test-helpers';
 
 /** Answers lookups from an index over `records`, reporting it as kept when `keep` is `'kept'`. */
 class StubRepository extends IndexedRepository {
-  readonly kept: IndexedAnalysis | undefined;
+  readonly kept: IndexedDraft | undefined;
 
-  private readonly index: AnalysisIndex;
+  private readonly indexedDraft: IndexedDraft;
 
   constructor(records: TextAnalysis, keep: 'kept' | 'none') {
     super();
-    this.index = new AnalysisIndex(records);
-    this.kept = keep === 'kept' ? { analysis: records, index: this.index } : undefined;
+    this.indexedDraft = {
+      draft: { ...emptyDraft('src'), analysisLanguages: ['en'], analysis: records },
+      index: new AnalysisIndex(records),
+    };
+    this.kept = keep === 'kept' ? this.indexedDraft : undefined;
   }
 
-  protected async indexed(): Promise<AnalysisIndex> {
-    return this.index;
+  protected async indexed(): Promise<IndexedDraft> {
+    return this.indexedDraft;
   }
 
-  protected keptIndex(): IndexedAnalysis | undefined {
+  protected keptIndex(): IndexedDraft | undefined {
     return this.kept;
   }
 }
@@ -54,7 +57,7 @@ describe('IndexedRepository', () => {
 
   it('reports the differences of the index it keeps from its analysis', async () => {
     const repository = new StubRepository(analysis(), 'kept');
-    repository.kept?.analysis.tokenAnalyses.pop();
+    repository.kept?.draft.analysis.tokenAnalyses.pop();
 
     await expect(repository.checkIndexes()).resolves.toContainEqual({
       index: 'tokenAnalyses',
@@ -64,6 +67,14 @@ describe('IndexedRepository', () => {
     });
   });
 
+  it("reads the draft's own record without its analysis", async () => {
+    await expect(new StubRepository(analysis(), 'none').getScope()).resolves.toStrictEqual({
+      sourceProjectId: 'src',
+      modelVersion: emptyDraft('src').modelVersion,
+      analysisLanguages: ['en'],
+    });
+  });
+
   it('reports nothing while it keeps no index', async () => {
     await expect(new StubRepository(analysis(), 'none').checkIndexes()).resolves.toStrictEqual([]);
   });
diff --git a/src/__tests__/services/projectStorage.test.ts b/src/__tests__/services/projectStorage.test.ts
index 80094fd0f..1030b3c67 100644
--- a/src/__tests__/services/projectStorage.test.ts
+++ b/src/__tests__/services/projectStorage.test.ts
@@ -2995,6 +2995,11 @@ describe('projectStorage', () => {
       ],
       ['findPhraseAnalysesByForm', (r: AnalysisRepository) => r.findPhraseAnalysesByForm(['x']), 0],
       ['checkIndexes', (r: AnalysisRepository) => r.checkIndexes(), 0],
+      [
+        'getScope',
+        (r: AnalysisRepository) => r.getScope().then(({ analysisLanguages }) => analysisLanguages),
+        0,
+      ],
     ])('answers %s from the draft saveDraft saved', async (_name, lookup, count) => {
       await saveDraft(token, 'src-proj', makeDraftSpanningBooks('src-proj', 'GEN'));
 
diff --git a/src/__tests__/utils/change-set.test.ts b/src/__tests__/utils/change-set.test.ts
index a8f19f1ec..b0894f579 100644
--- a/src/__tests__/utils/change-set.test.ts
+++ b/src/__tests__/utils/change-set.test.ts
@@ -2,7 +2,7 @@
 
 import type { DraftProject, TokenAnalysis } from 'interlinearizer';
 import { emptyAnalysis, emptyDraft } from '../../types/empty-factories';
-import { applyChangeSet, scopeRecordOf } from '../../utils/change-set';
+import { applyChangeSet, isEmptyChangeSet, scopeRecordOf } from '../../utils/change-set';
 import { FIXTURE_STAMPS } from '../test-helpers';
 
 function payload(id: string, gloss?: string): TokenAnalysis {
@@ -189,3 +189,19 @@ describe('applyChangeSet', () => {
     ).toStrictEqual([['sa'], ['sl'], ['a'], ['tl'], ['pa'], ['pl']]);
   });
 });
+
+describe('isEmptyChangeSet', () => {
+  it('finds a change set naming only its intent empty', () => {
+    expect(isEmptyChangeSet({ intent: 'none' })).toBe(true);
+  });
+
+  it('finds a change set with record changes not empty', () => {
+    expect(isEmptyChangeSet({ intent: 'edit', tokenAnalyses: { puts: [], deletes: ['a'] } })).toBe(
+      false,
+    );
+  });
+
+  it("finds a change set putting the scope's record not empty", () => {
+    expect(isEmptyChangeSet({ intent: 'edit', scope: scopeRecordOf(draftOf()) })).toBe(false);
+  });
+});
diff --git a/src/__tests__/utils/token-analysis-content.test.ts b/src/__tests__/utils/token-analysis-content.test.ts
new file mode 100644
index 000000000..5625fd3a3
--- /dev/null
+++ b/src/__tests__/utils/token-analysis-content.test.ts
@@ -0,0 +1,59 @@
+/// <reference types="jest" />
+
+import type { TokenAnalysis } from 'interlinearizer';
+import { clearAnalysisGloss, isEmptyTokenAnalysis } from '../../utils/token-analysis-content';
+import { FIXTURE_STAMPS } from '../test-helpers';
+
+function analysis(fields: Partial<TokenAnalysis> = {}): TokenAnalysis {
+  return { id: 'ta-1', ...FIXTURE_STAMPS, surfaceText: 'In', ...fields };
+}
+
+describe('isEmptyTokenAnalysis', () => {
+  it('finds a record holding only blank glosses and provenance empty', () => {
+    expect(isEmptyTokenAnalysis(analysis({ gloss: { en: ' ' }, confidence: 'high' }))).toBe(true);
+  });
+
+  it.each([
+    ['a gloss', { gloss: { en: 'at' } }],
+    ['morphemes', { morphemes: [{ id: 'm-1', form: 'in', writingSystem: 'en' }] }],
+    ['a part of speech', { pos: 'prep' }],
+    ['features', { features: { case: 'loc' } }],
+    ['a gloss sense', { glossSenseRef: { authority: 'fwlite', senseId: 's-1' } }],
+  ])('finds a record holding %s not empty', (_field, fields) => {
+    expect(isEmptyTokenAnalysis(analysis(fields))).toBe(false);
+  });
+});
+
+describe('clearAnalysisGloss', () => {
+  it('clears one language, keeping the others and the sense', () => {
+    const record = analysis({
+      gloss: { en: 'at', fr: 'à' },
+      glossSenseRef: { authority: 'fwlite', senseId: 's-1' },
+    });
+
+    clearAnalysisGloss(record, 'en');
+
+    expect(record).toStrictEqual(
+      analysis({ gloss: { fr: 'à' }, glossSenseRef: { authority: 'fwlite', senseId: 's-1' } }),
+    );
+  });
+
+  it('drops the gloss and the sense once no language holds usable text', () => {
+    const record = analysis({
+      gloss: { en: 'at', fr: ' ' },
+      glossSenseRef: { authority: 'fwlite', senseId: 's-1' },
+    });
+
+    clearAnalysisGloss(record, 'en');
+
+    expect(record).toStrictEqual(analysis());
+  });
+
+  it('drops a sense left with no gloss at all', () => {
+    const record = analysis({ glossSenseRef: { authority: 'fwlite', senseId: 's-1' } });
+
+    clearAnalysisGloss(record, 'en');
+
+    expect(record).toStrictEqual(analysis());
+  });
+});
diff --git a/src/main.ts b/src/main.ts
index 039043714..e5ae69088 100644
--- a/src/main.ts
+++ b/src/main.ts
@@ -11,8 +11,10 @@ import type { ProjectConfig } from 'interlinearizer';
 import { formatReplacementString, type LocalizeKey } from 'platform-bible-utils';
 import interlinearizerReact from './interlinearizer.web-view?inline';
 import interlinearizerStyles from './interlinearizer.web-view.scss?inline';
-import { AnalysisSessions, type OpenedSession } from './services/analysisSessions';
+import { AnalysisSessions, type OpenedSession, type Session } from './services/analysisSessions';
 import * as bookService from './services/bookService';
+import type { ChangeBuffer } from './services/commands/changeBuffer';
+import * as tokenCommands from './services/commands/tokenCommands';
 import { readHostPerf, setHostPerfMarks } from './services/hostPerf';
 import * as projectStorage from './services/projectStorage';
 import * as pt9ImportService from './services/pt9ImportService';
@@ -825,6 +827,80 @@ async function checkIndexes(sessionId: string): Promise<string> {
   }
 }
 
+/**
+ * Runs `command` as one edit of a session's analysis.
+ *
+ * @returns The changes it applied, as JSON.
+ * @throws If the session is read-only or not open, or the edit is refused or fails. The error is
+ *   logged before rethrowing.
+ */
+async function runSessionEdit(
+  sessionId: string,
+  intent: string,
+  command: (buffer: ChangeBuffer, session: Session) => Promise<void>,
+): Promise<string> {
+  try {
+    return JSON.stringify(await sessions.edit(sessionId, intent, command));
+  } catch (e) {
+    logger.error(`Interlinearizer: failed to ${intent} in session ${sessionId}`, e);
+    throw e;
+  }
+}
+
+/** Ids a new record or link would take, and the time an edit lands. */
+function editStamp() {
+  return {
+    analysisId: crypto.randomUUID(),
+    linkId: crypto.randomUUID(),
+    now: new Date().toISOString(),
+  };
+}
+
+/**
+ * Writes a token's gloss in the session's analysis language; a blank value clears it.
+ *
+ * @returns The changes it applied, as JSON.
+ * @throws As {@link runSessionEdit} does.
+ */
+function writeGloss(
+  sessionId: string,
+  tokenRef: string,
+  surfaceText: string,
+  value: string,
+): Promise<string> {
+  return runSessionEdit(sessionId, 'writeGloss', (buffer, session) =>
+    tokenCommands.writeGloss(buffer, {
+      ...editStamp(),
+      tokenRef,
+      surfaceText,
+      value,
+      analysisLanguage: session.analysisLanguage,
+    }),
+  );
+}
+
+/**
+ * Approves a stored token analysis for a token, in place of any approval it held.
+ *
+ * @returns The changes it applied, as JSON.
+ * @throws As {@link runSessionEdit} does.
+ */
+function approveAnalysisForToken(
+  sessionId: string,
+  tokenRef: string,
+  surfaceText: string,
+  analysisId: string,
+): Promise<string> {
+  return runSessionEdit(sessionId, 'approveAnalysisForToken', (buffer) =>
+    tokenCommands.approveAnalysisForToken(buffer, {
+      ...editStamp(),
+      tokenRef,
+      surfaceText,
+      analysisId,
+    }),
+  );
+}
+
 /**
  * Returns a summary of every interlinearizer project for the given source project as a JSON string.
  * The WebView deserializes this to populate its project picker and to decide whether to prompt
@@ -1430,6 +1506,70 @@ export async function activate(context: ExecutionActivationContext): Promise<voi
     },
   );
 
+  /** The parameters naming the token a token edit acts on. */
+  const tokenParams = [
+    {
+      name: 'tokenRef',
+      required: true,
+      summary: 'Token.ref of the token edited',
+      schema: { type: 'string' },
+    },
+    {
+      name: 'surfaceText',
+      required: true,
+      summary: "The token's current surface text",
+      schema: { type: 'string' },
+    },
+  ] as const;
+
+  const editResult = {
+    name: 'return value',
+    summary: 'JSON-stringified ChangeSet the edit applied',
+    schema: { type: 'string' },
+  } as const;
+
+  const writeGlossCommandRegistration = await papi.commands.registerCommand(
+    'interlinearizer.writeGloss',
+    writeGloss,
+    {
+      method: {
+        summary: "Write a token's gloss in a session's analysis language; a blank value clears it",
+        params: [
+          sessionIdParam,
+          ...tokenParams,
+          {
+            name: 'value',
+            required: true,
+            summary: 'The gloss',
+            schema: { type: 'string' },
+          },
+        ],
+        result: editResult,
+      },
+    },
+  );
+
+  const approveAnalysisForTokenCommandRegistration = await papi.commands.registerCommand(
+    'interlinearizer.approveAnalysisForToken',
+    approveAnalysisForToken,
+    {
+      method: {
+        summary: 'Approve a stored token analysis for a token, in place of any approval it held',
+        params: [
+          sessionIdParam,
+          ...tokenParams,
+          {
+            name: 'analysisId',
+            required: true,
+            summary: 'Id of the stored token analysis to approve',
+            schema: { type: 'string' },
+          },
+        ],
+        result: editResult,
+      },
+    },
+  );
+
   const checkIndexesCommandRegistration = await papi.commands.registerCommand(
     'interlinearizer.checkIndexes',
     checkIndexes,
@@ -1823,6 +1963,8 @@ export async function activate(context: ExecutionActivationContext): Promise<voi
     undoEditCommandRegistration,
     redoEditCommandRegistration,
     checkIndexesCommandRegistration,
+    writeGlossCommandRegistration,
+    approveAnalysisForTokenCommandRegistration,
     setPerfMarksCommandRegistration,
     readPerfCommandRegistration,
     updateProjectMetadataCommandRegistration,
diff --git a/src/services/analysisSessions.ts b/src/services/analysisSessions.ts
index 29bae4c82..7be058f68 100644
--- a/src/services/analysisSessions.ts
+++ b/src/services/analysisSessions.ts
@@ -1,7 +1,10 @@
 import type { AnalysisRepository, ChangeSet } from '../types/analysis-repository';
 import { ReadOnlyAnalysisError } from '../types/read-only-analysis-error';
 import type { InterlinearProjectSummary } from '../types/interlinear-project-summary';
+import { isEmptyChangeSet } from '../utils/change-set';
 import { analysisHasFreeTranslations } from '../utils/free-translations';
+import { assertApprovalRule } from './commands/approvalRule';
+import { ChangeBuffer } from './commands/changeBuffer';
 import { EditHistory } from './editHistory';
 
 /** BCP 47 tag for a language that cannot be determined. */
@@ -202,6 +205,33 @@ export class AnalysisSessions {
     return this.run(sessionId, edit);
   }
 
+  /**
+   * Runs `command` as one edit of the session's analysis, in the session's turn. What it stages
+   * applies as one undo step, marking the draft dirty; a command staging nothing applies nothing.
+   *
+   * @returns The changes applied, naming `intent`.
+   * @throws {ReadOnlyAnalysisError} If the session is read-only.
+   * @throws {ApprovalRuleError} If the changes would give a token or segment a second approved
+   *   link; nothing is applied.
+   * @throws {Error} If the session is not open.
+   * @throws Whatever the command or applying its changes throws; nothing is applied.
+   */
+  edit(
+    sessionId: string,
+    intent: string,
+    command: (buffer: ChangeBuffer, session: Session) => Promise<void>,
+  ): Promise<ChangeSet> {
+    return this.runEdit(sessionId, async (session) => {
+      const buffer = new ChangeBuffer(session.repository);
+      await command(buffer, session);
+      const changes = buffer.toChangeSet(intent);
+      if (isEmptyChangeSet(changes)) return changes;
+      await assertApprovalRule(buffer, session.repository);
+      await session.history.apply(changes);
+      return changes;
+    });
+  }
+
   /**
    * Reverts the session's latest edit not yet undone.
    *
diff --git a/src/services/commands/approvalRule.ts b/src/services/commands/approvalRule.ts
new file mode 100644
index 000000000..e0477069d
--- /dev/null
+++ b/src/services/commands/approvalRule.ts
@@ -0,0 +1,69 @@
+import type { AnalysisRepository } from '../../types/analysis-repository';
+import type { ChangeBuffer } from './changeBuffer';
+
+/** Thrown by an edit that would give a token or segment a second approved link. */
+export class ApprovalRuleError extends Error {
+  /** The token refs and segment ids the edit would leave holding several approved links. */
+  readonly places: readonly string[];
+
+  constructor(places: readonly string[]) {
+    super(`Interlinearizer: an edit would approve several analyses at ${places.join(', ')}`);
+    this.name = 'ApprovalRuleError';
+    this.places = places;
+  }
+}
+
+/** How many approved links each place holds, placing each link by `placeOf`. */
+function approvedCounts<Link extends { status: string }>(
+  links: readonly Link[],
+  placeOf: (link: Link) => string,
+): Map<string, number> {
+  const counts = new Map<string, number>();
+  links.forEach((link) => {
+    if (link.status !== 'approved') return;
+    counts.set(placeOf(link), (counts.get(placeOf(link)) ?? 0) + 1);
+  });
+  return counts;
+}
+
+/** The places where `after` holds more than one approved link, and more than `before` held. */
+function breaches<Link extends { status: string }>(
+  before: readonly Link[],
+  after: readonly Link[],
+  placeOf: (link: Link) => string,
+): string[] {
+  const held = approvedCounts(before, placeOf);
+  return [...approvedCounts(after, placeOf)].flatMap(([place, count]) =>
+    count > 1 && count > (held.get(place) ?? 0) ? [place] : [],
+  );
+}
+
+/**
+ * Refuses the changes staged in `buffer` over `repository` when they would leave a token or segment
+ * holding more approved links than one, and more than it held before them. A place the stored
+ * analysis already breaches is left to the edits that repair it.
+ *
+ * @throws {ApprovalRuleError} If the changes breach the rule anywhere.
+ */
+export async function assertApprovalRule(
+  buffer: ChangeBuffer,
+  repository: AnalysisRepository,
+): Promise<void> {
+  const tokenRefs = [
+    ...new Set(buffer.touched('tokenAnalysisLinks').map(({ token }) => token.tokenRef)),
+  ];
+  const segmentIds = [...new Set(buffer.touched('segmentAnalysisLinks').map((l) => l.segmentId))];
+  const found = [
+    ...breaches(
+      (await repository.findLinksByToken(tokenRefs)).tokenAnalysisLinks,
+      (await buffer.findLinksByToken(tokenRefs)).tokenAnalysisLinks,
+      ({ token }) => token.tokenRef,
+    ),
+    ...breaches(
+      await repository.findLinksBySegment(segmentIds),
+      await buffer.findLinksBySegment(segmentIds),
+      ({ segmentId }) => segmentId,
+    ),
+  ];
+  if (found.length > 0) throw new ApprovalRuleError(found);
+}
diff --git a/src/services/commands/changeBuffer.ts b/src/services/commands/changeBuffer.ts
new file mode 100644
index 000000000..5a5392fa5
--- /dev/null
+++ b/src/services/commands/changeBuffer.ts
@@ -0,0 +1,214 @@
+import type {
+  PhraseAnalysis,
+  SegmentAnalysis,
+  SegmentAnalysisLink,
+  TextAnalysis,
+  TokenAnalysis,
+} from 'interlinearizer';
+import type { AnalysisLinks, AnalysisRepository, ChangeSet } from '../../types/analysis-repository';
+import { normalizeSurfaceForm } from '../../utils/analysis-identity';
+import { jsonCopy } from '../../utils/json-copy';
+
+/** A record kind, named as {@link TextAnalysis} names its list. */
+export type RecordKind = keyof TextAnalysis;
+
+/** A record of one kind. */
+export type RecordOf<Kind extends RecordKind> = TextAnalysis[Kind][number];
+
+/** One kind's staged changes. */
+type Staged<T> = {
+  /** Records to store, by id. */
+  puts: Map<string, T>;
+  /** Records to remove, as they stood before the removal, by id. */
+  deletes: Map<string, T>;
+  /** Ids of the staged puts that no stored record shares, so removing one stages nothing. */
+  created: Set<string>;
+};
+
+function emptyStaged<T>(): Staged<T> {
+  return { puts: new Map(), deletes: new Map(), created: new Set() };
+}
+
+/**
+ * Changes a command stages before they apply, over a repository it reads through. Every read
+ * answers as the repository would once the staged changes applied, and hands out copies the command
+ * may change before staging them.
+ */
+export class ChangeBuffer {
+  private readonly repository: AnalysisRepository;
+
+  private readonly staged: { [Kind in RecordKind]: Staged<RecordOf<Kind>> } = {
+    segmentAnalyses: emptyStaged(),
+    segmentAnalysisLinks: emptyStaged(),
+    tokenAnalyses: emptyStaged(),
+    tokenAnalysisLinks: emptyStaged(),
+    phraseAnalyses: emptyStaged(),
+    phraseAnalysisLinks: emptyStaged(),
+  };
+
+  constructor(repository: AnalysisRepository) {
+    this.repository = repository;
+  }
+
+  /** The token analyses stored under `ids` once the staged changes apply. */
+  async getTokenAnalyses(ids: string[]): Promise<TokenAnalysis[]> {
+    const wanted = new Set(ids);
+    const stored = await this.repository.getTokenAnalyses(ids);
+    return this.overlay('tokenAnalyses', stored, ({ id }) => wanted.has(id));
+  }
+
+  /** The phrase analyses stored under `ids` once the staged changes apply. */
+  async getPhraseAnalyses(ids: string[]): Promise<PhraseAnalysis[]> {
+    const wanted = new Set(ids);
+    const stored = await this.repository.getPhraseAnalyses(ids);
+    return this.overlay('phraseAnalyses', stored, ({ id }) => wanted.has(id));
+  }
+
+  /** The segment analyses stored under `ids` once the staged changes apply. */
+  async getSegmentAnalyses(ids: string[]): Promise<SegmentAnalysis[]> {
+    const wanted = new Set(ids);
+    const stored = await this.repository.getSegmentAnalyses(ids);
+    return this.overlay('segmentAnalyses', stored, ({ id }) => wanted.has(id));
+  }
+
+  /**
+   * The token links on the tokens `tokenRefs` names, and the phrase links touching any of them,
+   * once the staged changes apply.
+   */
+  async findLinksByToken(
+    tokenRefs: string[],
+  ): Promise<Pick<AnalysisLinks, 'tokenAnalysisLinks' | 'phraseAnalysisLinks'>> {
+    const wanted = new Set(tokenRefs);
+    const stored = await this.repository.findLinksByToken(tokenRefs);
+    return {
+      tokenAnalysisLinks: this.overlay('tokenAnalysisLinks', stored.tokenAnalysisLinks, (link) =>
+        wanted.has(link.token.tokenRef),
+      ),
+      phraseAnalysisLinks: this.overlay('phraseAnalysisLinks', stored.phraseAnalysisLinks, (link) =>
+        link.tokens.some(({ tokenRef }) => wanted.has(tokenRef)),
+      ),
+    };
+  }
+
+  /** The segment links on the segments `segmentIds` names once the staged changes apply. */
+  async findLinksBySegment(segmentIds: string[]): Promise<SegmentAnalysisLink[]> {
+    const wanted = new Set(segmentIds);
+    const stored = await this.repository.findLinksBySegment(segmentIds);
+    return this.overlay('segmentAnalysisLinks', stored, (link) => wanted.has(link.segmentId));
+  }
+
+  /** The links of every kind to the analyses `analysisIds` names once the staged changes apply. */
+  async findLinksToAnalyses(analysisIds: string[]): Promise<AnalysisLinks> {
+    const wanted = new Set(analysisIds);
+    const stored = await this.repository.findLinksToAnalyses(analysisIds);
+    const linksTo = ({ analysisId }: { analysisId: string }) => wanted.has(analysisId);
+    return {
+      tokenAnalysisLinks: this.overlay('tokenAnalysisLinks', stored.tokenAnalysisLinks, linksTo),
+      phraseAnalysisLinks: this.overlay('phraseAnalysisLinks', stored.phraseAnalysisLinks, linksTo),
+      segmentAnalysisLinks: this.overlay(
+        'segmentAnalysisLinks',
+        stored.segmentAnalysisLinks,
+        linksTo,
+      ),
+    };
+  }
+
+  /**
+   * The token analyses whose surface text normalizes to one of `normalizedForms` once the staged
+   * changes apply.
+   */
+  async findTokenAnalysesByForm(normalizedForms: string[]): Promise<TokenAnalysis[]> {
+    const wanted = new Set(normalizedForms);
+    const stored = await this.repository.findTokenAnalysesByForm(normalizedForms);
+    return this.overlay('tokenAnalyses', stored, ({ surfaceText }) =>
+      wanted.has(normalizeSurfaceForm(surfaceText)),
+    );
+  }
+
+  /**
+   * The phrase analyses whose surface text normalizes to one of `normalizedForms` once the staged
+   * changes apply.
+   */
+  async findPhraseAnalysesByForm(normalizedForms: string[]): Promise<PhraseAnalysis[]> {
+    const wanted = new Set(normalizedForms);
+    const stored = await this.repository.findPhraseAnalysesByForm(normalizedForms);
+    return this.overlay('phraseAnalyses', stored, ({ surfaceText }) =>
+      wanted.has(normalizeSurfaceForm(surfaceText)),
+    );
+  }
+
+  /** Stages a new record of `kind`, under an id no stored record has. */
+  create<Kind extends RecordKind>(kind: Kind, record: RecordOf<Kind>): void {
+    this.stagedOf(kind).created.add(record.id);
+    this.put(kind, record);
+  }
+
+  /** Stages `record` to be stored whole under its id. */
+  put<Kind extends RecordKind>(kind: Kind, record: RecordOf<Kind>): void {
+    const staged = this.stagedOf(kind);
+    staged.deletes.delete(record.id);
+    staged.puts.set(record.id, jsonCopy(record));
+  }
+
+  /** Stages `record`'s removal; removing one the buffer created stages nothing for it. */
+  delete<Kind extends RecordKind>(kind: Kind, record: RecordOf<Kind>): void {
+    const staged = this.stagedOf(kind);
+    staged.puts.delete(record.id);
+    if (staged.created.delete(record.id)) return;
+    staged.deletes.set(record.id, jsonCopy(record));
+  }
+
+  /** Every record of `kind` the staged changes put or remove, as each stood before or will stand. */
+  touched<Kind extends RecordKind>(kind: Kind): RecordOf<Kind>[] {
+    const staged = this.stagedOf(kind);
+    return [...staged.puts.values(), ...staged.deletes.values()].map((record) => jsonCopy(record));
+  }
+
+  /** The staged changes as one change set; a kind with nothing staged is left out. */
+  toChangeSet(intent: string): ChangeSet {
+    const changes: ChangeSet = { intent };
+    const kinds: RecordKind[] = [
+      'segmentAnalyses',
+      'segmentAnalysisLinks',
+      'tokenAnalyses',
+      'tokenAnalysisLinks',
+      'phraseAnalyses',
+      'phraseAnalysisLinks',
+    ];
+    kinds.forEach((kind) => this.collect(changes, kind));
+    return changes;
+  }
+
+  /**
+   * `stored` as it stands once the staged changes of `kind` apply, keeping only the records
+   * `matches` accepts; `stored` must hold every stored record `matches` accepts.
+   */
+  private overlay<Kind extends RecordKind>(
+    kind: Kind,
+    stored: readonly RecordOf<Kind>[],
+    matches: (record: RecordOf<Kind>) => boolean,
+  ): RecordOf<Kind>[] {
+    const staged = this.stagedOf(kind);
+    const latest = new Map<string, RecordOf<Kind>>();
+    stored.forEach((record) => {
+      if (!staged.deletes.has(record.id)) latest.set(record.id, record);
+    });
+    staged.puts.forEach((record, id) => latest.set(id, record));
+    return [...latest.values()].filter(matches).map((record) => jsonCopy(record));
+  }
+
+  private collect<Kind extends RecordKind>(changes: ChangeSet, kind: Kind): void {
+    const { puts, deletes } = this.stagedOf(kind);
+    if (puts.size === 0 && deletes.size === 0) return;
+    Object.assign(changes, {
+      [kind]: {
+        puts: [...puts.values()].map((record) => jsonCopy(record)),
+        deletes: [...deletes.keys()],
+      },
+    });
+  }
+
+  private stagedOf<Kind extends RecordKind>(kind: Kind): Staged<RecordOf<Kind>> {
+    return this.staged[kind];
+  }
+}
diff --git a/src/services/commands/tokenCommands.ts b/src/services/commands/tokenCommands.ts
new file mode 100644
index 000000000..a1921ad4e
--- /dev/null
+++ b/src/services/commands/tokenCommands.ts
@@ -0,0 +1,291 @@
+import type { TokenAnalysis, TokenAnalysisLink } from 'interlinearizer';
+import { analysesAreIdentical, normalizeSurfaceForm } from '../../utils/analysis-identity';
+import { preferredLink, preferredPayload } from '../../utils/pick-rules';
+import { clearAnalysisGloss, isEmptyTokenAnalysis } from '../../utils/token-analysis-content';
+import type { ChangeBuffer } from './changeBuffer';
+
+/** Where and when a token edit lands. */
+type TokenEdit = {
+  /** `Token.ref` of the token edited. */
+  tokenRef: string;
+  /** The token's current surface text, refreshed on the records the edit touches. */
+  surfaceText: string;
+  /** ISO 8601 time of the edit, stamped on the records it touches. */
+  now: string;
+  /** Id a new link takes, spent only when the edit makes one. */
+  linkId: string;
+};
+
+/** What writing a token's gloss needs. */
+export type WriteGlossRequest = TokenEdit & {
+  /** The gloss; blank clears the token's gloss in `analysisLanguage`. */
+  value: string;
+  /** BCP 47 tag of the language the gloss is written in. */
+  analysisLanguage: string;
+  /** Id a new token analysis takes, spent only when the write makes one. */
+  analysisId: string;
+};
+
+/** What approving a stored analysis for a token needs. */
+export type ApproveAnalysisRequest = TokenEdit & {
+  /** The stored token analysis to approve. */
+  analysisId: string;
+};
+
+/**
+ * The token's approved link an approval tie picks, with its payload. Approved links naming no
+ * stored payload are removed first, so they never persist or crowd the pick.
+ */
+async function resolveApprovedAnalysis(
+  buffer: ChangeBuffer,
+  tokenRef: string,
+): Promise<{ link: TokenAnalysisLink; analysis: TokenAnalysis } | undefined> {
+  const { tokenAnalysisLinks } = await buffer.findLinksByToken([tokenRef]);
+  const approved = tokenAnalysisLinks.filter(({ status }) => status === 'approved');
+  const payloads = new Map(
+    (await buffer.getTokenAnalyses(approved.map(({ analysisId }) => analysisId))).map(
+      (analysis) => [analysis.id, analysis],
+    ),
+  );
+  approved
+    .filter(({ analysisId }) => !payloads.has(analysisId))
+    .forEach((orphan) => buffer.delete('tokenAnalysisLinks', orphan));
+  const link = preferredLink(approved.filter(({ analysisId }) => payloads.has(analysisId)));
+  const analysis = link && payloads.get(link.analysisId);
+  return link && analysis ? { link, analysis } : undefined;
+}
+
+/** Whether a token other than `link`'s links the payload `analysisId`, at any status. */
+async function isSharedByOtherTokens(
+  buffer: ChangeBuffer,
+  link: TokenAnalysisLink,
+  analysisId: string,
+): Promise<boolean> {
+  const { tokenAnalysisLinks } = await buffer.findLinksToAnalyses([analysisId]);
+  return tokenAnalysisLinks.some(({ token }) => token.tokenRef !== link.token.tokenRef);
+}
+
+/**
+ * Moves `link` onto a private copy of its shared payload, so an edit aimed at its token leaves the
+ * others reading what they did. The copy is dated by the edit, being a record of its own.
+ *
+ * @returns The copy, staged; `link` is repointed but left for the caller to stage.
+ */
+function forkSharedAnalysis(
+  buffer: ChangeBuffer,
+  link: TokenAnalysisLink,
+  analysis: TokenAnalysis,
+  forkId: string,
+  now: string,
+): TokenAnalysis {
+  const fork: TokenAnalysis = { ...analysis, id: forkId, createdAt: now, updatedAt: now };
+  buffer.create('tokenAnalyses', fork);
+  link.analysisId = forkId;
+  return fork;
+}
+
+/**
+ * Approves the non-approved link `tokenRef` holds to `analysisId`, so a token taking on a record it
+ * was offered keeps one link to it. The link keeps its creation date and `confidence`.
+ *
+ * @returns The approved link, staged, or `undefined` when the token holds no such link.
+ */
+async function approveHeldLink(
+  buffer: ChangeBuffer,
+  tokenRef: string,
+  analysisId: string,
+  surfaceText: string,
+  now: string,
+): Promise<TokenAnalysisLink | undefined> {
+  const { tokenAnalysisLinks } = await buffer.findLinksByToken([tokenRef]);
+  const held = preferredLink(
+    tokenAnalysisLinks.filter((l) => l.status !== 'approved' && l.analysisId === analysisId),
+  );
+  if (!held) return undefined;
+  held.status = 'approved';
+  held.token.surfaceText = surfaceText;
+  held.updatedAt = now;
+  buffer.put('tokenAnalysisLinks', held);
+  return held;
+}
+
+/** Removes the payload once no link of any status names it. */
+async function reclaimIfUnlinked(buffer: ChangeBuffer, analysis: TokenAnalysis): Promise<void> {
+  const { tokenAnalysisLinks } = await buffer.findLinksToAnalyses([analysis.id]);
+  if (tokenAnalysisLinks.length === 0) buffer.delete('tokenAnalyses', analysis);
+}
+
+/**
+ * Leaves each token holding one link to `analysisId` where it held several. The token keeps its
+ * approved link over any other, then the one an approval tie picks, and the survivor keeps the
+ * token's first annotation date.
+ */
+async function coalesceLinksPerToken(buffer: ChangeBuffer, analysisId: string): Promise<void> {
+  const { tokenAnalysisLinks } = await buffer.findLinksToAnalyses([analysisId]);
+  const byToken = new Map<string, TokenAnalysisLink[]>();
+  tokenAnalysisLinks.forEach((link) => {
+    byToken.set(link.token.tokenRef, [...(byToken.get(link.token.tokenRef) ?? []), link]);
+  });
+  byToken.forEach((links) => {
+    const kept =
+      preferredLink(links.filter(({ status }) => status === 'approved')) ?? preferredLink(links);
+    /* v8 ignore next -- every token's group holds a link */
+    if (!kept) return;
+    const createdAt = links.reduce(
+      (earliest, link) => (link.createdAt < earliest ? link.createdAt : earliest),
+      kept.createdAt,
+    );
+    links.forEach((link) => {
+      if (link !== kept) buffer.delete('tokenAnalysisLinks', link);
+    });
+    if (kept.createdAt !== createdAt) buffer.put('tokenAnalysisLinks', { ...kept, createdAt });
+  });
+}
+
+/**
+ * Folds the just-edited payload into a content-identical one where the edit made one, so an edit
+ * never leaves the duplicate a first write's find-or-create avoids. Every link to the edited
+ * payload moves to the survivor, which keeps its own timestamps, and a token linking both keeps one
+ * link. The survivor's breakdown stays stale only when both payloads' were.
+ */
+async function mergeIntoIdenticalPayload(
+  buffer: ChangeBuffer,
+  analysis: TokenAnalysis,
+  now: string,
+): Promise<void> {
+  const candidates = await buffer.findTokenAnalysesByForm([
+    normalizeSurfaceForm(analysis.surfaceText),
+  ]);
+  const other = preferredPayload(
+    candidates.filter((ta) => ta.id !== analysis.id && analysesAreIdentical(ta, analysis)),
+  );
+  if (!other) return;
+  if (other.morphemesStale && !analysis.morphemesStale) {
+    delete other.morphemesStale;
+    other.updatedAt = now;
+    buffer.put('tokenAnalyses', other);
+  }
+  const { tokenAnalysisLinks } = await buffer.findLinksToAnalyses([analysis.id]);
+  tokenAnalysisLinks.forEach((link) =>
+    buffer.put('tokenAnalysisLinks', { ...link, analysisId: other.id }),
+  );
+  await coalesceLinksPerToken(buffer, other.id);
+  buffer.delete('tokenAnalyses', analysis);
+}
+
+/**
+ * Links a token to an approved payload holding `analysis`'s content, sharing a content-identical
+ * stored one where there is one and staging `analysis` otherwise. A non-approved link the token
+ * holds to the shared payload is approved rather than joined by a second.
+ */
+async function appendApprovedAnalysis(
+  buffer: ChangeBuffer,
+  analysis: TokenAnalysis,
+  { tokenRef, now, linkId }: TokenEdit,
+): Promise<void> {
+  const candidates = await buffer.findTokenAnalysesByForm([
+    normalizeSurfaceForm(analysis.surfaceText),
+  ]);
+  const existing = preferredPayload(candidates.filter((ta) => analysesAreIdentical(ta, analysis)));
+  if (!existing) buffer.create('tokenAnalyses', analysis);
+  else if (await approveHeldLink(buffer, tokenRef, existing.id, analysis.surfaceText, now)) return;
+  buffer.create('tokenAnalysisLinks', {
+    id: linkId,
+    analysisId: existing?.id ?? analysis.id,
+    createdAt: now,
+    updatedAt: now,
+    status: 'approved',
+    token: { tokenRef, surfaceText: analysis.surfaceText },
+  });
+}
+
+/**
+ * Stages writing a token's gloss. The edit is per token: a payload other tokens share is forked
+ * first. An edit that makes the payload identical to another folds it in. A token with no approved
+ * analysis takes a content-identical stored one, or a new one. A blank value clears the gloss, and
+ * a payload left empty goes once nothing links it; a blank write to a token with no approved
+ * analysis stages nothing.
+ */
+export async function writeGloss(buffer: ChangeBuffer, request: WriteGlossRequest): Promise<void> {
+  const { tokenRef, surfaceText, value, analysisLanguage: lang, analysisId, now } = request;
+  const isBlank = value.trim() === '';
+
+  const resolved = await resolveApprovedAnalysis(buffer, tokenRef);
+  if (resolved) {
+    const { link, analysis } = resolved;
+    const target = (await isSharedByOtherTokens(buffer, link, analysis.id))
+      ? forkSharedAnalysis(buffer, link, analysis, analysisId, now)
+      : analysis;
+    target.surfaceText = surfaceText;
+    target.updatedAt = now;
+    link.token.surfaceText = surfaceText;
+    link.updatedAt = now;
+    if (isBlank) {
+      clearAnalysisGloss(target, lang);
+      if (isEmptyTokenAnalysis(target)) {
+        buffer.delete('tokenAnalysisLinks', link);
+        const { tokenAnalysisLinks } = await buffer.findLinksToAnalyses([target.id]);
+        if (tokenAnalysisLinks.length === 0) buffer.delete('tokenAnalyses', target);
+        else buffer.put('tokenAnalyses', target);
+        return;
+      }
+    } else {
+      target.gloss = { ...target.gloss, [lang]: value };
+      delete target.glossSenseRef;
+    }
+    buffer.put('tokenAnalyses', target);
+    buffer.put('tokenAnalysisLinks', link);
+    await mergeIntoIdenticalPayload(buffer, target, now);
+    return;
+  }
+
+  if (isBlank) return;
+  await appendApprovedAnalysis(
+    buffer,
+    { id: analysisId, createdAt: now, updatedAt: now, surfaceText, gloss: { [lang]: value } },
+    request,
+  );
+}
+
+/**
+ * Stages approving the stored payload `analysisId` for a token, in place of any approval it held.
+ * The payload that approval named goes once nothing links it. A token holding a non-approved link
+ * to the payload has that link approved, keeping the earlier creation date of the two; one holding
+ * neither gets a new link. It stages nothing for a payload not stored, or one already approved for
+ * the token.
+ */
+export async function approveAnalysisForToken(
+  buffer: ChangeBuffer,
+  { tokenRef, surfaceText, analysisId, now, linkId }: ApproveAnalysisRequest,
+): Promise<void> {
+  if ((await buffer.getTokenAnalyses([analysisId])).length === 0) return;
+  const resolved = await resolveApprovedAnalysis(buffer, tokenRef);
+  if (resolved?.link.analysisId === analysisId) return;
+
+  const pending = await approveHeldLink(buffer, tokenRef, analysisId, surfaceText, now);
+  if (pending) {
+    if (resolved) {
+      if (resolved.link.createdAt < pending.createdAt) {
+        buffer.put('tokenAnalysisLinks', { ...pending, createdAt: resolved.link.createdAt });
+      }
+      buffer.delete('tokenAnalysisLinks', resolved.link);
+    }
+  } else if (resolved) {
+    const { link } = resolved;
+    link.analysisId = analysisId;
+    link.token.surfaceText = surfaceText;
+    link.updatedAt = now;
+    buffer.put('tokenAnalysisLinks', link);
+  } else {
+    buffer.create('tokenAnalysisLinks', {
+      id: linkId,
+      analysisId,
+      createdAt: now,
+      updatedAt: now,
+      status: 'approved',
+      token: { tokenRef, surfaceText },
+    });
+  }
+
+  if (resolved) await reclaimIfUnlinked(buffer, resolved.analysis);
+}
diff --git a/src/services/draftRepository.ts b/src/services/draftRepository.ts
index d4f0e0787..080ca2ffd 100644
--- a/src/services/draftRepository.ts
+++ b/src/services/draftRepository.ts
@@ -23,7 +23,7 @@ import { applyChangeSet } from '../utils/change-set';
 import { jsonCopy } from '../utils/json-copy';
 import { perfTime, perfTimeAsync, perfTimeAsyncExcluding } from '../utils/perf-marks';
 import { AnalysisIndex } from './analysisIndex';
-import { IndexedRepository, type IndexedAnalysis } from './indexedRepository';
+import { IndexedRepository, type IndexedDraft } from './indexedRepository';
 import { draftAnalysisKey, draftJournalKey, draftKey } from './storageKeys';
 
 /**
@@ -136,7 +136,7 @@ export class DraftRepository extends IndexedRepository implements AnalysisReposi
    * its records. A whole save drops it, since its caller may hold another draft, and so does
    * {@link exportAll}, which reads storage afresh.
    */
-  private current: { draft: DraftProject; index: AnalysisIndex } | undefined;
+  private current: IndexedDraft | undefined;
 
   constructor(storage: KeyValueStorage, sourceProjectId: string, logger: WarningLogger) {
     super();
@@ -264,7 +264,7 @@ export class DraftRepository extends IndexedRepository implements AnalysisReposi
    *   is left as it was.
    */
   async apply(changes: ChangeSet): Promise<ApplyResult> {
-    const { draft: base, index } = await this.keptDraft();
+    const { draft: base, index } = await this.indexed();
     const copied = jsonCopy(changes);
     const { draft, inverse } = applyChangeSet(base, copied);
     await this.writeDraft(draft, undefined, { refuseUnreadable: true });
@@ -273,21 +273,13 @@ export class DraftRepository extends IndexedRepository implements AnalysisReposi
     return { inverse };
   }
 
-  protected async indexed(): Promise<AnalysisIndex> {
-    return (await this.keptDraft()).index;
-  }
-
-  protected keptIndex(): IndexedAnalysis | undefined {
-    return this.current && { analysis: this.current.draft.analysis, index: this.current.index };
-  }
-
   /**
    * The draft this instance keeps and the index over its records, loading the draft from storage
    * and building the index when none is kept.
    *
    * @throws Whatever {@link exportAll} throws.
    */
-  private async keptDraft(): Promise<{ draft: DraftProject; index: AnalysisIndex }> {
+  protected async indexed(): Promise<IndexedDraft> {
     if (!this.current) {
       const { draft } = await this.read(false);
       this.current = { draft, index: new AnalysisIndex(draft.analysis) };
@@ -295,6 +287,10 @@ export class DraftRepository extends IndexedRepository implements AnalysisReposi
     return this.current;
   }
 
+  protected keptIndex(): IndexedDraft | undefined {
+    return this.current;
+  }
+
   /**
    * Loads the stored draft as {@link readDraft} does, noting that this instance has loaded it.
    *
diff --git a/src/services/indexedRepository.ts b/src/services/indexedRepository.ts
index bfbcc7ff0..a82e85225 100644
--- a/src/services/indexedRepository.ts
+++ b/src/services/indexedRepository.ts
@@ -1,28 +1,31 @@
 import type {
   AssignmentStatus,
+  DraftProject,
   PhraseAnalysis,
   SegmentAnalysis,
   SegmentAnalysisLink,
-  TextAnalysis,
   TokenAnalysis,
 } from 'interlinearizer';
 import type {
   AnalysisLinks,
   AnalysisRepository,
   IndexDifference,
+  ScopeRecord,
 } from '../types/analysis-repository';
+import { scopeRecordOf } from '../utils/change-set';
 import { jsonCopy } from '../utils/json-copy';
 import type { AnalysisIndex } from './analysisIndex';
 
-/** An index, with the analysis whose records it is kept over. */
-export type IndexedAnalysis = {
-  analysis: TextAnalysis;
+/** An index, with the draft whose records it is kept over. */
+export type IndexedDraft = {
+  draft: DraftProject;
   index: AnalysisIndex;
 };
 
-/** The lookups of a repository that answers them from an {@link AnalysisIndex} over its records. */
+/** The reads of a repository that answers them from an {@link AnalysisIndex} over its records. */
 export abstract class IndexedRepository implements Pick<
   AnalysisRepository,
+  | 'getScope'
   | 'getTokenAnalyses'
   | 'getPhraseAnalyses'
   | 'getSegmentAnalyses'
@@ -34,6 +37,10 @@ export abstract class IndexedRepository implements Pick<
   | 'findPhraseAnalysesByForm'
   | 'checkIndexes'
 > {
+  async getScope(): Promise<ScopeRecord> {
+    return jsonCopy(scopeRecordOf((await this.indexed()).draft));
+  }
+
   getTokenAnalyses(ids: string[]): Promise<TokenAnalysis[]> {
     return this.query((index) => index.getTokenAnalyses(ids));
   }
@@ -78,21 +85,21 @@ export abstract class IndexedRepository implements Pick<
    */
   async checkIndexes(): Promise<IndexDifference[]> {
     const kept = this.keptIndex();
-    return kept ? kept.index.differencesFrom(kept.analysis) : [];
+    return kept ? kept.index.differencesFrom(kept.draft.analysis) : [];
   }
 
   /** Runs `read` against the index and returns a copy of its result, so callers may change it. */
   private async query<T>(read: (index: AnalysisIndex) => T): Promise<T> {
-    return jsonCopy(read(await this.indexed()));
+    return jsonCopy(read((await this.indexed()).index));
   }
 
   /**
-   * The kept index, built over the stored records first when none is kept.
+   * The kept index and its draft, loaded from storage first when none is kept.
    *
    * @throws Whatever loading the stored records throws.
    */
-  protected abstract indexed(): Promise<AnalysisIndex>;
+  protected abstract indexed(): Promise<IndexedDraft>;
 
-  /** The kept index and the analysis it is kept over, or `undefined` when none is kept. */
-  protected abstract keptIndex(): IndexedAnalysis | undefined;
+  /** The kept index and the draft it is kept over, or `undefined` when none is kept. */
+  protected abstract keptIndex(): IndexedDraft | undefined;
 }
diff --git a/src/services/projectStorage.ts b/src/services/projectStorage.ts
index f3b6e714a..7f7fcc0d5 100644
--- a/src/services/projectStorage.ts
+++ b/src/services/projectStorage.ts
@@ -1144,6 +1144,7 @@ export function openDraftRepository(
     replaceAll: (draft, options) => counted((repository) => repository.replaceAll(draft, options)),
     markClean: () => queued((repository) => repository.markClean()),
     apply: (changes) => counted((repository) => repository.apply(changes)),
+    getScope: () => queued((repository) => repository.getScope()),
     getTokenAnalyses: (ids) => queued((repository) => repository.getTokenAnalyses(ids)),
     getPhraseAnalyses: (ids) => queued((repository) => repository.getPhraseAnalyses(ids)),
     getSegmentAnalyses: (ids) => queued((repository) => repository.getSegmentAnalyses(ids)),
diff --git a/src/services/pt9ImportRepository.ts b/src/services/pt9ImportRepository.ts
index 4aec82bda..a7e9166ea 100644
--- a/src/services/pt9ImportRepository.ts
+++ b/src/services/pt9ImportRepository.ts
@@ -8,7 +8,7 @@ import type {
 import { CURRENT_MODEL_VERSION } from '../types/model-version';
 import { ReadOnlyAnalysisError } from '../types/read-only-analysis-error';
 import { AnalysisIndex } from './analysisIndex';
-import { IndexedRepository, type IndexedAnalysis } from './indexedRepository';
+import { IndexedRepository, type IndexedDraft } from './indexedRepository';
 
 /**
  * A Paratext 9 import's analysis, read in a draft's shape. Only a sync replaces an import's
@@ -27,7 +27,7 @@ export class Pt9ImportRepository extends IndexedRepository implements AnalysisRe
    * The import as first read for a lookup, with the index over its records; dropped once a sync
    * replaces the import or a deletion removes it.
    */
-  private loaded: { draft: DraftProject; revision: number; index: AnalysisIndex } | undefined;
+  private loaded: (IndexedDraft & { revision: number }) | undefined;
 
   /**
    * @param interlinearProjectId - Id of the project to read, which must be a Paratext 9 import.
@@ -83,23 +83,19 @@ export class Pt9ImportRepository extends IndexedRepository implements AnalysisRe
     throw this.readOnlyError();
   }
 
-  protected async indexed(): Promise<AnalysisIndex> {
-    const kept = this.kept();
-    if (kept) return kept.index;
+  /** @throws Whatever {@link exportAll} throws. */
+  protected async indexed(): Promise<IndexedDraft> {
+    const kept = this.keptIndex();
+    if (kept) return kept;
     // The revision is taken before the read, so a sync landing during it forces another.
     const revision = this.revision();
     const draft = await this.readImport();
     this.loaded = { draft, revision, index: new AnalysisIndex(draft.analysis) };
-    return this.loaded.index;
-  }
-
-  protected keptIndex(): IndexedAnalysis | undefined {
-    const kept = this.kept();
-    return kept && { analysis: kept.draft.analysis, index: kept.index };
+    return this.loaded;
   }
 
   /** The import as last read, unless a sync or a deletion has changed it since. */
-  private kept() {
+  protected keptIndex(): IndexedDraft | undefined {
     if (this.loaded?.revision !== this.revision()) this.loaded = undefined;
     return this.loaded;
   }
diff --git a/src/store/analysisSlice.ts b/src/store/analysisSlice.ts
index f2635e7b4..49e5b8e38 100644
--- a/src/store/analysisSlice.ts
+++ b/src/store/analysisSlice.ts
@@ -22,6 +22,7 @@ import {
 import { buildCatalogRows, type HeadingPlacement } from '../utils/analysis-query';
 import type { StaleFreeTranslation } from '../utils/stale-free-translations';
 import { isEmptyMultiString } from '../utils/multi-string';
+import { clearAnalysisGloss, isEmptyTokenAnalysis } from '../utils/token-analysis-content';
 import {
   preferredLink,
   preferredLinkByKey,
@@ -868,46 +869,6 @@ function writeGlossOntoAnalysis(
   mergeIntoIdenticalPayload(state, analysis, now);
 }
 
-/**
- * Determines whether a `TokenAnalysis` carries no analysis content, so a reducer that just emptied
- * one field can decide to drop the whole record instead of letting empty records accumulate in
- * storage. Checks every content field of the type — `gloss`, `morphemes`, `pos`, `features`, and
- * `glossSenseRef` — not only the field the caller emptied, so records carrying imported
- * morphosyntactic or lexicon data are never discarded by an unrelated edit. A gloss counts as empty
- * when it has no entries or every entry is blank, so a record left holding only whitespace glosses
- * (junk from clearing a gloss field) is treated the same as one with no gloss at all.
- *
- * Provenance fields (`confidence`, `producer`, `sourceUser`) are intentionally NOT treated as
- * content: they describe who/what produced an analysis, not an analysis worth keeping on their own.
- * A record holding only provenance and no glosses/morphemes/pos/features is therefore considered
- * empty and may be dropped when its last content field is cleared. This is a deliberate choice — if
- * a future workflow needs provenance-only records (e.g. imported parser metadata) to survive a
- * gloss clear, add the relevant fields to the check below.
- */
-function isEmptyTokenAnalysis(analysis: TokenAnalysis): boolean {
-  return (
-    isEmptyMultiString(analysis.gloss) &&
-    /* v8 ignore next -- the length===0 sub-branch needs an empty-but-defined morphemes array, which no caller produces */
-    (!analysis.morphemes || analysis.morphemes.length === 0) &&
-    analysis.pos === undefined &&
-    analysis.features === undefined &&
-    analysis.glossSenseRef === undefined
-  );
-}
-
-/**
- * Empties one language's gloss, dropping the gloss and the analysis-wide `glossSenseRef` once no
- * language is left holding usable text — a sibling left holding only whitespace counts for neither,
- * so the sense is never stranded on a gloss nothing renders.
- */
-function clearAnalysisGloss(analysis: TokenAnalysis, lang: string): void {
-  if (analysis.gloss) {
-    delete analysis.gloss[lang];
-    if (isEmptyMultiString(analysis.gloss)) delete analysis.gloss;
-  }
-  if (!analysis.gloss) delete analysis.glossSenseRef;
-}
-
 /**
  * The annotated forms a re-split to `forms` would strand: those whose morpheme carries a gloss or a
  * lexicon reference and which the new breakdown leaves no morpheme to hold, in the order the old
diff --git a/src/types/analysis-repository.ts b/src/types/analysis-repository.ts
index cd5bdda2a..749e3a67f 100644
--- a/src/types/analysis-repository.ts
+++ b/src/types/analysis-repository.ts
@@ -206,6 +206,14 @@ export interface AnalysisRepository {
    */
   apply(changes: ChangeSet): Promise<ApplyResult>;
 
+  /**
+   * The draft's own record, as {@link AnalysisRepository.exportAll} would load it without its
+   * analysis.
+   *
+   * @throws Whatever {@link AnalysisRepository.exportAll} throws.
+   */
+  getScope(): Promise<ScopeRecord>;
+
   /**
    * The token analyses stored under `ids`; an id with none stored under it is skipped.
    *
diff --git a/src/types/interlinearizer.d.ts b/src/types/interlinearizer.d.ts
index c43af3ea6..155cb8170 100644
--- a/src/types/interlinearizer.d.ts
+++ b/src/types/interlinearizer.d.ts
@@ -390,6 +390,34 @@ declare module 'papi-shared-types' {
      */
     'interlinearizer.checkIndexes': (sessionId: string) => Promise<string>;
 
+    /**
+     * Writes a token's gloss in a session's analysis language; a blank value clears it.
+     *
+     * @returns A JSON string of the changes it applied.
+     * @throws If the session is read-only or not open, or the edit is refused or fails (logged
+     *   before rethrowing).
+     */
+    'interlinearizer.writeGloss': (
+      sessionId: string,
+      tokenRef: string,
+      surfaceText: string,
+      value: string,
+    ) => Promise<string>;
+
+    /**
+     * Approves a stored token analysis for a token, in place of any approval it held.
+     *
+     * @returns A JSON string of the changes it applied.
+     * @throws If the session is read-only or not open, or the edit is refused or fails (logged
+     *   before rethrowing).
+     */
+    'interlinearizer.approveAnalysisForToken': (
+      sessionId: string,
+      tokenRef: string,
+      surfaceText: string,
+      analysisId: string,
+    ) => Promise<string>;
+
     /**
      * Turns the extension host's timing entries on or off, discarding any it holds. Off until
      * turned on.
diff --git a/src/utils/change-set.ts b/src/utils/change-set.ts
index 0f48c72e5..e11a47445 100644
--- a/src/utils/change-set.ts
+++ b/src/utils/change-set.ts
@@ -7,6 +7,11 @@ export type AppliedChanges = {
   inverse: ChangeSet;
 };
 
+/** Whether `changes` change no record, the scope's record included. */
+export function isEmptyChangeSet(changes: ChangeSet): boolean {
+  return Object.keys(changes).every((key) => key === 'intent');
+}
+
 /** The draft's record, without its analysis or its `dirty` flag. */
 // eslint-disable-next-line @typescript-eslint/no-unused-vars -- named only to leave them out
 export function scopeRecordOf({ analysis, dirty, ...scope }: DraftProject): ScopeRecord {
diff --git a/src/utils/token-analysis-content.ts b/src/utils/token-analysis-content.ts
new file mode 100644
index 000000000..81f65e855
--- /dev/null
+++ b/src/utils/token-analysis-content.ts
@@ -0,0 +1,42 @@
+import type { TokenAnalysis } from 'interlinearizer';
+import { isEmptyMultiString } from './multi-string';
+
+/**
+ * Determines whether a `TokenAnalysis` carries no analysis content, so an edit that just emptied
+ * one field can drop the whole record instead of letting empty records accumulate in storage.
+ * Checks every content field of the type — `gloss`, `morphemes`, `pos`, `features`, and
+ * `glossSenseRef` — not only the field the caller emptied, so records carrying imported
+ * morphosyntactic or lexicon data are never discarded by an unrelated edit. A gloss counts as empty
+ * when it has no entries or every entry is blank, so a record left holding only whitespace glosses
+ * (junk from clearing a gloss field) is treated the same as one with no gloss at all.
+ *
+ * Provenance fields (`confidence`, `producer`, `sourceUser`) are intentionally NOT treated as
+ * content: they describe who/what produced an analysis, not an analysis worth keeping on their own.
+ * A record holding only provenance and no glosses/morphemes/pos/features is therefore considered
+ * empty and may be dropped when its last content field is cleared. This is a deliberate choice — if
+ * a future workflow needs provenance-only records (e.g. imported parser metadata) to survive a
+ * gloss clear, add the relevant fields to the check below.
+ */
+export function isEmptyTokenAnalysis(analysis: TokenAnalysis): boolean {
+  return (
+    isEmptyMultiString(analysis.gloss) &&
+    /* v8 ignore next -- the length===0 sub-branch needs an empty-but-defined morphemes array, which no caller produces */
+    (!analysis.morphemes || analysis.morphemes.length === 0) &&
+    analysis.pos === undefined &&
+    analysis.features === undefined &&
+    analysis.glossSenseRef === undefined
+  );
+}
+
+/**
+ * Empties one language's gloss, dropping the gloss and the analysis-wide `glossSenseRef` once no
+ * language is left holding usable text — a sibling left holding only whitespace counts for neither,
+ * so the sense is never stranded on a gloss nothing renders.
+ */
+export function clearAnalysisGloss(analysis: TokenAnalysis, lang: string): void {
+  if (analysis.gloss) {
+    delete analysis.gloss[lang];
+    if (isEmptyMultiString(analysis.gloss)) delete analysis.gloss;
+  }
+  if (!analysis.gloss) delete analysis.glossSenseRef;
+}

From a7a8a7d2cd59f1d345897e8a1c661efc70ded694 Mon Sep 17 00:00:00 2001
From: Alex Rawlings <alex.rawlings@wycliffe.ca>
Date: Fri, 23 Oct 2026 15:44:18 -0600
Subject: [PATCH 15/22] Keep sense refs on gloss rewrites; list the session's
 language on edit

---
 .../services/analysisSessions.test.ts         | 28 +++++++++++++++++++
 .../commands/tokenCommands.parity.test.ts     |  8 ++++--
 src/__tests__/store/analysisSlice.test.ts     | 14 +++++++---
 src/services/analysisSessions.ts              |  8 +++++-
 src/services/commands/tokenCommands.ts        |  7 ++---
 src/store/analysisSlice.ts                    | 14 ++++------
 6 files changed, 60 insertions(+), 19 deletions(-)

diff --git a/src/__tests__/services/analysisSessions.test.ts b/src/__tests__/services/analysisSessions.test.ts
index 4862f4293..e00a8c112 100644
--- a/src/__tests__/services/analysisSessions.test.ts
+++ b/src/__tests__/services/analysisSessions.test.ts
@@ -510,6 +510,34 @@ describe('AnalysisSessions', () => {
       await expect(stored(storage)).resolves.toMatchObject({ analysis: { tokenAnalyses: [] } });
     });
 
+    it("lists the session's analysis language on a draft listing none, undoing it with the edit", async () => {
+      const { host, sessions, storage } = makeSessions();
+      host.getInterfaceLanguages.mockResolvedValue(['de']);
+      const { sessionId } = await sessions.open(SOURCE);
+
+      await sessions.edit(sessionId, 'add', async (buffer) => {
+        buffer.create('tokenAnalyses', payload('a'));
+      });
+
+      await expect(stored(storage)).resolves.toMatchObject({ analysisLanguages: ['de'] });
+      await sessions.undo(sessionId);
+      await expect(stored(storage)).resolves.toMatchObject({ analysisLanguages: [] });
+    });
+
+    it('leaves the analysis languages of a draft listing some', async () => {
+      const { sessions, storage, saveDraft } = makeSessions();
+      await saveDraft({ ...emptyDraft(SOURCE), analysisLanguages: ['fr', 'en'] });
+      const { sessionId } = await sessions.open(SOURCE);
+      await sessions.setAnalysisLanguage(sessionId, 'de');
+
+      const changes = await sessions.edit(sessionId, 'add', async (buffer) => {
+        buffer.create('tokenAnalyses', payload('a'));
+      });
+
+      expect(changes.scope).toBeUndefined();
+      await expect(stored(storage)).resolves.toMatchObject({ analysisLanguages: ['fr', 'en'] });
+    });
+
     it('applies nothing, and records no undo step, for a command staging nothing', async () => {
       const { sessions, storage } = makeSessions();
       const { sessionId } = await sessions.open(SOURCE);
diff --git a/src/__tests__/services/commands/tokenCommands.parity.test.ts b/src/__tests__/services/commands/tokenCommands.parity.test.ts
index a00234a54..7d61825af 100644
--- a/src/__tests__/services/commands/tokenCommands.parity.test.ts
+++ b/src/__tests__/services/commands/tokenCommands.parity.test.ts
@@ -99,7 +99,7 @@ describe('writeGloss parity with the reducer', () => {
       },
     ],
     [
-      'edits an unshared payload in place, refreshing surface text and dropping its sense',
+      'edits an unshared payload in place, refreshing surface text and keeping its sense',
       {
         analysis: analysisOf(
           [
@@ -113,7 +113,11 @@ describe('writeGloss parity with the reducer', () => {
         input: { surfaceText: 'In,', value: 'at first' },
         expectStore: (store) => {
           expect(store.tokenAnalyses).toStrictEqual([
-            payload('ta-in', 'In,', { gloss: { en: 'at first', fr: 'à' }, updatedAt: NOW }),
+            payload('ta-in', 'In,', {
+              gloss: { en: 'at first', fr: 'à' },
+              glossSenseRef: { authority: 'fwlite', senseId: 's-at' },
+              updatedAt: NOW,
+            }),
           ]);
         },
       },
diff --git a/src/__tests__/store/analysisSlice.test.ts b/src/__tests__/store/analysisSlice.test.ts
index 5cd38f52d..9f109d4ea 100644
--- a/src/__tests__/store/analysisSlice.test.ts
+++ b/src/__tests__/store/analysisSlice.test.ts
@@ -208,7 +208,7 @@ describe('writeGloss', () => {
     expect(tokenAnalyses[0].gloss).toStrictEqual({ und: 'hello' });
   });
 
-  it('drops the sense reference when the reader rewrites the gloss', () => {
+  it('keeps the sense reference when the reader rewrites the gloss', () => {
     const store = createAnalysisStore({
       analysis: {
         analysis: makeAnalysis({
@@ -226,7 +226,10 @@ describe('writeGloss', () => {
 
     const { tokenAnalyses } = store.getState().analysis.analysis;
     expect(tokenAnalyses[0].gloss).toStrictEqual({ und: 'race' });
-    expect(tokenAnalyses[0].glossSenseRef).toBeUndefined();
+    expect(tokenAnalyses[0].glossSenseRef).toStrictEqual({
+      authority: 'x-test',
+      senseId: 'sense-run',
+    });
   });
 
   it('drops the sense reference when the reader clears the gloss', () => {
@@ -5154,7 +5157,7 @@ describe('analysis-keyed reducers', () => {
       expect(tokenAnalyses[0].gloss).toBeUndefined();
     });
 
-    it('drops the sense reference when the reader rewrites the gloss', () => {
+    it('keeps the sense reference when the reader rewrites the gloss', () => {
       const store = makeSharedStore({
         glossSenseRef: { authority: 'x-test', senseId: 'sense-run' },
         morphemes: [{ id: 'm-1', form: 'word', writingSystem: 'en' }],
@@ -5164,7 +5167,10 @@ describe('analysis-keyed reducers', () => {
 
       const { tokenAnalyses } = store.getState().analysis.analysis;
       expect(tokenAnalyses[0].gloss).toEqual({ und: 'race' });
-      expect(tokenAnalyses[0].glossSenseRef).toBeUndefined();
+      expect(tokenAnalyses[0].glossSenseRef).toStrictEqual({
+        authority: 'x-test',
+        senseId: 'sense-run',
+      });
     });
 
     it('drops the sense reference when the reader clears the gloss', () => {
diff --git a/src/services/analysisSessions.ts b/src/services/analysisSessions.ts
index 7be058f68..c73c4ea0c 100644
--- a/src/services/analysisSessions.ts
+++ b/src/services/analysisSessions.ts
@@ -208,13 +208,15 @@ export class AnalysisSessions {
   /**
    * Runs `command` as one edit of the session's analysis, in the session's turn. What it stages
    * applies as one undo step, marking the draft dirty; a command staging nothing applies nothing.
+   * When the draft lists no analysis languages, that step adds the session's analysis language.
    *
    * @returns The changes applied, naming `intent`.
    * @throws {ReadOnlyAnalysisError} If the session is read-only.
    * @throws {ApprovalRuleError} If the changes would give a token or segment a second approved
    *   link; nothing is applied.
    * @throws {Error} If the session is not open.
-   * @throws Whatever the command or applying its changes throws; nothing is applied.
+   * @throws Whatever the command, reading the draft's record, or applying its changes throws;
+   *   nothing is applied.
    */
   edit(
     sessionId: string,
@@ -227,6 +229,10 @@ export class AnalysisSessions {
       const changes = buffer.toChangeSet(intent);
       if (isEmptyChangeSet(changes)) return changes;
       await assertApprovalRule(buffer, session.repository);
+      const scope = await session.repository.getScope();
+      if (scope.analysisLanguages.length === 0) {
+        changes.scope = { ...scope, analysisLanguages: [session.analysisLanguage] };
+      }
       await session.history.apply(changes);
       return changes;
     });
diff --git a/src/services/commands/tokenCommands.ts b/src/services/commands/tokenCommands.ts
index a1921ad4e..ea61832de 100644
--- a/src/services/commands/tokenCommands.ts
+++ b/src/services/commands/tokenCommands.ts
@@ -202,9 +202,9 @@ async function appendApprovedAnalysis(
 /**
  * Stages writing a token's gloss. The edit is per token: a payload other tokens share is forked
  * first. An edit that makes the payload identical to another folds it in. A token with no approved
- * analysis takes a content-identical stored one, or a new one. A blank value clears the gloss, and
- * a payload left empty goes once nothing links it; a blank write to a token with no approved
- * analysis stages nothing.
+ * analysis takes a content-identical stored one, or a new one. A rewrite keeps the payload's
+ * `glossSenseRef`. A blank value clears the gloss, and a payload left empty goes once nothing links
+ * it; a blank write to a token with no approved analysis stages nothing.
  */
 export async function writeGloss(buffer: ChangeBuffer, request: WriteGlossRequest): Promise<void> {
   const { tokenRef, surfaceText, value, analysisLanguage: lang, analysisId, now } = request;
@@ -231,7 +231,6 @@ export async function writeGloss(buffer: ChangeBuffer, request: WriteGlossReques
       }
     } else {
       target.gloss = { ...target.gloss, [lang]: value };
-      delete target.glossSenseRef;
     }
     buffer.put('tokenAnalyses', target);
     buffer.put('tokenAnalysisLinks', link);
diff --git a/src/store/analysisSlice.ts b/src/store/analysisSlice.ts
index 49e5b8e38..50f24f9e6 100644
--- a/src/store/analysisSlice.ts
+++ b/src/store/analysisSlice.ts
@@ -857,7 +857,6 @@ function writeGlossOntoAnalysis(
   } else {
     if (!analysis.gloss) analysis.gloss = {};
     analysis.gloss[lang] = value;
-    delete analysis.glossSenseRef;
   }
   analysis.updatedAt = now;
 
@@ -940,9 +939,9 @@ const analysisSlice = createSlice({
        * stranded on an emptied payload. A blank write to a token with no approved analysis is a
        * no-op, so a focus/blur cycle on an empty gloss never creates a record.
        *
-       * A gloss the reader typed resolves through no lexicon sense of theirs, so a rewrite drops
-       * the payload's `glossSenseRef`. A clear drops it only once no language still holds usable
-       * gloss text, the sense belonging to the analysis rather than to the emptied language.
+       * A rewrite keeps the payload's `glossSenseRef`. A clear drops it only once no language still
+       * holds usable gloss text, the sense belonging to the analysis rather than to the emptied
+       * language.
        */
       reducer(state, action: PayloadAction<WriteGlossPayload>) {
         const { tokenRef, surfaceText, value, id, linkId, now } = action.payload;
@@ -977,7 +976,6 @@ const analysisSlice = createSlice({
           }
           if (!target.gloss) target.gloss = {};
           target.gloss[lang] = value;
-          delete target.glossSenseRef;
           // An in-place edit can make this payload identical to an existing one (e.g. a homograph
           // instance re-glossed to match its sibling); re-converge so the dedupe the create path
           // guarantees on first write also holds after edits.
@@ -1210,9 +1208,9 @@ const analysisSlice = createSlice({
      * removes it and every link to it. An edit that makes the record identical to a sibling
      * collapses it into that sibling, so the edited row disappears from the catalog.
      *
-     * A gloss the reader typed resolves through no lexicon sense of theirs, so a rewrite drops the
-     * record's `glossSenseRef`. A clear drops it only once no language still holds usable gloss
-     * text, the sense belonging to the analysis rather than to the emptied language.
+     * A rewrite keeps the record's `glossSenseRef`. A clear drops it only once no language still
+     * holds usable gloss text, the sense belonging to the analysis rather than to the emptied
+     * language.
      */
     writeAnalysisGloss: {
       /** Reads the clock before the action reaches the reducer, keeping the reducer pure. */

From 78f8dce75c8dad8cc00cc857b5211e49b12ac1fb Mon Sep 17 00:00:00 2001
From: Alex Rawlings <alex.rawlings@wycliffe.ca>
Date: Mon, 26 Oct 2026 08:35:42 -0600
Subject: [PATCH 16/22] Clarify token-command and change-buffer docs

---
 src/main.ts                            |  7 +--
 src/services/commands/approvalRule.ts  |  5 +--
 src/services/commands/changeBuffer.ts  | 12 ++---
 src/services/commands/tokenCommands.ts | 61 +++++++++++++++-----------
 src/services/indexedRepository.ts      |  2 +-
 src/types/analysis-repository.ts       |  3 +-
 src/types/interlinearizer.d.ts         |  2 +-
 src/utils/token-analysis-content.ts    | 21 ++-------
 8 files changed, 55 insertions(+), 58 deletions(-)

diff --git a/src/main.ts b/src/main.ts
index e5ae69088..0db89f7aa 100644
--- a/src/main.ts
+++ b/src/main.ts
@@ -847,7 +847,7 @@ async function runSessionEdit(
   }
 }
 
-/** Ids a new record or link would take, and the time an edit lands. */
+/** Ids that a new record or link would take, and the time an edit lands. */
 function editStamp() {
   return {
     analysisId: crypto.randomUUID(),
@@ -880,7 +880,7 @@ function writeGloss(
 }
 
 /**
- * Approves a stored token analysis for a token, in place of any approval it held.
+ * Approves a stored token analysis for a token, in place of any approval the token held.
  *
  * @returns The changes it applied, as JSON.
  * @throws As {@link runSessionEdit} does.
@@ -1554,7 +1554,8 @@ export async function activate(context: ExecutionActivationContext): Promise<voi
     approveAnalysisForToken,
     {
       method: {
-        summary: 'Approve a stored token analysis for a token, in place of any approval it held',
+        summary:
+          'Approve a stored token analysis for a token, in place of any approval the token held',
         params: [
           sessionIdParam,
           ...tokenParams,
diff --git a/src/services/commands/approvalRule.ts b/src/services/commands/approvalRule.ts
index e0477069d..23d570005 100644
--- a/src/services/commands/approvalRule.ts
+++ b/src/services/commands/approvalRule.ts
@@ -39,9 +39,8 @@ function breaches<Link extends { status: string }>(
 }
 
 /**
- * Refuses the changes staged in `buffer` over `repository` when they would leave a token or segment
- * holding more approved links than one, and more than it held before them. A place the stored
- * analysis already breaches is left to the edits that repair it.
+ * Refuses the staged changes where they would give a token or segment more than one approved link,
+ * and more than it has now.
  *
  * @throws {ApprovalRuleError} If the changes breach the rule anywhere.
  */
diff --git a/src/services/commands/changeBuffer.ts b/src/services/commands/changeBuffer.ts
index 5a5392fa5..67a49cfb5 100644
--- a/src/services/commands/changeBuffer.ts
+++ b/src/services/commands/changeBuffer.ts
@@ -19,7 +19,7 @@ export type RecordOf<Kind extends RecordKind> = TextAnalysis[Kind][number];
 type Staged<T> = {
   /** Records to store, by id. */
   puts: Map<string, T>;
-  /** Records to remove, as they stood before the removal, by id. */
+  /** Records to remove, as they were staged, by id. */
   deletes: Map<string, T>;
   /** Ids of the staged puts that no stored record shares, so removing one stages nothing. */
   created: Set<string>;
@@ -30,9 +30,8 @@ function emptyStaged<T>(): Staged<T> {
 }
 
 /**
- * Changes a command stages before they apply, over a repository it reads through. Every read
- * answers as the repository would once the staged changes applied, and hands out copies the command
- * may change before staging them.
+ * A command's changes, staged over a repository until they apply. Reads through the buffer answer
+ * as if the changes had applied. Each read returns copies that the command may change.
  */
 export class ChangeBuffer {
   private readonly repository: AnalysisRepository;
@@ -158,7 +157,10 @@ export class ChangeBuffer {
     staged.deletes.set(record.id, jsonCopy(record));
   }
 
-  /** Every record of `kind` the staged changes put or remove, as each stood before or will stand. */
+  /**
+   * Every staged record of `kind`: those to store as they will be stored, those to remove as they
+   * were staged.
+   */
   touched<Kind extends RecordKind>(kind: Kind): RecordOf<Kind>[] {
     const staged = this.stagedOf(kind);
     return [...staged.puts.values(), ...staged.deletes.values()].map((record) => jsonCopy(record));
diff --git a/src/services/commands/tokenCommands.ts b/src/services/commands/tokenCommands.ts
index ea61832de..82c8387b8 100644
--- a/src/services/commands/tokenCommands.ts
+++ b/src/services/commands/tokenCommands.ts
@@ -4,7 +4,7 @@ import { preferredLink, preferredPayload } from '../../utils/pick-rules';
 import { clearAnalysisGloss, isEmptyTokenAnalysis } from '../../utils/token-analysis-content';
 import type { ChangeBuffer } from './changeBuffer';
 
-/** Where and when a token edit lands. */
+/** What every token edit needs. */
 type TokenEdit = {
   /** `Token.ref` of the token edited. */
   tokenRef: string;
@@ -33,8 +33,9 @@ export type ApproveAnalysisRequest = TokenEdit & {
 };
 
 /**
- * The token's approved link an approval tie picks, with its payload. Approved links naming no
- * stored payload are removed first, so they never persist or crowd the pick.
+ * The token's approved link that an approval tie picks, with its payload, or `undefined` when there
+ * is none. Approved links that name no stored payload are removed first, so that they never persist
+ * or crowd the pick.
  */
 async function resolveApprovedAnalysis(
   buffer: ChangeBuffer,
@@ -66,10 +67,10 @@ async function isSharedByOtherTokens(
 }
 
 /**
- * Moves `link` onto a private copy of its shared payload, so an edit aimed at its token leaves the
- * others reading what they did. The copy is dated by the edit, being a record of its own.
+ * Repoints `link` to a private copy of its shared payload, so that editing the link's token leaves
+ * the other tokens alone. The copy is dated by the edit. Staging `link` is left to the caller.
  *
- * @returns The copy, staged; `link` is repointed but left for the caller to stage.
+ * @returns The copy, staged.
  */
 function forkSharedAnalysis(
   buffer: ChangeBuffer,
@@ -116,9 +117,9 @@ async function reclaimIfUnlinked(buffer: ChangeBuffer, analysis: TokenAnalysis):
 }
 
 /**
- * Leaves each token holding one link to `analysisId` where it held several. The token keeps its
- * approved link over any other, then the one an approval tie picks, and the survivor keeps the
- * token's first annotation date.
+ * Leaves each token holding one link to `analysisId` where it held several. An approval tie picks
+ * the survivor from the token's approved links, or from all the token's links when none is
+ * approved. The survivor takes the earliest creation date among the token's links to `analysisId`.
  */
 async function coalesceLinksPerToken(buffer: ChangeBuffer, analysisId: string): Promise<void> {
   const { tokenAnalysisLinks } = await buffer.findLinksToAnalyses([analysisId]);
@@ -143,10 +144,12 @@ async function coalesceLinksPerToken(buffer: ChangeBuffer, analysisId: string):
 }
 
 /**
- * Folds the just-edited payload into a content-identical one where the edit made one, so an edit
- * never leaves the duplicate a first write's find-or-create avoids. Every link to the edited
- * payload moves to the survivor, which keeps its own timestamps, and a token linking both keeps one
- * link. The survivor's breakdown stays stale only when both payloads' were.
+ * When the edit made `analysis` identical to another payload, folds it into that one, so that an
+ * edit never leaves a duplicate.
+ *
+ * Every link to `analysis` moves to the survivor. The survivor keeps its own timestamps. A token
+ * that links both keeps one link. The survivor's breakdown stays stale only when both payloads'
+ * were.
  */
 async function mergeIntoIdenticalPayload(
   buffer: ChangeBuffer,
@@ -174,9 +177,9 @@ async function mergeIntoIdenticalPayload(
 }
 
 /**
- * Links a token to an approved payload holding `analysis`'s content, sharing a content-identical
- * stored one where there is one and staging `analysis` otherwise. A non-approved link the token
- * holds to the shared payload is approved rather than joined by a second.
+ * Gives a token an approved link to a payload that holds `analysis`'s content. A content-identical
+ * stored payload is shared where one exists. Otherwise `analysis` is staged. A non-approved link
+ * that the token holds to the shared payload is approved, rather than joined by a second link.
  */
 async function appendApprovedAnalysis(
   buffer: ChangeBuffer,
@@ -200,11 +203,15 @@ async function appendApprovedAnalysis(
 }
 
 /**
- * Stages writing a token's gloss. The edit is per token: a payload other tokens share is forked
- * first. An edit that makes the payload identical to another folds it in. A token with no approved
- * analysis takes a content-identical stored one, or a new one. A rewrite keeps the payload's
- * `glossSenseRef`. A blank value clears the gloss, and a payload left empty goes once nothing links
- * it; a blank write to a token with no approved analysis stages nothing.
+ * Stages writing a token's gloss.
+ *
+ * The edit is per token: a payload that other tokens share is forked first. An edit that makes the
+ * payload identical to another folds it into that one. A rewrite keeps the payload's
+ * `glossSenseRef`. A token with no approved analysis takes a content-identical stored one, or a new
+ * one.
+ *
+ * A blank value clears the gloss. A payload that the clear leaves empty goes once nothing links it.
+ * A blank write to a token with no approved analysis stages nothing.
  */
 export async function writeGloss(buffer: ChangeBuffer, request: WriteGlossRequest): Promise<void> {
   const { tokenRef, surfaceText, value, analysisLanguage: lang, analysisId, now } = request;
@@ -247,11 +254,13 @@ export async function writeGloss(buffer: ChangeBuffer, request: WriteGlossReques
 }
 
 /**
- * Stages approving the stored payload `analysisId` for a token, in place of any approval it held.
- * The payload that approval named goes once nothing links it. A token holding a non-approved link
- * to the payload has that link approved, keeping the earlier creation date of the two; one holding
- * neither gets a new link. It stages nothing for a payload not stored, or one already approved for
- * the token.
+ * Stages approving the stored payload `analysisId` for a token, in place of any approval the token
+ * held. Nothing is staged for a payload that isn't stored, or one already approved for the token.
+ *
+ * A token that holds a non-approved link to the payload has that link approved. The approved link
+ * keeps the earlier of its own creation date and the replaced approval's. A token with no approval
+ * and no link to the payload gets a new link. The payload that the replaced approval named goes
+ * once nothing links it.
  */
 export async function approveAnalysisForToken(
   buffer: ChangeBuffer,
diff --git a/src/services/indexedRepository.ts b/src/services/indexedRepository.ts
index a82e85225..d0573b317 100644
--- a/src/services/indexedRepository.ts
+++ b/src/services/indexedRepository.ts
@@ -22,7 +22,7 @@ export type IndexedDraft = {
   index: AnalysisIndex;
 };
 
-/** The reads of a repository that answers them from an {@link AnalysisIndex} over its records. */
+/** The reads of a repository that keeps an {@link AnalysisIndex} over its records. */
 export abstract class IndexedRepository implements Pick<
   AnalysisRepository,
   | 'getScope'
diff --git a/src/types/analysis-repository.ts b/src/types/analysis-repository.ts
index 749e3a67f..d67f56f02 100644
--- a/src/types/analysis-repository.ts
+++ b/src/types/analysis-repository.ts
@@ -207,8 +207,7 @@ export interface AnalysisRepository {
   apply(changes: ChangeSet): Promise<ApplyResult>;
 
   /**
-   * The draft's own record, as {@link AnalysisRepository.exportAll} would load it without its
-   * analysis.
+   * The draft's own record, as {@link AnalysisRepository.exportAll} would load it.
    *
    * @throws Whatever {@link AnalysisRepository.exportAll} throws.
    */
diff --git a/src/types/interlinearizer.d.ts b/src/types/interlinearizer.d.ts
index 155cb8170..29ceb1abc 100644
--- a/src/types/interlinearizer.d.ts
+++ b/src/types/interlinearizer.d.ts
@@ -405,7 +405,7 @@ declare module 'papi-shared-types' {
     ) => Promise<string>;
 
     /**
-     * Approves a stored token analysis for a token, in place of any approval it held.
+     * Approves a stored token analysis for a token, in place of any approval the token held.
      *
      * @returns A JSON string of the changes it applied.
      * @throws If the session is read-only or not open, or the edit is refused or fails (logged
diff --git a/src/utils/token-analysis-content.ts b/src/utils/token-analysis-content.ts
index 81f65e855..1b4bbbe65 100644
--- a/src/utils/token-analysis-content.ts
+++ b/src/utils/token-analysis-content.ts
@@ -2,20 +2,8 @@ import type { TokenAnalysis } from 'interlinearizer';
 import { isEmptyMultiString } from './multi-string';
 
 /**
- * Determines whether a `TokenAnalysis` carries no analysis content, so an edit that just emptied
- * one field can drop the whole record instead of letting empty records accumulate in storage.
- * Checks every content field of the type — `gloss`, `morphemes`, `pos`, `features`, and
- * `glossSenseRef` — not only the field the caller emptied, so records carrying imported
- * morphosyntactic or lexicon data are never discarded by an unrelated edit. A gloss counts as empty
- * when it has no entries or every entry is blank, so a record left holding only whitespace glosses
- * (junk from clearing a gloss field) is treated the same as one with no gloss at all.
- *
- * Provenance fields (`confidence`, `producer`, `sourceUser`) are intentionally NOT treated as
- * content: they describe who/what produced an analysis, not an analysis worth keeping on their own.
- * A record holding only provenance and no glosses/morphemes/pos/features is therefore considered
- * empty and may be dropped when its last content field is cleared. This is a deliberate choice — if
- * a future workflow needs provenance-only records (e.g. imported parser metadata) to survive a
- * gloss clear, add the relevant fields to the check below.
+ * Whether `analysis` holds no analysis content, so that an edit can drop the record rather than
+ * store an empty one. A gloss with only blank entries counts as empty. Provenance isn't content.
  */
 export function isEmptyTokenAnalysis(analysis: TokenAnalysis): boolean {
   return (
@@ -29,9 +17,8 @@ export function isEmptyTokenAnalysis(analysis: TokenAnalysis): boolean {
 }
 
 /**
- * Empties one language's gloss, dropping the gloss and the analysis-wide `glossSenseRef` once no
- * language is left holding usable text — a sibling left holding only whitespace counts for neither,
- * so the sense is never stranded on a gloss nothing renders.
+ * Empties `lang`'s gloss, dropping `gloss` and `glossSenseRef` once no language holds non-blank
+ * text.
  */
 export function clearAnalysisGloss(analysis: TokenAnalysis, lang: string): void {
   if (analysis.gloss) {

From 9a16e1aedda925ec09b2ab2fc360cd536e044849 Mon Sep 17 00:00:00 2001
From: Tim Haasdyk <tim_haasdyk@sil.org>
Date: Mon, 26 Oct 2026 17:04:52 +0100
Subject: [PATCH 17/22] Share parity test fixtures and assertions through
 parity.ts

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../commands/morphemeCommands.parity.test.ts  | 189 +++++++++---------
 src/__tests__/services/commands/parity.ts     |  69 ++++++-
 .../commands/tokenCommands.parity.test.ts     | 128 +++++-------
 3 files changed, 204 insertions(+), 182 deletions(-)

diff --git a/src/__tests__/services/commands/morphemeCommands.parity.test.ts b/src/__tests__/services/commands/morphemeCommands.parity.test.ts
index 3df7ef29f..d3028a6a1 100644
--- a/src/__tests__/services/commands/morphemeCommands.parity.test.ts
+++ b/src/__tests__/services/commands/morphemeCommands.parity.test.ts
@@ -1,11 +1,6 @@
 /// <reference types="jest" />
 
-import type {
-  MorphemeAnalysis,
-  TextAnalysis,
-  TokenAnalysis,
-  TokenAnalysisLink,
-} from 'interlinearizer';
+import type { MorphemeAnalysis } from 'interlinearizer';
 import {
   deleteMorphemes as deleteMorphemesCommand,
   writeMorphemeGloss as writeMorphemeGlossCommand,
@@ -14,59 +9,29 @@ import {
 import { deleteMorphemes, writeMorphemeGloss, writeMorphemes } from '../../../store/analysisSlice';
 import { emptyAnalysis } from '../../../types/empty-factories';
 import { FIXTURE_STAMPS } from '../../test-helpers';
-import { runParity } from './parity';
-
-const NOW = '2026-06-01T00:00:00.000Z';
-const EARLIER = { createdAt: '2025-06-01T00:00:00.000Z', updatedAt: '2025-06-01T00:00:00.000Z' };
-const LATER = { createdAt: '2026-03-01T00:00:00.000Z', updatedAt: '2026-03-01T00:00:00.000Z' };
-
-function payload(id: string, surfaceText: string, fields: Partial<TokenAnalysis> = {}) {
-  return { id, ...FIXTURE_STAMPS, surfaceText, ...fields };
-}
+import {
+  analysisOf,
+  EARLIER,
+  expectParity,
+  ids,
+  LATER,
+  link,
+  NOW,
+  OTHER_TOKEN,
+  type ParityCase,
+  payload,
+  runParity,
+  TOKEN,
+} from './parity';
 
 function morpheme(id: string, form: string, fields: Partial<MorphemeAnalysis> = {}) {
   return { id, form, writingSystem: 'en', ...fields };
 }
 
-function link(
-  id: string,
-  analysisId: string,
-  tokenRef: string,
-  fields: Partial<TokenAnalysisLink> = {},
-): TokenAnalysisLink {
-  return {
-    id,
-    analysisId,
-    ...FIXTURE_STAMPS,
-    status: 'approved',
-    token: { tokenRef, surfaceText: 'cats' },
-    ...fields,
-  };
-}
-
-function analysisOf(
-  tokenAnalyses: TokenAnalysis[],
-  tokenAnalysisLinks: TokenAnalysisLink[],
-): TextAnalysis {
-  return { ...emptyAnalysis(), tokenAnalyses, tokenAnalysisLinks };
-}
-
-const TOKEN = 'GEN 1:1:0';
-const OTHER_TOKEN = 'GEN 1:2:0';
-
 /** A breakdown as the WebView prepares one: a fresh id per form. */
 const forms = (...list: string[]) => list.map((form, i) => ({ id: `new-m-${i}`, form }));
 const CAT_S = [morpheme('m-cat', 'cat'), morpheme('m-s', '-s')];
 
-type ParityCase<Input> = {
-  analysis: TextAnalysis;
-  input: Input;
-  /** What the reducer's result must show, so the case exercises the path it names. */
-  expectStore: (store: TextAnalysis) => void;
-};
-
-const ids = (records: readonly { id: string }[]) => records.map(({ id }) => id).sort();
-
 type MorphemesInput = {
   surfaceText?: string;
   writingSystem?: string;
@@ -97,7 +62,7 @@ describe('writeMorphemes parity with the reducer', () => {
       {
         analysis: analysisOf(
           [payload('ta-cats', 'cats', { morphemes: CAT_S })],
-          [link('tl-other', 'ta-cats', OTHER_TOKEN)],
+          [link('tl-other', 'ta-cats', OTHER_TOKEN, 'cats')],
         ),
         input: { morphemes: forms('cat', '-s') },
         expectStore: (store) => {
@@ -113,7 +78,7 @@ describe('writeMorphemes parity with the reducer', () => {
       {
         analysis: analysisOf(
           [payload('ta-cats', 'cats', { morphemes: CAT_S })],
-          [link('tl-held', 'ta-cats', TOKEN, { status: 'suggested', confidence: 'low' })],
+          [link('tl-held', 'ta-cats', TOKEN, 'cats', { status: 'suggested', confidence: 'low' })],
         ),
         input: { morphemes: forms('cat', '-s') },
         expectStore: (store) => {
@@ -128,7 +93,7 @@ describe('writeMorphemes parity with the reducer', () => {
       {
         analysis: analysisOf(
           [payload('ta-cats', 'cats', { gloss: { en: 'cats' } })],
-          [link('tl-cats', 'ta-cats', TOKEN)],
+          [link('tl-cats', 'ta-cats', TOKEN, 'cats')],
         ),
         input: { morphemes: forms('cat', '-s') },
         expectStore: (store) => {
@@ -158,7 +123,7 @@ describe('writeMorphemes parity with the reducer', () => {
               morphemesStale: true,
             }),
           ],
-          [link('tl-cats', 'ta-cats', TOKEN)],
+          [link('tl-cats', 'ta-cats', TOKEN, 'cats')],
         ),
         input: { surfaceText: 'cats,', morphemes: forms('cat', 's') },
         expectStore: (store) => {
@@ -190,7 +155,7 @@ describe('writeMorphemes parity with the reducer', () => {
               ],
             }),
           ],
-          [link('tl-baba', 'ta-baba', TOKEN, { token: { tokenRef: TOKEN, surfaceText: 'baba' } })],
+          [link('tl-baba', 'ta-baba', TOKEN, 'baba')],
         ),
         input: { surfaceText: 'baba', morphemes: forms('ba', 'ba', 'ba') },
         expectStore: (store) => {
@@ -211,7 +176,7 @@ describe('writeMorphemes parity with the reducer', () => {
               morphemes: [morpheme('m-cat', 'cat', { gloss: { en: 'feline' } })],
             }),
           ],
-          [link('tl-cats', 'ta-cats', TOKEN)],
+          [link('tl-cats', 'ta-cats', TOKEN, 'cats')],
         ),
         input: { writingSystem: 'en-Latn', morphemes: forms('cat', '-s') },
         expectStore: (store) => {
@@ -227,7 +192,10 @@ describe('writeMorphemes parity with the reducer', () => {
       {
         analysis: analysisOf(
           [payload('ta-cats', 'cats', { morphemes: CAT_S })],
-          [link('tl-cats', 'ta-cats', TOKEN), link('tl-other', 'ta-cats', OTHER_TOKEN)],
+          [
+            link('tl-cats', 'ta-cats', TOKEN, 'cats'),
+            link('tl-other', 'ta-cats', OTHER_TOKEN, 'cats'),
+          ],
         ),
         input: { morphemes: forms('ca', 'ts') },
         expectStore: (store) => {
@@ -243,7 +211,10 @@ describe('writeMorphemes parity with the reducer', () => {
       {
         analysis: analysisOf(
           [payload('ta-cats', 'cats', { morphemes: CAT_S })],
-          [link('tl-cats', 'ta-cats', TOKEN), link('tl-other', 'ta-cats', OTHER_TOKEN)],
+          [
+            link('tl-cats', 'ta-cats', TOKEN, 'cats'),
+            link('tl-other', 'ta-cats', OTHER_TOKEN, 'cats'),
+          ],
         ),
         input: { morphemes: forms('cat', '-s') },
         expectStore: (store) => {
@@ -264,7 +235,10 @@ describe('writeMorphemes parity with the reducer', () => {
             }),
             payload('ta-cats', 'Cats', { ...EARLIER, morphemes: CAT_S, morphemesStale: true }),
           ],
-          [link('tl-split', 'ta-split', TOKEN), link('tl-other', 'ta-cats', OTHER_TOKEN)],
+          [
+            link('tl-split', 'ta-split', TOKEN, 'cats'),
+            link('tl-other', 'ta-cats', OTHER_TOKEN, 'cats'),
+          ],
         ),
         input: { morphemes: forms('cat', '-s') },
         expectStore: (store) => {
@@ -287,8 +261,8 @@ describe('writeMorphemes parity with the reducer', () => {
             payload('ta-cats', 'cats', { ...EARLIER, morphemes: CAT_S }),
           ],
           [
-            link('tl-split', 'ta-split', TOKEN, LATER),
-            link('tl-offered', 'ta-cats', TOKEN, { ...EARLIER, status: 'suggested' }),
+            link('tl-split', 'ta-split', TOKEN, 'cats', LATER),
+            link('tl-offered', 'ta-cats', TOKEN, 'cats', { ...EARLIER, status: 'suggested' }),
           ],
         ),
         input: { morphemes: forms('cat', '-s') },
@@ -311,7 +285,10 @@ describe('writeMorphemes parity with the reducer', () => {
             payload('ta-old', 'cats', { morphemes: [morpheme('m-old', 'cats')] }),
             payload('ta-new', 'cats', { morphemes: CAT_S }),
           ],
-          [link('tl-old', 'ta-old', TOKEN, EARLIER), link('tl-new', 'ta-new', TOKEN, LATER)],
+          [
+            link('tl-old', 'ta-old', TOKEN, 'cats', EARLIER),
+            link('tl-new', 'ta-new', TOKEN, 'cats', LATER),
+          ],
         ),
         input: { morphemes: forms('ca', 'ts') },
         expectStore: (store) => {
@@ -329,7 +306,7 @@ describe('writeMorphemes parity with the reducer', () => {
       {
         analysis: analysisOf(
           [payload('ta-cats', 'cats', { gloss: { en: 'cats' }, morphemes: CAT_S })],
-          [link('tl-cats', 'ta-cats', TOKEN)],
+          [link('tl-cats', 'ta-cats', TOKEN, 'cats')],
         ),
         input: { morphemes: [] },
         expectStore: (store) => {
@@ -340,7 +317,7 @@ describe('writeMorphemes parity with the reducer', () => {
     [
       'removes an approved link whose payload is gone before writing',
       {
-        analysis: analysisOf([], [link('tl-orphan', 'ta-missing', TOKEN)]),
+        analysis: analysisOf([], [link('tl-orphan', 'ta-missing', TOKEN, 'cats')]),
         input: { morphemes: forms('cat', '-s') },
         expectStore: (store) => {
           expect(ids(store.tokenAnalysisLinks)).toStrictEqual(['new-link']);
@@ -379,9 +356,7 @@ describe('writeMorphemes parity with the reducer', () => {
         }),
     );
 
-    expectStore(outcome.store);
-    expect(outcome.host).toStrictEqual(outcome.store);
-    expect(outcome.indexDifferences).toStrictEqual([]);
+    expectParity(outcome, expectStore);
   });
 });
 
@@ -394,7 +369,7 @@ describe('writeMorphemeGloss parity with the reducer', () => {
       {
         analysis: analysisOf(
           [payload('ta-cats', 'cats', { morphemes: CAT_S, morphemesStale: true })],
-          [link('tl-cats', 'ta-cats', TOKEN)],
+          [link('tl-cats', 'ta-cats', TOKEN, 'cats')],
         ),
         input: { value: 'feline' },
         expectStore: (store) => {
@@ -421,7 +396,7 @@ describe('writeMorphemeGloss parity with the reducer', () => {
               morphemes: [morpheme('m-cat', 'cat', { gloss: { en: 'feline', fr: 'chat' } })],
             }),
           ],
-          [link('tl-cats', 'ta-cats', TOKEN)],
+          [link('tl-cats', 'ta-cats', TOKEN, 'cats')],
         ),
         input: { value: 'cat' },
         expectStore: (store) => {
@@ -441,7 +416,7 @@ describe('writeMorphemeGloss parity with the reducer', () => {
               morphemes: [morpheme('m-cat', 'cat', { gloss: { en: 'feline' } })],
             }),
           ],
-          [link('tl-cats', 'ta-cats', TOKEN)],
+          [link('tl-cats', 'ta-cats', TOKEN, 'cats')],
         ),
         input: { value: '  ' },
         expectStore: (store) => {
@@ -460,7 +435,7 @@ describe('writeMorphemeGloss parity with the reducer', () => {
               morphemes: [morpheme('m-cat', 'cat', { gloss: { en: 'feline', fr: 'chat' } })],
             }),
           ],
-          [link('tl-cats', 'ta-cats', TOKEN)],
+          [link('tl-cats', 'ta-cats', TOKEN, 'cats')],
         ),
         input: { value: '' },
         expectStore: (store) => {
@@ -473,7 +448,7 @@ describe('writeMorphemeGloss parity with the reducer', () => {
       {
         analysis: analysisOf(
           [payload('ta-cats', 'cats', { morphemes: CAT_S })],
-          [link('tl-cats', 'ta-cats', TOKEN)],
+          [link('tl-cats', 'ta-cats', TOKEN, 'cats')],
         ),
         input: { value: '' },
         expectStore: (store) => {
@@ -487,7 +462,10 @@ describe('writeMorphemeGloss parity with the reducer', () => {
       {
         analysis: analysisOf(
           [payload('ta-cats', 'cats', { morphemes: CAT_S })],
-          [link('tl-cats', 'ta-cats', TOKEN), link('tl-other', 'ta-cats', OTHER_TOKEN)],
+          [
+            link('tl-cats', 'ta-cats', TOKEN, 'cats'),
+            link('tl-other', 'ta-cats', OTHER_TOKEN, 'cats'),
+          ],
         ),
         input: { value: 'feline' },
         expectStore: (store) => {
@@ -516,7 +494,10 @@ describe('writeMorphemeGloss parity with the reducer', () => {
               morphemesStale: true,
             }),
           ],
-          [link('tl-bare', 'ta-bare', TOKEN), link('tl-other', 'ta-glossed', OTHER_TOKEN)],
+          [
+            link('tl-bare', 'ta-bare', TOKEN, 'cats'),
+            link('tl-other', 'ta-glossed', OTHER_TOKEN, 'cats'),
+          ],
         ),
         input: { value: 'feline' },
         expectStore: (store) => {
@@ -544,7 +525,10 @@ describe('writeMorphemeGloss parity with the reducer', () => {
               morphemes: [morpheme('m-cat-2', 'cat'), morpheme('m-s-2', '-s')],
             }),
           ],
-          [link('tl-glossed', 'ta-glossed', TOKEN), link('tl-other', 'ta-bare', OTHER_TOKEN)],
+          [
+            link('tl-glossed', 'ta-glossed', TOKEN, 'cats'),
+            link('tl-other', 'ta-bare', OTHER_TOKEN, 'cats'),
+          ],
         ),
         input: { value: '' },
         expectStore: (store) => {
@@ -560,7 +544,7 @@ describe('writeMorphemeGloss parity with the reducer', () => {
       {
         analysis: analysisOf(
           [payload('ta-cats', 'cats', { morphemes: CAT_S })],
-          [link('tl-other', 'ta-cats', OTHER_TOKEN)],
+          [link('tl-other', 'ta-cats', OTHER_TOKEN, 'cats')],
         ),
         input: { value: 'feline' },
         expectStore: (store) => {
@@ -573,7 +557,7 @@ describe('writeMorphemeGloss parity with the reducer', () => {
       {
         analysis: analysisOf(
           [payload('ta-cats', 'cats', { morphemes: CAT_S })],
-          [link('tl-cats', 'ta-cats', TOKEN)],
+          [link('tl-cats', 'ta-cats', TOKEN, 'cats')],
         ),
         input: { morphemeId: 'm-missing', value: 'feline' },
         expectStore: (store) => {
@@ -586,7 +570,7 @@ describe('writeMorphemeGloss parity with the reducer', () => {
       {
         analysis: analysisOf(
           [payload('ta-cats', 'cats', { gloss: { en: 'cats' } })],
-          [link('tl-cats', 'ta-cats', TOKEN)],
+          [link('tl-cats', 'ta-cats', TOKEN, 'cats')],
         ),
         input: { value: 'feline' },
         expectStore: (store) => {
@@ -597,7 +581,7 @@ describe('writeMorphemeGloss parity with the reducer', () => {
     [
       'removes an approved link whose payload is gone, and nothing else',
       {
-        analysis: analysisOf([], [link('tl-orphan', 'ta-missing', TOKEN)]),
+        analysis: analysisOf([], [link('tl-orphan', 'ta-missing', TOKEN, 'cats')]),
         input: { value: 'feline' },
         expectStore: (store) => {
           expect(store).toStrictEqual(emptyAnalysis());
@@ -626,9 +610,7 @@ describe('writeMorphemeGloss parity with the reducer', () => {
         }),
     );
 
-    expectStore(outcome.store);
-    expect(outcome.host).toStrictEqual(outcome.store);
-    expect(outcome.indexDifferences).toStrictEqual([]);
+    expectParity(outcome, expectStore);
   });
 });
 
@@ -645,7 +627,7 @@ describe('deleteMorphemes parity with the reducer', () => {
               morphemesStale: true,
             }),
           ],
-          [link('tl-cats', 'ta-cats', TOKEN)],
+          [link('tl-cats', 'ta-cats', TOKEN, 'cats')],
         ),
         expectStore: (store) => {
           expect(store.tokenAnalyses).toStrictEqual([
@@ -660,7 +642,7 @@ describe('deleteMorphemes parity with the reducer', () => {
       {
         analysis: analysisOf(
           [payload('ta-cats', 'cats', { morphemes: CAT_S })],
-          [link('tl-cats', 'ta-cats', TOKEN)],
+          [link('tl-cats', 'ta-cats', TOKEN, 'cats')],
         ),
         expectStore: (store) => {
           expect(store).toStrictEqual(emptyAnalysis());
@@ -672,7 +654,7 @@ describe('deleteMorphemes parity with the reducer', () => {
       {
         analysis: analysisOf(
           [payload('ta-cats', 'cats', { gloss: { en: 'cats' }, morphemes: [] })],
-          [link('tl-cats', 'ta-cats', TOKEN)],
+          [link('tl-cats', 'ta-cats', TOKEN, 'cats')],
         ),
         expectStore: (store) => {
           expect(store.tokenAnalyses).toStrictEqual([
@@ -687,8 +669,8 @@ describe('deleteMorphemes parity with the reducer', () => {
         analysis: analysisOf(
           [payload('ta-cats', 'cats', { morphemes: CAT_S })],
           [
-            link('tl-cats', 'ta-cats', TOKEN),
-            link('tl-rejected', 'ta-cats', TOKEN, { status: 'rejected' }),
+            link('tl-cats', 'ta-cats', TOKEN, 'cats'),
+            link('tl-rejected', 'ta-cats', TOKEN, 'cats', { status: 'rejected' }),
           ],
         ),
         expectStore: (store) => {
@@ -704,7 +686,7 @@ describe('deleteMorphemes parity with the reducer', () => {
       {
         analysis: analysisOf(
           [payload('ta-cats', 'cats', { gloss: {}, morphemes: CAT_S })],
-          [link('tl-cats', 'ta-cats', TOKEN)],
+          [link('tl-cats', 'ta-cats', TOKEN, 'cats')],
         ),
         expectStore: (store) => {
           expect(store).toStrictEqual(emptyAnalysis());
@@ -716,7 +698,7 @@ describe('deleteMorphemes parity with the reducer', () => {
       {
         analysis: analysisOf(
           [payload('ta-cats', 'cats', { morphemes: CAT_S, pos: 'n' })],
-          [link('tl-cats', 'ta-cats', TOKEN)],
+          [link('tl-cats', 'ta-cats', TOKEN, 'cats')],
         ),
         expectStore: (store) => {
           expect(store.tokenAnalyses).toStrictEqual([
@@ -730,7 +712,7 @@ describe('deleteMorphemes parity with the reducer', () => {
       {
         analysis: analysisOf(
           [payload('ta-cats', 'cats', { morphemes: CAT_S, features: { Number: 'Pl' } })],
-          [link('tl-cats', 'ta-cats', TOKEN)],
+          [link('tl-cats', 'ta-cats', TOKEN, 'cats')],
         ),
         expectStore: (store) => {
           expect(store.tokenAnalyses).toStrictEqual([
@@ -749,7 +731,7 @@ describe('deleteMorphemes parity with the reducer', () => {
               glossSenseRef: { authority: 'fwlite', senseId: 's-cat' },
             }),
           ],
-          [link('tl-cats', 'ta-cats', TOKEN)],
+          [link('tl-cats', 'ta-cats', TOKEN, 'cats')],
         ),
         expectStore: (store) => {
           expect(store.tokenAnalyses).toStrictEqual([
@@ -766,7 +748,10 @@ describe('deleteMorphemes parity with the reducer', () => {
       {
         analysis: analysisOf(
           [payload('ta-cats', 'cats', { gloss: { en: 'cats' }, morphemes: CAT_S })],
-          [link('tl-cats', 'ta-cats', TOKEN), link('tl-other', 'ta-cats', OTHER_TOKEN)],
+          [
+            link('tl-cats', 'ta-cats', TOKEN, 'cats'),
+            link('tl-other', 'ta-cats', OTHER_TOKEN, 'cats'),
+          ],
         ),
         expectStore: (store) => {
           expect(ids(store.tokenAnalyses)).toStrictEqual(['new-analysis', 'ta-cats']);
@@ -781,7 +766,10 @@ describe('deleteMorphemes parity with the reducer', () => {
       {
         analysis: analysisOf(
           [payload('ta-cats', 'cats', { morphemes: CAT_S })],
-          [link('tl-cats', 'ta-cats', TOKEN), link('tl-other', 'ta-cats', OTHER_TOKEN)],
+          [
+            link('tl-cats', 'ta-cats', TOKEN, 'cats'),
+            link('tl-other', 'ta-cats', OTHER_TOKEN, 'cats'),
+          ],
         ),
         expectStore: (store) => {
           expect(store.tokenAnalyses).toStrictEqual([
@@ -799,7 +787,10 @@ describe('deleteMorphemes parity with the reducer', () => {
             payload('ta-split', 'cats', { gloss: { en: 'cats' }, morphemes: CAT_S }),
             payload('ta-plain', 'Cats', { ...EARLIER, gloss: { en: 'cats' } }),
           ],
-          [link('tl-split', 'ta-split', TOKEN), link('tl-other', 'ta-plain', OTHER_TOKEN)],
+          [
+            link('tl-split', 'ta-split', TOKEN, 'cats'),
+            link('tl-other', 'ta-plain', OTHER_TOKEN, 'cats'),
+          ],
         ),
         expectStore: (store) => {
           expect(ids(store.tokenAnalyses)).toStrictEqual(['ta-plain']);
@@ -814,7 +805,7 @@ describe('deleteMorphemes parity with the reducer', () => {
       {
         analysis: analysisOf(
           [payload('ta-cats', 'cats', { morphemes: CAT_S })],
-          [link('tl-other', 'ta-cats', OTHER_TOKEN)],
+          [link('tl-other', 'ta-cats', OTHER_TOKEN, 'cats')],
         ),
         expectStore: (store) => {
           expect(store.tokenAnalyses[0].updatedAt).toBe(FIXTURE_STAMPS.updatedAt);
@@ -826,7 +817,7 @@ describe('deleteMorphemes parity with the reducer', () => {
       {
         analysis: analysisOf(
           [payload('ta-cats', 'cats', { gloss: { en: 'cats' } })],
-          [link('tl-cats', 'ta-cats', TOKEN)],
+          [link('tl-cats', 'ta-cats', TOKEN, 'cats')],
         ),
         expectStore: (store) => {
           expect(store.tokenAnalyses[0].updatedAt).toBe(FIXTURE_STAMPS.updatedAt);
@@ -836,7 +827,7 @@ describe('deleteMorphemes parity with the reducer', () => {
     [
       'removes an approved link whose payload is gone, and nothing else',
       {
-        analysis: analysisOf([], [link('tl-orphan', 'ta-missing', TOKEN)]),
+        analysis: analysisOf([], [link('tl-orphan', 'ta-missing', TOKEN, 'cats')]),
         expectStore: (store) => {
           expect(store).toStrictEqual(emptyAnalysis());
         },
@@ -853,8 +844,6 @@ describe('deleteMorphemes parity with the reducer', () => {
         deleteMorphemesCommand(buffer, { tokenRef: TOKEN, analysisId: 'new-analysis', now: NOW }),
     );
 
-    expectStore(outcome.store);
-    expect(outcome.host).toStrictEqual(outcome.store);
-    expect(outcome.indexDifferences).toStrictEqual([]);
+    expectParity(outcome, expectStore);
   });
 });
diff --git a/src/__tests__/services/commands/parity.ts b/src/__tests__/services/commands/parity.ts
index 4307d22d1..8a5e6cb2e 100644
--- a/src/__tests__/services/commands/parity.ts
+++ b/src/__tests__/services/commands/parity.ts
@@ -1,13 +1,63 @@
 /// <reference types="jest" />
 
 import type { UnknownAction } from '@reduxjs/toolkit';
-import type { TextAnalysis } from 'interlinearizer';
+import type { TextAnalysis, TokenAnalysis, TokenAnalysisLink } from 'interlinearizer';
 import { ChangeBuffer } from '../../../services/commands/changeBuffer';
 import { DraftRepository } from '../../../services/draftRepository';
 import reducer from '../../../store/analysisSlice';
 import type { ChangeSet, IndexDifference } from '../../../types/analysis-repository';
-import { emptyDraft } from '../../../types/empty-factories';
-import { memoryStorage, silentLogger } from '../../test-helpers';
+import { emptyAnalysis, emptyDraft } from '../../../types/empty-factories';
+import { FIXTURE_STAMPS, memoryStorage, silentLogger } from '../../test-helpers';
+
+export const NOW = '2026-06-01T00:00:00.000Z';
+export const EARLIER = {
+  createdAt: '2025-06-01T00:00:00.000Z',
+  updatedAt: '2025-06-01T00:00:00.000Z',
+};
+export const LATER = {
+  createdAt: '2026-03-01T00:00:00.000Z',
+  updatedAt: '2026-03-01T00:00:00.000Z',
+};
+
+export const TOKEN = 'GEN 1:1:0';
+export const OTHER_TOKEN = 'GEN 1:2:0';
+
+export function payload(id: string, surfaceText: string, fields: Partial<TokenAnalysis> = {}) {
+  return { id, ...FIXTURE_STAMPS, surfaceText, ...fields };
+}
+
+export function link(
+  id: string,
+  analysisId: string,
+  tokenRef: string,
+  surfaceText: string,
+  fields: Partial<TokenAnalysisLink> = {},
+): TokenAnalysisLink {
+  return {
+    id,
+    analysisId,
+    ...FIXTURE_STAMPS,
+    status: 'approved',
+    token: { tokenRef, surfaceText },
+    ...fields,
+  };
+}
+
+export function analysisOf(
+  tokenAnalyses: TokenAnalysis[],
+  tokenAnalysisLinks: TokenAnalysisLink[],
+): TextAnalysis {
+  return { ...emptyAnalysis(), tokenAnalyses, tokenAnalysisLinks };
+}
+
+export const ids = (records: readonly { id: string }[]) => records.map(({ id }) => id).sort();
+
+export type ParityCase<Input> = {
+  analysis: TextAnalysis;
+  input: Input;
+  /** What the reducer's result must show, so the case exercises the path it names. */
+  expectStore: (store: TextAnalysis) => void;
+};
 
 /** What one input gives through the store's reducer and through the host's command. */
 export type ParityOutcome = {
@@ -73,3 +123,16 @@ export async function runParity(
     indexDifferences: await repository.checkIndexes(),
   };
 }
+
+/**
+ * Asserts the reducer took the path the case names, and that the command left the same analysis
+ * with its indexes matching its records.
+ */
+export function expectParity(
+  outcome: ParityOutcome,
+  expectStore: ParityCase<unknown>['expectStore'],
+): void {
+  expectStore(outcome.store);
+  expect(outcome.host).toStrictEqual(outcome.store);
+  expect(outcome.indexDifferences).toStrictEqual([]);
+}
diff --git a/src/__tests__/services/commands/tokenCommands.parity.test.ts b/src/__tests__/services/commands/tokenCommands.parity.test.ts
index 7d61825af..a83d34841 100644
--- a/src/__tests__/services/commands/tokenCommands.parity.test.ts
+++ b/src/__tests__/services/commands/tokenCommands.parity.test.ts
@@ -1,60 +1,28 @@
 /// <reference types="jest" />
 
-import type { TextAnalysis, TokenAnalysis, TokenAnalysisLink } from 'interlinearizer';
 import {
   approveAnalysisForToken as approveCommand,
   writeGloss as writeGlossCommand,
 } from '../../../services/commands/tokenCommands';
 import { approveAnalysisForToken, writeGloss } from '../../../store/analysisSlice';
 import { emptyAnalysis } from '../../../types/empty-factories';
-import { FIXTURE_STAMPS } from '../../test-helpers';
-import { runParity } from './parity';
-
-const NOW = '2026-06-01T00:00:00.000Z';
-const EARLIER = { createdAt: '2025-06-01T00:00:00.000Z', updatedAt: '2025-06-01T00:00:00.000Z' };
-const LATER = { createdAt: '2026-03-01T00:00:00.000Z', updatedAt: '2026-03-01T00:00:00.000Z' };
-
-function payload(id: string, surfaceText: string, fields: Partial<TokenAnalysis> = {}) {
-  return { id, ...FIXTURE_STAMPS, surfaceText, ...fields };
-}
-
-function link(
-  id: string,
-  analysisId: string,
-  tokenRef: string,
-  fields: Partial<TokenAnalysisLink> = {},
-): TokenAnalysisLink {
-  return {
-    id,
-    analysisId,
-    ...FIXTURE_STAMPS,
-    status: 'approved',
-    token: { tokenRef, surfaceText: 'in' },
-    ...fields,
-  };
-}
-
-function analysisOf(
-  tokenAnalyses: TokenAnalysis[],
-  tokenAnalysisLinks: TokenAnalysisLink[],
-): TextAnalysis {
-  return { ...emptyAnalysis(), tokenAnalyses, tokenAnalysisLinks };
-}
-
-const TOKEN = 'GEN 1:1:0';
-const OTHER_TOKEN = 'GEN 1:2:0';
-
-type ParityCase<Input> = {
-  analysis: TextAnalysis;
-  input: Input;
-  /** What the reducer's result must show, so the case exercises the path it names. */
-  expectStore: (store: TextAnalysis) => void;
-};
+import {
+  analysisOf,
+  EARLIER,
+  expectParity,
+  ids,
+  LATER,
+  link,
+  NOW,
+  OTHER_TOKEN,
+  type ParityCase,
+  payload,
+  runParity,
+  TOKEN,
+} from './parity';
 
 type GlossInput = { surfaceText?: string; value: string };
 
-const ids = (records: readonly { id: string }[]) => records.map(({ id }) => id).sort();
-
 describe('writeGloss parity with the reducer', () => {
   const cases: [string, ParityCase<GlossInput>][] = [
     [
@@ -73,7 +41,7 @@ describe('writeGloss parity with the reducer', () => {
       {
         analysis: analysisOf(
           [payload('ta-in', 'in', { gloss: { en: 'at' } })],
-          [link('tl-other', 'ta-in', OTHER_TOKEN)],
+          [link('tl-other', 'ta-in', OTHER_TOKEN, 'in')],
         ),
         input: { value: 'at' },
         expectStore: (store) => {
@@ -89,7 +57,7 @@ describe('writeGloss parity with the reducer', () => {
       {
         analysis: analysisOf(
           [payload('ta-in', 'in', { gloss: { en: 'at' } })],
-          [link('tl-held', 'ta-in', TOKEN, { status: 'suggested', confidence: 'low' })],
+          [link('tl-held', 'ta-in', TOKEN, 'in', { status: 'suggested', confidence: 'low' })],
         ),
         input: { value: 'at' },
         expectStore: (store) => {
@@ -108,7 +76,7 @@ describe('writeGloss parity with the reducer', () => {
               glossSenseRef: { authority: 'fwlite', senseId: 's-at' },
             }),
           ],
-          [link('tl-in', 'ta-in', TOKEN)],
+          [link('tl-in', 'ta-in', TOKEN, 'in')],
         ),
         input: { surfaceText: 'In,', value: 'at first' },
         expectStore: (store) => {
@@ -127,7 +95,7 @@ describe('writeGloss parity with the reducer', () => {
       {
         analysis: analysisOf(
           [payload('ta-in', 'In', { gloss: { en: 'at' } })],
-          [link('tl-in', 'ta-in', TOKEN), link('tl-other', 'ta-in', OTHER_TOKEN)],
+          [link('tl-in', 'ta-in', TOKEN, 'in'), link('tl-other', 'ta-in', OTHER_TOKEN, 'in')],
         ),
         input: { value: 'start' },
         expectStore: (store) => {
@@ -147,7 +115,7 @@ describe('writeGloss parity with the reducer', () => {
               morphemesStale: true,
             }),
           ],
-          [link('tl-in', 'ta-at', TOKEN), link('tl-other', 'ta-within', OTHER_TOKEN)],
+          [link('tl-in', 'ta-at', TOKEN, 'in'), link('tl-other', 'ta-within', OTHER_TOKEN, 'in')],
         ),
         input: { value: 'within' },
         expectStore: (store) => {
@@ -165,8 +133,8 @@ describe('writeGloss parity with the reducer', () => {
             payload('ta-within', 'In', { ...EARLIER, gloss: { en: 'within' } }),
           ],
           [
-            link('tl-in', 'ta-at', TOKEN, LATER),
-            link('tl-offered', 'ta-within', TOKEN, { ...EARLIER, status: 'suggested' }),
+            link('tl-in', 'ta-at', TOKEN, 'in', LATER),
+            link('tl-offered', 'ta-within', TOKEN, 'in', { ...EARLIER, status: 'suggested' }),
           ],
         ),
         input: { value: 'within' },
@@ -189,8 +157,8 @@ describe('writeGloss parity with the reducer', () => {
             payload('ta-within', 'In', { ...EARLIER, gloss: { en: 'within' } }),
           ],
           [
-            link('tl-in', 'ta-at', TOKEN),
-            link('tl-offered', 'ta-within', OTHER_TOKEN, { status: 'suggested' }),
+            link('tl-in', 'ta-at', TOKEN, 'in'),
+            link('tl-offered', 'ta-within', OTHER_TOKEN, 'in', { status: 'suggested' }),
           ],
         ),
         input: { value: 'within' },
@@ -209,7 +177,7 @@ describe('writeGloss parity with the reducer', () => {
       {
         analysis: analysisOf(
           [payload('ta-in', 'In', { gloss: { en: 'at' } })],
-          [link('tl-in', 'ta-in', TOKEN)],
+          [link('tl-in', 'ta-in', TOKEN, 'in')],
         ),
         input: { value: '' },
         expectStore: (store) => {
@@ -227,7 +195,7 @@ describe('writeGloss parity with the reducer', () => {
               glossSenseRef: { authority: 'fwlite', senseId: 's-at' },
             }),
           ],
-          [link('tl-in', 'ta-in', TOKEN)],
+          [link('tl-in', 'ta-in', TOKEN, 'in')],
         ),
         input: { value: '  ' },
         expectStore: (store) => {
@@ -241,7 +209,7 @@ describe('writeGloss parity with the reducer', () => {
       {
         analysis: analysisOf(
           [payload('ta-in', 'In', { gloss: { en: 'at' } })],
-          [link('tl-in', 'ta-in', TOKEN), link('tl-other', 'ta-in', OTHER_TOKEN)],
+          [link('tl-in', 'ta-in', TOKEN, 'in'), link('tl-other', 'ta-in', OTHER_TOKEN, 'in')],
         ),
         input: { value: '' },
         expectStore: (store) => {
@@ -256,8 +224,8 @@ describe('writeGloss parity with the reducer', () => {
         analysis: analysisOf(
           [payload('ta-in', 'In', { gloss: { en: 'at' } })],
           [
-            link('tl-in', 'ta-in', TOKEN),
-            link('tl-rejected', 'ta-in', TOKEN, { status: 'rejected' }),
+            link('tl-in', 'ta-in', TOKEN, 'in'),
+            link('tl-rejected', 'ta-in', TOKEN, 'in', { status: 'rejected' }),
           ],
         ),
         input: { value: '' },
@@ -275,7 +243,7 @@ describe('writeGloss parity with the reducer', () => {
             payload('ta-in', 'In', { gloss: { en: 'at' }, pos: 'prep' }),
             payload('ta-bare', 'in', { ...EARLIER, pos: 'prep' }),
           ],
-          [link('tl-in', 'ta-in', TOKEN)],
+          [link('tl-in', 'ta-in', TOKEN, 'in')],
         ),
         input: { value: '' },
         expectStore: (store) => {
@@ -289,7 +257,7 @@ describe('writeGloss parity with the reducer', () => {
       {
         analysis: analysisOf(
           [payload('ta-in', 'In', { gloss: { en: 'at' } })],
-          [link('tl-in', 'ta-in', TOKEN), link('tl-other', 'ta-in', OTHER_TOKEN)],
+          [link('tl-in', 'ta-in', TOKEN, 'in'), link('tl-other', 'ta-in', OTHER_TOKEN, 'in')],
         ),
         input: { value: 'at' },
         expectStore: (store) => {
@@ -308,7 +276,10 @@ describe('writeGloss parity with the reducer', () => {
             payload('ta-old', 'In', { gloss: { en: 'old' } }),
             payload('ta-new', 'In', { gloss: { en: 'new' } }),
           ],
-          [link('tl-old', 'ta-old', TOKEN, EARLIER), link('tl-new', 'ta-new', TOKEN, LATER)],
+          [
+            link('tl-old', 'ta-old', TOKEN, 'in', EARLIER),
+            link('tl-new', 'ta-new', TOKEN, 'in', LATER),
+          ],
         ),
         input: { value: 'newer' },
         expectStore: (store) => {
@@ -331,7 +302,7 @@ describe('writeGloss parity with the reducer', () => {
     [
       'removes an approved link whose payload is gone before writing',
       {
-        analysis: analysisOf([], [link('tl-orphan', 'ta-missing', TOKEN)]),
+        analysis: analysisOf([], [link('tl-orphan', 'ta-missing', TOKEN, 'in')]),
         input: { value: 'at' },
         expectStore: (store) => {
           expect(ids(store.tokenAnalysisLinks)).toStrictEqual(['new-link']);
@@ -341,7 +312,7 @@ describe('writeGloss parity with the reducer', () => {
     [
       'removes an approved link whose payload is gone even on a blank write',
       {
-        analysis: analysisOf([], [link('tl-orphan', 'ta-missing', TOKEN)]),
+        analysis: analysisOf([], [link('tl-orphan', 'ta-missing', TOKEN, 'in')]),
         input: { value: '' },
         expectStore: (store) => {
           expect(store).toStrictEqual(emptyAnalysis());
@@ -378,9 +349,7 @@ describe('writeGloss parity with the reducer', () => {
         }),
     );
 
-    expectStore(outcome.store);
-    expect(outcome.host).toStrictEqual(outcome.store);
-    expect(outcome.indexDifferences).toStrictEqual([]);
+    expectParity(outcome, expectStore);
   });
 });
 
@@ -412,7 +381,7 @@ describe('approveAnalysisForToken parity with the reducer', () => {
       {
         analysis: analysisOf(
           [payload('ta-in', 'In', { gloss: { en: 'at' } })],
-          [link('tl-held', 'ta-in', TOKEN, { status: 'candidate', confidence: 'guess' })],
+          [link('tl-held', 'ta-in', TOKEN, 'in', { status: 'candidate', confidence: 'guess' })],
         ),
         input: { analysisId: 'ta-in' },
         expectStore: (store) => {
@@ -432,7 +401,7 @@ describe('approveAnalysisForToken parity with the reducer', () => {
             payload('ta-at', 'In', { gloss: { en: 'at' } }),
             payload('ta-on', 'In', { gloss: { en: 'on' } }),
           ],
-          [link('tl-in', 'ta-at', TOKEN)],
+          [link('tl-in', 'ta-at', TOKEN, 'in')],
         ),
         input: { analysisId: 'ta-on' },
         expectStore: (store) => {
@@ -449,7 +418,7 @@ describe('approveAnalysisForToken parity with the reducer', () => {
             payload('ta-at', 'In', { gloss: { en: 'at' } }),
             payload('ta-on', 'In', { gloss: { en: 'on' } }),
           ],
-          [link('tl-in', 'ta-at', TOKEN), link('tl-other', 'ta-at', OTHER_TOKEN)],
+          [link('tl-in', 'ta-at', TOKEN, 'in'), link('tl-other', 'ta-at', OTHER_TOKEN, 'in')],
         ),
         input: { analysisId: 'ta-on' },
         expectStore: (store) => {
@@ -466,8 +435,8 @@ describe('approveAnalysisForToken parity with the reducer', () => {
             payload('ta-on', 'In', { gloss: { en: 'on' } }),
           ],
           [
-            link('tl-in', 'ta-at', TOKEN, EARLIER),
-            link('tl-held', 'ta-on', TOKEN, { ...LATER, status: 'suggested' }),
+            link('tl-in', 'ta-at', TOKEN, 'in', EARLIER),
+            link('tl-held', 'ta-on', TOKEN, 'in', { ...LATER, status: 'suggested' }),
           ],
         ),
         input: { analysisId: 'ta-on' },
@@ -486,7 +455,7 @@ describe('approveAnalysisForToken parity with the reducer', () => {
     [
       'stages nothing for a payload not stored',
       {
-        analysis: analysisOf([], [link('tl-orphan', 'ta-missing', TOKEN)]),
+        analysis: analysisOf([], [link('tl-orphan', 'ta-missing', TOKEN, 'in')]),
         input: { analysisId: 'ta-unknown' },
         expectStore: (store) => {
           expect(ids(store.tokenAnalysisLinks)).toStrictEqual(['tl-orphan']);
@@ -498,7 +467,10 @@ describe('approveAnalysisForToken parity with the reducer', () => {
       {
         analysis: analysisOf(
           [payload('ta-in', 'In', { gloss: { en: 'at' } })],
-          [link('tl-in', 'ta-in', TOKEN, LATER), link('tl-orphan', 'ta-missing', TOKEN, EARLIER)],
+          [
+            link('tl-in', 'ta-in', TOKEN, 'in', LATER),
+            link('tl-orphan', 'ta-missing', TOKEN, 'in', EARLIER),
+          ],
         ),
         input: { analysisId: 'ta-in' },
         expectStore: (store) => {
@@ -511,7 +483,7 @@ describe('approveAnalysisForToken parity with the reducer', () => {
       {
         analysis: analysisOf(
           [payload('ta-in', 'In', { gloss: { en: 'at' } })],
-          [link('tl-orphan', 'ta-missing', TOKEN)],
+          [link('tl-orphan', 'ta-missing', TOKEN, 'in')],
         ),
         input: { analysisId: 'ta-in' },
         expectStore: (store) => {
@@ -545,8 +517,6 @@ describe('approveAnalysisForToken parity with the reducer', () => {
         }),
     );
 
-    expectStore(outcome.store);
-    expect(outcome.host).toStrictEqual(outcome.store);
-    expect(outcome.indexDifferences).toStrictEqual([]);
+    expectParity(outcome, expectStore);
   });
 });

From e42e08e1c6305e610ced05de0e93b70326ea6b02 Mon Sep 17 00:00:00 2001
From: Tim Haasdyk <tim_haasdyk@sil.org>
Date: Tue, 27 Oct 2026 08:04:26 +0100
Subject: [PATCH 18/22] Pin that a blank morpheme gloss write keeps the sense
 ref

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../commands/morphemeCommands.parity.test.ts  | 24 +++++++++++++++++++
 1 file changed, 24 insertions(+)

diff --git a/src/__tests__/services/commands/morphemeCommands.parity.test.ts b/src/__tests__/services/commands/morphemeCommands.parity.test.ts
index d3028a6a1..f09cc7dc7 100644
--- a/src/__tests__/services/commands/morphemeCommands.parity.test.ts
+++ b/src/__tests__/services/commands/morphemeCommands.parity.test.ts
@@ -443,6 +443,30 @@ describe('writeMorphemeGloss parity with the reducer', () => {
         },
       },
     ],
+    [
+      'clears the gloss and keeps the sense ref',
+      {
+        analysis: analysisOf(
+          [
+            payload('ta-cats', 'cats', {
+              morphemes: [
+                morpheme('m-cat', 'cat', {
+                  gloss: { en: 'feline' },
+                  senseRef: { authority: 'fwlite', senseId: 's-cat' },
+                }),
+              ],
+            }),
+          ],
+          [link('tl-cats', 'ta-cats', TOKEN, 'cats')],
+        ),
+        input: { value: '' },
+        expectStore: (store) => {
+          expect(store.tokenAnalyses[0].morphemes).toStrictEqual([
+            morpheme('m-cat', 'cat', { senseRef: { authority: 'fwlite', senseId: 's-cat' } }),
+          ]);
+        },
+      },
+    ],
     [
       'stamps the payload and link even when a blank value finds no gloss to clear',
       {

From 198874166be71f69cf83bccc690218af21ca70a8 Mon Sep 17 00:00:00 2001
From: Tim Haasdyk <tim_haasdyk@sil.org>
Date: Tue, 27 Oct 2026 09:59:20 +0100
Subject: [PATCH 19/22] State the morpheme wrappers' throw conditions; split
 detachEmptiedAnalysis doc

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 src/main.ts                            | 9 ++++++---
 src/services/commands/tokenCommands.ts | 4 ++--
 2 files changed, 8 insertions(+), 5 deletions(-)

diff --git a/src/main.ts b/src/main.ts
index 70a582ec5..24dc60049 100644
--- a/src/main.ts
+++ b/src/main.ts
@@ -907,7 +907,8 @@ function approveAnalysisForToken(
  * Writes a token's morpheme breakdown, each form in `writingSystem`.
  *
  * @returns The changes it applied, as JSON.
- * @throws As {@link runSessionEdit} does.
+ * @throws If the session is read-only or not open, or the edit is refused or fails (logged before
+ *   rethrowing).
  */
 function writeMorphemes(
   sessionId: string,
@@ -931,7 +932,8 @@ function writeMorphemes(
  * Removes a token's morpheme breakdown.
  *
  * @returns The changes it applied, as JSON.
- * @throws As {@link runSessionEdit} does.
+ * @throws If the session is read-only or not open, or the edit is refused or fails (logged before
+ *   rethrowing).
  */
 function deleteMorphemes(sessionId: string, tokenRef: string): Promise<string> {
   return runSessionEdit(sessionId, 'deleteMorphemes', (buffer) =>
@@ -944,7 +946,8 @@ function deleteMorphemes(sessionId: string, tokenRef: string): Promise<string> {
  * clears it.
  *
  * @returns The changes it applied, as JSON.
- * @throws As {@link runSessionEdit} does.
+ * @throws If the session is read-only or not open, or the edit is refused or fails (logged before
+ *   rethrowing).
  */
 function writeMorphemeGloss(
   sessionId: string,
diff --git a/src/services/commands/tokenCommands.ts b/src/services/commands/tokenCommands.ts
index d3cc94181..0c45ac676 100644
--- a/src/services/commands/tokenCommands.ts
+++ b/src/services/commands/tokenCommands.ts
@@ -111,8 +111,8 @@ async function approveHeldLink(
 }
 
 /**
- * Detaches `link` from the payload an edit through it emptied, which goes once nothing links it and
- * otherwise stays, emptied, as the edit left it.
+ * Removes `link` after an edit through it emptied its payload. The payload goes too when no other
+ * link names it, and otherwise stays, emptied, as the edit left it.
  */
 export async function detachEmptiedAnalysis(
   buffer: ChangeBuffer,

From dc65b215b7d98657d04bd23995be2263b528f63d Mon Sep 17 00:00:00 2001
From: Tim Haasdyk <tim_haasdyk@sil.org>
Date: Tue, 27 Oct 2026 10:12:50 +0100
Subject: [PATCH 20/22] Match the sibling wrappers' @throws wording

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 src/main.ts | 9 +++------
 1 file changed, 3 insertions(+), 6 deletions(-)

diff --git a/src/main.ts b/src/main.ts
index 24dc60049..70a582ec5 100644
--- a/src/main.ts
+++ b/src/main.ts
@@ -907,8 +907,7 @@ function approveAnalysisForToken(
  * Writes a token's morpheme breakdown, each form in `writingSystem`.
  *
  * @returns The changes it applied, as JSON.
- * @throws If the session is read-only or not open, or the edit is refused or fails (logged before
- *   rethrowing).
+ * @throws As {@link runSessionEdit} does.
  */
 function writeMorphemes(
   sessionId: string,
@@ -932,8 +931,7 @@ function writeMorphemes(
  * Removes a token's morpheme breakdown.
  *
  * @returns The changes it applied, as JSON.
- * @throws If the session is read-only or not open, or the edit is refused or fails (logged before
- *   rethrowing).
+ * @throws As {@link runSessionEdit} does.
  */
 function deleteMorphemes(sessionId: string, tokenRef: string): Promise<string> {
   return runSessionEdit(sessionId, 'deleteMorphemes', (buffer) =>
@@ -946,8 +944,7 @@ function deleteMorphemes(sessionId: string, tokenRef: string): Promise<string> {
  * clears it.
  *
  * @returns The changes it applied, as JSON.
- * @throws If the session is read-only or not open, or the edit is refused or fails (logged before
- *   rethrowing).
+ * @throws As {@link runSessionEdit} does.
  */
 function writeMorphemeGloss(
   sessionId: string,

From 3099d5820397bd252b78ec2efbb55a984231a9e8 Mon Sep 17 00:00:00 2001
From: Danny Rorabaugh <imnasnainaec@gmail.com>
Date: Tue, 27 Oct 2026 17:04:06 -0400
Subject: [PATCH 21/22] Share parity fixtures across the command parity tests

The phrase, free-translation, and stale parity tests import NOW, EARLIER,
LATER, TOKEN, OTHER_TOKEN, ids, ParityCase, and the token-shaped payload and
analysisOf from parity.ts instead of redefining them. Helpers shaped for
phrases or segments, and stale's single-surface link, stay local.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../freeTranslationCommands.parity.test.ts    | 15 +------
 .../commands/phraseCommands.parity.test.ts    | 13 +-----
 .../commands/staleCommands.parity.test.ts     | 40 ++++++-------------
 3 files changed, 15 insertions(+), 53 deletions(-)

diff --git a/src/__tests__/services/commands/freeTranslationCommands.parity.test.ts b/src/__tests__/services/commands/freeTranslationCommands.parity.test.ts
index 944777c59..3ff0a75b6 100644
--- a/src/__tests__/services/commands/freeTranslationCommands.parity.test.ts
+++ b/src/__tests__/services/commands/freeTranslationCommands.parity.test.ts
@@ -5,10 +5,8 @@ import { writeSegmentFreeTranslation as writeCommand } from '../../../services/c
 import { writeSegmentFreeTranslation } from '../../../store/analysisSlice';
 import { emptyAnalysis } from '../../../types/empty-factories';
 import { FIXTURE_STAMPS } from '../../test-helpers';
-import { runParity } from './parity';
+import { ids, LATER, NOW, type ParityCase, runParity } from './parity';
 
-const NOW = '2026-06-01T00:00:00.000Z';
-const LATER = { createdAt: '2026-03-01T00:00:00.000Z', updatedAt: '2026-03-01T00:00:00.000Z' };
 const NEW = { linkId: 'new-link', analysisId: 'new-analysis' };
 
 const SEGMENT = 'GEN 1:1';
@@ -34,8 +32,6 @@ function analysisOf(
   return { ...emptyAnalysis(), segmentAnalyses, segmentAnalysisLinks };
 }
 
-const ids = (records: readonly { id: string }[]) => records.map(({ id }) => id).sort();
-
 const translationOf = (store: TextAnalysis, id: string) =>
   store.segmentAnalyses.find((sa) => sa.id === id);
 
@@ -44,15 +40,8 @@ const linkOf = (store: TextAnalysis, id: string) =>
 
 type WriteInput = { value: string; adoptStaleAnalysisId?: string };
 
-type ParityCase = {
-  analysis: TextAnalysis;
-  input: WriteInput;
-  /** What the reducer's result must show, so the case exercises the path it names. */
-  expectStore: (store: TextAnalysis) => void;
-};
-
 describe('writeSegmentFreeTranslation parity with the reducer', () => {
-  const cases: [string, ParityCase][] = [
+  const cases: [string, ParityCase<WriteInput>][] = [
     [
       'makes an approved translation for a segment with none',
       {
diff --git a/src/__tests__/services/commands/phraseCommands.parity.test.ts b/src/__tests__/services/commands/phraseCommands.parity.test.ts
index 73ed1e199..62b28eb55 100644
--- a/src/__tests__/services/commands/phraseCommands.parity.test.ts
+++ b/src/__tests__/services/commands/phraseCommands.parity.test.ts
@@ -28,10 +28,8 @@ import {
 import { emptyAnalysis } from '../../../types/empty-factories';
 import { splitPhraseAtBoundary } from '../../../utils/phrase-arc';
 import { FIXTURE_STAMPS } from '../../test-helpers';
-import { runParity } from './parity';
+import { EARLIER, ids, NOW, type ParityCase, runParity } from './parity';
 
-const NOW = '2026-06-01T00:00:00.000Z';
-const EARLIER = { createdAt: '2025-06-01T00:00:00.000Z', updatedAt: '2025-06-01T00:00:00.000Z' };
 const STAMP = { forkId: 'fork', now: NOW };
 const NEW = { linkId: 'new-link', analysisId: 'new-analysis' };
 const SENSE = { authority: 'fwlite', senseId: 's-beginning' } as const;
@@ -67,21 +65,12 @@ function analysisOf(
   return { ...emptyAnalysis(), phraseAnalyses, phraseAnalysisLinks };
 }
 
-const ids = (records: readonly { id: string }[]) => records.map(({ id }) => id).sort();
-
 const linkOf = (store: TextAnalysis, id: string) =>
   store.phraseAnalysisLinks.find((l) => l.id === id);
 
 const payloadOf = (store: TextAnalysis, id: string) =>
   store.phraseAnalyses.find((pa) => pa.id === id);
 
-type ParityCase<Input> = {
-  analysis: TextAnalysis;
-  input: Input;
-  /** What the reducer's result must show, so the case exercises the path it names. */
-  expectStore: (store: TextAnalysis) => void;
-};
-
 /**
  * Runs `analysis` through both `action` and `command`. Checks the reducer's result with
  * `expectStore`, then checks that the command leaves the same analysis with consistent indexes.
diff --git a/src/__tests__/services/commands/staleCommands.parity.test.ts b/src/__tests__/services/commands/staleCommands.parity.test.ts
index 10e055a39..67755d3b1 100644
--- a/src/__tests__/services/commands/staleCommands.parity.test.ts
+++ b/src/__tests__/services/commands/staleCommands.parity.test.ts
@@ -5,7 +5,6 @@ import type {
   SegmentAnalysis,
   SegmentAnalysisLink,
   TextAnalysis,
-  TokenAnalysis,
   TokenAnalysisLink,
 } from 'interlinearizer';
 import {
@@ -22,11 +21,18 @@ import {
 } from '../../../store/analysisSlice';
 import { emptyAnalysis } from '../../../types/empty-factories';
 import { FIXTURE_STAMPS } from '../../test-helpers';
-import { runParity } from './parity';
-
-function payload(id: string, surfaceText: string, fields: Partial<TokenAnalysis> = {}) {
-  return { id, ...FIXTURE_STAMPS, surfaceText, ...fields };
-}
+import {
+  analysisOf,
+  EARLIER,
+  ids,
+  LATER,
+  NOW,
+  OTHER_TOKEN,
+  type ParityCase,
+  payload,
+  runParity,
+  TOKEN,
+} from './parity';
 
 function morpheme(id: string, form: string, fields: Partial<MorphemeAnalysis> = {}) {
   return { id, form, writingSystem: 'qaa', ...fields };
@@ -48,28 +54,6 @@ function link(
   };
 }
 
-function analysisOf(
-  tokenAnalyses: TokenAnalysis[],
-  tokenAnalysisLinks: TokenAnalysisLink[],
-): TextAnalysis {
-  return { ...emptyAnalysis(), tokenAnalyses, tokenAnalysisLinks };
-}
-
-const NOW = '2026-06-01T00:00:00.000Z';
-const EARLIER = { createdAt: '2025-06-01T00:00:00.000Z', updatedAt: '2025-06-01T00:00:00.000Z' };
-const LATER = { createdAt: '2026-03-01T00:00:00.000Z', updatedAt: '2026-03-01T00:00:00.000Z' };
-const TOKEN = 'GEN 1:1:0';
-const OTHER_TOKEN = 'GEN 1:2:0';
-
-type ParityCase<Input> = {
-  analysis: TextAnalysis;
-  input: Input;
-  /** What the reducer's result must show, so the case exercises the path it names. */
-  expectStore: (store: TextAnalysis) => void;
-};
-
-const ids = (records: readonly { id: string }[]) => records.map(({ id }) => id).sort();
-
 describe('discardStaleAnalysis parity with the reducer', () => {
   const cases: [string, ParityCase<{ tokenRef: string }>][] = [
     [

From 061ba9ef065376a766c09d5336f62ce5591cd141 Mon Sep 17 00:00:00 2001
From: Alex Rawlings <alex.rawlings@wycliffe.ca>
Date: Tue, 27 Oct 2026 15:55:10 -0600
Subject: [PATCH 22/22] Clarify morpheme command docs; state session-edit
 throws in full

---
 src/__tests__/main.test.ts                |  4 +--
 src/__tests__/services/commands/parity.ts | 17 ++++++++++---
 src/main.ts                               | 31 +++++++++++++++--------
 src/services/commands/morphemeCommands.ts | 26 ++++++++++---------
 src/types/interlinearizer.d.ts            |  2 +-
 5 files changed, 51 insertions(+), 29 deletions(-)

diff --git a/src/__tests__/main.test.ts b/src/__tests__/main.test.ts
index 2ecf129d9..e1573e405 100644
--- a/src/__tests__/main.test.ts
+++ b/src/__tests__/main.test.ts
@@ -2008,8 +2008,8 @@ describe('main', () => {
     };
 
     /**
-     * Opens the source project's draft holding `analysis` and `segmentation`, its analysis language
-     * English.
+     * Gives sessions a draft of `src-project` to open. The draft holds `analysis` and
+     * `segmentation`, with English as its analysis language.
      */
     async function seedDraft(
       analysis: Partial<TextAnalysis>,
diff --git a/src/__tests__/services/commands/parity.ts b/src/__tests__/services/commands/parity.ts
index 6360a6aad..52d73a895 100644
--- a/src/__tests__/services/commands/parity.ts
+++ b/src/__tests__/services/commands/parity.ts
@@ -31,22 +31,28 @@ import {
 } from '../../../utils/segmentation';
 import { FIXTURE_STAMPS, memoryStorage, silentLogger } from '../../test-helpers';
 
+/** Stamps dated before {@link FIXTURE_STAMPS}. */
 export const EARLIER = {
   createdAt: '2025-06-01T00:00:00.000Z',
   updatedAt: '2025-06-01T00:00:00.000Z',
 };
+/** Stamps dated after {@link FIXTURE_STAMPS} and before {@link NOW}. */
 export const LATER = {
   createdAt: '2026-03-01T00:00:00.000Z',
   updatedAt: '2026-03-01T00:00:00.000Z',
 };
 
+/** `Token.ref` of the token that a case edits. */
 export const TOKEN = 'GEN 1:1:0';
+/** `Token.ref` of a token that a case leaves alone. */
 export const OTHER_TOKEN = 'GEN 1:2:0';
 
+/** A token analysis stamped with {@link FIXTURE_STAMPS}, with `fields` overriding the defaults. */
 export function payload(id: string, surfaceText: string, fields: Partial<TokenAnalysis> = {}) {
   return { id, ...FIXTURE_STAMPS, surfaceText, ...fields };
 }
 
+/** An approved link stamped with {@link FIXTURE_STAMPS}, with `fields` overriding the defaults. */
 export function link(
   id: string,
   analysisId: string,
@@ -64,6 +70,7 @@ export function link(
   };
 }
 
+/** An analysis holding only the given token analyses and links. */
 export function analysisOf(
   tokenAnalyses: TokenAnalysis[],
   tokenAnalysisLinks: TokenAnalysisLink[],
@@ -71,10 +78,14 @@ export function analysisOf(
   return { ...emptyAnalysis(), tokenAnalyses, tokenAnalysisLinks };
 }
 
+/** The ids of `records`, sorted. */
 export const ids = (records: readonly { id: string }[]) => records.map(({ id }) => id).sort();
 
+/** One input that a parity suite runs through both the reducer and the command. */
 export type ParityCase<Input> = {
+  /** What the draft holds before the input runs. */
   analysis: TextAnalysis;
+  /** What varies between the suite's cases, passed to both the reducer and the command. */
   input: Input;
   /** What the reducer's result must show, so the case exercises the path it names. */
   expectStore: (store: TextAnalysis) => void;
@@ -183,7 +194,7 @@ export type BoundaryParityOutcome = ParityOutcome & {
   hostSegmentation: SegmentationDelta | undefined;
 };
 
-/** The time both ways of a boundary run stamp on the records they touch. */
+/** The time stamped on every record that either way of a run touches. */
 export const NOW = '2026-06-01T00:00:00.000Z';
 
 /** Makes ids in a fixed sequence, so both ways of a run spend the same ids in the same order. */
@@ -291,8 +302,8 @@ export async function runBoundaryParity(
 }
 
 /**
- * Asserts the reducer took the path the case names, and that the command left the same analysis
- * with its indexes matching its records.
+ * Asserts that the reducer took the path that the case names, and that the command left the same
+ * analysis and consistent indexes.
  */
 export function expectParity(
   outcome: ParityOutcome,
diff --git a/src/main.ts b/src/main.ts
index 7de6d0eec..bd3eee84a 100644
--- a/src/main.ts
+++ b/src/main.ts
@@ -872,7 +872,8 @@ function editStamp() {
  * Writes a token's gloss in the session's analysis language; a blank value clears it.
  *
  * @returns The changes it applied, as JSON.
- * @throws As {@link runSessionEdit} does.
+ * @throws If the session is read-only or not open, or the edit is refused or fails. The error is
+ *   logged before rethrowing.
  */
 function writeGloss(
   sessionId: string,
@@ -895,7 +896,8 @@ function writeGloss(
  * Approves a stored token analysis for a token, in place of any approval the token held.
  *
  * @returns The changes it applied, as JSON.
- * @throws As {@link runSessionEdit} does.
+ * @throws If the session is read-only or not open, or the edit is refused or fails. The error is
+ *   logged before rethrowing.
  */
 function approveAnalysisForToken(
   sessionId: string,
@@ -917,7 +919,8 @@ function approveAnalysisForToken(
  * Writes a token's morpheme breakdown, each form in `writingSystem`.
  *
  * @returns The changes it applied, as JSON.
- * @throws As {@link runSessionEdit} does.
+ * @throws If the session is read-only or not open, or the edit is refused or fails. The error is
+ *   logged before rethrowing.
  */
 function writeMorphemes(
   sessionId: string,
@@ -941,7 +944,8 @@ function writeMorphemes(
  * Removes a token's morpheme breakdown.
  *
  * @returns The changes it applied, as JSON.
- * @throws As {@link runSessionEdit} does.
+ * @throws If the session is read-only or not open, or the edit is refused or fails. The error is
+ *   logged before rethrowing.
  */
 function deleteMorphemes(sessionId: string, tokenRef: string): Promise<string> {
   return runSessionEdit(sessionId, 'deleteMorphemes', (buffer) =>
@@ -951,10 +955,11 @@ function deleteMorphemes(sessionId: string, tokenRef: string): Promise<string> {
 
 /**
  * Glosses one morpheme of a token's breakdown in the session's analysis language; a blank value
- * clears it.
+ * clears the morpheme's gloss.
  *
  * @returns The changes it applied, as JSON.
- * @throws As {@link runSessionEdit} does.
+ * @throws If the session is read-only or not open, or the edit is refused or fails. The error is
+ *   logged before rethrowing.
  */
 function writeMorphemeGloss(
   sessionId: string,
@@ -977,7 +982,8 @@ function writeMorphemeGloss(
  * Gives up the place an analysis went stale at, leaving its other places alone.
  *
  * @returns The changes it applied, as JSON.
- * @throws As {@link runSessionEdit} does.
+ * @throws If the session is read-only or not open, or the edit is refused or fails. The error is
+ *   logged before rethrowing.
  */
 function discardStaleAnalysis(
   sessionId: string,
@@ -994,7 +1000,8 @@ function discardStaleAnalysis(
  * whatever that token held.
  *
  * @returns The changes it applied, as JSON.
- * @throws As {@link runSessionEdit} does.
+ * @throws If the session is read-only or not open, or the edit is refused or fails. The error is
+ *   logged before rethrowing.
  */
 function reapplyStaleAnalysis(
   sessionId: string,
@@ -1022,7 +1029,8 @@ function reapplyStaleAnalysis(
  * segment.
  *
  * @returns The changes it applied, as JSON.
- * @throws As {@link runSessionEdit} does.
+ * @throws If the session is read-only or not open, or the edit is refused or fails. The error is
+ *   logged before rethrowing.
  */
 function keepStaleFreeTranslation(
   sessionId: string,
@@ -1044,7 +1052,8 @@ function keepStaleFreeTranslation(
  * Drops a stale free translation, even one whose verse the book no longer holds.
  *
  * @returns The changes it applied, as JSON.
- * @throws As {@link runSessionEdit} does.
+ * @throws If the session is read-only or not open, or the edit is refused or fails. The error is
+ *   logged before rethrowing.
  */
 function discardStaleFreeTranslation(sessionId: string, analysisId: string): Promise<string> {
   return runSessionEdit(sessionId, 'discardStaleFreeTranslation', (buffer) =>
@@ -2066,7 +2075,7 @@ export async function activate(context: ExecutionActivationContext): Promise<voi
     {
       method: {
         summary:
-          "Gloss one morpheme of a token's breakdown in a session's analysis language; a blank value clears it",
+          "Gloss one morpheme of a token's breakdown in a session's analysis language; a blank value clears the morpheme's gloss",
         params: [
           sessionIdParam,
           tokenParams[0],
diff --git a/src/services/commands/morphemeCommands.ts b/src/services/commands/morphemeCommands.ts
index cae199a7f..0cc8f2fb8 100644
--- a/src/services/commands/morphemeCommands.ts
+++ b/src/services/commands/morphemeCommands.ts
@@ -40,11 +40,11 @@ export type WriteMorphemeGlossRequest = Pick<TokenEdit, 'tokenRef' | 'now'> & {
 };
 
 /**
- * Stages writing a token's morpheme breakdown. The edit is per token: a payload other tokens share
- * is forked first. A form the breakdown already carried keeps its morpheme whole, so links to it
- * survive; every morpheme takes `writingSystem`, and the breakdown is never left marked stale. An
- * edit that makes the payload identical to another folds it in. A token with no approved analysis
- * takes a content-identical stored one, or a new one.
+ * Stages writing a token's morpheme breakdown. The edit is per token: a payload that other tokens
+ * share is forked first. A form that the breakdown already carried keeps its morpheme whole, so
+ * links to that morpheme survive. Every morpheme takes `writingSystem`. The breakdown is never left
+ * marked stale. An edit that makes the payload identical to another folds it in. A token with no
+ * approved analysis takes a content-identical stored one, or a new one.
  */
 export async function writeMorphemes(
   buffer: ChangeBuffer,
@@ -85,9 +85,10 @@ export async function writeMorphemes(
 
 /**
  * Stages removing a token's morpheme breakdown and its stale mark. The edit is per token: a payload
- * other tokens share is forked first. A payload the removal leaves empty is detached from the token
- * and goes once nothing links it; one left with content folds into an identical payload where there
- * is one. It stages nothing for a token with no approved analysis, or one with no breakdown.
+ * that other tokens share is forked first. A payload that the removal leaves empty is detached from
+ * the token and goes once nothing links it. A payload left with content folds into an identical
+ * payload, if one exists. It stages nothing for a token with no approved analysis, or one with no
+ * breakdown.
  */
 export async function deleteMorphemes(
   buffer: ChangeBuffer,
@@ -115,10 +116,11 @@ export async function deleteMorphemes(
 
 /**
  * Stages glossing one morpheme of a token's approved breakdown. The edit is per token: a payload
- * other tokens share is forked first, the morpheme keeping its id on the fork. A blank value clears
- * the gloss in `analysisLanguage`, dropping a gloss it leaves empty; the morpheme and its analysis
- * stay. An edit or clear that makes the payload identical to another folds it in. It stages nothing
- * for a token with no approved analysis, or one whose breakdown lacks the morpheme.
+ * that other tokens share is forked first, the morpheme keeping its id on the fork. A blank value
+ * clears the morpheme's gloss in `analysisLanguage`. The morpheme and its analysis stay, even when
+ * no language's gloss is left. An edit or clear that makes the payload identical to another folds
+ * it in. It stages nothing for a token with no approved analysis, or one whose breakdown lacks the
+ * morpheme.
  */
 export async function writeMorphemeGloss(
   buffer: ChangeBuffer,
diff --git a/src/types/interlinearizer.d.ts b/src/types/interlinearizer.d.ts
index 4f0cd56c8..90a49c465 100644
--- a/src/types/interlinearizer.d.ts
+++ b/src/types/interlinearizer.d.ts
@@ -448,7 +448,7 @@ declare module 'papi-shared-types' {
 
     /**
      * Glosses one morpheme of a token's breakdown in a session's analysis language; a blank value
-     * clears it.
+     * clears the morpheme's gloss.
      *
      * @returns A JSON string of the changes it applied.
      * @throws If the session is read-only or not open, or the edit is refused or fails (logged