projectStorage.ts

import papi, { logger } from '@papi/backend';
import type { ExecutionToken } from '@papi/core';
import type {
  DraftProject,
  InterlinearProject,
  SegmentationDelta,
  TextAnalysis,
} from 'interlinearizer';
import { emptyAnalysis, emptyDraft } from '../types/empty-factories';
import { mergeAnalyses, splitAnalysisByBook } from '../utils/analysis-book';
import { assertSupportedModelVersion, CURRENT_MODEL_VERSION } from '../types/model-version';
import { isDraftProject, isTextAnalysis, validateTextAnalysis } from '../types/type-guards';
import { perfTime, perfTimeAsync, perfTimeAsyncExcluding } from '../utils/perf-marks';
import { draftAnalysisKey, draftJournalKey, draftKey, projectKey } from './storageKeys';

const PROJECT_IDS_KEY = 'projectIds';

/**
 * Storage key holding the set of project IDs whose records were orphaned by a failed rollback (see
 * {@link createProject}). Each entry is a `project:{id}` record that was written but never added to
 * the index and could not be deleted at the time; {@link sweepPendingCleanup} retries their
 * deletion.
 */
const PENDING_CLEANUP_KEY = 'pendingCleanup';

/**
 * Serializes all read-modify-write operations on the shared `projectIds` index. Every operation
 * that reads then writes the index must be enqueued here so concurrent calls (e.g. from two open
 * WebView tabs) cannot interleave at await boundaries and silently overwrite each other's updates.
 */
let indexQueue: Promise<unknown> = Promise.resolve();

/**
 * Serializes all read-modify-write operations on the shared `pendingCleanup` set. Recording a new
 * orphan (from a failed rollback) and the sweep that retries deletions must not interleave at await
 * boundaries, or one could overwrite the other's changes to the set.
 */
let pendingCleanupQueue: Promise<unknown> = Promise.resolve();

/**
 * Per-project serialization queues. Keyed by project ID; each entry serializes all
 * read-modify-write operations on that project's storage record so concurrent update and delete
 * calls cannot interleave and create orphaned or stale records.
 */
const projectQueues = new Map<string, Promise<unknown>>();

/**
 * Per-source draft serialization queues. Keyed by `sourceProjectId`; serializes writes to a single
 * draft record so a WebView's rapid auto-saves cannot interleave at await boundaries and persist
 * out of order.
 */
const draftQueues = new Map<string, Promise<unknown>>();

/**
 * The serialized analysis shard last read or written per source project, keyed by source project id
 * then book code. An unknown book counts as changed, so a lost entry costs a write, not
 * correctness.
 */
const shardContentsBySource = new Map<string, Map<string, string>>();

/**
 * Book codes whose shard the last load could not read, per source project. Such a book reaches the
 * caller as empty, so a save holds its shard and manifest entry rather than taking it for wiped.
 */
const unreadableShardsBySource = new Map<string, Set<string>>();

/**
 * Returns `key`'s entry in `map`, storing a fresh one from `create` when absent. The entry itself
 * is returned, not a copy, so a caller's mutations reach the map.
 */
function getOrCreateEntry<K, V>(map: Map<K, V>, key: K, create: () => V): V {
  const existing = map.get(key);
  if (existing !== undefined) return existing;
  const created = create();
  map.set(key, created);
  return created;
}

/**
 * Enqueues `fn` on a single shared serialization queue and returns a promise that resolves or
 * rejects with `fn`'s result. The queue always advances regardless of whether `fn` throws, so a
 * failed operation does not block later ones.
 *
 * @param get - Returns the current tail of the queue to chain `fn` after.
 * @param set - Stores the new tail of the queue (a promise that settles once `fn` settles).
 * @param fn - The async function to serialize.
 * @throws Whatever `fn` throws; the queue advances past the error so later operations are not
 *   blocked.
 */
function enqueueOnQueue<T>(
  get: () => Promise<unknown>,
  set: (queue: Promise<unknown>) => void,
  fn: () => Promise<T>,
): Promise<T> {
  const result = get().then(fn);
  set(result.catch(() => {}));
  return result;
}

/**
 * Enqueues `fn` on the index serialization queue, so it runs only once every index operation
 * enqueued before it has settled.
 *
 * @throws Whatever `fn` throws; the queue advances past the error so later operations are not
 *   blocked.
 */
function enqueueIndexOp<T>(fn: () => Promise<T>): Promise<T> {
  return enqueueOnQueue(
    () => indexQueue,
    (q) => {
      indexQueue = q;
    },
    fn,
  );
}

/**
 * Enqueues `fn` on the pending-cleanup serialization queue, so it runs only once every
 * pending-cleanup operation enqueued before it has settled.
 *
 * @throws Whatever `fn` throws; the queue advances past the error so later operations are not
 *   blocked.
 */
function enqueuePendingCleanupOp<T>(fn: () => Promise<T>): Promise<T> {
  return enqueueOnQueue(
    () => pendingCleanupQueue,
    (q) => {
      pendingCleanupQueue = q;
    },
    fn,
  );
}

/**
 * Awaits every operation, so a caller that rejects leaves none of them still in flight.
 *
 * @throws Whatever the first rejecting operation threw, in argument order.
 */
async function settleAll(operations: readonly Promise<unknown>[]): Promise<void> {
  const outcomes = await Promise.allSettled(operations);
  const failure = outcomes.find((outcome) => outcome.status === 'rejected');
  if (failure?.status === 'rejected') throw failure.reason;
}

/**
 * Enqueues `fn` on the serialization queue identified by `key` within `queues` and returns a
 * promise that resolves or rejects with `fn`'s result. Cleans up the queue entry when the operation
 * settles.
 *
 * @param queues - The queue map to serialize on; one chain per `key`.
 * @param key - The key whose queue `fn` should join.
 * @param fn - The async function to serialize.
 * @throws Whatever `fn` throws; the queue entry is removed and the rejection propagates to the
 *   caller.
 */
function enqueueSerialized<T>(
  queues: Map<string, Promise<unknown>>,
  key: string,
  fn: () => Promise<T>,
): Promise<T> {
  const previous = queues.get(key) ?? Promise.resolve();
  const result = previous.then(fn);
  let settled: Promise<void>;
  const cleanup = () => {
    if (queues.get(key) === settled) queues.delete(key);
  };
  settled = result.then(cleanup, cleanup);
  queues.set(key, settled);
  return result;
}

/**
 * Enqueues `fn` on the serialization queue for project `id`, so it runs only once every operation
 * enqueued before it on that same project has settled; other projects proceed independently.
 *
 * @throws Whatever `fn` throws; the queue entry is removed and the rejection propagates to the
 *   caller.
 */
