@equationalapplications/core-llm-wiki 7.11.2 → 7.13.0

package/dist/testing.js

@@ -38,6 +38,8 @@ var SQLITE_RESULT_CODE_NAMES = {
   // prefix and we normalize it back to the symbolic name so callers can branch on
   // the same string the rest of the ecosystem uses.
   2067: "SQLITE_CONSTRAINT_UNIQUE",
+  // 267 = SQLITE_CORRUPT_VTAB — a corrupt FTS5 shadow table (ftsCorruptionClass).
+  267: "SQLITE_CORRUPT_VTAB",
   100: "SQLITE_ROW",
   101: "SQLITE_DONE"
 };
@@ -157,6 +159,19 @@ var WikiSupersedeError = class _WikiSupersedeError extends Error {
     Object.setPrototypeOf(this, _WikiSupersedeError.prototype);
   }
 };
+var WikiSearchUnavailableError = class extends Error {
+  constructor(message = "Keyword search is temporarily unavailable", cause) {
+    super(message, cause !== void 0 ? { cause } : void 0);
+    this.name = "WikiSearchUnavailableError";
+  }
+};
+function isWikiSearchUnavailableError(err) {
+  try {
+    return err instanceof WikiSearchUnavailableError;
+  } catch {
+    return false;
+  }
+}
 
 // src/utils/pure.ts
 var MAX_REPAIR_CANDIDATES = 5;
