@equationalapplications/core-llm-wiki 4.16.0 → 4.17.1

package/dist/index.d.mts

@@ -1,10 +1,17 @@
-import { M as MemoryBundle, F as FormatContextOptions, a as MemoryDump, b as FormattedMemoryDump, R as ReadOptions, S as SQLiteAdapter, W as WikiOptions, c as WikiMemory } from './testing-BMsplvLy.mjs';
-export { E as EntityStatus, d as ExtractedFact, e as ExtractedFactEdge, f as ExtractedFactWithOntology, g as ExtractedTask, H as HOOK_TIMEOUT_MARKER, L as LLMProvider, O as OntologyConfig, h as OntologyEdgeType, i as OntologyManifest, j as OntologyMode, k as OntologyNodeType, l as OntologyPromptContext, m as OntologyUpdates, P as PromptOverrides, n as PromptService, o as PrunePartialFailureError, V as VectorRanker, p as VectorRankerFallback, q as VectorRankerRankArgs, r as VectorRankerSemanticResult, s as WikiBusyError, t as WikiBusyOperation, u as WikiCheckpoint, v as WikiConfig, w as WikiEdge, x as WikiEvent, y as WikiFact, z as WikiMemoryTestAccess, A as WikiOutboxEvent, B as WikiTask } from './testing-BMsplvLy.mjs';
+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-D02cdI9A.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 } from './testing-D02cdI9A.mjs';
 import { OkfFile } from '@equationalapplications/core-okf';
 import 'minisearch';
 
 declare function formatContext(bundle: MemoryBundle, options?: FormatContextOptions): string;
 
