@equationalapplications/core-llm-wiki 7.11.1 → 7.12.0

package/dist/testing.js

@@ -157,6 +157,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 +668,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 +721,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.",
@@ -1709,12 +1722,24 @@ ${groundingEvidenceBlock(writer, cfg)}` : systemPrompt;
   hasOntologyPlaceholders(template) {
     return /\{\{\s*ontology(?:Manifest|ModeInstructions)\s*\}\}/.test(template);
   }
+  /** Removes ontology placeholders until none remain, so a nested form cannot reassemble one (closes CodeQL #11). */
+  stripOntologyPlaceholders(template) {
+    let out = template;
+    let prev;
+    do {
+      prev = out;
+      out = out.replace(/\{\{\s*ontology(?:Manifest|ModeInstructions)\s*\}\}/g, "");
+    } while (out !== prev);
+    return out;
+  }
   buildSystemPrompt(template, variables, ontologyContext) {
+    const hasOntologyPlaceholders = this.hasOntologyPlaceholders(template);
+    const effective = hasOntologyPlaceholders && ontologyContext == null ? this.stripOntologyPlaceholders(template) : template;
     const shouldHydrate = Object.keys(variables).some(
-      (key) => new RegExp(`\\{\\{\\s*${key}\\s*\\}\\}`).test(template)
-    ) || ontologyContext != null && this.hasOntologyPlaceholders(template);
-    const hydrated = shouldHydrate ? this.hydrate(template, { ...variables, ...ontologyContext ?? {} }) : template;
-    return this.hasOntologyPlaceholders(template) ? ontologyContext != null ? hydrated : hydrated.replace(/\{\{\s*ontology(?:Manifest|ModeInstructions)\s*\}\}/g, "") : this.appendOntology(hydrated, ontologyContext);
+      (key) => new RegExp(`\\{\\{\\s*${key}\\s*\\}\\}`).test(effective)
+    ) || ontologyContext != null && hasOntologyPlaceholders;
+    const hydrated = shouldHydrate ? this.hydrate(effective, { ...variables, ...ontologyContext ?? {} }) : effective;
+    return hasOntologyPlaceholders ? hydrated : this.appendOntology(hydrated, ontologyContext);
   }
   appendOntology(systemPrompt, ctx) {
     if (!ctx) return systemPrompt;
@@ -2328,6 +2353,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: [] } };
@@ -2838,6 +2866,326 @@ 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/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);
+    }
+  }
+];
+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/librarian/constants.ts
 var FUZZY_THRESHOLD = 0.5;
 var MIN_TOKENS_TO_QUALIFY = 3;
@@ -3135,6 +3483,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();
@@ -3150,14 +3514,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;
@@ -3178,7 +3536,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]));
@@ -3529,6 +3887,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);
@@ -3758,6 +4119,7 @@ var MaintenanceService = class {
         }
       }
       if (vacuum) {
+        await resetNormalizeWatermarks(this.metadataRepo);
         await this.metadataRepo.vacuum();
       }
       await this.searchService.syncEntries(entityId, syncedIds);
@@ -4057,7 +4419,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;
@@ -4103,7 +4466,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);
@@ -4115,7 +4482,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);
@@ -4919,7 +5289,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) {
@@ -5421,6 +5796,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() {
+  }
+};
+
 // src/services/SearchService.ts
 var _SearchService = class _SearchService {
   constructor(entryRepo, indexStrategy) {
@@ -5459,6 +5856,10 @@ 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);
+  }
   /**
    * One serialized drain turn for strategies with a durable ledger. Like
    * sync(), it never rejects: the keyword index is rebuildable, and a failed
@@ -6173,6 +6574,7 @@ var WriteService = class {
     this.jobManager = jobManager;
     this.maintenanceService = maintenanceService;
     this.inflight = /* @__PURE__ */ new Set();
+    this.warnedSearchUnavailable = false;
   }
   track(p) {
     this.inflight.add(p);
@@ -6269,8 +6671,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);
         });
@@ -6281,8 +6682,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);
     }
@@ -6320,13 +6720,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" }
     });
   }
 };