function enqueueProjectOp<T>(id: string, fn: () => Promise<T>): Promise<T> {
  return enqueueSerialized(projectQueues, id, fn);
}

/** The error rejecting a user write to a Paratext 9 import, whose content only sync replaces. */
function pt9ImportReadOnlyError(id: string): Error {
  return new Error(`Project ${id} is a Paratext 9 import and is read-only`);
}

/**
 * Names the shards a save is about to strand if it is interrupted, so the next run can find them
 * without the in-memory tally. Storage cannot enumerate keys, so a shard the manifest does not name
 * is otherwise unreachable once this process is gone.
 */
interface ShardJournal {
  /**
   * Books whose shard this save wrote, pending the envelope write that names them. A load reads
   * these, recovering work an interrupted save would otherwise strand.
   */
  adding: string[];
  /**
   * Books whose shard is orphaned pending deletion, already dropped from the envelope. A load must
   * not read these, or the wipe that recorded them would undo itself; they await a retried
   * deletion.
   */
  removing: string[];
}

/** A journal naming no shards, which is what a cleared or unusable one recovers as. */
function emptyShardJournal(): ShardJournal {
  return { adding: [], removing: [] };
}

/** Type guard for a JSON-parsed value that must be a {@link ShardJournal}. */
function isShardJournal(value: unknown): value is ShardJournal {
  if (!value || typeof value !== 'object') return false;
  return (
    'adding' in value &&
    isStringArray(value.adding) &&
    'removing' in value &&
    isStringArray(value.removing)
  );
}

/**
 * Reads a source project's shard journal, recovering a missing, unparseable, or malformed one as
 * empty. A journal is a recovery hint rather than a record of truth: every book it names is
 * cross-checked against storage before it is acted on, so losing one costs an orphaned shard, never
 * correctness.
 *
 * @throws If `papi.storage.readUserData` rejects for any non-ENOENT reason.
 */
async function readShardJournal(
  token: ExecutionToken,
  sourceProjectId: string,
): Promise<ShardJournal> {
  let raw: string;
  try {
    raw = await papi.storage.readUserData(token, draftJournalKey(sourceProjectId));
  } catch (e) {
    if (isNotFound(e)) return emptyShardJournal();
    throw e;
  }
  try {
    const parsed: unknown = JSON.parse(raw);
    if (isShardJournal(parsed)) return parsed;
    logger.warn(
      `Interlinearizer: shard journal for ${sourceProjectId} is malformed; treating as empty`,
    );
  } catch {
    logger.warn(
      `Interlinearizer: shard journal for ${sourceProjectId} is not valid JSON; treating as empty`,
    );
  }
  return emptyShardJournal();
}

/**
 * Writes a source project's shard journal, deleting the record instead when it names nothing, so a
 * settled draft leaves no journal behind.
 *
 * @throws If `papi.storage.writeUserData` rejects, or if `papi.storage.deleteUserData` rejects for
 *   any non-ENOENT reason.
 */
async function writeShardJournal(
  token: ExecutionToken,
  sourceProjectId: string,
  journal: ShardJournal,
): Promise<void> {
  const key = draftJournalKey(sourceProjectId);
  if (journal.adding.length === 0 && journal.removing.length === 0) {
    try {
      await papi.storage.deleteUserData(token, key);
    } catch (e) {
      if (!isNotFound(e)) throw e;
    }
    return;
  }
  await papi.storage.writeUserData(token, key, JSON.stringify(journal));
}

/** A draft as persisted: the in-memory draft with an always-empty `analysis`, held in shards. */
type StoredDraft = DraftProject & {
  /**
   * Book codes of the shards holding this draft's analysis. Storage cannot enumerate keys, so
   * nothing else can say which shards a draft owns.
   */
  analysisBooks: string[];
};

/**
 * Separates a validated draft from its shard manifest, which is absent when the analysis is stored
 * inline and dropped when it is unusable.
 */
function withoutShardManifest(draft: DraftProject): DraftProject & { analysisBooks?: string[] } {
  if (!('analysisBooks' in draft)) return draft;
  const { analysisBooks, ...rest } = draft;
  return isStringArray(analysisBooks) ? { ...rest, analysisBooks } : rest;
}

/** One book's shard as loaded. */
type LoadedShard = {
  /** Empty when the shard could not be read, standing in for content this build cannot recover. */
  analysis: TextAnalysis;
  /**
   * Whether the shard was read, and failing that, whether it still occupies storage — which is what
   * decides whether anything is left to keep reachable.
   */
  state: 'loaded' | 'unusable' | 'absent';
};

/**
 * Reads the record stored at `key`.
 *
 * @returns `undefined` when `key` has never been written (ENOENT).
 * @throws If `papi.storage.readUserData` rejects for any non-ENOENT reason.
 */
async function readRecord(token: ExecutionToken, key: string): Promise<string | undefined> {
  try {
    return await papi.storage.readUserData(token, key);
  } catch (e) {
    if (isNotFound(e)) return undefined;
    throw e;
  }
}

/**
 * Parses one book's analysis shard as read from `key`, treating a missing or unusable one as empty
 * so a single lost book does not fail the whole load.
 */
function parseAnalysisShard(raw: string | undefined, key: string): LoadedShard {
  if (raw === undefined) return { analysis: emptyAnalysis(), state: 'absent' };
  try {
    const parsed: unknown = JSON.parse(raw);
    if (!isTextAnalysis(parsed)) {
      logger.warn(`Interlinearizer: analysis shard ${key} failed validation; treating as empty`);
      return { analysis: emptyAnalysis(), state: 'unusable' };
    }
    return { analysis: parsed, state: 'loaded' };
  } catch {
    logger.warn(`Interlinearizer: analysis shard ${key} is not valid JSON; treating as empty`);
    return { analysis: emptyAnalysis(), state: 'unusable' };
  }
}

/**
 * Returns true when `e` is a file-not-found error (ENOENT) from the Node.js file system, which is
 * what `papi.storage.readUserData` throws when the requested key has never been written.
 */
function isNotFound(e: unknown): boolean {
  return !!e && typeof e === 'object' && 'code' in e && e.code === 'ENOENT';
}

/**
 * Logs how an analysis falls short as it crosses the storage boundary — an unreadable shape, or an
 * invariant its collections break — tagged with `description` to name the record and the point it
 * was checked at, e.g. `project abc on save`. Logging is the whole response: the read or the write
 * proceeds either way, since a record that disagrees with itself still renders, and refusing it
 * would cost the user their work over a fault they cannot act on.
 */