+/**
+ * Pure presenter — dense text serialization of a GraphNeighborhood for LLM prompt
+ * injection. Deterministic: same input always produces byte-identical output
+ * (matters for prompt caching).
+ */
+declare function formatGraphContext(neighborhood: GraphNeighborhood): string;
+
 declare function formatMemoryDump(dump: MemoryDump): FormattedMemoryDump;
 
 declare function formatOkfBundle(dump: MemoryDump): {
@@ -19,6 +26,16 @@ declare function parseOkfBundle(entityId: string, files: OkfFile[], options?: Ok
 
 declare function parseEmbedding(blob: Uint8Array | null | undefined, text: string | null | undefined): Float32Array | null;
 
+type GetRandomValues = (bytes: Uint8Array) => void;
+/**
+ * Inject a platform-specific `getRandomValues` implementation.
+ * Call this once at module load time from the platform adapter
+ * (e.g. expo-crypto's getRandomValues) when the global `crypto` API is
+ * absent — Hermes / React Native being the primary case.
+ * Pass `null` to clear a previously injected source.
+ */
+declare function configureRandomSource(fn: GetRandomValues | null): void;
+
 interface LibrarianOptions {
     /** If provided, replaces the default Librarian system instructions. */
     systemPrompt?: string;
@@ -43,4 +60,4 @@ declare function mapLibrarianOptionsToReadOptions(options: LibrarianOptions): Pi
 
 declare function createWiki(db: SQLiteAdapter, options: WikiOptions): WikiMemory;
 
-export { DEFAULT_LIBRARIAN_SYNTHESIS_PROMPT, FormatContextOptions, FormattedMemoryDump, type LibrarianOptions, type LibrarianPromptVariables, MemoryBundle, MemoryDump, type OkfImportOptions, ReadOptions, SQLiteAdapter, WikiMemory, WikiOptions, createWiki, formatContext, formatMemoryDump, formatOkfBundle, hydrateLibrarianPrompt, mapLibrarianOptionsToReadOptions, parseEmbedding, parseOkfBundle, validateLibrarianPromptTemplate };
+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 };

package/dist/index.d.ts

@@ -1,10 +1,17 @@
-import { M as MemoryBundle, F as FormatContextOptions, a as MemoryDump, b as FormattedMemoryDump, R as ReadOptions, S as SQLiteAdapter, W as WikiOptions, c as WikiMemory } from './testing-BMsplvLy.js';
-export { E as EntityStatus, d as ExtractedFact, e as ExtractedFactEdge, f as ExtractedFactWithOntology, g as ExtractedTask, H as HOOK_TIMEOUT_MARKER, L as LLMProvider, O as OntologyConfig, h as OntologyEdgeType, i as OntologyManifest, j as OntologyMode, k as OntologyNodeType, l as OntologyPromptContext, m as OntologyUpdates, P as PromptOverrides, n as PromptService, o as PrunePartialFailureError, V as VectorRanker, p as VectorRankerFallback, q as VectorRankerRankArgs, r as VectorRankerSemanticResult, s as WikiBusyError, t as WikiBusyOperation, u as WikiCheckpoint, v as WikiConfig, w as WikiEdge, x as WikiEvent, y as WikiFact, z as WikiMemoryTestAccess, A as WikiOutboxEvent, B as WikiTask } from './testing-BMsplvLy.js';
+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-D02cdI9A.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 } from './testing-D02cdI9A.js';
 import { OkfFile } from '@equationalapplications/core-okf';
 import 'minisearch';
 
 declare function formatContext(bundle: MemoryBundle, options?: FormatContextOptions): string;
 
+/**
+ * Pure presenter — dense text serialization of a GraphNeighborhood for LLM prompt
+ * injection. Deterministic: same input always produces byte-identical output
+ * (matters for prompt caching).
+ */
+declare function formatGraphContext(neighborhood: GraphNeighborhood): string;
+
 declare function formatMemoryDump(dump: MemoryDump): FormattedMemoryDump;
 
 declare function formatOkfBundle(dump: MemoryDump): {
@@ -19,6 +26,16 @@ declare function parseOkfBundle(entityId: string, files: OkfFile[], options?: Ok
 
 declare function parseEmbedding(blob: Uint8Array | null | undefined, text: string | null | undefined): Float32Array | null;
 
+type GetRandomValues = (bytes: Uint8Array) => void;
+/**
+ * Inject a platform-specific `getRandomValues` implementation.
+ * Call this once at module load time from the platform adapter
+ * (e.g. expo-crypto's getRandomValues) when the global `crypto` API is
+ * absent — Hermes / React Native being the primary case.
+ * Pass `null` to clear a previously injected source.
+ */
+declare function configureRandomSource(fn: GetRandomValues | null): void;
+
 interface LibrarianOptions {
     /** If provided, replaces the default Librarian system instructions. */
     systemPrompt?: string;
@@ -43,4 +60,4 @@ declare function mapLibrarianOptionsToReadOptions(options: LibrarianOptions): Pi
 
 declare function createWiki(db: SQLiteAdapter, options: WikiOptions): WikiMemory;
 
-export { DEFAULT_LIBRARIAN_SYNTHESIS_PROMPT, FormatContextOptions, FormattedMemoryDump, type LibrarianOptions, type LibrarianPromptVariables, MemoryBundle, MemoryDump, type OkfImportOptions, ReadOptions, SQLiteAdapter, WikiMemory, WikiOptions, createWiki, formatContext, formatMemoryDump, formatOkfBundle, hydrateLibrarianPrompt, mapLibrarianOptionsToReadOptions, parseEmbedding, parseOkfBundle, validateLibrarianPromptTemplate };
+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 };

package/dist/index.js

@@ -983,6 +983,10 @@ var EntryRepository = class extends BaseRepository {
 };
 
 // src/utils/ids.ts
+var _injectedGetRandomValues = null;
+function configureRandomSource(fn) {
+  _injectedGetRandomValues = fn;
+}
 function generateId(prefix = "") {
   if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") {
     return prefix + crypto.randomUUID().replace(/-/g, "").substring(0, 24);
@@ -992,8 +996,13 @@ function generateId(prefix = "") {
     crypto.getRandomValues(bytes);
     return prefix + Array.from(bytes).map((b) => b.toString(16).padStart(2, "0")).join("").substring(0, 24);
   }
+  if (_injectedGetRandomValues) {
+    const bytes = new Uint8Array(16);
+    _injectedGetRandomValues(bytes);
+    return prefix + Array.from(bytes).map((b) => b.toString(16).padStart(2, "0")).join("").substring(0, 24);
+  }
   throw new Error(
-    "generateId: no cryptographically secure random source available (crypto.randomUUID and crypto.getRandomValues are both missing)."
+    "generateId: no cryptographically secure random source available (crypto.randomUUID and crypto.getRandomValues are both missing, and no configureRandomSource() injection was provided)."
   );
 }
 
@@ -1407,6 +1416,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.
@@ -1437,21 +1451,111 @@ 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() {
@@ -4481,6 +4585,38 @@ var OntologyService = class {
   }
 };
 
+// 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;
@@ -4564,6 +4700,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.
@@ -4584,6 +4725,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
@@ -4654,6 +4796,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 });
   }
@@ -4881,6 +5026,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;
@@ -5395,8 +5572,10 @@ exports.PromptService = PromptService;
 exports.PrunePartialFailureError = PrunePartialFailureError;
 exports.WikiBusyError = WikiBusyError;
 exports.WikiMemory = WikiMemory;
+exports.configureRandomSource = configureRandomSource;
 exports.createWiki = createWiki;
 exports.formatContext = formatContext;
+exports.formatGraphContext = formatGraphContext;
 exports.formatMemoryDump = formatMemoryDump;
 exports.formatOkfBundle = formatOkfBundle;
 exports.hydrateLibrarianPrompt = hydrateLibrarianPrompt;