@equationalapplications/core-llm-wiki 4.19.0 → 4.21.0

package/dist/index.js

@@ -35,7 +35,8 @@ async function setupDatabase(db, prefix) {
       deleted_at INTEGER,
       embedding TEXT,
       embedding_blob BLOB,
-      okf_type TEXT
+      okf_type TEXT,
+      ontology_checked_at INTEGER
     );
 
     CREATE INDEX IF NOT EXISTS ${prefix}entries_entity_idx ON ${prefix}entries(entity_id);
@@ -117,6 +118,127 @@ async function setupDatabase(db, prefix) {
   `);
 }
 
+// src/db/sqliteCodes.ts
+var SQLITE_RESULT_CODE_NAMES = {
+  1: "SQLITE_ERROR",
+  2: "SQLITE_INTERNAL",
+  3: "SQLITE_PERM",
+  4: "SQLITE_ABORT",
+  5: "SQLITE_BUSY",
+  6: "SQLITE_LOCKED",
+  7: "SQLITE_NOMEM",
+  8: "SQLITE_READONLY",
+  9: "SQLITE_INTERRUPT",
+  10: "SQLITE_IOERR",
+  11: "SQLITE_CORRUPT",
+  12: "SQLITE_NOTFOUND",
+  13: "SQLITE_FULL",
+  14: "SQLITE_CANTOPEN",
+  15: "SQLITE_PROTOCOL",
+  16: "SQLITE_EMPTY",
+  17: "SQLITE_SCHEMA",
+  18: "SQLITE_TOOBIG",
+  19: "SQLITE_CONSTRAINT",
+  20: "SQLITE_MISMATCH",
+  21: "SQLITE_MISUSE",
+  22: "SQLITE_NOLFS",
+  23: "SQLITE_AUTH",
+  24: "SQLITE_FORMAT",
+  25: "SQLITE_RANGE",
+  26: "SQLITE_NOTADB",
+  27: "SQLITE_NOTICE",
+  28: "SQLITE_WARNING",
+  100: "SQLITE_ROW",
+  101: "SQLITE_DONE"
+};
+function nameForSqliteResultCode(n) {
+  return SQLITE_RESULT_CODE_NAMES[n] ?? `SQLITE_${n}`;
+}
+function extractSqliteCode(err) {
+  if (typeof err !== "object" || err === null) return void 0;
+  const { code, message } = err;
+  if (typeof code === "string" && code.startsWith("SQLITE_")) return code;
+  if (typeof message === "string") {
+    const m = /^Error code (\d+):/.exec(message);
+    if (m) return nameForSqliteResultCode(Number(m[1]));
+  }
+  return void 0;
+}
+
+// src/types.ts
+var WikiBusyError = class extends Error {
+  constructor(operation, entityId) {
+    super(`${operation} already running for entity ${entityId}`);
+    this.name = "WikiBusyError";
+    this.operation = operation;
+    this.entityId = entityId;
+  }
+};
+var WikiTransactionError = class extends Error {
+  constructor(message, options) {
+    super(message, options);
+    this.name = "WikiTransactionError";
+    this.sqliteErrorCode = extractSqliteCode(options.cause);
+  }
+};
+var PrunePartialFailureError = class extends Error {
+  constructor(deleted, failedAt, remaining, cause, deletedTasks = 0, deletedEvents = 0) {
+    super(`Prune partially failed: deleted ${deleted}, failed at ${failedAt}, ${remaining} remaining`);
+    this.name = "PrunePartialFailureError";
+    this.deleted = deleted;
+    this.failedAt = failedAt;
+    this.remaining = remaining;
+    this.deletedTasks = deletedTasks;
+    this.deletedEvents = deletedEvents;
+    this.cause = cause;
+  }
+};
+var HOOK_TIMEOUT_MARKER = /* @__PURE__ */ Symbol("WikiMemoryHookTimeout");
+
+// src/db/serializedAdapter.ts
+function isDriverError(err) {
+  return extractSqliteCode(err) !== void 0;
+}
+function withOverrides(target, overrides) {
+  return new Proxy(target, {
+    get(obj, prop, receiver) {
+      if (prop in overrides) return Reflect.get(overrides, prop, receiver);
+      const value = Reflect.get(obj, prop, obj);
+      return typeof value === "function" ? value.bind(obj) : value;
+    }
+  });
+}
+function guardReentrancy(tx) {
+  return withOverrides(tx, {
+    withTransactionAsync() {
+      throw new Error(
+        "Nested withTransactionAsync is not supported: you are already inside a transaction. Pass the current `tx` down instead of opening a new transaction."
+      );
+    }
+  });
+}
+var DEADLOCK_WARN_MS = 1e4;
+function withSerializedTransactions(db) {
+  let queue = Promise.resolve();
+  return withOverrides(db, {
+    withTransactionAsync(fn) {
+      const warn = setTimeout(() => {
+        console.warn(
+          "[core-llm-wiki] Transaction queued >10s \u2014 possible deadlock. Inside a transaction callback, use the `tx` parameter, never the outer database handle."
+        );
+      }, DEADLOCK_WARN_MS);
+      const run = queue.catch(() => void 0).then(() => {
+        clearTimeout(warn);
+        return db.withTransactionAsync((tx) => fn(guardReentrancy(tx ?? db)));
+      }).catch((e) => {
+        throw isDriverError(e) ? new WikiTransactionError("Transaction failed", { cause: e }) : e;
+      });
+      queue = run;
+      return run;
+    }
+  });
+}
+
 // src/db/migrations.ts
 var MIGRATIONS = [
   {
@@ -217,6 +339,20 @@ var MIGRATIONS = [
         );
       `);
     }