function reportAnalysisViolations(analysis: unknown, description: string): void {
  // A stored record is typed but never validated, so its analysis may be absent or misshapen. Only
  // absence is legitimate: a stored null is corruption.
  if (analysis === undefined) return;
  if (!isTextAnalysis(analysis)) {
    logger.warn(`Interlinearizer: ${description} has a structurally invalid analysis`);
    return;
  }
  validateTextAnalysis(analysis).forEach(({ kind, layer, count, sample }) => {
    logger.warn(
      `Interlinearizer: ${description} has ${count} ${layer}-layer ${kind} violation(s): ${sample.join(', ')}`,
    );
  });
}

/**
 * Type guard for a JSON-parsed value that must be an array of strings — the shape of both the
 * `projectIds` index and the `pendingCleanup` set.
 */
function isStringArray(value: unknown): value is string[] {
  return Array.isArray(value) && value.every((id) => typeof id === 'string');
}

/**
 * Reads and JSON-parses the value stored at `key`, treating a never-written key as an empty array.
 * Returns the raw parsed value as `unknown` and does not validate that it is an array of strings.
 *
 * @throws {SyntaxError} If the stored value contains invalid JSON.
 * @throws If `papi.storage.readUserData` rejects for any non-ENOENT reason (e.g. permission denied,
 *   I/O error).
 */
async function readJsonArray(token: ExecutionToken, key: string): Promise<unknown> {
  try {
    return JSON.parse(await papi.storage.readUserData(token, key));
  } catch (e) {
    if (isNotFound(e)) return [];
    throw e;
  }
}

/**
 * Reads the stored list of project IDs. Unlike the pending-cleanup set, a corrupt index is never
 * silently reset to an empty array — that would drop every project's id at once and orphan all
 * their records — so a stored value that is not an array of strings throws a clear corruption error
 * rather than being coerced into subtle downstream failures (e.g. spreading a string into
 * characters in {@link createProject}, or calling `.filter` on a non-array in
 * {@link deleteProject}).
 *
 * @returns The stored project ID array, or an empty array if `projectIds` has never been written
 *   (ENOENT).
 * @throws {SyntaxError} If the `projectIds` storage value contains invalid JSON.
 * @throws {Error} If the parsed `projectIds` value is not an array of strings (a corrupt index).
 * @throws If `papi.storage.readUserData` rejects for any non-ENOENT reason (e.g. permission denied,
 *   I/O error).
 */
async function readIds(token: ExecutionToken): Promise<string[]> {
  const parsed = await readJsonArray(token, PROJECT_IDS_KEY);
  if (!isStringArray(parsed)) {
    throw new Error(
      `Interlinearizer: '${PROJECT_IDS_KEY}' index is corrupt (expected an array of strings)`,
    );
  }
  return parsed;
}

/**
 * Outcome of reading the pending-cleanup set, distinguishing a genuinely-empty (or well-formed) set
 * from a corrupt stored value. {@link sweepPendingCleanup} uses `corrupt` to decide whether it must
 * overwrite the stored value even when there are no ids to process, so a bad value is repaired
 * rather than re-read (and re-warned about) on every launch.
 */
interface PendingCleanupRead {
  /** The recovered pending-cleanup ids: the parsed array, or `[]` when the stored value was corrupt. */
  ids: string[];
  /** Whether the stored value was unparseable or not an array of strings. */
  corrupt: boolean;
}

/**
 * Reads the stored set of orphaned project IDs awaiting cleanup, tolerating corruption so a bad
 * value can never wedge {@link sweepPendingCleanup} (which runs fire-and-forget at activation, where
 * a thrown error would be invisible and would recur on every launch). A value that is missing
 * (ENOENT), unparseable, or not an array of strings is recovered as an empty set; when the value
 * was present but corrupt, `corrupt` is set so the caller can rewrite the key with a valid value,
 * self-healing it instead of re-reading (and re-warning about) the bad value on every launch.
 *
 * @throws If `papi.storage.readUserData` rejects for any non-ENOENT reason.
 */
async function readPendingCleanup(token: ExecutionToken): Promise<PendingCleanupRead> {
  let parsed: unknown;
  try {
    parsed = await readJsonArray(token, PENDING_CLEANUP_KEY);
  } catch (e) {
    if (e instanceof SyntaxError) {
      logger.warn('Interlinearizer: pending-cleanup set contains invalid JSON; resetting to empty');
      return { ids: [], corrupt: true };
    }
    throw e;
  }
  if (!isStringArray(parsed)) {
    logger.warn(
      'Interlinearizer: pending-cleanup set is not an array of strings; resetting to empty',
    );
    return { ids: [], corrupt: true };
  }
  return { ids: parsed, corrupt: false };
}

/**
 * Records `id` in the persistent `pendingCleanup` set so a later {@link sweepPendingCleanup} can
 * retry deleting its orphaned `project:{id}` record. Serialized with every other write to the set,
 * so concurrent updates cannot overwrite each other, and idempotent: an id already in the set is
 * not added twice.
 *
 * @throws If `papi.storage.readUserData` or `papi.storage.writeUserData` rejects for a non-ENOENT
 *   reason. A corrupt `pendingCleanup` value is not thrown; it is recovered as an empty set.
 */
function recordPendingCleanup(token: ExecutionToken, id: string): Promise<void> {
  return enqueuePendingCleanupOp(async () => {
    const { ids } = await readPendingCleanup(token);
    if (ids.includes(id)) return;
    await papi.storage.writeUserData(token, PENDING_CLEANUP_KEY, JSON.stringify([...ids, id]));
  });
}

/**
 * Retries deleting the orphaned project records recorded in the `pendingCleanup` set (see
 * {@link createProject}). For each recorded id:
 *
 * - If the id is still present in the `projectIds` index, it belongs to a live project — its record
 *   must not be deleted. The id is dropped from the set without touching its record; it should
 *   never have been recorded (or has since become live) and is not an orphan to clean.
 * - Otherwise the record is an orphan: its `project:{id}` deletion is attempted, treating ENOENT as
 *   success (already gone). On success the id is dropped from the set; on failure it is retained
 *   for the next attempt and logged.
 *
 * Consulting the index guards against destroying a live project's record if an id ever lands in the
 * set while still indexed (e.g. an index write that persists but then reports failure). Intended to
 * run opportunistically at activation.
 *
 * The whole read-delete-rewrite cycle is serialized with every other write to the set, so it cannot
 * interleave with a concurrent {@link recordPendingCleanup} and drop a newly recorded orphan. The
 * per-record deletions run concurrently within the cycle; the set is small and each targets a
 * distinct key.
 *
 * @returns A promise resolving to the number of orphaned records successfully deleted this pass
 *   (live ids dropped from the set without deleting their record are not counted).
 * @throws {SyntaxError} If the `projectIds` storage value contains invalid JSON.
 * @throws {Error} If the stored `projectIds` value is not an array of strings (a corrupt index).
 * @throws If reading the set or the index, or rewriting the set (`papi.storage.writeUserData`),
 *   rejects for a non-ENOENT reason. A per-record delete failure is not thrown; the id is retained
 *   instead.
 */
