@equationalapplications/core-llm-wiki 5.2.0 → 5.3.0

package/dist/testing.js

@@ -6,6 +6,59 @@ function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
 
 var MiniSearch__default = /*#__PURE__*/_interopDefault(MiniSearch);
 
+// src/db/sqliteCodes.ts
+var SQLITE_RESULT_CODE_NAMES = {
+  1: "SQLITE_ERROR",
+  2: "SQLITE_INTERNAL",
+  3: "SQLITE_PERM",
+  4: "SQLITE_ABORT",
+  5: "SQLITE_BUSY",
+  6: "SQLITE_LOCKED",
+  7: "SQLITE_NOMEM",
+  8: "SQLITE_READONLY",
+  9: "SQLITE_INTERRUPT",
+  10: "SQLITE_IOERR",
+  11: "SQLITE_CORRUPT",
+  12: "SQLITE_NOTFOUND",
+  13: "SQLITE_FULL",
+  14: "SQLITE_CANTOPEN",
+  15: "SQLITE_PROTOCOL",
+  16: "SQLITE_EMPTY",
+  17: "SQLITE_SCHEMA",
+  18: "SQLITE_TOOBIG",
+  19: "SQLITE_CONSTRAINT",
+  20: "SQLITE_MISMATCH",
+  21: "SQLITE_MISUSE",
+  22: "SQLITE_NOLFS",
+  23: "SQLITE_AUTH",
+  24: "SQLITE_FORMAT",
+  25: "SQLITE_RANGE",
+  26: "SQLITE_NOTADB",
+  27: "SQLITE_NOTICE",
+  28: "SQLITE_WARNING",
+  // Extended result codes (https://sqlite.org/rescode.html#extended_result_code_list).
+  // 2067 = SQLITE_CONSTRAINT_UNIQUE — raised when a UNIQUE index/PRIMARY KEY
+  // rejects an INSERT/UPDATE; expo-sqlite reports this as a numeric "Error code N:"
+  // prefix and we normalize it back to the symbolic name so callers can branch on
+  // the same string the rest of the ecosystem uses.
+  2067: "SQLITE_CONSTRAINT_UNIQUE",
+  100: "SQLITE_ROW",
+  101: "SQLITE_DONE"
+};
+function nameForSqliteResultCode(n) {
+  return SQLITE_RESULT_CODE_NAMES[n] ?? `SQLITE_${n}`;
+}
+function extractSqliteCode(err) {
+  if (typeof err !== "object" || err === null) return void 0;
+  const { code, message } = err;
+  if (typeof code === "string" && code.startsWith("SQLITE_")) return code;
+  if (typeof message === "string") {
+    const m = /^Error code (\d+):/.exec(message);
+    if (m) return nameForSqliteResultCode(Number(m[1]));
+  }
+  return void 0;
+}
+
 // src/types.ts
 var WikiBusyError = class extends Error {
   constructor(operation, entityId) {
@@ -24,6 +77,25 @@ 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 WikiTransactionError = class extends Error {
+  constructor(message, options) {
+    super(message, options);
+    this.name = "WikiTransactionError";
+    this.sqliteErrorCode = extractSqliteCode(options.cause);
+  }
+};
 var PrunePartialFailureError = class extends Error {
   constructor(deleted, failedAt, remaining, cause, deletedTasks = 0, deletedEvents = 0) {
     super(`Prune partially failed: deleted ${deleted}, failed at ${failedAt}, ${remaining} remaining`);
@@ -993,11 +1065,14 @@ var DEFAULT_CHUNK_OVERLAP = 400;
 
 // src/services/IngestionService.ts
 var IngestionService = class {
-  constructor(db, prefix, options, entryRepo, 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;
@@ -1009,18 +1084,6 @@ var IngestionService = class {
     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 onDuplicateHash = opts?.onDuplicateHash ?? "ingest";
-    if (onDuplicateHash !== "ingest") {
-      const refs = await this.entryRepo.findSourceRefsByHash(entityId, sourceHash);
-      const others = refs.filter((r) => r !== sourceRef);
-      if (others.length > 0) {
-        const canonical = others[0];
-        if (onDuplicateHash === "throw") {
-          throw new WikiDuplicateHashError({ canonical, sourceHash, entityId });
-        }
-        return { truncated: false, chunks: 0, duplicateOf: canonical };
-      }
-    }
     const maxChunkLength = params.maxChunkLength ?? this.options.config?.maxChunkLength ?? DEFAULT_MAX_CHUNK_LENGTH;
     const rawOverlap = params.chunkOverlap ?? this.options.config?.chunkOverlap ?? DEFAULT_CHUNK_OVERLAP;
     const chunkOverlap = Math.min(
@@ -1032,8 +1095,18 @@ var IngestionService = class {
     if (typeof params.documentChunk !== "string") {
       throw new Error(`documentChunk must be a string, received ${typeof params.documentChunk}`);
     }
-    this.jobManager.acquireLock("ingest", entityId, sourceRef);
+    const releaseIngestLocks = await this.jobManager.acquireIngestLocks(entityId, sourceRef, sourceHash);
     try {
+      const onDuplicateHash = opts?.onDuplicateHash ?? "ingest";
+      if (onDuplicateHash !== "ingest") {
+        const canonical = await this.sourceRefIndexRepo.findActiveByEntityAndHash(entityId, sourceHash);
+        if (canonical !== null && canonical !== sourceRef) {
+          if (onDuplicateHash === "throw") {
+            throw new WikiDuplicateHashError({ canonical, sourceHash, entityId });
+          }
+          return { truncated: false, chunks: 0, duplicateOf: canonical };
+        }
+      }
       const { chunks, truncated } = chunkText(params.documentChunk, maxChunkLength, chunkOverlap);
       if (chunks.length === 0) return { truncated: false, chunks: 0 };
       const chunkResults = await withConcurrency(
@@ -1069,68 +1142,85 @@ var IngestionService = class {
       const now = Date.now();
       const insertedFacts = [];
       const deletedSourceFactIds = [];
-      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);
-        const titleIndex = /* @__PURE__ */ new Map();
-        const pendingEdges = [];
-        const existingFacts = await this.entryRepo.findRecentByEntityId(entityId, 500, tx);
-        for (const existing of existingFacts) {
-          titleIndex.set(normalizeTitleKey(existing.title), {
-            id: existing.id,
-            okf_type: existing.okf_type ?? null
-          });
-        }
-        let ontologyState = await this.ontologyService?.getEffectiveState(entityId, tx) ?? { mode: "off", manifest: { node_types: [], edge_types: [] } };
-        let { mode, manifest } = ontologyState;
-        for (const { facts, ontology_updates } of orderedChunkFacts) {
-          if (mode === "emergent" && ontology_updates && this.ontologyService) {
-            manifest = await this.ontologyService.mergeEmergentUpdates(entityId, ontology_updates, tx);
-            ontologyState = await this.ontologyService.getEffectiveState(entityId, tx);
-            mode = ontologyState.mode;
+      try {
+        await this.db.withTransactionAsync(async (tx) => {
+          deletedSourceFactIds.push(...await this.entryRepo.findIdsBySource(entityId, sourceRef, null, tx, false));
+          const titleIndex = /* @__PURE__ */ new Map();
+          const existingFacts = await this.entryRepo.findRecentByEntityId(entityId, 500, tx, sourceRef);
+          for (const existing of existingFacts) {
+            titleIndex.set(normalizeTitleKey(existing.title), {
+              id: existing.id,
+              okf_type: existing.okf_type ?? null
+            });
           }
-          for (const fact of facts) {
-            const ontologyFact = fact;
-            const normalized = this.ontologyService?.validateAndNormalizeFact(ontologyFact, manifest) ?? { okf_type: null, edges: [] };
-            const id = generateId("fact_");
-            const wikiFact = {
-              id,
-              entity_id: entityId,
-              title: fact.title,
-              body: fact.body,
-              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);
-            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 });
+          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);
+              ontologyState = await this.ontologyService.getEffectiveState(entityId, tx);
+              mode = ontologyState.mode;
+            }
+            for (const fact of facts) {
+              const ontologyFact = fact;
+              const normalized = this.ontologyService?.validateAndNormalizeFact(ontologyFact, manifest, { strict: false }) ?? { okf_type: null, edges: [] };
+              const id = generateId("fact_");
+              hostNodes.push({
+                id,
+                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
+              });
+              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) {
+                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,
+              req.sourceId,
+              req.sourceType,
+              req.edges,
+              manifest,
+              titleIndex,
+              now
+            ) ?? [];
+            for (const e of resolved) {
+              hostEdges.push({ type: e.edge_type, sourceId: e.source_id, targetId: e.target_id });
+            }
+          }
+          await this.upsertGraphCore(
             entityId,
-            item.sourceId,
-            item.sourceType,
-            item.edges ?? [],
-            manifest,
-            titleIndex,
+            { sourceRef, sourceHash, nodes: hostNodes, edges: hostEdges },
             tx,
-            now
+            { strict: false }
           );
+        });
+      } catch (err) {
+        const sqliteCode = err instanceof WikiTransactionError ? err.sqliteErrorCode : extractSqliteCode(err);
+        if (sqliteCode !== "SQLITE_CONSTRAINT_UNIQUE") throw err;
+        const canonical = await this.sourceRefIndexRepo.findActiveByEntityAndHash(entityId, sourceHash);
+        if (canonical === null) throw err;
+        if (onDuplicateHash === "throw" || onDuplicateHash === "ingest") {
+          throw new WikiDuplicateHashError({ canonical, sourceHash, entityId });
         }
-      });
+        return { truncated: false, chunks: 0, duplicateOf: canonical };
+      }
       await this.searchService.sync(entityId);
       const uniqueDeletedSourceFactIds = Array.from(new Set(deletedSourceFactIds));
       for (const factId of uniqueDeletedSourceFactIds) {
@@ -1146,9 +1236,129 @@ var IngestionService = class {
       this.searchService.evictCache(entityId);
       return { truncated, chunks: chunks.length };
     } finally {
-      this.jobManager.releaseLock("ingest", entityId, sourceRef);
+      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/utils/embedding.ts
@@ -1298,11 +1508,12 @@ var HEAL_MAX_PROMPT_CHARS = 4e4;
 var HEAL_BATCH_SIZE = 25;
 var HEAL_RECHECK_MS = 7 * 24 * 60 * 60 * 1e3;
 var MaintenanceService = class {
-  constructor(db, prefix, options, entryRepo, taskRepo, eventRepo, metadataRepo, searchService, jobManager, embeddingService, promptService, ontologyService) {
+  constructor(db, prefix, options, entryRepo, sourceRefIndexRepo, taskRepo, eventRepo, metadataRepo, searchService, jobManager, embeddingService, promptService, ontologyService) {
     this.db = db;
     this.prefix = prefix;
     this.options = options;
     this.entryRepo = entryRepo;
+    this.sourceRefIndexRepo = sourceRefIndexRepo;
     this.taskRepo = taskRepo;
     this.eventRepo = eventRepo;
     this.metadataRepo = metadataRepo;
@@ -1501,10 +1712,12 @@ var MaintenanceService = class {
           const entryPromise = params.entryId ? this.entryRepo.softDelete(params.entryId, entityId, tx).then((r) => r.changes > 0) : null;
           const taskDeletedPromise = params.taskId ? this.taskRepo.softDeleteById(params.taskId, entityId, tx).then((r) => r.changes > 0) : null;
           const refPromise = sourceRef || sourceHash ? this.entryRepo.softDeleteBySource(entityId, tx, sourceRef, sourceHash) : null;
+          const sourceRefIndexPromise = sourceRef ? this.sourceRefIndexRepo.softDeleteByEntityAndSourceRef(entityId, sourceRef, tx).then(() => void 0) : null;
           const [entryResult, taskResult, refResult] = await Promise.all([
             entryPromise ?? Promise.resolve(false),
             taskDeletedPromise ?? Promise.resolve(false),
-            refPromise ?? Promise.resolve(0)
+            refPromise ?? Promise.resolve(0),
+            sourceRefIndexPromise ?? Promise.resolve(void 0)
           ]);
           if (entryResult) deletedEntries++;
           if (taskResult) deletedTasks++;
@@ -1622,7 +1835,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,
@@ -2007,7 +2220,8 @@ var MaintenanceService = class {
             okf_type: classification.okf_type,
             edges: classification.edges
           },
-          manifest
+          manifest,
+          { strict: false }
         );
         if (!normalized.okf_type) {
           failedValidation++;
@@ -2880,6 +3094,19 @@ var JobManager = class {
     this.prefix = prefix;
     this.activeMaintenanceJobs = /* @__PURE__ */ new Set();
     this.activeIngestJobs = /* @__PURE__ */ new Map();
+    /**
+     * Per-(entityId, sourceHash) promise-chain lock. Serializes ingest races
+     * at the application level (the v9 partial UNIQUE index enforces it at
+     * the DB level as defense-in-depth). Two callers holding the same hash
+     * see FIFO order; different hashes never block one another.
+     *
+     * Keyed `${entityId}\0${sourceHash}` so distinct (entityId, sourceHash)
+     * pairs can never share a lock. A raw concatenation would let
+     * ("ab", "c…") collide with ("a", "bc…"); the NUL separator makes that
+     * impossible because neither component can contain NUL (entityIds are
+     * user-supplied identifiers; sourceHashes are hex digests).
+     */
+    this.hashLocks = /* @__PURE__ */ new Map();
     this.statusSubscribers = /* @__PURE__ */ new Map();
     /**
      * Lookup table for acquireLock/releaseLock's dynamic-dispatch branch.
@@ -2897,6 +3124,51 @@ var JobManager = class {
       ontologyBackfill: (id) => this._ontologyBackfillKey(id)
     };
   }
+  _hashLockKey(entityId, sourceHash) {
+    return `${entityId}\0${sourceHash}`;
+  }
+  /**
+   * Acquire a promise-chain lock scoped to one `(entityId, sourceHash)` pair.
+   * Returns a zero-argument release closure that removes the current tail
+   * from the chain. Releasing is idempotent so a holder that double-fires
+   * (e.g. on a finally that races an explicit release) cannot unblock
+   * the next holder prematurely.
+   *
+   * Documented ordering: ingest acquires the hash lock FIRST, then the
+   * synchronous sourceRef ingest lock, and the release closure unwinds in
+   * the opposite order (sourceRef first, hash second). Hash-then-sourceRef
+   * is required because the v9 partial UNIQUE index conflicts on the
+   * (entity_id, source_hash) pair regardless of source_ref, so two callers
+   * with DIFFERENT source_refs racing the same hash are the exact case the
+   * TOCTOU race fix needs to serialize.
+   *
+   * Mechanics: each holder owns a private `released` promise that resolves
+   * only when THIS holder calls release(). The map stores the holder's
+   * `released` promise as the "tail" — the NEXT caller awaits that tail
+   * via `previous = this.hashLocks.get(key)`. The current caller gets
+   * their unique release function once `previous` (the prior holder's
+   * release signal) settles, so each holder is guaranteed a UNIQUE release
+   * closure bound to their own `released` promise.
+   */
+  acquireHashLock(entityId, sourceHash) {
+    const key = this._hashLockKey(entityId, sourceHash);
+    const previous = this.hashLocks.get(key) ?? Promise.resolve();
+    let resolveReleased;
+    const released = new Promise((resolve) => {
+      resolveReleased = resolve;
+    });
+    let fired = false;
+    const release = () => {
+      if (fired) return;
+      fired = true;
+      if (this.hashLocks.get(key) === released) {
+        this.hashLocks.delete(key);
+      }
+      resolveReleased();
+    };
+    this.hashLocks.set(key, released);
+    return previous.then(() => release);
+  }
   _pruneKey(entityId) {
     return `${this.prefix}:${entityId}:prune`;
   }
@@ -3110,6 +3382,38 @@ var JobManager = class {
     this._notifyStatusSubscribers(entityId);
     return true;
   }
+  /**
+   * Centralized ingest lock acquisition. Acquires the hash lock FIRST
+   * (FIFO across callers racing the same hash), then the synchronous
+   * sourceRef ingest lock (rejects cross-entity conflicts and busy
+   * operations). Returns a single zero-argument release closure that
+   * unwinds in the opposite order — sourceRef first, hash second — so
+   * the sourceRef lock is freed the instant its work is done and only
+   * the hash lock keeps serializing the duplicate-content race window.
+   *
+   * On a sourceRef conflict (WikiBusyError thrown synchronously by the
+   * underlying acquireLock) the hash lock is released BEFORE the error
+   * propagates, so the next caller in the hash chain is not held up by
+   * a request that never reached the DB.
+   */
+  async acquireIngestLocks(entityId, sourceRef, sourceHash) {
+    const releaseHash = await this.acquireHashLock(entityId, sourceHash);
+    let sourceLockAcquired = false;
+    try {
+      this.acquireLock("ingest", entityId, sourceRef);
+      sourceLockAcquired = true;
+    } catch (err) {
+      releaseHash();
+      throw err;
+    }
+    return () => {
+      try {
+        if (sourceLockAcquired) this.releaseLock("ingest", entityId, sourceRef);
+      } finally {
+        releaseHash();
+      }
+    };
+  }
   /**
    * Validates then acquires global + per-entity import locks atomically.
    * Validates all entities before acquiring any lock (same as current importDump semantics).