@equationalapplications/core-llm-wiki 5.2.1 → 5.3.1

package/dist/{testing-CAk9oFvw.d.mts → testing-zf3Jp_RL.d.mts}

@@ -560,6 +560,42 @@ declare class WikiDuplicateHashError extends Error {
         entityId: string;
     });
 }
+/**
+ * Thrown by `WikiMemory.upsertGraph` when the persisted ontology mode for the
+ * entity is `'strict'` and a caller-supplied node or edge `type` does not
+ * resolve against the entity's manifest. Mirrors {@link WikiBusyError}'s
+ * anchoring of canonical metadata on the error instance for stable
+ * observability. Per C4, the check is pre-flight and all-or-nothing — the
+ * first invalid item throws; NONE are written.
+ */
+declare class WikiStrictOntologyViolation extends Error {
+    readonly entityId: string;
+    readonly kind: 'node' | 'edge';
+    readonly type: string;
+    readonly code: "WIKI_STRICT_ONTOLOGY_VIOLATION";
+    constructor(entityId: string, kind: 'node' | 'edge', type: string);
+}
+/**
+ * Thrown by `WikiMemory.upsertGraph`'s C2 probe when the supplied
+ * `sourceHash` is already mapped to a *different* `sourceRef` for the same
+ * entity. Indicates either a caller-side id-derivation collision, a race with
+ * another writer, or — per the C2 known-limitation note in the spec — two
+ * source files with genuinely identical content (byte-identical barrel
+ * re-exports, blank stubs, vendored boilerplate). In all cases: fail loud.
+ */
+declare class WikiSourceRefHashCollision extends Error {
+    readonly entityId: string;
+    readonly sourceHash: string;
+    readonly existingSourceRef: string;
+    readonly attemptedSourceRef: string;
+    readonly code: "WIKI_SOURCE_REF_HASH_COLLISION";
+    constructor(params: {
+        entityId: string;
+        sourceHash: string;
+        existingSourceRef: string;
+        attemptedSourceRef: string;
+    });
+}
 /**
  * Thrown by the serialized transaction wrapper when a SQLite driver error
  * escapes a transaction callback (nested BEGIN, SQLITE_BUSY, constraint
@@ -734,8 +770,16 @@ declare class EntryRepository extends BaseRepository {
     /**
      * Fetch recent non-deleted entries for an entity (limited), ordered by updated_at DESC.
      * Used by MaintenanceService.doRunLibrarian().
+     *
+     * When `excludeSourceRef` is supplied, the WHERE clause filters out that
+     * sourceRef BEFORE applying LIMIT. The caller in IngestionService is
+     * `findRecentByEntityId(entityId, 500, tx)` — it discards same-sourceRef
+     * rows after the read to build a cross-sourceRef title index. If those
+     * rows are filtered out in SQL, the limit applies to usable rows only
+     * and a re-ingest where the caller's sourceRef owns most recent facts
+     * still leaves cross-sourceRef entries in the index.
      */