export function sweepPendingCleanup(token: ExecutionToken): Promise<number> {
  return enqueuePendingCleanupOp(async () => {
    const { ids, corrupt } = await readPendingCleanup(token);
    if (ids.length === 0) {
      // Nothing to sweep. If the stored value was corrupt, overwrite it with a valid empty set so
      // it self-heals; otherwise it would be re-read and re-warned about on every launch.
      if (corrupt) await papi.storage.writeUserData(token, PENDING_CLEANUP_KEY, JSON.stringify([]));
      return 0;
    }
    // Read the index directly rather than on the index queue: this snapshot is consulted only
    // to protect live projects from deletion, and both directions of a stale read are safe. A read
    // that misses a just-created project is harmless (a live project's id is never in the
    // pending-cleanup work set), and a read that still shows a since-deleted project only makes the
    // sweep conservatively skip a deletion. A stale snapshot can never make the sweep delete a
    // record it should keep, so serializing this read would add contention for no benefit.
    const indexed = new Set(await readIds(token));
    // For each id, decide whether to keep it in the set and whether its record was cleaned.
    const outcomes = await Promise.all(
      ids.map(async (id) => {
        if (indexed.has(id)) {
          // Live project: never delete its record. Drop it from the set as a non-orphan.
          logger.warn(`Interlinearizer: pending-cleanup id ${id} is a live project; not deleting`);
          return { keep: false, cleaned: false };
        }
        try {
          await papi.storage.deleteUserData(token, projectKey(id));
          return { keep: false, cleaned: true };
        } catch (e) {
          if (isNotFound(e)) return { keep: false, cleaned: true };
          logger.error(`Interlinearizer: cleanup of orphaned project ${id} failed again:`, e);
          return { keep: true, cleaned: false };
        }
      }),
    );
    const remaining = ids.filter((_id, i) => outcomes[i].keep);
    if (remaining.length !== ids.length) {
      await papi.storage.writeUserData(token, PENDING_CLEANUP_KEY, JSON.stringify(remaining));
    }
    return outcomes.filter((o) => o.cleaned).length;
  });
}

/**
 * Creates a new interlinearizer project with empty analysis data and writes it to extension
 * storage. Appends the project ID to the stored index. `createdAt` and `updatedAt` are set to the
 * same creation timestamp.
 *
 * @param token - The execution token for storage access.
 * @param sourceProjectId - The Platform.Bible project ID of the source text.
 * @param analysisLanguages - BCP 47 tags for languages used in glosses and annotations. Required
 *   and must contain at least one entry.
 * @param targetProjectId - Optional Platform.Bible project ID of the target text. When provided,
 *   the project is created as a bilateral alignment project and `links` is initialized to `[]`;
 *   when omitted the project is analysis-only and `links` is left undefined.
 * @param name - Optional user-facing name for the project.
 * @param description - Optional user-facing description for the project.
 * @throws {SyntaxError} If the `projectIds` storage value contains invalid JSON.
 * @throws {Error} If the stored `projectIds` value is not an array of strings (a corrupt index).
 * @throws If `papi.storage.readUserData` rejects for any non-ENOENT reason when reading the index.
 * @throws If the project or index `papi.storage.writeUserData` rejects. On an index-write failure
 *   the original error is rethrown after best-effort rollback; a failed rollback does not throw —
 *   the orphaned record is instead recorded for a later {@link sweepPendingCleanup} (and a failure
 *   to even record it is logged and swallowed).
 */
export async function createProject(
  token: ExecutionToken,
  sourceProjectId: string,
  analysisLanguages: string[],
  targetProjectId?: string,
  name?: string,
  description?: string,
): Promise<InterlinearProject> {
  const id = crypto.randomUUID();
  const now = new Date().toISOString();
  const project: InterlinearProject = {
    id,
    modelVersion: CURRENT_MODEL_VERSION,
    createdAt: now,
    updatedAt: now,
    ...(name !== undefined && { name }),
    ...(description !== undefined && { description }),
    sourceProjectId,
    ...(targetProjectId !== undefined && { targetProjectId }),
    analysisLanguages,
    analysis: emptyAnalysis(),
    ...(targetProjectId !== undefined && { links: [] }),
  };

  await persistNewProject(token, project);
  return project;
}

/**
 * Writes a newly built project record and appends its ID to the stored index, keeping the two in
 * step: on an index-write failure the record is rolled back (or, failing that, recorded for a later
 * {@link sweepPendingCleanup}) before the index error is rethrown, so no successful return leaves an
 * indexed-but-missing or written-but-unindexed project behind.
 */
async function persistNewProject(
  token: ExecutionToken,
  project: InterlinearProject,
): Promise<void> {
  const { id } = project;
  await papi.storage.writeUserData(token, projectKey(id), JSON.stringify(project));
  try {
    await enqueueIndexOp(async () => {
      const ids = await readIds(token);
      await papi.storage.writeUserData(token, PROJECT_IDS_KEY, JSON.stringify([...ids, id]));
    });
  } catch (indexError) {
    try {
      await papi.storage.deleteUserData(token, projectKey(id));
    } catch (rollbackError) {
      logger.error(`Failed to roll back project ${id} after index write failure:`, rollbackError);
      // The orphaned record was written but never indexed and could not be deleted. Record it so a
      // later sweep retries the deletion; a failure to even record it is logged and swallowed so it
      // never masks the original index error the caller needs to see.
      await recordPendingCleanup(token, id).catch((recordError) => {
        logger.error(`Failed to record orphaned project ${id} for cleanup:`, recordError);
      });
    }
    throw indexError;
  }
}

/**
 * Reads the single Paratext 9 import project for the given source project, or `undefined` when the
 * source has none. At most one project per source carries `pt9Import` (the import replaces it in
 * place rather than creating another), so the first match is the only match.
 *
 * @throws {SyntaxError} If a project's storage value contains invalid JSON.
 * @throws {Error} If a stored record was written by a newer build.
 * @throws If `papi.storage.readUserData` rejects for any non-ENOENT reason.
 */
export async function getPt9ImportForSource(
  token: ExecutionToken,
  sourceProjectId: string,
): Promise<InterlinearProject | undefined> {
  const projects = await getProjectsForSource(token, sourceProjectId);
  return projects.find((project) => project.pt9Import !== undefined);
}