+  },
+  {
+    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`
+        );
+      }
+    }
   }
 ];
 for (let i = 1; i < MIGRATIONS.length; i++) {
@@ -980,6 +1116,79 @@ var EntryRepository = class extends BaseRepository {
     );
     return rows.map(mapRowToFact);
   }
+  /**
+   * Live untyped facts eligible for ontology backfill, oldest first.
+   * Skips facts checked within the recheck cooldown (ontology_checked_at > recheckCutoff).
+   */
+  async findUntypedByEntityId(entityId, limit, recheckCutoff, tx) {
+    const executor = this.getExecutor(tx);
+    const rows = await executor.getAllAsync(
+      `SELECT * FROM ${this.prefix}entries
+       WHERE entity_id = ? AND okf_type IS NULL AND deleted_at IS NULL
+         AND (ontology_checked_at IS NULL OR ontology_checked_at <= ?)
+       ORDER BY updated_at ASC LIMIT ?`,
+      [entityId, recheckCutoff, limit]
+    );
+    return rows.map(mapRowToFact);
+  }
+  /** Counts live untyped facts: eligible (past cooldown) vs deferred (in cooldown). */
+  async countUntypedByEntityId(entityId, recheckCutoff, tx) {
+    const executor = this.getExecutor(tx);
+    const row = await executor.getFirstAsync(
+      `SELECT
+         SUM(CASE WHEN ontology_checked_at IS NULL OR ontology_checked_at <= ? THEN 1 ELSE 0 END) AS eligible,
+         SUM(CASE WHEN ontology_checked_at IS NOT NULL AND ontology_checked_at > ? THEN 1 ELSE 0 END) AS deferred
+       FROM ${this.prefix}entries
+       WHERE entity_id = ? AND okf_type IS NULL AND deleted_at IS NULL`,
+      [recheckCutoff, recheckCutoff, entityId]
+    );
+    return { eligible: Number(row?.eligible ?? 0), deferred: Number(row?.deferred ?? 0) };
+  }
+  /**
+   * Sets okf_type only when currently NULL — additive by construction: a
+   * concurrently-typed fact is never overwritten. Returns changes for the caller
+   * to distinguish applied vs skipped.
+   */
+  async updateOkfType(id, entityId, okfType, tx) {
+    const result = await tx.runAsync(
+      `UPDATE ${this.prefix}entries SET okf_type = ?
+       WHERE id = ? AND entity_id = ? AND okf_type IS NULL AND deleted_at IS NULL`,
+      [okfType, id, entityId]
+    );
+    return { changes: result.changes };
+  }
+  /**
+   * Stamps the backfill recheck cooldown. NEVER touches updated_at — import
+   * merge resolution is last-write-wins on updated_at and a bump here would
+   * make an unchanged local fact beat a genuinely newer remote edit.
+   */
+  async markOntologyChecked(ids, entityId, now, tx) {
+    if (ids.length === 0) return;
+    for (let i = 0; i < ids.length; i += this.chunkSize) {
+      const chunk = ids.slice(i, i + this.chunkSize);
+      const placeholders = chunk.map(() => "?").join(",");
+      await tx.runAsync(
+        `UPDATE ${this.prefix}entries SET ontology_checked_at = ?
+         WHERE id IN (${placeholders}) AND entity_id = ? AND deleted_at IS NULL`,
+        [now, ...chunk, entityId]
+      );
+    }
+  }
+  /**
+   * Lightweight full-breadth title index (id, title, okf_type) over all live
+   * typed facts. Used by ontology backfill edge resolution — a recent-N window
+   * would miss an old fact's contemporaries. Untyped rows are excluded: they
+   * can never pass the edge target-type check, and batch facts typed during
+   * the run are re-added to the in-memory index by the caller.
+   */
+  async findTitleIndexByEntityId(entityId, tx) {
+    const executor = this.getExecutor(tx);
+    const rows = await executor.getAllAsync(
+      `SELECT id, title, okf_type FROM ${this.prefix}entries WHERE entity_id = ? AND deleted_at IS NULL AND okf_type IS NOT NULL`,
+      [entityId]
+    );
+    return rows.map((r) => ({ id: r.id, title: r.title, okf_type: r.okf_type ?? null }));
+  }
 };
 
 // src/utils/ids.ts
@@ -1424,6 +1633,7 @@ var CONFIDENCE_RANK = {
 var EdgeRepository = class extends BaseRepository {
   /**
    * Insert an edge, silently skipping on primary-key or uniqueness conflicts.
+   * Returns true when a row was inserted, false when skipped as a duplicate.
    * Throws when the insert was skipped due to an id collision with a different edge tuple.
    */
   async addIgnoreDuplicate(edge, tx) {
@@ -1433,17 +1643,18 @@ var EdgeRepository = class extends BaseRepository {
        VALUES (?, ?, ?, ?, ?, ?)`,
       [edge.id, edge.entity_id, edge.source_id, edge.target_id, edge.edge_type, edge.created_at]
     );
