@equationalapplications/core-llm-wiki 5.1.1 → 5.2.1

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

@@ -544,6 +544,22 @@ declare class WikiBusyError extends Error {
     readonly entityId: string;
     constructor(operation: WikiBusyOperation, entityId: string);
 }
+/**
+ * Thrown by `ingestDocument({ onDuplicateHash: 'throw' })` when a different
+ * source_ref in the same entity already holds the supplied source_hash against
+ * a live row. Mirrors {@link WikiBusyError}'s anchoring of canonical metadata
+ * on the error instance for stable observability.
+ */
+declare class WikiDuplicateHashError extends Error {
+    readonly canonical: string;
+    readonly sourceHash: string;
+    readonly entityId: string;
+    constructor(params: {
+        canonical: string;
+        sourceHash: string;
+        entityId: string;
+    });
+}
 /**
  * Thrown by the serialized transaction wrapper when a SQLite driver error
  * escapes a transaction callback (nested BEGIN, SQLITE_BUSY, constraint
@@ -796,6 +812,59 @@ declare class EntryRepository extends BaseRepository {
     }>>;
     updateSourceRefByRowid(rowid: number, sourceRef: string | null, tx: SQLiteAdapter): Promise<void>;
     findLatestSourceHash(entityId: string, sourceRef: string, tx?: SQLiteAdapter): Promise<string | null>;
+    /**
+     * Batch version of {@link findLatestSourceHash}. Returns a Map covering every
+     * requested ref, where the value is the source_hash from the row with the
+     * most-recently-updated live fact for that ref, or null when no live row exists.
+     *
+     * The SQL uses ROW_NUMBER() OVER (PARTITION BY source_ref ORDER BY updated_at
+     * DESC, id ASC) — NOT MAX(source_hash). Aggregation with MAX(source_hash) is
+     * wrong because MAX computes independently across grouped rows; the hash must
+     * come from the exact row that wins MAX(updated_at). The `id ASC` tie-break
+     * keeps selection deterministic when two live rows share `updated_at`.
+     *
+     * Source refs are de-duplicated and processed in chunks so the per-query bind
+     * parameter count stays under SQLite's `SQLITE_MAX_VARIABLE_NUMBER` (default
+     * 999, leaving one slot for `entity_id`).
+     *
+     * Empty input is a synchronous early return with zero SQL calls.
+     */
+    findLatestSourceHashes(entityId: string, sourceRefs: readonly string[], tx?: SQLiteAdapter): Promise<Map<string, string | null>>;
+    /**
+     * Return the live source_refs for an entity that hold the given source_hash.
+     * Used by the ingestDocument duplicate-hash guard and by hosts auditing
+     * duplicate-content collisions. Sorted `COLLATE BINARY` so the canonical
+     * ref (the code-unit-minimum of the set) is stable across deploys.
+     */
+    findSourceRefsByHash(entityId: string, sourceHash: string, tx?: SQLiteAdapter): Promise<string[]>;
+    /**
+     * Per-sourceRef rollup for an entity: one row per live source_ref, with the
+     * most-recently-updated live hash (NOT the lexically-max hash) and a live
+     * fact count.
+     *
+     * The hash comes from the same row that wins ROW_NUMBER() over updated_at
+     * DESC, so a ref with multiple live hashes (e.g. from import) reports the
+     * latest one — matching single-doc `findLatestSourceHash` semantics.
+     *
+     * Sort is COLLATE BINARY: locale-dependent ordering re-mints identity on
+     * every deploy, which is the bug this whole section exists to prevent.
+     */
+    listSourceRefs(entityId: string, tx?: SQLiteAdapter): Promise<Array<{
+        sourceRef: string;
+        sourceHash: string | null;
+        factCount: number;
+        lastIngestedAt: number;
+    }>>;
+    /**
+     * Count live entries for an entity across all source_refs/source_hashes.
+     * Used by forget({ dryRun, clearAll: true }).
+     */
+    countLiveByEntityId(entityId: string, tx?: SQLiteAdapter): Promise<number>;
+    /**
+     * Count live entries matching a source filter (either or both may be null).
+     * Used by forget({ dryRun: true }) with sourceRef/sourceHash.
+     */
+    countLiveBySource(entityId: string, sourceRef: string | null, sourceHash: string | null, tx?: SQLiteAdapter): Promise<number>;
     findMetadataByIds(ids: readonly string[], tx?: SQLiteAdapter): Promise<EntryRowMetadata[]>;
     findWithEmbeddingsByIds(ids: readonly string[], tx?: SQLiteAdapter): Promise<EntryRowWithEmbeddings[]>;
     findMetadataByEntityIds(entityIds: readonly string[], tx?: SQLiteAdapter): Promise<EntryRowMetadata[]>;
