@equationalapplications/core-llm-wiki 5.1.1 → 5.2.1

package/dist/index.mjs

@@ -1,5 +1,5 @@
-import { __privateAdd, MetadataRepository, EmbeddingService, SearchService, JobManager, PromptService, IngestionService, MaintenanceService, ImportExportService, RetrievalService, WriteService, __privateGet, __privateSet, normalizeSourceRef, normalizeSourceHash, entitySummaryMetaKey, generateId, BaseRepository, emptyManifest, resolveNodeType, validateInlineEdges, resolveEdgeDefinitions, normalizeTitleKey, WikiTransactionError, extractSqliteCode } from './chunk-YKXCMOHH.mjs';
-export { DEFAULT_CHUNK_OVERLAP, DEFAULT_MAX_CHUNK_LENGTH, HEAL_BATCH_SIZE, HEAL_RECHECK_MS, HOOK_TIMEOUT_MARKER, ONTOLOGY_BACKFILL_BATCH_SIZE, ONTOLOGY_BACKFILL_MAX_PROMPT_CHARS, ONTOLOGY_BACKFILL_RECHECK_MS, ONTOLOGY_BACKFILL_SYSTEM_PROMPT, PromptService, PrunePartialFailureError, WikiBusyError, WikiTransactionError, chunkText, configureRandomSource, parseEmbedding, safeSlice, validateManifest } from './chunk-YKXCMOHH.mjs';
+import { __privateAdd, MetadataRepository, EmbeddingService, SearchService, JobManager, PromptService, IngestionService, MaintenanceService, ImportExportService, RetrievalService, WriteService, __privateGet, __privateSet, normalizeSourceRef, normalizeSourceHash, entitySummaryMetaKey, generateId, BaseRepository, emptyManifest, resolveNodeType, validateInlineEdges, resolveEdgeDefinitions, normalizeTitleKey, WikiTransactionError, extractSqliteCode } from './chunk-6HNIOKT4.mjs';
+export { DEFAULT_CHUNK_OVERLAP, DEFAULT_MAX_CHUNK_LENGTH, HEAL_BATCH_SIZE, HEAL_RECHECK_MS, HOOK_TIMEOUT_MARKER, ONTOLOGY_BACKFILL_BATCH_SIZE, ONTOLOGY_BACKFILL_MAX_PROMPT_CHARS, ONTOLOGY_BACKFILL_RECHECK_MS, ONTOLOGY_BACKFILL_SYSTEM_PROMPT, PromptService, PrunePartialFailureError, WikiBusyError, WikiDuplicateHashError, WikiTransactionError, chunkText, configureRandomSource, parseEmbedding, safeSlice, validateManifest } from './chunk-6HNIOKT4.mjs';
 import { appendRelatedSection, buildConceptDocument, buildLogMd, buildEntityIndexMd, buildRootIndexMd, isAllowedOkfPath, parseRootIndexMd, parseEntityIndexMd, parseConcept, splitRelatedSection, extractMarkdownLinks, parseLogMd, parseEventIdComment, appendEventIdComment } from '@equationalapplications/core-okf';
 
 // src/db/schema.ts
@@ -32,6 +32,24 @@ async function setupDatabase(db, prefix) {
     CREATE INDEX IF NOT EXISTS ${prefix}entries_source_hash_idx ON ${prefix}entries(entity_id, source_hash) WHERE source_hash IS NOT NULL;
     CREATE INDEX IF NOT EXISTS ${prefix}entries_updated_idx ON ${prefix}entries(updated_at DESC);
 
+    -- source_ref_index: per-(entity, 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;
+    -- entries-level uniqueness cannot express it because a single ingestDocument call
+    -- writes N facts that all share (entity_id, source_ref, source_hash). See
+    -- docs/superpowers/specs/2026-08-07-dependabot-concurrency-release-hygiene-design.md \xA7B1.
+    CREATE TABLE IF NOT EXISTS ${prefix}source_ref_index (
+      id TEXT PRIMARY KEY,
+      entity_id TEXT NOT NULL,
+      source_hash TEXT NOT NULL,
+      source_ref TEXT NOT NULL,
+      created_at INTEGER NOT NULL,
+      deleted_at INTEGER
+    );
+    CREATE UNIQUE INDEX IF NOT EXISTS ${prefix}idx_source_ref_hash
+      ON ${prefix}source_ref_index (entity_id, source_hash)
+      WHERE deleted_at IS NULL;
+
     CREATE TABLE IF NOT EXISTS ${prefix}tasks (
       id TEXT PRIMARY KEY,
       entity_id TEXT NOT NULL,
@@ -278,6 +296,61 @@ var MIGRATIONS = [
         );
       }
     }
+  },
+  {
+    version: 9,
+    description: "add_source_ref_index",
+    run: async (db, prefix) => {
+      const duplicates = await db.getAllAsync(
+        `SELECT entity_id, source_hash, COUNT(DISTINCT source_ref) AS n_refs
+         FROM ${prefix}entries
+         WHERE deleted_at IS NULL AND source_hash IS NOT NULL
+         GROUP BY entity_id, source_hash
+         HAVING COUNT(DISTINCT source_ref) > 1`
+      );
+      if (duplicates.length > 0) {
+        const sample = duplicates.slice(0, 5).map((d) => `(entity_id=${d.entity_id}, source_hash=${d.source_hash.slice(0, 12)}\u2026, n_refs=${d.n_refs})`).join(", ");
+        throw new Error(
+          `Migration v9 (add_source_ref_index) failed: existing live rows have multiple sourceRefs sharing a hash. Found ${duplicates.length} duplicate (entity_id, source_hash) groups. First ${Math.min(5, duplicates.length)}: ${sample}. Resolve each by calling forget({ sourceRef: <loser> }) for the offending sourceRef, then re-run setup.`
+        );
+      }
+      await db.execAsync(
+        `CREATE TABLE IF NOT EXISTS ${prefix}source_ref_index (
+          id TEXT PRIMARY KEY,
+          entity_id TEXT NOT NULL,
+          source_hash TEXT NOT NULL,
+          source_ref TEXT NOT NULL,
+          created_at INTEGER NOT NULL,
+          deleted_at INTEGER
+        );
+        CREATE UNIQUE INDEX IF NOT EXISTS ${prefix}idx_source_ref_hash
+          ON ${prefix}source_ref_index (entity_id, source_hash)
+          WHERE deleted_at IS NULL;`
+      );
+      await db.execAsync(
+        `INSERT OR IGNORE INTO ${prefix}source_ref_index (id, entity_id, source_hash, source_ref, created_at, deleted_at)
+         SELECT
+           'sri:' || entity_id || ':' || source_hash,
+           entity_id,
+           source_hash,
+           source_ref,
+           updated_at,
+           NULL
+         FROM (
+           SELECT
+             entity_id, source_hash, source_ref, updated_at,
+             ROW_NUMBER() OVER (
+               PARTITION BY entity_id, source_hash
+               ORDER BY updated_at ASC, id ASC
+             ) AS rn
+           FROM ${prefix}entries
+           WHERE deleted_at IS NULL
+             AND source_hash IS NOT NULL
+             AND source_ref IS NOT NULL
+         ) ranked
+         WHERE rn = 1;`
+      );
+    }
   }
 ];
 for (let i = 1; i < MIGRATIONS.length; i++) {
@@ -975,12 +1048,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);
@@ -1252,6 +1467,57 @@ var OutboxRepository = class extends BaseRepository {
   }
 };
 
