@equationalapplications/core-llm-wiki 7.12.0 → 7.13.1

package/dist/index.js

@@ -75,6 +75,8 @@ var SQLITE_RESULT_CODE_NAMES = {
   // prefix and we normalize it back to the symbolic name so callers can branch on
   // the same string the rest of the ecosystem uses.
   2067: "SQLITE_CONSTRAINT_UNIQUE",
+  // 267 = SQLITE_CORRUPT_VTAB — a corrupt FTS5 shadow table (ftsCorruptionClass).
+  267: "SQLITE_CORRUPT_VTAB",
   100: "SQLITE_ROW",
   101: "SQLITE_DONE"
 };
@@ -935,6 +937,143 @@ async function createTemporalIndexesIfColumnsExist(db, prefix) {
   }
 }
 
+// src/services/search/fts5Sql.ts
+var FTS5_STATE_KEY = "fts5_index_state";
+var FTS5_DRAIN_CHUNK = 500;
+var FTS5_SWEEP_CHUNK = 500;
+var FTS5_RETIRED_TABLES_KEY = "fts5_retired_tables";
+var FTS5_RETIRED_COUNTER_KEY = "fts5_retired_counter";
+var FTS5_RECLAIM_MERGE_PAGES = 500;
+function retiredTableName(p, n) {
+  return `${p}entries_fts_retired_${n}`;
+}
+function isRetiredTableName(p, name) {
+  return typeof name === "string" && name.startsWith(`${p}entries_fts_retired_`) && /^\d+$/.test(name.slice(`${p}entries_fts_retired_`.length));
+}
+var FTS5_REBUILD_WM_KEY = "fts5_rebuild_wm";
+var FTS5_REBUILD_SNAPSHOT_KEY = "fts5_rebuild_snapshot";
+var FTS5_SWEEP_CURSOR_KEY = "fts5_orphan_sweep_cursor";
+function fts5TriggerNames(prefix) {
+  return [`${prefix}entries_fts_ai`, `${prefix}entries_fts_au`, `${prefix}entries_fts_ad`];
+}
+function tagsExpr(col) {
+  return `CASE WHEN json_valid(${col}) THEN
+      CASE WHEN json_type(${col}) = 'array' THEN
+        (SELECT group_concat(CASE type WHEN 'true' THEN 'true' WHEN 'false' THEN 'false'
+                                       WHEN 'null' THEN '' ELSE value END, ' ')
+           FROM json_each(${col}))
+      ELSE ${col} END
+    ELSE ${col} END`;
+}
+function fts5TablesDdl(p) {
+  return `
+CREATE VIRTUAL TABLE IF NOT EXISTS ${p}entries_fts USING fts5(
+  id UNINDEXED, entity_id UNINDEXED, title, body, tags,
+  tokenize = 'porter unicode61'
+);
+CREATE TABLE IF NOT EXISTS ${p}fts_map (
+  fts_rowid INTEGER PRIMARY KEY,
+  id TEXT NOT NULL UNIQUE,
+  entity_id TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS ${p}fts_map_entity ON ${p}fts_map(entity_id);
+CREATE TABLE IF NOT EXISTS ${p}fts_pending (
+  seq INTEGER PRIMARY KEY,
+  entity_id TEXT NOT NULL,
+  id TEXT NOT NULL
+);`;
+}
+function fts5TriggersDdl(p) {
+  const [ai, au, ad] = fts5TriggerNames(p);
+  return `
+CREATE TRIGGER IF NOT EXISTS ${ai} AFTER INSERT ON ${p}entries BEGIN
+  INSERT INTO ${p}fts_pending (entity_id, id) VALUES (NEW.entity_id, NEW.id);
+END;
+CREATE TRIGGER IF NOT EXISTS ${au}
+AFTER UPDATE OF id, entity_id, title, body, tags, deleted_at ON ${p}entries BEGIN
+  INSERT INTO ${p}fts_pending (entity_id, id) VALUES (OLD.entity_id, OLD.id);
+  INSERT INTO ${p}fts_pending (entity_id, id)
+    SELECT NEW.entity_id, NEW.id WHERE NEW.id <> OLD.id OR NEW.entity_id <> OLD.entity_id;
+END;
+CREATE TRIGGER IF NOT EXISTS ${ad} AFTER DELETE ON ${p}entries BEGIN
+  INSERT INTO ${p}fts_pending (entity_id, id) VALUES (OLD.entity_id, OLD.id);
+END;`;
+}
+function drainHiSql(p) {
+  return `SELECT max(seq) AS hi FROM (SELECT seq FROM ${p}fts_pending ORDER BY seq LIMIT ${FTS5_DRAIN_CHUNK})`;
+}
+function ledgerChunkSql(p, chunkIds, ledgerWhere) {
+  return [
+    `DELETE FROM ${p}entries_fts WHERE rowid IN (SELECT m.fts_rowid FROM ${p}fts_map m WHERE m.id IN (${chunkIds}))`,
+    `DELETE FROM ${p}fts_map WHERE id IN (${chunkIds})`,
+    `INSERT INTO ${p}fts_map (id, entity_id)
+       SELECT e.id, e.entity_id FROM ${p}entries e WHERE e.id IN (${chunkIds}) AND e.deleted_at IS NULL`,
+    `INSERT INTO ${p}entries_fts (rowid, id, entity_id, title, body, tags)
+       SELECT m.fts_rowid, e.id, e.entity_id, e.title, e.body, ${tagsExpr("e.tags")}
+       FROM ${p}fts_map m JOIN ${p}entries e ON e.id = m.id
+       WHERE m.id IN (${chunkIds})`,
+    `DELETE FROM ${p}fts_pending WHERE ${ledgerWhere}`
+  ];
+}
+function drainChunkSql(p) {
+  return ledgerChunkSql(p, `SELECT id FROM ${p}fts_pending WHERE seq <= ?`, "seq <= ?");
+}
+function fts5PendingIndexesDdl(p) {
+  return `
+CREATE INDEX IF NOT EXISTS ${p}fts_pending_id ON ${p}fts_pending(id);
+CREATE INDEX IF NOT EXISTS ${p}fts_pending_entity ON ${p}fts_pending(entity_id);`;
+}
+function idDrainChunkSql(p) {
+  return ledgerChunkSql(
+    p,
+    `SELECT id FROM ${p}fts_pending WHERE id IN (SELECT value FROM json_each(?))`,
+    "id IN (SELECT value FROM json_each(?))"
+  );
+}
+function idReindexChunkSql(p) {
+  return ledgerChunkSql(p, "SELECT value FROM json_each(?)", "id IN (SELECT value FROM json_each(?))");
+}
+function entityDrainHiSql(p) {
+  return `SELECT max(seq) AS hi FROM (SELECT seq FROM ${p}fts_pending WHERE entity_id = ? ORDER BY seq LIMIT ${FTS5_DRAIN_CHUNK})`;
+}
+function entityDrainChunkSql(p) {
+  return ledgerChunkSql(p, `SELECT id FROM ${p}fts_pending WHERE entity_id = ? AND seq <= ?`, "entity_id = ? AND seq <= ?");
+}
+function fts5LedgerDropSql(p) {
+  return [
+    ...fts5TriggerNames(p).map((n) => `DROP TRIGGER IF EXISTS ${n};`),
+    `DROP TABLE IF EXISTS ${p}fts_pending;`,
+    `DROP TABLE IF EXISTS ${p}fts_map;`
+  ].join("\n");
+}
+function windowHiSql(p) {
+  return `SELECT max(rowid) AS hi FROM (SELECT rowid FROM ${p}entries WHERE rowid > ? AND rowid <= ? ORDER BY rowid LIMIT ${FTS5_DRAIN_CHUNK})`;
+}
+function windowChunkSql(p) {
+  const chunkIds = `SELECT id FROM ${p}entries WHERE rowid > ? AND rowid <= ?`;
+  return [
+    `DELETE FROM ${p}entries_fts WHERE rowid IN (SELECT m.fts_rowid FROM ${p}fts_map m WHERE m.id IN (${chunkIds}))`,
+    `DELETE FROM ${p}fts_map WHERE id IN (${chunkIds})`,
+    `INSERT INTO ${p}fts_map (id, entity_id)
+       SELECT e.id, e.entity_id FROM ${p}entries e WHERE e.rowid > ? AND e.rowid <= ? AND e.deleted_at IS NULL`,
+    `INSERT INTO ${p}entries_fts (rowid, id, entity_id, title, body, tags)
+       SELECT m.fts_rowid, e.id, e.entity_id, e.title, e.body, ${tagsExpr("e.tags")}
+       FROM ${p}entries e JOIN ${p}fts_map m ON m.id = e.id
+       WHERE e.rowid > ? AND e.rowid <= ?`
+  ];
+}
+function sweepHiSql(p) {
+  return `SELECT max(fts_rowid) AS hi FROM (SELECT fts_rowid FROM ${p}fts_map WHERE fts_rowid > ? AND fts_rowid <= ? ORDER BY fts_rowid LIMIT ${FTS5_SWEEP_CHUNK})`;
+}
+function sweepChunkSql(p) {
+  const orphans = `SELECT m.fts_rowid FROM ${p}fts_map m
+     WHERE m.fts_rowid > ? AND m.fts_rowid <= ? AND NOT EXISTS (SELECT 1 FROM ${p}entries e WHERE e.id = m.id)`;
+  return [
+    `DELETE FROM ${p}entries_fts WHERE rowid IN (${orphans})`,
+    `DELETE FROM ${p}fts_map WHERE fts_rowid IN (${orphans})`
+  ];
+}
+
 // src/db/migrations.ts
 var MIGRATIONS = [
   {
@@ -1215,6 +1354,17 @@ var MIGRATIONS = [
     run: async (db, prefix) => {
       await createLegacySourceTypeIndex(db, prefix);
     }
+  },
+  {
+    version: 15,
+    description: "fts_pending(id) and fts_pending(entity_id) indexes for the ids-first and entity-targeted drains",
+    run: async (db, prefix) => {
+      const row = await db.getFirstAsync(
+        `SELECT count(*) AS n FROM sqlite_master WHERE type = 'table' AND name = ?`,
+        [`${prefix}fts_pending`]
+      );
+      if (row?.n) await db.execAsync(fts5PendingIndexesDdl(prefix));
+    }
   }
 ];
 async function createLegacySourceTypeIndex(db, prefix) {
@@ -1400,6 +1550,44 @@ var BaseRepository = class {
   }
 };
 
+// src/services/search/fts5Progress.ts
+async function writeRebuildStart(tx, prefix, meta) {
+  const e = await tx.getFirstAsync(`SELECT coalesce(max(rowid), 0) AS hi FROM ${prefix}entries`);
+  const m = await tx.getFirstAsync(`SELECT coalesce(max(fts_rowid), 0) AS hi FROM ${prefix}fts_map`);
+  await meta.setMeta(FTS5_REBUILD_WM_KEY, JSON.stringify({ rowid: 0, id: null }), tx);
+  await meta.setMeta(FTS5_REBUILD_SNAPSHOT_KEY, JSON.stringify({ entries: e?.hi ?? 0, map: m?.hi ?? 0 }), tx);
+  await meta.setMeta(FTS5_SWEEP_CURSOR_KEY, "0", tx);
+}
+async function readRebuildProgress(meta, tx) {
+  const wm = parseJsonObject(await meta.getMeta(FTS5_REBUILD_WM_KEY, tx));
+  const snap = parseJsonObject(await meta.getMeta(FTS5_REBUILD_SNAPSHOT_KEY, tx));
+  const rawCursor = await meta.getMeta(FTS5_SWEEP_CURSOR_KEY, tx);
+  const cursor = rawCursor === null ? Number.NaN : Number(rawCursor);
+  if (typeof wm?.rowid !== "number" || !(typeof wm.id === "string" || wm.id === null)) return null;
+  if (typeof snap?.entries !== "number" || typeof snap.map !== "number" || !Number.isFinite(cursor)) return null;
+  return { wm: { rowid: wm.rowid, id: wm.id }, snapshot: { entries: snap.entries, map: snap.map }, cursor };
+}
+async function reanchorRebuildFingerprint(tx, prefix, deletedIds) {
+  if (deletedIds.length === 0) return;
+  const metaValue = async (key) => (await tx.getFirstAsync(`SELECT value FROM ${prefix}meta WHERE key = ?`, [key]))?.value ?? null;
+  if (await metaValue(FTS5_STATE_KEY) !== "rebuilding") return;
+  const wm = parseJsonObject(await metaValue(FTS5_REBUILD_WM_KEY));
+  if (typeof wm?.rowid !== "number" || typeof wm.id !== "string" || !deletedIds.includes(wm.id)) return;
+  if ((await tx.getFirstAsync(`SELECT id FROM ${prefix}entries WHERE rowid = ?`, [wm.rowid]))?.id === wm.id) return;
+  const below = await tx.getFirstAsync(
+    `SELECT rowid, id FROM ${prefix}entries WHERE rowid < ? ORDER BY rowid DESC LIMIT 1`,
+    [wm.rowid]
+  );
+  const next = below ? { rowid: below.rowid, id: below.id } : { rowid: 0, id: null };
+  await tx.runAsync(`UPDATE ${prefix}meta SET value = ? WHERE key = ?`, [JSON.stringify(next), FTS5_REBUILD_WM_KEY]);
+}
+async function restartRebuildAfterVacuum(db, prefix, meta) {
+  await db.withTransactionAsync(async (tx) => {
+    if (await meta.getMeta(FTS5_STATE_KEY, tx) !== "rebuilding") return;
+    await writeRebuildStart(tx, prefix, meta);
+  });
+}
+
 // src/utils/temporal.ts
 function liveAtSql(mode, alias = "") {
   const from = mode === "asOf" ? `COALESCE(${alias}valid_from, ${alias}created_at) <= ?` : `(${alias}valid_from IS NULL OR ${alias}valid_from <= ?)`;
@@ -2047,6 +2235,7 @@ var _EntryRepository = class _EntryRepository extends BaseRepository {
         }
       }
     }
