@equationalapplications/core-llm-wiki 4.20.0 → 4.22.0

package/dist/index.d.mts

@@ -1,5 +1,5 @@
-import { M as MemoryBundle, F as FormatContextOptions, G as GraphNeighborhood, a as MemoryDump, b as FormattedMemoryDump, R as ReadOptions, S as SQLiteAdapter, W as WikiOptions, c as WikiMemory } from './testing-BVN_g414.mjs';
-export { E as EntityStatus, d as ExtractedFact, e as ExtractedFactEdge, f as ExtractedFactWithOntology, g as ExtractedTask, h as GraphTraversalOptions, H as HOOK_TIMEOUT_MARKER, L as LLMProvider, O as OntologyConfig, i as OntologyEdgeType, j as OntologyManifest, k as OntologyMode, l as OntologyNodeType, m as OntologyPromptContext, n as OntologyUpdates, P as PromptOverrides, o as PromptService, p as PrunePartialFailureError, V as VectorRanker, q as VectorRankerFallback, r as VectorRankerRankArgs, s as VectorRankerSemanticResult, t as WikiBusyError, u as WikiBusyOperation, v as WikiCheckpoint, w as WikiConfig, x as WikiEdge, y as WikiEvent, z as WikiFact, A as WikiMemoryTestAccess, B as WikiOutboxEvent, C as WikiTask, D as WikiTransactionError } from './testing-BVN_g414.mjs';
+import { M as MemoryBundle, F as FormatContextOptions, G as GraphNeighborhood, a as MemoryDump, b as FormattedMemoryDump, O as OntologyManifest, R as ReadOptions, S as SQLiteAdapter, W as WikiOptions, c as WikiMemory } from './testing-Bk8J6QLX.mjs';
+export { E as EntityStatus, d as ExtractedFact, e as ExtractedFactEdge, f as ExtractedFactWithOntology, g as ExtractedTask, h as GraphTraversalOptions, H as HOOK_TIMEOUT_MARKER, L as LLMProvider, i as ONTOLOGY_BACKFILL_BATCH_SIZE, j as ONTOLOGY_BACKFILL_MAX_PROMPT_CHARS, k as ONTOLOGY_BACKFILL_RECHECK_MS, l as OntologyBackfillResult, m as OntologyConfig, n as OntologyEdgeType, o as OntologyMode, p as OntologyNodeType, q as OntologyPromptContext, r as OntologyUpdates, P as PromptOverrides, s as PromptService, t as PrunePartialFailureError, V as VectorRanker, u as VectorRankerFallback, v as VectorRankerRankArgs, w as VectorRankerSemanticResult, x as WikiBusyError, y as WikiBusyOperation, z as WikiCheckpoint, A as WikiConfig, B as WikiEdge, C as WikiEvent, D as WikiFact, I as WikiMemoryTestAccess, J as WikiOutboxEvent, K as WikiTask, N as WikiTransactionError } from './testing-Bk8J6QLX.mjs';
 import { OkfFile } from '@equationalapplications/core-okf';
 import 'minisearch';
 