@@ -655,7 +670,7 @@ function taskRejectionReason(raw) {
 }
 function normalizeSourceRef(value) {
   if (typeof value !== "string") return null;
-  const cleaned = value.replace(/[^A-Za-z0-9._\- ]/g, "").trim().slice(0, 255);
+  const cleaned = value.replace(/[^A-Za-z0-9._\- ]/g, "").trim().slice(0, 255).trimEnd();
   return cleaned.length > 0 ? cleaned : null;
 }
 function normalizeSourceHash(value) {
@@ -708,7 +723,7 @@ var MESSAGE = {
   embedding_failed: "A fact could not be embedded.",
   hook_failed: "A host hook threw or rejected.",
   background_job_failed: "A background maintenance job failed.",
-  heal_skipped: "Heal skipped a candidate fact.",
+  heal_skipped: "Heal skipped a candidate fact, or the whole LLM pass when keyword search is unavailable.",
   grounding_missing: "A fact carried no qualifying evidence and was stored as a draft.",
   grounding_failed: "A fact carried evidence not found in its source and was stored as a draft.",
   classification_low_confidence: "A classifier answer was below the confidence threshold and was not applied.",
@@ -1394,7 +1409,7 @@ var ImportExportService = class {
     if (merge) {
       await this.searchService.syncEntries(entityId, [...upsertedFactIds]);
     } else {
-      await this.searchService.sync(entityId);
+      await this.searchService.sync(entityId, { ids: [.../* @__PURE__ */ new Set([...upsertedFactIds, ...softDeletedFactIds])] });
     }
     for (const fact of bundle.facts) {
       if (!fact.deleted_at && upsertedFactIds.has(fact.id) && !factsWithPreservedBlob.has(fact.id)) {
@@ -2327,7 +2342,8 @@ var IngestionService = class {
    *
    * @returns Counts: nodesWritten (validated nodes persisted), edgesWritten
    *   (manifest-valid edges persisted), superseded (prior facts soft-deleted
-   *   plus prior source-ref edges hard-deleted).
+   *   plus prior source-ref edges hard-deleted), and supersededFactIds (the
+   *   ids of those soft-deleted facts, for the caller's post-commit index sync).
    *
    * Node-ownership pre-flight (spec §3, REQ-GRAPH-01): the first statement
    * is `assertGraphNodeOwnership(entityId, params.nodes, tx)`, which runs
@@ -2340,6 +2356,9 @@ var IngestionService = class {
    * ordering and counts so success counts match the pre-change contract.
    */
   async upsertGraphCore(entityId, params, tx, opts) {
+    const sourceRef = normalizeSourceRef(params.sourceRef);
+    if (!sourceRef) throw new Error("Invalid sourceRef");
+    params = { ...params, sourceRef };
     await this.assertGraphNodeOwnership(entityId, params.nodes, tx);
     const now = Date.now();
     const ontologyState = await this.ontologyService?.getEffectiveState(entityId, tx) ?? { mode: "off", manifest: { node_types: [], edge_types: [] } };
@@ -2452,7 +2471,8 @@ var IngestionService = class {
     return {
       nodesWritten: wikiFacts.length,
       edgesWritten: edgesInsertedCount,
-      superseded: deletedFactIds.length + deletedEdgeCount
+      superseded: deletedFactIds.length + deletedEdgeCount,
+      supersededFactIds: deletedFactIds
     };
   }
   /**
@@ -2850,6 +2870,363 @@ async function runBatched(args) {
   return { results, skipped, batches, unattempted, ...budgetStop ? { budgetStop } : {} };
 }
 
+// src/db/schema.ts
+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;`
+    );
+  }
+}
+
+// src/services/search/fts5Sql.ts
+var FTS5_STATE_KEY = "fts5_index_state";
+var FTS5_REBUILD_WM_KEY = "fts5_rebuild_wm";
+var FTS5_REBUILD_SNAPSHOT_KEY = "fts5_rebuild_snapshot";
+var FTS5_SWEEP_CURSOR_KEY = "fts5_orphan_sweep_cursor";
+function fts5PendingIndexesDdl(p) {
+  return `
+CREATE INDEX IF NOT EXISTS ${p}fts_pending_id ON ${p}fts_pending(id);
+CREATE INDEX IF NOT EXISTS ${p}fts_pending_entity ON ${p}fts_pending(entity_id);`;
+}
+
+// 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);
+    }
+  },
+  {
+    version: 14,
+    description: "Partial index for the every-open legacy source_type probe",
+    run: async (db, prefix) => {
+      await createLegacySourceTypeIndex(db, prefix);
+    }
+  },
+  {
+    version: 15,
+    description: "fts_pending(id) and fts_pending(entity_id) indexes for the ids-first and entity-targeted drains",
+    run: async (db, prefix) => {
+      const row = await db.getFirstAsync(
+        `SELECT count(*) AS n FROM sqlite_master WHERE type = 'table' AND name = ?`,
+        [`${prefix}fts_pending`]
+      );
+      if (row?.n) await db.execAsync(fts5PendingIndexesDdl(prefix));
+    }
+  }
+];
+async function createLegacySourceTypeIndex(db, prefix) {
+  await db.execAsync(
+    `CREATE INDEX IF NOT EXISTS ${prefix}entries_legacy_source_type_idx ON ${prefix}entries(source_type) WHERE source_type IN ('user_document', 'agent_inferred')`
+  );
+}
+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}.`
+    );
+  }
+}
+MIGRATIONS.length > 0 ? MIGRATIONS[MIGRATIONS.length - 1].version : 0;
+
+// src/db/sourceRefNormalize.ts
+var ENTRIES_WM_KEY = "normalize_v14_entries_wm";
+var SRI_WM_KEY = "normalize_v14_sri_wm";
+async function resetNormalizeWatermarks(meta) {
+  await meta.deleteMeta(ENTRIES_WM_KEY);
+  await meta.deleteMeta(SRI_WM_KEY);
+}
+
+// src/services/search/fts5Progress.ts
+async function writeRebuildStart(tx, prefix, meta) {
+  const e = await tx.getFirstAsync(`SELECT coalesce(max(rowid), 0) AS hi FROM ${prefix}entries`);
+  const m = await tx.getFirstAsync(`SELECT coalesce(max(fts_rowid), 0) AS hi FROM ${prefix}fts_map`);
+  await meta.setMeta(FTS5_REBUILD_WM_KEY, JSON.stringify({ rowid: 0, id: null }), tx);
+  await meta.setMeta(FTS5_REBUILD_SNAPSHOT_KEY, JSON.stringify({ entries: e?.hi ?? 0, map: m?.hi ?? 0 }), tx);
+  await meta.setMeta(FTS5_SWEEP_CURSOR_KEY, "0", tx);
+}
+async function restartRebuildAfterVacuum(db, prefix, meta) {
+  await db.withTransactionAsync(async (tx) => {
+    if (await meta.getMeta(FTS5_STATE_KEY, tx) !== "rebuilding") return;
+    await writeRebuildStart(tx, prefix, meta);
+  });
+}
+
 // src/services/librarian/constants.ts
 var FUZZY_THRESHOLD = 0.5;
 var MIN_TOKENS_TO_QUALIFY = 3;
@@ -3147,6 +3524,22 @@ function classifyCandidate(candidate, neighbours, cfg, mode) {
   if (score < cfg.novelThreshold) return { kind: "add" };
   return { kind: "ambiguous" };
 }
+async function loadStoredVectors(deps, entityId, nonLive) {
+  const stored = [];
+  for (const row of await deps.entryRepo.findWithEmbeddingsByEntityIds([entityId])) {
+    if (nonLive.has(row.id)) continue;
+    const vec = parseEmbedding(row.embedding_blob, row.embedding);
+    if (vec) stored.push({ id: row.id, vec });
+  }
+  return stored;
+}
+async function gateNeedsKeyword(deps, entityId) {
+  if (!await deps.entryRepo.hasLiveEntry(entityId)) return false;
+  if (typeof deps.options.llmProvider.embed !== "function") return true;
+  const nonLive = await deps.entryRepo.findNonLiveIdsByEntityIds([entityId], "current", Date.now());
+  const stored = await loadStoredVectors(deps, entityId, nonLive);
+  return stored.length === 0 || stored.some((s) => s.vec.length !== stored[0].vec.length);
+}
 async function gateCandidates(deps, ctx, candidates, cfg) {
   const { entityId, trigger } = ctx;
   const seen = /* @__PURE__ */ new Set();
@@ -3162,14 +3555,8 @@ async function gateCandidates(deps, ctx, candidates, cfg) {
   }
   const nonLive = await deps.entryRepo.findNonLiveIdsByEntityIds([entityId], "current", Date.now());
   const canEmbed = typeof deps.options.llmProvider.embed === "function";
-  const stored = [];
-  if (canEmbed && unique.length > 0) {
-    for (const row of await deps.entryRepo.findWithEmbeddingsByEntityIds([entityId])) {
-      if (nonLive.has(row.id)) continue;
-      const vec = parseEmbedding(row.embedding_blob, row.embedding);
-      if (vec) stored.push({ id: row.id, vec });
-    }
-  }
+  const stored = canEmbed && unique.length > 0 ? await loadStoredVectors(deps, entityId, nonLive) : [];
+  const hasFacts = unique.length > 0 && await deps.entryRepo.hasLiveEntry(entityId);
   const gated = [];
   for (const c of unique) {
     let ranked = null;
@@ -3190,7 +3577,7 @@ async function gateCandidates(deps, ctx, candidates, cfg) {
       }
     }
     if (!ranked) {
-      ranked = (await deps.searchService.searchKeyword(`${c.fact.title} ${c.fact.body}`, [entityId], cfg.k + nonLive.size)).filter((h) => !nonLive.has(h.id)).slice(0, cfg.k).map((h) => ({ id: h.id, score: null }));
+      ranked = hasFacts ? (await deps.searchService.searchKeyword(`${c.fact.title} ${c.fact.body}`, [entityId], cfg.k + nonLive.size)).filter((h) => !nonLive.has(h.id)).slice(0, cfg.k).map((h) => ({ id: h.id, score: null })) : [];
     }
     const facts = ranked.length > 0 ? await deps.entryRepo.findByIds(ranked.map((r) => r.id), [entityId]) : [];
     const byId = new Map(facts.map((f) => [f.id, f]));
@@ -3541,6 +3928,9 @@ var runOpsLibrarianPass = async (deps, ctx) => {
   const sel = await selectBatch(deps, entityId, wm, ctx.meter);
   if ("budgetStop" in sel) return { processedThrough: null, factsWritten: 0, budgetStop: sel.budgetStop };
   if (sel.batch.length === 0) return { processedThrough: null, factsWritten: 0 };
+  if (!deps.searchService.isKeywordAvailable() && await gateNeedsKeyword(deps, entityId)) {
+    throw new WikiSearchUnavailableError("librarian: keyword search unavailable and this pass may need it; retry the pass");
+  }
   let ex;
   try {
     ex = await runExtract(deps, ctx, sel.batch);
@@ -3770,7 +4160,9 @@ var MaintenanceService = class {
         }
       }
       if (vacuum) {
+        await resetNormalizeWatermarks(this.metadataRepo);
         await this.metadataRepo.vacuum();
+        await restartRebuildAfterVacuum(this.db, this.prefix, this.metadataRepo);
       }
       await this.searchService.syncEntries(entityId, syncedIds);
       return { entries: deletedEntries, tasks: deletedTasks, events: deletedEvents };
@@ -4069,7 +4461,8 @@ var MaintenanceService = class {
    *
    * Bounded: at most `batchSize` candidates per pass (#67). Loop on
    * `result.remaining > 0` for convergence — see {@link HealResult.remaining}
-   * for what convergence means here.
+   * for what convergence means here, and for the no-progress flags
+   * (`searchUnavailable`, `budgetStop`) a loop must also stop on.
    */
   async doRunHeal(entityId, options) {
     const promptOverride = options?.promptOverride;
@@ -4115,7 +4508,11 @@ var MaintenanceService = class {
       }
     }
     const healCandidates = await this.entryRepo.findHealCandidatesByEntityId(entityId, batchSize, recheckCutoff);
-    if (healCandidates.length === 0) {
+    const keywordUnavailable = healCandidates.length > 0 && !this.searchService.isKeywordAvailable();
+    if (healCandidates.length === 0 || keywordUnavailable) {
+      if (keywordUnavailable) {
+        emitDiagnostic(this.options, { ...diagBase, code: "heal_skipped", detail: { reason: "keyword_search_unavailable", count: healCandidates.length } });
+      }
       await this.searchService.syncEntries(entityId, Array.from(/* @__PURE__ */ new Set([...orphanedIds, ...staleDowngradedIds])));
       this.searchService.evictCache(entityId);
       const counts2 = await this.entryRepo.countHealCandidatesByEntityId(entityId, recheckCutoff);
@@ -4127,7 +4524,10 @@ var MaintenanceService = class {
         skipped: [],
         degraded: [],
         remaining: counts2.eligible,
-        deferred: counts2.deferred
+        deferred: counts2.deferred,
+        // remaining stays > 0 so maybeRunHeal holds the checkpoint back and
+        // retries after the outage; the flag lets a host loop stop instead.
+        ...keywordUnavailable ? { searchUnavailable: true } : {}
       };
     }
     const allTasks = await this.taskRepo.findAllPending([entityId], HEAL_MAX_TASKS);
@@ -4931,7 +5331,12 @@ var RetrievalService = class {
               candidateRows = this._withoutIds(await this.entryRepo.findWithEmbeddingsByEntityIds(scoredEntityIds), excludedIds);
             }
             if (weight !== void 0 && weight < 1) {
-              miniSearchScores = await this.searchService.getKeywordScores(trimmedQuery, scoredEntityIds);
+              try {
+                miniSearchScores = await this.searchService.getKeywordScores(trimmedQuery, scoredEntityIds);
+              } catch (err) {
+                if (!isWikiSearchUnavailableError(err)) throw err;
+                miniSearchScores = /* @__PURE__ */ new Map();
+              }
             }
           }
           if (candidateRows === null) {
@@ -5433,6 +5838,28 @@ function toIndexDoc(row) {
   };
 }
 
+// src/services/search/UnavailableIndexStrategy.ts
+var UnavailableIndexStrategy = class {
+  constructor(cause) {
+    this.cause = cause;
+  }
+  async search(_query, options) {
+    if (options.entityIds.length === 0) return [];
+    throw new WikiSearchUnavailableError(void 0, this.cause);
+  }
+  async replace(_entityId, _ids, _documents) {
+  }
+  async replaceEntity(_entityId, _documents) {
+  }
+  async replaceAll(_documents) {
+  }
+  hasIndexedEntity(_entityId) {
+    return false;
+  }
+  async drain(_opts) {
+  }
+};
+
 // src/services/SearchService.ts
 var _SearchService = class _SearchService {
   constructor(entryRepo, indexStrategy) {
@@ -5471,24 +5898,35 @@ var _SearchService = class _SearchService {
   setIndexStrategy(strategy) {
     this.indexStrategy = strategy;
   }
+  /** False while the installed strategy is the degraded UnavailableIndexStrategy (spec #280 Change 4). */
+  isKeywordAvailable() {
+    return !(this.indexStrategy instanceof UnavailableIndexStrategy);
+  }
+  /** True when the installed strategy drains a durable ledger (FTS5, or the degraded stand-in). */
+  hasLedger() {
+    return this.indexStrategy.drain !== void 0;
+  }
   /**
    * One serialized drain turn for strategies with a durable ledger. Like
    * sync(), it never rejects: the keyword index is rebuildable, and a failed
-   * drain leaves the ledger rows in place for the next turn.
+   * drain leaves the ledger rows in place for the next turn. Resolves false
+   * when the drain failed.
    */
-  drainTurn(entityId) {
+  drainTurn(entityId, opts) {
     const work = this.syncChain.then(async () => {
       try {
         try {
-          await this.indexStrategy.drain();
+          await this.indexStrategy.drain(opts);
         } finally {
           this.evictCache(entityId);
         }
+        return true;
       } catch (err) {
         console.warn(`[WikiMemory] search index drain failed for ${entityId ?? "*"}:`, err);
+        return false;
       }
     });
-    this.syncChain = work;
+    this.syncChain = work.then(() => void 0);
     return work;
   }
   /**
@@ -5498,9 +5936,18 @@ var _SearchService = class _SearchService {
    * Rebuilds are serialized per instance and never reject: the keyword index
    * is a rebuildable cache over SQLite, so degraded keyword search is the
    * correct failure mode and killing the host process is not.
+   *
+   * With a ledger strategy, `sync()` runs one full quantum bounded by
+   * `opts.deadline`; `sync(entityId)` is a write turn (ledger only).
+   * `opts.ids` are the caller's touched ids: a ledger strategy drains them
+   * first, to completion; MiniSearch ignores them and rebuilds the entity in
+   * one scan.
    */
-  async sync(entityId) {
-    if (this.indexStrategy.drain) return this.drainTurn(entityId);
+  async sync(entityId, opts) {
+    if (this.indexStrategy.drain) {
+      await this.drainTurn(entityId, entityId === void 0 ? { mode: "full", deadline: opts?.deadline, ids: opts?.ids } : { mode: "ledger", entityId, ids: opts?.ids });
+      return;
+    }
     const work = this.syncChain.then(async () => {
       try {
         try {
@@ -5541,13 +5988,17 @@ var _SearchService = class _SearchService {
    * — including on an empty `ids` list, which is a no-op only for an entity
    * the index already tracks, and even then one that waits for rebuilds
    * already queued on the chain.
+   *
+   * Resolves false only when a ledger drain failed: the caller's ids were not
+   * applied (their ledger rows remain), so a caller holding them retries.
    */
   async syncEntries(entityId, ids) {
-    if (this.indexStrategy.drain) return this.drainTurn(entityId);
+    if (this.indexStrategy.drain) return this.drainTurn(entityId, { mode: "ledger", entityId, ids: [...new Set(ids)] });
     const uniqueIds = [...new Set(ids)];
     const indexed = this.indexStrategy.hasIndexedEntity?.(entityId);
     if (uniqueIds.length === 0 && !this.staleEntities.has(entityId) && indexed === true) {
-      return this.syncChain;
+      await this.syncChain;
+      return true;
     }
     const work = this.syncChain.then(async () => {
       try {
@@ -5576,7 +6027,8 @@ var _SearchService = class _SearchService {
       }
     });
     this.syncChain = work;
-    return work;
+    await work;
+    return true;
   }
   /**
    * Forces the entity's next syncEntries to rebuild it in full. For writes core
@@ -5592,11 +6044,13 @@ var _SearchService = class _SearchService {
    * so only those entities are rebuilt. Each rebuild still takes its own turn
    * on the sync chain, and like syncEntries this never rejects. With nothing
    * stale it resolves at once, without waiting on work already on the chain.
+   * Resolves false only when a ledger drain failed (see syncEntries).
    */
-  async syncStale() {
-    if (this.indexStrategy.drain) return this.drainTurn();
+  async syncStale(opts) {
+    if (this.indexStrategy.drain) return this.drainTurn(void 0, { mode: "full", ids: opts?.ids });
     const ids = [...this.staleEntities];
     await Promise.all(ids.map((id) => this.syncEntries(id, [])));
+    return true;
   }
   /**
    * Clears the parsed vector cache. Useful for mid-loop flush guarantees
@@ -6185,6 +6639,7 @@ var WriteService = class {
     this.jobManager = jobManager;
     this.maintenanceService = maintenanceService;
     this.inflight = /* @__PURE__ */ new Set();
+    this.warnedSearchUnavailable = false;
   }
   track(p) {
     this.inflight.add(p);
@@ -6281,8 +6736,7 @@ var WriteService = class {
         this.jobManager.acquireLock("librarian", entityId);
         const stage = { job: "librarian" };
         const job = this.runLibrarianThenMaybeHeal(entityId, librarianCount, prevMemoryCheckpoint, stage).catch((err) => {
-          console.error(err);
-          this.reportBackgroundFailure(entityId, stage.job);
+          this.reportBackgroundFailure(entityId, stage.job, err);
         }).finally(() => {
           this.jobManager.releaseLock("librarian", entityId);
         });
@@ -6293,8 +6747,7 @@ var WriteService = class {
       }
     } else if (!this.jobManager.isBlocked("librarian", entityId)) {
       const healJob = this.maybeRunHeal(entityId, eventCount).catch((err) => {
-        console.error(err);
-        this.reportBackgroundFailure(entityId, "heal");
+        this.reportBackgroundFailure(entityId, "heal", err);
       });
       this.track(healJob);
     }
@@ -6332,13 +6785,19 @@ var WriteService = class {
       }
     }
   }
-  reportBackgroundFailure(entityId, job) {
+  reportBackgroundFailure(entityId, job, err) {
+    const searchUnavailable = isWikiSearchUnavailableError(err);
+    if (!searchUnavailable) console.error(err);
+    else if (!this.warnedSearchUnavailable) {
+      this.warnedSearchUnavailable = true;
+      console.warn("[WikiMemory] Auto librarian/heal pass skipped: keyword search is unavailable. Work is held, not lost, until it recovers (a no-arg syncSearchIndex() retries the init); later skips report only via onDiagnostic.");
+    }
     emitDiagnostic(this.options, {
       code: "background_job_failed",
       operation: job,
       trigger: "auto",
       entityId,
-      detail: { reason: "unhandled_rejection" }
+      detail: { reason: searchUnavailable ? "keyword_search_unavailable" : "unhandled_rejection" }
     });
   }
 };