@equationalapplications/core-llm-wiki 4.15.3 → 4.17.0

package/dist/index.js

@@ -87,6 +87,13 @@ async function setupDatabase(db, prefix) {
       memory_checkpoint INTEGER NOT NULL DEFAULT 0
     );
 
+    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
@@ -196,6 +203,20 @@ var MIGRATIONS = [
         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
+        );
+      `);
+    }
   }
 ];
 for (let i = 1; i < MIGRATIONS.length; i++) {
@@ -319,8 +340,8 @@ var EntryRepository = class extends BaseRepository {
       `INSERT INTO ${this.prefix}entries (
         id, entity_id, title, body, tags, confidence, source_type,
         source_hash, source_ref, created_at, updated_at, last_accessed_at, access_count,
-        deleted_at, embedding_blob, embedding
-      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+        deleted_at, embedding_blob, embedding, okf_type
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
       ON CONFLICT(id) DO UPDATE SET
         entity_id = excluded.entity_id,
         title = excluded.title,
@@ -335,7 +356,8 @@ var EntryRepository = class extends BaseRepository {
         access_count = excluded.access_count,
         deleted_at = excluded.deleted_at,
         embedding_blob = CASE WHEN excluded.embedding_blob IS NULL THEN embedding_blob ELSE excluded.embedding_blob END,
-        embedding = NULL`,
+        embedding = NULL,
+        okf_type = excluded.okf_type`,
       [
         fact.id,
         fact.entity_id,
@@ -352,7 +374,8 @@ var EntryRepository = class extends BaseRepository {
         fact.access_count,
         fact.deleted_at ?? null,
         embeddingBlob ?? null,
-        null
+        null,
+        fact.okf_type ?? null
       ]
     );
     await this.outbox.push({
@@ -1384,6 +1407,11 @@ var EventRepository = class extends BaseRepository {
 };
 
 // src/repositories/EdgeRepository.ts
+var CONFIDENCE_RANK = {
+  tentative: 0,
+  inferred: 1,
+  certain: 2
+};
 var EdgeRepository = class extends BaseRepository {
   /**
    * Insert an edge, silently skipping on primary-key or uniqueness conflicts.
@@ -1414,21 +1442,196 @@ var EdgeRepository = class extends BaseRepository {
       `SELECT * FROM ${this.prefix}edges WHERE entity_id = ? ORDER BY created_at ASC`,
       [entityId]
     );
-    return rows.map((row) => ({
-      id: String(row.id),
-      entity_id: String(row.entity_id),
-      source_id: String(row.source_id),
-      target_id: String(row.target_id),
-      edge_type: String(row.edge_type),
-      created_at: Number(row.created_at)
-    }));
+    return rows.map(mapRowToEdge);
   }
   /** Hard delete — edges have no soft-delete concept, only presence/absence. `tx` is REQUIRED. */
   async bulkDeleteByEntityId(entityId, tx) {
     const executor = this.getExecutor(tx);
     await executor.runAsync(`DELETE FROM ${this.prefix}edges WHERE entity_id = ?`, [entityId]);
   }
+  /**
+   * Multi-hop traversal from `sourceId` via SQLite `WITH RECURSIVE`. All filtering,
+   * dead-ending, cycle-guarding, capping, and ordering happens in this one query.
+   * The anchor is validated (exists, right entity, not soft-deleted) but never gated
+   * by confidence/source_type — only nodes discovered beyond it are.
+   */
+  async getNeighborhood(entityId, sourceId, opts, tx) {
+    const executor = this.getExecutor(tx);
+    if (opts.edgeTypes && opts.edgeTypes.length === 0) {
+      const anchor = await executor.getFirstAsync(
+        `SELECT id FROM ${this.prefix}entries WHERE id = ? AND entity_id = ? AND deleted_at IS NULL`,
+        [sourceId, entityId]
+      );
+      return { nodeIds: anchor ? [anchor.id] : [], edges: [] };
+    }
+    const edgeTypesClause = opts.edgeTypes ? `e.edge_type IN (${opts.edgeTypes.map(() => "?").join(",")})` : "1=1";
+    const excludeSourceTypesPlaceholders = opts.excludeSourceTypes.map(() => "?").join(",");
+    const minConfidenceRank = CONFIDENCE_RANK[opts.minConfidence];
+    const sql = `
+      WITH RECURSIVE walk(node_id, depth, visited) AS (
+        SELECT id, 0, ',' || id || ','
+        FROM ${this.prefix}entries
+        WHERE id = ? AND entity_id = ? AND deleted_at IS NULL
+
+        UNION
+
+        SELECT
+          CASE WHEN e.source_id = w.node_id THEN e.target_id ELSE e.source_id END,
+          w.depth + 1,
+          w.visited || (CASE WHEN e.source_id = w.node_id THEN e.target_id ELSE e.source_id END) || ','
+        FROM walk w
+        JOIN ${this.prefix}edges e
+          ON e.entity_id = ?
+          AND (
+            (? != 'inbound'  AND e.source_id = w.node_id) OR
+            (? != 'outbound' AND e.target_id = w.node_id)
+          )
+          AND (${edgeTypesClause})
+        JOIN ${this.prefix}entries n
+          ON n.id = (CASE WHEN e.source_id = w.node_id THEN e.target_id ELSE e.source_id END)
+          AND n.entity_id = ?
+          AND n.deleted_at IS NULL
+          AND (
+            CASE n.confidence
+              WHEN 'tentative' THEN 0
+              WHEN 'inferred' THEN 1
+              WHEN 'certain' THEN 2
+              ELSE -1
+            END
+          ) >= ?
+          AND n.source_type NOT IN (${excludeSourceTypesPlaceholders})
+        WHERE w.depth < ?
+          AND instr(w.visited, ',' || (CASE WHEN e.source_id = w.node_id THEN e.target_id ELSE e.source_id END) || ',') = 0
+      )
+      SELECT node_id, MIN(depth) AS depth
+      FROM walk
+      GROUP BY node_id
+      ORDER BY depth ASC, (SELECT updated_at FROM ${this.prefix}entries WHERE id = node_id) DESC
+      LIMIT ?
+    `;
+    const params = [
+      sourceId,
+      entityId,
+      entityId,
+      opts.direction,
+      opts.direction,
+      ...opts.edgeTypes ?? [],
+      entityId,
+      minConfidenceRank,
+      ...opts.excludeSourceTypes,
+      opts.maxDepth,
+      opts.maxNodes
+    ];
+    const rows = await executor.getAllAsync(sql, params);
+    const nodeIds = rows.map((r) => r.node_id);
+    if (nodeIds.length === 0) return { nodeIds: [], edges: [] };
+    const valueRows = nodeIds.map(() => "(?)").join(", ");
+    const edgeRows = await executor.getAllAsync(
+      `WITH neighborhood(node_id) AS (VALUES ${valueRows})
+       SELECT e.* FROM ${this.prefix}edges e
+       JOIN neighborhood ns ON e.source_id = ns.node_id
+       JOIN neighborhood nt ON e.target_id = nt.node_id
+       WHERE e.entity_id = ?`,
+      [...nodeIds, entityId]
+    );
+    return { nodeIds, edges: edgeRows.map(mapRowToEdge) };
+  }
 };
+function mapRowToEdge(row) {
+  return {
+    id: String(row.id),
+    entity_id: String(row.entity_id),
+    source_id: String(row.source_id),
+    target_id: String(row.target_id),
+    edge_type: String(row.edge_type),
+    created_at: Number(row.created_at)
+  };
+}
+
+// src/utils/ontology.ts
+function emptyManifest() {
+  return { node_types: [], edge_types: [] };
+}
+function normalizeTitleKey(title) {
+  return title.trim().toLowerCase().replace(/\s+/g, " ");
+}
+function resolveNodeType(raw, manifest) {
+  const slug = raw.trim();
+  if (!slug) return null;
+  const hit = manifest.node_types.find((n) => n.type.toLowerCase() === slug.toLowerCase());
+  return hit?.type ?? null;
+}
+function resolveEdgeDefinition(rawEdgeType, manifest) {
+  const slug = rawEdgeType.trim();
+  if (!slug) return null;
+  return manifest.edge_types.find((e) => e.type.toLowerCase() === slug.toLowerCase()) ?? null;
+}
+function validateManifest(manifest) {
+  const nodeSlugs = /* @__PURE__ */ new Set();
+  for (const node of manifest.node_types ?? []) {
+    const type = node.type?.trim();
+    if (!type) throw new Error("Ontology node type slug must be non-empty");
+    const key = type.toLowerCase();
+    if (nodeSlugs.has(key)) throw new Error(`Duplicate node type: ${type}`);
+    nodeSlugs.add(key);
+  }
+  const edgeSlugs = /* @__PURE__ */ new Set();
+  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`);
+    }
+  }
+}
+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()));
+  for (const node of updates.node_types ?? []) {
+    const type = node?.type?.trim();
+    if (!type) continue;
+    const key = type.toLowerCase();
+    if (nodeSlugs.has(key)) continue;
+    node_types.push({ type, description: String(node.description ?? "") });
+    nodeSlugs.add(key);
+  }
+  for (const edge of updates.edge_types ?? []) {
+    const edgeType = 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 (!nodeSlugs.has(sourceType.toLowerCase()) || !nodeSlugs.has(targetType.toLowerCase())) continue;
+    edge_types.push({
+      type: edgeType,
+      source_type: sourceType,
+      target_type: targetType,
+      description: String(edge.description ?? "")
+    });
+    edgeSlugs.add(edgeKey);
+  }
+  return { node_types, edge_types };
+}
+function validateInlineEdges(sourceType, _targetType, edges, manifest) {
+  if (!Array.isArray(edges)) return [];
+  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 });
+  }
+  return valid;
+}
 
 // src/repositories/MetadataRepository.ts
 var MetadataRepository = class extends BaseRepository {
@@ -1528,6 +1731,44 @@ var MetadataRepository = class extends BaseRepository {
     );
     return rows.map((r) => r.entity_id);
   }
+  async getManifest(entityId, tx) {
+    const executor = this.getExecutor(tx);
+    const row = await executor.getFirstAsync(`SELECT mode, manifest_json FROM ${this.prefix}entity_manifests WHERE entity_id = ?`, [entityId]);
+    if (!row) return null;
+    if (row.mode !== "off" && row.mode !== "strict" && row.mode !== "emergent") {
+      throw new Error(`Invalid ontology mode for entity ${entityId}: ${JSON.stringify(row.mode)}`);
+    }
+    let manifest;
+    try {
+      manifest = JSON.parse(row.manifest_json);
+    } catch (error) {
+      throw new Error(`Invalid manifest_json for entity ${entityId}: ${error.message}`);
+    }
+    validateManifest(manifest);
+    return {
+      mode: row.mode,
+      manifest
+    };
+  }
+  async setManifest(entityId, data, tx) {
+    validateManifest(data.manifest);
+    const executor = this.getExecutor(tx);
+    await executor.runAsync(
+      `INSERT INTO ${this.prefix}entity_manifests (entity_id, mode, manifest_json, updated_at)
+       VALUES (?, ?, ?, ?)
+       ON CONFLICT(entity_id) DO UPDATE SET mode = excluded.mode, manifest_json = excluded.manifest_json, updated_at = excluded.updated_at`,
+      [entityId, data.mode, JSON.stringify(data.manifest), Date.now()]
+    );
+  }
+  async mergeManifestUpdates(entityId, updates, tx) {
+    const current = await this.getManifest(entityId, tx) ?? {
+      mode: "emergent",
+      manifest: emptyManifest()
+    };
+    const merged = mergeOntologyUpdates(current.manifest, updates);
+    await this.setManifest(entityId, { mode: current.mode, manifest: merged }, tx);
+    return merged;
+  }
 };
 
 // src/utils/cosine.ts
@@ -2343,30 +2584,54 @@ var PromptService = class {
       return typeof value === "string" ? value : JSON.stringify(value, null, 2);
     });
   }
-  buildIngestPrompt(documentChunk, runtimeOverride) {
+  hasOntologyPlaceholders(template) {
+    return /\{\{\s*ontology(?:Manifest|ModeInstructions)\s*\}\}/.test(template);
+  }
+  buildSystemPrompt(template, variables, ontologyContext) {
+    const shouldHydrate = Object.keys(variables).some(
+      (key) => new RegExp(`\\{\\{\\s*${key}\\s*\\}\\}`).test(template)
+    ) || ontologyContext != null && this.hasOntologyPlaceholders(template);
+    const hydrated = shouldHydrate ? this.hydrate(template, { ...variables, ...ontologyContext ?? {} }) : template;
+    return this.hasOntologyPlaceholders(template) ? ontologyContext != null ? hydrated : hydrated.replace(/\{\{\s*ontology(?:Manifest|ModeInstructions)\s*\}\}/g, "") : this.appendOntology(hydrated, ontologyContext);
+  }
+  appendOntology(systemPrompt, ctx) {
+    if (!ctx) return systemPrompt;
+    return `${systemPrompt}
+
+${ctx.ontologyModeInstructions}`;
+  }
+  buildIngestPrompt(documentChunk, runtimeOverride, ontologyContext) {
     const template = runtimeOverride ?? this.globalOverrides?.ingestSystemPrompt ?? INGEST_SYSTEM_PROMPT;
-    if (/\{\{\s*documentChunk\s*\}\}/.test(template)) {
+    const hasDocumentChunk = /\{\{\s*documentChunk\s*\}\}/.test(template);
+    if (hasDocumentChunk || this.hasOntologyPlaceholders(template)) {
       return {
-        systemPrompt: this.hydrate(template, { documentChunk }),
-        userPrompt: "Please extract the facts."
+        systemPrompt: this.buildSystemPrompt(template, { documentChunk }, ontologyContext),
+        userPrompt: hasDocumentChunk ? "Please extract the facts." : `Document Chunk:
+${documentChunk}`
       };
     }
     return {
-      systemPrompt: template,
+      systemPrompt: this.appendOntology(template, ontologyContext),
       userPrompt: `Document Chunk:
 ${documentChunk}`
     };
   }
-  buildLibrarianPrompt(events, currentFacts, runtimeOverride) {
+  buildLibrarianPrompt(events, currentFacts, runtimeOverride, ontologyContext) {
     const template = runtimeOverride ?? this.globalOverrides?.librarianSystemPrompt ?? LIBRARIAN_SYSTEM_PROMPT;
-    if (/\{\{\s*events\s*\}\}/.test(template) || /\{\{\s*currentFacts\s*\}\}/.test(template)) {
+    const hasEvents = /\{\{\s*events\s*\}\}/.test(template);
+    const hasCurrentFacts = /\{\{\s*currentFacts\s*\}\}/.test(template);
+    if (hasEvents || hasCurrentFacts || this.hasOntologyPlaceholders(template)) {
       return {
-        systemPrompt: this.hydrate(template, { events, currentFacts }),
-        userPrompt: "Please synthesize the context."
+        systemPrompt: this.buildSystemPrompt(template, { events, currentFacts }, ontologyContext),
+        userPrompt: hasEvents || hasCurrentFacts ? "Please synthesize the context." : `Events:
+${JSON.stringify(events, null, 2)}
+
+Current Facts:
+${JSON.stringify(currentFacts, null, 2)}`
       };
     }
     return {
-      systemPrompt: template,
+      systemPrompt: this.appendOntology(template, ontologyContext),
       userPrompt: `Events:
 ${JSON.stringify(events, null, 2)}
 
@@ -2399,7 +2664,7 @@ The following document anchors are provided for contradiction detection only. Do
 
 // src/services/IngestionService.ts
 var IngestionService = class {
-  constructor(db, prefix, options, entryRepo, searchService, jobManager, embeddingService, promptService) {
+  constructor(db, prefix, options, entryRepo, searchService, jobManager, embeddingService, promptService, ontologyService) {
     this.db = db;
     this.prefix = prefix;
     this.options = options;
@@ -2407,6 +2672,7 @@ var IngestionService = class {
     this.searchService = searchService;
     this.jobManager = jobManager;
     this.embeddingService = embeddingService;
+    this.ontologyService = ontologyService;
     this.promptService = promptService ?? new PromptService(this.options.config?.prompts);
   }
   async ingestDocument(entityId, params) {
@@ -2431,23 +2697,33 @@ var IngestionService = class {
       if (chunks.length === 0) return { truncated: false, chunks: 0 };
       const chunkResults = await withConcurrency(
         chunks.map((chunk) => async () => {
-          const { systemPrompt, userPrompt } = this.promptService.buildIngestPrompt(chunk, params.promptOverride);
+          const ontologyContext = await this.ontologyService?.buildPromptContext(entityId) ?? null;
+          const { systemPrompt, userPrompt } = this.promptService.buildIngestPrompt(
+            chunk,
+            params.promptOverride,
+            ontologyContext
+          );
           const responseText = await this.options.llmProvider.generateText({ systemPrompt, userPrompt });
           const result = parseJsonResponse(responseText);
-          return (Array.isArray(result.facts) ? result.facts : []).map(validateFact).filter((f) => f !== null);
+          return {
+            facts: (Array.isArray(result.facts) ? result.facts : []).map(validateFact).filter((f) => f !== null),
+            ontology_updates: result.ontology_updates
+          };
         }),
         chunkConcurrency
       );
       const seen = /* @__PURE__ */ new Set();
-      const allValidFacts = [];
-      for (const facts of chunkResults) {
-        for (const fact of facts) {
-          const normalized = fact.title.trim().toLowerCase().replace(/\s+/g, " ");
-          if (!seen.has(normalized)) {
-            seen.add(normalized);
-            allValidFacts.push(fact);
+      const orderedChunkFacts = [];
+      for (const chunkResult of chunkResults) {
+        const dedupedFacts = [];
+        for (const fact of chunkResult.facts) {
+          const normalizedTitle = normalizeTitleKey(fact.title);
+          if (!seen.has(normalizedTitle)) {
+            seen.add(normalizedTitle);
+            dedupedFacts.push(fact);
           }
         }
+        orderedChunkFacts.push({ facts: dedupedFacts, ontology_updates: chunkResult.ontology_updates });
       }
       const now = Date.now();
       const insertedFacts = [];
@@ -2455,26 +2731,63 @@ var IngestionService = class {
       await this.db.withTransactionAsync(async (tx) => {
         deletedSourceFactIds.push(...await this.entryRepo.findIdsBySource(entityId, sourceRef, null, tx, false));
         await this.entryRepo.softDeleteBySource(entityId, tx, sourceRef, null);
-        for (const fact of allValidFacts) {
-          const id = generateId("fact_");
-          const wikiFact = {
-            id,
-            entity_id: entityId,
-            title: fact.title,
-            body: fact.body,
-            tags: fact.tags,
-            confidence: fact.confidence,
-            source_type: "immutable_document",
-            source_hash: sourceHash,
-            source_ref: sourceRef,
-            created_at: now,
-            updated_at: now,
-            last_accessed_at: null,
-            access_count: 0,
-            deleted_at: null
-          };
-          await this.entryRepo.upsert(wikiFact, tx);
-          insertedFacts.push({ id, entity_id: entityId, title: fact.title, body: fact.body, tags: JSON.stringify(fact.tags) });
+        const titleIndex = /* @__PURE__ */ new Map();
+        const pendingEdges = [];
+        const existingFacts = await this.entryRepo.findRecentByEntityId(entityId, 500, tx);
+        for (const existing of existingFacts) {
+          titleIndex.set(normalizeTitleKey(existing.title), {
+            id: existing.id,
+            okf_type: existing.okf_type ?? null
+          });
+        }
+        let ontologyState = await this.ontologyService?.getEffectiveState(entityId, tx) ?? { mode: "off", manifest: { node_types: [], edge_types: [] } };
+        let { mode, manifest } = ontologyState;
+        for (const { facts, ontology_updates } of orderedChunkFacts) {
+          if (mode === "emergent" && ontology_updates && this.ontologyService) {
+            manifest = await this.ontologyService.mergeEmergentUpdates(entityId, ontology_updates, tx);
+            ontologyState = await this.ontologyService.getEffectiveState(entityId, tx);
+            mode = ontologyState.mode;
+          }
+          for (const fact of facts) {
+            const ontologyFact = fact;
+            const normalized = this.ontologyService?.validateAndNormalizeFact(ontologyFact, manifest) ?? { okf_type: null, edges: [] };
+            const id = generateId("fact_");
+            const wikiFact = {
+              id,
+              entity_id: entityId,
+              title: fact.title,
+              body: fact.body,
+              tags: fact.tags,
+              confidence: fact.confidence,
+              source_type: "immutable_document",
+              source_hash: sourceHash,
+              source_ref: sourceRef,
+              created_at: now,
+              updated_at: now,
+              last_accessed_at: null,
+              access_count: 0,
+              deleted_at: null,
+              okf_type: normalized.okf_type
+            };
+            await this.entryRepo.upsert(wikiFact, tx);
+            insertedFacts.push({ id, entity_id: entityId, title: fact.title, body: fact.body, tags: JSON.stringify(fact.tags) });
+            titleIndex.set(normalizeTitleKey(fact.title), { id, okf_type: normalized.okf_type });
+            if (normalized.edges.length > 0) {
+              pendingEdges.push({ sourceId: id, sourceType: normalized.okf_type, edges: normalized.edges });
+            }
+          }
+        }
+        for (const item of pendingEdges) {
+          await this.ontologyService?.resolveAndPersistEdges(
+            entityId,
+            item.sourceId,
+            item.sourceType,
+            item.edges ?? [],
+            manifest,
+            titleIndex,
+            tx,
+            now
+          );
         }
       });
       await this.searchService.sync(entityId);
@@ -2501,7 +2814,7 @@ var IngestionService = class {
 var FUZZY_THRESHOLD = 0.5;
 var MIN_TOKENS_TO_QUALIFY = 3;
 var MaintenanceService = class {
-  constructor(db, prefix, options, entryRepo, taskRepo, eventRepo, metadataRepo, searchService, jobManager, embeddingService, promptService) {
+  constructor(db, prefix, options, entryRepo, taskRepo, eventRepo, metadataRepo, searchService, jobManager, embeddingService, promptService, ontologyService) {
     this.db = db;
     this.prefix = prefix;
     this.options = options;
@@ -2512,6 +2825,7 @@ var MaintenanceService = class {
     this.searchService = searchService;
     this.jobManager = jobManager;
     this.embeddingService = embeddingService;
+    this.ontologyService = ontologyService;
     this.promptService = promptService ?? new PromptService(this.options.config?.prompts);
   }
   async runPrune(entityId, options) {
@@ -2734,21 +3048,36 @@ var MaintenanceService = class {
         tags: typeof rest.tags === "string" ? JSON.parse(rest.tags) : rest.tags
       };
     });
+    const ontologyContext = await this.ontologyService?.buildPromptContext(entityId) ?? null;
     const { systemPrompt, userPrompt } = this.promptService.buildLibrarianPrompt(
       events.reverse(),
       currentFacts,
-      promptOverride
+      promptOverride,
+      ontologyContext
     );
     const responseText = await this.options.llmProvider.generateText({ systemPrompt, userPrompt });
     const result = parseJsonResponse(responseText);
     const facts = Array.isArray(result.facts) ? result.facts : [];
     const tasks = Array.isArray(result.tasks) ? result.tasks : [];
+    const ontologyUpdates = result.ontology_updates;
     const validFacts = facts.map(validateFact).filter((f) => f !== null);
     const validTasks = tasks.map(validateTask).filter((t) => t !== null);
     const now = Date.now();
     const insertedFacts = [];
     await this.db.withTransactionAsync(async (tx) => {
+      let { mode, manifest } = await this.ontologyService?.getEffectiveState(entityId, tx) ?? { mode: "off", manifest: { node_types: [], edge_types: [] } };
+      if (mode === "emergent" && ontologyUpdates && this.ontologyService) {
+        manifest = await this.ontologyService.mergeEmergentUpdates(entityId, ontologyUpdates, tx);
+      }
+      const titleIndex = /* @__PURE__ */ new Map();
+      for (const existing of currentFactsRows) {
+        titleIndex.set(normalizeTitleKey(existing.title), {
+          id: existing.id,
+          okf_type: existing.okf_type ?? null
+        });
+      }
       const factsForDedupe = await this.entryRepo.findRecentByEntityId(entityId, 100, tx);
+      const pendingEdges = [];
       for (const fact of validFacts) {
         const newTokens = titleTokens(fact.title);
         let skip = false;
@@ -2765,6 +3094,8 @@ var MaintenanceService = class {
           }
         }
         if (skip) continue;
+        const ontologyFact = fact;
+        const normalized = this.ontologyService?.validateAndNormalizeFact(ontologyFact, manifest) ?? { okf_type: null, edges: [] };
         const id = generateId("fact_");
         const factObj = {
           id,
@@ -2780,11 +3111,28 @@ var MaintenanceService = class {
           updated_at: now,
           last_accessed_at: null,
           access_count: 0,
-          deleted_at: null
+          deleted_at: null,
+          okf_type: normalized.okf_type
         };
         await this.entryRepo.upsert(factObj, tx);
         insertedFacts.push({ id, entity_id: entityId, title: fact.title, body: fact.body, tags: JSON.stringify(fact.tags) });
         factsForDedupe.push(factObj);
+        titleIndex.set(normalizeTitleKey(fact.title), { id, okf_type: normalized.okf_type });
+        if (normalized.edges.length > 0) {
+          pendingEdges.push({ sourceId: id, sourceType: normalized.okf_type, edges: normalized.edges });
+        }
+      }
+      for (const item of pendingEdges) {
+        await this.ontologyService?.resolveAndPersistEdges(
+          entityId,
+          item.sourceId,
+          item.sourceType,
+          item.edges ?? [],
+          manifest,
+          titleIndex,
+          tx,
+          now
+        );
       }
       for (const task of validTasks) {
         const id = generateId("task_");
@@ -4121,6 +4469,145 @@ var WriteService = class {
   }
 };
 
+// src/prompts/ontology.ts
+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`;
+var EMERGENT_EXTRA = `
+You may also return "ontology_updates" to propose new types:
+"ontology_updates": {
+  "node_types": [{ "type": "slug", "description": "..." }],
+  "edge_types": [{ "type": "slug", "source_type": "...", "target_type": "...", "description": "..." }]
+}
+Only propose types not already in the manifest. Do not redefine existing types.`;
+function buildOntologyPromptAppendix(mode, manifestJson) {
+  const strictRules = mode === "strict" ? "STRICT MODE: Use ONLY types defined in the manifest. If a fact does not fit any node_type, omit okf_type and edges entirely." : "EMERGENT MODE: Prefer manifest types. You may propose new types via ontology_updates when necessary.";
+  const fallback = "If okf_type or an edge is invalid, omit them rather than inventing unlisted types.";
+  const ontologyModeInstructions = [
+    "## Ontology constraints",
+    strictRules,
+    fallback,
+    FACT_ONTOLOGY_FIELDS,
+    mode === "emergent" ? EMERGENT_EXTRA : "",
+    "Manifest:",
+    manifestJson
+  ].filter(Boolean).join("\n");
+  return { ontologyManifest: manifestJson, ontologyModeInstructions };
+}
+
+// src/services/OntologyService.ts
+var OntologyService = class {
+  constructor(metadataRepo, edgeRepo, ontologyConfig) {
+    this.metadataRepo = metadataRepo;
+    this.edgeRepo = edgeRepo;
+    this.ontologyConfig = ontologyConfig;
+    this.cache = /* @__PURE__ */ new Map();
+  }
+  resolveMode(storedMode) {
+    return storedMode ?? this.ontologyConfig?.mode ?? "off";
+  }
+  invalidateCache(entityId) {
+    this.cache.delete(entityId);
+  }
+  async getEffectiveState(entityId, tx) {
+    if (!tx) {
+      const cached = this.cache.get(entityId);
+      if (cached) return cached;
+    }
+    const row = await this.metadataRepo.getManifest(entityId, tx);
+    if (row) {
+      const state = { mode: this.resolveMode(row.mode), manifest: row.manifest };
+      if (!tx) this.cache.set(entityId, state);
+      return state;
+    }
+    const seed = this.ontologyConfig?.seedManifests?.[entityId];
+    if (seed) {
+      const state = {
+        mode: this.resolveMode(seed.mode),
+        manifest: seed.manifest
+      };
+      if (tx) {
+        await this.metadataRepo.setManifest(entityId, state, tx);
+      } else {
+        this.cache.set(entityId, state);
+      }
+      return state;
+    }
+    return { mode: "off", manifest: emptyManifest() };
+  }
+  async buildPromptContext(entityId) {
+    const { mode, manifest } = await this.getEffectiveState(entityId);
+    if (mode === "off") return null;
+    const manifestJson = JSON.stringify(manifest, null, 2);
+    return buildOntologyPromptAppendix(mode, manifestJson);
+  }
+  async mergeEmergentUpdates(entityId, updates, tx) {
+    const merged = await this.metadataRepo.mergeManifestUpdates(entityId, updates, tx);
+    this.invalidateCache(entityId);
+    return merged;
+  }
+  validateAndNormalizeFact(fact, manifest) {
+    const rawType = typeof fact.okf_type === "string" ? fact.okf_type : "";
+    const canonical = resolveNodeType(rawType, manifest);
+    if (!canonical) return { okf_type: null, edges: [] };
+    const edges = validateInlineEdges(canonical, null, fact.edges ?? [], manifest);
+    return { okf_type: canonical, edges };
+  }
+  async resolveAndPersistEdges(entityId, sourceId, sourceType, edges, manifest, titleIndex, tx, now) {
+    if (!sourceType || edges.length === 0) return;
+    for (const edge of edges) {
+      const def = resolveEdgeDefinition(edge.edge_type, manifest);
+      if (!def || def.source_type.toLowerCase() !== sourceType.toLowerCase()) 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 wikiEdge = {
+        id: generateId(),
+        entity_id: entityId,
+        source_id: sourceId,
+        target_id: target.id,
+        edge_type: def.type,
+        created_at: now
+      };
+      await this.edgeRepo.addIgnoreDuplicate(wikiEdge, tx);
+    }
+  }
+};
+
+// src/services/GraphTraversalService.ts
+var GraphTraversalService = class {
+  constructor(edgeRepo, entryRepo, config) {
+    this.edgeRepo = edgeRepo;
+    this.entryRepo = entryRepo;
+    this.config = config;
+  }
+  async traverseGraph(entityId, options) {
+    const fallbackMaxNodes = 20;
+    const rawConfigDefault = this.config.maxTraversalNodes ?? fallbackMaxNodes;
+    const defaultMaxNodes = Number.isFinite(rawConfigDefault) && rawConfigDefault >= 1 ? Math.floor(rawConfigDefault) : fallbackMaxNodes;
+    const rawMaxNodes = options.maxTraversalNodes ?? defaultMaxNodes;
+    const maxNodes = Number.isFinite(rawMaxNodes) && rawMaxNodes >= 1 ? Math.floor(rawMaxNodes) : defaultMaxNodes;
+    const opts = {
+      maxDepth: Math.max(1, Math.min(options.maxDepth ?? 1, 3)),
+      direction: options.direction ?? this.config.traversalDirection ?? "both",
+      edgeTypes: options.edgeTypes,
+      minConfidence: options.minTraversalConfidence ?? this.config.minTraversalConfidence ?? "tentative",
+      excludeSourceTypes: options.excludeSourceTypes ?? this.config.excludeSourceTypes ?? [],
+      maxNodes
+    };
+    const { nodeIds, edges } = await this.edgeRepo.getNeighborhood(entityId, options.sourceId, opts);
+    if (nodeIds.length === 0) return { nodes: [], edges: [] };
+    const nodes = await this.entryRepo.findByIds(nodeIds, [entityId]);
+    const hydratedIds = new Set(nodes.map((node) => node.id));
+    const filteredEdges = edges.filter(
+      (edge) => hydratedIds.has(edge.source_id) && hydratedIds.has(edge.target_id)
+    );
+    return { nodes, edges: filteredEdges };
+  }
+};
+
 // src/WikiMemory.ts
 var TABLE_PREFIX_PATTERN = /^[A-Za-z][A-Za-z0-9_]{0,30}_$/;
 var _testAccessNonTestEnvWarned;
@@ -4142,6 +4629,11 @@ var WikiMemory = class {
     this.eventRepo = new EventRepository(db, this.prefix);
     this.edgeRepo = new EdgeRepository(db, this.prefix);
     this.metadataRepo = new MetadataRepository(db, this.prefix);
+    this.ontologyService = new OntologyService(
+      this.metadataRepo,
+      this.edgeRepo,
+      options.config?.ontology
+    );
     this.embeddingService = new EmbeddingService(this.db, this.options, this.entryRepo, this.metadataRepo);
     this.searchService = new SearchService(this.entryRepo);
     this.jobManager = new JobManager(this.prefix);
@@ -4154,7 +4646,8 @@ var WikiMemory = class {
       this.searchService,
       this.jobManager,
       this.embeddingService,
-      this.promptService
+      this.promptService,
+      this.ontologyService
     );
     this.maintenanceService = new MaintenanceService(
       this.db,
@@ -4167,7 +4660,8 @@ var WikiMemory = class {
       this.searchService,
       this.jobManager,
       this.embeddingService,
-      this.promptService
+      this.promptService,
+      this.ontologyService
     );
     this.importExportService = new ImportExportService(
       this.db,
@@ -4197,6 +4691,11 @@ var WikiMemory = class {
       this.jobManager,
       this.maintenanceService
     );
+    this.graphTraversalService = new GraphTraversalService(
+      this.edgeRepo,
+      this.entryRepo,
+      this.options.config ?? {}
+    );
   }
   /**
    * Explicit escape hatch for test suites: typed access to composed services for mocks/spies.
@@ -4217,6 +4716,7 @@ var WikiMemory = class {
       searchService: this.searchService,
       writeService: this.writeService,
       promptService: this.promptService,
+      graphTraversalService: this.graphTraversalService,
       entryRepo: this.entryRepo,
       metadataRepo: this.metadataRepo,
       jobManager: this.jobManager
@@ -4287,6 +4787,9 @@ var WikiMemory = class {
   async read(entityId, query, options) {
     return this.retrievalService.read(entityId, query, options);
   }
+  async traverseGraph(entityId, options) {
+    return this.graphTraversalService.traverseGraph(entityId, options);
+  }
   async getMemoryBundle(entityId) {
     return this.importExportService.getFullBundle(entityId, { maxEvents: 10 });
   }
@@ -4362,6 +4865,34 @@ var WikiMemory = class {
   async markOutboxEventsProcessed(eventIds) {
     await this.outboxRepo.acknowledge(eventIds);
   }
+  /**
+   * Returns the effective ontology mode and manifest for an entity.
+   * Resolution order: persisted DB row → `WikiConfig.ontology.seedManifests[entityId]` → `null`.
+   */
+  async getOntologyManifest(entityId) {
+    const row = await this.metadataRepo.getManifest(entityId);
+    if (row) return { mode: this.ontologyService.resolveMode(row.mode), manifest: row.manifest };
+    const seed = this.options.config?.ontology?.seedManifests?.[entityId];
+    if (seed) {
+      return {
+        mode: this.ontologyService.resolveMode(seed.mode),
+        manifest: seed.manifest
+      };
+    }
+    return null;
+  }
+  /**
+   * Seeds or replaces an entity's ontology manifest and optional mode override.
+   * Validates manifest invariants (unique type slugs, edge endpoints reference node types).
+   * Invalidates the in-memory ontology cache for this entity.
+   */
+  async setOntologyManifest(entityId, manifest, options) {
+    const mode = options?.mode ?? this.ontologyService.resolveMode();
+    await this.db.withTransactionAsync(
+      (tx) => this.metadataRepo.setManifest(entityId, { mode, manifest }, tx)
+    );
+    this.ontologyService.invalidateCache(entityId);
+  }
 };
 _testAccessNonTestEnvWarned = new WeakMap();
 
@@ -4486,6 +5017,38 @@ function formatContext(bundle, options) {
   return lines.join("\n");
 }
 
+// src/utils/formatGraphContext.ts
+function formatGraphContext(neighborhood) {
+  const { nodes, edges } = neighborhood;
+  if (nodes.length === 0) return "";
+  const nodeById = new Map(nodes.map((n) => [n.id, n]));
+  const nodeIndex = new Map(nodes.map((n, i) => [n.id, i]));
+  const lines = [];
+  for (const node of nodes) {
+    lines.push(`[${node.okf_type ?? "fact"}] ${node.title} (ID: ${node.id})`);
+    const outbound = edgesByDirection(edges, node.id, "source_id", nodeById, nodeIndex);
+    const inbound = edgesByDirection(edges, node.id, "target_id", nodeById, nodeIndex);
+    for (const { edge, other } of outbound) {
+      lines.push(`  -[${edge.edge_type}]-> [${other.okf_type ?? "fact"}] ${other.title}`);
+    }
+    for (const { edge, other } of inbound) {
+      lines.push(`  <-[${edge.edge_type}]- [${other.okf_type ?? "fact"}] ${other.title}`);
+    }
+  }
+  return lines.join("\n");
+}
+function edgesByDirection(edges, nodeId, endpoint, nodeById, nodeIndex) {
+  const otherEndpoint = endpoint === "source_id" ? "target_id" : "source_id";
+  return edges.filter((e) => e[endpoint] === nodeId).filter((e) => {
+    const otherId = e[otherEndpoint];
+    const selfIdx = nodeIndex.get(nodeId);
+    const otherIdx = nodeIndex.get(otherId);
+    return otherIdx !== void 0 && selfIdx < otherIdx;
+  }).map((edge) => ({ edge, other: nodeById.get(edge[otherEndpoint]) })).sort(
+    (a, b) => a.edge.edge_type.localeCompare(b.edge.edge_type) || a.other.title.localeCompare(b.other.title) || a.other.id.localeCompare(b.other.id) || a.edge.id.localeCompare(b.edge.id)
+  );
+}
+
 // src/utils/sanitizeForFilename.ts
 function shortHash(value) {
   let h1 = 5381;
@@ -5002,6 +5565,7 @@ exports.WikiBusyError = WikiBusyError;
 exports.WikiMemory = WikiMemory;
 exports.createWiki = createWiki;
 exports.formatContext = formatContext;
+exports.formatGraphContext = formatGraphContext;
 exports.formatMemoryDump = formatMemoryDump;
 exports.formatOkfBundle = formatOkfBundle;
 exports.hydrateLibrarianPrompt = hydrateLibrarianPrompt;