@@ -26,6 +26,8 @@ declare function parseOkfBundle(entityId: string, files: OkfFile[], options?: Ok
 
 declare function parseEmbedding(blob: Uint8Array | null | undefined, text: string | null | undefined): Float32Array | null;
 
+declare function validateManifest(manifest: OntologyManifest): void;
+
 type GetRandomValues = (bytes: Uint8Array) => void;
 /**
  * Inject a platform-specific `getRandomValues` implementation.
@@ -58,6 +60,8 @@ declare function validateLibrarianPromptTemplate(template: string, options: {
 }): string[];
 declare function mapLibrarianOptionsToReadOptions(options: LibrarianOptions): Pick<ReadOptions, 'tierWeights' | 'includeZeroWeightEntities'>;
 
+declare const 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.\nReturn ONLY a valid JSON object matching this schema:\n{\n  \"classifications\": [\n    { \"id\": \"string (input fact id, copied verbatim)\", \"okf_type\": \"string (manifest node type slug)\", \"edges\": [{ \"edge_type\": \"string\", \"target_title\": \"string\" }] }\n  ]\n}\nIf no manifest type fits a fact, omit that fact from \"classifications\" entirely \u2014 do not guess.\nDo not return markdown, just raw JSON.";
+
 declare function createWiki(db: SQLiteAdapter, options: WikiOptions): WikiMemory;
 
-export { DEFAULT_LIBRARIAN_SYNTHESIS_PROMPT, FormatContextOptions, FormattedMemoryDump, GraphNeighborhood, type LibrarianOptions, type LibrarianPromptVariables, MemoryBundle, MemoryDump, type OkfImportOptions, ReadOptions, SQLiteAdapter, WikiMemory, WikiOptions, configureRandomSource, createWiki, formatContext, formatGraphContext, formatMemoryDump, formatOkfBundle, hydrateLibrarianPrompt, mapLibrarianOptionsToReadOptions, parseEmbedding, parseOkfBundle, validateLibrarianPromptTemplate };
+export { DEFAULT_LIBRARIAN_SYNTHESIS_PROMPT, FormatContextOptions, FormattedMemoryDump, GraphNeighborhood, type LibrarianOptions, type LibrarianPromptVariables, MemoryBundle, MemoryDump, ONTOLOGY_BACKFILL_SYSTEM_PROMPT, type OkfImportOptions, OntologyManifest, ReadOptions, SQLiteAdapter, WikiMemory, WikiOptions, configureRandomSource, createWiki, formatContext, formatGraphContext, formatMemoryDump, formatOkfBundle, hydrateLibrarianPrompt, mapLibrarianOptionsToReadOptions, parseEmbedding, parseOkfBundle, validateLibrarianPromptTemplate, validateManifest };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { M as MemoryBundle, F as FormatContextOptions, G as GraphNeighborhood, a as MemoryDump, b as FormattedMemoryDump, R as ReadOptions, S as SQLiteAdapter, W as WikiOptions, c as WikiMemory } from './testing-BVN_g414.js';
-export { E as EntityStatus, d as ExtractedFact, e as ExtractedFactEdge, f as ExtractedFactWithOntology, g as ExtractedTask, h as GraphTraversalOptions, H as HOOK_TIMEOUT_MARKER, L as LLMProvider, O as OntologyConfig, i as OntologyEdgeType, j as OntologyManifest, k as OntologyMode, l as OntologyNodeType, m as OntologyPromptContext, n as OntologyUpdates, P as PromptOverrides, o as PromptService, p as PrunePartialFailureError, V as VectorRanker, q as VectorRankerFallback, r as VectorRankerRankArgs, s as VectorRankerSemanticResult, t as WikiBusyError, u as WikiBusyOperation, v as WikiCheckpoint, w as WikiConfig, x as WikiEdge, y as WikiEvent, z as WikiFact, A as WikiMemoryTestAccess, B as WikiOutboxEvent, C as WikiTask, D as WikiTransactionError } from './testing-BVN_g414.js';
+import { M as MemoryBundle, F as FormatContextOptions, G as GraphNeighborhood, a as MemoryDump, b as FormattedMemoryDump, O as OntologyManifest, R as ReadOptions, S as SQLiteAdapter, W as WikiOptions, c as WikiMemory } from './testing-Bk8J6QLX.js';
+export { E as EntityStatus, d as ExtractedFact, e as ExtractedFactEdge, f as ExtractedFactWithOntology, g as ExtractedTask, h as GraphTraversalOptions, H as HOOK_TIMEOUT_MARKER, L as LLMProvider, i as ONTOLOGY_BACKFILL_BATCH_SIZE, j as ONTOLOGY_BACKFILL_MAX_PROMPT_CHARS, k as ONTOLOGY_BACKFILL_RECHECK_MS, l as OntologyBackfillResult, m as OntologyConfig, n as OntologyEdgeType, o as OntologyMode, p as OntologyNodeType, q as OntologyPromptContext, r as OntologyUpdates, P as PromptOverrides, s as PromptService, t as PrunePartialFailureError, V as VectorRanker, u as VectorRankerFallback, v as VectorRankerRankArgs, w as VectorRankerSemanticResult, x as WikiBusyError, y as WikiBusyOperation, z as WikiCheckpoint, A as WikiConfig, B as WikiEdge, C as WikiEvent, D as WikiFact, I as WikiMemoryTestAccess, J as WikiOutboxEvent, K as WikiTask, N as WikiTransactionError } from './testing-Bk8J6QLX.js';
 import { OkfFile } from '@equationalapplications/core-okf';
 import 'minisearch';
 
@@ -26,6 +26,8 @@ declare function parseOkfBundle(entityId: string, files: OkfFile[], options?: Ok
 
 declare function parseEmbedding(blob: Uint8Array | null | undefined, text: string | null | undefined): Float32Array | null;
 
+declare function validateManifest(manifest: OntologyManifest): void;
+
 type GetRandomValues = (bytes: Uint8Array) => void;
 /**
  * Inject a platform-specific `getRandomValues` implementation.
@@ -58,6 +60,8 @@ declare function validateLibrarianPromptTemplate(template: string, options: {
 }): string[];
 declare function mapLibrarianOptionsToReadOptions(options: LibrarianOptions): Pick<ReadOptions, 'tierWeights' | 'includeZeroWeightEntities'>;
 
+declare const 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.\nReturn ONLY a valid JSON object matching this schema:\n{\n  \"classifications\": [\n    { \"id\": \"string (input fact id, copied verbatim)\", \"okf_type\": \"string (manifest node type slug)\", \"edges\": [{ \"edge_type\": \"string\", \"target_title\": \"string\" }] }\n  ]\n}\nIf no manifest type fits a fact, omit that fact from \"classifications\" entirely \u2014 do not guess.\nDo not return markdown, just raw JSON.";
+
 declare function createWiki(db: SQLiteAdapter, options: WikiOptions): WikiMemory;
 
-export { DEFAULT_LIBRARIAN_SYNTHESIS_PROMPT, FormatContextOptions, FormattedMemoryDump, GraphNeighborhood, type LibrarianOptions, type LibrarianPromptVariables, MemoryBundle, MemoryDump, type OkfImportOptions, ReadOptions, SQLiteAdapter, WikiMemory, WikiOptions, configureRandomSource, createWiki, formatContext, formatGraphContext, formatMemoryDump, formatOkfBundle, hydrateLibrarianPrompt, mapLibrarianOptionsToReadOptions, parseEmbedding, parseOkfBundle, validateLibrarianPromptTemplate };
+export { DEFAULT_LIBRARIAN_SYNTHESIS_PROMPT, FormatContextOptions, FormattedMemoryDump, GraphNeighborhood, type LibrarianOptions, type LibrarianPromptVariables, MemoryBundle, MemoryDump, ONTOLOGY_BACKFILL_SYSTEM_PROMPT, type OkfImportOptions, OntologyManifest, ReadOptions, SQLiteAdapter, WikiMemory, WikiOptions, configureRandomSource, createWiki, formatContext, formatGraphContext, formatMemoryDump, formatOkfBundle, hydrateLibrarianPrompt, mapLibrarianOptionsToReadOptions, parseEmbedding, parseOkfBundle, validateLibrarianPromptTemplate, validateManifest };

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);
@@ -338,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++) {
@@ -1101,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
@@ -1545,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) {
@@ -1554,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);
@@ -1691,10 +1781,13 @@ function resolveNodeType(raw, manifest) {
   const hit = manifest.node_types.find((n) => n.type.toLowerCase() === slug.toLowerCase());
   return hit?.type ?? null;
 }
-function resolveEdgeDefinition(rawEdgeType, manifest) {
+function resolveEdgeDefinitions(rawEdgeType, manifest) {
   const slug = rawEdgeType.trim();
-  if (!slug) return null;
-  return manifest.edge_types.find((e) => e.type.toLowerCase() === slug.toLowerCase()) ?? null;
+  if (!slug) return [];
+  return manifest.edge_types.filter((e) => e.type.toLowerCase() === slug.toLowerCase());
+}
+function edgeTripleKey(type, sourceType, targetType) {
+  return `${type.trim().toLowerCase()}|${sourceType.trim().toLowerCase()}|${targetType.trim().toLowerCase()}`;
 }
 function validateManifest(manifest) {
   const nodeSlugs = /* @__PURE__ */ new Set();
@@ -1705,25 +1798,35 @@ function validateManifest(manifest) {
     if (nodeSlugs.has(key)) throw new Error(`Duplicate node type: ${type}`);
     nodeSlugs.add(key);
   }
-  const edgeSlugs = /* @__PURE__ */ new Set();
+  const edgeKeys = /* @__PURE__ */ new Set();
+  const edgeNames = /* @__PURE__ */ new Map();
   for (const edge of manifest.edge_types ?? []) {
     const edgeType = edge.type?.trim();
     const sourceType = edge.source_type?.trim();
     const targetType = edge.target_type?.trim();
     if (!edgeType) throw new Error("Ontology edge type slug must be non-empty");
-    const edgeKey = edgeType.toLowerCase();
-    if (edgeSlugs.has(edgeKey)) throw new Error(`Duplicate edge type: ${edgeType}`);
-    edgeSlugs.add(edgeKey);
     if (!sourceType || !targetType || !nodeSlugs.has(sourceType.toLowerCase()) || !nodeSlugs.has(targetType.toLowerCase())) {
       throw new Error(`Edge type ${edgeType} references unknown node type`);
     }
+    const edgeKey = edgeTripleKey(edgeType, sourceType, targetType);
+    if (edgeKeys.has(edgeKey)) {
+      throw new Error(`Duplicate edge definition: ${edgeType} (${sourceType} \u2192 ${targetType})`);
+    }
+    edgeKeys.add(edgeKey);
+    const canonical = edgeNames.get(edgeType.toLowerCase());
+    if (canonical === void 0) {
+      edgeNames.set(edgeType.toLowerCase(), edgeType);
+    } else if (canonical !== edgeType) {
+      throw new Error(`Inconsistent casing for edge type: ${edgeType} conflicts with ${canonical}`);
+    }
   }
 }
 function mergeOntologyUpdates(current, updates) {
   const node_types = [...current.node_types];
   const edge_types = [...current.edge_types];
   const nodeSlugs = new Set(node_types.map((n) => n.type.trim().toLowerCase()));
-  const edgeSlugs = new Set(edge_types.map((e) => e.type.trim().toLowerCase()));
+  const edgeKeys = new Set(edge_types.map((e) => edgeTripleKey(e.type, e.source_type, e.target_type)));
+  const edgeNames = new Map(edge_types.map((e) => [e.type.trim().toLowerCase(), e.type.trim()]));
   for (const node of updates.node_types ?? []) {
     const type = node?.type?.trim();
     if (!type) continue;
@@ -1733,20 +1836,22 @@ function mergeOntologyUpdates(current, updates) {
     nodeSlugs.add(key);
   }
   for (const edge of updates.edge_types ?? []) {
-    const edgeType = edge?.type?.trim();
+    const rawEdgeType = edge?.type?.trim();
     const sourceType = edge?.source_type?.trim();
     const targetType = edge?.target_type?.trim();
-    if (!edgeType || !sourceType || !targetType) continue;
-    const edgeKey = edgeType.toLowerCase();
-    if (edgeSlugs.has(edgeKey)) continue;
+    if (!rawEdgeType || !sourceType || !targetType) continue;
+    const edgeType = edgeNames.get(rawEdgeType.toLowerCase()) ?? rawEdgeType;
+    const edgeKey = edgeTripleKey(edgeType, sourceType, targetType);
+    if (edgeKeys.has(edgeKey)) continue;
     if (!nodeSlugs.has(sourceType.toLowerCase()) || !nodeSlugs.has(targetType.toLowerCase())) continue;
+    edgeNames.set(edgeType.toLowerCase(), edgeType);
     edge_types.push({
       type: edgeType,
       source_type: sourceType,
       target_type: targetType,
       description: String(edge.description ?? "")
     });
-    edgeSlugs.add(edgeKey);
+    edgeKeys.add(edgeKey);
   }
   return { node_types, edge_types };
 }
@@ -1755,10 +1860,10 @@ function validateInlineEdges(sourceType, _targetType, edges, manifest) {
   const valid = [];
   for (const edge of edges) {
     if (typeof edge?.edge_type !== "string" || typeof edge?.target_title !== "string") continue;
-    const def = resolveEdgeDefinition(edge.edge_type, manifest);
-    if (!def) continue;
-    if (def.source_type.toLowerCase() !== sourceType.toLowerCase()) continue;
-    valid.push({ edge_type: def.type, target_title: edge.target_title });
+    const defs = resolveEdgeDefinitions(edge.edge_type, manifest);
+    const match = defs.find((d) => d.source_type.toLowerCase() === sourceType.toLowerCase());
+    if (!match) continue;
+    valid.push({ edge_type: match.type, target_title: edge.target_title });
   }
   return valid;
 }
@@ -2176,7 +2281,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) {
@@ -2203,6 +2309,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());
   }