/**
 * Persists the outcome of a Paratext 9 interlinear import: creates the source project's import
 * record, or replaces it wholesale when one exists. This is the only write path for
 * `pt9Import`-carrying projects - the public update functions reject them - and every field except
 * `id` and `createdAt` is rebuilt from the arguments on replace, so nothing from the previous
 * import survives a sync.
 *
 * @param token - The execution token for storage access.
 * @param sourceProjectId - The Platform.Bible project ID the interlinear data was imported from.
 * @param name - Fixed, already-localized project name the import stamps on every run.
 * @param description - Fixed, already-localized project description, stamped like `name`.
 * @param analysisLanguages - Resolved gloss-language tags from the conversion.
 * @param analysis - The converted analysis layer.
 * @param pt9Import - Provenance to store: per-file hashes and the import timestamp.
 * @throws {SyntaxError} If a read storage value contains invalid JSON.
 * @throws {Error} If a stored record was written by a newer build.
 * @throws If `papi.storage.readUserData` or `papi.storage.writeUserData` rejects for a non-ENOENT
 *   reason. On a create, an index-write failure rolls back the record as in {@link createProject}.
 */
export async function savePt9Import(
  token: ExecutionToken,
  sourceProjectId: string,
  name: string,
  description: string,
  analysisLanguages: string[],
  analysis: TextAnalysis,
  pt9Import: NonNullable<InterlinearProject['pt9Import']>,
): Promise<InterlinearProject> {
  const buildNew = (): InterlinearProject => {
    const now = new Date().toISOString();
    return {
      id: crypto.randomUUID(),
      modelVersion: CURRENT_MODEL_VERSION,
      createdAt: now,
      updatedAt: now,
      name,
      description,
      sourceProjectId,
      analysisLanguages,
      analysis,
      pt9Import,
    };
  };

  reportAnalysisViolations(analysis, `Paratext 9 import of ${sourceProjectId} on save`);

  const existing = await getPt9ImportForSource(token, sourceProjectId);
  if (existing) {
    const replaced = await enqueueProjectOp(existing.id, async () => {
      const current = await getProject(token, existing.id);
      if (!current) return undefined;
      const updated: InterlinearProject = {
        ...buildNew(),
        id: current.id,
        createdAt: current.createdAt,
      };
      await papi.storage.writeUserData(token, projectKey(current.id), JSON.stringify(updated));
      return updated;
    });
    if (replaced) return replaced;
    // The import was deleted between the lookup and the queued write; fall through and create.
  }

  const project = buildNew();
  await persistNewProject(token, project);
  return project;
}

/**
 * Creates an editable project from a Paratext 9 import: a new record with a fresh id and timestamps
 * carrying the import's analysis and analysis languages verbatim, the same source project, and no
 * `pt9Import` - so the copy is an ordinary editable project that never syncs. The import itself is
 * untouched.
 *
 * @param token - The execution token for storage access.
 * @param projectId - The Paratext 9 import to copy.
 * @param name - User-facing name for the copy, chosen in the copy dialog.
 * @param description - Optional user-facing description for the copy.
 * @throws {Error} If no project with the given ID exists.
 * @throws {Error} If the project is not a Paratext 9 import - only frozen imports need an editable
 *   copy; ordinary projects are already editable.
 * @throws {SyntaxError} If the project's storage value contains invalid JSON.
 * @throws If storage reads or writes reject for a non-ENOENT reason. On an index-write failure the
 *   new record rolls back as in {@link createProject}.
 */
export async function createEditableCopy(
  token: ExecutionToken,
  projectId: string,
  name: string,
  description?: string,
): Promise<InterlinearProject> {
  const source = await getProject(token, projectId);
  if (!source) throw new Error(`Project ${projectId} does not exist`);
  if (!source.pt9Import)
    throw new Error(`Project ${projectId} is not a Paratext 9 import; it is already editable`);

  const now = new Date().toISOString();
  const project: InterlinearProject = {
    id: crypto.randomUUID(),
    modelVersion: CURRENT_MODEL_VERSION,
    createdAt: now,
    updatedAt: now,
    name,
    ...(description !== undefined && { description }),
    sourceProjectId: source.sourceProjectId,
    analysisLanguages: source.analysisLanguages,
    analysis: source.analysis,
  };
  await persistNewProject(token, project);
  return project;
}

/**
 * A project as storage may actually hold it. The record type declares both times as required, which
 * a project written before it carried a modification time — or one damaged outside the extension —
 * does not satisfy; this optional view is what lets the gaps be found and filled.
 */
type StoredProject = Omit<InterlinearProject, 'createdAt' | 'updatedAt'> & {
  createdAt?: string;
  updatedAt?: string;
};

/**
 * Reads one persisted interlinearizer project, supplying the timestamps a record stored without
 * them carries no value for: a project with no modification time is dated by its creation time, the
 * closest bound storage still holds on when it was last written. A project with no creation time,
 * which only damage outside the extension produces, falls back to the read time and is logged,
 * since that date is invented rather than recovered.
 *
 * A record written by a newer build is refused outright, so it survives on disk in the shape that
 * build wrote.
 *
 * @returns The project record, or `undefined` if it does not exist in storage (ENOENT).
 * @throws {SyntaxError} If the project's storage value contains invalid JSON.
 * @throws {Error} If the stored record's `modelVersion` is higher than this build's.
 * @throws If `papi.storage.readUserData` rejects for any non-ENOENT reason.
 */
export async function getProject(
  token: ExecutionToken,
  id: string,
): Promise<InterlinearProject | undefined> {
  const raw = await readRecord(token, projectKey(id));
  return raw === undefined ? undefined : parseProject(raw, id);
}

/**
 * Parses project `id`'s stored record as {@link getProject} describes.
 *
 * @throws {SyntaxError} If `raw` is not valid JSON.
 * @throws {Error} If the stored record's `modelVersion` is higher than this build's.
 */
function parseProject(raw: string, id: string): InterlinearProject {
  const stored: StoredProject = JSON.parse(raw);
  assertSupportedModelVersion(stored, `project ${id}`);
  if (!stored.createdAt)
    logger.warn(
      `Interlinearizer: project ${id} was stored without a creation time; dating it by the read time`,
    );
  const createdAt = stored.createdAt ?? new Date().toISOString();
  reportAnalysisViolations(stored.analysis, `project ${id} on load`);
  return {
    ...stored,
    createdAt,
    updatedAt: stored.updatedAt ?? createdAt,
  };
}

/**
 * Returns all stored projects in creation order. Projects whose storage keys are missing (e.g.
 * after a failed delete) are silently omitted. Projects that fail to read or parse are logged and
 * skipped so a single corrupted record does not prevent access to the rest; a project written by a
 * newer build is one of those failures, and is omitted rather than reported.
 *
 * @throws {SyntaxError} If `projectIds` contains invalid JSON.
 * @throws {Error} If the stored `projectIds` value is not an array of strings (a corrupt index).
 * @throws If `papi.storage.readUserData` rejects for any non-ENOENT reason when reading the index.
 */
