@equationalapplications/core-llm-wiki 5.2.0 → 5.3.0

package/dist/index.mjs

@@ -1,5 +1,5 @@
-import { __privateAdd, MetadataRepository, EmbeddingService, SearchService, JobManager, PromptService, IngestionService, MaintenanceService, ImportExportService, RetrievalService, WriteService, __privateGet, __privateSet, normalizeSourceRef, normalizeSourceHash, entitySummaryMetaKey, generateId, BaseRepository, emptyManifest, resolveNodeType, validateInlineEdges, resolveEdgeDefinitions, normalizeTitleKey, WikiTransactionError, extractSqliteCode } from './chunk-J3N3WRK7.mjs';
-export { DEFAULT_CHUNK_OVERLAP, DEFAULT_MAX_CHUNK_LENGTH, HEAL_BATCH_SIZE, HEAL_RECHECK_MS, HOOK_TIMEOUT_MARKER, ONTOLOGY_BACKFILL_BATCH_SIZE, ONTOLOGY_BACKFILL_MAX_PROMPT_CHARS, ONTOLOGY_BACKFILL_RECHECK_MS, ONTOLOGY_BACKFILL_SYSTEM_PROMPT, PromptService, PrunePartialFailureError, WikiBusyError, WikiDuplicateHashError, WikiTransactionError, chunkText, configureRandomSource, parseEmbedding, safeSlice, validateManifest } from './chunk-J3N3WRK7.mjs';
+import { __privateAdd, MetadataRepository, EmbeddingService, SearchService, JobManager, PromptService, IngestionService, MaintenanceService, ImportExportService, RetrievalService, WriteService, __privateGet, __privateSet, normalizeSourceRef, normalizeSourceHash, entitySummaryMetaKey, WikiSourceRefHashCollision, generateId, BaseRepository, emptyManifest, resolveNodeType, WikiStrictOntologyViolation, validateInlineEdges, resolveEdgeDefinitions, normalizeTitleKey, WikiTransactionError, extractSqliteCode } from './chunk-KIJINNYU.mjs';
+export { DEFAULT_CHUNK_OVERLAP, DEFAULT_MAX_CHUNK_LENGTH, HEAL_BATCH_SIZE, HEAL_RECHECK_MS, HOOK_TIMEOUT_MARKER, ONTOLOGY_BACKFILL_BATCH_SIZE, ONTOLOGY_BACKFILL_MAX_PROMPT_CHARS, ONTOLOGY_BACKFILL_RECHECK_MS, ONTOLOGY_BACKFILL_SYSTEM_PROMPT, PromptService, PrunePartialFailureError, WikiBusyError, WikiDuplicateHashError, WikiSourceRefHashCollision, WikiStrictOntologyViolation, WikiTransactionError, chunkText, configureRandomSource, parseEmbedding, safeSlice, validateManifest } from './chunk-KIJINNYU.mjs';
 import { appendRelatedSection, buildConceptDocument, buildLogMd, buildEntityIndexMd, buildRootIndexMd, isAllowedOkfPath, parseRootIndexMd, parseEntityIndexMd, parseConcept, splitRelatedSection, extractMarkdownLinks, parseLogMd, parseEventIdComment, appendEventIdComment } from '@equationalapplications/core-okf';
 
 // src/db/schema.ts
@@ -32,6 +32,24 @@ async function setupDatabase(db, prefix) {
     CREATE INDEX IF NOT EXISTS ${prefix}entries_source_hash_idx ON ${prefix}entries(entity_id, source_hash) WHERE source_hash IS NOT NULL;
     CREATE INDEX IF NOT EXISTS ${prefix}entries_updated_idx ON ${prefix}entries(updated_at DESC);
 
+    -- source_ref_index: per-(entity, source_hash) record of the canonical sourceRef
+    -- currently holding that hash. The partial UNIQUE index on (entity_id, source_hash)
+    -- WHERE deleted_at IS NULL enforces the sourceRef-level TOCTOU-race invariant;
+    -- entries-level uniqueness cannot express it because a single ingestDocument call
+    -- writes N facts that all share (entity_id, source_ref, source_hash). See
+    -- docs/superpowers/specs/2026-08-07-dependabot-concurrency-release-hygiene-design.md \xA7B1.
+    CREATE TABLE IF NOT EXISTS ${prefix}source_ref_index (
+      id TEXT PRIMARY KEY,
+      entity_id TEXT NOT NULL,
+      source_hash TEXT NOT NULL,
+      source_ref TEXT NOT NULL,
+      created_at INTEGER NOT NULL,
+      deleted_at INTEGER
+    );
+    CREATE UNIQUE INDEX IF NOT EXISTS ${prefix}idx_source_ref_hash
+      ON ${prefix}source_ref_index (entity_id, source_hash)
+      WHERE deleted_at IS NULL;
+
     CREATE TABLE IF NOT EXISTS ${prefix}tasks (
       id TEXT PRIMARY KEY,
       entity_id TEXT NOT NULL,
@@ -278,6 +296,61 @@ var MIGRATIONS = [
         );
       }
     }
