@equationalapplications/core-llm-wiki 5.1.1 → 5.2.0

package/dist/index.d.mts

@@ -1,5 +1,5 @@
-import { M as MemoryBundle, F as FormatContextOptions, G as GraphNeighborhood, a as MemoryDump, b as FormattedMemoryDump, O as OntologyManifest, R as ReadOptions, S as SQLiteAdapter, W as WikiOptions, c as WikiMemory } from './testing-DCRNie7k.mjs';
-export { E as EntityStatus, d as ExtractedFact, e as ExtractedFactEdge, f as ExtractedFactWithOntology, g as ExtractedTask, h as GraphTraversalOptions, H as HEAL_BATCH_SIZE, i as HEAL_RECHECK_MS, j as HOOK_TIMEOUT_MARKER, k as HealResult, L as LLMProvider, l as ONTOLOGY_BACKFILL_BATCH_SIZE, m as ONTOLOGY_BACKFILL_MAX_PROMPT_CHARS, n as ONTOLOGY_BACKFILL_RECHECK_MS, o as OntologyBackfillResult, p as OntologyConfig, q as OntologyEdgeType, r as OntologyMode, s as OntologyNodeType, t as OntologyPromptContext, u as OntologyUpdates, P as PromptOverrides, v as PromptService, w as PrunePartialFailureError, V as VectorRanker, x as VectorRankerFallback, y as VectorRankerRankArgs, z as VectorRankerSemanticResult, A as WikiBusyError, B as WikiBusyOperation, C as WikiCheckpoint, D as WikiConfig, I as WikiEdge, J as WikiEvent, K as WikiFact, N as WikiMemoryTestAccess, Q as WikiOutboxEvent, T as WikiTask, U as WikiTransactionError } from './testing-DCRNie7k.mjs';
+import { M as MemoryBundle, F as FormatContextOptions, G as GraphNeighborhood, a as MemoryDump, b as FormattedMemoryDump, O as OntologyManifest, R as ReadOptions, S as SQLiteAdapter, W as WikiOptions, c as WikiMemory } from './testing-DyXISRwS.mjs';
+export { E as EntityStatus, d as ExtractedFact, e as ExtractedFactEdge, f as ExtractedFactWithOntology, g as ExtractedTask, h as GraphTraversalOptions, H as HEAL_BATCH_SIZE, i as HEAL_RECHECK_MS, j as HOOK_TIMEOUT_MARKER, k as HealResult, L as LLMProvider, l as ONTOLOGY_BACKFILL_BATCH_SIZE, m as ONTOLOGY_BACKFILL_MAX_PROMPT_CHARS, n as ONTOLOGY_BACKFILL_RECHECK_MS, o as OntologyBackfillResult, p as OntologyConfig, q as OntologyEdgeType, r as OntologyMode, s as OntologyNodeType, t as OntologyPromptContext, u as OntologyUpdates, P as PromptOverrides, v as PromptService, w as PrunePartialFailureError, V as VectorRanker, x as VectorRankerFallback, y as VectorRankerRankArgs, z as VectorRankerSemanticResult, A as WikiBusyError, B as WikiBusyOperation, C as WikiCheckpoint, D as WikiConfig, I as WikiDuplicateHashError, J as WikiEdge, K as WikiEvent, N as WikiFact, Q as WikiMemoryTestAccess, T as WikiOutboxEvent, U as WikiTask, X as WikiTransactionError } from './testing-DyXISRwS.mjs';
 import { OkfFile } from '@equationalapplications/core-okf';
 import 'minisearch';
 

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { M as MemoryBundle, F as FormatContextOptions, G as GraphNeighborhood, a as MemoryDump, b as FormattedMemoryDump, O as OntologyManifest, R as ReadOptions, S as SQLiteAdapter, W as WikiOptions, c as WikiMemory } from './testing-DCRNie7k.js';
-export { E as EntityStatus, d as ExtractedFact, e as ExtractedFactEdge, f as ExtractedFactWithOntology, g as ExtractedTask, h as GraphTraversalOptions, H as HEAL_BATCH_SIZE, i as HEAL_RECHECK_MS, j as HOOK_TIMEOUT_MARKER, k as HealResult, L as LLMProvider, l as ONTOLOGY_BACKFILL_BATCH_SIZE, m as ONTOLOGY_BACKFILL_MAX_PROMPT_CHARS, n as ONTOLOGY_BACKFILL_RECHECK_MS, o as OntologyBackfillResult, p as OntologyConfig, q as OntologyEdgeType, r as OntologyMode, s as OntologyNodeType, t as OntologyPromptContext, u as OntologyUpdates, P as PromptOverrides, v as PromptService, w as PrunePartialFailureError, V as VectorRanker, x as VectorRankerFallback, y as VectorRankerRankArgs, z as VectorRankerSemanticResult, A as WikiBusyError, B as WikiBusyOperation, C as WikiCheckpoint, D as WikiConfig, I as WikiEdge, J as WikiEvent, K as WikiFact, N as WikiMemoryTestAccess, Q as WikiOutboxEvent, T as WikiTask, U as WikiTransactionError } from './testing-DCRNie7k.js';
+import { M as MemoryBundle, F as FormatContextOptions, G as GraphNeighborhood, a as MemoryDump, b as FormattedMemoryDump, O as OntologyManifest, R as ReadOptions, S as SQLiteAdapter, W as WikiOptions, c as WikiMemory } from './testing-DyXISRwS.js';
+export { E as EntityStatus, d as ExtractedFact, e as ExtractedFactEdge, f as ExtractedFactWithOntology, g as ExtractedTask, h as GraphTraversalOptions, H as HEAL_BATCH_SIZE, i as HEAL_RECHECK_MS, j as HOOK_TIMEOUT_MARKER, k as HealResult, L as LLMProvider, l as ONTOLOGY_BACKFILL_BATCH_SIZE, m as ONTOLOGY_BACKFILL_MAX_PROMPT_CHARS, n as ONTOLOGY_BACKFILL_RECHECK_MS, o as OntologyBackfillResult, p as OntologyConfig, q as OntologyEdgeType, r as OntologyMode, s as OntologyNodeType, t as OntologyPromptContext, u as OntologyUpdates, P as PromptOverrides, v as PromptService, w as PrunePartialFailureError, V as VectorRanker, x as VectorRankerFallback, y as VectorRankerRankArgs, z as VectorRankerSemanticResult, A as WikiBusyError, B as WikiBusyOperation, C as WikiCheckpoint, D as WikiConfig, I as WikiDuplicateHashError, J as WikiEdge, K as WikiEvent, N as WikiFact, Q as WikiMemoryTestAccess, T as WikiOutboxEvent, U as WikiTask, X as WikiTransactionError } from './testing-DyXISRwS.js';
 import { OkfFile } from '@equationalapplications/core-okf';
 import 'minisearch';
 

