@equationalapplications/core-llm-wiki 7.12.0 → 7.13.0

package/dist/index.mjs

@@ -1,5 +1,5 @@
-import { BaseRepository, WikiGraphNodeOwnershipConflict, parseJsonObject, parseJsonArray, liveAtSql, __privateAdd, MetadataRepository, EmbeddingService, SearchService, TemporalService, JobManager, PromptService, resolveGrounding, IngestionService, MaintenanceService, ImportExportService, RetrievalService, WriteService, __privateGet, __privateSet, createLegacySourceTypeIndex, writeNormalizeStamp, CURRENT_SCHEMA_VERSION, detectSchemaVersion, MIGRATIONS, runSourceRefNormalize, normalizeSourceRef, normalizeSourceHash, entitySummaryMetaKey, WikiSourceRefHashCollision, DiagnosticBuffer, validateManifest, WikiDraftNotFound, generateId, emptyManifest, resolveNodeType, WikiStrictOntologyViolation, validateInlineEdges, resolveEdgeDefinitions, typeSatisfies, normalizeTitleKey, edgeTripleAllowed, MAX_EMBED_ATTEMPTS, UsageMeter, isWikiSearchUnavailableError, WikiBusyError, WikiInvalidReadOptions, isLiveAt, packFactsByBudget, factTokenCost, probePendingWork, WikiMigrationRequiredError, setupDatabase, UnavailableIndexStrategy, WikiTransactionError, extractSqliteCode } from './chunk-KN4XSLLB.mjs';
-export { DEFAULT_CHUNK_OVERLAP, DEFAULT_MAX_CHUNK_LENGTH, DEFAULT_MAX_EMBED_CHARS, EMBED_CHARS_CEILING, HEAL_ANCHORS_PER_CANDIDATE, HEAL_BATCH_SIZE, HEAL_MAX_FACT_BODY_CHARS_L3, HEAL_MAX_TASKS, HEAL_RECHECK_MS, HOOK_TIMEOUT_MARKER, ONTOLOGY_BACKFILL_BATCH_SIZE, ONTOLOGY_BACKFILL_MAX_PROMPT_CHARS, ONTOLOGY_BACKFILL_RECHECK_MS, ONTOLOGY_BACKFILL_SYSTEM_PROMPT, PromptService, PrunePartialFailureError, WikiBusyError, WikiDraftNotFound, WikiDuplicateHashError, WikiGraphNodeOwnershipConflict, WikiIngestEmptyError, WikiInvalidReadOptions, WikiMigrationRequiredError, WikiParseError, WikiSearchUnavailableError, WikiSourceRefHashCollision, WikiStrictOntologyViolation, WikiSupersedeError, WikiTransactionError, chunkText, configureRandomSource, isWikiSearchUnavailableError, parseEmbedding, safeSlice, validateManifest } from './chunk-KN4XSLLB.mjs';
+import { BaseRepository, WikiGraphNodeOwnershipConflict, parseJsonObject, parseJsonArray, liveAtSql, reanchorRebuildFingerprint, __privateAdd, MetadataRepository, EmbeddingService, SearchService, TemporalService, JobManager, PromptService, resolveGrounding, IngestionService, MaintenanceService, ImportExportService, RetrievalService, WriteService, __privateGet, __privateSet, createLegacySourceTypeIndex, writeNormalizeStamp, CURRENT_SCHEMA_VERSION, detectSchemaVersion, MIGRATIONS, runSourceRefNormalize, normalizeSourceRef, normalizeSourceHash, entitySummaryMetaKey, WikiSourceRefHashCollision, DiagnosticBuffer, validateManifest, WikiDraftNotFound, generateId, emptyManifest, resolveNodeType, WikiStrictOntologyViolation, validateInlineEdges, resolveEdgeDefinitions, typeSatisfies, normalizeTitleKey, edgeTripleAllowed, MAX_EMBED_ATTEMPTS, UsageMeter, isWikiSearchUnavailableError, WikiBusyError, WikiInvalidReadOptions, isLiveAt, packFactsByBudget, factTokenCost, probePendingWork, WikiMigrationRequiredError, setupDatabase, UnavailableIndexStrategy, FTS5_STATE_KEY, fts5LedgerDropSql, fts5TablesDdl, fts5PendingIndexesDdl, fts5TriggersDdl, writeRebuildStart, FTS5_RETIRED_COUNTER_KEY, retiredTableName, FTS5_RETIRED_TABLES_KEY, isRetiredTableName, idReindexChunkSql, readRebuildProgress, FTS5_DRAIN_CHUNK, FTS5_RECLAIM_MERGE_PAGES, windowHiSql, windowChunkSql, FTS5_REBUILD_WM_KEY, sweepHiSql, sweepChunkSql, FTS5_SWEEP_CURSOR_KEY, drainHiSql, drainChunkSql, FTS5_REBUILD_SNAPSHOT_KEY, idDrainChunkSql, entityDrainHiSql, entityDrainChunkSql, fts5TriggerNames, extractSqliteCode, WikiTransactionError } from './chunk-PCRYIUV5.mjs';
+export { DEFAULT_CHUNK_OVERLAP, DEFAULT_MAX_CHUNK_LENGTH, DEFAULT_MAX_EMBED_CHARS, EMBED_CHARS_CEILING, HEAL_ANCHORS_PER_CANDIDATE, HEAL_BATCH_SIZE, HEAL_MAX_FACT_BODY_CHARS_L3, HEAL_MAX_TASKS, HEAL_RECHECK_MS, HOOK_TIMEOUT_MARKER, ONTOLOGY_BACKFILL_BATCH_SIZE, ONTOLOGY_BACKFILL_MAX_PROMPT_CHARS, ONTOLOGY_BACKFILL_RECHECK_MS, ONTOLOGY_BACKFILL_SYSTEM_PROMPT, PromptService, PrunePartialFailureError, WikiBusyError, WikiDraftNotFound, WikiDuplicateHashError, WikiGraphNodeOwnershipConflict, WikiIngestEmptyError, WikiInvalidReadOptions, WikiMigrationRequiredError, WikiParseError, WikiSearchUnavailableError, WikiSourceRefHashCollision, WikiStrictOntologyViolation, WikiSupersedeError, WikiTransactionError, chunkText, configureRandomSource, isWikiSearchUnavailableError, parseEmbedding, safeSlice, validateManifest } from './chunk-PCRYIUV5.mjs';
 import { deriveTrustTier, isStaleAfter, appendRelatedSection, buildConceptDocument, buildLogMd, buildEntityIndexMd, buildRootIndexMd, isAllowedOkfPath, parseRootIndexMd, parseEntityIndexMd, parseConcept, splitRelatedSection, extractMarkdownLinks, parseLogMd, parseEventIdComment, latestVerified, formatSourcesJson, appendEventIdComment, parseVerifiedFlexible, parseCitationsList } from '@equationalapplications/core-okf';
 import MiniSearch from 'minisearch';
 