+  },
+  {
+    version: 9,
+    description: "add_source_ref_index",
+    run: async (db, prefix) => {
+      const duplicates = await db.getAllAsync(
+        `SELECT entity_id, source_hash, COUNT(DISTINCT source_ref) AS n_refs
+         FROM ${prefix}entries
+         WHERE deleted_at IS NULL AND source_hash IS NOT NULL
+         GROUP BY entity_id, source_hash
+         HAVING COUNT(DISTINCT source_ref) > 1`
+      );
+      if (duplicates.length > 0) {
+        const sample = duplicates.slice(0, 5).map((d) => `(entity_id=${d.entity_id}, source_hash=${d.source_hash.slice(0, 12)}\u2026, n_refs=${d.n_refs})`).join(", ");
+        throw new Error(
+          `Migration v9 (add_source_ref_index) failed: existing live rows have multiple sourceRefs sharing a hash. Found ${duplicates.length} duplicate (entity_id, source_hash) groups. First ${Math.min(5, duplicates.length)}: ${sample}. Resolve each by calling forget({ sourceRef: <loser> }) for the offending sourceRef, then re-run setup.`
+        );
+      }
+      await db.execAsync(
+        `CREATE TABLE IF NOT EXISTS ${prefix}source_ref_index (
+          id TEXT PRIMARY KEY,
+          entity_id TEXT NOT NULL,
+          source_hash TEXT NOT NULL,
+          source_ref TEXT NOT NULL,
+          created_at INTEGER NOT NULL,
+          deleted_at INTEGER
+        );
+        CREATE UNIQUE INDEX IF NOT EXISTS ${prefix}idx_source_ref_hash
+          ON ${prefix}source_ref_index (entity_id, source_hash)
+          WHERE deleted_at IS NULL;`
+      );
+      await db.execAsync(
+        `INSERT OR IGNORE INTO ${prefix}source_ref_index (id, entity_id, source_hash, source_ref, created_at, deleted_at)
+         SELECT
+           'sri:' || entity_id || ':' || source_hash,
+           entity_id,
+           source_hash,
+           source_ref,
+           updated_at,
+           NULL
+         FROM (
+           SELECT
+             entity_id, source_hash, source_ref, updated_at,
+             ROW_NUMBER() OVER (
+               PARTITION BY entity_id, source_hash
+               ORDER BY updated_at ASC, id ASC
+             ) AS rn
+           FROM ${prefix}entries
+           WHERE deleted_at IS NULL
+             AND source_hash IS NOT NULL
+             AND source_ref IS NOT NULL
+         ) ranked
+         WHERE rn = 1;`
+      );
+    }
   }
 ];
 for (let i = 1; i < MIGRATIONS.length; i++) {
@@ -663,12 +736,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);
   }
@@ -1394,6 +1477,57 @@ var OutboxRepository = class extends BaseRepository {
   }
 };
 