package/dist/index.js

@@ -175,6 +175,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 WikiTransactionError = class extends Error {
   constructor(message, options) {
     super(message, options);
@@ -1080,12 +1089,154 @@ var EntryRepository = class extends BaseRepository {
     const row = await executor.getFirstAsync(
       `SELECT source_hash FROM ${this.prefix}entries
        WHERE entity_id = ? AND source_ref = ? AND deleted_at IS NULL
-       ORDER BY updated_at DESC
+       ORDER BY updated_at DESC, id ASC
        LIMIT 1`,
       [entityId, sourceRef]
     );
     return row?.source_hash ?? 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.
+   */
+  async findLatestSourceHashes(entityId, sourceRefs, tx) {
+    const out = /* @__PURE__ */ new Map();
+    if (sourceRefs.length === 0) return out;
+    const dedupedRefs = Array.from(new Set(sourceRefs));
+    for (const ref of dedupedRefs) {
+      out.set(ref, null);
+    }
+    const executor = this.getExecutor(tx);
+    const chunkLimit = Math.max(1, this.chunkSize - 1);
+    for (let i = 0; i < dedupedRefs.length; i += chunkLimit) {
+      const chunk = dedupedRefs.slice(i, i + chunkLimit);
+      const placeholders = chunk.map(() => "?").join(",");
+      const rows = await executor.getAllAsync(
+        `WITH ranked AS (
+           SELECT source_ref, source_hash,
+                  ROW_NUMBER() OVER (
+                    PARTITION BY source_ref
+                    ORDER BY updated_at DESC, id ASC
+                  ) as rn
+           FROM ${this.prefix}entries
+           WHERE entity_id = ? AND source_ref IN (${placeholders}) AND deleted_at IS NULL
+         )
+         SELECT source_ref, source_hash
+         FROM ranked
+         WHERE rn = 1`,
+        [entityId, ...chunk]
+      );
+      for (const r of rows) {
+        out.set(r.source_ref, r.source_hash);
+      }
+    }
+    return out;
+  }
+  /**
+   * 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.
+   */
+  async findSourceRefsByHash(entityId, sourceHash, tx) {
+    const executor = this.getExecutor(tx);
+    const rows = await executor.getAllAsync(
+      `SELECT source_ref FROM ${this.prefix}entries
+       WHERE entity_id = ? AND source_hash = ? AND deleted_at IS NULL
+         AND source_ref IS NOT NULL
+       GROUP BY source_ref
+       ORDER BY source_ref COLLATE BINARY`,
+      [entityId, sourceHash]
+    );
+    return rows.map((r) => r.source_ref);
+  }
+  /**
+   * 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.
+   */
+  async listSourceRefs(entityId, tx) {
+    const executor = this.getExecutor(tx);
+    const rows = await executor.getAllAsync(
+      `WITH ranked AS (
+         SELECT source_ref, source_hash, updated_at,
+                ROW_NUMBER() OVER (
+                  PARTITION BY source_ref
+                  ORDER BY updated_at DESC, id ASC
+                ) AS rn,
+                COUNT(*) OVER (PARTITION BY source_ref) AS fact_count
+         FROM ${this.prefix}entries
+         WHERE entity_id = ? AND deleted_at IS NULL AND source_ref IS NOT NULL
+       )
+       SELECT source_ref,
+              source_hash       AS source_hash,
+              fact_count        AS fact_count,
+              updated_at        AS last_ingested_at
+       FROM ranked
+       WHERE rn = 1
+       ORDER BY source_ref COLLATE BINARY`,
+      [entityId]
+    );
+    return rows.map((r) => ({
+      sourceRef: r.source_ref,
+      sourceHash: r.source_hash,
+      factCount: Number(r.fact_count),
+      lastIngestedAt: Number(r.last_ingested_at)
+    }));
+  }
+  /**
+   * Count live entries for an entity across all source_refs/source_hashes.
+   * Used by forget({ dryRun, clearAll: true }).
+   */
+  async countLiveByEntityId(entityId, tx) {
+    const executor = this.getExecutor(tx);
+    const row = await executor.getFirstAsync(
+      `SELECT COUNT(*) AS cnt FROM ${this.prefix}entries
+     WHERE entity_id = ? AND deleted_at IS NULL`,
+      [entityId]
+    );
+    return row?.cnt ?? 0;
+  }
+  /**
+   * Count live entries matching a source filter (either or both may be null).
+   * Used by forget({ dryRun: true }) with sourceRef/sourceHash.
+   */
+  async countLiveBySource(entityId, sourceRef, sourceHash, tx) {
+    const executor = this.getExecutor(tx);
+    let q = `SELECT COUNT(*) AS cnt FROM ${this.prefix}entries
+           WHERE entity_id = ? AND deleted_at IS NULL`;
+    const args = [entityId];
+    if (sourceRef !== null) {
+      q += ` AND source_ref = ?`;
+      args.push(sourceRef);
+    }
+    if (sourceHash !== null) {
+      q += ` AND source_hash = ?`;
+      args.push(sourceHash);
+    }
+    const row = await executor.getFirstAsync(q, args);
+    return row?.cnt ?? 0;
+  }
   async findMetadataByIds(ids, tx) {
     if (ids.length === 0) return [];
     const executor = this.getExecutor(tx);
@@ -1637,6 +1788,18 @@ var TaskRepository = class extends BaseRepository {
     }
     return result.changes;
   }
+  /**
+   * Count live tasks for an entity. Used by forget({ dryRun, clearAll: true }).
+   */
+  async countLiveByEntityId(entityId, tx) {
+    const executor = this.getExecutor(tx);
+    const row = await executor.getFirstAsync(
+      `SELECT COUNT(*) AS cnt FROM ${this.prefix}tasks
+     WHERE entity_id = ? AND deleted_at IS NULL`,
+      [entityId]
+    );
+    return row?.cnt ?? 0;
+  }
 };
 
 // src/repositories/EventRepository.ts
@@ -2614,6 +2777,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;
     }
@@ -3080,11 +3256,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(
@@ -3497,10 +3685,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();
@@ -3561,11 +3752,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);
@@ -4289,6 +4511,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,
@@ -4298,7 +4529,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,
@@ -5616,19 +5847,69 @@ var WikiMemory = class {
     });
     await this.searchService.sync();
   }
