@equationalapplications/core-llm-wiki 5.2.1 → 5.3.0

package/dist/index.d.mts

@@ -1,5 +1,5 @@
-import { M as MemoryBundle, F as FormatContextOptions, G as GraphNeighborhood, a as MemoryDump, b as FormattedMemoryDump, O as OntologyManifest, R as ReadOptions, S as SQLiteAdapter, W as WikiOptions, c as WikiMemory } from './testing-CAk9oFvw.mjs';
-export { E as EntityStatus, d as ExtractedFact, e as ExtractedFactEdge, f as ExtractedFactWithOntology, g as ExtractedTask, h as GraphTraversalOptions, H as HEAL_BATCH_SIZE, i as HEAL_RECHECK_MS, j as HOOK_TIMEOUT_MARKER, k as HealResult, L as LLMProvider, l as ONTOLOGY_BACKFILL_BATCH_SIZE, m as ONTOLOGY_BACKFILL_MAX_PROMPT_CHARS, n as ONTOLOGY_BACKFILL_RECHECK_MS, o as OntologyBackfillResult, p as OntologyConfig, q as OntologyEdgeType, r as OntologyMode, s as OntologyNodeType, t as OntologyPromptContext, u as OntologyUpdates, P as PromptOverrides, v as PromptService, w as PrunePartialFailureError, V as VectorRanker, x as VectorRankerFallback, y as VectorRankerRankArgs, z as VectorRankerSemanticResult, A as WikiBusyError, B as WikiBusyOperation, C as WikiCheckpoint, D as WikiConfig, I as WikiDuplicateHashError, J as WikiEdge, K as WikiEvent, N as WikiFact, Q as WikiMemoryTestAccess, T as WikiOutboxEvent, U as WikiTask, X as WikiTransactionError } from './testing-CAk9oFvw.mjs';
+import { M as MemoryBundle, F as FormatContextOptions, G as GraphNeighborhood, a as MemoryDump, b as FormattedMemoryDump, O as OntologyManifest, R as ReadOptions, S as SQLiteAdapter, W as WikiOptions, c as WikiMemory } from './testing-zf3Jp_RL.mjs';
+export { E as EntityStatus, d as ExtractedFact, e as ExtractedFactEdge, f as ExtractedFactWithOntology, g as ExtractedTask, h as GraphTraversalOptions, H as HEAL_BATCH_SIZE, i as HEAL_RECHECK_MS, j as HOOK_TIMEOUT_MARKER, k as HealResult, L as LLMProvider, l as ONTOLOGY_BACKFILL_BATCH_SIZE, m as ONTOLOGY_BACKFILL_MAX_PROMPT_CHARS, n as ONTOLOGY_BACKFILL_RECHECK_MS, o as OntologyBackfillResult, p as OntologyConfig, q as OntologyEdgeType, r as OntologyMode, s as OntologyNodeType, t as OntologyPromptContext, u as OntologyUpdates, P as PromptOverrides, v as PromptService, w as PrunePartialFailureError, V as VectorRanker, x as VectorRankerFallback, y as VectorRankerRankArgs, z as VectorRankerSemanticResult, A as WikiBusyError, B as WikiBusyOperation, C as WikiCheckpoint, D as WikiConfig, I as WikiDuplicateHashError, J as WikiEdge, K as WikiEvent, N as WikiFact, Q as WikiMemoryTestAccess, T as WikiOutboxEvent, U as WikiSourceRefHashCollision, X as WikiStrictOntologyViolation, Y as WikiTask, Z as WikiTransactionError } from './testing-zf3Jp_RL.mjs';
 import { OkfFile } from '@equationalapplications/core-okf';
 import 'minisearch';
 

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { M as MemoryBundle, F as FormatContextOptions, G as GraphNeighborhood, a as MemoryDump, b as FormattedMemoryDump, O as OntologyManifest, R as ReadOptions, S as SQLiteAdapter, W as WikiOptions, c as WikiMemory } from './testing-CAk9oFvw.js';
-export { E as EntityStatus, d as ExtractedFact, e as ExtractedFactEdge, f as ExtractedFactWithOntology, g as ExtractedTask, h as GraphTraversalOptions, H as HEAL_BATCH_SIZE, i as HEAL_RECHECK_MS, j as HOOK_TIMEOUT_MARKER, k as HealResult, L as LLMProvider, l as ONTOLOGY_BACKFILL_BATCH_SIZE, m as ONTOLOGY_BACKFILL_MAX_PROMPT_CHARS, n as ONTOLOGY_BACKFILL_RECHECK_MS, o as OntologyBackfillResult, p as OntologyConfig, q as OntologyEdgeType, r as OntologyMode, s as OntologyNodeType, t as OntologyPromptContext, u as OntologyUpdates, P as PromptOverrides, v as PromptService, w as PrunePartialFailureError, V as VectorRanker, x as VectorRankerFallback, y as VectorRankerRankArgs, z as VectorRankerSemanticResult, A as WikiBusyError, B as WikiBusyOperation, C as WikiCheckpoint, D as WikiConfig, I as WikiDuplicateHashError, J as WikiEdge, K as WikiEvent, N as WikiFact, Q as WikiMemoryTestAccess, T as WikiOutboxEvent, U as WikiTask, X as WikiTransactionError } from './testing-CAk9oFvw.js';
+import { M as MemoryBundle, F as FormatContextOptions, G as GraphNeighborhood, a as MemoryDump, b as FormattedMemoryDump, O as OntologyManifest, R as ReadOptions, S as SQLiteAdapter, W as WikiOptions, c as WikiMemory } from './testing-zf3Jp_RL.js';
+export { E as EntityStatus, d as ExtractedFact, e as ExtractedFactEdge, f as ExtractedFactWithOntology, g as ExtractedTask, h as GraphTraversalOptions, H as HEAL_BATCH_SIZE, i as HEAL_RECHECK_MS, j as HOOK_TIMEOUT_MARKER, k as HealResult, L as LLMProvider, l as ONTOLOGY_BACKFILL_BATCH_SIZE, m as ONTOLOGY_BACKFILL_MAX_PROMPT_CHARS, n as ONTOLOGY_BACKFILL_RECHECK_MS, o as OntologyBackfillResult, p as OntologyConfig, q as OntologyEdgeType, r as OntologyMode, s as OntologyNodeType, t as OntologyPromptContext, u as OntologyUpdates, P as PromptOverrides, v as PromptService, w as PrunePartialFailureError, V as VectorRanker, x as VectorRankerFallback, y as VectorRankerRankArgs, z as VectorRankerSemanticResult, A as WikiBusyError, B as WikiBusyOperation, C as WikiCheckpoint, D as WikiConfig, I as WikiDuplicateHashError, J as WikiEdge, K as WikiEvent, N as WikiFact, Q as WikiMemoryTestAccess, T as WikiOutboxEvent, U as WikiSourceRefHashCollision, X as WikiStrictOntologyViolation, Y as WikiTask, Z as WikiTransactionError } from './testing-zf3Jp_RL.js';
 import { OkfFile } from '@equationalapplications/core-okf';
 import 'minisearch';
 