+// src/repositories/SourceRefIndexRepository.ts
+var SourceRefIndexRepository = class extends BaseRepository {
+  /**
+   * Idempotent insert: the partial UNIQUE index catches concurrent inserts for
+   * the same (entity_id, source_hash). The caller (IngestionService) catches
+   * the resulting SQLITE_CONSTRAINT_UNIQUE and translates it to the per-mode
+   * duplicate-hash outcome. Runtime IDs use the `sri_` prefix to avoid
+   * collision with the deterministic `sri:<entity>:<hash>` IDs used by the v9
+   * backfill (the colon separator keeps the two ID spaces disjoint).
+   */
+  async upsert(entityId, sourceHash, sourceRef, tx) {
+    const executor = this.getExecutor(tx);
+    await executor.runAsync(
+      `INSERT INTO ${this.prefix}source_ref_index (id, entity_id, source_hash, source_ref, created_at, deleted_at)
+       VALUES (?, ?, ?, ?, ?, NULL)`,
+      [generateId("sri_"), entityId, sourceHash, sourceRef, Date.now()]
+    );
+  }
+  /**
+   * Idempotent soft-delete of the live row for (entity_id, source_ref).
+   * Called at the start of every ingestDocument to remove the prior run's
+   * index row, so the new upsert doesn't collide with itself. No-op when the
+   * row is already soft-deleted or never existed.
+   */
+  async softDeleteByEntityAndSourceRef(entityId, sourceRef, tx) {
+    const executor = this.getExecutor(tx);
+    const now = Date.now();
+    const result = await executor.runAsync(
+      `UPDATE ${this.prefix}source_ref_index
+       SET deleted_at = ?, created_at = ?
+       WHERE entity_id = ? AND source_ref = ? AND deleted_at IS NULL`,
+      [now, now, entityId, sourceRef]
+    );
+    return result.changes;
+  }
+  /**
+   * Returns the live sourceRef holding the given hash, or null when no live
+   * row exists. Used by the IngestionService pre-check (line 82) and the
+   * catch-and-translate canonical lookup (line 212).
+   */
+  async findActiveByEntityAndHash(entityId, sourceHash, tx) {
+    const executor = this.getExecutor(tx);
+    const row = await executor.getFirstAsync(
+      `SELECT source_ref FROM ${this.prefix}source_ref_index
+       WHERE entity_id = ? AND source_hash = ? AND deleted_at IS NULL`,
+      [entityId, sourceHash]
+    );
+    return row?.source_ref ?? null;
+  }
+};
+
 // src/repositories/TaskRepository.ts
 function mapRowToTask(row) {
   return {
@@ -1808,6 +1942,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.
@@ -1986,16 +2148,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;
@@ -2006,15 +2179,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;
@@ -2070,6 +2257,7 @@ var WikiMemory = class {
     }
     this.outboxRepo = new OutboxRepository(this.db, this.prefix, !!options.config?.enableOutbox);
     this.entryRepo = new EntryRepository(this.db, this.prefix, this.outboxRepo);
+    this.sourceRefIndexRepo = new SourceRefIndexRepository(this.db, this.prefix);
     this.taskRepo = new TaskRepository(this.db, this.prefix, this.outboxRepo);
     this.eventRepo = new EventRepository(this.db, this.prefix);
     this.edgeRepo = new EdgeRepository(this.db, this.prefix);
@@ -2088,6 +2276,9 @@ var WikiMemory = class {
       this.prefix,
       this.options,
       this.entryRepo,
+      this.sourceRefIndexRepo,
+      this.metadataRepo,
+      this.edgeRepo,
       this.searchService,
       this.jobManager,
       this.embeddingService,
@@ -2099,6 +2290,7 @@ var WikiMemory = class {
       this.prefix,
       this.options,
       this.entryRepo,
+      this.sourceRefIndexRepo,
       this.taskRepo,
       this.eventRepo,
       this.metadataRepo,
@@ -2163,6 +2355,7 @@ var WikiMemory = class {
       promptService: this.promptService,
       graphTraversalService: this.graphTraversalService,
       entryRepo: this.entryRepo,
+      sourceRefIndexRepo: this.sourceRefIndexRepo,
       metadataRepo: this.metadataRepo,
       jobManager: this.jobManager
     };
@@ -2239,7 +2432,7 @@ var WikiMemory = class {
     const latestHashes = await this.entryRepo.findLatestSourceHashes(entityId, normalized.map((e) => e.sourceRef));
     const distinctHashes = Array.from(new Set(normalized.map((e) => e.sourceHash)));
     const dupRefs = await Promise.all(
-      distinctHashes.map((h) => this.entryRepo.findSourceRefsByHash(entityId, h))
+      distinctHashes.map((h) => this.sourceRefIndexRepo.findActiveByEntityAndHash(entityId, h))
     );
     const dupMap = /* @__PURE__ */ new Map();
     for (let i = 0; i < distinctHashes.length; i++) {
@@ -2248,12 +2441,10 @@ var WikiMemory = class {
     return normalized.map((e) => {
       const stored = latestHashes.get(e.sourceRef);
       const changed = stored === void 0 || stored === null || normalizeSourceHash(stored) !== e.sourceHash;
-      const allRefs = dupMap.get(e.sourceHash) ?? [];
-      const others = allRefs.filter((r) => r !== e.sourceRef);
-      if (others.length === 0) {
+      const canonical = dupMap.get(e.sourceHash) ?? null;
+      if (canonical === null || canonical === e.sourceRef) {
         return { sourceRef: e.rawSourceRef, changed };
       }
-      const canonical = others[0];
       return { sourceRef: e.rawSourceRef, changed, duplicateOf: canonical };
     });
   }
@@ -2268,13 +2459,47 @@ var WikiMemory = class {
     return this.entryRepo.listSourceRefs(entityId);
   }
   /**
-   * Returns the live source_refs for an entity that hold the given source_hash,
-   * sorted `COLLATE BINARY` ascending. The first element is the canonical ref
-   * under the code-unit-minimum rule (no locale dependency). Used by the
-   * ingestDocument guard and by hosts auditing duplicate-content collisions.
+   * Returns the live source_refs for an entity that hold the given source_hash.
+   * With v9, source_ref_index is the source of truth for the sourceRef-level
+   * TOCTOU-race invariant: at most one sourceRef can hold a given
+   * (entity_id, source_hash). The result is either a single-element array
+   * (one canonical ref) or empty (no live ref holds the hash). Returned as
+   * an array to preserve the existing public-API shape used by hosts
+   * auditing duplicate-content collisions.
    */
   async findSourceRefsByHash(entityId, sourceHash) {
-    return this.entryRepo.findSourceRefsByHash(entityId, sourceHash);
+    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);
@@ -2372,6 +2597,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.