@equationalapplications/core-llm-wiki 7.11.2 → 7.13.0

package/dist/index.mjs

@@ -1,187 +1,25 @@
-import { BaseRepository, WikiGraphNodeOwnershipConflict, liveAtSql, __privateAdd, MetadataRepository, EmbeddingService, SearchService, TemporalService, JobManager, PromptService, resolveGrounding, IngestionService, MaintenanceService, ImportExportService, RetrievalService, WriteService, __privateGet, __privateSet, normalizeSourceRef, normalizeSourceHash, entitySummaryMetaKey, WikiSourceRefHashCollision, DiagnosticBuffer, validateManifest, WikiDraftNotFound, generateId, emptyManifest, resolveNodeType, WikiStrictOntologyViolation, validateInlineEdges, resolveEdgeDefinitions, typeSatisfies, normalizeTitleKey, edgeTripleAllowed, MAX_EMBED_ATTEMPTS, UsageMeter, WikiBusyError, WikiInvalidReadOptions, isLiveAt, packFactsByBudget, factTokenCost, WikiTransactionError, extractSqliteCode } from './chunk-522SCN2E.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, WikiParseError, WikiSourceRefHashCollision, WikiStrictOntologyViolation, WikiSupersedeError, WikiTransactionError, chunkText, configureRandomSource, parseEmbedding, safeSlice, validateManifest } from './chunk-522SCN2E.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';
 