package/dist/index.js

@@ -208,6 +208,31 @@ var WikiDuplicateHashError = class extends Error {
     this.entityId = params.entityId;
   }
 };
+var WikiStrictOntologyViolation = class extends Error {
+  constructor(entityId, kind, type) {
+    super(
+      `Out-of-manifest ${kind} type "${type}" for entity "${entityId}" under strict mode.`
+    );
+    this.code = "WIKI_STRICT_ONTOLOGY_VIOLATION";
+    this.entityId = entityId;
+    this.kind = kind;
+    this.type = type;
+    this.name = "WikiStrictOntologyViolation";
+  }
+};
+var WikiSourceRefHashCollision = class extends Error {
+  constructor(params) {
+    super(
+      `Source hash "${params.sourceHash}" for entity "${params.entityId}" is already mapped to sourceRef "${params.existingSourceRef}"; cannot remap to "${params.attemptedSourceRef}".`
+    );
+    this.code = "WIKI_SOURCE_REF_HASH_COLLISION";
+    this.entityId = params.entityId;
+    this.sourceHash = params.sourceHash;
+    this.existingSourceRef = params.existingSourceRef;
+    this.attemptedSourceRef = params.attemptedSourceRef;
+    this.name = "WikiSourceRefHashCollision";
+  }
+};
 var WikiTransactionError = class extends Error {
   constructor(message, options) {
     super(message, options);
@@ -856,12 +881,22 @@ var EntryRepository = class 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.
    */
-  async findRecentByEntityId(entityId, limit, tx) {
+  async findRecentByEntityId(entityId, limit, tx, excludeSourceRef) {
     const executor = this.getExecutor(tx);
+    const excludeClause = excludeSourceRef ? ` AND (source_ref IS NULL OR source_ref != ?)` : "";
+    const args = excludeSourceRef ? [entityId, excludeSourceRef, limit] : [entityId, limit];
     const rows = await executor.getAllAsync(
-      `SELECT * FROM ${this.prefix}entries WHERE entity_id = ? AND deleted_at IS NULL ORDER BY updated_at DESC LIMIT ?`,
-      [entityId, limit]
+      `SELECT * FROM ${this.prefix}entries WHERE entity_id = ? AND deleted_at IS NULL${excludeClause} ORDER BY updated_at DESC LIMIT ?`,
+      args
     );
     return rows.map(mapRowToFact);
   }
@@ -2076,6 +2111,34 @@ var EdgeRepository = class extends BaseRepository {
     const executor = this.getExecutor(tx);
     await executor.runAsync(`DELETE FROM ${this.prefix}edges WHERE entity_id = ?`, [entityId]);
   }
+  /**
+   * 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`.
+   */
+  async softDeleteBySourceFactIds(entityId, sourceFactIds, tx) {
+    if (sourceFactIds.length === 0) return 0;
+    const executor = this.getExecutor(tx);
+    const chunkSize = 500;
+    let totalChanges = 0;
+    for (let i = 0; i < sourceFactIds.length; i += chunkSize) {
+      const chunk = sourceFactIds.slice(i, i + chunkSize);
+      const placeholders = chunk.map(() => "?").join(",");
+      const result = await executor.runAsync(
+        `DELETE FROM ${this.prefix}edges
+         WHERE entity_id = ? AND source_id IN (${placeholders})`,
+        [entityId, ...chunk]
+      );
+      totalChanges += result.changes;
+    }
+    return totalChanges;
+  }
   /**
    * Multi-hop traversal from `sourceId` via SQLite `WITH RECURSIVE`. All filtering,
    * dead-ending, cycle-guarding, capping, and ordering happens in this one query.
@@ -2262,14 +2325,25 @@ function mergeOntologyUpdates(current, updates) {
   }
   return { node_types, edge_types };
 }
-function validateInlineEdges(sourceType, _targetType, edges, manifest) {
-  if (!Array.isArray(edges)) return [];
+function validateInlineEdges(sourceType, _targetType, edges, manifest, opts) {
+  const strict = opts?.strict === true;
+  const entityId = opts?.entityId ?? "";
+  if (!Array.isArray(edges)) {
+    if (strict) throw new WikiStrictOntologyViolation(entityId, "edge", "");
+    return [];
+  }
   const valid = [];
   for (const edge of edges) {
-    if (typeof edge?.edge_type !== "string" || typeof edge?.target_title !== "string") continue;
+    if (typeof edge?.edge_type !== "string" || typeof edge?.target_title !== "string") {
+      if (strict) throw new WikiStrictOntologyViolation(entityId, "edge", String(edge?.edge_type ?? ""));
+      continue;
+    }
     const defs = resolveEdgeDefinitions(edge.edge_type, manifest);
     const match = defs.find((d) => d.source_type.toLowerCase() === sourceType.toLowerCase());
-    if (!match) continue;
+    if (!match) {
+      if (strict) throw new WikiStrictOntologyViolation(entityId, "edge", edge.edge_type);
+      continue;
+    }
     valid.push({ edge_type: match.type, target_title: edge.target_title });
   }
   return valid;
@@ -2370,16 +2444,25 @@ var MetadataRepository = class extends BaseRepository {
     await this.db.execAsync(`PRAGMA wal_checkpoint(TRUNCATE)`);
     await this.db.execAsync(`VACUUM`);
   }
+  /**
+   * 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.
+   */
   async getDistinctEntityIds(tx) {
     const executor = this.getExecutor(tx);
     const rows = await executor.getAllAsync(
       `SELECT DISTINCT entity_id FROM (
-         SELECT entity_id FROM ${this.prefix}entries WHERE deleted_at IS NULL
+         SELECT entity_id FROM ${this.prefix}entries
          UNION
-         SELECT entity_id FROM ${this.prefix}tasks WHERE deleted_at IS NULL
+         SELECT entity_id FROM ${this.prefix}tasks
          UNION
          SELECT entity_id FROM ${this.prefix}events
-       ) ORDER BY entity_id`
+       ) ORDER BY entity_id COLLATE BINARY`
     );
     return rows.map((r) => r.entity_id);
   }
@@ -3465,12 +3548,14 @@ var DEFAULT_CHUNK_OVERLAP = 400;
 
 // src/services/IngestionService.ts
 var IngestionService = class {
-  constructor(db, prefix, options, entryRepo, sourceRefIndexRepo, searchService, jobManager, embeddingService, promptService, ontologyService) {
+  constructor(db, prefix, options, entryRepo, sourceRefIndexRepo, metadataRepo, edgeRepo, searchService, jobManager, embeddingService, promptService, ontologyService) {
     this.db = db;
     this.prefix = prefix;
     this.options = options;
     this.entryRepo = entryRepo;
     this.sourceRefIndexRepo = sourceRefIndexRepo;
+    this.metadataRepo = metadataRepo;
+    this.edgeRepo = edgeRepo;
     this.searchService = searchService;
     this.jobManager = jobManager;
     this.embeddingService = embeddingService;
@@ -3543,12 +3628,8 @@ var IngestionService = class {
       try {
         await this.db.withTransactionAsync(async (tx) => {
           deletedSourceFactIds.push(...await this.entryRepo.findIdsBySource(entityId, sourceRef, null, tx, false));
-          await this.entryRepo.softDeleteBySource(entityId, tx, sourceRef, null);
-          await this.sourceRefIndexRepo.softDeleteByEntityAndSourceRef(entityId, sourceRef, tx);
-          await this.sourceRefIndexRepo.upsert(entityId, sourceHash, sourceRef, tx);
           const titleIndex = /* @__PURE__ */ new Map();
-          const pendingEdges = [];
-          const existingFacts = await this.entryRepo.findRecentByEntityId(entityId, 500, tx);
+          const existingFacts = await this.entryRepo.findRecentByEntityId(entityId, 500, tx, sourceRef);
           for (const existing of existingFacts) {
             titleIndex.set(normalizeTitleKey(existing.title), {
               id: existing.id,
@@ -3557,6 +3638,8 @@ var IngestionService = class {
           }
           let ontologyState = await this.ontologyService?.getEffectiveState(entityId, tx) ?? { mode: "off", manifest: { node_types: [], edge_types: [] } };
           let { mode, manifest } = ontologyState;
+          const hostNodes = [];
+          const rawEdgeRequests = [];
           for (const { facts, ontology_updates } of orderedChunkFacts) {
             if (mode === "emergent" && ontology_updates && this.ontologyService) {
               manifest = await this.ontologyService.mergeEmergentUpdates(entityId, ontology_updates, tx);
@@ -3565,45 +3648,51 @@ var IngestionService = class {
             }
             for (const fact of facts) {
               const ontologyFact = fact;
-              const normalized = this.ontologyService?.validateAndNormalizeFact(ontologyFact, manifest) ?? { okf_type: null, edges: [] };
+              const normalized = this.ontologyService?.validateAndNormalizeFact(ontologyFact, manifest, { strict: false }) ?? { okf_type: null, edges: [] };
               const id = generateId("fact_");
-              const wikiFact = {
+              hostNodes.push({
                 id,
-                entity_id: entityId,
+                type: ontologyFact.okf_type ?? "",
                 title: fact.title,
                 body: fact.body,
+                // Forward the LLM-extracted tags/confidence through the
+                // extracted-shape upsertGraphCore path so the entries row
+                // stores them (search filterability, heal-candidate
+                // selection, runReembed embedding-text signal). The public
+                // WikiMemory.upsertGraph API doesn't accept tags/confidence
+                // — host-supplied deterministic nodes default to [] and
+                // 'certain' as documented.
                 tags: fact.tags,
-                confidence: fact.confidence,
-                source_type: "immutable_document",
-                source_hash: sourceHash,
-                source_ref: sourceRef,
-                created_at: now,
-                updated_at: now,
-                last_accessed_at: null,
-                access_count: 0,
-                deleted_at: null,
-                okf_type: normalized.okf_type
-              };
-              await this.entryRepo.upsert(wikiFact, tx);
+                confidence: fact.confidence
+              });
               insertedFacts.push({ id, entity_id: entityId, title: fact.title, body: fact.body, tags: JSON.stringify(fact.tags) });
               titleIndex.set(normalizeTitleKey(fact.title), { id, okf_type: normalized.okf_type });
               if (normalized.edges.length > 0) {
-                pendingEdges.push({ sourceId: id, sourceType: normalized.okf_type, edges: normalized.edges });
+                rawEdgeRequests.push({ sourceId: id, sourceType: normalized.okf_type, edges: normalized.edges });
               }
             }
           }
-          for (const item of pendingEdges) {
-            await this.ontologyService?.resolveAndPersistEdges(
+          const hostEdges = [];
+          for (const req of rawEdgeRequests) {
+            const resolved = this.ontologyService?.resolveEdges(
               entityId,
-              item.sourceId,
-              item.sourceType,
-              item.edges ?? [],
+              req.sourceId,
+              req.sourceType,
+              req.edges,
               manifest,
               titleIndex,
-              tx,
               now
-            );
+            ) ?? [];
+            for (const e of resolved) {
+              hostEdges.push({ type: e.edge_type, sourceId: e.source_id, targetId: e.target_id });
+            }
           }
+          await this.upsertGraphCore(
+            entityId,
+            { sourceRef, sourceHash, nodes: hostNodes, edges: hostEdges },
+            tx,
+            { strict: false }
+          );
         });
       } catch (err) {
         const sqliteCode = err instanceof WikiTransactionError ? err.sqliteErrorCode : extractSqliteCode(err);
@@ -3633,6 +3722,126 @@ var IngestionService = class {
       releaseIngestLocks();
     }
   }
+  /**
+   * 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).
+   */
+  async upsertGraphCore(entityId, params, tx, opts) {
+    const now = Date.now();
+    const ontologyState = await this.ontologyService?.getEffectiveState(entityId, tx) ?? { mode: "off", manifest: { node_types: [], edge_types: [] } };
+    let { mode, manifest } = ontologyState;
+    const strictEffective = opts?.strict === false ? false : opts?.strict === true || mode === "strict";
+    const wikiFacts = [];
+    for (const node of params.nodes) {
+      const factLike = { okf_type: node.type, edges: [] };
+      const normalized = this.ontologyService?.validateAndNormalizeFact(factLike, manifest, {
+        strict: strictEffective,
+        entityId
+      }) ?? { okf_type: null};
+      const wikiFact = {
+        id: node.id,
+        entity_id: entityId,
+        title: node.title,
+        body: node.body ?? "",
+        // Public upsertGraph callers don't supply tags/confidence, so they
+        // default to [] / 'certain' for deterministic AST-grade facts.
+        // ingestDocument routes through this method for the LLM path and
+        // forwards the LLM-supplied tags + confidence, preserving the prior
+        // behavior (search filterability, heal-candidate selection, runReembed
+        // embedding-text signal).
+        tags: node.tags ? Array.from(node.tags) : [],
+        confidence: node.confidence ?? "certain",
+        source_type: "immutable_document",
+        source_hash: params.sourceHash,
+        source_ref: params.sourceRef,
+        created_at: now,
+        updated_at: now,
+        last_accessed_at: null,
+        access_count: 0,
+        deleted_at: null,
+        okf_type: normalized.okf_type
+      };
+      wikiFacts.push(wikiFact);
+    }
+    const sourceIdToType = /* @__PURE__ */ new Map();
+    for (const fact of wikiFacts) sourceIdToType.set(fact.id, fact.okf_type ?? null);
+    const hasConstraints = (manifest.node_types?.length ?? 0) > 0 || (manifest.edge_types?.length ?? 0) > 0;
+    const validEdges = [];
+    for (const edge of params.edges) {
+      if (!hasConstraints) {
+        validEdges.push({
+          id: edge.id ?? generateId(),
+          entity_id: entityId,
+          source_id: edge.sourceId,
+          target_id: edge.targetId,
+          edge_type: edge.type,
+          created_at: now
+        });
+        continue;
+      }
+      if (!sourceIdToType.has(edge.sourceId)) {
+        validEdges.push({
+          id: edge.id ?? generateId(),
+          entity_id: entityId,
+          source_id: edge.sourceId,
+          target_id: edge.targetId,
+          edge_type: edge.type,
+          created_at: now
+        });
+        continue;
+      }
+      const sourceType = sourceIdToType.get(edge.sourceId);
+      const candidates = (manifest.edge_types ?? []).filter(
+        (d) => d.type.toLowerCase() === edge.type.toLowerCase() && d.source_type.toLowerCase() === (sourceType ?? "").toLowerCase()
+      );
+      const match = candidates[0];
+      if (!match) {
+        if (strictEffective) throw new WikiStrictOntologyViolation(entityId, "edge", edge.type);
+        continue;
+      }
+      validEdges.push({
+        id: edge.id ?? generateId(),
+        entity_id: entityId,
+        source_id: edge.sourceId,
+        target_id: edge.targetId,
+        edge_type: match.type,
+        created_at: now
+      });
+    }
+    const deletedFactIds = await this.entryRepo.findIdsBySource(entityId, params.sourceRef, null, tx, false);
+    await this.entryRepo.softDeleteBySource(entityId, tx, params.sourceRef, null);
+    const deletedEdgeCount = await this.edgeRepo.softDeleteBySourceFactIds(entityId, deletedFactIds, tx);
+    await this.sourceRefIndexRepo.softDeleteByEntityAndSourceRef(entityId, params.sourceRef, tx);
+    await this.sourceRefIndexRepo.upsert(entityId, params.sourceHash, params.sourceRef, tx);
+    for (const wikiFact of wikiFacts) {
+      await this.entryRepo.upsert(wikiFact, tx);
+    }
+    let edgesInsertedCount = 0;
+    for (const edge of validEdges) {
+      const inserted = await this.edgeRepo.addIgnoreDuplicate(edge, tx);
+      if (inserted) edgesInsertedCount++;
+    }
+    return {
+      nodesWritten: wikiFacts.length,
+      edgesWritten: edgesInsertedCount,
+      superseded: deletedFactIds.length + deletedEdgeCount
+    };
+  }
 };
 
 // src/services/BoundedLlmCall.ts
@@ -4081,7 +4290,7 @@ var MaintenanceService = class {
         }
         if (skip) continue;
         const ontologyFact = fact;
-        const normalized = this.ontologyService?.validateAndNormalizeFact(ontologyFact, manifest) ?? { okf_type: null, edges: [] };
+        const normalized = this.ontologyService?.validateAndNormalizeFact(ontologyFact, manifest, { strict: false }) ?? { okf_type: null, edges: [] };
         const id = generateId("fact_");
         const factObj = {
           id,
@@ -4466,7 +4675,8 @@ var MaintenanceService = class {
             okf_type: classification.okf_type,
             edges: classification.edges
           },
-          manifest
+          manifest,
+          { strict: false }
         );
         if (!normalized.okf_type) {
           failedValidation++;
@@ -5856,16 +6066,27 @@ var OntologyService = class {
     this.invalidateCache(entityId);
     return merged;
   }
-  validateAndNormalizeFact(fact, manifest) {
+  validateAndNormalizeFact(fact, manifest, opts) {
     const rawType = typeof fact.okf_type === "string" ? fact.okf_type : "";
+    const strict = opts?.strict === true;
     const canonical = resolveNodeType(rawType, manifest);
-    if (!canonical) return { okf_type: null, edges: [] };
-    const edges = validateInlineEdges(canonical, null, fact.edges ?? [], manifest);
+    if (!canonical) {
+      if (strict) throw new WikiStrictOntologyViolation(opts?.entityId ?? "", "node", rawType);
+      return { okf_type: null, edges: [] };
+    }
+    const edges = validateInlineEdges(canonical, null, fact.edges ?? [], manifest, opts);
     return { okf_type: canonical, edges };
   }
-  async resolveAndPersistEdges(entityId, sourceId, sourceType, edges, manifest, titleIndex, tx, now) {
-    if (!sourceType || edges.length === 0) return 0;
-    let persisted = 0;
+  /**
+   * 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, sourceId, sourceType, edges, manifest, titleIndex, now) {
+    if (!sourceType || edges.length === 0) return [];
+    const out = [];
     for (const edge of edges) {
       const candidates = resolveEdgeDefinitions(edge.edge_type, manifest).filter((d) => d.source_type.toLowerCase() === sourceType.toLowerCase());
       if (candidates.length === 0) continue;
@@ -5876,15 +6097,29 @@ var OntologyService = class {
         (d) => d.target_type.toLowerCase() === (target.okf_type ?? "").toLowerCase()
       );
       if (!def) continue;
-      const wikiEdge = {
+      out.push({
         id: generateId(),
         entity_id: entityId,
         source_id: sourceId,
         target_id: target.id,
         edge_type: def.type,
         created_at: now
-      };
-      const inserted = await this.edgeRepo.addIgnoreDuplicate(wikiEdge, tx);
+      });
+    }
+    return out;
+  }
+  /**
+   * 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).
+   */
+  async resolveAndPersistEdges(entityId, sourceId, sourceType, edges, manifest, titleIndex, tx, now) {
+    const resolved = this.resolveEdges(entityId, sourceId, sourceType, edges, manifest, titleIndex, now);
+    let persisted = 0;
+    for (const edge of resolved) {
+      const inserted = await this.edgeRepo.addIgnoreDuplicate(edge, tx);
       if (inserted) persisted++;
     }
     return persisted;
@@ -5960,6 +6195,8 @@ var WikiMemory = class {
       this.options,
       this.entryRepo,
       this.sourceRefIndexRepo,
+      this.metadataRepo,
+      this.edgeRepo,
       this.searchService,
       this.jobManager,
       this.embeddingService,
@@ -6152,6 +6389,36 @@ var WikiMemory = class {
     const canonical = await this.sourceRefIndexRepo.findActiveByEntityAndHash(entityId, sourceHash);
     return canonical === null ? [] : [canonical];
   }
+  /**
+   * 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.
+   */
+  async listEntityIds(options) {
+    const ids = await this.metadataRepo.getDistinctEntityIds();
+    if (options?.prefix === void 0) return ids;
+    return ids.filter((id) => id.startsWith(options.prefix));
+  }
   async runPrune(entityId, options) {
     return this.maintenanceService.runPrune(entityId, options);
   }
@@ -6248,6 +6515,57 @@ var WikiMemory = class {
   async ingestDocument(entityId, params, opts) {
     return this.ingestionService.ingestDocument(entityId, params, opts);
   }
+  /**
+   * 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).
+   */
+  async upsertGraph(entityId, params, adapter) {
+    const sourceRef = normalizeSourceRef(params.sourceRef);
+    if (!sourceRef) throw new Error("Invalid sourceRef");
+    const sourceHash = normalizeSourceHash(params.sourceHash);
+    if (!sourceHash) throw new Error("Invalid sourceHash (must be 64-char hex string)");
+    const canonical = await this.sourceRefIndexRepo.findActiveByEntityAndHash(entityId, sourceHash, adapter);
+    if (canonical !== null && canonical === sourceRef) {
+      return { nodesWritten: 0, edgesWritten: 0, superseded: 0 };
+    }
+    if (canonical !== null && canonical !== sourceRef) {
+      throw new WikiSourceRefHashCollision({
+        entityId,
+        sourceHash,
+        existingSourceRef: canonical,
+        attemptedSourceRef: sourceRef
+      });
+    }
+    return this.ingestionService.upsertGraphCore(
+      entityId,
+      { sourceRef, sourceHash, nodes: params.nodes, edges: params.edges },
+      adapter
+    );
+  }
   /**
    * Returns up to `limit` unprocessed outbox events, oldest first.
    * Works regardless of enableOutbox value — allows draining after disabling.
@@ -7067,6 +7385,8 @@ exports.PrunePartialFailureError = PrunePartialFailureError;
 exports.WikiBusyError = WikiBusyError;
 exports.WikiDuplicateHashError = WikiDuplicateHashError;
 exports.WikiMemory = WikiMemory;
+exports.WikiSourceRefHashCollision = WikiSourceRefHashCollision;
+exports.WikiStrictOntologyViolation = WikiStrictOntologyViolation;
 exports.WikiTransactionError = WikiTransactionError;
 exports.chunkText = chunkText;
 exports.configureRandomSource = configureRandomSource;