@@ -874,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;
@@ -996,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;
@@ -1034,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).
@@ -1155,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;
@@ -1169,9 +1335,12 @@ declare class IngestionService {
         chunkOverlap?: number;
         chunkConcurrency?: number;
         promptOverride?: string;
+    }, opts?: {
+        onDuplicateHash?: 'ingest' | 'skip' | 'throw';
     }): Promise<{
         truncated: boolean;
         chunks: number;
+        duplicateOf?: string;
     }>;
 }
 
@@ -1230,6 +1399,10 @@ declare class TaskRepository extends BaseRepository {
      * `tx` is REQUIRED.
      */
     bulkSoftDeleteByEntityId(entityId: string, tx: SQLiteAdapter): Promise<number>;
+    /**
+     * Count live tasks for an entity. Used by forget({ dryRun, clearAll: true }).
+     */
+    countLiveByEntityId(entityId: string, tx?: SQLiteAdapter): Promise<number>;
 }
 
 declare class EventRepository extends BaseRepository {
@@ -1285,6 +1458,7 @@ declare class MaintenanceService {
     private prefix;
     private options;
     private entryRepo;
+    private sourceRefIndexRepo;
     private taskRepo;
     private eventRepo;
     private metadataRepo;
@@ -1293,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;
@@ -1328,12 +1502,28 @@ declare class MaintenanceService {
         sourceRef?: string;
         sourceHash?: string;
         clearAll?: boolean;
+    }, opts?: {
+        dryRun?: boolean;
     }): Promise<{
         deleted: {
             entries: number;
             tasks: number;
         };
+        metadataReset?: boolean;
     }>;
+    /**
+     * Read-only dry-run preview of {@link forget}. Returns the same shape as a
+     * real call would, without acquiring the lock, opening a transaction, staging
+     * outbox events, or firing embedding hooks. Counts may be off-by-N during a
+     * concurrent real forget — this is accepted, not considered a bug.
+     *
+     * `metadataReset` mirrors the real call: only `clearAll: true` returns true,
+     * because only `clearAll` actually resets the metadata checkpoint.
+     * `standard` (sourceRef/sourceHash) returns no metadataReset field, just like
+     * the real call. `entryId`/`taskId` selectors are rejected with a clear error
+     * (the spec keeps dry-run narrow).
+     */
+    private forgetDryRun;
     /** Core librarian pass (locks handled by {@link runLibrarian}). Package-internal orchestration hook. */
     doRunLibrarian(entityId: string, promptOverride?: string): Promise<void>;
     /**
@@ -1490,6 +1680,7 @@ interface WikiMemoryTestAccess {
     promptService: PromptService;
     graphTraversalService: GraphTraversalService;
     entryRepo: EntryRepository;
+    sourceRefIndexRepo: SourceRefIndexRepository;
     metadataRepo: MetadataRepository;
     jobManager: JobManager;
 }
@@ -1500,6 +1691,7 @@ declare class WikiMemory {
     private options;
     private entryRepo;
     private outboxRepo;
+    private sourceRefIndexRepo;
     private taskRepo;
     private eventRepo;
     private edgeRepo;
@@ -1523,6 +1715,47 @@ declare class WikiMemory {
     get __testAccess(): WikiMemoryTestAccess;
     setup(): Promise<void>;
     hasChanged(entityId: string, sourceRef: string, sourceHash: string): Promise<boolean>;
+    /**
+     * Batched overload.
+     *
+     * `duplicateOf`, when present, is the canonical stored DIFFERENT `source_ref`
+     * holding the same hash — never the incoming ref itself (the incoming ref is
+     * excluded from the canonical-sort set so a self-reference is impossible).
+     * `duplicateOf` reflects the *DB-side* normalized spelling; `sourceRef` in
+     * each result echoes the raw caller value. Hosts should not compare these
+     * two fields directly to infer canonical status.
+     */
+    hasChanged(entityId: string, entries: Array<{
+        sourceRef: string;
+        sourceHash: string;
+    }>): Promise<Array<{
+        sourceRef: string;
+        changed: boolean;
+        duplicateOf?: string;
+    }>>;
+    /**
+     * Returns the live source_refs for an entity, one row per ref, with the most
+     * recently-updated live `source_hash` and a live fact count. Refs are sorted
+     * `COLLATE BINARY` (no locale dependency). Used by hosts to reconcile stored
+     * state against a live source, or audit duplicate-hash collisions via
+     * `findSourceRefsByHash`.
+     */
+    listSourceRefs(entityId: string): Promise<Array<{
+        sourceRef: string;
+        sourceHash: string | null;
+        factCount: number;
+        lastIngestedAt: number;
+    }>>;
+    /**
+     * 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?: {
         retainSoftDeletedFor?: number | null;
         retainEventsFor?: number | null;
@@ -1609,11 +1842,14 @@ declare class WikiMemory {
         sourceRef?: string;
         sourceHash?: string;
         clearAll?: boolean;
+    }, opts?: {
+        dryRun?: boolean;
     }): Promise<{
         deleted: {
             entries: number;
             tasks: number;
         };
+        metadataReset?: boolean;
     }>;
     /**
      * @param params.promptOverride - Overrides the system prompt for this ingest call only.
@@ -1628,9 +1864,12 @@ declare class WikiMemory {
         chunkOverlap?: number;
         chunkConcurrency?: number;
         promptOverride?: string;
+    }, opts?: {
+        onDuplicateHash?: 'ingest' | 'skip' | 'throw';
     }): Promise<{
         truncated: boolean;
         chunks: number;
+        duplicateOf?: string;
     }>;
     /**
      * Returns up to `limit` unprocessed outbox events, oldest first.
@@ -1660,4 +1899,4 @@ declare class WikiMemory {
     }): Promise<void>;
 }
 
-export { MaintenanceService as $, WikiBusyError as A, type WikiBusyOperation as B, type WikiCheckpoint as C, type WikiConfig as D, type EntityStatus as E, type FormatContextOptions as F, type GraphNeighborhood as G, HEAL_BATCH_SIZE as H, type WikiEdge as I, type WikiEvent as J, type WikiFact as K, type LLMProvider as L, type MemoryBundle as M, type WikiMemoryTestAccess as N, type OntologyManifest as O, type PromptOverrides as P, type WikiOutboxEvent as Q, type ReadOptions as R, type SQLiteAdapter as S, type WikiTask as T, WikiTransactionError as U, type VectorRanker as V, type WikiOptions as W, EmbeddingService as X, ImportExportService as Y, IngestionService as Z, JobManager as _, type MemoryDump as a, RetrievalService as a0, SearchService as a1, WriteService as a2, type FormattedMemoryDump as b, WikiMemory as c, type ExtractedFact as d, type ExtractedFactEdge as e, type ExtractedFactWithOntology as f, type ExtractedTask as g, type GraphTraversalOptions as h, HEAL_RECHECK_MS as i, HOOK_TIMEOUT_MARKER as j, type HealResult as k, ONTOLOGY_BACKFILL_BATCH_SIZE as l, ONTOLOGY_BACKFILL_MAX_PROMPT_CHARS as m, ONTOLOGY_BACKFILL_RECHECK_MS as n, type OntologyBackfillResult as o, type OntologyConfig as p, type OntologyEdgeType as q, type OntologyMode as r, type OntologyNodeType as s, type OntologyPromptContext as t, type OntologyUpdates as u, PromptService as v, PrunePartialFailureError as w, type VectorRankerFallback as x, type VectorRankerRankArgs as y, type VectorRankerSemanticResult as z };
+export { JobManager as $, WikiBusyError as A, type WikiBusyOperation as B, type WikiCheckpoint as C, type WikiConfig as D, type EntityStatus as E, type FormatContextOptions as F, type GraphNeighborhood as G, HEAL_BATCH_SIZE as H, WikiDuplicateHashError as I, type WikiEdge as J, type WikiEvent as K, type LLMProvider as L, type MemoryBundle as M, type WikiFact as N, type OntologyManifest as O, type PromptOverrides as P, type WikiMemoryTestAccess as Q, type ReadOptions as R, type SQLiteAdapter as S, type WikiOutboxEvent as T, type WikiTask as U, type VectorRanker as V, type WikiOptions as W, WikiTransactionError as X, EmbeddingService as Y, ImportExportService as Z, IngestionService as _, type MemoryDump as a, MaintenanceService as a0, RetrievalService as a1, SearchService as a2, WriteService as a3, type FormattedMemoryDump as b, WikiMemory as c, type ExtractedFact as d, type ExtractedFactEdge as e, type ExtractedFactWithOntology as f, type ExtractedTask as g, type GraphTraversalOptions as h, HEAL_RECHECK_MS as i, HOOK_TIMEOUT_MARKER as j, type HealResult as k, ONTOLOGY_BACKFILL_BATCH_SIZE as l, ONTOLOGY_BACKFILL_MAX_PROMPT_CHARS as m, ONTOLOGY_BACKFILL_RECHECK_MS as n, type OntologyBackfillResult as o, type OntologyConfig as p, type OntologyEdgeType as q, type OntologyMode as r, type OntologyNodeType as s, type OntologyPromptContext as t, type OntologyUpdates as u, PromptService as v, PrunePartialFailureError as w, type VectorRankerFallback as x, type VectorRankerRankArgs as y, type VectorRankerSemanticResult as z };