-    if (result.changes > 0) return;
+    if (result.changes > 0) return true;
     const existing = await executor.getFirstAsync(
       `SELECT entity_id, source_id, target_id, edge_type FROM ${this.prefix}edges WHERE id = ?`,
       [edge.id]
     );
-    if (!existing) return;
+    if (!existing) return false;
     if (String(existing.entity_id) !== edge.entity_id || String(existing.source_id) !== edge.source_id || String(existing.target_id) !== edge.target_id || String(existing.edge_type) !== edge.edge_type) {
       throw new Error(
         `Edge id collision: ${JSON.stringify(edge.id)} already exists with a different (entity_id, source_id, target_id, edge_type) tuple`
       );
     }
+    return false;
   }
   async getByEntityId(entityId, tx) {
     const executor = this.getExecutor(tx);
@@ -2036,29 +2247,6 @@ _SearchService.MAX_VECTOR_CACHE_ENTITIES = 16;
 _SearchService.MAX_VECTOR_CACHE_FACTS_PER_ENTITY = 500;
 var SearchService = _SearchService;
 
-// src/types.ts
-var WikiBusyError = class extends Error {
-  constructor(operation, entityId) {
-    super(`${operation} already running for entity ${entityId}`);
-    this.name = "WikiBusyError";
-    this.operation = operation;
-    this.entityId = entityId;
-  }
-};
-var PrunePartialFailureError = class extends Error {
-  constructor(deleted, failedAt, remaining, cause, deletedTasks = 0, deletedEvents = 0) {
-    super(`Prune partially failed: deleted ${deleted}, failed at ${failedAt}, ${remaining} remaining`);
-    this.name = "PrunePartialFailureError";
-    this.deleted = deleted;
-    this.failedAt = failedAt;
-    this.remaining = remaining;
-    this.deletedTasks = deletedTasks;
-    this.deletedEvents = deletedEvents;
-    this.cause = cause;
-  }
-};
-var HOOK_TIMEOUT_MARKER = /* @__PURE__ */ Symbol("WikiMemoryHookTimeout");
-
 // src/services/JobManager.ts
 var JobManager = class {
   constructor(prefix) {
@@ -2078,7 +2266,8 @@ var JobManager = class {
       heal: (id) => this._healKey(id),
       reembed: (id) => this._reembedKey(id),
       import: (id) => this._importKey(id),
-      forget: (id) => this._forgetKey(id)
+      forget: (id) => this._forgetKey(id),
+      ontologyBackfill: (id) => this._ontologyBackfillKey(id)
     };
   }
   _pruneKey(entityId) {
@@ -2105,6 +2294,9 @@ var JobManager = class {
   _healKey(entityId) {
     return `${this.prefix}:${entityId}:heal`;
   }
+  _ontologyBackfillKey(entityId) {
+    return `${this.prefix}:${entityId}:ontologyBackfill`;
+  }
   _isReembedActive(entityId) {
     return this.activeMaintenanceJobs.has(this._reembedKey(entityId)) || this.activeMaintenanceJobs.has(this._globalReembedKey());
   }
@@ -2155,14 +2347,16 @@ var JobManager = class {
         if (this.activeMaintenanceJobs.has(this._pruneKey(entityId))) blockingOperation = "prune";
         else if (this.activeMaintenanceJobs.has(this._librarianKey(entityId))) blockingOperation = "librarian";
         else if (this.activeMaintenanceJobs.has(this._healKey(entityId))) blockingOperation = "heal";
+        else if (this.activeMaintenanceJobs.has(this._ontologyBackfillKey(entityId))) blockingOperation = "ontologyBackfill";
         else if (this._isReembedActive(entityId)) blockingOperation = "reembed";
         else if (this._isIngestActiveFor(entityId)) blockingOperation = "ingest";
         else if (this._isImportActiveFor(entityId)) blockingOperation = "import";
         else if (this._isForgetActiveFor(entityId)) blockingOperation = "forget";
         break;
       case "librarian":
-      case "heal": {
-        const opKey = operation === "librarian" ? this._librarianKey(entityId) : this._healKey(entityId);
+      case "heal":
+      case "ontologyBackfill": {
+        const opKey = this.lockKeyFns[operation](entityId);
         if (this.activeMaintenanceJobs.has(opKey)) blockingOperation = operation;
         else if (this.activeMaintenanceJobs.has(this._pruneKey(entityId))) blockingOperation = "prune";
         else if (this._isReembedActive(entityId)) blockingOperation = "reembed";
@@ -2176,6 +2370,7 @@ var JobManager = class {
         else if (this.activeMaintenanceJobs.has(this._pruneKey(entityId))) blockingOperation = "prune";
         else if (this.activeMaintenanceJobs.has(this._librarianKey(entityId))) blockingOperation = "librarian";
         else if (this.activeMaintenanceJobs.has(this._healKey(entityId))) blockingOperation = "heal";
+        else if (this.activeMaintenanceJobs.has(this._ontologyBackfillKey(entityId))) blockingOperation = "ontologyBackfill";
         else if (this._isIngestActiveFor(entityId)) blockingOperation = "ingest";
         else if (this._isImportActiveFor(entityId)) blockingOperation = "import";
         else if (this._isForgetActiveFor(entityId)) blockingOperation = "forget";
@@ -2186,6 +2381,7 @@ var JobManager = class {
         else if (this._isAnyMaintenanceActiveWithSuffix(":prune")) blockingOperation = "prune";
         else if (this._isAnyMaintenanceActiveWithSuffix(":librarian")) blockingOperation = "librarian";
         else if (this._isAnyMaintenanceActiveWithSuffix(":heal")) blockingOperation = "heal";
+        else if (this._isAnyMaintenanceActiveWithSuffix(":ontologyBackfill")) blockingOperation = "ontologyBackfill";
         else if (this.activeIngestJobs.size > 0) blockingOperation = "ingest";
         else if (this._isAnyMaintenanceActiveWithSuffix(":import")) blockingOperation = "import";
         else if (this._isAnyMaintenanceActiveWithSuffix(":forget")) blockingOperation = "forget";
@@ -2196,6 +2392,7 @@ var JobManager = class {
         if (this.activeMaintenanceJobs.has(selfKey)) blockingOperation = operation;
         else if (this.activeMaintenanceJobs.has(this._librarianKey(entityId))) blockingOperation = "librarian";
         else if (this.activeMaintenanceJobs.has(this._healKey(entityId))) blockingOperation = "heal";
+        else if (this.activeMaintenanceJobs.has(this._ontologyBackfillKey(entityId))) blockingOperation = "ontologyBackfill";
         else if (this.activeMaintenanceJobs.has(this._pruneKey(entityId))) blockingOperation = "prune";
         else if (this._isReembedActive(entityId)) blockingOperation = "reembed";
         else if (this._isIngestActiveFor(entityId)) blockingOperation = "ingest";
@@ -2253,11 +2450,11 @@ var JobManager = class {
     if (operation !== "global_import" && this.activeMaintenanceJobs.has(this._globalImportKey())) return true;
     switch (operation) {
       case "librarian":
-        return this.activeMaintenanceJobs.has(this._librarianKey(entityId)) || this.activeMaintenanceJobs.has(this._pruneKey(entityId)) || this._isReembedActive(entityId) || this._isImportActiveFor(entityId) || this._isForgetActiveFor(entityId);
       case "heal":
-        return this.activeMaintenanceJobs.has(this._healKey(entityId)) || this.activeMaintenanceJobs.has(this._pruneKey(entityId)) || this._isReembedActive(entityId) || this._isImportActiveFor(entityId) || this._isForgetActiveFor(entityId);
+      case "ontologyBackfill":
+        return this.activeMaintenanceJobs.has(this.lockKeyFns[operation](entityId)) || this.activeMaintenanceJobs.has(this._pruneKey(entityId)) || this._isReembedActive(entityId) || this._isImportActiveFor(entityId) || this._isForgetActiveFor(entityId);
       case "prune":
-        return this.activeMaintenanceJobs.has(this._pruneKey(entityId)) || this.activeMaintenanceJobs.has(this._librarianKey(entityId)) || this.activeMaintenanceJobs.has(this._healKey(entityId)) || this._isReembedActive(entityId) || this._isIngestActiveFor(entityId) || this._isImportActiveFor(entityId) || this._isForgetActiveFor(entityId);
+        return this.activeMaintenanceJobs.has(this._pruneKey(entityId)) || this.activeMaintenanceJobs.has(this._librarianKey(entityId)) || this.activeMaintenanceJobs.has(this._healKey(entityId)) || this.activeMaintenanceJobs.has(this._ontologyBackfillKey(entityId)) || this._isReembedActive(entityId) || this._isIngestActiveFor(entityId) || this._isImportActiveFor(entityId) || this._isForgetActiveFor(entityId);
       default:
         return false;
     }
@@ -2282,6 +2479,7 @@ var JobManager = class {
       if (this.activeMaintenanceJobs.has(this._importKey(entityId))) throw new WikiBusyError("import", entityId);
       if (this.activeMaintenanceJobs.has(this._librarianKey(entityId))) throw new WikiBusyError("librarian", entityId);
       if (this.activeMaintenanceJobs.has(this._healKey(entityId))) throw new WikiBusyError("heal", entityId);
+      if (this.activeMaintenanceJobs.has(this._ontologyBackfillKey(entityId))) throw new WikiBusyError("ontologyBackfill", entityId);
       if (this.activeMaintenanceJobs.has(this._pruneKey(entityId))) throw new WikiBusyError("prune", entityId);
       if (this._isReembedActive(entityId)) throw new WikiBusyError("reembed", entityId);
       if (this._isIngestActiveFor(entityId)) throw new WikiBusyError("ingest", entityId);
@@ -2590,6 +2788,15 @@ Return ONLY a valid JSON object matching this schema:
   "facts": [{ "title": "string (max 80 chars)", "body": "string (max 800 chars)", "tags": ["string"], "confidence": "certain|inferred|tentative" }]
 }
 Extract verbatim factual content. Do not return markdown, just raw JSON.`;
+var ONTOLOGY_BACKFILL_SYSTEM_PROMPT = `You are a knowledge classification agent. You will receive existing memory facts that currently have no ontology type. For each input fact { "id", "title", "body", "tags" }, assign the best matching okf_type from the ontology manifest and optionally propose edges to related facts by title.
+Return ONLY a valid JSON object matching this schema:
+{
+  "classifications": [
+    { "id": "string (input fact id, copied verbatim)", "okf_type": "string (manifest node type slug)", "edges": [{ "edge_type": "string", "target_title": "string" }] }
+  ]
+}
+If no manifest type fits a fact, omit that fact from "classifications" entirely \u2014 do not guess.
+Do not return markdown, just raw JSON.`;
 
 // src/services/PromptService.ts
 var PromptService = class {
@@ -2679,6 +2886,22 @@ ${JSON.stringify(recentEvents, null, 2)}
 The following document anchors are provided for contradiction detection only. Do not include them in \`downgraded\`, \`deleted\`, or \`newFacts\`.`
     };
   }
+  buildOntologyBackfillPrompt(facts, runtimeOverride, ontologyContext) {
+    const template = runtimeOverride ?? this.globalOverrides?.ontologyBackfillSystemPrompt ?? ONTOLOGY_BACKFILL_SYSTEM_PROMPT;
+    const hasFacts = /\{\{\s*facts\s*\}\}/.test(template);
+    if (hasFacts || this.hasOntologyPlaceholders(template)) {
+      return {
+        systemPrompt: this.buildSystemPrompt(template, { facts }, ontologyContext),
+        userPrompt: hasFacts ? "Please classify the facts." : `Facts:
+${JSON.stringify(facts, null, 2)}`
+      };
+    }
+    return {
+      systemPrompt: this.appendOntology(template, ontologyContext),
+      userPrompt: `Facts:
+${JSON.stringify(facts, null, 2)}`
+    };
+  }
 };
 
 // src/services/IngestionService.ts
@@ -2832,6 +3055,9 @@ var IngestionService = class {
 // src/services/MaintenanceService.ts
 var FUZZY_THRESHOLD = 0.5;
 var MIN_TOKENS_TO_QUALIFY = 3;
+var ONTOLOGY_BACKFILL_BATCH_SIZE = 25;
+var ONTOLOGY_BACKFILL_MAX_PROMPT_CHARS = 4e4;
+var ONTOLOGY_BACKFILL_RECHECK_MS = 7 * 24 * 60 * 60 * 1e3;
 var MaintenanceService = class {
   constructor(db, prefix, options, entryRepo, taskRepo, eventRepo, metadataRepo, searchService, jobManager, embeddingService, promptService, ontologyService) {
     this.db = db;
@@ -2937,6 +3163,14 @@ var MaintenanceService = class {
       this.jobManager.releaseLock("heal", entityId);
     }
   }
+  async runOntologyBackfill(entityId, options) {
+    this.jobManager.acquireLock("ontologyBackfill", entityId);
+    try {
+      return await this.doRunOntologyBackfill(entityId, options);
+    } finally {
+      this.jobManager.releaseLock("ontologyBackfill", entityId);
+    }
+  }
   async runReembed(entityId, opts) {
     const embedFn = this.options.llmProvider.embed;
     if (!embedFn) return { embedded: 0, skipped: 0, failed: 0 };
@@ -3288,6 +3522,121 @@ var MaintenanceService = class {
     }
     this.searchService.evictCache(entityId);
   }
+  /** Core ontology backfill pass (locks handled by {@link runOntologyBackfill}). Package-internal orchestration hook. */
+  async doRunOntologyBackfill(entityId, options) {
+    const batchSize = options?.batchSize ?? ONTOLOGY_BACKFILL_BATCH_SIZE;
+    if (!Number.isInteger(batchSize) || batchSize < 1) {
+      throw new Error("Invalid batchSize: must be an integer >= 1");
+    }
+    const now = Date.now();
+    const recheckCutoff = now - ONTOLOGY_BACKFILL_RECHECK_MS;
+    const zeroed = { scanned: 0, typed: 0, failedValidation: 0, edgesAdded: 0 };
+    const ontologyService = this.ontologyService;
+    if (!ontologyService) {
+      return { ...zeroed, remaining: 0, deferred: 0 };
+    }
+    const { mode } = await ontologyService.getEffectiveState(entityId);
+    if (mode === "off") {
+      const counts2 = await this.entryRepo.countUntypedByEntityId(entityId, recheckCutoff);
+      return { ...zeroed, remaining: 0, deferred: counts2.deferred };
+    }
+    const candidates = await this.entryRepo.findUntypedByEntityId(entityId, batchSize, recheckCutoff);
+    if (candidates.length === 0) {
+      const counts2 = await this.entryRepo.countUntypedByEntityId(entityId, recheckCutoff);
+      return { ...zeroed, remaining: counts2.eligible, deferred: counts2.deferred };
+    }
+    const ontologyContext = await ontologyService.buildPromptContext(entityId);
+    const toPromptShape = (f) => ({ id: f.id, title: f.title, body: f.body, tags: f.tags });
+    const buildPrompt = (facts) => this.promptService.buildOntologyBackfillPrompt(
+      facts.map(toPromptShape),
+      options?.promptOverride,
+      ontologyContext
+    );
+    const batch = [candidates[0]];
+    let built = buildPrompt(batch);
+    for (let i = 1; i < candidates.length; i++) {
+      const next = buildPrompt([...batch, candidates[i]]);
+      if (next.systemPrompt.length + next.userPrompt.length > ONTOLOGY_BACKFILL_MAX_PROMPT_CHARS) break;
+      batch.push(candidates[i]);
+      built = next;
+    }
+    const { systemPrompt, userPrompt } = built;
+    const responseText = await this.options.llmProvider.generateText({ systemPrompt, userPrompt });
+    const parsed = parseJsonResponse(responseText);
+    const classifications = Array.isArray(parsed.classifications) ? parsed.classifications : [];
+    let typed = 0;
+    let failedValidation = 0;
+    let edgesAdded = 0;
+    let abortedOntologyOff = false;
+    await this.db.withTransactionAsync(async (tx) => {
+      let { mode: txMode, manifest } = await ontologyService.getEffectiveState(entityId, tx);
+      if (txMode === "off") {
+        abortedOntologyOff = true;
+        return;
+      }
+      if (txMode === "emergent" && parsed.ontology_updates) {
+        manifest = await ontologyService.mergeEmergentUpdates(entityId, parsed.ontology_updates, tx);
+      }
+      const titleRows = await this.entryRepo.findTitleIndexByEntityId(entityId, tx);
+      const titleIndex = /* @__PURE__ */ new Map();
+      for (const row of titleRows) {
+        titleIndex.set(normalizeTitleKey(row.title), { id: row.id, okf_type: row.okf_type });
+      }
+      const batchById = new Map(batch.map((f) => [f.id, f]));
+      const applied = /* @__PURE__ */ new Set();
+      const pendingEdges = [];
+      for (const classification of classifications) {
+        const fact = typeof classification.id === "string" ? batchById.get(classification.id) : void 0;
+        if (!fact || applied.has(fact.id)) {
+          failedValidation++;
+          continue;
+        }
+        applied.add(fact.id);
+        const normalized = ontologyService.validateAndNormalizeFact(
+          {
+            title: fact.title,
+            body: fact.body,
+            tags: fact.tags,
+            confidence: fact.confidence,
+            okf_type: classification.okf_type,
+            edges: classification.edges
+          },
+          manifest
+        );
+        if (!normalized.okf_type) {
+          failedValidation++;
+          continue;
+        }
+        const result = await this.entryRepo.updateOkfType(fact.id, entityId, normalized.okf_type, tx);
+        if (result.changes === 0) continue;
+        typed++;
+        titleIndex.set(normalizeTitleKey(fact.title), { id: fact.id, okf_type: normalized.okf_type });
+        if (normalized.edges.length > 0) {
+          pendingEdges.push({ sourceId: fact.id, sourceType: normalized.okf_type, edges: normalized.edges });
+        }
+      }
+      for (const item of pendingEdges) {
+        edgesAdded += await ontologyService.resolveAndPersistEdges(
+          entityId,
+          item.sourceId,
+          item.sourceType,
+          item.edges,
+          manifest,
+          titleIndex,
+          tx,
+          now
+        );
+      }
+      await this.entryRepo.markOntologyChecked(batch.map((f) => f.id), entityId, now, tx);
+    });
+    if (abortedOntologyOff) {
+      const counts2 = await this.entryRepo.countUntypedByEntityId(entityId, recheckCutoff);
+      return { ...zeroed, remaining: 0, deferred: counts2.deferred };
+    }
+    this.searchService.evictCache(entityId);
+    const counts = await this.entryRepo.countUntypedByEntityId(entityId, recheckCutoff);
+    return { scanned: batch.length, typed, failedValidation, edgesAdded, remaining: counts.eligible, deferred: counts.deferred };
+  }
   _validatePruneDuration(value, name) {
     if (value !== null && value !== void 0 && (typeof value !== "number" || !isFinite(value) || value < 0)) {
       throw new Error(`Invalid ${name}: must be a non-negative finite number or null`);
@@ -4587,7 +4936,8 @@ var OntologyService = class {
     return { okf_type: canonical, edges };
   }
   async resolveAndPersistEdges(entityId, sourceId, sourceType, edges, manifest, titleIndex, tx, now) {
-    if (!sourceType || edges.length === 0) return;
+    if (!sourceType || edges.length === 0) return 0;
+    let persisted = 0;
     for (const edge of edges) {
       const def = resolveEdgeDefinition(edge.edge_type, manifest);
       if (!def || def.source_type.toLowerCase() !== sourceType.toLowerCase()) continue;
@@ -4603,8 +4953,10 @@ var OntologyService = class {
         edge_type: def.type,
         created_at: now
       };
-      await this.edgeRepo.addIgnoreDuplicate(wikiEdge, tx);
+      const inserted = await this.edgeRepo.addIgnoreDuplicate(wikiEdge, tx);
+      if (inserted) persisted++;
     }
+    return persisted;
   }
 };
 
@@ -4647,7 +4999,7 @@ var WikiMemory = class {
   constructor(db, options) {
     /** Emits `__testAccess` console warning at most once per instance when NODE_ENV ≠ "test". */
     __privateAdd(this, _testAccessNonTestEnvWarned, false);
-    this.db = db;
+    this.db = withSerializedTransactions(db);
     this.options = options;
     this.prefix = options.config?.tablePrefix ?? "llm_wiki_";
     if (!TABLE_PREFIX_PATTERN.test(this.prefix)) {
@@ -4655,12 +5007,12 @@ var WikiMemory = class {
         `Invalid tablePrefix: ${JSON.stringify(this.prefix)}. Must match ${TABLE_PREFIX_PATTERN} (letter, then alphanumeric/underscore, ending in "_", max 32 chars total).`
       );
     }
-    this.outboxRepo = new OutboxRepository(db, this.prefix, !!options.config?.enableOutbox);
-    this.entryRepo = new EntryRepository(db, this.prefix, this.outboxRepo);
-    this.taskRepo = new TaskRepository(db, this.prefix, this.outboxRepo);
-    this.eventRepo = new EventRepository(db, this.prefix);
-    this.edgeRepo = new EdgeRepository(db, this.prefix);
-    this.metadataRepo = new MetadataRepository(db, this.prefix);
+    this.outboxRepo = new OutboxRepository(this.db, this.prefix, !!options.config?.enableOutbox);
+    this.entryRepo = new EntryRepository(this.db, this.prefix, this.outboxRepo);
+    this.taskRepo = new TaskRepository(this.db, this.prefix, this.outboxRepo);
+    this.eventRepo = new EventRepository(this.db, this.prefix);
+    this.edgeRepo = new EdgeRepository(this.db, this.prefix);
+    this.metadataRepo = new MetadataRepository(this.db, this.prefix);
     this.ontologyService = new OntologyService(
       this.metadataRepo,
       this.edgeRepo,
@@ -4844,6 +5196,24 @@ var WikiMemory = class {
   async runHeal(entityId, options) {
     return this.maintenanceService.runHeal(entityId, options);
   }
+  /**
+   * Types already-persisted untyped facts (okf_type IS NULL) in place via one
+   * librarian-style LLM call. Strictly additive: never creates, deletes, or
+   * rewrites facts; never overwrites an existing okf_type. Free when there is
+   * nothing to do (ontology off, or zero eligible untyped facts).
+   *
+   * Hosts own the trigger cadence (e.g. after each sync); loop `while
+   * result.remaining > 0` for convergence. Throws WikiBusyError when another
+   * backfill (or conflicting maintenance op) is running for the entity.
+   *
+   * @param options.promptOverride - Applies only to this call. For persistent
+   * customization set `options.config.prompts.ontologyBackfillSystemPrompt`.
+   * @param options.batchSize - Facts per run (default 25) for providers with
+   * tighter context limits.
+   */
+  async runOntologyBackfill(entityId, options) {
+    return this.maintenanceService.runOntologyBackfill(entityId, options);
+  }
   async runReembed(entityId, opts) {
     return this.maintenanceService.runReembed(entityId, opts);
   }
@@ -5683,10 +6053,15 @@ function createWiki(db, options) {
 
 exports.DEFAULT_LIBRARIAN_SYNTHESIS_PROMPT = DEFAULT_LIBRARIAN_SYNTHESIS_PROMPT;
 exports.HOOK_TIMEOUT_MARKER = HOOK_TIMEOUT_MARKER;
+exports.ONTOLOGY_BACKFILL_BATCH_SIZE = ONTOLOGY_BACKFILL_BATCH_SIZE;
+exports.ONTOLOGY_BACKFILL_MAX_PROMPT_CHARS = ONTOLOGY_BACKFILL_MAX_PROMPT_CHARS;
+exports.ONTOLOGY_BACKFILL_RECHECK_MS = ONTOLOGY_BACKFILL_RECHECK_MS;
+exports.ONTOLOGY_BACKFILL_SYSTEM_PROMPT = ONTOLOGY_BACKFILL_SYSTEM_PROMPT;
 exports.PromptService = PromptService;
 exports.PrunePartialFailureError = PrunePartialFailureError;
 exports.WikiBusyError = WikiBusyError;
 exports.WikiMemory = WikiMemory;
+exports.WikiTransactionError = WikiTransactionError;
 exports.configureRandomSource = configureRandomSource;
 exports.createWiki = createWiki;
 exports.formatContext = formatContext;