@wrongstack/tools 0.306.0 → 0.306.3

package/dist/codebase-index/worker.js

@@ -2704,6 +2704,7 @@ import { parentPort } from "node:worker_threads";
 // src/codebase-index/indexer.ts
 import { expectDefined as expectDefined5 } from "@wrongstack/core/utils";
 import { execFile } from "node:child_process";
+import { createHash } from "node:crypto";
 import * as fs9 from "node:fs/promises";
 import { availableParallelism } from "node:os";
 import * as path12 from "node:path";
@@ -4100,6 +4101,85 @@ function runSqliteWithRetry(fn) {
   throw lastError;
 }
 
+// src/codebase-index/vector-search.ts
+var RRF_K = 60;
+var VECTOR_DIMENSIONS = 384;
+var NGRAM_SIZE = 3;
+function embedText(text) {
+  const vec = new Float32Array(VECTOR_DIMENSIONS);
+  const normalized = text.toLowerCase().trim();
+  if (normalized.length < NGRAM_SIZE) {
+    const padded = ` ${normalized} `.slice(0, Math.max(NGRAM_SIZE, normalized.length + 2));
+    for (let i = 0; i <= padded.length - NGRAM_SIZE; i++) {
+      const ngram = padded.slice(i, i + NGRAM_SIZE);
+      const bucket = hashNgram(ngram) % VECTOR_DIMENSIONS;
+      vec[bucket] += 1;
+    }
+  } else {
+    for (let i = 0; i <= normalized.length - NGRAM_SIZE; i++) {
+      const ngram = normalized.slice(i, i + NGRAM_SIZE);
+      const bucket = hashNgram(ngram) % VECTOR_DIMENSIONS;
+      vec[bucket] += 1;
+    }
+  }
+  let norm = 0;
+  for (let i = 0; i < VECTOR_DIMENSIONS; i++) {
+    norm += vec[i] * vec[i];
+  }
+  norm = Math.sqrt(norm);
+  if (norm > 0) {
+    for (let i = 0; i < VECTOR_DIMENSIONS; i++) {
+      vec[i] /= norm;
+    }
+  }
+  return vec;
+}
+function hashNgram(str) {
+  let hash = 2166136261;
+  for (let i = 0; i < str.length; i++) {
+    hash ^= str.charCodeAt(i);
+    hash = Math.imul(hash, 16777619);
+  }
+  return hash >>> 0;
+}
+function cosineSimilarity(a, b) {
+  let dot = 0;
+  const len = Math.min(a.length, b.length);
+  for (let i = 0; i < len; i++) {
+    dot += a[i] * b[i];
+  }
+  return dot;
+}
+function encodeVector(vec) {
+  return Buffer.from(vec.buffer, vec.byteOffset, vec.byteLength);
+}
+function decodeVector(buf) {
+  const view = new DataView(
+    buf.buffer,
+    buf.byteOffset,
+    buf.byteLength
+  );
+  const copy = new Float32Array(buf.byteLength / 4);
+  for (let i = 0; i < copy.length; i++) {
+    copy[i] = view.getFloat32(i * 4, true);
+  }
+  return copy;
+}
+function reciprocalRankFusion(bm25Ranks, vectorRanks, k = RRF_K) {
+  const allIds = /* @__PURE__ */ new Set([...bm25Ranks.keys(), ...vectorRanks.keys()]);
+  const scored = [];
+  for (const id of allIds) {
+    const bm25Rank = bm25Ranks.get(id);
+    const vecRank = vectorRanks.get(id);
+    let score = 0;
+    if (bm25Rank !== void 0) score += 1 / (k + bm25Rank);
+    if (vecRank !== void 0) score += 1 / (k + vecRank);
+    scored.push([id, score]);
+  }
+  scored.sort((a, b) => b[1] - a[1]);
+  return scored;
+}
+
 // src/codebase-index/writer-admin.ts
 import * as fs7 from "node:fs";
 import * as path10 from "node:path";
@@ -5155,90 +5235,19 @@ var StorePool = class {
   }
 };
 