export async function listProjects(token: ExecutionToken): Promise<InterlinearProject[]> {
  const projects = await perfTimeAsyncExcluding(
    'listProjects:read',
    'listProjects:parse',
    async () => {
      const ids = await readIds(token);
      return Promise.all(
        ids.map(async (id) => {
          try {
            const raw = await readRecord(token, projectKey(id));
            return raw === undefined
              ? undefined
              : perfTime('listProjects:parse', () => parseProject(raw, id));
          } catch (e) {
            logger.error(`Interlinearizer: failed to read project ${id}:`, e);
            return undefined;
          }
        }),
      );
    },
  );
  return projects.filter((p): p is InterlinearProject => p !== undefined);
}

/**
 * Returns all interlinearizer projects whose `sourceProjectId` matches the given value, in creation
 * order.
 *
 * @throws {SyntaxError} If `projectIds` or any project's storage value contains invalid JSON.
 * @throws {Error} If the stored `projectIds` value is not an array of strings (a corrupt index).
 * @throws If `papi.storage.readUserData` rejects for any non-ENOENT reason.
 */
export async function getProjectsForSource(
  token: ExecutionToken,
  sourceProjectId: string,
): Promise<InterlinearProject[]> {
  const all = await listProjects(token);
  return all.filter((p) => p.sourceProjectId === sourceProjectId);
}

/**
 * Replaces the analysis of an existing interlinearizer project, and optionally its custom segment
 * boundaries, in one atomic write. Refreshes `updatedAt` to the current time.
 *
 * @param token - The execution token for storage access.
 * @param id - The interlinearizer project UUID to update.
 * @param analysis - The new `TextAnalysis` to persist.
 * @param segmentation - The new boundary delta to persist (`SegmentationDelta`), `null` to clear
 *   any stored boundaries, or `undefined` to leave the project's existing boundaries unchanged.
 * @returns The updated project record, or `undefined` if no project with the given ID exists.
 * @throws {SyntaxError} If the project's storage value contains invalid JSON.
 * @throws {Error} If the stored record was written by a newer build; nothing is written.
 * @throws {Error} If the project is a Paratext 9 import (`pt9Import` present); imports are
 *   read-only and only {@link savePt9Import} replaces their content.
 * @throws If `papi.storage.readUserData` or `papi.storage.writeUserData` rejects for a non-ENOENT
 *   reason.
 */
export async function updateAnalysis(
  token: ExecutionToken,
  id: string,
  analysis: TextAnalysis,
  segmentation?: SegmentationDelta | null,
): Promise<InterlinearProject | undefined> {
  return enqueueProjectOp(id, async () => {
    const raw = await perfTimeAsync('updateAnalysis:read', () => readRecord(token, projectKey(id)));
    if (raw === undefined) return undefined;
    const project = perfTime('updateAnalysis:parse', () => parseProject(raw, id));
    if (project.pt9Import) throw pt9ImportReadOnlyError(id);
    perfTime('updateAnalysis:parse', () =>
      reportAnalysisViolations(analysis, `project ${id} on save`),
    );
    const updated: InterlinearProject = {
      ...project,
      modelVersion: CURRENT_MODEL_VERSION,
      analysis,
      updatedAt: new Date().toISOString(),
    };
    // eslint-disable-next-line no-null/no-null -- null is the explicit "clear stored boundaries" sentinel
    if (segmentation === null) delete updated.segmentation;
    else if (segmentation !== undefined) updated.segmentation = segmentation;
    await perfTimeAsync('updateAnalysis:write', () =>
      papi.storage.writeUserData(token, projectKey(id), JSON.stringify(updated)),
    );
    return updated;
  });
}

/**
 * Updates the metadata of an existing interlinearizer project. Refreshes `updatedAt` to the current
 * time.
 *
 * @param token - The execution token for storage access.
 * @param id - The interlinearizer project UUID to update.
 * @param name - New user-facing name, or `undefined` to clear it.
 * @param description - New user-facing description, or `undefined` to clear it.
 * @param analysisLanguages - New BCP 47 analysis language tags. Required and must be non-empty;
 *   pass the current value to leave the field unchanged (it cannot be cleared).
 * @param targetProjectId - New target-project ID. `undefined` removes the target binding (the
 *   project becomes analysis-only); a string overwrites the existing value.
 * @returns The updated project record, or `undefined` if no project with the given ID exists.
 * @throws {SyntaxError} If the project's storage value contains invalid JSON.
 * @throws {Error} If the stored record was written by a newer build; nothing is written.
 * @throws {Error} If the project is a Paratext 9 import (`pt9Import` present); imports are
 *   read-only, their name and description included - the import stamps fixed values.
 * @throws If `papi.storage.readUserData` or `papi.storage.writeUserData` rejects for a non-ENOENT
 *   reason.
 */
export async function updateProjectMetadata(
  token: ExecutionToken,
  id: string,
  name: string | undefined,
  description: string | undefined,
  analysisLanguages: string[],
  targetProjectId?: string,
): Promise<InterlinearProject | undefined> {
  return enqueueProjectOp(id, async () => {
    const project = await getProject(token, id);
    if (!project) return undefined;
    if (project.pt9Import) throw pt9ImportReadOnlyError(id);
    const updated: InterlinearProject = {
      ...project,
      modelVersion: CURRENT_MODEL_VERSION,
      updatedAt: new Date().toISOString(),
    };
    if (name === undefined) {
      delete updated.name;
    } else {
      updated.name = name;
    }
    if (description === undefined) {
      delete updated.description;
    } else {
      updated.description = description;
    }
    updated.analysisLanguages = analysisLanguages;
    if (targetProjectId === undefined) {
      delete updated.targetProjectId;
    } else {
      updated.targetProjectId = targetProjectId;
    }
    await papi.storage.writeUserData(token, projectKey(id), JSON.stringify(updated));
    return updated;
  });
}

/**
 * Deletes the project with the given ID from storage and removes it from the index. No-ops silently
 * if the project does not exist.
 *
 * @throws {SyntaxError} If the `projectIds` storage value contains invalid JSON.
 * @throws {Error} If the stored `projectIds` value is not an array of strings (a corrupt index).
 * @throws If `papi.storage.readUserData` rejects for any non-ENOENT reason when reading the index.
 * @throws If `papi.storage.deleteUserData` throws for a reason other than ENOENT.
 * @throws If `papi.storage.writeUserData` rejects when updating `PROJECT_IDS_KEY`.
 */
