@equationalapplications/core-llm-wiki 5.2.0 → 5.2.1

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

@@ -943,6 +943,49 @@ declare class EntryRepository extends BaseRepository {
     }>>;
 }
 
+/**
+ * Per-(entity_id, 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
+ * for the #79 fix. See
+ * docs/superpowers/specs/2026-08-07-dependabot-concurrency-release-hygiene-design.md §B1.
+ *
+ * The entries table cannot express this invariant directly because a single
+ * `ingestDocument` call writes N facts that all share
+ * (entity_id, source_ref, source_hash); a UNIQUE index on
+ * `entries(entity_id, source_hash)` would block the 2nd–Nth fact inserts in
+ * the normal multi-fact path. The per-(entity, hash) granularity of
+ * source_ref_index matches the TOCTOU invariant exactly.
+ *
+ * No outbox events: this is an internal index table whose state is fully
+ * derivable from `entries`. Hosts that need CDC continue to read `entries`
+ * outbox events; the index is not part of the user-visible contract.
+ */
+declare class SourceRefIndexRepository 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).
+     */
+    upsert(entityId: string, sourceHash: string, sourceRef: string, tx: SQLiteAdapter): Promise<void>;
+    /**
+     * 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.
+     */
+    softDeleteByEntityAndSourceRef(entityId: string, sourceRef: string, tx: SQLiteAdapter): Promise<number>;
+    /**
+     * 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).
+     */
+    findActiveByEntityAndHash(entityId: string, sourceHash: string, tx?: SQLiteAdapter): Promise<string | null>;
+}
+
 declare class MetadataRepository extends BaseRepository {
     getCheckpoint(entityId: string, tx: SQLiteAdapter): Promise<{
         memory?: number;
@@ -1065,8 +1108,46 @@ declare class JobManager {
     private prefix;
     private activeMaintenanceJobs;
     private activeIngestJobs;
+    /**
+     * 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).
+     */
+    private hashLocks;
     private statusSubscribers;
     constructor(prefix: string);
+    private _hashLockKey;
+    /**
+     * 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: string, sourceHash: string): Promise<() => void>;
     private _pruneKey;
     private _reembedKey;
     private _globalReembedKey;
@@ -1103,6 +1184,21 @@ declare class JobManager {
      * for write() auto-trigger paths while preserving stricter checks in acquireLock().
      */
     tryAcquireAutoHealLock(entityId: string): boolean;
+    /**
+     * 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.
+     */
+    acquireIngestLocks(entityId: string, sourceRef: string, sourceHash: string): Promise<() => void>;
     /**
      * Validates then acquires global + per-entity import locks atomically.
      * Validates all entities before acquiring any lock (same as current importDump semantics).
@@ -1224,12 +1320,13 @@ declare class IngestionService {
     private prefix;
     private options;
     private entryRepo;
+    private sourceRefIndexRepo;
     private searchService;
     private jobManager;
     private embeddingService;
     private ontologyService?;
     private promptService;
-    constructor(db: SQLiteAdapter, prefix: string, options: WikiOptions, entryRepo: EntryRepository, searchService: SearchService, jobManager: JobManager, embeddingService: EmbeddingService, promptService?: PromptService, ontologyService?: OntologyService | undefined);
+    constructor(db: SQLiteAdapter, prefix: string, options: WikiOptions, entryRepo: EntryRepository, sourceRefIndexRepo: SourceRefIndexRepository, searchService: SearchService, jobManager: JobManager, embeddingService: EmbeddingService, promptService?: PromptService, ontologyService?: OntologyService | undefined);
     ingestDocument(entityId: string, params: {
         sourceRef: string;
         sourceHash: string;
@@ -1361,6 +1458,7 @@ declare class MaintenanceService {
     private prefix;
     private options;
     private entryRepo;
+    private sourceRefIndexRepo;
     private taskRepo;
     private eventRepo;
     private metadataRepo;
@@ -1369,7 +1467,7 @@ declare class MaintenanceService {
     private embeddingService;
     private ontologyService?;
     private promptService;
-    constructor(db: SQLiteAdapter, prefix: string, options: WikiOptions, entryRepo: EntryRepository, taskRepo: TaskRepository, eventRepo: EventRepository, metadataRepo: MetadataRepository, searchService: SearchService, jobManager: JobManager, embeddingService: EmbeddingService, promptService?: PromptService, ontologyService?: OntologyService | undefined);
+    constructor(db: SQLiteAdapter, prefix: string, options: WikiOptions, entryRepo: EntryRepository, sourceRefIndexRepo: SourceRefIndexRepository, taskRepo: TaskRepository, eventRepo: EventRepository, metadataRepo: MetadataRepository, searchService: SearchService, jobManager: JobManager, embeddingService: EmbeddingService, promptService?: PromptService, ontologyService?: OntologyService | undefined);
     runPrune(entityId: string, options?: {
         retainSoftDeletedFor?: number | null;
         retainEventsFor?: number | null;
@@ -1582,6 +1680,7 @@ interface WikiMemoryTestAccess {
     promptService: PromptService;
     graphTraversalService: GraphTraversalService;
     entryRepo: EntryRepository;
+    sourceRefIndexRepo: SourceRefIndexRepository;
     metadataRepo: MetadataRepository;
     jobManager: JobManager;
 }
@@ -1592,6 +1691,7 @@ declare class WikiMemory {
     private options;
     private entryRepo;
     private outboxRepo;
+    private sourceRefIndexRepo;
     private taskRepo;
     private eventRepo;
     private edgeRepo;
@@ -1647,10 +1747,13 @@ declare class WikiMemory {
         lastIngestedAt: number;
     }>>;
     /**
-     * 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.
      */
     findSourceRefsByHash(entityId: string, sourceHash: string): Promise<string[]>;
     runPrune(entityId: string, options?: {

package/dist/{testing-DyXISRwS.d.ts → testing-CAk9oFvw.d.ts}

@@ -943,6 +943,49 @@ declare class EntryRepository extends BaseRepository {
     }>>;
 }
 
+/**
+ * Per-(entity_id, 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
+ * for the #79 fix. See
+ * docs/superpowers/specs/2026-08-07-dependabot-concurrency-release-hygiene-design.md §B1.
+ *
+ * The entries table cannot express this invariant directly because a single
+ * `ingestDocument` call writes N facts that all share
+ * (entity_id, source_ref, source_hash); a UNIQUE index on
+ * `entries(entity_id, source_hash)` would block the 2nd–Nth fact inserts in
+ * the normal multi-fact path. The per-(entity, hash) granularity of
+ * source_ref_index matches the TOCTOU invariant exactly.
+ *
+ * No outbox events: this is an internal index table whose state is fully
+ * derivable from `entries`. Hosts that need CDC continue to read `entries`
+ * outbox events; the index is not part of the user-visible contract.
+ */
+declare class SourceRefIndexRepository 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).
+     */
+    upsert(entityId: string, sourceHash: string, sourceRef: string, tx: SQLiteAdapter): Promise<void>;
+    /**
+     * 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.
+     */
+    softDeleteByEntityAndSourceRef(entityId: string, sourceRef: string, tx: SQLiteAdapter): Promise<number>;
+    /**
+     * 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).
+     */
+    findActiveByEntityAndHash(entityId: string, sourceHash: string, tx?: SQLiteAdapter): Promise<string | null>;
+}
+
 declare class MetadataRepository extends BaseRepository {
     getCheckpoint(entityId: string, tx: SQLiteAdapter): Promise<{
         memory?: number;
@@ -1065,8 +1108,46 @@ declare class JobManager {
     private prefix;
     private activeMaintenanceJobs;
     private activeIngestJobs;
+    /**
+     * 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).
+     */
+    private hashLocks;
     private statusSubscribers;
     constructor(prefix: string);
+    private _hashLockKey;
+    /**
+     * 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: string, sourceHash: string): Promise<() => void>;
     private _pruneKey;
     private _reembedKey;
     private _globalReembedKey;
@@ -1103,6 +1184,21 @@ declare class JobManager {
      * for write() auto-trigger paths while preserving stricter checks in acquireLock().
      */
     tryAcquireAutoHealLock(entityId: string): boolean;
+    /**
+     * 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.
+     */
+    acquireIngestLocks(entityId: string, sourceRef: string, sourceHash: string): Promise<() => void>;
     /**
      * Validates then acquires global + per-entity import locks atomically.
      * Validates all entities before acquiring any lock (same as current importDump semantics).
@@ -1224,12 +1320,13 @@ declare class IngestionService {
     private prefix;
     private options;
     private entryRepo;
+    private sourceRefIndexRepo;
     private searchService;
     private jobManager;
     private embeddingService;
     private ontologyService?;
     private promptService;
-    constructor(db: SQLiteAdapter, prefix: string, options: WikiOptions, entryRepo: EntryRepository, searchService: SearchService, jobManager: JobManager, embeddingService: EmbeddingService, promptService?: PromptService, ontologyService?: OntologyService | undefined);
+    constructor(db: SQLiteAdapter, prefix: string, options: WikiOptions, entryRepo: EntryRepository, sourceRefIndexRepo: SourceRefIndexRepository, searchService: SearchService, jobManager: JobManager, embeddingService: EmbeddingService, promptService?: PromptService, ontologyService?: OntologyService | undefined);
     ingestDocument(entityId: string, params: {
         sourceRef: string;
         sourceHash: string;
@@ -1361,6 +1458,7 @@ declare class MaintenanceService {
     private prefix;
     private options;
     private entryRepo;
+    private sourceRefIndexRepo;
     private taskRepo;
     private eventRepo;
     private metadataRepo;
@@ -1369,7 +1467,7 @@ declare class MaintenanceService {
     private embeddingService;
     private ontologyService?;
     private promptService;
-    constructor(db: SQLiteAdapter, prefix: string, options: WikiOptions, entryRepo: EntryRepository, taskRepo: TaskRepository, eventRepo: EventRepository, metadataRepo: MetadataRepository, searchService: SearchService, jobManager: JobManager, embeddingService: EmbeddingService, promptService?: PromptService, ontologyService?: OntologyService | undefined);
+    constructor(db: SQLiteAdapter, prefix: string, options: WikiOptions, entryRepo: EntryRepository, sourceRefIndexRepo: SourceRefIndexRepository, taskRepo: TaskRepository, eventRepo: EventRepository, metadataRepo: MetadataRepository, searchService: SearchService, jobManager: JobManager, embeddingService: EmbeddingService, promptService?: PromptService, ontologyService?: OntologyService | undefined);
     runPrune(entityId: string, options?: {
         retainSoftDeletedFor?: number | null;
         retainEventsFor?: number | null;
@@ -1582,6 +1680,7 @@ interface WikiMemoryTestAccess {
     promptService: PromptService;
     graphTraversalService: GraphTraversalService;
     entryRepo: EntryRepository;
+    sourceRefIndexRepo: SourceRefIndexRepository;
     metadataRepo: MetadataRepository;
     jobManager: JobManager;
 }
@@ -1592,6 +1691,7 @@ declare class WikiMemory {
     private options;
     private entryRepo;
     private outboxRepo;
+    private sourceRefIndexRepo;
     private taskRepo;
     private eventRepo;
     private edgeRepo;
@@ -1647,10 +1747,13 @@ declare class WikiMemory {
         lastIngestedAt: number;
     }>>;
     /**
-     * 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.
      */
     findSourceRefsByHash(entityId: string, sourceHash: string): Promise<string[]>;
     runPrune(entityId: string, options?: {

package/dist/testing.d.mts

@@ -1,2 +1,2 @@
-export { Y as EmbeddingService, Z as ImportExportService, _ as IngestionService, $ as JobManager, $ as JobManagerType, a0 as MaintenanceService, a1 as RetrievalService, a2 as SearchService, a2 as SearchServiceType, Q as WikiMemoryTestAccess, a3 as WriteService } from './testing-DyXISRwS.mjs';
+export { Y as EmbeddingService, Z as ImportExportService, _ as IngestionService, $ as JobManager, $ as JobManagerType, a0 as MaintenanceService, a1 as RetrievalService, a2 as SearchService, a2 as SearchServiceType, Q as WikiMemoryTestAccess, a3 as WriteService } from './testing-CAk9oFvw.mjs';
 import 'minisearch';

package/dist/testing.d.ts

@@ -1,2 +1,2 @@
-export { Y as EmbeddingService, Z as ImportExportService, _ as IngestionService, $ as JobManager, $ as JobManagerType, a0 as MaintenanceService, a1 as RetrievalService, a2 as SearchService, a2 as SearchServiceType, Q as WikiMemoryTestAccess, a3 as WriteService } from './testing-DyXISRwS.js';
+export { Y as EmbeddingService, Z as ImportExportService, _ as IngestionService, $ as JobManager, $ as JobManagerType, a0 as MaintenanceService, a1 as RetrievalService, a2 as SearchService, a2 as SearchServiceType, Q as WikiMemoryTestAccess, a3 as WriteService } from './testing-CAk9oFvw.js';
 import 'minisearch';