+    if (totalChanges > 0) await reanchorRebuildFingerprint(executor, this.prefix, ids);
     return totalChanges;
   }
   /**
@@ -4153,7 +4342,7 @@ var UnavailableIndexStrategy = class {
   hasIndexedEntity(_entityId) {
     return false;
   }
-  async drain() {
+  async drain(_opts) {
   }
 };
 
@@ -4199,24 +4388,31 @@ var _SearchService = class _SearchService {
   isKeywordAvailable() {
     return !(this.indexStrategy instanceof UnavailableIndexStrategy);
   }
+  /** True when the installed strategy drains a durable ledger (FTS5, or the degraded stand-in). */
+  hasLedger() {
+    return this.indexStrategy.drain !== void 0;
+  }
   /**
    * One serialized drain turn for strategies with a durable ledger. Like
    * sync(), it never rejects: the keyword index is rebuildable, and a failed
-   * drain leaves the ledger rows in place for the next turn.
+   * drain leaves the ledger rows in place for the next turn. Resolves false
+   * when the drain failed.
    */
-  drainTurn(entityId) {
+  drainTurn(entityId, opts) {
     const work = this.syncChain.then(async () => {
       try {
         try {
-          await this.indexStrategy.drain();
+          await this.indexStrategy.drain(opts);
         } finally {
           this.evictCache(entityId);
         }
+        return true;
       } catch (err) {
         console.warn(`[WikiMemory] search index drain failed for ${entityId ?? "*"}:`, err);
+        return false;
       }
     });
-    this.syncChain = work;
+    this.syncChain = work.then(() => void 0);
     return work;
   }
   /**
@@ -4226,9 +4422,18 @@ var _SearchService = class _SearchService {
    * Rebuilds are serialized per instance and never reject: the keyword index
    * is a rebuildable cache over SQLite, so degraded keyword search is the
    * correct failure mode and killing the host process is not.
-   */
-  async sync(entityId) {
-    if (this.indexStrategy.drain) return this.drainTurn(entityId);
+   *
+   * With a ledger strategy, `sync()` runs one full quantum bounded by
+   * `opts.deadline`; `sync(entityId)` is a write turn (ledger only).
+   * `opts.ids` are the caller's touched ids: a ledger strategy drains them
+   * first, to completion; MiniSearch ignores them and rebuilds the entity in
+   * one scan.
+   */
+  async sync(entityId, opts) {
+    if (this.indexStrategy.drain) {
+      await this.drainTurn(entityId, entityId === void 0 ? { mode: "full", deadline: opts?.deadline, ids: opts?.ids } : { mode: "ledger", entityId, ids: opts?.ids });
+      return;
+    }
     const work = this.syncChain.then(async () => {
       try {
         try {
@@ -4269,13 +4474,17 @@ var _SearchService = class _SearchService {
    * — including on an empty `ids` list, which is a no-op only for an entity
    * the index already tracks, and even then one that waits for rebuilds
    * already queued on the chain.
+   *
+   * Resolves false only when a ledger drain failed: the caller's ids were not
+   * applied (their ledger rows remain), so a caller holding them retries.
    */
   async syncEntries(entityId, ids) {
-    if (this.indexStrategy.drain) return this.drainTurn(entityId);
+    if (this.indexStrategy.drain) return this.drainTurn(entityId, { mode: "ledger", entityId, ids: [...new Set(ids)] });
     const uniqueIds = [...new Set(ids)];
     const indexed = this.indexStrategy.hasIndexedEntity?.(entityId);
     if (uniqueIds.length === 0 && !this.staleEntities.has(entityId) && indexed === true) {
-      return this.syncChain;
+      await this.syncChain;
+      return true;
     }
     const work = this.syncChain.then(async () => {
       try {
@@ -4304,7 +4513,8 @@ var _SearchService = class _SearchService {
       }
     });
     this.syncChain = work;
-    return work;
+    await work;
+    return true;
   }
   /**
    * Forces the entity's next syncEntries to rebuild it in full. For writes core
@@ -4320,11 +4530,13 @@ var _SearchService = class _SearchService {
    * so only those entities are rebuilt. Each rebuild still takes its own turn
    * on the sync chain, and like syncEntries this never rejects. With nothing
    * stale it resolves at once, without waiting on work already on the chain.
+   * Resolves false only when a ledger drain failed (see syncEntries).
    */
-  async syncStale() {
-    if (this.indexStrategy.drain) return this.drainTurn();
+  async syncStale(opts) {
+    if (this.indexStrategy.drain) return this.drainTurn(void 0, { mode: "full", ids: opts?.ids });
     const ids = [...this.staleEntities];
     await Promise.all(ids.map((id) => this.syncEntries(id, [])));
+    return true;
   }
   /**
    * Clears the parsed vector cache. Useful for mid-loop flush guarantees
@@ -4665,87 +4877,11 @@ function assertOwnedBy(entityId, documents) {
   }
 }
 
-// src/services/search/fts5Sql.ts
-var FTS5_STATE_KEY = "fts5_index_state";
-var FTS5_DRAIN_CHUNK = 500;
-function fts5TriggerNames(prefix) {
-  return [`${prefix}entries_fts_ai`, `${prefix}entries_fts_au`, `${prefix}entries_fts_ad`];
-}
-function tagsExpr(col) {
-  return `CASE WHEN json_valid(${col}) THEN
-      CASE WHEN json_type(${col}) = 'array' THEN
-        (SELECT group_concat(CASE type WHEN 'true' THEN 'true' WHEN 'false' THEN 'false'
-                                       WHEN 'null' THEN '' ELSE value END, ' ')
-           FROM json_each(${col}))
-      ELSE ${col} END
-    ELSE ${col} END`;
-}
-function fts5TablesDdl(p) {
-  return `
-CREATE VIRTUAL TABLE IF NOT EXISTS ${p}entries_fts USING fts5(
-  id UNINDEXED, entity_id UNINDEXED, title, body, tags,
-  tokenize = 'porter unicode61'
-);
-CREATE TABLE IF NOT EXISTS ${p}fts_map (
-  fts_rowid INTEGER PRIMARY KEY,
-  id TEXT NOT NULL UNIQUE,
-  entity_id TEXT NOT NULL
-);
-CREATE INDEX IF NOT EXISTS ${p}fts_map_entity ON ${p}fts_map(entity_id);
-CREATE TABLE IF NOT EXISTS ${p}fts_pending (
-  seq INTEGER PRIMARY KEY,
-  entity_id TEXT NOT NULL,
-  id TEXT NOT NULL
-);`;
-}
-function fts5TriggersDdl(p) {
-  const [ai, au, ad] = fts5TriggerNames(p);
-  return `
-CREATE TRIGGER IF NOT EXISTS ${ai} AFTER INSERT ON ${p}entries BEGIN
-  INSERT INTO ${p}fts_pending (entity_id, id) VALUES (NEW.entity_id, NEW.id);
-END;
-CREATE TRIGGER IF NOT EXISTS ${au}
-AFTER UPDATE OF id, entity_id, title, body, tags, deleted_at ON ${p}entries BEGIN
-  INSERT INTO ${p}fts_pending (entity_id, id) VALUES (OLD.entity_id, OLD.id);
-  INSERT INTO ${p}fts_pending (entity_id, id)
-    SELECT NEW.entity_id, NEW.id WHERE NEW.id <> OLD.id OR NEW.entity_id <> OLD.entity_id;
-END;
-CREATE TRIGGER IF NOT EXISTS ${ad} AFTER DELETE ON ${p}entries BEGIN
-  INSERT INTO ${p}fts_pending (entity_id, id) VALUES (OLD.entity_id, OLD.id);
-END;`;
-}
-function drainHiSql(p) {
-  return `SELECT max(seq) AS hi FROM (SELECT seq FROM ${p}fts_pending ORDER BY seq LIMIT ${FTS5_DRAIN_CHUNK})`;
-}
-function drainChunkSql(p) {
-  const chunkIds = `SELECT id FROM ${p}fts_pending WHERE seq <= ?`;
-  return [
-    `DELETE FROM ${p}entries_fts WHERE rowid IN (SELECT m.fts_rowid FROM ${p}fts_map m WHERE m.id IN (${chunkIds}))`,
-    `DELETE FROM ${p}fts_map WHERE id IN (${chunkIds})`,
-    `INSERT INTO ${p}fts_map (id, entity_id)
-       SELECT e.id, e.entity_id FROM ${p}entries e WHERE e.id IN (${chunkIds}) AND e.deleted_at IS NULL`,
-    `INSERT INTO ${p}entries_fts (rowid, id, entity_id, title, body, tags)
-       SELECT m.fts_rowid, e.id, e.entity_id, e.title, e.body, ${tagsExpr("e.tags")}
-       FROM ${p}fts_map m JOIN ${p}entries e ON e.id = m.id
-       WHERE m.id IN (${chunkIds})`,
-    `DELETE FROM ${p}fts_pending WHERE seq <= ?`
-  ];
-}
-function rebuildSql(p) {
-  return [
-    `INSERT INTO ${p}fts_map (id, entity_id) SELECT id, entity_id FROM ${p}entries WHERE deleted_at IS NULL`,
-    `INSERT INTO ${p}entries_fts (rowid, id, entity_id, title, body, tags)
-       SELECT m.fts_rowid, e.id, e.entity_id, e.title, e.body, ${tagsExpr("e.tags")}
-       FROM ${p}fts_map m JOIN ${p}entries e ON e.id = m.id`
-  ];
-}
-function fts5LedgerDropSql(p) {
-  return [
-    ...fts5TriggerNames(p).map((n) => `DROP TRIGGER IF EXISTS ${n};`),
-    `DROP TABLE IF EXISTS ${p}fts_pending;`,
-    `DROP TABLE IF EXISTS ${p}fts_map;`
-  ].join("\n");
-}
+// src/utils/monotonicNow.ts
+var monotonicNow = () => typeof performance !== "undefined" && typeof performance.now === "function" ? performance.now() : Date.now();
+
+// src/utils/setupDefaults.ts
+var DEFAULT_SETUP_BUDGET_MS = 1500;
 
 // src/services/search/ftsQuery.ts
 var TOKEN = /[\p{L}\p{N}]+/gu;
@@ -4758,41 +4894,363 @@ function buildFtsMatchQuery(query) {
 
 // src/services/search/Fts5IndexStrategy.ts
 var Fts5IndexStrategy = class {
-  constructor(db, prefix, metadataRepo) {
+  constructor(db, prefix, metadataRepo, budgetMs = DEFAULT_SETUP_BUDGET_MS) {
     this.db = db;
     this.prefix = prefix;
     this.metadataRepo = metadataRepo;
+    this.budgetMs = budgetMs;
   }
-  async init() {
+  /**
+   * Resolves the index state (spec #280 Change 3 transition table). Every
+   * read-only probe runs before the one transition transaction, so a probe
+   * failure leaves zero mutation (Change 4 ordering).
+   */
+  async init(opts = {}) {
+    try {
+      await this.initOnce(opts);
+    } catch (err) {
+      const wrapped = unwrapFtsOnly(err);
+      const cls = ftsCorruptionClass(wrapped.cause);
+      if (cls === "vtab" || cls === "corrupt" && wrapped.ftsOnly) {
+        await this.resetAndRearm();
+        return;
+      }
+      throw wrapped.cause;
+    }
+  }
+  /** Marks errors from statements that touch only FTS tables (entries_fts + shadows). */
+  async ftsOnly(fn) {
+    try {
+      return await fn();
+    } catch (err) {
+      throw new FtsOnlyStatementError(err);
+    }
+  }
+  async initOnce(opts) {
+    const p = this.prefix;
     const state = await this.metadataRepo.getMeta(FTS5_STATE_KEY);
-    if (state === "live" && await this.triggersPresent()) {
-      await this.db.execAsync(fts5TablesDdl(this.prefix));
+    const schema = await this.readSchema();
+    const ftsExists = schema.tables.has(`${p}entries_fts`);
+    const mapExists = schema.tables.has(`${p}fts_map`);
+    const pendingExists = schema.tables.has(`${p}fts_pending`);
+    const trig = schema.triggersPresent;
+    const ftsDdl = schema.tables.get(`${p}entries_fts`) ?? null;
+    const tokenizerOk = ftsDdl === null || /tokenize\s*=\s*['"]porter\s+unicode61['"]/i.test(ftsDdl);
+    if (state === null && opts.entriesExisted === false) {
+      await this.db.withTransactionAsync(async (tx) => {
+        await tx.execAsync(fts5TablesDdl(p) + fts5PendingIndexesDdl(p) + fts5TriggersDdl(p));
+        await this.metadataRepo.setMeta(FTS5_STATE_KEY, "live", tx);
+      });
+      return;
+    }
+    if (state === "detached") return this.resetAndRearm();
+    if (!tokenizerOk) return this.resetAndRearm();
+    const intact = trig && ftsExists && mapExists && pendingExists;
+    if (intact && state === "rebuilding") return;
+    if (intact && state === "live") {
+      await this.ftsOnly(() => this.db.getFirstAsync(`SELECT rowid FROM ${p}entries_fts ORDER BY rowid DESC LIMIT 1`));
+      if (await this.liveRowUnindexed()) return this.resetAndRearm();
+      return;
+    }
+    if (ftsExists && mapExists && await this.keepMapConsistent()) {
+      await this.db.withTransactionAsync((tx) => this.rearmInTx(tx));
+      return;
+    }
+    return this.resetAndRearm();
+  }
+  /**
+   * The index was lost (rev 8 m3 / rev 9 m4): the oldest or the newest live entry is neither mapped nor
+   * ledgered, which `live` never allows. The oldest one keeps detection armed after post-loss writes
+   * repopulate the map and the ledger (#284 review). Every-open path: each side reads at most
+   * FTS5_DRAIN_CHUNK entries rows (final review M1), so an all-soft-deleted store is never fully scanned;
+   * a lost index whose oldest and newest rows are all deleted goes undetected.
+   */
+  async liveRowUnindexed() {
+    const p = this.prefix;
+    const edge = (dir) => `SELECT id FROM (SELECT id FROM (SELECT id, deleted_at FROM ${p}entries ORDER BY rowid ${dir} LIMIT ${FTS5_DRAIN_CHUNK}) WHERE deleted_at IS NULL LIMIT 1)`;
+    return await this.db.getFirstAsync(
+      `SELECT 1 AS x FROM (${edge("ASC")} UNION ALL ${edge("DESC")}) e
+        WHERE NOT EXISTS (SELECT 1 FROM ${p}fts_map m WHERE m.id = e.id)
+          AND NOT EXISTS (SELECT 1 FROM ${p}fts_pending q WHERE q.id = e.id)
+        LIMIT 1`
+    ) !== null;
+  }
+  /**
+   * Read-only keep-map check (spec DDL note): every surviving entries_fts
+   * rowid must have a map row. Max-rowid seek, then docsize vs map counts.
+   */
+  async keepMapConsistent() {
+    const p = this.prefix;
+    const fts = await this.ftsOnly(() => this.db.getFirstAsync(`SELECT rowid FROM ${p}entries_fts ORDER BY rowid DESC LIMIT 1`));
+    const map = await this.db.getFirstAsync(
+      `SELECT coalesce(max(fts_rowid), 0) AS hi, count(*) AS n FROM ${p}fts_map`
+    );
+    if ((fts?.rowid ?? 0) > (map?.hi ?? 0)) return false;
+    const doc = await this.ftsOnly(() => this.db.getFirstAsync(`SELECT count(*) AS n FROM ${p}entries_fts_docsize`));
+    return (doc?.n ?? 0) === (map?.n ?? 0);
+  }
+  /** Keep-map re-arm: triggers, empty ledger, rebuild from 0, state rebuilding. One transaction. */
+  async rearmInTx(tx) {
+    const p = this.prefix;
+    await tx.execAsync(fts5TablesDdl(p));
+    await tx.execAsync(`DELETE FROM ${p}fts_pending;`);
+    await tx.execAsync(fts5PendingIndexesDdl(p) + fts5TriggersDdl(p));
+    await writeRebuildStart(tx, p, this.metadataRepo);
+    await this.metadataRepo.setMeta(FTS5_STATE_KEY, "rebuilding", tx);
+  }
+  /** Reset path: retire entries_fts, recreate it empty, clear map + ledger, then the re-arm. One transaction. */
+  async resetAndRearm() {
+    const p = this.prefix;
+    await this.db.withTransactionAsync(async (tx) => {
+      await this.retireFtsTable(tx);
+      await tx.execAsync(fts5TablesDdl(p));
+      await tx.execAsync(`DELETE FROM ${p}fts_map; DELETE FROM ${p}fts_pending;`);
+      await this.rearmInTx(tx);
+    });
+  }
+  /** Rename-retire entries_fts (spec #280 rev 11); DROP only when the RENAME throws. */
+  async retireFtsTable(tx) {
+    const p = this.prefix;
+    if (!await this.metadataRepo.tableExists(`${p}entries_fts`, tx)) return;
+    const n = Number(await this.metadataRepo.getMeta(FTS5_RETIRED_COUNTER_KEY, tx) ?? "0") + 1;
+    const name = retiredTableName(p, n);
+    try {
+      await tx.execAsync(`ALTER TABLE ${p}entries_fts RENAME TO ${name}`);
+    } catch (err) {
+      if (isTransientOrTxFatal(err)) throw err;
+      await tx.execAsync(`DROP TABLE ${p}entries_fts`);
       return;
     }
+    await this.metadataRepo.setMeta(FTS5_RETIRED_TABLES_KEY, JSON.stringify([...await this.retiredList(tx), name]), tx);
+    await this.metadataRepo.setMeta(FTS5_RETIRED_COUNTER_KEY, String(n), tx);
+  }
+  async retiredList(tx = this.db) {
+    const raw = parseJsonArray(await this.metadataRepo.getMeta(FTS5_RETIRED_TABLES_KEY, tx), []);
+    return raw.filter((n) => isRetiredTableName(this.prefix, n));
+  }
+  async drain(opts = {}) {
+    try {
+      await this.drainOnce(opts);
+    } catch (err) {
+      if (ftsCorruptionClass(err) !== "vtab") throw err;
+      await this.resetAndRearm();
+      if (opts.ids && opts.ids.length > 0) await this.drainIds(opts.ids, idReindexChunkSql(this.prefix));
+    }
+  }
+  async drainOnce(opts) {
+    const ids = opts.ids ?? [];
+    if (ids.length > 0) await this.drainIds(ids);
+    if (opts.mode === "ledger") {
+      if (ids.length === 0 && opts.entityId !== void 0) await this.drainEntityChunk(opts.entityId);
+      else await this.drainLedgerChunk();
+      return;
+    }
+    await this.fullQuantum(opts.deadline ?? monotonicNow() + this.budgetMs);
+  }
+  /**
+   * One full quantum (spec #280 Change 3): ledger first (at most half the
+   * budget while `rebuilding`); then, while `rebuilding`, ≥1 window unless
+   * the ledger drain overran the deadline, one sweep tx, and the flip check;
+   * then reclamation. A `live` store reads only the state.
+   */
+  async fullQuantum(deadline) {
+    const rebuilding = await this.metadataRepo.getMeta(FTS5_STATE_KEY) === "rebuilding";
+    const start = monotonicNow();
+    const ledgerRan = await this.drainLedgerUntil(rebuilding ? start + (deadline - start) / 2 : deadline);
+    const ledgerOverran = ledgerRan && monotonicNow() >= deadline;
+    if (rebuilding) {
+      const progress = await readRebuildProgress(this.metadataRepo);
+      if (!progress || !await this.fingerprintValid(progress.wm)) {
+        await this.restartRebuild();
+      } else {
+        if (!ledgerOverran) {
+          let step;
+          do {
+            step = await this.runWindow(progress);
+          } while (step === "more" && monotonicNow() < deadline);
+          if (step !== "stale") await this.runSweepTx(progress);
+        }
+        await this.tryFlip();
+      }
+    }
+    try {
+      await this.reclaimRetired(deadline);
+    } catch (err) {
+      if (!isSqliteError(err)) throw err;
+    }
+  }
+  /** Bounded reclamation steps, each its own tx, until the deadline or nothing is retired. */
+  async reclaimRetired(deadline) {
+    while (monotonicNow() < deadline) {
+      const [name] = await this.retiredList();
+      if (name === void 0) return;
+      try {
+        if (!await this.metadataRepo.tableExists(name)) {
+          await this.delistRetired(name, false);
+          continue;
+        }
+        while (!await this.reclaimStep(name) && monotonicNow() < deadline) ;
+      } catch (err) {
+        if (ftsCorruptionClass(err) === null) throw err;
+        try {
+          await this.delistRetired(name, true);
+        } catch (dropErr) {
+          if (!isSqliteError(dropErr)) throw dropErr;
+          await this.delistRetired(name, false);
+        }
+      }
+    }
+  }
+  /** (1) delete <=500 rows, else (2) one bounded merge, else (3) DROP + delist. True once delisted. */
+  async reclaimStep(name) {
+    if (await this.db.getFirstAsync(`SELECT rowid FROM ${name} LIMIT 1`)) {
+      await this.db.withTransactionAsync(async (tx) => {
+        await tx.runAsync(`DELETE FROM ${name} WHERE rowid IN (SELECT rowid FROM ${name} ORDER BY rowid LIMIT ${FTS5_DRAIN_CHUNK})`);
+      });
+      return false;
+    }
+    let merged = false;
+    await this.db.withTransactionAsync(async (tx) => {
+      const before = await tx.getFirstAsync(`SELECT total_changes() AS n`);
+      await tx.runAsync(`INSERT INTO ${name}(${name}, rank) VALUES('merge', ${FTS5_RECLAIM_MERGE_PAGES})`);
+      const after = await tx.getFirstAsync(`SELECT total_changes() AS n`);
+      merged = (after?.n ?? 0) - (before?.n ?? 0) >= 2;
+    });
+    if (!merged) await this.delistRetired(name, true);
+    return !merged;
+  }
+  async delistRetired(name, drop) {
+    await this.db.withTransactionAsync(async (tx) => {
+      if (drop) await tx.execAsync(`DROP TABLE IF EXISTS ${name}`);
+      const rest = (await this.retiredList(tx)).filter((n) => n !== name);
+      await this.metadataRepo.setMeta(FTS5_RETIRED_TABLES_KEY, JSON.stringify(rest), tx);
+    });
+  }
+  /** The id at the watermark's rowid still matches. A null id (start, or windows complete) has nothing to check. */
+  async fingerprintValid(wm, tx = this.db) {
+    if (wm.id === null) return true;
+    const row = await tx.getFirstAsync(`SELECT id FROM ${this.prefix}entries WHERE rowid = ?`, [wm.rowid]);
+    return row?.id === wm.id;
+  }
+  /** External change under the watermark: start over (same re-arm transaction as a trigger-loss restart). */
+  async restartRebuild() {
+    await this.db.withTransactionAsync((tx) => this.rearmInTx(tx));
+  }
+  /**
+   * Progress as stored, re-read inside a window/sweep tx: false when it no
+   * longer matches what this quantum assumed (final review I1). Writing a
+   * watermark or cursor computed from a stale `pr` would overwrite a
+   * concurrent restart (runPrune VACUUM is not on the sync chain).
+   */
+  async progressUnchanged(pr, tx) {
+    if (await this.metadataRepo.getMeta(FTS5_STATE_KEY, tx) !== "rebuilding") return false;
+    const cur = await readRebuildProgress(this.metadataRepo, tx);
+    return cur !== null && cur.wm.rowid === pr.wm.rowid && cur.wm.id === pr.wm.id && cur.cursor === pr.cursor && cur.snapshot.entries === pr.snapshot.entries && cur.snapshot.map === pr.snapshot.map;
+  }
+  /** One window tx. 'done' once no rows remain in (wm, snapshot] (the watermark is then pinned at the snapshot, F9); 'stale' when progress moved under the quantum. */
+  async runWindow(pr) {
+    if (pr.wm.rowid >= pr.snapshot.entries) return "done";
+    const p = this.prefix;
+    let next = pr.wm;
+    let more = false;
+    let stale = false;
     await this.db.withTransactionAsync(async (tx) => {
-      await tx.execAsync(`DROP TABLE IF EXISTS ${this.prefix}entries_fts;`);
-      await tx.execAsync(fts5TablesDdl(this.prefix));
-      await this.rebuildInTx(tx);
-      await tx.execAsync(fts5TriggersDdl(this.prefix));
+      if (!await this.progressUnchanged(pr, tx)) {
+        stale = true;
+        return;
+      }
+      const row = await tx.getFirstAsync(windowHiSql(p), [pr.wm.rowid, pr.snapshot.entries]);
+      if (row?.hi == null) {
+        next = { rowid: pr.snapshot.entries, id: null };
+      } else {
+        for (const sql of windowChunkSql(p)) await tx.runAsync(sql, [pr.wm.rowid, row.hi]);
+        const fp = await tx.getFirstAsync(`SELECT id FROM ${p}entries WHERE rowid = ?`, [row.hi]);
+        next = { rowid: row.hi, id: fp.id };
+        more = true;
+      }
+      await this.metadataRepo.setMeta(FTS5_REBUILD_WM_KEY, JSON.stringify(next), tx);
+    });
+    if (stale) return "stale";
+    pr.wm = next;
+    return more ? "more" : "done";
+  }
+  /** At most one bounded sweep tx; the cursor advances in the same tx. */
+  async runSweepTx(pr) {
+    if (pr.cursor >= pr.snapshot.map) return;
+    const p = this.prefix;
+    let next = pr.cursor;
+    await this.db.withTransactionAsync(async (tx) => {
+      if (!await this.progressUnchanged(pr, tx)) return;
+      const row = await tx.getFirstAsync(sweepHiSql(p), [pr.cursor, pr.snapshot.map]);
+      const hi = row?.hi ?? pr.snapshot.map;
+      for (const sql of sweepChunkSql(p)) await tx.runAsync(sql, [pr.cursor, hi]);
+      await this.metadataRepo.setMeta(FTS5_SWEEP_CURSOR_KEY, String(hi), tx);
+      next = hi;
+    });
+    pr.cursor = next;
+  }
+  /** Completion, re-checked inside the flipping tx; the residual ledger (≤ one chunk) drains in it. */
+  async tryFlip() {
+    const p = this.prefix;
+    await this.db.withTransactionAsync(async (tx) => {
+      if (await this.metadataRepo.getMeta(FTS5_STATE_KEY, tx) !== "rebuilding") return;
+      const pr = await readRebuildProgress(this.metadataRepo, tx);
+      if (!pr || pr.wm.rowid < pr.snapshot.entries || pr.cursor < pr.snapshot.map) return;
+      if (!await this.fingerprintValid(pr.wm, tx)) return;
+      const residual = await tx.getFirstAsync(
+        `SELECT count(*) AS n FROM (SELECT 1 FROM ${p}fts_pending LIMIT ${FTS5_DRAIN_CHUNK + 1})`
+      );
+      if ((residual?.n ?? 0) > FTS5_DRAIN_CHUNK) return;
+      const hi = await tx.getFirstAsync(drainHiSql(p));
+      if (hi?.hi != null) for (const sql of drainChunkSql(p)) await tx.runAsync(sql, [hi.hi]);
+      await this.metadataRepo.deleteMeta(FTS5_REBUILD_WM_KEY, tx);
+      await this.metadataRepo.deleteMeta(FTS5_REBUILD_SNAPSHOT_KEY, tx);
+      await this.metadataRepo.deleteMeta(FTS5_SWEEP_CURSOR_KEY, tx);
       await this.metadataRepo.setMeta(FTS5_STATE_KEY, "live", tx);
     });
   }
-  async rebuildFromSource() {
-    await this.db.withTransactionAsync((tx) => this.rebuildInTx(tx));
+  /** Seq-ordered ledger chunks until empty or `stopAt`. True when a chunk ran. */
+  async drainLedgerUntil(stopAt) {
+    let ran = false;
+    while (await this.drainLedgerChunk()) {
+      ran = true;
+      if (monotonicNow() >= stopAt) break;
+    }
+    return ran;
   }
-  async drain() {
-    const hiSql = drainHiSql(this.prefix);
-    const chunk = drainChunkSql(this.prefix);
-    for (; ; ) {
-      const done = await this.db.withTransactionAsync(async (tx) => {
-        const row = await tx.getFirstAsync(hiSql);
-        if (row?.hi == null) return true;
-        for (const sql of chunk) await tx.runAsync(sql, [row.hi]);
-        return false;
+  /** The caller's own ids, to completion, ≤ FTS5_DRAIN_CHUNK per transaction. */
+  async drainIds(ids, chunk = idDrainChunkSql(this.prefix)) {
+    const unique = [...new Set(ids)];
+    for (let i = 0; i < unique.length; i += FTS5_DRAIN_CHUNK) {
+      const json = JSON.stringify(unique.slice(i, i + FTS5_DRAIN_CHUNK));
+      await this.db.withTransactionAsync(async (tx) => {
+        for (const sql of chunk) await tx.runAsync(sql, [json]);
       });
-      if (done) return;
     }
   }
+  /** One seq-ordered chunk. False when the ledger was empty. */
+  async drainLedgerChunk() {
+    const hiSql = drainHiSql(this.prefix);
+    const chunk = drainChunkSql(this.prefix);
+    let ran = false;
+    await this.db.withTransactionAsync(async (tx) => {
+      const row = await tx.getFirstAsync(hiSql);
+      if (row?.hi == null) return;
+      for (const sql of chunk) await tx.runAsync(sql, [row.hi]);
+      ran = true;
+    });
+    return ran;
+  }
+  /** One entity-targeted chunk (ORDER BY seq, ≤ FTS5_DRAIN_CHUNK). */
+  async drainEntityChunk(entityId) {
+    const hiSql = entityDrainHiSql(this.prefix);
+    const chunk = entityDrainChunkSql(this.prefix);
+    await this.db.withTransactionAsync(async (tx) => {
+      const row = await tx.getFirstAsync(hiSql, [entityId]);
+      if (row?.hi == null) return;
+      for (const sql of chunk) await tx.runAsync(sql, [entityId, row.hi]);
+    });
+  }
   async replace(entityId, ids, documents) {
     assertEntity(entityId, documents);
     const docIds = documents.map((d) => d.id);
@@ -4870,20 +5328,57 @@ var Fts5IndexStrategy = class {
       );
     }
   }
-  async rebuildInTx(tx) {
+  /** The init probes' schema facts in one sqlite_master read (#284 review): FTS tables with their DDL, and the triggers. */
+  async readSchema() {
     const p = this.prefix;
-    await tx.execAsync(`DELETE FROM ${p}entries_fts; DELETE FROM ${p}fts_map; DELETE FROM ${p}fts_pending;`);
-    for (const sql of rebuildSql(p)) await tx.runAsync(sql);
-  }
-  async triggersPresent() {
-    const names = fts5TriggerNames(this.prefix);
+    const triggers = fts5TriggerNames(p);
+    const names = [`${p}entries_fts`, `${p}fts_map`, `${p}fts_pending`, ...triggers];
     const rows = await this.db.getAllAsync(
-      `SELECT name FROM sqlite_master WHERE type = 'trigger' AND name IN (?, ?, ?)`,
-      [...names]
+      `SELECT type, name, sql FROM sqlite_master WHERE name IN (${names.map(() => "?").join(", ")})`,
+      names
     );
-    return rows.length === names.length;
+    const tables = new Map(rows.filter((r) => r.type === "table").map((r) => [r.name, r.sql]));
+    const present = new Set(rows.filter((r) => r.type === "trigger").map((r) => r.name));
+    return { tables, triggersPresent: triggers.every((n) => present.has(n)) };
   }
 };
+var FtsOnlyStatementError = class extends Error {
+  constructor(cause) {
+    super("FTS-only statement failed");
+    this.ftsOnlyCause = cause;
+  }
+};
+function unwrapFtsOnly(err) {
+  try {
+    if (err instanceof FtsOnlyStatementError) return { cause: err.ftsOnlyCause, ftsOnly: true };
+  } catch {
+  }
+  return { cause: err, ftsOnly: false };
+}
+function safeSqliteCode(err) {
+  try {
+    const code = extractSqliteCode(err);
+    if (code !== void 0) return code;
+    const lifted = err?.sqliteErrorCode;
+    return typeof lifted === "string" ? lifted : void 0;
+  } catch {
+    return void 0;
+  }
+}
+var TRANSIENT_OR_TX_FATAL = ["SQLITE_BUSY", "SQLITE_LOCKED", "SQLITE_FULL", "SQLITE_IOERR", "SQLITE_NOMEM", "SQLITE_INTERRUPT", "SQLITE_ABORT", "SQLITE_READONLY"];
+function isTransientOrTxFatal(err) {
+  const code = safeSqliteCode(err);
+  return code !== void 0 && TRANSIENT_OR_TX_FATAL.some((c) => code === c || code.startsWith(`${c}_`));
+}
+function ftsCorruptionClass(err) {
+  const code = safeSqliteCode(err);
+  if (code === "SQLITE_CORRUPT_VTAB") return "vtab";
+  if (code?.startsWith("SQLITE_CORRUPT")) return "corrupt";
+  return null;
+}
+function isSqliteError(err) {
+  return safeSqliteCode(err) !== void 0;
+}
 function assertEntity(entityId, documents) {
   for (const d of documents) {
     if (d.entity_id !== entityId) {
@@ -4941,15 +5436,15 @@ async function detachFts5(db, prefix, metadataRepo) {
   } catch {
   }
 }
-async function createIndexStrategy(db, prefix, metadataRepo, preferred) {
+async function createIndexStrategy(db, prefix, metadataRepo, preferred, opts = {}) {
   if (preferred === "minisearch") {
     await detachFts5(db, prefix, metadataRepo);
     return new MiniSearchIndexStrategy();
   }
   const attempt = async () => {
     if (!await probeFts5(db, prefix)) return "absent";
-    const strategy = new Fts5IndexStrategy(db, prefix, metadataRepo);
-    await strategy.init();
+    const strategy = new Fts5IndexStrategy(db, prefix, metadataRepo, opts.setupBudgetMs);
+    await strategy.init({ entriesExisted: opts.entriesExisted });
     return strategy;
   };
   const absent = async () => {
@@ -6312,7 +6807,8 @@ var IngestionService = class {
    *
    * @returns Counts: nodesWritten (validated nodes persisted), edgesWritten
    *   (manifest-valid edges persisted), superseded (prior facts soft-deleted
-   *   plus prior source-ref edges hard-deleted).
+   *   plus prior source-ref edges hard-deleted), and supersededFactIds (the
+   *   ids of those soft-deleted facts, for the caller's post-commit index sync).
    *
    * Node-ownership pre-flight (spec §3, REQ-GRAPH-01): the first statement
    * is `assertGraphNodeOwnership(entityId, params.nodes, tx)`, which runs
@@ -6440,7 +6936,8 @@ var IngestionService = class {
     return {
       nodesWritten: wikiFacts.length,
       edgesWritten: edgesInsertedCount,
-      superseded: deletedFactIds.length + deletedEdgeCount
+      superseded: deletedFactIds.length + deletedEdgeCount,
+      supersededFactIds: deletedFactIds
     };
   }
   /**
@@ -7724,6 +8221,7 @@ var MaintenanceService = class {
       if (vacuum) {
         await resetNormalizeWatermarks(this.metadataRepo);
         await this.metadataRepo.vacuum();
+        await restartRebuildAfterVacuum(this.db, this.prefix, this.metadataRepo);
       }
       await this.searchService.syncEntries(entityId, syncedIds);
       return { entries: deletedEntries, tasks: deletedTasks, events: deletedEvents };
@@ -9167,7 +9665,7 @@ var ImportExportService = class {
     if (merge) {
       await this.searchService.syncEntries(entityId, [...upsertedFactIds]);
     } else {
-      await this.searchService.sync(entityId);
+      await this.searchService.sync(entityId, { ids: [.../* @__PURE__ */ new Set([...upsertedFactIds, ...softDeletedFactIds])] });
     }
     for (const fact of bundle.facts) {
       if (!fact.deleted_at && upsertedFactIds.has(fact.id) && !factsWithPreservedBlob.has(fact.id)) {
@@ -10971,7 +11469,6 @@ var TABLE_PREFIX_PATTERN = /^[A-Za-z][A-Za-z0-9_]{0,30}_$/;
 var SEARCH_REINIT_COOLDOWN_MS = 5e3;
 var SEARCH_REINIT_COOLDOWN_MAX_MS = 5 * 6e4;
 var SEARCH_REINIT_COST_FACTOR = 10;
-var monotonicNow = () => typeof performance !== "undefined" && typeof performance.now === "function" ? performance.now() : Date.now();
 function decodeDraftCursor(cursor) {
   const sep = typeof cursor === "string" ? cursor.indexOf(":") : -1;
   const createdAt = sep > 0 ? Number(cursor.slice(0, sep)) : Number.NaN;
@@ -10986,6 +11483,16 @@ var WikiMemory = class {
   constructor(db, options) {
     /** Emits `__testAccess` console warning at most once per instance when NODE_ENV ≠ "test". */
     __privateAdd(this, _testAccessNonTestEnvWarned, false);
+    /**
+     * upsertGraph node and superseded-fact ids per entity, awaiting syncSearchIndex(), each with the
+     * generation of its latest stash. Ids leave the stash only once a drain
+     * succeeded, so a failed drain retries them next call.
+     */
+    this.upsertIdStash = /* @__PURE__ */ new Map();
+    /** Total ids across upsertIdStash, kept in step so the cap check is O(1). */
+    this.upsertIdStashSize = 0;
+    /** Bumped per stashed id; a re-stash during an in-flight drain outlives that drain's drop. */
+    this.upsertIdStashGen = 0;
     this.reinitSearch = null;
     /** Monotonic time before which a no-arg syncSearchIndex() skips the re-init (0 = no cooldown). */
     this.reinitRetryAt = 0;
@@ -11122,6 +11629,49 @@ var WikiMemory = class {
       jobManager: this.jobManager
     };
   }
+  stashUpsertIds(entityId, ids) {
+    if (!this.searchService.hasLedger()) return;
+    const cap = this.constructor.UPSERT_ID_STASH_CAP;
+    const stash = this.upsertIdStash.get(entityId) ?? /* @__PURE__ */ new Map();
+    for (const id of ids) {
+      if (!stash.has(id)) {
+        if (this.upsertIdStashSize >= cap) continue;
+        this.upsertIdStashSize++;
+      }
+      stash.set(id, ++this.upsertIdStashGen);
+    }
+    if (stash.size > 0) this.upsertIdStash.set(entityId, stash);
+  }
+  /** Snapshot of the stash (one entity, or all) with generations, without removing anything. */
+  peekStashedIds(entityId) {
+    const snapshot = /* @__PURE__ */ new Map();
+    for (const [id, stash] of this.upsertIdStash) {
+      if (entityId === void 0 || id === entityId) snapshot.set(id, new Map(stash));
+    }
+    return snapshot;
+  }
+  /**
+   * Removes a drained snapshot. An id re-stashed after the peek has a newer
+   * generation and stays: the drain may have run before that write committed.
+   */
+  dropStashedIds(snapshot) {
+    for (const [entityId, drained] of snapshot) {
+      const stash = this.upsertIdStash.get(entityId);
+      if (!stash) continue;
+      for (const [id, gen] of drained) {
+        if (stash.get(id) === gen && stash.delete(id)) this.upsertIdStashSize--;
+      }
+      if (stash.size === 0) this.upsertIdStash.delete(entityId);
+    }
+  }
+  /** `config.setupBudgetMs` or the default, validated: a positive finite number. */
+  setupBudgetMs() {
+    const budget = this.options.config?.setupBudgetMs ?? DEFAULT_SETUP_BUDGET_MS;
+    if (typeof budget !== "number" || !Number.isFinite(budget) || budget <= 0) {
+      throw new TypeError(`setupBudgetMs must be a positive finite number; got ${String(budget)}`);
+    }
+    return budget;
+  }
   /**
    * Opens the store: migration gate, DDL, schema migrations, then the stamped
    * source_ref normalize. Await it before any other call on this instance — the
@@ -11132,8 +11682,15 @@ var WikiMemory = class {
    * Pass `{ migrations: 'refuse' }` from inside a writer lease: pending one-time
    * work then throws WikiMigrationRequiredError before any mutation, and the
    * host runs a plain `setup()` outside the lease.
+   *
+   * Keyword-index catch-up work is bounded by `config.setupBudgetMs`; anything
+   * left converges on later opens and no-arg `syncSearchIndex()` calls. Not
+   * bounded: an index reset (tokenizer change, re-attach after detach, a lost
+   * or inconsistent index), which runs as one unchunked transaction.
    */
   async setup(opts) {
+    const setupBudgetMs = this.setupBudgetMs();
+    const openDeadline = monotonicNow() + setupBudgetMs;
     const entriesExistedBeforeSetup = await this.metadataRepo.tableExists(`${this.prefix}entries`);
     const migrationPolicy = opts?.migrations ?? this.options.config?.migrations ?? "allow";
     await setupDatabaseWithGate(this.db, this.prefix, this.metadataRepo, migrationPolicy);
@@ -11168,10 +11725,11 @@ var WikiMemory = class {
         this.db,
         this.prefix,
         this.metadataRepo,
-        this.options.config?.indexStrategy ?? "auto"
+        this.options.config?.indexStrategy ?? "auto",
+        { setupBudgetMs, entriesExisted: entriesExistedBeforeSetup }
       )
     );
-    await this.searchService.sync();
+    await this.searchService.sync(void 0, { deadline: openDeadline });
   }
   async hasChanged(entityId, sourceRefOrEntries, sourceHashArg) {
     if (typeof sourceRefOrEntries === "string") {
@@ -11422,14 +11980,18 @@ var WikiMemory = class {
    * commit, so without this the nodes stay out of keyword, hybrid and
    * fallback retrieval until the entity's next core write.
    *
-   * With `entityId`, rebuilds that entity if it is stale or has never been
-   * indexed; otherwise it is a no-op that still waits for rebuilds already
-   * queued. Without an argument, rebuilds every entity currently marked
-   * stale; when none is, it resolves immediately and does not wait for rebuilds
-   * already queued. While keyword search is unavailable it first retries the
-   * index init; after a failed attempt it waits at least 5 s, doubling per
-   * consecutive failure up to 5 min (longer when an attempt is itself slow),
-   * before retrying again.
+   * With `entityId`: drains that entity's pending `upsertGraph` ids (its new
+   * nodes and the facts they superseded) first, to completion, then at most
+   * one more ledger chunk — so its new nodes are searchable, and the
+   * superseded facts gone, when the call resolves, under any backlog. Without an
+   * argument: drains every stashed `upsertGraph` id across entities first,
+   * then runs one keyword-index quantum bounded by `config.setupBudgetMs`
+   * (backlog drain, then rebuild work while the index is rebuilding). Hosts
+   * with a long-lived process should call the no-arg form on their own
+   * schedule: that is what converges a rebuilding index. While keyword search
+   * is unavailable it first retries the index init; after a failed attempt it
+   * waits at least 5 s, doubling per consecutive failure up to 5 min (longer
+   * when an attempt is itself slow), before retrying again.
    *
    * Call only after the host's transaction commits: called inside it, the
    * rebuild may index rows that later roll back, or miss them and clear the
@@ -11455,10 +12017,11 @@ var WikiMemory = class {
               this.db,
               this.prefix,
               this.metadataRepo,
-              this.options.config?.indexStrategy ?? "auto"
+              this.options.config?.indexStrategy ?? "auto",
+              { setupBudgetMs: this.setupBudgetMs() }
             );
             this.searchService.setIndexStrategy(strategy);
-            if (this.searchService.isKeywordAvailable()) await this.searchService.sync();
+            if (this.searchService.isKeywordAvailable() && !this.searchService.hasLedger()) await this.searchService.sync();
           } finally {
             if (this.searchService.isKeywordAvailable()) {
               this.reinitFailures = 0;
@@ -11474,10 +12037,24 @@ var WikiMemory = class {
         })());
         await this.reinitSearch;
       }
-      return this.searchService.syncStale();
+      const stashed2 = this.peekStashedIds();
+      const ids = [...stashed2.values()].flatMap((m) => [...m.keys()]);
+      if (await this.syncDrained(this.searchService.syncStale({ ids }))) this.dropStashedIds(stashed2);
+      return;
     }
     assertEntityId(entityId);
-    return this.searchService.syncEntries(entityId, []);
+    const stashed = this.peekStashedIds(entityId);
+    if (await this.syncDrained(this.searchService.syncEntries(entityId, stashed.get(entityId)?.keys() ?? []))) {
+      this.dropStashedIds(stashed);
+    }
+  }
+  /**
+   * True when a sync applied the stashed ids. While keyword search is
+   * unavailable the stand-in strategy's drain is a no-op that reports success,
+   * so the ids stay stashed for the first sync after a re-init (#284 review).
+   */
+  async syncDrained(sync) {
+    return await sync && this.searchService.isKeywordAvailable();
   }
   async exportDump(entityIds) {
     return this.importExportService.exportDump(entityIds);
@@ -11528,7 +12105,10 @@ var WikiMemory = class {
    * post-commit work (search sync, embedding, cache eviction). After the
    * transaction commits, call `syncSearchIndex(entityId)` — or
    * `syncSearchIndex()` after writing several entities in one transaction —
-   * to make the new nodes keyword-searchable. Embeddings still come from the maintenance
+   * to make the new nodes keyword-searchable: both forms drain this call's node ids
+   * first, to completion, so the nodes are searchable under any backlog (up to
+   * `WikiMemory.UPSERT_ID_STASH_CAP` pending ids; beyond that they converge with
+   * the backlog). Embeddings still come from the maintenance
    * sweep (`runLibrarian` / `runHeal` / `runOntologyBackfill` / `runPrune`,
    * scoped via `listEntityIds`).
    *
@@ -11578,12 +12158,13 @@ var WikiMemory = class {
       });
     }
     const diagBuffer = new DiagnosticBuffer();
-    const result = await this.ingestionService.upsertGraphCore(
+    const { supersededFactIds, ...result } = await this.ingestionService.upsertGraphCore(
       entityId,
       { sourceRef, sourceHash, nodes: params.nodes, edges: params.edges },
       adapter,
       { diag: { buffer: diagBuffer, operation: "upsertGraph" } }
     );
+    this.stashUpsertIds(entityId, [...supersededFactIds, ...params.nodes.map((n) => n.id)]);
     this.searchService.markStale(entityId);
     diagBuffer.flush(this.options);
     return result;
@@ -11766,6 +12347,8 @@ var WikiMemory = class {
   }
 };
 _testAccessNonTestEnvWarned = new WeakMap();
+/** Max upsertGraph node ids held for their post-commit sync (spec #280 id threading). */
+WikiMemory.UPSERT_ID_STASH_CAP = 1e4;
 function assertEntityId(entityId) {
   if (typeof entityId !== "string" || entityId.length === 0) {
     throw new TypeError("Invalid entityId: must be a non-empty string.");
@@ -12695,6 +13278,7 @@ exports.DEFAULT_CHUNK_OVERLAP = DEFAULT_CHUNK_OVERLAP;
 exports.DEFAULT_LIBRARIAN_SYNTHESIS_PROMPT = DEFAULT_LIBRARIAN_SYNTHESIS_PROMPT;
 exports.DEFAULT_MAX_CHUNK_LENGTH = DEFAULT_MAX_CHUNK_LENGTH;
 exports.DEFAULT_MAX_EMBED_CHARS = DEFAULT_MAX_EMBED_CHARS;
+exports.DEFAULT_SETUP_BUDGET_MS = DEFAULT_SETUP_BUDGET_MS;
 exports.EMBED_CHARS_CEILING = EMBED_CHARS_CEILING;
 exports.HEAL_ANCHORS_PER_CANDIDATE = HEAL_ANCHORS_PER_CANDIDATE;
 exports.HEAL_BATCH_SIZE = HEAL_BATCH_SIZE;