@@ -695,6 +695,7 @@ var _EntryRepository = class _EntryRepository extends BaseRepository {
         }
       }
     }
+    if (totalChanges > 0) await reanchorRebuildFingerprint(executor, this.prefix, ids);
     return totalChanges;
   }
   /**
@@ -2512,87 +2513,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;
@@ -2605,41 +2530,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;
+  }
+  /**
+   * 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 init() {
+  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 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));
+      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) => {
+      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);
@@ -2717,20 +2964,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) {
@@ -2788,15 +3072,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 () => {
@@ -3508,7 +3792,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;
@@ -3523,6 +3806,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;
@@ -3659,6 +3952,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
@@ -3669,8 +4005,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);
@@ -3705,10 +4048,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") {
@@ -3959,14 +4303,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
@@ -3992,10 +4340,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;
@@ -4011,10 +4360,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);
@@ -4065,7 +4428,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`).
    *
@@ -4115,12 +4481,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;
@@ -4303,6 +4670,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.");
@@ -5228,6 +5597,6 @@ function createWiki(db, options) {
   return new WikiMemory(db, options);
 }
 
-export { DEFAULT_LIBRARIAN_SYNTHESIS_PROMPT, WikiMemory, createWiki, formatContext, formatGraphContext, formatMemoryDump, formatOkfBundle, hydrateLibrarianPrompt, mapLibrarianOptionsToReadOptions, parseOkfBundle, validateLibrarianPromptTemplate };
+export { DEFAULT_LIBRARIAN_SYNTHESIS_PROMPT, DEFAULT_SETUP_BUDGET_MS, WikiMemory, createWiki, formatContext, formatGraphContext, formatMemoryDump, formatOkfBundle, hydrateLibrarianPrompt, mapLibrarianOptionsToReadOptions, parseOkfBundle, validateLibrarianPromptTemplate };
 //# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map