-// src/db/schema.ts
-async function setupDatabase(db, prefix) {
-  await db.execAsync(`
-    CREATE TABLE IF NOT EXISTS ${prefix}entries (
-      id TEXT PRIMARY KEY,
-      entity_id TEXT NOT NULL,
-      title TEXT NOT NULL,
-      body TEXT NOT NULL,
-      tags TEXT NOT NULL DEFAULT '[]',
-      confidence TEXT NOT NULL DEFAULT 'inferred',
-      source_type TEXT NOT NULL DEFAULT 'librarian_inferred',
-      source_hash TEXT,
-      source_ref TEXT,
-      created_at INTEGER NOT NULL,
-      updated_at INTEGER NOT NULL,
-      last_accessed_at INTEGER,
-      access_count INTEGER NOT NULL DEFAULT 0,
-      deleted_at INTEGER,
-      embedding TEXT,
-      embedding_blob BLOB,
-      okf_type TEXT,
-      ontology_checked_at INTEGER,
-      heal_checked_at INTEGER,
-      lifecycle_status TEXT NOT NULL DEFAULT 'stable',
-      stale_after INTEGER,
-      generated_by TEXT,
-      last_verified_at INTEGER,
-      last_verified_by TEXT,
-      okf_sources TEXT,
-      okf_verified TEXT,
-      okf_usage_window TEXT,
-      embedding_failed_at INTEGER,
-      embedding_failure_kind TEXT,
-      embedding_attempts INTEGER NOT NULL DEFAULT 0,
-      valid_from INTEGER,
-      valid_to INTEGER,
-      superseded_by TEXT,
-      superseded_at INTEGER
-    );
-
-    CREATE INDEX IF NOT EXISTS ${prefix}entries_entity_idx ON ${prefix}entries(entity_id);
-    CREATE INDEX IF NOT EXISTS ${prefix}entries_source_ref_idx ON ${prefix}entries(entity_id, source_ref);
-    CREATE INDEX IF NOT EXISTS ${prefix}entries_source_hash_idx ON ${prefix}entries(entity_id, source_hash) WHERE source_hash IS NOT NULL;
-    CREATE INDEX IF NOT EXISTS ${prefix}entries_updated_idx ON ${prefix}entries(updated_at DESC);
-
-    -- source_ref_index: per-(entity, source_hash) record of the canonical sourceRef
-    -- currently holding that hash. The partial UNIQUE index on (entity_id, source_hash)
-    -- WHERE deleted_at IS NULL enforces the sourceRef-level TOCTOU-race invariant;
-    -- entries-level uniqueness cannot express it because a single ingestDocument call
-    -- writes N facts that all share (entity_id, source_ref, source_hash). See
-    -- docs/superpowers/specs/2026-08-07-dependabot-concurrency-release-hygiene-design.md \xA7B1.
-    CREATE TABLE IF NOT EXISTS ${prefix}source_ref_index (
-      id TEXT PRIMARY KEY,
-      entity_id TEXT NOT NULL,
-      source_hash TEXT NOT NULL,
-      source_ref TEXT NOT NULL,
-      created_at INTEGER NOT NULL,
-      deleted_at INTEGER
-    );
-    CREATE UNIQUE INDEX IF NOT EXISTS ${prefix}idx_source_ref_hash
-      ON ${prefix}source_ref_index (entity_id, source_hash)
-      WHERE deleted_at IS NULL;
-
-    CREATE TABLE IF NOT EXISTS ${prefix}tasks (
-      id TEXT PRIMARY KEY,
-      entity_id TEXT NOT NULL,
-      description TEXT NOT NULL,
-      status TEXT NOT NULL DEFAULT 'pending',
-      priority INTEGER NOT NULL DEFAULT 0,
-      created_at INTEGER NOT NULL,
-      updated_at INTEGER NOT NULL,
-      resolved_at INTEGER,
-      deleted_at INTEGER,
-      okf_type TEXT,
-      lifecycle_status TEXT NOT NULL DEFAULT 'stable',
-      stale_after INTEGER,
-      generated_by TEXT,
-      last_verified_at INTEGER,
-      last_verified_by TEXT,
-      okf_sources TEXT,
-      okf_verified TEXT,
-      okf_usage_window TEXT
-    );
-
-    CREATE INDEX IF NOT EXISTS ${prefix}tasks_entity_idx ON ${prefix}tasks(entity_id, status);
-
-    CREATE TABLE IF NOT EXISTS ${prefix}edges (
-      id TEXT PRIMARY KEY,
-      entity_id TEXT NOT NULL,
-      source_id TEXT NOT NULL,
-      target_id TEXT NOT NULL,
-      edge_type TEXT NOT NULL,
-      created_at INTEGER NOT NULL,
-      UNIQUE(entity_id, source_id, target_id, edge_type)
-    );
-
-    CREATE INDEX IF NOT EXISTS ${prefix}edges_entity_id_idx ON ${prefix}edges(entity_id, id);
-
-    CREATE TABLE IF NOT EXISTS ${prefix}events (
-      id TEXT PRIMARY KEY,
-      entity_id TEXT NOT NULL,
-      event_type TEXT NOT NULL,
-      summary TEXT NOT NULL,
-      related_entry_id TEXT,
-      created_at INTEGER NOT NULL,
-      occurred_at INTEGER
-    );
-
-    CREATE INDEX IF NOT EXISTS ${prefix}events_entity_idx ON ${prefix}events(entity_id, created_at DESC);
-
-    CREATE TABLE IF NOT EXISTS ${prefix}checkpoints (
-      entity_id TEXT PRIMARY KEY,
-      heal_checkpoint INTEGER NOT NULL DEFAULT 0,
-      memory_checkpoint INTEGER NOT NULL DEFAULT 0,
-      librarian_watermark_at INTEGER,
-      librarian_watermark_id TEXT
-    );
-
-    CREATE TABLE IF NOT EXISTS ${prefix}entity_manifests (
-      entity_id TEXT PRIMARY KEY,
-      mode TEXT NOT NULL DEFAULT 'off',
-      manifest_json TEXT NOT NULL DEFAULT '{"node_types":[],"edge_types":[]}',
-      updated_at INTEGER NOT NULL
-    );
-
-    CREATE TABLE IF NOT EXISTS ${prefix}meta (
-      key TEXT PRIMARY KEY,
-      value TEXT NOT NULL
-    );
-
-    CREATE TABLE IF NOT EXISTS ${prefix}outbox (
-      id TEXT PRIMARY KEY,
-      entity_id TEXT NOT NULL,
-      table_name TEXT NOT NULL,
-      record_id TEXT NOT NULL,
-      operation TEXT NOT NULL,
-      payload TEXT NOT NULL,
-      created_at INTEGER NOT NULL
-    );
-
-    CREATE INDEX IF NOT EXISTS ${prefix}outbox_entity_id_created_at
-      ON ${prefix}outbox (entity_id, created_at);
-
-    CREATE INDEX IF NOT EXISTS ${prefix}outbox_created_at
-      ON ${prefix}outbox (created_at);
-  `);
-  await createOkfV02IndexesIfColumnsExist(db, prefix);
-  await createTemporalIndexesIfColumnsExist(db, prefix);
-}
-async function createOkfV02IndexesIfColumnsExist(db, prefix) {
-  for (const table of ["entries", "tasks"]) {
-    const cols = await db.getAllAsync(
-      `PRAGMA table_info(${prefix}${table})`
-    );
-    const colNames = new Set(cols.map((c) => c.name));
-    if (colNames.has("lifecycle_status")) {
-      await db.execAsync(`CREATE INDEX IF NOT EXISTS ${prefix}${table}_lifecycle_status_idx ON ${prefix}${table}(lifecycle_status);`);
-    }
-    if (colNames.has("stale_after")) {
-      await db.execAsync(`CREATE INDEX IF NOT EXISTS ${prefix}${table}_stale_after_idx ON ${prefix}${table}(stale_after);`);
-    }
-    if (colNames.has("last_verified_at")) {
-      await db.execAsync(`CREATE INDEX IF NOT EXISTS ${prefix}${table}_last_verified_at_idx ON ${prefix}${table}(last_verified_at);`);
+// src/db/migrationGate.ts
+var MIGRATION_POLICIES = ["allow", "refuse", "auto"];
+async function setupDatabaseWithGate(db, prefix, meta, migrations = "allow") {
+  if (!MIGRATION_POLICIES.includes(migrations)) {
+    throw new TypeError(`Invalid migrations policy ${JSON.stringify(migrations)}; expected 'allow', 'refuse' or 'auto'.`);
+  }
+  if (migrations !== "allow") {
+    const pending = await probePendingWork(db, meta, prefix);
+    if (pending && (migrations === "refuse" || pending.type === "schema_migration")) {
+      throw new WikiMigrationRequiredError(describePending(pending, migrations), pending);
     }
   }
+  return setupDatabase(db, prefix);
 }
-async function createTemporalIndexesIfColumnsExist(db, prefix) {
-  const cols = await db.getAllAsync(`PRAGMA table_info(${prefix}entries)`);
-  const names = new Set(cols.map((c) => c.name));
-  if (names.has("superseded_by")) {
-    await db.execAsync(
-      `CREATE INDEX IF NOT EXISTS ${prefix}entries_superseded_idx ON ${prefix}entries(entity_id, superseded_by) WHERE superseded_by IS NOT NULL;`
-    );
-  }
-  if (names.has("valid_from") && names.has("valid_to")) {
-    await db.execAsync(
-      `CREATE INDEX IF NOT EXISTS ${prefix}entries_temporal_idx ON ${prefix}entries(entity_id) WHERE valid_from IS NOT NULL OR valid_to IS NOT NULL;`
-    );
-  }
+function describePending(pending, policy) {
+  const what = pending.type === "schema_migration" ? `schema migration v${pending.fromVersion} -> v${pending.toVersion} is pending` : pending.entriesWatermark === 0 && pending.sourceRefIndexWatermark === 0 ? "source_ref normalize has not run on this store (normalize stamp missing or outdated; may complete with zero rewrites)" : "source_ref normalize was interrupted and will resume from its watermark";
+  return `Migration refused (migrations: '${policy}'): ${what}. Open once with setup({ migrations: 'allow' }) outside any time-critical path to complete it.`;
 }
 
 // src/db/serializedAdapter.ts
@@ -227,314 +65,6 @@ function withSerializedTransactions(db) {
     }
   });
 }
-
-// src/db/migrations.ts
-var MIGRATIONS = [
-  {
-    version: 1,
-    description: "Rebuild FTS5 with porter unicode61 tokenizer (superseded by v2)",
-    run: async (_db, _prefix) => {
-    }
-  },
-  {
-    version: 2,
-    description: "Remove FTS5; add embedding column for semantic retrieval",
-    run: async (db, prefix) => {
-      await db.withTransactionAsync(async (tx) => {
-        await tx.execAsync(`
-          DROP TRIGGER IF EXISTS ${prefix}entries_ai;
-          DROP TRIGGER IF EXISTS ${prefix}entries_ad;
-          DROP TRIGGER IF EXISTS ${prefix}entries_au;
-          DROP TABLE IF EXISTS ${prefix}entries_fts;
-        `);
-      });
-      const cols = await db.getAllAsync(
-        `PRAGMA table_info(${prefix}entries)`
-      );
-      if (!cols.some((c) => c.name === "embedding")) {
-        await db.execAsync(`ALTER TABLE ${prefix}entries ADD COLUMN embedding TEXT`);
-      }
-    }
-  },
-  {
-    version: 3,
-    description: "Add embedding_blob BLOB column for Float32Array vector storage",
-    run: async (db, prefix) => {
-      const cols = await db.getAllAsync(
-        `PRAGMA table_info(${prefix}entries)`
-      );
-      if (!cols.some((c) => c.name === "embedding_blob")) {
-        await db.execAsync(
-          `ALTER TABLE ${prefix}entries ADD COLUMN embedding_blob BLOB`
-        );
-      }
-    }
-  },
-  {
-    version: 4,
-    description: "Create outbox table for change data capture",
-    run: async (db, prefix) => {
-      await db.execAsync(`
-        CREATE TABLE IF NOT EXISTS ${prefix}outbox (
-          id TEXT PRIMARY KEY,
-          entity_id TEXT NOT NULL,
-          table_name TEXT NOT NULL,
-          record_id TEXT NOT NULL,
-          operation TEXT NOT NULL,
-          payload TEXT NOT NULL,
-          created_at INTEGER NOT NULL
-        );
-        CREATE INDEX IF NOT EXISTS ${prefix}outbox_entity_id_created_at
-          ON ${prefix}outbox (entity_id, created_at);
-      `);
-    }
-  },
-  {
-    version: 5,
-    description: "Add okf_type to entries/tasks for OKF type fidelity; create edges table for OKF graph import",
-    run: async (db, prefix) => {
-      for (const table of ["entries", "tasks"]) {
-        const cols = await db.getAllAsync(
-          `PRAGMA table_info(${prefix}${table})`
-        );
-        if (!cols.some((c) => c.name === "okf_type")) {
-          await db.execAsync(`ALTER TABLE ${prefix}${table} ADD COLUMN okf_type TEXT`);
-        }
-      }
-      await db.execAsync(`
-        CREATE TABLE IF NOT EXISTS ${prefix}edges (
-          id TEXT PRIMARY KEY,
-          entity_id TEXT NOT NULL,
-          source_id TEXT NOT NULL,
-          target_id TEXT NOT NULL,
-          edge_type TEXT NOT NULL,
-          created_at INTEGER NOT NULL,
-          UNIQUE(entity_id, source_id, target_id, edge_type)
-        );
-        CREATE INDEX IF NOT EXISTS ${prefix}edges_entity_idx ON ${prefix}edges (entity_id);
-      `);
-    }
-  },
-  {
-    version: 6,
-    description: "Add entity_manifests table for per-entity ontology state",
-    run: async (db, prefix) => {
-      await db.execAsync(`
-        CREATE TABLE IF NOT EXISTS ${prefix}entity_manifests (
-          entity_id TEXT PRIMARY KEY,
-          mode TEXT NOT NULL DEFAULT 'off',
-          manifest_json TEXT NOT NULL DEFAULT '{"node_types":[],"edge_types":[]}',
-          updated_at INTEGER NOT NULL
-        );
-      `);
-    }
-  },
-  {
-    version: 7,
-    description: "Add ontology_checked_at to entries for ontology backfill recheck cooldown",
-    run: async (db, prefix) => {
-      const cols = await db.getAllAsync(
-        `PRAGMA table_info(${prefix}entries)`
-      );
-      if (!cols.some((c) => c.name === "ontology_checked_at")) {
-        await db.execAsync(
-          `ALTER TABLE ${prefix}entries ADD COLUMN ontology_checked_at INTEGER`
-        );
-      }
-    }
-  },
-  {
-    version: 8,
-    description: "Add heal_checked_at to entries for heal recheck cooldown",
-    run: async (db, prefix) => {
-      const cols = await db.getAllAsync(
-        `PRAGMA table_info(${prefix}entries)`
-      );
-      if (!cols.some((c) => c.name === "heal_checked_at")) {
-        await db.execAsync(
-          `ALTER TABLE ${prefix}entries ADD COLUMN heal_checked_at INTEGER`
-        );
-      }
-    }
-  },
-  {
-    version: 9,
-    description: "add_source_ref_index",
-    run: async (db, prefix) => {
-      const duplicates = await db.getAllAsync(
-        `SELECT entity_id, source_hash, COUNT(DISTINCT source_ref) AS n_refs
-         FROM ${prefix}entries
-         WHERE deleted_at IS NULL AND source_hash IS NOT NULL
-         GROUP BY entity_id, source_hash
-         HAVING COUNT(DISTINCT source_ref) > 1`
-      );
-      if (duplicates.length > 0) {
-        const sample = duplicates.slice(0, 5).map((d) => `(entity_id=${d.entity_id}, source_hash=${d.source_hash.slice(0, 12)}\u2026, n_refs=${d.n_refs})`).join(", ");
-        throw new Error(
-          `Migration v9 (add_source_ref_index) failed: existing live rows have multiple sourceRefs sharing a hash. Found ${duplicates.length} duplicate (entity_id, source_hash) groups. First ${Math.min(5, duplicates.length)}: ${sample}. Resolve each by calling forget({ sourceRef: <loser> }) for the offending sourceRef, then re-run setup.`
-        );
-      }
-      await db.execAsync(
-        `CREATE TABLE IF NOT EXISTS ${prefix}source_ref_index (
-          id TEXT PRIMARY KEY,
-          entity_id TEXT NOT NULL,
-          source_hash TEXT NOT NULL,
-          source_ref TEXT NOT NULL,
-          created_at INTEGER NOT NULL,
-          deleted_at INTEGER
-        );
-        CREATE UNIQUE INDEX IF NOT EXISTS ${prefix}idx_source_ref_hash
-          ON ${prefix}source_ref_index (entity_id, source_hash)
-          WHERE deleted_at IS NULL;`
-      );
-      await db.execAsync(
-        `INSERT OR IGNORE INTO ${prefix}source_ref_index (id, entity_id, source_hash, source_ref, created_at, deleted_at)
-         SELECT
-           'sri:' || entity_id || ':' || source_hash,
-           entity_id,
-           source_hash,
-           source_ref,
-           updated_at,
-           NULL
-         FROM (
-           SELECT
-             entity_id, source_hash, source_ref, updated_at,
-             ROW_NUMBER() OVER (
-               PARTITION BY entity_id, source_hash
-               ORDER BY updated_at ASC, id ASC
-             ) AS rn
-           FROM ${prefix}entries
-           WHERE deleted_at IS NULL
-             AND source_hash IS NOT NULL
-             AND source_ref IS NOT NULL
-         ) ranked
-         WHERE rn = 1;`
-      );
-    }
-  },
-  {
-    version: 10,
-    description: "OKF v0.2: add lifecycle_status, stale_after, generated_by, last_verified_*, okf_sources, okf_verified, okf_usage_window to entries and tasks",
-    run: async (db, prefix) => {
-      for (const table of ["entries", "tasks"]) {
-        const cols = await db.getAllAsync(
-          `PRAGMA table_info(${prefix}${table})`
-        );
-        const existing = new Set(cols.map((c) => c.name));
-        const adds = [
-          ["lifecycle_status", `ALTER TABLE ${prefix}${table} ADD COLUMN lifecycle_status TEXT NOT NULL DEFAULT 'stable'`],
-          ["stale_after", `ALTER TABLE ${prefix}${table} ADD COLUMN stale_after INTEGER`],
-          ["generated_by", `ALTER TABLE ${prefix}${table} ADD COLUMN generated_by TEXT`],
-          ["last_verified_at", `ALTER TABLE ${prefix}${table} ADD COLUMN last_verified_at INTEGER`],
-          ["last_verified_by", `ALTER TABLE ${prefix}${table} ADD COLUMN last_verified_by TEXT`],
-          ["okf_sources", `ALTER TABLE ${prefix}${table} ADD COLUMN okf_sources TEXT`],
-          ["okf_verified", `ALTER TABLE ${prefix}${table} ADD COLUMN okf_verified TEXT`],
-          ["okf_usage_window", `ALTER TABLE ${prefix}${table} ADD COLUMN okf_usage_window TEXT`]
-        ];
-        for (const [name, sql] of adds) {
-          if (!existing.has(name)) await db.execAsync(sql);
-        }
-      }
-      await db.execAsync(`
-        CREATE INDEX IF NOT EXISTS ${prefix}entries_lifecycle_status_idx ON ${prefix}entries(lifecycle_status);
-        CREATE INDEX IF NOT EXISTS ${prefix}entries_stale_after_idx ON ${prefix}entries(stale_after);
-        CREATE INDEX IF NOT EXISTS ${prefix}entries_last_verified_at_idx ON ${prefix}entries(last_verified_at);
-        CREATE INDEX IF NOT EXISTS ${prefix}tasks_lifecycle_status_idx ON ${prefix}tasks(lifecycle_status);
-        CREATE INDEX IF NOT EXISTS ${prefix}tasks_stale_after_idx ON ${prefix}tasks(stale_after);
-        CREATE INDEX IF NOT EXISTS ${prefix}tasks_last_verified_at_idx ON ${prefix}tasks(last_verified_at);
-      `);
-    }
-  },
-  {
-    version: 11,
-    description: "Add embedding_failed_at, embedding_failure_kind, embedding_attempts to entries for embed retry state",
-    run: async (db, prefix) => {
-      const cols = await db.getAllAsync(
-        `PRAGMA table_info(${prefix}entries)`
-      );
-      const existing = new Set(cols.map((c) => c.name));
-      const adds = [
-        ["embedding_failed_at", `ALTER TABLE ${prefix}entries ADD COLUMN embedding_failed_at INTEGER`],
-        ["embedding_failure_kind", `ALTER TABLE ${prefix}entries ADD COLUMN embedding_failure_kind TEXT`],
-        ["embedding_attempts", `ALTER TABLE ${prefix}entries ADD COLUMN embedding_attempts INTEGER NOT NULL DEFAULT 0`]
-      ];
-      for (const [name, sql] of adds) {
-        if (!existing.has(name)) await db.execAsync(sql);
-      }
-    }
-  },
-  {
-    version: 12,
-    description: "Replace edges_entity_idx with composite edges(entity_id, id) for keyset paging",
-    run: async (db, prefix) => {
-      await db.execAsync(`
-        CREATE INDEX IF NOT EXISTS ${prefix}edges_entity_id_idx ON ${prefix}edges(entity_id, id);
-        DROP INDEX IF EXISTS ${prefix}edges_entity_idx;
-      `);
-    }
-  },
-  {
-    version: 13,
-    description: "Temporal facts: valid_from/valid_to/superseded_by/superseded_at on entries, occurred_at on events, librarian watermark on checkpoints",
-    run: async (db, prefix) => {
-      const adds = [
-        ["entries", "valid_from", "INTEGER"],
-        ["entries", "valid_to", "INTEGER"],
-        ["entries", "superseded_by", "TEXT"],
-        ["entries", "superseded_at", "INTEGER"],
-        ["events", "occurred_at", "INTEGER"],
-        ["checkpoints", "librarian_watermark_at", "INTEGER"],
-        ["checkpoints", "librarian_watermark_id", "TEXT"]
-      ];
-      const existingByTable = /* @__PURE__ */ new Map();
-      for (const [table, column, type] of adds) {
-        let existing = existingByTable.get(table);
-        if (!existing) {
-          const cols = await db.getAllAsync(`PRAGMA table_info(${prefix}${table})`);
-          existing = new Set(cols.map((c) => c.name));
-          existingByTable.set(table, existing);
-        }
-        if (!existing.has(column)) {
-          await db.execAsync(`ALTER TABLE ${prefix}${table} ADD COLUMN ${column} ${type}`);
-          existing.add(column);
-        }
-      }
-      await createTemporalIndexesIfColumnsExist(db, prefix);
-    }
-  }
-];
-for (let i = 1; i < MIGRATIONS.length; i++) {
-  if (MIGRATIONS[i].version <= MIGRATIONS[i - 1].version) {
-    throw new Error(
-      `migrations.ts: MIGRATIONS must be in strictly ascending version order. Found version ${MIGRATIONS[i].version} after ${MIGRATIONS[i - 1].version} at index ${i}.`
-    );
-  }
-}
-var CURRENT_SCHEMA_VERSION = MIGRATIONS.length > 0 ? MIGRATIONS[MIGRATIONS.length - 1].version : 0;
-
-// src/repositories/rowMappers.ts
-function parseJsonArray(s, fallback) {
-  if (Array.isArray(s)) return s;
-  if (typeof s === "string" && s.length > 0) {
-    try {
-      const p = JSON.parse(s);
-      if (Array.isArray(p)) return p;
-    } catch {
-    }
-  }
-  return fallback;
-}
-function parseJsonObject(s, fallback = null) {
-  if (s && typeof s === "object" && !Array.isArray(s)) return s;
-  if (typeof s === "string" && s.length > 0) {
-    try {
-      const p = JSON.parse(s);
-      if (p && typeof p === "object" && !Array.isArray(p)) return p;
-    } catch {
-    }
-  }
-  return fallback;
-}
 function mapRowToFact(row) {
   const tags = (() => {
     if (Array.isArray(row.tags)) return row.tags;
@@ -612,6 +142,15 @@ var _EntryRepository = class _EntryRepository extends BaseRepository {
     this.outbox = outbox;
     this.chunkSize = 500;
   }
+  /** Whether the entity has any non-deleted row (librarian gate: keyword ranking over zero facts is trivially empty). */
+  async hasLiveEntry(entityId, tx) {
+    const executor = this.getExecutor(tx);
+    const row = await executor.getFirstAsync(
+      `SELECT 1 AS one FROM ${this.prefix}entries WHERE entity_id = ? AND deleted_at IS NULL LIMIT 1`,
+      [entityId]
+    );
+    return row != null;
+  }
   /**
    * Fetch facts by IDs, optionally scoped to entity IDs.
    * Returns facts in the order of the input IDs (first match wins).
@@ -1156,6 +695,7 @@ var _EntryRepository = class _EntryRepository extends BaseRepository {
         }
       }
     }
+    if (totalChanges > 0) await reanchorRebuildFingerprint(executor, this.prefix, ids);
     return totalChanges;
   }
   /**
@@ -1498,27 +1038,6 @@ var _EntryRepository = class _EntryRepository extends BaseRepository {
       `SELECT * FROM ${this.prefix}entries WHERE deleted_at IS NULL`
     );
   }
-  async findRowsForSourceRefMigration(tx) {
-    const executor = this.getExecutor(tx);
-    return executor.getAllAsync(
-      `SELECT rowid, source_ref FROM ${this.prefix}entries
-       WHERE source_ref IS NOT NULL
-         AND (
-           TRIM(source_ref) != source_ref
-           OR INSTR(source_ref, '/') > 0
-           OR INSTR(source_ref, '\\') > 0
-           OR INSTR(source_ref, CHAR(0)) > 0
-           OR source_ref GLOB '*[^-A-Za-z0-9._ ]*'
-         )`
-    );
-  }
-  async updateSourceRefByRowid(rowid, sourceRef, tx) {
-    const executor = this.getExecutor(tx);
-    await executor.runAsync(
-      `UPDATE ${this.prefix}entries SET source_ref = ? WHERE rowid = ?`,
-      [sourceRef, rowid]
-    );
-  }
   async findLatestSourceHash(entityId, sourceRef, tx) {
     const executor = this.getExecutor(tx);
     const row = await executor.getFirstAsync(
@@ -2994,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;
@@ -3087,40 +2530,362 @@ 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;
+  }
+  /** 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]);
+      });
+    }
   }
-  async drain() {
+  /** One seq-ordered chunk. False when the ledger was empty. */
+  async drainLedgerChunk() {
     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;
-      });
-      if (done) return;
-    }
+    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);
@@ -3199,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) {
@@ -3222,14 +3024,34 @@ function assertEntity(entityId, documents) {
 }
 
 // src/services/search/createIndexStrategy.ts
+var FTS5_INIT_RETRY_MS = 250;
+function isModuleAbsentError(err) {
+  let cur = err;
+  for (let depth = 0; depth < 3 && cur != null; depth++) {
+    let msg = "";
+    try {
+      msg = String(cur.message ?? cur);
+    } catch {
+      return false;
+    }
+    if (/no such module: fts5/i.test(msg) || /no such function: json_valid/i.test(msg)) return true;
+    try {
+      cur = cur.cause;
+    } catch {
+      return false;
+    }
+  }
+  return false;
+}
 async function probeFts5(db, prefix) {
   const name = `temp.${prefix}fts5_probe`;
   try {
     await db.execAsync(`CREATE VIRTUAL TABLE IF NOT EXISTS ${name} USING fts5(x)`);
     const row = await db.getFirstAsync(`SELECT json_valid('[]') AS ok`);
     return row?.ok === 1;
-  } catch {
-    return false;
+  } catch (err) {
+    if (isModuleAbsentError(err)) return false;
+    throw err;
   } finally {
     try {
       await db.execAsync(`DROP TABLE IF EXISTS ${name}`);
@@ -3250,23 +3072,37 @@ async function detachFts5(db, prefix, metadataRepo) {
   } catch {
   }
 }
-async function createIndexStrategy(db, prefix, metadataRepo, preferred) {
-  if (preferred !== "minisearch") {
-    if (await probeFts5(db, prefix)) {
-      const strategy = new Fts5IndexStrategy(db, prefix, metadataRepo);
-      try {
-        await strategy.init();
-        return strategy;
-      } catch (err) {
-        if (preferred === "fts5") throw err;
-        console.warn("[WikiMemory] FTS5 init failed; falling back to MiniSearch:", err);
-      }
-    } else if (preferred === "fts5") {
+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, opts.setupBudgetMs);
+    await strategy.init({ entriesExisted: opts.entriesExisted });
+    return strategy;
+  };
+  const absent = async () => {
+    if (preferred === "fts5") {
       throw new Error(`indexStrategy 'fts5' was requested, but this SQLite build lacks FTS5 or json1.`);
     }
+    await detachFts5(db, prefix, metadataRepo);
+    return new MiniSearchIndexStrategy();
+  };
+  for (let tries = 1; ; tries++) {
+    try {
+      const s = await attempt();
+      return s === "absent" ? await absent() : s;
+    } catch (err) {
+      if (preferred === "fts5") throw err;
+      if (tries === 2) {
+        console.warn("[WikiMemory] FTS5 init failed after retry; keyword search unavailable until a later open or syncSearchIndex():", err);
+        return new UnavailableIndexStrategy(err);
+      }
+    }
+    await new Promise((resolve) => setTimeout(resolve, FTS5_INIT_RETRY_MS));
   }
-  await detachFts5(db, prefix, metadataRepo);
-  return new MiniSearchIndexStrategy();
 }
 
 // src/services/MaintenanceScheduler.ts
@@ -3350,8 +3186,14 @@ var MaintenanceScheduler = class {
       var _a;
       ((_a = st.report).busy ?? (_a.busy = [])).push(job);
     };
+    const markSearchUnavailable = (st, job) => {
+      var _a;
+      ((_a = st.report).searchUnavailable ?? (_a.searchUnavailable = [])).push(job);
+    };
+    const openJobs = () => states.reduce((n, s) => n + +s.librarian + +s.heal + +s.reembed, 0);
     rounds: for (; ; ) {
       let progressed = false;
+      const openAtStart = openJobs();
       for (const st of states) {
         if (!st.librarian && !st.heal && !st.reembed) continue;
         if (Date.now() >= deadline) {
@@ -3369,6 +3211,11 @@ var MaintenanceScheduler = class {
           let r;
           try {
             r = await this.maintenanceService.runLibrarianPass({ entityId, trigger: "call", meter });
+          } catch (err) {
+            if (!isWikiSearchUnavailableError(err)) throw err;
+            st.librarian = false;
+            markSearchUnavailable(st, "librarian");
+            continue;
           } finally {
             this.jobManager.releaseLock("librarian", entityId);
           }
@@ -3412,6 +3259,11 @@ var MaintenanceScheduler = class {
             st.heal = false;
             continue;
           }
+          if (h.scanned === 0 && h.remaining > 0) {
+            st.heal = false;
+            if (h.searchUnavailable) markSearchUnavailable(st, "heal");
+            continue;
+          }
           st.report.healPasses++;
           progressed = true;
           if (h.remaining === 0) {
@@ -3436,7 +3288,7 @@ var MaintenanceScheduler = class {
           }
         }
       }
-      if (!progressed) break;
+      if (!progressed && openJobs() === openAtStart) break;
     }
     if (stopped.reason === "complete" && tooSmall) stopped = tooSmall;
     return {
@@ -3937,6 +3789,9 @@ var OkfTrustWritesRepository = class {
 
 // src/WikiMemory.ts
 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;
 function decodeDraftCursor(cursor) {
   const sep = typeof cursor === "string" ? cursor.indexOf(":") : -1;
   const createdAt = sep > 0 ? Number(cursor.slice(0, sep)) : Number.NaN;
@@ -3951,6 +3806,21 @@ 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;
+    /** Consecutive failed re-inits; drives the exponential backoff. */
+    this.reinitFailures = 0;
     this.db = withSerializedTransactions(db);
     this.options = options;
     this.prefix = options.config?.tablePrefix ?? "llm_wiki_";
@@ -4082,23 +3952,81 @@ var WikiMemory = class {
       jobManager: this.jobManager
     };
   }
-  async setup() {
+  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
+   * normalize commits in chunks, so a sourceRef-keyed call (forget, upsertGraph,
+   * hasChanged, ingest) issued before setup() resolves can see partially
+   * normalized refs.
+   *
+   * 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`);
-    await setupDatabase(this.db, this.prefix);
+    const migrationPolicy = opts?.migrations ?? this.options.config?.migrations ?? "allow";
+    await setupDatabaseWithGate(this.db, this.prefix, this.metadataRepo, migrationPolicy);
     let currentVersion;
     if (!entriesExistedBeforeSetup) {
-      await this.metadataRepo.setMeta("schema_version", String(CURRENT_SCHEMA_VERSION), this.db);
+      await this.db.withTransactionAsync(async (tx) => {
+        await createLegacySourceTypeIndex(tx, this.prefix);
+        await writeNormalizeStamp(this.metadataRepo, tx);
+        await this.metadataRepo.setMeta("schema_version", String(CURRENT_SCHEMA_VERSION), tx);
+      });
       currentVersion = CURRENT_SCHEMA_VERSION;
     } else {
-      const schemaVersionValue = await this.metadataRepo.getMeta("schema_version");
-      if (schemaVersionValue) {
-        currentVersion = parseInt(schemaVersionValue, 10);
-        if (!Number.isFinite(currentVersion)) currentVersion = 0;
-      } else {
-        const ftsDdl = await this.metadataRepo.getTableDdl(`${this.prefix}entries_fts`);
-        const hasPorter = /tokenize\s*=\s*['"]porter\s+unicode61['"]/i.test(ftsDdl ?? "");
-        currentVersion = hasPorter ? 1 : 0;
-      }
+      currentVersion = await detectSchemaVersion(this.metadataRepo, this.prefix);
     }
     for (const migration of MIGRATIONS) {
       if (migration.version > currentVersion) {
@@ -4112,28 +4040,19 @@ var WikiMemory = class {
       if (!schemaVersionCheck) {
         await this.metadataRepo.setMeta("schema_version", String(currentVersion), this.db);
       }
-    }
-    if (entriesExistedBeforeSetup) {
       await this.importExportService.assertNoLegacySourceTypes();
+      await runSourceRefNormalize(this.db, this.prefix, this.metadataRepo);
     }
-    const rows = await this.entryRepo.findRowsForSourceRefMigration();
-    await this.db.withTransactionAsync(async (tx) => {
-      for (const row of rows) {
-        const normalized = normalizeSourceRef(row.source_ref);
-        if (normalized !== row.source_ref) {
-          await this.entryRepo.updateSourceRefByRowid(row.rowid, normalized, tx);
-        }
-      }
-    });
     this.searchService.setIndexStrategy(
       await createIndexStrategy(
         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") {
@@ -4384,11 +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.
+   * 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
@@ -4405,9 +4331,53 @@ var WikiMemory = class {
    * @throws {TypeError} when `entityId` is given but is not a non-empty string.
    */
   async syncSearchIndex(entityId) {
-    if (entityId === void 0) return this.searchService.syncStale();
+    if (entityId === void 0) {
+      if (!this.searchService.isKeywordAvailable() && monotonicNow() >= this.reinitRetryAt) {
+        this.reinitSearch ?? (this.reinitSearch = (async () => {
+          const started = monotonicNow();
+          try {
+            const strategy = await createIndexStrategy(
+              this.db,
+              this.prefix,
+              this.metadataRepo,
+              this.options.config?.indexStrategy ?? "auto",
+              { setupBudgetMs: this.setupBudgetMs() }
+            );
+            this.searchService.setIndexStrategy(strategy);
+            if (this.searchService.isKeywordAvailable() && !this.searchService.hasLedger()) await this.searchService.sync();
+          } finally {
+            if (this.searchService.isKeywordAvailable()) {
+              this.reinitFailures = 0;
+              this.reinitRetryAt = 0;
+            } else {
+              const now = monotonicNow();
+              const backoff = Math.min(SEARCH_REINIT_COOLDOWN_MS * 2 ** this.reinitFailures, SEARCH_REINIT_COOLDOWN_MAX_MS);
+              this.reinitFailures++;
+              this.reinitRetryAt = now + Math.max(backoff, SEARCH_REINIT_COST_FACTOR * (now - started));
+            }
+            this.reinitSearch = null;
+          }
+        })());
+        await this.reinitSearch;
+      }
+      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);
@@ -4458,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`).
    *
@@ -4508,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;
@@ -4696,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.");
@@ -5621,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