@equationalapplications/core-llm-wiki 5.1.0 → 5.2.0

package/dist/{testing-DCRNie7k.d.mts → testing-DyXISRwS.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[]>;
@@ -1169,9 +1238,12 @@ declare class IngestionService {
         chunkOverlap?: number;
         chunkConcurrency?: number;
         promptOverride?: string;
+    }, opts?: {
+        onDuplicateHash?: 'ingest' | 'skip' | 'throw';
     }): Promise<{
         truncated: boolean;
         chunks: number;
+        duplicateOf?: string;
     }>;
 }
 
@@ -1230,6 +1302,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 {
@@ -1328,12 +1404,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>;
     /**
@@ -1523,6 +1615,44 @@ 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,
+     * 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.
+     */
+    findSourceRefsByHash(entityId: string, sourceHash: string): Promise<string[]>;
     runPrune(entityId: string, options?: {
         retainSoftDeletedFor?: number | null;
         retainEventsFor?: number | null;
@@ -1609,11 +1739,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 +1761,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 +1796,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 };

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

@@ -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[]>;
@@ -1169,9 +1238,12 @@ declare class IngestionService {
         chunkOverlap?: number;
         chunkConcurrency?: number;
         promptOverride?: string;
+    }, opts?: {
+        onDuplicateHash?: 'ingest' | 'skip' | 'throw';
     }): Promise<{
         truncated: boolean;
         chunks: number;
+        duplicateOf?: string;
     }>;
 }
 