+// src/repositories/SourceRefIndexRepository.ts
+var SourceRefIndexRepository = class 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).
+   */
+  async upsert(entityId, sourceHash, sourceRef, tx) {
+    const executor = this.getExecutor(tx);
+    await executor.runAsync(
+      `INSERT INTO ${this.prefix}source_ref_index (id, entity_id, source_hash, source_ref, created_at, deleted_at)
+       VALUES (?, ?, ?, ?, ?, NULL)`,
+      [generateId("sri_"), entityId, sourceHash, sourceRef, Date.now()]
+    );
+  }
+  /**
+   * 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.
+   */
+  async softDeleteByEntityAndSourceRef(entityId, sourceRef, tx) {
+    const executor = this.getExecutor(tx);
+    const now = Date.now();
+    const result = await executor.runAsync(
+      `UPDATE ${this.prefix}source_ref_index
+       SET deleted_at = ?, created_at = ?
+       WHERE entity_id = ? AND source_ref = ? AND deleted_at IS NULL`,
+      [now, now, entityId, sourceRef]
+    );
+    return result.changes;
+  }
+  /**
+   * 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).
+   */
+  async findActiveByEntityAndHash(entityId, sourceHash, tx) {
+    const executor = this.getExecutor(tx);
+    const row = await executor.getFirstAsync(
+      `SELECT source_ref FROM ${this.prefix}source_ref_index
+       WHERE entity_id = ? AND source_hash = ? AND deleted_at IS NULL`,
+      [entityId, sourceHash]
+    );
+    return row?.source_ref ?? null;
+  }
+};
+
 // src/repositories/TaskRepository.ts
 function mapRowToTask(row) {
   return {
@@ -1508,6 +1774,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
@@ -1916,6 +2194,7 @@ var WikiMemory = class {
     }
     this.outboxRepo = new OutboxRepository(this.db, this.prefix, !!options.config?.enableOutbox);
     this.entryRepo = new EntryRepository(this.db, this.prefix, this.outboxRepo);
+    this.sourceRefIndexRepo = new SourceRefIndexRepository(this.db, this.prefix);
     this.taskRepo = new TaskRepository(this.db, this.prefix, this.outboxRepo);
     this.eventRepo = new EventRepository(this.db, this.prefix);
     this.edgeRepo = new EdgeRepository(this.db, this.prefix);
@@ -1934,6 +2213,7 @@ var WikiMemory = class {
       this.prefix,
       this.options,
       this.entryRepo,
+      this.sourceRefIndexRepo,
       this.searchService,
       this.jobManager,
       this.embeddingService,
@@ -1945,6 +2225,7 @@ var WikiMemory = class {
       this.prefix,
       this.options,
       this.entryRepo,
+      this.sourceRefIndexRepo,
       this.taskRepo,
       this.eventRepo,
       this.metadataRepo,
@@ -2009,6 +2290,7 @@ var WikiMemory = class {
       promptService: this.promptService,
       graphTraversalService: this.graphTraversalService,
       entryRepo: this.entryRepo,
+      sourceRefIndexRepo: this.sourceRefIndexRepo,
       metadataRepo: this.metadataRepo,
       jobManager: this.jobManager
     };
@@ -2058,19 +2340,71 @@ 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.sourceRefIndexRepo.findActiveByEntityAndHash(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 canonical = dupMap.get(e.sourceHash) ?? null;
+      if (canonical === null || canonical === e.sourceRef) {
+        return { sourceRef: e.rawSourceRef, changed };
+      }
+      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.
+   * 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.
+   */
+  async findSourceRefsByHash(entityId, sourceHash) {
+    const canonical = await this.sourceRefIndexRepo.findActiveByEntityAndHash(entityId, sourceHash);
+    return canonical === null ? [] : [canonical];
   }
   async runPrune(entityId, options) {
     return this.maintenanceService.runPrune(entityId, options);
@@ -2157,16 +2491,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.