@equationalapplications/core-llm-wiki 4.15.3 → 4.17.0

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

@@ -21,6 +21,54 @@ interface PromptOverrides {
     librarianSystemPrompt?: string;
     healSystemPrompt?: string;
 }
+type OntologyMode = 'strict' | 'emergent' | 'off';
+interface OntologyNodeType {
+    type: string;
+    description: string;
+}
+interface OntologyEdgeType {
+    type: string;
+    source_type: string;
+    target_type: string;
+    description: string;
+}
+/**
+ * Allowed node and edge types for an entity's ontology graph.
+ * Persisted per entity and injected into librarian/ingest prompts when mode ≠ `off`.
+ */
+interface OntologyManifest {
+    node_types: OntologyNodeType[];
+    edge_types: OntologyEdgeType[];
+}
+/**
+ * Global ontology defaults and bootstrap manifests for known entities.
+ * Per-entity mode and manifest overrides are stored in SQLite and managed via
+ * `WikiMemory.getOntologyManifest` / `setOntologyManifest`.
+ */
+interface OntologyConfig {
+    /** Global default mode. Default: `'off'` (backward compatible — no typed extraction). */
+    mode?: OntologyMode;
+    /**
+     * Bootstrap manifests for known entities at construction time.
+     * Written to the database on first access if no row exists for that entity.
+     */
+    seedManifests?: Record<string, {
+        manifest: OntologyManifest;
+        mode?: OntologyMode;
+    }>;
+}
+interface ExtractedFactEdge {
+    edge_type: string;
+    target_title: string;
+}
+interface OntologyUpdates {
+    node_types?: OntologyNodeType[];
+    edge_types?: OntologyEdgeType[];
+}
+interface OntologyPromptContext {
+    ontologyManifest: string;
+    ontologyModeInstructions: string;
+}
 interface WikiConfig {
     /**
      * Prefix applied to every SQL table/index/trigger name. Must match
@@ -64,6 +112,15 @@ interface WikiConfig {
      * @default false
      */
     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;
@@ -159,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;
@@ -170,6 +251,10 @@ interface ExtractedFact {
     tags: string[];
     confidence: 'certain' | 'inferred' | 'tentative';
 }
+interface ExtractedFactWithOntology extends ExtractedFact {
+    okf_type?: string;
+    edges?: ExtractedFactEdge[];
+}
 interface ExtractedTask {
     description: string;
     priority: number;
@@ -627,6 +712,15 @@ declare class MetadataRepository extends BaseRepository {
     getTableDdl(tableName: string, tx?: SQLiteAdapter): Promise<string | null>;
     vacuum(): Promise<void>;
     getDistinctEntityIds(tx?: SQLiteAdapter): Promise<string[]>;
+    getManifest(entityId: string, tx?: SQLiteAdapter): Promise<{
+        mode: OntologyMode;
+        manifest: OntologyManifest;
+    } | null>;
+    setManifest(entityId: string, data: {
+        mode: OntologyMode;
+        manifest: OntologyManifest;
+    }, tx: SQLiteAdapter): Promise<void>;
+    mergeManifestUpdates(entityId: string, updates: OntologyUpdates, tx: SQLiteAdapter): Promise<OntologyManifest>;
 }
 
 interface ScoredRow {
@@ -778,15 +872,76 @@ 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.
+     * Throws when the insert was skipped due to an id collision with a different edge tuple.
+     */
+    addIgnoreDuplicate(edge: WikiEdge, tx?: SQLiteAdapter): Promise<void>;
+    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 = {
+    id: string;
+    okf_type: string | null;
+};
+/**
+ * Coordinates ontology mode resolution, manifest caching, LLM output validation, and edge persistence.
+ * Cache is per WikiMemory instance (single-process); not shared across instances.
+ */
+declare class OntologyService {
+    private metadataRepo;
+    private edgeRepo;
+    private ontologyConfig?;
+    private cache;
+    constructor(metadataRepo: MetadataRepository, edgeRepo: EdgeRepository, ontologyConfig?: OntologyConfig | undefined);
+    resolveMode(storedMode?: OntologyMode): OntologyMode;
+    invalidateCache(entityId: string): void;
+    getEffectiveState(entityId: string, tx?: SQLiteAdapter): Promise<{
+        mode: OntologyMode;
+        manifest: OntologyManifest;
+    }>;
+    buildPromptContext(entityId: string): Promise<OntologyPromptContext | null>;
+    mergeEmergentUpdates(entityId: string, updates: OntologyUpdates, tx: SQLiteAdapter): Promise<OntologyManifest>;
+    validateAndNormalizeFact(fact: ExtractedFactWithOntology, manifest: OntologyManifest): {
+        okf_type: string | null;
+        edges: ExtractedFactEdge[];
+    };
+    resolveAndPersistEdges(entityId: string, sourceId: string, sourceType: string | null, edges: ExtractedFactEdge[], manifest: OntologyManifest, titleIndex: Map<string, TitleIndexEntry>, tx: SQLiteAdapter, now: number): Promise<void>;
+}
+
 declare class PromptService {
     private globalOverrides?;
     constructor(globalOverrides?: PromptOverrides | undefined);
     private hydrate;
-    buildIngestPrompt(documentChunk: string, runtimeOverride?: string): {
+    private hasOntologyPlaceholders;
+    private buildSystemPrompt;
+    private appendOntology;
+    buildIngestPrompt(documentChunk: string, runtimeOverride?: string, ontologyContext?: OntologyPromptContext | null): {
         systemPrompt: string;
         userPrompt: string;
     };
-    buildLibrarianPrompt(events: unknown[], currentFacts: unknown[], runtimeOverride?: string): {
+    buildLibrarianPrompt(events: unknown[], currentFacts: unknown[], runtimeOverride?: string, ontologyContext?: OntologyPromptContext | null): {
         systemPrompt: string;
         userPrompt: string;
     };
@@ -804,8 +959,9 @@ declare class IngestionService {
     private searchService;
     private jobManager;
     private embeddingService;
+    private ontologyService?;
     private promptService;
-    constructor(db: SQLiteAdapter, prefix: string, options: WikiOptions, entryRepo: EntryRepository, searchService: SearchService, jobManager: JobManager, embeddingService: EmbeddingService, promptService?: PromptService);
+    constructor(db: SQLiteAdapter, prefix: string, options: WikiOptions, entryRepo: EntryRepository, searchService: SearchService, jobManager: JobManager, embeddingService: EmbeddingService, promptService?: PromptService, ontologyService?: OntologyService | undefined);
     ingestDocument(entityId: string, params: {
         sourceRef: string;
         sourceHash: string;
@@ -924,8 +1080,9 @@ declare class MaintenanceService {
     private searchService;
     private jobManager;
     private embeddingService;
+    private ontologyService?;
     private promptService;
-    constructor(db: SQLiteAdapter, prefix: string, options: WikiOptions, entryRepo: EntryRepository, taskRepo: TaskRepository, eventRepo: EventRepository, metadataRepo: MetadataRepository, searchService: SearchService, jobManager: JobManager, embeddingService: EmbeddingService, promptService?: PromptService);
+    constructor(db: SQLiteAdapter, prefix: string, options: WikiOptions, entryRepo: EntryRepository, taskRepo: TaskRepository, eventRepo: EventRepository, metadataRepo: MetadataRepository, searchService: SearchService, jobManager: JobManager, embeddingService: EmbeddingService, promptService?: PromptService, ontologyService?: OntologyService | undefined);
     runPrune(entityId: string, options?: {
         retainSoftDeletedFor?: number | null;
         retainEventsFor?: number | null;
@@ -969,17 +1126,6 @@ declare class MaintenanceService {
     private _sanitizeRankerError;
 }
 
-declare class EdgeRepository extends BaseRepository {
-    /**
-     * Insert an edge, silently skipping on primary-key or uniqueness conflicts.
-     * Throws when the insert was skipped due to an id collision with a different edge tuple.
-     */
-    addIgnoreDuplicate(edge: WikiEdge, tx?: SQLiteAdapter): Promise<void>;
-    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>;
-}
-
 declare class ImportExportService {
     private db;
     private entryRepo;
@@ -1056,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;
@@ -1066,6 +1224,7 @@ interface WikiMemoryTestAccess {
     searchService: SearchService;
     writeService: WriteService;
     promptService: PromptService;
+    graphTraversalService: GraphTraversalService;
     entryRepo: EntryRepository;
     metadataRepo: MetadataRepository;
     jobManager: JobManager;
@@ -1090,6 +1249,8 @@ declare class WikiMemory {
     private retrievalService;
     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.
@@ -1108,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>;
     /**
@@ -1180,6 +1342,22 @@ declare class WikiMemory {
      * Call after successfully committing events to the external system.
      */
     markOutboxEventsProcessed(eventIds: string[]): Promise<void>;
+    /**
+     * Returns the effective ontology mode and manifest for an entity.
+     * Resolution order: persisted DB row → `WikiConfig.ontology.seedManifests[entityId]` → `null`.
+     */
+    getOntologyManifest(entityId: string): Promise<{
+        mode: OntologyMode;
+        manifest: OntologyManifest;
+    } | 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.
+     */
+    setOntologyManifest(entityId: string, manifest: OntologyManifest, options?: {
+        mode?: OntologyMode;
+    }): Promise<void>;
 }
 
-export { type EntityStatus as E, type FormatContextOptions as F, HOOK_TIMEOUT_MARKER as H, ImportExportService as I, JobManager as J, type LLMProvider as L, type MemoryBundle as M, type PromptOverrides as P, 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 ExtractedTask as e, PromptService as f, PrunePartialFailureError as g, type VectorRankerFallback as h, type VectorRankerRankArgs as i, type VectorRankerSemanticResult as j, WikiBusyError as k, type WikiBusyOperation as l, type WikiCheckpoint as m, type WikiConfig as n, type WikiEdge as o, type WikiEvent as p, type WikiFact as q, type WikiMemoryTestAccess as r, type WikiOutboxEvent as s, type WikiTask as t, EmbeddingService as u, IngestionService as v, MaintenanceService as w, RetrievalService as x, SearchService as y, WriteService 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-NH1_Aigh.d.ts → testing-D02cdI9A.d.ts}

@@ -21,6 +21,54 @@ interface PromptOverrides {
     librarianSystemPrompt?: string;
     healSystemPrompt?: string;
 }
+type OntologyMode = 'strict' | 'emergent' | 'off';
+interface OntologyNodeType {
+    type: string;
+    description: string;
+}
+interface OntologyEdgeType {
+    type: string;
+    source_type: string;
+    target_type: string;
+    description: string;
+}
+/**
+ * Allowed node and edge types for an entity's ontology graph.
+ * Persisted per entity and injected into librarian/ingest prompts when mode ≠ `off`.
+ */
+interface OntologyManifest {
+    node_types: OntologyNodeType[];
+    edge_types: OntologyEdgeType[];
+}
+/**
+ * Global ontology defaults and bootstrap manifests for known entities.
+ * Per-entity mode and manifest overrides are stored in SQLite and managed via
+ * `WikiMemory.getOntologyManifest` / `setOntologyManifest`.
+ */
+interface OntologyConfig {
+    /** Global default mode. Default: `'off'` (backward compatible — no typed extraction). */
+    mode?: OntologyMode;
+    /**
+     * Bootstrap manifests for known entities at construction time.
+     * Written to the database on first access if no row exists for that entity.
+     */
+    seedManifests?: Record<string, {
+        manifest: OntologyManifest;
+        mode?: OntologyMode;
+    }>;
+}
+interface ExtractedFactEdge {
+    edge_type: string;
+    target_title: string;
+}
+interface OntologyUpdates {
+    node_types?: OntologyNodeType[];
+    edge_types?: OntologyEdgeType[];
+}
+interface OntologyPromptContext {
+    ontologyManifest: string;
+    ontologyModeInstructions: string;
+}
 interface WikiConfig {
     /**
      * Prefix applied to every SQL table/index/trigger name. Must match
@@ -64,6 +112,15 @@ interface WikiConfig {
      * @default false
      */
     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;
@@ -159,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;
@@ -170,6 +251,10 @@ interface ExtractedFact {
     tags: string[];
     confidence: 'certain' | 'inferred' | 'tentative';
 }
+interface ExtractedFactWithOntology extends ExtractedFact {
+    okf_type?: string;
+    edges?: ExtractedFactEdge[];
+}
 interface ExtractedTask {
     description: string;
     priority: number;
@@ -627,6 +712,15 @@ declare class MetadataRepository extends BaseRepository {
     getTableDdl(tableName: string, tx?: SQLiteAdapter): Promise<string | null>;
     vacuum(): Promise<void>;
     getDistinctEntityIds(tx?: SQLiteAdapter): Promise<string[]>;
+    getManifest(entityId: string, tx?: SQLiteAdapter): Promise<{
+        mode: OntologyMode;
+        manifest: OntologyManifest;
+    } | null>;
+    setManifest(entityId: string, data: {
+        mode: OntologyMode;
+        manifest: OntologyManifest;
+    }, tx: SQLiteAdapter): Promise<void>;
+    mergeManifestUpdates(entityId: string, updates: OntologyUpdates, tx: SQLiteAdapter): Promise<OntologyManifest>;
 }
 
 interface ScoredRow {
@@ -778,15 +872,76 @@ 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.
+     * Throws when the insert was skipped due to an id collision with a different edge tuple.
+     */
+    addIgnoreDuplicate(edge: WikiEdge, tx?: SQLiteAdapter): Promise<void>;
+    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 = {
+    id: string;
+    okf_type: string | null;
+};
+/**
+ * Coordinates ontology mode resolution, manifest caching, LLM output validation, and edge persistence.
+ * Cache is per WikiMemory instance (single-process); not shared across instances.
+ */
+declare class OntologyService {
+    private metadataRepo;
+    private edgeRepo;
+    private ontologyConfig?;
+    private cache;
+    constructor(metadataRepo: MetadataRepository, edgeRepo: EdgeRepository, ontologyConfig?: OntologyConfig | undefined);
+    resolveMode(storedMode?: OntologyMode): OntologyMode;
+    invalidateCache(entityId: string): void;
+    getEffectiveState(entityId: string, tx?: SQLiteAdapter): Promise<{
+        mode: OntologyMode;
+        manifest: OntologyManifest;
+    }>;
+    buildPromptContext(entityId: string): Promise<OntologyPromptContext | null>;
+    mergeEmergentUpdates(entityId: string, updates: OntologyUpdates, tx: SQLiteAdapter): Promise<OntologyManifest>;
+    validateAndNormalizeFact(fact: ExtractedFactWithOntology, manifest: OntologyManifest): {
+        okf_type: string | null;
+        edges: ExtractedFactEdge[];
+    };
+    resolveAndPersistEdges(entityId: string, sourceId: string, sourceType: string | null, edges: ExtractedFactEdge[], manifest: OntologyManifest, titleIndex: Map<string, TitleIndexEntry>, tx: SQLiteAdapter, now: number): Promise<void>;
+}
+
 declare class PromptService {
     private globalOverrides?;
     constructor(globalOverrides?: PromptOverrides | undefined);
     private hydrate;
-    buildIngestPrompt(documentChunk: string, runtimeOverride?: string): {
+    private hasOntologyPlaceholders;
+    private buildSystemPrompt;
+    private appendOntology;
+    buildIngestPrompt(documentChunk: string, runtimeOverride?: string, ontologyContext?: OntologyPromptContext | null): {
         systemPrompt: string;
         userPrompt: string;
     };
-    buildLibrarianPrompt(events: unknown[], currentFacts: unknown[], runtimeOverride?: string): {
+    buildLibrarianPrompt(events: unknown[], currentFacts: unknown[], runtimeOverride?: string, ontologyContext?: OntologyPromptContext | null): {
         systemPrompt: string;
         userPrompt: string;
     };
@@ -804,8 +959,9 @@ declare class IngestionService {
     private searchService;
     private jobManager;
     private embeddingService;
+    private ontologyService?;
     private promptService;
-    constructor(db: SQLiteAdapter, prefix: string, options: WikiOptions, entryRepo: EntryRepository, searchService: SearchService, jobManager: JobManager, embeddingService: EmbeddingService, promptService?: PromptService);
+    constructor(db: SQLiteAdapter, prefix: string, options: WikiOptions, entryRepo: EntryRepository, searchService: SearchService, jobManager: JobManager, embeddingService: EmbeddingService, promptService?: PromptService, ontologyService?: OntologyService | undefined);
     ingestDocument(entityId: string, params: {
         sourceRef: string;
         sourceHash: string;
@@ -924,8 +1080,9 @@ declare class MaintenanceService {
     private searchService;
     private jobManager;
     private embeddingService;
+    private ontologyService?;
     private promptService;
-    constructor(db: SQLiteAdapter, prefix: string, options: WikiOptions, entryRepo: EntryRepository, taskRepo: TaskRepository, eventRepo: EventRepository, metadataRepo: MetadataRepository, searchService: SearchService, jobManager: JobManager, embeddingService: EmbeddingService, promptService?: PromptService);
+    constructor(db: SQLiteAdapter, prefix: string, options: WikiOptions, entryRepo: EntryRepository, taskRepo: TaskRepository, eventRepo: EventRepository, metadataRepo: MetadataRepository, searchService: SearchService, jobManager: JobManager, embeddingService: EmbeddingService, promptService?: PromptService, ontologyService?: OntologyService | undefined);
     runPrune(entityId: string, options?: {
         retainSoftDeletedFor?: number | null;
         retainEventsFor?: number | null;
@@ -969,17 +1126,6 @@ declare class MaintenanceService {
     private _sanitizeRankerError;
 }
 
-declare class EdgeRepository extends BaseRepository {
-    /**
-     * Insert an edge, silently skipping on primary-key or uniqueness conflicts.
-     * Throws when the insert was skipped due to an id collision with a different edge tuple.
-     */
-    addIgnoreDuplicate(edge: WikiEdge, tx?: SQLiteAdapter): Promise<void>;
-    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>;
-}
-
 declare class ImportExportService {
     private db;
     private entryRepo;
@@ -1056,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;
@@ -1066,6 +1224,7 @@ interface WikiMemoryTestAccess {
     searchService: SearchService;
     writeService: WriteService;
     promptService: PromptService;
+    graphTraversalService: GraphTraversalService;
     entryRepo: EntryRepository;
     metadataRepo: MetadataRepository;
     jobManager: JobManager;
@@ -1090,6 +1249,8 @@ declare class WikiMemory {
     private retrievalService;
     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.
@@ -1108,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>;
     /**
@@ -1180,6 +1342,22 @@ declare class WikiMemory {
      * Call after successfully committing events to the external system.
      */
     markOutboxEventsProcessed(eventIds: string[]): Promise<void>;
+    /**
+     * Returns the effective ontology mode and manifest for an entity.
+     * Resolution order: persisted DB row → `WikiConfig.ontology.seedManifests[entityId]` → `null`.
+     */
+    getOntologyManifest(entityId: string): Promise<{
+        mode: OntologyMode;
+        manifest: OntologyManifest;
+    } | 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.
+     */
+    setOntologyManifest(entityId: string, manifest: OntologyManifest, options?: {
+        mode?: OntologyMode;
+    }): Promise<void>;
 }
 
-export { type EntityStatus as E, type FormatContextOptions as F, HOOK_TIMEOUT_MARKER as H, ImportExportService as I, JobManager as J, type LLMProvider as L, type MemoryBundle as M, type PromptOverrides as P, 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 ExtractedTask as e, PromptService as f, PrunePartialFailureError as g, type VectorRankerFallback as h, type VectorRankerRankArgs as i, type VectorRankerSemanticResult as j, WikiBusyError as k, type WikiBusyOperation as l, type WikiCheckpoint as m, type WikiConfig as n, type WikiEdge as o, type WikiEvent as p, type WikiFact as q, type WikiMemoryTestAccess as r, type WikiOutboxEvent as s, type WikiTask as t, EmbeddingService as u, IngestionService as v, MaintenanceService as w, RetrievalService as x, SearchService as y, WriteService 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 { u as EmbeddingService, I as ImportExportService, v as IngestionService, J as JobManager, J as JobManagerType, w as MaintenanceService, x as RetrievalService, y as SearchService, y as SearchServiceType, r as WikiMemoryTestAccess, z as WriteService } from './testing-NH1_Aigh.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 { u as EmbeddingService, I as ImportExportService, v as IngestionService, J as JobManager, J as JobManagerType, w as MaintenanceService, x as RetrievalService, y as SearchService, y as SearchServiceType, r as WikiMemoryTestAccess, z as WriteService } from './testing-NH1_Aigh.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';