-  async hasChanged(entityId, sourceRef, sourceHash) {
-    const normalizedRef = normalizeSourceRef(sourceRef);
-    if (!normalizedRef) {
-      throw new Error(`Invalid sourceRef: ${JSON.stringify(sourceRef)}`);
-    }
-    const normalizedHash = normalizeSourceHash(sourceHash);
-    if (!normalizedHash) {
-      throw new Error(`Invalid sourceHash: must be a 64-character hex string (normalized to lowercase)`);
-    }
-    const storedHash = await this.entryRepo.findLatestSourceHash(entityId, normalizedRef);
-    if (storedHash === null) return true;
-    const normalizedStoredHash = normalizeSourceHash(storedHash);
-    return normalizedStoredHash !== normalizedHash;
+  async hasChanged(entityId, sourceRefOrEntries, sourceHashArg) {
+    if (typeof sourceRefOrEntries === "string") {
+      const sourceRef = normalizeSourceRef(sourceRefOrEntries);
+      if (!sourceRef) {
+        throw new Error(`Invalid sourceRef: ${JSON.stringify(sourceRefOrEntries)}`);
+      }
+      const sourceHash = normalizeSourceHash(sourceHashArg);
+      if (!sourceHash) {
+        throw new Error("Invalid sourceHash: must be a 64-character hex string (normalized to lowercase)");
+      }
+      const storedHash = await this.entryRepo.findLatestSourceHash(entityId, sourceRef);
+      if (storedHash === null) return true;
+      const normalizedStoredHash = normalizeSourceHash(storedHash);
+      return normalizedStoredHash !== sourceHash;
+    }
+    const entries = sourceRefOrEntries;
+    if (entries.length === 0) return [];
+    const normalized = entries.map((e) => {
+      const r = normalizeSourceRef(e.sourceRef);
+      if (!r) throw new Error(`Invalid sourceRef: ${JSON.stringify(e.sourceRef)}`);
+      const h = normalizeSourceHash(e.sourceHash);
+      if (!h) throw new Error("Invalid sourceHash: must be a 64-character hex string (normalized to lowercase)");
+      return { rawSourceRef: e.sourceRef, sourceRef: r, sourceHash: h };
+    });
+    const latestHashes = await this.entryRepo.findLatestSourceHashes(entityId, normalized.map((e) => e.sourceRef));
+    const distinctHashes = Array.from(new Set(normalized.map((e) => e.sourceHash)));
+    const dupRefs = await Promise.all(
+      distinctHashes.map((h) => this.entryRepo.findSourceRefsByHash(entityId, h))
+    );
+    const dupMap = /* @__PURE__ */ new Map();
+    for (let i = 0; i < distinctHashes.length; i++) {
+      dupMap.set(distinctHashes[i], dupRefs[i]);
+    }
+    return normalized.map((e) => {
+      const stored = latestHashes.get(e.sourceRef);
+      const changed = stored === void 0 || stored === null || normalizeSourceHash(stored) !== e.sourceHash;
+      const allRefs = dupMap.get(e.sourceHash) ?? [];
+      const others = allRefs.filter((r) => r !== e.sourceRef);
+      if (others.length === 0) {
+        return { sourceRef: e.rawSourceRef, changed };
+      }
+      const canonical = others[0];
+      return { sourceRef: e.rawSourceRef, changed, duplicateOf: canonical };
+    });
+  }
+  /**
+   * 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`.
+   */
+  async listSourceRefs(entityId) {
+    return this.entryRepo.listSourceRefs(entityId);
+  }
+  /**
+   * Returns the live source_refs for an entity that hold the given source_hash,
+   * sorted `COLLATE BINARY` ascending. The first element is the canonical ref
+   * under the code-unit-minimum rule (no locale dependency). Used by the
+   * ingestDocument guard and by hosts auditing duplicate-content collisions.
+   */
+  async findSourceRefsByHash(entityId, sourceHash) {
+    return this.entryRepo.findSourceRefsByHash(entityId, sourceHash);
   }
   async runPrune(entityId, options) {
     return this.maintenanceService.runPrune(entityId, options);
@@ -5715,16 +5996,16 @@ var WikiMemory = class {
   async importDump(dump, opts) {
     return this.importExportService.importDump(dump, opts);
   }
-  async forget(entityId, params) {
-    return this.maintenanceService.forget(entityId, params);
+  async forget(entityId, params, opts) {
+    return this.maintenanceService.forget(entityId, params, opts);
   }
   /**
    * @param params.promptOverride - Overrides the system prompt for this ingest call only.
    * For persistent customization, set `options.config.prompts.ingestSystemPrompt` at
    * WikiMemory construction time.
    */
-  async ingestDocument(entityId, params) {
-    return this.ingestionService.ingestDocument(entityId, params);
+  async ingestDocument(entityId, params, opts) {
+    return this.ingestionService.ingestDocument(entityId, params, opts);
   }
   /**
    * Returns up to `limit` unprocessed outbox events, oldest first.
@@ -6543,6 +6824,7 @@ exports.ONTOLOGY_BACKFILL_SYSTEM_PROMPT = ONTOLOGY_BACKFILL_SYSTEM_PROMPT;
 exports.PromptService = PromptService;
 exports.PrunePartialFailureError = PrunePartialFailureError;
 exports.WikiBusyError = WikiBusyError;
+exports.WikiDuplicateHashError = WikiDuplicateHashError;
 exports.WikiMemory = WikiMemory;
 exports.WikiTransactionError = WikiTransactionError;
 exports.chunkText = chunkText;