-// src/codebase-index/vector-search.ts
-var RRF_K = 60;
-var VECTOR_DIMENSIONS = 384;
-var NGRAM_SIZE = 3;
-function embedText(text) {
-  const vec = new Float32Array(VECTOR_DIMENSIONS);
-  const normalized = text.toLowerCase().trim();
-  if (normalized.length < NGRAM_SIZE) {
-    const padded = ` ${normalized} `.slice(0, Math.max(NGRAM_SIZE, normalized.length + 2));
-    for (let i = 0; i <= padded.length - NGRAM_SIZE; i++) {
-      const ngram = padded.slice(i, i + NGRAM_SIZE);
-      const bucket = hashNgram(ngram) % VECTOR_DIMENSIONS;
-      vec[bucket] += 1;
-    }
-  } else {
-    for (let i = 0; i <= normalized.length - NGRAM_SIZE; i++) {
-      const ngram = normalized.slice(i, i + NGRAM_SIZE);
-      const bucket = hashNgram(ngram) % VECTOR_DIMENSIONS;
-      vec[bucket] += 1;
-    }
-  }
-  let norm = 0;
-  for (let i = 0; i < VECTOR_DIMENSIONS; i++) {
-    norm += vec[i] * vec[i];
-  }
-  norm = Math.sqrt(norm);
-  if (norm > 0) {
-    for (let i = 0; i < VECTOR_DIMENSIONS; i++) {
-      vec[i] /= norm;
-    }
-  }
-  return vec;
-}
-function hashNgram(str) {
-  let hash = 2166136261;
-  for (let i = 0; i < str.length; i++) {
-    hash ^= str.charCodeAt(i);
-    hash = Math.imul(hash, 16777619);
-  }
-  return hash >>> 0;
-}
-function cosineSimilarity(a, b) {
-  let dot = 0;
-  const len = Math.min(a.length, b.length);
-  for (let i = 0; i < len; i++) {
-    dot += a[i] * b[i];
-  }
-  return dot;
-}
-function encodeVector(vec) {
-  return Buffer.from(vec.buffer, vec.byteOffset, vec.byteLength);
-}
-function decodeVector(buf) {
-  const view = new DataView(
-    buf.buffer,
-    buf.byteOffset,
-    buf.byteLength
-  );
-  const copy = new Float32Array(buf.byteLength / 4);
-  for (let i = 0; i < copy.length; i++) {
-    copy[i] = view.getFloat32(i * 4, true);
-  }
-  return copy;
-}
-function reciprocalRankFusion(bm25Ranks, vectorRanks, k = RRF_K) {
-  const allIds = /* @__PURE__ */ new Set([...bm25Ranks.keys(), ...vectorRanks.keys()]);
-  const scored = [];
-  for (const id of allIds) {
-    const bm25Rank = bm25Ranks.get(id);
-    const vecRank = vectorRanks.get(id);
-    let score = 0;
-    if (bm25Rank !== void 0) score += 1 / (k + bm25Rank);
-    if (vecRank !== void 0) score += 1 / (k + vecRank);
-    scored.push([id, score]);
-  }
-  scored.sort((a, b) => b[1] - a[1]);
-  return scored;
-}
-
 // src/codebase-index/writer.ts
 var DB_FILE2 = "index.db";
 var MAX_STATEMENT_CACHE = 128;
 var IndexStore = class _IndexStore {
   db;
+  /**
+   * True while an index run owns one outer SQLite transaction. Individual
+   * writer methods normally protect themselves with BEGIN/COMMIT, but during
+   * a refresh they join this transaction so readers observe either the last
+   * completed index or the next completed index, never an in-between batch.
+   */
+  atomicIndexUpdateActive = false;
+  writeSavepointSequence = 0;
   /** Absolute path to this project's index directory. */
   indexDir;
   /**
@@ -5319,6 +5328,51 @@ var IndexStore = class _IndexStore {
   runWithRetry(fn) {
     return runSqliteWithRetry(fn);
   }
+  /** Run a complete index mutation as one WAL-visible publication. */
+  async runAtomicIndexUpdate(job) {
+    if (this.atomicIndexUpdateActive) return job();
+    this.runWithRetry(() => this.db.exec("BEGIN IMMEDIATE"));
+    this.atomicIndexUpdateActive = true;
+    try {
+      const result = await job();
+      this.db.exec("COMMIT");
+      return result;
+    } catch (error) {
+      try {
+        this.db.exec("ROLLBACK");
+      } catch {
+      }
+      throw error;
+    } finally {
+      this.atomicIndexUpdateActive = false;
+    }
+  }
+  /**
+   * Begin a method-local transaction. Inside an atomic index publication a
+   * SAVEPOINT preserves the old per-batch rollback boundary, which is needed
+   * when commitBatch falls back to per-file writes after one batch fails.
+   */
+  beginWriteTransaction() {
+    if (this.atomicIndexUpdateActive) {
+      const savepoint = `index_write_${++this.writeSavepointSequence}`;
+      this.db.exec(`SAVEPOINT ${savepoint}`);
+      return savepoint;
+    }
+    this.db.exec("BEGIN IMMEDIATE");
+    return null;
+  }
+  commitWriteTransaction(savepoint) {
+    if (savepoint) this.db.exec(`RELEASE SAVEPOINT ${savepoint}`);
+    else this.db.exec("COMMIT");
+  }
+  rollbackWriteTransaction(savepoint) {
+    if (savepoint) {
+      this.db.exec(`ROLLBACK TO SAVEPOINT ${savepoint}`);
+      this.db.exec(`RELEASE SAVEPOINT ${savepoint}`);
+    } else {
+      this.db.exec("ROLLBACK");
+    }
+  }
   /**
    * Mirror the in-process language→family map into SQLite.
    *
@@ -5553,7 +5607,7 @@ var IndexStore = class _IndexStore {
   insertSymbols(symbols) {
     this.invalidateBm25();
     return this.runWithRetry(() => {
-      this.db.exec("BEGIN IMMEDIATE");
+      const ownsTransaction = this.beginWriteTransaction();
       try {
         let nextId = this.allocateSymbolIds(symbols.length);
         const result = [];
@@ -5580,7 +5634,9 @@ var IndexStore = class _IndexStore {
           }
           vectorRows.push({
             id,
-            vector: encodeVector(embedText(s.text || buildIndexableText(s.name, s.signature, s.docComment)))
+            vector: encodeVector(
+              embedText(s.text || buildIndexableText(s.name, s.signature, s.docComment))
+            )
           });
           result.push({ ...s, id });
         }
@@ -5598,10 +5654,10 @@ var IndexStore = class _IndexStore {
             vectorRows
           );
         }
-        this.db.exec("COMMIT");
+        this.commitWriteTransaction(ownsTransaction);
         return result;
       } catch (err) {
-        this.db.exec("ROLLBACK");
+        this.rollbackWriteTransaction(ownsTransaction);
         throw err;
       }
     });
@@ -5609,7 +5665,7 @@ var IndexStore = class _IndexStore {
   deleteSymbolsForFile(file) {
     this.invalidateBm25();
     this.runWithRetry(() => {
-      this.db.exec("BEGIN IMMEDIATE");
+      const ownsTransaction = this.beginWriteTransaction();
       try {
         const affectedNames = this.invalidateIncomingRefsForFiles([file]);
         if (this.ftsAvailable) {
@@ -5624,9 +5680,9 @@ var IndexStore = class _IndexStore {
         }
         this.stmt("DELETE FROM symbols WHERE file_fk = ?").run(file);
         this.resolveRefsForNamesUnsafe(affectedNames);
-        this.db.exec("COMMIT");
+        this.commitWriteTransaction(ownsTransaction);
       } catch (error) {
-        this.db.exec("ROLLBACK");
+        this.rollbackWriteTransaction(ownsTransaction);
         throw error;
       }
     });
@@ -5639,7 +5695,7 @@ var IndexStore = class _IndexStore {
   deleteFile(file) {
     this.invalidateBm25();
     this.runWithRetry(() => {
-      this.db.exec("BEGIN IMMEDIATE");
+      const ownsTransaction = this.beginWriteTransaction();
       try {
         const affectedNames = this.invalidateIncomingRefsForFiles([file]);
         if (this.ftsAvailable) {
@@ -5658,9 +5714,9 @@ var IndexStore = class _IndexStore {
         this.stmt("DELETE FROM symbols WHERE file_fk = ?").run(file);
         this.stmt("DELETE FROM files WHERE file = ?").run(file);
         this.resolveRefsForNamesUnsafe(affectedNames);
-        this.db.exec("COMMIT");
+        this.commitWriteTransaction(ownsTransaction);
       } catch (err) {
-        this.db.exec("ROLLBACK");
+        this.rollbackWriteTransaction(ownsTransaction);
         throw err;
       }
     });
@@ -6047,7 +6103,7 @@ var IndexStore = class _IndexStore {
   clearAll() {
     this.invalidateBm25();
     this.runWithRetry(() => {
-      this.db.exec("BEGIN IMMEDIATE");
+      const ownsTransaction = this.beginWriteTransaction();
       try {
         this.db.exec("DROP TABLE IF EXISTS refs");
         this.db.exec("DROP TABLE IF EXISTS symbols");
@@ -6055,15 +6111,15 @@ var IndexStore = class _IndexStore {
         this.db.exec("DROP TABLE IF EXISTS metadata");
         if (this.ftsAvailable) this.db.exec("DROP TABLE IF EXISTS symbols_fts");
         this.db.exec("DROP TABLE IF EXISTS symbol_vectors");
-        this.db.exec("COMMIT");
         this.stmtCache.clear();
         this.initSchema();
         this.stmt("INSERT OR REPLACE INTO metadata(key, value) VALUES (?, ?)").run(
           _IndexStore.NEXT_SYMBOL_ID_KEY,
           "1"
         );
+        this.commitWriteTransaction(ownsTransaction);
       } catch (err) {
-        this.db.exec("ROLLBACK");
+        this.rollbackWriteTransaction(ownsTransaction);
         throw err;
       }
     });
@@ -6125,7 +6181,7 @@ var IndexStore = class _IndexStore {
     }
     this.invalidateBm25();
     return this.runWithRetry(() => {
-      this.db.exec("BEGIN IMMEDIATE");
+      const ownsTransaction = this.beginWriteTransaction();
       try {
         const affectedNames = /* @__PURE__ */ new Set();
         for (const entry of entries) {
@@ -6186,7 +6242,9 @@ var IndexStore = class _IndexStore {
             }
             vectorRows.push({
               id,
-              vector: encodeVector(embedText(s.text || buildIndexableText(s.name, s.signature, s.docComment)))
+              vector: encodeVector(
+                embedText(s.text || buildIndexableText(s.name, s.signature, s.docComment))
+              )
             });
             const inserted = { ...s, id };
             allInserted.push(inserted);
@@ -6231,10 +6289,10 @@ var IndexStore = class _IndexStore {
           );
         }
         this.resolveRefsForNamesUnsafe(affectedNames);
-        this.db.exec("COMMIT");
+        this.commitWriteTransaction(ownsTransaction);
         return allInserted;
       } catch (err) {
-        this.db.exec("ROLLBACK");
+        this.rollbackWriteTransaction(ownsTransaction);
         throw err;
       }
     });
