@equationalapplications/core-llm-wiki 7.11.2 → 7.12.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, __privateAdd, MetadataRepository, EmbeddingService, SearchService, TemporalService, JobManager, PromptService, resolveGrounding, IngestionService, MaintenanceService, ImportExportService, RetrievalService, WriteService, __privateGet, __privateSet, createLegacySourceTypeIndex, writeNormalizeStamp, CURRENT_SCHEMA_VERSION, detectSchemaVersion, MIGRATIONS, runSourceRefNormalize, normalizeSourceRef, normalizeSourceHash, entitySummaryMetaKey, WikiSourceRefHashCollision, DiagnosticBuffer, validateManifest, WikiDraftNotFound, generateId, emptyManifest, resolveNodeType, WikiStrictOntologyViolation, validateInlineEdges, resolveEdgeDefinitions, typeSatisfies, normalizeTitleKey, edgeTripleAllowed, MAX_EMBED_ATTEMPTS, UsageMeter, isWikiSearchUnavailableError, WikiBusyError, WikiInvalidReadOptions, isLiveAt, packFactsByBudget, factTokenCost, probePendingWork, WikiMigrationRequiredError, setupDatabase, UnavailableIndexStrategy, WikiTransactionError, extractSqliteCode } from './chunk-KN4XSLLB.mjs';
+export { DEFAULT_CHUNK_OVERLAP, DEFAULT_MAX_CHUNK_LENGTH, DEFAULT_MAX_EMBED_CHARS, EMBED_CHARS_CEILING, HEAL_ANCHORS_PER_CANDIDATE, HEAL_BATCH_SIZE, HEAL_MAX_FACT_BODY_CHARS_L3, HEAL_MAX_TASKS, HEAL_RECHECK_MS, HOOK_TIMEOUT_MARKER, ONTOLOGY_BACKFILL_BATCH_SIZE, ONTOLOGY_BACKFILL_MAX_PROMPT_CHARS, ONTOLOGY_BACKFILL_RECHECK_MS, ONTOLOGY_BACKFILL_SYSTEM_PROMPT, PromptService, PrunePartialFailureError, WikiBusyError, WikiDraftNotFound, WikiDuplicateHashError, WikiGraphNodeOwnershipConflict, WikiIngestEmptyError, WikiInvalidReadOptions, WikiMigrationRequiredError, WikiParseError, WikiSearchUnavailableError, WikiSourceRefHashCollision, WikiStrictOntologyViolation, WikiSupersedeError, WikiTransactionError, chunkText, configureRandomSource, isWikiSearchUnavailableError, parseEmbedding, safeSlice, validateManifest } from './chunk-KN4XSLLB.mjs';
 import { 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).
@@ -1498,27 +1037,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(
@@ -3222,14 +2740,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}`);
@@ -3251,22 +2789,36 @@ async function detachFts5(db, prefix, metadataRepo) {
   }
 }
 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") {
+  if (preferred === "minisearch") {
+    await detachFts5(db, prefix, metadataRepo);
+    return new MiniSearchIndexStrategy();
+  }
+  const attempt = async () => {
+    if (!await probeFts5(db, prefix)) return "absent";
+    const strategy = new Fts5IndexStrategy(db, prefix, metadataRepo);
+    await strategy.init();
+    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 +2902,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 +2927,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 +2975,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 +3004,7 @@ var MaintenanceScheduler = class {
           }
         }
       }
-      if (!progressed) break;
+      if (!progressed && openJobs() === openAtStart) break;
     }
     if (stopped.reason === "complete" && tooSmall) stopped = tooSmall;
     return {
@@ -3937,6 +3505,10 @@ 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;
+var monotonicNow = () => typeof performance !== "undefined" && typeof performance.now === "function" ? performance.now() : Date.now();
 function decodeDraftCursor(cursor) {
   const sep = typeof cursor === "string" ? cursor.indexOf(":") : -1;
   const createdAt = sep > 0 ? Number(cursor.slice(0, sep)) : Number.NaN;
@@ -3951,6 +3523,11 @@ var WikiMemory = class {
   constructor(db, options) {
     /** Emits `__testAccess` console warning at most once per instance when NODE_ENV ≠ "test". */
     __privateAdd(this, _testAccessNonTestEnvWarned, false);
+    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 +3659,31 @@ var WikiMemory = class {
       jobManager: this.jobManager
     };
   }
-  async setup() {
+  /**
+   * 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.
+   */
+  async setup(opts) {
     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,19 +3697,9 @@ 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,
@@ -4388,7 +3963,10 @@ var WikiMemory = class {
    * 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.
+   * already queued. While keyword search is unavailable it first retries the
+   * index init; after a failed attempt it waits at least 5 s, doubling per
+   * consecutive failure up to 5 min (longer when an attempt is itself slow),
+   * before retrying again.
    *
    * 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,7 +3983,36 @@ 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"
+            );
+            this.searchService.setIndexStrategy(strategy);
+            if (this.searchService.isKeywordAvailable()) 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;
+      }
+      return this.searchService.syncStale();
+    }
     assertEntityId(entityId);
     return this.searchService.syncEntries(entityId, []);
   }