@equationalapplications/core-llm-wiki 4.16.0 → 4.17.1

package/dist/{testing-BMsplvLy.d.mts → testing-D02cdI9A.d.mts}

@@ -113,6 +113,14 @@ interface WikiConfig {
      */
     enableOutbox?: boolean;
     ontology?: OntologyConfig;
+    /** Default node cap for traverseGraph(), unless overridden per-call. Default 20. */
+    maxTraversalNodes?: number;
+    /** Default minimum confidence tier for discovered traversal nodes. Default 'tentative'. */
+    minTraversalConfidence?: 'certain' | 'inferred' | 'tentative';
+    /** Default traversal direction. Default 'both'. */
+    traversalDirection?: 'inbound' | 'outbound' | 'both';
+    /** Default source_type dead-end list for discovered traversal nodes. Default []. */
+    excludeSourceTypes?: Array<WikiFact['source_type']>;
 }
 interface ReadOptions {
     maxResults?: number;
@@ -208,6 +216,30 @@ interface WikiEdge {
     edge_type: string;
     created_at: number;
 }
+interface GraphTraversalOptions {
+    sourceId: string;
+    /** Hop count. Default 1. Clamped to [1, 3] regardless of input. */
+    maxDepth?: number;
+    /** Default 'both'. Falls back to WikiConfig.traversalDirection, then 'both'. */
+    direction?: 'inbound' | 'outbound' | 'both';
+    /**
+     * Allowed edge types. `undefined` = no filter (all types).
+     * `[]` (explicit empty array) = match nothing — distinct from `undefined`.
+     */
+    edgeTypes?: string[];
+    /** Total node cap (anchor + neighbors). Default 20 via WikiConfig.maxTraversalNodes. */
+    maxTraversalNodes?: number;
+    /** Minimum confidence tier for *discovered* nodes. Does not gate the anchor. Default 'tentative'. */
+    minTraversalConfidence?: 'certain' | 'inferred' | 'tentative';
+    /** source_type values to dead-end on for *discovered* nodes. Does not gate the anchor. Default []. */
+    excludeSourceTypes?: Array<WikiFact['source_type']>;
+}
+interface GraphNeighborhood {
+    /** Anchor node first, then discovered neighbors ordered by depth ASC, then updated_at DESC. */
+    nodes: WikiFact[];
+    /** Only edges where both endpoints are present in `nodes`. */
+    edges: WikiEdge[];
+}
 interface WikiCheckpoint {
     entity_id: string;
     heal_checkpoint: number;
@@ -840,6 +872,14 @@ declare class EmbeddingService {
     notifyEmbeddingPersistedOrThrow(entityId: string, factId: string, vector: Float32Array | null): Promise<void>;
 }
 
+interface NeighborhoodQueryOptions {
+    maxDepth: number;
+    direction: 'inbound' | 'outbound' | 'both';
+    edgeTypes?: string[];
+    minConfidence: 'certain' | 'inferred' | 'tentative';
+    excludeSourceTypes: string[];
+    maxNodes: number;
+}
 declare class EdgeRepository extends BaseRepository {
     /**
      * Insert an edge, silently skipping on primary-key or uniqueness conflicts.
@@ -849,6 +889,16 @@ declare class EdgeRepository extends BaseRepository {
     getByEntityId(entityId: string, tx?: SQLiteAdapter): Promise<WikiEdge[]>;
     /** Hard delete — edges have no soft-delete concept, only presence/absence. `tx` is REQUIRED. */
     bulkDeleteByEntityId(entityId: string, tx: SQLiteAdapter): Promise<void>;
+    /**
+     * 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.
+     */
+    getNeighborhood(entityId: string, sourceId: string, opts: NeighborhoodQueryOptions, tx?: SQLiteAdapter): Promise<{
+        nodeIds: string[];
+        edges: WikiEdge[];
+    }>;
 }
 
 type TitleIndexEntry = {
@@ -1152,6 +1202,18 @@ declare class WriteService {
     private runLibrarianThenMaybeHeal;
 }
 
+/**
+ * Pure orchestrator — no SQL. Merges WikiConfig defaults with per-call options,
+ * delegates the recursive walk to EdgeRepository, then hydrates node IDs into facts.
+ */
+declare class GraphTraversalService {
+    private edgeRepo;
+    private entryRepo;
+    private config;
+    constructor(edgeRepo: EdgeRepository, entryRepo: EntryRepository, config: WikiConfig);
+    traverseGraph(entityId: string, options: GraphTraversalOptions): Promise<GraphNeighborhood>;
+}
+
 /** Typed escape hatch for tests — not part of the supported consumer API. */
 interface WikiMemoryTestAccess {
     embeddingService: EmbeddingService;
@@ -1162,6 +1224,7 @@ interface WikiMemoryTestAccess {
     searchService: SearchService;
     writeService: WriteService;
     promptService: PromptService;
+    graphTraversalService: GraphTraversalService;
     entryRepo: EntryRepository;
     metadataRepo: MetadataRepository;
     jobManager: JobManager;
@@ -1187,6 +1250,7 @@ declare class WikiMemory {
     private writeService;
     private promptService;
     private ontologyService;
+    private graphTraversalService;
     constructor(db: SQLiteAdapter, options: WikiOptions);
     /**
      * Explicit escape hatch for test suites: typed access to composed services for mocks/spies.
@@ -1205,6 +1269,7 @@ declare class WikiMemory {
         events: number;
     }>;
     read(entityId: string | string[], query: string, options?: ReadOptions): Promise<MemoryBundle>;
+    traverseGraph(entityId: string, options: GraphTraversalOptions): Promise<GraphNeighborhood>;
     getMemoryBundle(entityId: string): Promise<MemoryBundle>;
     write(entityId: string, event: Omit<WikiEvent, 'id' | 'entity_id' | 'created_at'>): Promise<void>;
     /**
@@ -1295,4 +1360,4 @@ declare class WikiMemory {
     }): Promise<void>;
 }
 
-export { type WikiOutboxEvent as A, type WikiTask as B, EmbeddingService as C, IngestionService as D, type EntityStatus as E, type FormatContextOptions as F, MaintenanceService as G, HOOK_TIMEOUT_MARKER as H, ImportExportService as I, JobManager as J, RetrievalService as K, type LLMProvider as L, type MemoryBundle as M, SearchService as N, type OntologyConfig as O, type PromptOverrides as P, WriteService as Q, type ReadOptions as R, type SQLiteAdapter as S, type VectorRanker as V, type WikiOptions as W, type MemoryDump as a, type FormattedMemoryDump as b, WikiMemory as c, type ExtractedFact as d, type ExtractedFactEdge as e, type ExtractedFactWithOntology as f, type ExtractedTask as g, type OntologyEdgeType as h, type OntologyManifest as i, type OntologyMode as j, type OntologyNodeType as k, type OntologyPromptContext as l, type OntologyUpdates as m, PromptService as n, PrunePartialFailureError as o, type VectorRankerFallback as p, type VectorRankerRankArgs as q, type VectorRankerSemanticResult as r, WikiBusyError as s, type WikiBusyOperation as t, type WikiCheckpoint as u, type WikiConfig as v, type WikiEdge as w, type WikiEvent as x, type WikiFact as y, type WikiMemoryTestAccess as z };
+export { type WikiMemoryTestAccess as A, type WikiOutboxEvent as B, type WikiTask as C, EmbeddingService as D, type EntityStatus as E, type FormatContextOptions as F, type GraphNeighborhood as G, HOOK_TIMEOUT_MARKER as H, ImportExportService as I, IngestionService as J, JobManager as K, type LLMProvider as L, type MemoryBundle as M, MaintenanceService as N, type OntologyConfig as O, type PromptOverrides as P, RetrievalService as Q, type ReadOptions as R, type SQLiteAdapter as S, SearchService as T, WriteService as U, type VectorRanker as V, type WikiOptions as W, type MemoryDump as a, type FormattedMemoryDump as b, WikiMemory as c, type ExtractedFact as d, type ExtractedFactEdge as e, type ExtractedFactWithOntology as f, type ExtractedTask as g, type GraphTraversalOptions as h, type OntologyEdgeType as i, type OntologyManifest as j, type OntologyMode as k, type OntologyNodeType as l, type OntologyPromptContext as m, type OntologyUpdates as n, PromptService as o, PrunePartialFailureError as p, type VectorRankerFallback as q, type VectorRankerRankArgs as r, type VectorRankerSemanticResult as s, WikiBusyError as t, type WikiBusyOperation as u, type WikiCheckpoint as v, type WikiConfig as w, type WikiEdge as x, type WikiEvent as y, type WikiFact as z };

package/dist/{testing-BMsplvLy.d.ts → testing-D02cdI9A.d.ts}

@@ -113,6 +113,14 @@ interface WikiConfig {
      */
     enableOutbox?: boolean;
     ontology?: OntologyConfig;
+    /** Default node cap for traverseGraph(), unless overridden per-call. Default 20. */
+    maxTraversalNodes?: number;
+    /** Default minimum confidence tier for discovered traversal nodes. Default 'tentative'. */
+    minTraversalConfidence?: 'certain' | 'inferred' | 'tentative';
+    /** Default traversal direction. Default 'both'. */
+    traversalDirection?: 'inbound' | 'outbound' | 'both';
+    /** Default source_type dead-end list for discovered traversal nodes. Default []. */
+    excludeSourceTypes?: Array<WikiFact['source_type']>;
 }
 interface ReadOptions {
     maxResults?: number;
@@ -208,6 +216,30 @@ interface WikiEdge {
     edge_type: string;
     created_at: number;
 }
+interface GraphTraversalOptions {
+    sourceId: string;
+    /** Hop count. Default 1. Clamped to [1, 3] regardless of input. */
+    maxDepth?: number;
+    /** Default 'both'. Falls back to WikiConfig.traversalDirection, then 'both'. */
+    direction?: 'inbound' | 'outbound' | 'both';
+    /**
+     * Allowed edge types. `undefined` = no filter (all types).
+     * `[]` (explicit empty array) = match nothing — distinct from `undefined`.
+     */
+    edgeTypes?: string[];
+    /** Total node cap (anchor + neighbors). Default 20 via WikiConfig.maxTraversalNodes. */
+    maxTraversalNodes?: number;
+    /** Minimum confidence tier for *discovered* nodes. Does not gate the anchor. Default 'tentative'. */
+    minTraversalConfidence?: 'certain' | 'inferred' | 'tentative';
+    /** source_type values to dead-end on for *discovered* nodes. Does not gate the anchor. Default []. */
+    excludeSourceTypes?: Array<WikiFact['source_type']>;
+}
+interface GraphNeighborhood {
+    /** Anchor node first, then discovered neighbors ordered by depth ASC, then updated_at DESC. */
+    nodes: WikiFact[];
+    /** Only edges where both endpoints are present in `nodes`. */
+    edges: WikiEdge[];
+}
 interface WikiCheckpoint {
     entity_id: string;
     heal_checkpoint: number;
@@ -840,6 +872,14 @@ declare class EmbeddingService {
     notifyEmbeddingPersistedOrThrow(entityId: string, factId: string, vector: Float32Array | null): Promise<void>;
 }
 
+interface NeighborhoodQueryOptions {
+    maxDepth: number;
+    direction: 'inbound' | 'outbound' | 'both';
+    edgeTypes?: string[];
+    minConfidence: 'certain' | 'inferred' | 'tentative';
+    excludeSourceTypes: string[];
+    maxNodes: number;
+}
 declare class EdgeRepository extends BaseRepository {
     /**
      * Insert an edge, silently skipping on primary-key or uniqueness conflicts.
@@ -849,6 +889,16 @@ declare class EdgeRepository extends BaseRepository {
     getByEntityId(entityId: string, tx?: SQLiteAdapter): Promise<WikiEdge[]>;
     /** Hard delete — edges have no soft-delete concept, only presence/absence. `tx` is REQUIRED. */
     bulkDeleteByEntityId(entityId: string, tx: SQLiteAdapter): Promise<void>;
+    /**
+     * 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.
+     */
+    getNeighborhood(entityId: string, sourceId: string, opts: NeighborhoodQueryOptions, tx?: SQLiteAdapter): Promise<{
+        nodeIds: string[];
+        edges: WikiEdge[];
+    }>;
 }
 
 type TitleIndexEntry = {
@@ -1152,6 +1202,18 @@ declare class WriteService {
     private runLibrarianThenMaybeHeal;
 }
 
+/**
+ * Pure orchestrator — no SQL. Merges WikiConfig defaults with per-call options,
+ * delegates the recursive walk to EdgeRepository, then hydrates node IDs into facts.
+ */
+declare class GraphTraversalService {
+    private edgeRepo;
+    private entryRepo;
+    private config;
+    constructor(edgeRepo: EdgeRepository, entryRepo: EntryRepository, config: WikiConfig);
+    traverseGraph(entityId: string, options: GraphTraversalOptions): Promise<GraphNeighborhood>;
+}
+
 /** Typed escape hatch for tests — not part of the supported consumer API. */
 interface WikiMemoryTestAccess {
     embeddingService: EmbeddingService;
@@ -1162,6 +1224,7 @@ interface WikiMemoryTestAccess {
     searchService: SearchService;
     writeService: WriteService;
     promptService: PromptService;
+    graphTraversalService: GraphTraversalService;
     entryRepo: EntryRepository;
     metadataRepo: MetadataRepository;
     jobManager: JobManager;
@@ -1187,6 +1250,7 @@ declare class WikiMemory {
     private writeService;
     private promptService;
     private ontologyService;
+    private graphTraversalService;
     constructor(db: SQLiteAdapter, options: WikiOptions);
     /**
      * Explicit escape hatch for test suites: typed access to composed services for mocks/spies.
@@ -1205,6 +1269,7 @@ declare class WikiMemory {
         events: number;
     }>;
     read(entityId: string | string[], query: string, options?: ReadOptions): Promise<MemoryBundle>;
+    traverseGraph(entityId: string, options: GraphTraversalOptions): Promise<GraphNeighborhood>;
     getMemoryBundle(entityId: string): Promise<MemoryBundle>;
     write(entityId: string, event: Omit<WikiEvent, 'id' | 'entity_id' | 'created_at'>): Promise<void>;
     /**
@@ -1295,4 +1360,4 @@ declare class WikiMemory {
     }): Promise<void>;
 }
 
-export { type WikiOutboxEvent as A, type WikiTask as B, EmbeddingService as C, IngestionService as D, type EntityStatus as E, type FormatContextOptions as F, MaintenanceService as G, HOOK_TIMEOUT_MARKER as H, ImportExportService as I, JobManager as J, RetrievalService as K, type LLMProvider as L, type MemoryBundle as M, SearchService as N, type OntologyConfig as O, type PromptOverrides as P, WriteService as Q, type ReadOptions as R, type SQLiteAdapter as S, type VectorRanker as V, type WikiOptions as W, type MemoryDump as a, type FormattedMemoryDump as b, WikiMemory as c, type ExtractedFact as d, type ExtractedFactEdge as e, type ExtractedFactWithOntology as f, type ExtractedTask as g, type OntologyEdgeType as h, type OntologyManifest as i, type OntologyMode as j, type OntologyNodeType as k, type OntologyPromptContext as l, type OntologyUpdates as m, PromptService as n, PrunePartialFailureError as o, type VectorRankerFallback as p, type VectorRankerRankArgs as q, type VectorRankerSemanticResult as r, WikiBusyError as s, type WikiBusyOperation as t, type WikiCheckpoint as u, type WikiConfig as v, type WikiEdge as w, type WikiEvent as x, type WikiFact as y, type WikiMemoryTestAccess as z };
+export { type WikiMemoryTestAccess as A, type WikiOutboxEvent as B, type WikiTask as C, EmbeddingService as D, type EntityStatus as E, type FormatContextOptions as F, type GraphNeighborhood as G, HOOK_TIMEOUT_MARKER as H, ImportExportService as I, IngestionService as J, JobManager as K, type LLMProvider as L, type MemoryBundle as M, MaintenanceService as N, type OntologyConfig as O, type PromptOverrides as P, RetrievalService as Q, type ReadOptions as R, type SQLiteAdapter as S, SearchService as T, WriteService as U, type VectorRanker as V, type WikiOptions as W, type MemoryDump as a, type FormattedMemoryDump as b, WikiMemory as c, type ExtractedFact as d, type ExtractedFactEdge as e, type ExtractedFactWithOntology as f, type ExtractedTask as g, type GraphTraversalOptions as h, type OntologyEdgeType as i, type OntologyManifest as j, type OntologyMode as k, type OntologyNodeType as l, type OntologyPromptContext as m, type OntologyUpdates as n, PromptService as o, PrunePartialFailureError as p, type VectorRankerFallback as q, type VectorRankerRankArgs as r, type VectorRankerSemanticResult as s, WikiBusyError as t, type WikiBusyOperation as u, type WikiCheckpoint as v, type WikiConfig as w, type WikiEdge as x, type WikiEvent as y, type WikiFact as z };

package/dist/testing.d.mts

@@ -1,2 +1,2 @@
-export { C as EmbeddingService, I as ImportExportService, D as IngestionService, J as JobManager, J as JobManagerType, G as MaintenanceService, K as RetrievalService, N as SearchService, N as SearchServiceType, z as WikiMemoryTestAccess, Q as WriteService } from './testing-BMsplvLy.mjs';
+export { D as EmbeddingService, I as ImportExportService, J as IngestionService, K as JobManager, K as JobManagerType, N as MaintenanceService, Q as RetrievalService, T as SearchService, T as SearchServiceType, A as WikiMemoryTestAccess, U as WriteService } from './testing-D02cdI9A.mjs';
 import 'minisearch';

package/dist/testing.d.ts

@@ -1,2 +1,2 @@
-export { C as EmbeddingService, I as ImportExportService, D as IngestionService, J as JobManager, J as JobManagerType, G as MaintenanceService, K as RetrievalService, N as SearchService, N as SearchServiceType, z as WikiMemoryTestAccess, Q as WriteService } from './testing-BMsplvLy.js';
+export { D as EmbeddingService, I as ImportExportService, J as IngestionService, K as JobManager, K as JobManagerType, N as MaintenanceService, Q as RetrievalService, T as SearchService, T as SearchServiceType, A as WikiMemoryTestAccess, U as WriteService } from './testing-D02cdI9A.js';
 import 'minisearch';

package/dist/testing.js

@@ -800,8 +800,6 @@ After running the migration SQL, restart your application.`
 function normalizeTitleKey(title) {
   return title.trim().toLowerCase().replace(/\s+/g, " ");
 }
-
-// src/utils/ids.ts
 function generateId(prefix = "") {
   if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") {
     return prefix + crypto.randomUUID().replace(/-/g, "").substring(0, 24);
@@ -812,7 +810,7 @@ function generateId(prefix = "") {
     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)."
   );
 }