-    findRecentByEntityId(entityId: string, limit: number, tx?: SQLiteAdapter): Promise<WikiFact[]>;
+    findRecentByEntityId(entityId: string, limit: number, tx?: SQLiteAdapter, excludeSourceRef?: string): Promise<WikiFact[]>;
     /**
      * Fetch all non-deleted entries for an entity with embedding blobs preserved.
      * Used by ImportExportService for export/import round-tripping.
@@ -1003,6 +1047,15 @@ declare class MetadataRepository extends BaseRepository {
     tableExists(tableName: string, tx?: SQLiteAdapter): Promise<boolean>;
     getTableDdl(tableName: string, tx?: SQLiteAdapter): Promise<string | null>;
     vacuum(): Promise<void>;
+    /**
+     * Returns the set of distinct `entity_id` values across entries/tasks/events.
+     *
+     * Deliberately widened from a prior `WHERE deleted_at IS NULL` form: the
+     * returned set intentionally includes entities whose only rows are
+     * soft-deleted, so the host's maintenance sweep can visit such
+     * "decommissioned-scope" namespaces and reap the soft-deleted rows. Sorting
+     * is `entity_id COLLATE BINARY` for stable, locale-independent ordering.
+     */
     getDistinctEntityIds(tx?: SQLiteAdapter): Promise<string[]>;
     getManifest(entityId: string, tx?: SQLiteAdapter): Promise<{
         mode: OntologyMode;
@@ -1211,26 +1264,6 @@ declare class JobManager {
     private _notifyStatusSubscribers;
 }
 
-declare class EmbeddingService {
-    private db;
-    private options;
-    private entryRepo;
-    private metadataRepo;
-    constructor(db: SQLiteAdapter, options: WikiOptions, entryRepo: EntryRepository, metadataRepo: MetadataRepository);
-    storeEmbeddingDimension(dim: number): Promise<void>;
-    /** Promotes embedding_dimension_mismatch to canonical embedding_dimension when safe. */
-    reconcileEmbeddingDimension(): Promise<void>;
-    embedFact(fact: {
-        id: string;
-        entity_id: string;
-        title: string;
-        body: string;
-        tags: string | string[];
-    }): Promise<boolean>;
-    notifyEmbeddingPersisted(entityId: string, factId: string, vector: Float32Array | null): Promise<void>;
-    notifyEmbeddingPersistedOrThrow(entityId: string, factId: string, vector: Float32Array | null): Promise<void>;
-}
-
 interface NeighborhoodQueryOptions {
     maxDepth: number;
     direction: 'inbound' | 'outbound' | 'both';
@@ -1249,6 +1282,18 @@ 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>;
+    /**
+     * Hard-delete every edge whose `source_id` is in `sourceFactIds`, scoped to
+     * `entityId`. Returns the number of rows deleted. Edges have no soft-delete
+     * concept; this method is named `softDeleteBySourceFactIds` for symmetry with
+     * `EntryRepository.softDeleteBySource` (which IS a soft delete), but its
+     * semantics are immediate presence/absence removal. Use ONLY inside an open
+     * transaction — the method requires `tx` and performs no autocommit.
+     *
+     * Used by `IngestionService.upsertGraphCore` to retire the prior parse's
+     * edges whose source facts are being superseded by `softDeleteBySource`.
+     */
+    softDeleteBySourceFactIds(entityId: string, sourceFactIds: readonly string[], tx: SQLiteAdapter): Promise<number>;
     /**
      * Multi-hop traversal from `sourceId` via SQLite `WITH RECURSIVE`. All filtering,
      * dead-ending, cycle-guarding, capping, and ordering happens in this one query.
@@ -1261,6 +1306,26 @@ declare class EdgeRepository extends BaseRepository {
     }>;
 }
 
+declare class EmbeddingService {
+    private db;
+    private options;
+    private entryRepo;
+    private metadataRepo;
+    constructor(db: SQLiteAdapter, options: WikiOptions, entryRepo: EntryRepository, metadataRepo: MetadataRepository);
+    storeEmbeddingDimension(dim: number): Promise<void>;
+    /** Promotes embedding_dimension_mismatch to canonical embedding_dimension when safe. */
+    reconcileEmbeddingDimension(): Promise<void>;
+    embedFact(fact: {
+        id: string;
+        entity_id: string;
+        title: string;
+        body: string;
+        tags: string | string[];
+    }): Promise<boolean>;
+    notifyEmbeddingPersisted(entityId: string, factId: string, vector: Float32Array | null): Promise<void>;
+    notifyEmbeddingPersistedOrThrow(entityId: string, factId: string, vector: Float32Array | null): Promise<void>;
+}
+
 type TitleIndexEntry = {
     id: string;
     okf_type: string | null;
@@ -1283,10 +1348,28 @@ declare class OntologyService {
     }>;
     buildPromptContext(entityId: string): Promise<OntologyPromptContext | null>;
     mergeEmergentUpdates(entityId: string, updates: OntologyUpdates, tx: SQLiteAdapter): Promise<OntologyManifest>;
-    validateAndNormalizeFact(fact: ExtractedFactWithOntology, manifest: OntologyManifest): {
+    validateAndNormalizeFact(fact: ExtractedFactWithOntology, manifest: OntologyManifest, opts?: {
+        strict?: boolean;
+        entityId?: string;
+    }): {
         okf_type: string | null;
         edges: ExtractedFactEdge[];
     };
+    /**
+     * Pure resolver: given a source type, LLM-supplied edges, the manifest,
+     * and a title index, return a list of concrete `WikiEdge` objects ready
+     * for persistence. Performs no DB writes. Used by callers that batch edge
+     * writes inside their own transaction (e.g. `IngestionService.ingestDocument`
+     * when delegating to `upsertGraphCore`).
+     */
+    resolveEdges(entityId: string, sourceId: string, sourceType: string | null, edges: ExtractedFactEdge[], manifest: OntologyManifest, titleIndex: Map<string, TitleIndexEntry>, now: number): WikiEdge[];
+    /**
+     * Backwards-compatible wrapper: resolves edges via {@link resolveEdges},
+     * then persists each via `edgeRepo.addIgnoreDuplicate` in the supplied
+     * transaction. Returns the number of edges persisted. Used by paths that
+     * want self-contained edge persistence (e.g. MaintenanceService heal /
+     * backfill callers that do not have a separate edge-write step).
+     */
     resolveAndPersistEdges(entityId: string, sourceId: string, sourceType: string | null, edges: ExtractedFactEdge[], manifest: OntologyManifest, titleIndex: Map<string, TitleIndexEntry>, tx: SQLiteAdapter, now: number): Promise<number>;
 }
 
@@ -1321,12 +1404,14 @@ declare class IngestionService {
     private options;
     private entryRepo;
     private sourceRefIndexRepo;
+    private metadataRepo;
+    private edgeRepo;
     private searchService;
     private jobManager;
     private embeddingService;
     private ontologyService?;
     private promptService;
-    constructor(db: SQLiteAdapter, prefix: string, options: WikiOptions, entryRepo: EntryRepository, sourceRefIndexRepo: SourceRefIndexRepository, searchService: SearchService, jobManager: JobManager, embeddingService: EmbeddingService, promptService?: PromptService, ontologyService?: OntologyService | undefined);
+    constructor(db: SQLiteAdapter, prefix: string, options: WikiOptions, entryRepo: EntryRepository, sourceRefIndexRepo: SourceRefIndexRepository, metadataRepo: MetadataRepository, edgeRepo: EdgeRepository, searchService: SearchService, jobManager: JobManager, embeddingService: EmbeddingService, promptService?: PromptService, ontologyService?: OntologyService | undefined);
     ingestDocument(entityId: string, params: {
         sourceRef: string;
         sourceHash: string;
@@ -1342,6 +1427,49 @@ declare class IngestionService {
         chunks: number;
         duplicateOf?: string;
     }>;
+    /**
+     * Implements spec §2 data flow steps a–j with the host-facing
+     * `{sourceRef, sourceHash, nodes, edges}` parameter shape. Shared between
+     * `ingestDocument` (with `{ strict: false }` to preserve current behavior)
+     * and `WikiMemory.upsertGraph` (which lets the persisted ontology mode
+     * decide strictness).
+     *
+     * Runs ENTIRELY inside the supplied `tx`. Does not acquire locks, does not
+     * open a nested transaction, does not perform post-commit work (search
+     * sync, embedding, cache eviction). Those concerns remain in `ingestDocument`.
+     *
+     * The pre-flight validation (steps a–c) lives INSIDE this method per the
+     * spec, so the public `WikiMemory.upsertGraph` can be a thin wrapper that
+     * performs only the C2 probe before delegating.
+     *
+     * @returns Counts: nodesWritten (validated nodes persisted), edgesWritten
+     *   (manifest-valid edges persisted), superseded (prior facts soft-deleted
+     *   plus prior source-ref edges hard-deleted).
+     */
+    upsertGraphCore(entityId: string, params: {
+        sourceRef: string;
+        sourceHash: string;
+        nodes: readonly {
+            id: string;
+            type: string;
+            title: string;
+            body?: string;
+            tags?: readonly string[];
+            confidence?: 'certain' | 'inferred' | 'tentative';
+        }[];
+        edges: readonly {
+            type: string;
+            sourceId: string;
+            targetId: string;
+            id?: string;
+        }[];
+    }, tx: SQLiteAdapter, opts?: {
+        strict?: boolean;
+    }): Promise<{
+        nodesWritten: number;
+        edgesWritten: number;
+        superseded: number;
+    }>;
 }
 
 declare class TaskRepository extends BaseRepository {
@@ -1756,6 +1884,34 @@ declare class WikiMemory {
      * auditing duplicate-content collisions.
      */
     findSourceRefsByHash(entityId: string, sourceHash: string): Promise<string[]>;
+    /**
+     * Returns the set of `entity_id` values with at least one row in this
+     * database, INCLUDING entities whose only remaining rows are soft-deleted
+     * — sorted ascending `entity_id COLLATE BINARY`. Empty array when the
+     * database has no entities.
+     *
+     * The deliberate inclusion of soft-deleted-only entities closes the
+     * decommissioned-scope leak: a scoped namespace whose documents have all
+     * been forgotten or superseded must still appear so host maintenance
+     * sweeps (`runLibrarian`, `runHeal`, `runOntologyBackfill`, `runPrune`)
+     * can visit it and reap the soft-deleted rows.
+     *
+     * Read-only. Never acquires a lock. Never opens a transaction. Propagates
+     * underlying read errors.
+     *
+     * @param options.prefix - Optional string filter applied as
+     *   `id.startsWith(prefix)`. O(n) over distinct ids because the
+     *   `(entity_id, source_ref)` index is not seekable on `entity_id`-only
+     *   prefix. Empty-string prefix matches every id.
+     *
+     * Note: this widens the coverage of `exportDump` (which delegates to
+     * `MetadataRepository.getDistinctEntityIds`); exported dumps now include
+     * orphaned entities. This is a deliberate widening for backup/migration
+     * coverage, not a breaking change to `exportDump`'s return shape.
+     */
+    listEntityIds(options?: {
+        prefix?: string;
+    }): Promise<string[]>;
     runPrune(entityId: string, options?: {
         retainSoftDeletedFor?: number | null;
         retainEventsFor?: number | null;
@@ -1871,6 +2027,54 @@ declare class WikiMemory {
         chunks: number;
         duplicateOf?: string;
     }>;
+    /**
+     * Deterministic write path into the graph. Accepts caller-supplied
+     * `(nodes, edges)` and writes them under `(sourceRef, sourceHash)`
+     * semantics identical to `ingestDocument`, minus the LLM extraction step.
+     *
+     * MUST be called from inside an open `db.withTransactionAsync` callback —
+     * the third argument is the caller's `tx`. The method does not open a
+     * nested transaction, does not acquire any lock, and does not perform
+     * post-commit work (search sync, embedding, cache eviction). Hosts that
+     * want embeddings synced should drive the existing maintenance sweep
+     * (`runLibrarian` / `runHeal` / `runOntologyBackfill` / `runPrune`,
+     * scoped via `listEntityIds`).
+     *
+     * Contract (full pre-flight validation lives inside
+     * `IngestionService.upsertGraphCore`, which this method delegates to):
+     * - C2: no-op when `(entityId, sourceHash)` is already mapped to
+     *   `params.sourceRef`; throws `WikiSourceRefHashCollision` if mapped to
+     *   a different `sourceRef`.
+     * - C3: edges with dangling `targetId` are stored verbatim (no FK, no
+     *   resolution).
+     * - C4: under persisted ontology mode `'strict'`, an out-of-manifest node
+     *   or edge `type` throws `WikiStrictOntologyViolation` (pre-flight,
+     *   all-or-nothing — NONE written on failure).
+     *
+     * @returns Counts: nodesWritten (validated nodes persisted), edgesWritten
+     *   (manifest-valid edges persisted), superseded (prior facts soft-deleted
+     *   plus prior source-ref edges hard-deleted).
+     */
+    upsertGraph(entityId: string, params: {
+        sourceRef: string;
+        sourceHash: string;
+        nodes: readonly {
+            id: string;
+            type: string;
+            title: string;
+            body?: string;
+        }[];
+        edges: readonly {
+            type: string;
+            sourceId: string;
+            targetId: string;
+            id?: string;
+        }[];
+    }, adapter: SQLiteAdapter): Promise<{
+        nodesWritten: number;
+        edgesWritten: number;
+        superseded: number;
+    }>;
     /**
      * Returns up to `limit` unprocessed outbox events, oldest first.
      * Works regardless of enableOutbox value — allows draining after disabling.
@@ -1899,4 +2103,4 @@ declare class WikiMemory {
     }): Promise<void>;
 }
 
-export { JobManager as $, WikiBusyError as A, type WikiBusyOperation as B, type WikiCheckpoint as C, type WikiConfig as D, type EntityStatus as E, type FormatContextOptions as F, type GraphNeighborhood as G, HEAL_BATCH_SIZE as H, WikiDuplicateHashError as I, type WikiEdge as J, type WikiEvent as K, type LLMProvider as L, type MemoryBundle as M, type WikiFact as N, type OntologyManifest as O, type PromptOverrides as P, type WikiMemoryTestAccess as Q, type ReadOptions as R, type SQLiteAdapter as S, type WikiOutboxEvent as T, type WikiTask as U, type VectorRanker as V, type WikiOptions as W, WikiTransactionError as X, EmbeddingService as Y, ImportExportService as Z, IngestionService as _, type MemoryDump as a, MaintenanceService as a0, RetrievalService as a1, SearchService as a2, WriteService as a3, 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, HEAL_RECHECK_MS as i, HOOK_TIMEOUT_MARKER as j, type HealResult as k, ONTOLOGY_BACKFILL_BATCH_SIZE as l, ONTOLOGY_BACKFILL_MAX_PROMPT_CHARS as m, ONTOLOGY_BACKFILL_RECHECK_MS as n, type OntologyBackfillResult as o, type OntologyConfig as p, type OntologyEdgeType as q, type OntologyMode as r, type OntologyNodeType as s, type OntologyPromptContext as t, type OntologyUpdates as u, PromptService as v, PrunePartialFailureError as w, type VectorRankerFallback as x, type VectorRankerRankArgs as y, type VectorRankerSemanticResult as z };
+export { ImportExportService as $, WikiBusyError as A, type WikiBusyOperation as B, type WikiCheckpoint as C, type WikiConfig as D, type EntityStatus as E, type FormatContextOptions as F, type GraphNeighborhood as G, HEAL_BATCH_SIZE as H, WikiDuplicateHashError as I, type WikiEdge as J, type WikiEvent as K, type LLMProvider as L, type MemoryBundle as M, type WikiFact as N, type OntologyManifest as O, type PromptOverrides as P, type WikiMemoryTestAccess as Q, type ReadOptions as R, type SQLiteAdapter as S, type WikiOutboxEvent as T, WikiSourceRefHashCollision as U, type VectorRanker as V, type WikiOptions as W, WikiStrictOntologyViolation as X, type WikiTask as Y, WikiTransactionError as Z, EmbeddingService as _, type MemoryDump as a, IngestionService as a0, JobManager as a1, MaintenanceService as a2, RetrievalService as a3, SearchService as a4, WriteService as a5, 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, HEAL_RECHECK_MS as i, HOOK_TIMEOUT_MARKER as j, type HealResult as k, ONTOLOGY_BACKFILL_BATCH_SIZE as l, ONTOLOGY_BACKFILL_MAX_PROMPT_CHARS as m, ONTOLOGY_BACKFILL_RECHECK_MS as n, type OntologyBackfillResult as o, type OntologyConfig as p, type OntologyEdgeType as q, type OntologyMode as r, type OntologyNodeType as s, type OntologyPromptContext as t, type OntologyUpdates as u, PromptService as v, PrunePartialFailureError as w, type VectorRankerFallback as x, type VectorRankerRankArgs as y, type VectorRankerSemanticResult as z };