@@ -2253,14 +2362,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";
@@ -2274,6 +2385,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";
@@ -2284,6 +2396,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";
@@ -2294,6 +2407,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";
@@ -2351,11 +2465,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;
     }
@@ -2380,6 +2494,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);
@@ -2688,6 +2803,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 {
@@ -2777,6 +2901,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
@@ -2930,6 +3070,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;
@@ -3035,6 +3178,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 };
@@ -3386,6 +3537,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`);
@@ -4603,7 +4869,8 @@ var WriteService = class {
 var FACT_ONTOLOGY_FIELDS = `
 Each fact may optionally include:
 - "okf_type": string \u2014 must be one of the node_types in the manifest
-- "edges": [{ "edge_type": string, "target_title": string }] \u2014 target_title must match another fact's title in this response or existing memory`;
+- "edges": [{ "edge_type": string, "target_title": string }] \u2014 target_title must match another fact's title in this response or existing memory
+- An edge_type may appear in the manifest multiple times with different source_type/target_type; use the row whose types match your fact and target.`;
 var EMERGENT_EXTRA = `
 You may also return "ontology_updates" to propose new types:
 "ontology_updates": {
@@ -4685,14 +4952,18 @@ 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;
+      const candidates = resolveEdgeDefinitions(edge.edge_type, manifest).filter((d) => d.source_type.toLowerCase() === sourceType.toLowerCase());
+      if (candidates.length === 0) continue;
       const targetKey = normalizeTitleKey(edge.target_title);
       const target = titleIndex.get(targetKey);
       if (!target) continue;
-      if (def.target_type.toLowerCase() !== (target.okf_type ?? "").toLowerCase()) continue;
+      const def = candidates.find(
+        (d) => d.target_type.toLowerCase() === (target.okf_type ?? "").toLowerCase()
+      );
+      if (!def) continue;
       const wikiEdge = {
         id: generateId(),
         entity_id: entityId,
@@ -4701,8 +4972,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;
   }
 };
 
@@ -4942,6 +5215,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);
   }
@@ -5781,6 +6072,10 @@ 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;
@@ -5797,5 +6092,6 @@ exports.mapLibrarianOptionsToReadOptions = mapLibrarianOptionsToReadOptions;
 exports.parseEmbedding = parseEmbedding;
 exports.parseOkfBundle = parseOkfBundle;
 exports.validateLibrarianPromptTemplate = validateLibrarianPromptTemplate;
+exports.validateManifest = validateManifest;
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map