@@ -6311,7 +6369,7 @@ var IndexStore = class _IndexStore {
   replaceEmptyFile(meta) {
     this.invalidateBm25();
     this.runWithRetry(() => {
-      this.db.exec("BEGIN IMMEDIATE");
+      const ownsTransaction = this.beginWriteTransaction();
       try {
         const affectedNames = this.invalidateIncomingRefsForFiles([meta.file]);
         if (this.ftsAvailable) {
@@ -6346,9 +6404,9 @@ var IndexStore = class _IndexStore {
           meta.lastIndexed
         );
         this.resolveRefsForNamesUnsafe(affectedNames);
-        this.db.exec("COMMIT");
+        this.commitWriteTransaction(ownsTransaction);
       } catch (err) {
-        this.db.exec("ROLLBACK");
+        this.rollbackWriteTransaction(ownsTransaction);
         throw err;
       }
     });
@@ -6541,6 +6599,10 @@ var DEFAULT_IGNORE_FILES = /* @__PURE__ */ new Set(["package-lock.json", "pnpm-l
 var INDEXABLE_EXTENSION_SET = new Set(INDEXABLE_EXTENSIONS);
 var MAX_INDEX_FILE_BYTES = 5 * 1024 * 1024;
 var MAX_GIT_FILE_LIST_BYTES = 64 * 1024 * 1024;
+var GIT_SNAPSHOT_METADATA_KEY = "git_discovery_snapshot";
+var IndexSourceChangedError = class extends Error {
+  name = "IndexSourceChangedError";
+};
 function isWithinProject(projectRoot, file) {
   const rel = path12.relative(projectRoot, file);
   return rel !== "" && !rel.startsWith(`..${path12.sep}`) && rel !== ".." && !path12.isAbsolute(rel);
@@ -6577,7 +6639,7 @@ async function findGitSourceFiles(projectRoot, ignore, signal) {
     if (normalizeComparablePath(topLevel) !== normalizeComparablePath(projectRoot)) return null;
     throwIfAborted(signal);
     const ignoreSet = /* @__PURE__ */ new Set([...DEFAULT_IGNORE, ...ignore]);
-    const [output, statusOutput] = await Promise.all([
+    const [output, statusOutput, stagedOutput] = await Promise.all([
       gitOutput(projectRoot, ["ls-files", "--cached", "--others", "--exclude-standard", "-z"]),
       gitOutput(projectRoot, [
         "status",
@@ -6585,7 +6647,8 @@ async function findGitSourceFiles(projectRoot, ignore, signal) {
         "-z",
         "--untracked-files=all",
         "--ignored=no"
-      ])
+      ]),
+      gitOutput(projectRoot, ["ls-files", "--stage", "-z"])
     ]);
     throwIfAborted(signal);
     const dirty = /* @__PURE__ */ new Set();
@@ -6615,9 +6678,17 @@ async function findGitSourceFiles(projectRoot, ignore, signal) {
       const ext = path12.extname(relative2).toLowerCase();
       if (INDEXABLE_EXTENSION_SET.has(ext) || detectLang(full) !== null) files.push(full);
     }
+    const snapshot = createHash("sha256").update(stagedOutput).update("\0").update(statusOutput);
+    const indexedFiles = new Set(files);
+    for (const dirtyFile of [...dirty].sort()) {
+      if (!indexedFiles.has(dirtyFile) || deleted.has(dirtyFile)) continue;
+      snapshot.update("\0").update(dirtyFile).update("\0");
+      snapshot.update(xxhash64String(await fs9.readFile(dirtyFile, "utf8")));
+    }
     return {
       files,
-      trustedUnchanged: new Set(files.filter((file) => !dirty.has(file)))
+      trustedUnchanged: new Set(files.filter((file) => !dirty.has(file))),
+      snapshotKey: snapshot.digest("hex")
     };
   } catch {
     return null;
@@ -6630,7 +6701,8 @@ async function findSourceFiles(projectRoot, ignore, isGitIgnored, signal) {
       files: gitFiles.files,
       complete: true,
       errors: [],
-      trustedUnchanged: gitFiles.trustedUnchanged
+      trustedUnchanged: gitFiles.trustedUnchanged,
+      snapshotKey: gitFiles.snapshotKey
     };
   }
   const results = [];
@@ -6717,6 +6789,17 @@ async function resolveProjectRelations(store, projectRoot, opts) {
   }
 }
 async function runIndexerWithStore(store, opts) {
+  let result;
+  try {
+    result = await store.runAtomicIndexUpdate(() => runIndexerAtomic(store, opts));
+  } catch (error) {
+    if (!(error instanceof IndexSourceChangedError)) throw error;
+    result = await store.runAtomicIndexUpdate(() => runIndexerAtomic(store, opts));
+  }
+  if (!opts.files) store.compactIfNeeded();
+  return result;
+}
+async function runIndexerAtomic(store, opts) {
   const { projectRoot, langs, ignore = [], signal } = opts;
   const relationGraphVersion = "2";
   const refResolutionVersion = "2";
@@ -6736,6 +6819,7 @@ async function runIndexerWithStore(store, opts) {
   let discoveredFiles = null;
   let discoveryComplete = true;
   let trustedUnchanged;
+  let discoverySnapshotKey;
   if (opts.files && opts.files.length > 0) {
     files = opts.files.map((f) => path12.resolve(projectRoot, f)).filter((f) => {
       if (!isWithinProject(projectRoot, f)) return false;
@@ -6749,6 +6833,7 @@ async function runIndexerWithStore(store, opts) {
     discoveryComplete = discovery.complete;
     discoveredFiles = new Set(files);
     trustedUnchanged = discovery.trustedUnchanged;
+    discoverySnapshotKey = discovery.snapshotKey;
   }
   if (langs && langs.length > 0) {
     const langSet = new Set(langs);
@@ -6762,6 +6847,8 @@ async function runIndexerWithStore(store, opts) {
   if (!force) {
     for (const meta of store.getAllFileMetas()) existingMeta.set(meta.file, meta);
   }
+  const snapshotTrusted = !force && discoverySnapshotKey !== void 0 && store.getMetadata(GIT_SNAPSHOT_METADATA_KEY) === discoverySnapshotKey;
+  if (!snapshotTrusted) trustedUnchanged = void 0;
   const totalFilesForProgress = files.length;
   let filesPreSkipped = 0;
   if (!force && trustedUnchanged) {
@@ -6824,9 +6911,6 @@ async function runIndexerWithStore(store, opts) {
             };
           }
           const meta = existingMeta.get(file);
-          if (!force && meta && meta.mtimeMs === Math.floor(stat2.mtimeMs)) {
-            return { file, stat: stat2, lang, parsed: null, skippedMeta: meta };
-          }
           let content;
           try {
             content = await fs9.readFile(file, { encoding: "utf8", signal });
@@ -7055,9 +7139,18 @@ async function runIndexerWithStore(store, opts) {
   });
   store.setMetadata("ref_resolution_version", refResolutionVersion);
   store.setMetadata("relation_graph_version", relationGraphVersion);
+  const completeProjectScope = !opts.files && (!langs || langs.length === 0) && (!opts.ignore || opts.ignore.length === 0);
+  if (completeProjectScope && discoverySnapshotKey !== void 0) {
+    const finalSnapshot = await findGitSourceFiles(projectRoot, ignore, signal);
+    if (!finalSnapshot || finalSnapshot.snapshotKey !== discoverySnapshotKey) {
+      throw new IndexSourceChangedError(
+        "Project files changed during indexing; retrying before publishing the generation."
+      );
+    }
+    store.setMetadata(GIT_SNAPSHOT_METADATA_KEY, errors.length === 0 ? discoverySnapshotKey : "");
+  }
   if (!opts.files || filesIndexed >= 50) store.optimize();
   store.setLastIndexed(Date.now());
-  if (!opts.files) store.compactIfNeeded();
   const durationMs = Date.now() - startMs;
   return {
     filesIndexed,
@@ -7168,20 +7261,30 @@ function outgoingCallsService(args) {
 if (!parentPort) throw new Error("codebase-index worker must be started as a worker thread");
 var port = parentPort;
 var inFlight = /* @__PURE__ */ new Map();
+var activeIndexes = 0;
 function post(msg) {
   port.postMessage(msg);
 }
 async function dispatch2(msg) {
+  if (msg.op !== "index" && activeIndexes > 0) {
+    const error = new Error(
+      "Codebase index refresh in progress; retry after the completed generation is published."
+    );
+    error.name = "IndexRefreshInProgressError";
+    throw error;
+  }
   switch (msg.op) {
     case "index": {
       const ac = new AbortController();
       inFlight.set(msg.id, ac);
+      activeIndexes++;
       try {
         return await indexService(msg.args, {
           signal: ac.signal,
           onProgress: (current, total) => post({ type: "progress", id: msg.id, current, total })
         });
       } finally {
+        activeIndexes--;
         inFlight.delete(msg.id);
       }
     }

package/dist/codebase-index/writer.d.ts

@@ -5,6 +5,14 @@ export { codebaseIndexDirOverride, resolveIndexDir } from './writer-helpers.js';
 export { StorePool } from './writer-store-pool.js';
 export declare class IndexStore {
     private db;
+    /**
+     * True while an index run owns one outer SQLite transaction. Individual
+     * writer methods normally protect themselves with BEGIN/COMMIT, but during
+     * a refresh they join this transaction so readers observe either the last
+     * completed index or the next completed index, never an in-between batch.
+     */
+    private atomicIndexUpdateActive;
+    private writeSavepointSequence;
     /** Absolute path to this project's index directory. */
     private readonly indexDir;
     /**
@@ -62,6 +70,16 @@ export declare class IndexStore {
         indexDir?: string | undefined;
     });
     runWithRetry<T>(fn: () => T): T;
+    /** Run a complete index mutation as one WAL-visible publication. */
+    runAtomicIndexUpdate<T>(job: () => Promise<T>): Promise<T>;
+    /**
+     * Begin a method-local transaction. Inside an atomic index publication a
+     * SAVEPOINT preserves the old per-batch rollback boundary, which is needed
+     * when commitBatch falls back to per-file writes after one batch fails.
+     */
+    private beginWriteTransaction;
+    private commitWriteTransaction;
+    private rollbackWriteTransaction;
     /**
      * Mirror the in-process language→family map into SQLite.
      *