export async function deleteProject(token: ExecutionToken, id: string): Promise<void> {
  await enqueueProjectOp(id, async () => {
    try {
      await papi.storage.deleteUserData(token, projectKey(id));
    } catch (e) {
      if (!isNotFound(e)) throw e;
    }
    await enqueueIndexOp(async () => {
      const ids = await readIds(token);
      const updated = ids.filter((i) => i !== id);
      await papi.storage.writeUserData(token, PROJECT_IDS_KEY, JSON.stringify(updated));
    });
  });
}

/**
 * Whether a draft is stored for the source project. Unlike {@link getDraft}, never synthesizes an
 * empty draft, so a caller can tell a never-opened source from an opened-but-unedited one.
 */
export async function hasDraft(token: ExecutionToken, sourceProjectId: string): Promise<boolean> {
  return enqueueSerialized(draftQueues, sourceProjectId, async () => {
    try {
      await papi.storage.readUserData(token, draftKey(sourceProjectId));
      return true;
    } catch (e) {
      if (isNotFound(e)) return false;
      throw e;
    }
  });
}

/**
 * Reads the draft working buffer for a source project, returning a fresh empty draft when none has
 * been written yet (ENOENT), when the stored draft fails validation, or when it belongs to a
 * different source project — the invalid draft is logged and silently discarded. Drafts are never
 * added to the `projectIds` index, so they stay out of {@link listProjects} and
 * {@link getProjectsForSource} and never appear in the project picker.
 *
 * A draft written by a newer build is refused rather than discarded, leaving it intact for the
 * build that can read it; {@link saveDraft} refuses to overwrite that same record.
 *
 * A read concurrent with an auto-save for the same source returns one or the other whole, never a
 * mixture of the two.
 *
 * A book whose shard is missing or unusable loads as empty, and {@link saveDraft} then leaves that
 * shard and its manifest entry alone rather than treating the book as wiped, until a save carries
 * analyses for that book again.
 *
 * A save interrupted before its envelope landed leaves shards the stored manifest does not name. A
 * book first analyzed in that save still reopens with its work rather than empty.
 *
 * @throws {SyntaxError} If the draft's storage value contains invalid JSON.
 * @throws {Error} If the stored draft's `modelVersion` is higher than this build's.
 * @throws If `papi.storage.readUserData` rejects for any non-ENOENT reason.
 */
export async function getDraft(
  token: ExecutionToken,
  sourceProjectId: string,
): Promise<DraftProject> {
  return enqueueSerialized(draftQueues, sourceProjectId, async () => {
    const raw = await perfTimeAsync('getDraft:read', () =>
      readRecord(token, draftKey(sourceProjectId)),
    );
    if (raw === undefined) return emptyDraft(sourceProjectId);
    const parsed: unknown = perfTime('getDraft:parse', () => JSON.parse(raw));
    // Refuse a newer build's draft before validating it: a later shape need not satisfy this
    // build's guard, and failing validation is what resets the draft to empty.
    assertSupportedModelVersion(parsed, `draft for source project ${sourceProjectId}`);
    if (!isDraftProject(parsed) || parsed.sourceProjectId !== sourceProjectId) {
      logger.warn('Interlinearizer: stored draft failed validation; resetting to empty draft');
      return emptyDraft(sourceProjectId);
    }
    const { analysisBooks, ...draft } = withoutShardManifest(parsed);
    const describeDraft = `draft for source project ${sourceProjectId} on load`;
    // A draft with no manifest carries its analysis inline, with no shards to read.
    if (!analysisBooks) {
      perfTime('getDraft:parse', () => reportAnalysisViolations(draft.analysis, describeDraft));
      return draft;
    }
    const keyOf = (bookCode: string) => draftAnalysisKey(sourceProjectId, bookCode);
    // A save interrupted before its envelope landed leaves shards this manifest never came to
    // name. A journaled book whose shard never landed reads as missing and drops back out below.
    const { booksToRead, orphaned, shards } = await perfTimeAsyncExcluding(
      'getDraft:read',
      'getDraft:parse',
      async () => {
        const { adding } = await readShardJournal(token, sourceProjectId);
        const orphanedBooks = adding.filter((bookCode) => !analysisBooks.includes(bookCode));
        const books = [...analysisBooks, ...orphanedBooks];
        return {
          booksToRead: books,
          orphaned: orphanedBooks,
          shards: await Promise.all(
            books.map(async (bookCode) => {
              const shardRaw = await readRecord(token, keyOf(bookCode));
              return perfTime('getDraft:parse', () =>
                parseAnalysisShard(shardRaw, keyOf(bookCode)),
              );
            }),
          ),
        };
      },
    );
    // Record what each shard holds so the next save can tell which books actually changed. An
    // unusable shard's empty stand-in is not what is on disk, so it is recorded apart. A journaled
    // book is dropped only when its shard is gone: dropping one still in storage would strand it,
    // with neither the manifest nor the journal left to name it.
    const loadedByBook = booksToRead
      .map((bookCode, i) => ({ bookCode, ...shards[i] }))
      .filter(({ bookCode, state }) => state !== 'absent' || !orphaned.includes(bookCode));
    perfTime('getDraft:compare', () =>
      shardContentsBySource.set(
        sourceProjectId,
        new Map(
          loadedByBook
            .filter(({ state }) => state === 'loaded')
            .map(({ bookCode, analysis }) => [bookCode, JSON.stringify(analysis)]),
        ),
      ),
    );
    unreadableShardsBySource.set(
      sourceProjectId,
      new Set(
        loadedByBook.filter(({ state }) => state !== 'loaded').map(({ bookCode }) => bookCode),
      ),
    );
    return perfTime('getDraft:parse', () => {
      // Checked once merged: a link and its payload can sit in different shards, so a violation
      // is only real of the whole.
      const analysis = mergeAnalyses(shards.map((shard) => shard.analysis));
      reportAnalysisViolations(analysis, describeDraft);
      return { ...draft, analysis };
    });
  });
}

/**
 * Guards an otherwise blind draft write against clobbering a record this build cannot read. The
 * draft in hand is not evidence about what is on disk: a caller that could not read the stored
 * draft holds an empty one stamped with this revision, and writing that would land on the very
 * record the refused read protected.
 *
 * A draft that is absent or unparseable carries no stamp to refuse, so the write proceeds and
 * replaces it. A read that fails for any other reason cannot rule out the very record this guard
 * protects: a refused write costs a retry, where an overwritten record is gone for good.
 *
 * @returns The book codes the stored draft's manifest names, empty when there is no readable
 *   manifest to name them.
 * @throws {Error} If the stored draft's `modelVersion` is higher than this build's.
 * @throws If `papi.storage.readUserData` rejects for any non-ENOENT reason.
 */