@@ -1230,6 +1302,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 {
@@ -1328,12 +1404,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>;
     /**
@@ -1523,6 +1615,44 @@ 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,
+     * 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.
+     */
+    findSourceRefsByHash(entityId: string, sourceHash: string): Promise<string[]>;
     runPrune(entityId: string, options?: {
         retainSoftDeletedFor?: number | null;
         retainEventsFor?: number | null;
@@ -1609,11 +1739,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 +1761,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 +1796,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 };

package/dist/testing.d.mts

@@ -1,2 +1,2 @@
-export { X as EmbeddingService, Y as ImportExportService, Z as IngestionService, _ as JobManager, _ as JobManagerType, $ as MaintenanceService, a0 as RetrievalService, a1 as SearchService, a1 as SearchServiceType, N as WikiMemoryTestAccess, a2 as WriteService } from './testing-DCRNie7k.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-DyXISRwS.mjs';
 import 'minisearch';

package/dist/testing.d.ts

@@ -1,2 +1,2 @@
-export { X as EmbeddingService, Y as ImportExportService, Z as IngestionService, _ as JobManager, _ as JobManagerType, $ as MaintenanceService, a0 as RetrievalService, a1 as SearchService, a1 as SearchServiceType, N as WikiMemoryTestAccess, a2 as WriteService } from './testing-DCRNie7k.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-DyXISRwS.js';
 import 'minisearch';

package/dist/testing.js

@@ -15,6 +15,15 @@ var WikiBusyError = class extends Error {
     this.entityId = entityId;
   }
 };
+var WikiDuplicateHashError = class extends Error {
+  constructor(params) {
+    super(`Duplicate source hash for entity ${params.entityId}; another ref already holds this content`);
+    this.name = "WikiDuplicateHashError";
+    this.canonical = params.canonical;
+    this.sourceHash = params.sourceHash;
+    this.entityId = params.entityId;
+  }
+};
 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`);
@@ -574,6 +583,15 @@ var ImportExportService = class {
         const safeTitle = clip(String(fact.title ?? ""), IMPORT_TITLE_MAX);
         const safeBody = clip(String(fact.body ?? ""), IMPORT_BODY_MAX);
         clippedTextByFactId.set(fact.id, { title: safeTitle, body: safeBody });
+        let normalizedSourceRef = null;
+        if (fact.source_ref !== null && fact.source_ref !== void 0) {
+          normalizedSourceRef = normalizeSourceRef(fact.source_ref);
+          if (normalizedSourceRef === null) {
+            throw new Error(
+              `importDump: invalid source_ref ${JSON.stringify(fact.source_ref)} for entity "${entityId}" fact "${fact.id}" (must normalize to a non-empty string; see ingestDocument's sourceRef validation)`
+            );
+          }
+        }
         const factObj = {
           id: fact.id,
           entity_id: entityId,
@@ -583,7 +601,7 @@ var ImportExportService = class {
           confidence: fact.confidence,
           source_type: sourceType,
           source_hash: fact.source_hash,
-          source_ref: fact.source_ref,
+          source_ref: normalizedSourceRef,
           created_at: fact.created_at,
           updated_at: safeUpdatedAt,
           last_accessed_at: fact.last_accessed_at,
@@ -986,11 +1004,23 @@ var IngestionService = class {
     this.ontologyService = ontologyService;
     this.promptService = promptService ?? new PromptService(this.options.config?.prompts);
   }
-  async ingestDocument(entityId, params) {
+  async ingestDocument(entityId, params, opts) {
     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 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(
@@ -1431,10 +1461,13 @@ var MaintenanceService = class {
       this.jobManager.releaseLock(op, entityId ?? "*");
     }
   }
-  async forget(entityId, params) {
+  async forget(entityId, params, opts) {
     if (params.clearAll && (params.entryId !== void 0 || params.taskId !== void 0 || params.sourceRef !== void 0 || params.sourceHash !== void 0)) {
       throw new Error("forget() clearAll is mutually exclusive with entryId, taskId, sourceRef, and sourceHash");
     }
+    if (opts?.dryRun === true) {
+      return this.forgetDryRun(entityId, params);
+    }
     this.jobManager.acquireLock("forget", entityId);
     try {
       const now = Date.now();
@@ -1495,11 +1528,42 @@ var MaintenanceService = class {
           throw new Error(`forget(${entityId}/${factId}) failed: ANN cleanup hook rejected`, { cause: this._sanitizeRankerError(hookErr) });
         }
       }
-      return { deleted: { entries: deletedEntries, tasks: deletedTasks } };
+      return params.clearAll ? { deleted: { entries: deletedEntries, tasks: deletedTasks }, metadataReset: true } : { deleted: { entries: deletedEntries, tasks: deletedTasks } };
     } finally {
       this.jobManager.releaseLock("forget", entityId);
     }
   }
+  /**
+   * 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).
+   */
+  async forgetDryRun(entityId, params) {
+    if (params.entryId !== void 0 || params.taskId !== void 0) {
+      throw new Error("forget({ dryRun: true }) does not support entryId/taskId selectors; use sourceRef/sourceHash or clearAll");
+    }
+    if (params.clearAll) {
+      const entries2 = await this.entryRepo.countLiveByEntityId(entityId);
+      const tasks = await this.taskRepo.countLiveByEntityId(entityId);
+      return { deleted: { entries: entries2, tasks }, metadataReset: true };
+    }
+    const sourceRef = params.sourceRef !== void 0 ? normalizeSourceRef(params.sourceRef) : null;
+    if (params.sourceRef !== void 0 && !sourceRef) throw new Error("Invalid sourceRef");
+    const sourceHash = params.sourceHash !== void 0 ? normalizeSourceHash(params.sourceHash) : null;
+    if (params.sourceHash !== void 0 && !sourceHash) throw new Error("Invalid sourceHash (must be 64-char hex string)");
+    if (sourceRef === null && sourceHash === null) {
+      return { deleted: { entries: 0, tasks: 0 } };
+    }
+    const entries = await this.entryRepo.countLiveBySource(entityId, sourceRef, sourceHash);
+    return { deleted: { entries, tasks: 0 } };
+  }
   /** Core librarian pass (locks handled by {@link runLibrarian}). Package-internal orchestration hook. */
   async doRunLibrarian(entityId, promptOverride) {
     const events = await this.eventRepo.getRecent(entityId, 50);
@@ -1729,10 +1793,10 @@ var MaintenanceService = class {
     const validNewFacts = newFacts.map(validateFact).filter((f) => f !== null);
     const insertedFacts = [];
     const uniqueDeletedFactIds = Array.from(new Set(safeDeleted));
-    const healFactsForDedupe = (await this.entryRepo.findInferredTitlesByEntityId(entityId)).filter((f) => !safeDeletedSet.has(f.id));
     await this.db.withTransactionAsync(async (tx) => {
       await this.entryRepo.downgradeByIds(safeDowngraded, entityId, tx);
       await this.entryRepo.softDeleteByIds(safeDeleted, entityId, tx);
+      const healFactsForDedupe = await this.entryRepo.findInferredTitlesByEntityId(entityId, tx);
       for (const fact of validNewFacts) {
         const newTokens = titleTokens(fact.title);
         let skip = false;
@@ -3018,6 +3082,19 @@ var JobManager = class {
         return this.activeMaintenanceJobs.has(this.lockKeyFns[operation](entityId)) || this.activeMaintenanceJobs.has(this._pruneKey(entityId)) || this._isReembedActive(entityId) || this._isImportActiveFor(entityId) || this._isForgetActiveFor(entityId);
       case "prune":
         return this.activeMaintenanceJobs.has(this._pruneKey(entityId)) || this.activeMaintenanceJobs.has(this._librarianKey(entityId)) || this.activeMaintenanceJobs.has(this._healKey(entityId)) || this.activeMaintenanceJobs.has(this._ontologyBackfillKey(entityId)) || this._isReembedActive(entityId) || this._isIngestActiveFor(entityId) || this._isImportActiveFor(entityId) || this._isForgetActiveFor(entityId);
+      case "reembed":
+        return this.activeMaintenanceJobs.has(this._reembedKey(entityId)) || this.activeMaintenanceJobs.has(this._globalReembedKey()) || this.activeMaintenanceJobs.has(this._pruneKey(entityId)) || this.activeMaintenanceJobs.has(this._librarianKey(entityId)) || this.activeMaintenanceJobs.has(this._healKey(entityId)) || this.activeMaintenanceJobs.has(this._ontologyBackfillKey(entityId)) || this._isIngestActiveFor(entityId) || this._isImportActiveFor(entityId) || this._isForgetActiveFor(entityId);
+      case "global_reembed":
+        return this.activeMaintenanceJobs.has(this._globalReembedKey()) || this._isAnyMaintenanceActiveWithSuffix(":reembed") || this._isAnyMaintenanceActiveWithSuffix(":prune") || this._isAnyMaintenanceActiveWithSuffix(":librarian") || this._isAnyMaintenanceActiveWithSuffix(":heal") || this._isAnyMaintenanceActiveWithSuffix(":ontologyBackfill") || this.activeIngestJobs.size > 0 || this._isAnyMaintenanceActiveWithSuffix(":import") || this._isAnyMaintenanceActiveWithSuffix(":forget");
+      case "import":
+      case "forget": {
+        const selfKey = operation === "import" ? this._importKey(entityId) : this._forgetKey(entityId);
+        return this.activeMaintenanceJobs.has(selfKey) || this.activeMaintenanceJobs.has(this._librarianKey(entityId)) || this.activeMaintenanceJobs.has(this._healKey(entityId)) || this.activeMaintenanceJobs.has(this._ontologyBackfillKey(entityId)) || this.activeMaintenanceJobs.has(this._pruneKey(entityId)) || this._isReembedActive(entityId) || this._isIngestActiveFor(entityId) || this._isImportActiveFor(entityId) || this._isForgetActiveFor(entityId);
+      }
+      case "global_import":
+        return this.activeMaintenanceJobs.has(this._globalImportKey());
+      case "ingest":
+        return this._hasIngestJob(entityId) || this.activeMaintenanceJobs.has(this._pruneKey(entityId)) || this._isReembedActive(entityId) || this._isImportActiveFor(entityId) || this._isForgetActiveFor(entityId);
       default:
         return false;
     }