async function assertStoredDraftIsWritable(
  token: ExecutionToken,
  sourceProjectId: string,
): Promise<string[]> {
  let raw: string;
  try {
    raw = await papi.storage.readUserData(token, draftKey(sourceProjectId));
  } catch (e) {
    if (isNotFound(e)) return [];
    throw e;
  }
  let stored: unknown;
  try {
    stored = JSON.parse(raw);
  } catch {
    return [];
  }
  assertSupportedModelVersion(stored, `draft for source project ${sourceProjectId}`);
  if (!isDraftProject(stored)) return [];
  const { analysisBooks } = withoutShardManifest(stored);
  return analysisBooks ?? [];
}

/**
 * Writes the draft working buffer for a source project, replacing any existing draft. Writes are
 * serialized per source project, so a WebView's rapid auto-saves cannot persist out of order. The
 * caller owns the whole envelope — including the `dirty` flag — apart from the
 * {@link CURRENT_MODEL_VERSION} stamp, so nothing of the stored record survives the write. A draft
 * written by a newer build is the exception: it is left as it stands rather than overwritten.
 *
 * The analysis spans several records and no storage transaction spans them, so an interrupted save
 * can leave books from two saves. It never leaves a book listed whose shard is gone. What did reach
 * storage is tallied as it lands, so the save that follows a failed one rewrites only the books
 * still missing it.
 *
 * Recovery does not depend on this process staying up: a shard the envelope never came to name is
 * still found on reopen, and a deletion that fails is retried by a later save even across a
 * restart. A book dropped from the analysis leaves no shard behind whether or not this process
 * loaded the draft.
 *
 * A save that fails leaves no write of its own in flight, so the next one never overlaps it.
 *
 * @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.writeUserData` rejects.
 * @throws If deleting a wiped book's shard rejects for any non-ENOENT reason; the shard stays
 *   journaled for a later save to retry.
 */
export async function saveDraft(
  token: ExecutionToken,
  sourceProjectId: string,
  draft: DraftProject,
): Promise<void> {
  // Invariant violations go unreported here: this runs on every edit, so one would log per keystroke.
  await enqueueSerialized(draftQueues, sourceProjectId, async () => {
    const storedBooks = await perfTimeAsync('saveDraft:read', () =>
      assertStoredDraftIsWritable(token, sourceProjectId),
    );
    const byBook = perfTime('saveDraft:compare', () => splitAnalysisByBook(draft.analysis));
    const written = getOrCreateEntry(shardContentsBySource, sourceProjectId, () => new Map());
    const unreadable = getOrCreateEntry(unreadableShardsBySource, sourceProjectId, () => new Set());

    // Books this save no longer carries, less those held back because the load could not read them.
    // A save whose draft was never loaded here has only the stored manifest or the journal to name
    // earlier shards. A journaled addition whose shard never landed deletes as a no-op.
    const journaled = await perfTimeAsync('saveDraft:read', () =>
      readShardJournal(token, sourceProjectId),
    );
    const knownShards = new Set([
      ...written.keys(),
      ...storedBooks,
      ...journaled.adding,
      ...journaled.removing,
    ]);
    const wiped = [...knownShards].filter(
      (bookCode) => !byBook.has(bookCode) && !unreadable.has(bookCode),
    );
    const held = [...unreadable].filter((bookCode) => !byBook.has(bookCode));

    // Name every shard this save could strand before writing any of it. A book the stored manifest
    // already names needs no entry: it survives an interruption by that manifest alone.
    const stranded = [...byBook.keys()].filter((bookCode) => !storedBooks.includes(bookCode));
    await perfTimeAsync('saveDraft:write', () =>
      writeShardJournal(token, sourceProjectId, { adding: stranded, removing: wiped }),
    );

    const shards = perfTime('saveDraft:compare', () =>
      [...byBook].map(([bookCode, partition]) => {
        const json = JSON.stringify(partition);
        return { bookCode, json, changed: written.get(bookCode) !== json };
      }),
    );
    await perfTimeAsync('saveDraft:write', () =>
      settleAll(
        shards.map(async ({ bookCode, json, changed }) => {
          if (changed) {
            await papi.storage.writeUserData(
              token,
              draftAnalysisKey(sourceProjectId, bookCode),
              json,
            );
          }
          written.set(bookCode, json);
          // This save rewrote the book, so a later wipe must be free to delete the shard it
          // restored.
          unreadable.delete(bookCode);
        }),
      ),
    );

    const envelope: StoredDraft = {
      ...draft,
      modelVersion: CURRENT_MODEL_VERSION,
      analysis: emptyAnalysis(),
      analysisBooks: [...byBook.keys(), ...held],
    };
    await perfTimeAsync('saveDraft:write', () =>
      papi.storage.writeUserData(token, draftKey(sourceProjectId), JSON.stringify(envelope)),
    );

    // A wiped book would otherwise leave its shard orphaned. Deleting only once the envelope has
    // stopped naming the book keeps a failure here from stranding the manifest on a missing shard.
    const undeleted: string[] = [];
    const deletions = await perfTimeAsync('saveDraft:write', () =>
      Promise.allSettled(
        wiped.map(async (bookCode) => {
          try {
            await papi.storage.deleteUserData(token, draftAnalysisKey(sourceProjectId, bookCode));
          } catch (e) {
            if (!isNotFound(e)) {
              // Kept in the journal so a later save retries the deletion even across a restart.
              undeleted.push(bookCode);
              throw e;
            }
          }
          // Dropped only once the shard is gone, so a later save in this process retries a failed
          // deletion.
          written.delete(bookCode);
        }),
      ),
    );

    // With the envelope naming every shard this save added, only a failed deletion is still owed.
    // A failure to record that yields to the shard error, which is the one worth surfacing; the
    // next save retries the journal either way.
    const failed = deletions.find((outcome) => outcome.status === 'rejected');
    try {
      await perfTimeAsync('saveDraft:write', () =>
        writeShardJournal(token, sourceProjectId, { adding: [], removing: undeleted }),
      );
    } catch (e) {
      if (!failed) throw e;
      logger.warn(`Interlinearizer: could not update the shard journal for ${sourceProjectId}:`, e);
    }

    if (failed?.status === 'rejected') throw failed.reason;
  });
}

/**
 * Resets module-level queue state between tests. Jest's `resetMocks` resets mock implementations
 * but does not re-execute modules, so the serialization queues would otherwise persist across tests
 * and allow promise chains from one test to bleed into the next.
 */
export function resetQueuesForTesting(): void {
  indexQueue = Promise.resolve();
  pendingCleanupQueue = Promise.resolve();
  projectQueues.clear();
  draftQueues.clear();
  shardContentsBySource.clear();
  unreadableShardsBySource.clear();
}