@equationalapplications/core-llm-wiki 4.6.1 → 4.8.0

package/dist/chunk-2FGDZKC2.mjs

@@ -0,0 +1,2547 @@
+import MiniSearch from 'minisearch';
+
+var __typeError = (msg) => {
+  throw TypeError(msg);
+};
+var __accessCheck = (obj, member, msg) => member.has(obj) || __typeError("Cannot " + msg);
+var __privateGet = (obj, member, getter) => (__accessCheck(obj, member, "read from private field"), getter ? getter.call(obj) : member.get(obj));
+var __privateAdd = (obj, member, value) => member.has(obj) ? __typeError("Cannot add the same private member more than once") : member instanceof WeakSet ? member.add(obj) : member.set(obj, value);
+var __privateSet = (obj, member, value, setter) => (__accessCheck(obj, member, "write to private field"), setter ? setter.call(obj, value) : member.set(obj, value), value);
+
+// src/utils/embedding.ts
+function parseEmbedding(blob, text) {
+  if (blob && blob.byteLength > 0) {
+    if (blob.byteLength % 4 !== 0) return null;
+    const copy = new ArrayBuffer(blob.byteLength);
+    new Uint8Array(copy).set(blob);
+    const vector = new Float32Array(copy);
+    for (const value of vector) {
+      if (!Number.isFinite(value)) return null;
+    }
+    return vector;
+  }
+  if (text) {
+    try {
+      const arr = JSON.parse(text);
+      if (!Array.isArray(arr) || !arr.every((v) => typeof v === "number" && isFinite(v))) return null;
+      const vector = new Float32Array(arr);
+      for (const value of vector) {
+        if (!Number.isFinite(value)) return null;
+      }
+      return vector;
+    } catch {
+      return null;
+    }
+  }
+  return null;
+}
+
+// src/utils/cosine.ts
+function cosineSimilarity(a, b) {
+  let dot = 0, normA = 0, normB = 0;
+  const len = Math.min(a.length, b.length);
+  for (let i = 0; i < len; i++) {
+    dot += a[i] * b[i];
+    normA += a[i] * a[i];
+    normB += b[i] * b[i];
+  }
+  const denom = Math.sqrt(normA) * Math.sqrt(normB);
+  return denom === 0 ? 0 : dot / denom;
+}
+
+// src/services/SearchService.ts
+var _SearchService = class _SearchService {
+  constructor(entryRepo) {
+    this.entryRepo = entryRepo;
+    this.miniSearchEntryIdsByEntity = /* @__PURE__ */ new Map();
+    this.vectorCache = /* @__PURE__ */ new Map();
+    this.miniSearch = new MiniSearch({
+      fields: ["title", "body", "tags"],
+      storeFields: ["entity_id"],
+      searchOptions: {
+        boost: { title: 2 },
+        fuzzy: 0.2,
+        prefix: true
+      }
+    });
+  }
+  /**
+   * Rebuilds the search index and clears the vector cache for a given entity.
+   * A direct replacement for manually syncing state after a DB transaction.
+   */
+  async sync(entityId) {
+    await this.rebuildIndex(entityId);
+    this.evictCache(entityId);
+  }
+  /**
+   * Clears the parsed vector cache. Useful for mid-loop flush guarantees
+   * or memory pressure evictions.
+   */
+  evictCache(entityId) {
+    if (entityId) {
+      this.vectorCache.delete(entityId);
+    } else {
+      this.vectorCache.clear();
+    }
+  }
+  /**
+   * Fully resets the search service.
+   */
+  clearAll() {
+    this.vectorCache.clear();
+    this.miniSearch.removeAll();
+    this.miniSearchEntryIdsByEntity.clear();
+  }
+  /**
+   * Executes a keyword search against the active MiniSearch index.
+   */
+  searchKeyword(query, entityIds, limit) {
+    const entityIdSet = new Set(entityIds);
+    const results = this.miniSearch.search(query, {
+      filter: (r) => entityIdSet.has(r.entity_id),
+      combineWith: "OR"
+    });
+    return results.slice(0, limit);
+  }
+  /**
+   * Pre-fetches MiniSearch scores for candidate hydration, used during hybrid weighting.
+   */
+  getMiniSearchScores(query, entityIds, preFilterLimit) {
+    const entityIdSet = new Set(entityIds);
+    let results = this.miniSearch.search(query, {
+      filter: (r) => entityIdSet.has(r.entity_id),
+      combineWith: "OR"
+    });
+    if (preFilterLimit !== void 0) {
+      results = results.slice(0, preFilterLimit);
+    }
+    if (results.length === 0) return /* @__PURE__ */ new Map();
+    const maxMsScore = Math.max(1, results[0]?.score ?? 1);
+    return new Map(results.map((r) => [r.id, r.score / maxMsScore]));
+  }
+  /**
+   * Score candidate rows using in-process JS cosine similarity.
+   * Applies hybrid blending (if weight set) and tie-break sorting before returning.
+   */
+  async rankSemantic(args) {
+    const queryVec = args.queryVec instanceof Float32Array ? args.queryVec.slice() : Array.from(args.queryVec);
+    const { entityId, candidateRows, weight, miniSearchScores, populateCache, limit, skipSort } = args;
+    let entityCache = this.vectorCache.get(entityId);
+    const tooLarge = populateCache && candidateRows.length > _SearchService.MAX_VECTOR_CACHE_FACTS_PER_ENTITY;
+    if (tooLarge && entityCache) {
+      this.vectorCache.delete(entityId);
+      entityCache = void 0;
+    }
+    const canCache = populateCache && !tooLarge;
+    if (canCache && !entityCache) {
+      entityCache = /* @__PURE__ */ new Map();
+    }
+    const scored = candidateRows.map((row) => {
+      let vector = entityCache?.get(row.id) ?? parseEmbedding(row.embedding_blob, row.embedding);
+      if (vector && canCache && entityCache && !entityCache.has(row.id)) {
+        entityCache.set(row.id, vector);
+      }
+      let score = 0;
+      if (vector && vector.length === queryVec.length) {
+        const cosSim = cosineSimilarity(queryVec, vector);
+        if (weight !== void 0) {
+          const kwScore = miniSearchScores?.get(row.id) ?? 0;
+          score = weight * Math.max(0, cosSim) + (1 - weight) * kwScore;
+        } else {
+          score = cosSim;
+        }
+      } else if (weight !== void 0 && weight < 1) {
+        const kwScore = miniSearchScores?.get(row.id) ?? 0;
+        score = (1 - weight) * kwScore;
+      } else {
+        score = -2;
+      }
+      return {
+        id: row.id,
+        entity_id: row.entity_id,
+        score,
+        updated_at: row.updated_at,
+        access_count: row.access_count
+      };
+    });
+    if (canCache && entityCache && entityCache.size > 0) {
+      if (!this.vectorCache.has(entityId)) {
+        if (this.vectorCache.size >= _SearchService.MAX_VECTOR_CACHE_ENTITIES) {
+          const oldestKey = this.vectorCache.keys().next().value;
+          if (oldestKey !== void 0) this.vectorCache.delete(oldestKey);
+        }
+        this.vectorCache.set(entityId, entityCache);
+      }
+    }
+    if (!skipSort) {
+      this._tieBreakSort(scored);
+    }
+    return scored.slice(0, limit);
+  }
+  // --- Internal Index Management ---
+  async rebuildIndex(entityId) {
+    if (entityId) {
+      const rows2 = await this.entryRepo.findMiniSearchRows(entityId);
+      const previousIds = this.miniSearchEntryIdsByEntity.get(entityId);
+      if (previousIds) {
+        for (const id of previousIds) {
+          this.miniSearch.discard(id);
+        }
+      }
+      const documents2 = rows2.map((row) => this.normalizeMiniSearchRow(row));
+      if (documents2.length > 0) {
+        this.miniSearch.addAll(documents2);
+      }
+      this.miniSearchEntryIdsByEntity.set(
+        entityId,
+        new Set(documents2.map((document) => document.id))
+      );
+      return;
+    }
+    const rows = await this.entryRepo.findMiniSearchRows();
+    this.miniSearch.removeAll();
+    this.miniSearchEntryIdsByEntity.clear();
+    const documents = rows.map((row) => this.normalizeMiniSearchRow(row));
+    if (documents.length > 0) {
+      this.miniSearch.addAll(documents);
+    }
+    for (const document of documents) {
+      const ids = this.miniSearchEntryIdsByEntity.get(document.entity_id) ?? /* @__PURE__ */ new Set();
+      ids.add(document.id);
+      this.miniSearchEntryIdsByEntity.set(document.entity_id, ids);
+    }
+  }
+  normalizeMiniSearchRow(row) {
+    return {
+      id: row.id,
+      entity_id: row.entity_id,
+      title: row.title,
+      body: row.body,
+      tags: (() => {
+        try {
+          const parsed = JSON.parse(row.tags);
+          return Array.isArray(parsed) ? parsed.join(" ") : row.tags;
+        } catch {
+          return row.tags;
+        }
+      })()
+    };
+  }
+  _tieBreakSort(items) {
+    items.sort((a, b) => this._compareScoredRows(a, b));
+  }
+  _compareScoredRows(a, b) {
+    const scoreDiff = b.score - a.score;
+    if (!Number.isNaN(scoreDiff) && scoreDiff !== 0) return scoreDiff;
+    const accessCountDiff = (b.access_count ?? 0) - (a.access_count ?? 0);
+    if (accessCountDiff !== 0) return accessCountDiff;
+    const updatedAtDiff = (b.updated_at ?? 0) - (a.updated_at ?? 0);
+    if (updatedAtDiff !== 0) return updatedAtDiff;
+    return a.id.localeCompare(b.id);
+  }
+};
+/**
+ * Maximum number of entities whose parsed embedding vectors are held in
+ * memory. This cap is intentionally conservative so the cache remains safe
+ * on memory-constrained runtimes (e.g., mobile/Expo).
+ */
+_SearchService.MAX_VECTOR_CACHE_ENTITIES = 16;
+/**
+ * Maximum number of fact vectors cached per entity. Keep this high enough to
+ * preserve the parsed-embedding reuse optimization for common mid-sized
+ * entities while still maintaining a bounded memory footprint.
+ */
+_SearchService.MAX_VECTOR_CACHE_FACTS_PER_ENTITY = 500;
+var SearchService = _SearchService;
+
+// src/types.ts
+var WikiBusyError = class extends Error {
+  constructor(operation, entityId) {
+    super(`${operation} already running for entity ${entityId}`);
+    this.name = "WikiBusyError";
+    this.operation = operation;
+    this.entityId = 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`);
+    this.name = "PrunePartialFailureError";
+    this.deleted = deleted;
+    this.failedAt = failedAt;
+    this.remaining = remaining;
+    this.deletedTasks = deletedTasks;
+    this.deletedEvents = deletedEvents;
+    this.cause = cause;
+  }
+};
+var HOOK_TIMEOUT_MARKER = /* @__PURE__ */ Symbol("WikiMemoryHookTimeout");
+
+// src/services/JobManager.ts
+var JobManager = class {
+  constructor(prefix) {
+    this.prefix = prefix;
+    this.activeMaintenanceJobs = /* @__PURE__ */ new Set();
+    this.activeIngestJobs = /* @__PURE__ */ new Map();
+    this.statusSubscribers = /* @__PURE__ */ new Map();
+  }
+  _pruneKey(entityId) {
+    return `${this.prefix}:${entityId}:prune`;
+  }
+  _reembedKey(entityId) {
+    return `${this.prefix}:${entityId}:reembed`;
+  }
+  _globalReembedKey() {
+    return `${this.prefix}:reembed`;
+  }
+  _importKey(entityId) {
+    return `${this.prefix}:${entityId}:import`;
+  }
+  _globalImportKey() {
+    return `${this.prefix}:import`;
+  }
+  _forgetKey(entityId) {
+    return `${this.prefix}:${entityId}:forget`;
+  }
+  _librarianKey(entityId) {
+    return `${this.prefix}:${entityId}:librarian`;
+  }
+  _healKey(entityId) {
+    return `${this.prefix}:${entityId}:heal`;
+  }
+  _isReembedActive(entityId) {
+    return this.activeMaintenanceJobs.has(this._reembedKey(entityId)) || this.activeMaintenanceJobs.has(this._globalReembedKey());
+  }
+  _isImportActiveFor(entityId) {
+    return this.activeMaintenanceJobs.has(this._importKey(entityId)) || this.activeMaintenanceJobs.has(this._globalImportKey());
+  }
+  _isForgetActiveFor(entityId) {
+    return this.activeMaintenanceJobs.has(this._forgetKey(entityId));
+  }
+  _isAnyMaintenanceActiveWithSuffix(suffix) {
+    const entityKeyPrefix = `${this.prefix}:`;
+    for (const k of this.activeMaintenanceJobs) {
+      if (k.startsWith(entityKeyPrefix) && k.endsWith(suffix)) return true;
+    }
+    return false;
+  }
+  _hasIngestJob(entityId, sourceRef) {
+    return this.activeIngestJobs.get(entityId)?.has(sourceRef ?? "") ?? false;
+  }
+  _addIngestJob(entityId, sourceRef) {
+    const sourceKey = sourceRef ?? "";
+    let refs = this.activeIngestJobs.get(entityId);
+    if (!refs) {
+      refs = /* @__PURE__ */ new Set();
+      this.activeIngestJobs.set(entityId, refs);
+    }
+    refs.add(sourceKey);
+  }
+  _removeIngestJob(entityId, sourceRef) {
+    const sourceKey = sourceRef ?? "";
+    const refs = this.activeIngestJobs.get(entityId);
+    if (!refs) return;
+    refs.delete(sourceKey);
+    if (refs.size === 0) {
+      this.activeIngestJobs.delete(entityId);
+    }
+  }
+  _isIngestActiveFor(entityId) {
+    return this.activeIngestJobs.has(entityId);
+  }
+  acquireLock(operation, entityId, sourceRef) {
+    let blockingOperation = null;
+    if (operation !== "global_import" && this.activeMaintenanceJobs.has(this._globalImportKey())) {
+      throw new WikiBusyError("import", "*");
+    }
+    switch (operation) {
+      case "prune":
+        if (this.activeMaintenanceJobs.has(this._pruneKey(entityId))) blockingOperation = "prune";
+        else if (this.activeMaintenanceJobs.has(this._librarianKey(entityId))) blockingOperation = "librarian";
+        else if (this.activeMaintenanceJobs.has(this._healKey(entityId))) blockingOperation = "heal";
+        else if (this._isReembedActive(entityId)) blockingOperation = "reembed";
+        else if (this._isIngestActiveFor(entityId)) blockingOperation = "ingest";
+        else if (this._isImportActiveFor(entityId)) blockingOperation = "import";
+        else if (this._isForgetActiveFor(entityId)) blockingOperation = "forget";
+        break;
+      case "librarian":
+      case "heal": {
+        const opKey = operation === "librarian" ? this._librarianKey(entityId) : this._healKey(entityId);
+        if (this.activeMaintenanceJobs.has(opKey)) blockingOperation = operation;
+        else if (this.activeMaintenanceJobs.has(this._pruneKey(entityId))) blockingOperation = "prune";
+        else if (this._isReembedActive(entityId)) blockingOperation = "reembed";
+        else if (this._isImportActiveFor(entityId)) blockingOperation = "import";
+        else if (this._isForgetActiveFor(entityId)) blockingOperation = "forget";
+        break;
+      }
+      case "reembed":
+        if (this.activeMaintenanceJobs.has(this._reembedKey(entityId))) blockingOperation = "reembed";
+        else if (this.activeMaintenanceJobs.has(this._globalReembedKey())) blockingOperation = "reembed";
+        else if (this.activeMaintenanceJobs.has(this._pruneKey(entityId))) blockingOperation = "prune";
+        else if (this.activeMaintenanceJobs.has(this._librarianKey(entityId))) blockingOperation = "librarian";
+        else if (this.activeMaintenanceJobs.has(this._healKey(entityId))) blockingOperation = "heal";
+        else if (this._isIngestActiveFor(entityId)) blockingOperation = "ingest";
+        else if (this._isImportActiveFor(entityId)) blockingOperation = "import";
+        else if (this._isForgetActiveFor(entityId)) blockingOperation = "forget";
+        break;
+      case "global_reembed":
+        if (this.activeMaintenanceJobs.has(this._globalReembedKey())) blockingOperation = "reembed";
+        else if (this._isAnyMaintenanceActiveWithSuffix(":reembed")) blockingOperation = "reembed";
+        else if (this._isAnyMaintenanceActiveWithSuffix(":prune")) blockingOperation = "prune";
+        else if (this._isAnyMaintenanceActiveWithSuffix(":librarian")) blockingOperation = "librarian";
+        else if (this._isAnyMaintenanceActiveWithSuffix(":heal")) blockingOperation = "heal";
+        else if (this.activeIngestJobs.size > 0) blockingOperation = "ingest";
+        else if (this._isAnyMaintenanceActiveWithSuffix(":import")) blockingOperation = "import";
+        else if (this._isAnyMaintenanceActiveWithSuffix(":forget")) blockingOperation = "forget";
+        break;
+      case "import":
+      case "forget": {
+        const selfKey = operation === "import" ? this._importKey(entityId) : this._forgetKey(entityId);
+        if (this.activeMaintenanceJobs.has(selfKey)) blockingOperation = operation;
+        else if (this.activeMaintenanceJobs.has(this._librarianKey(entityId))) blockingOperation = "librarian";
+        else if (this.activeMaintenanceJobs.has(this._healKey(entityId))) blockingOperation = "heal";
+        else if (this.activeMaintenanceJobs.has(this._pruneKey(entityId))) blockingOperation = "prune";
+        else if (this._isReembedActive(entityId)) blockingOperation = "reembed";
+        else if (this._isIngestActiveFor(entityId)) blockingOperation = "ingest";
+        else if (this._isImportActiveFor(entityId)) blockingOperation = "import";
+        else if (this._isForgetActiveFor(entityId)) blockingOperation = "forget";
+        break;
+      }
+      case "global_import":
+        if (this.activeMaintenanceJobs.has(this._globalImportKey())) blockingOperation = "import";
+        break;
+      case "ingest": {
+        const sourceKey = sourceRef ?? "";
+        if (this._hasIngestJob(entityId, sourceKey)) blockingOperation = "ingest";
+        else if (this.activeMaintenanceJobs.has(this._pruneKey(entityId))) blockingOperation = "prune";
+        else if (this._isReembedActive(entityId)) blockingOperation = "reembed";
+        else if (this._isImportActiveFor(entityId)) blockingOperation = "import";
+        else if (this._isForgetActiveFor(entityId)) blockingOperation = "forget";
+        break;
+      }
+    }
+    if (blockingOperation) {
+      throw new WikiBusyError(
+        blockingOperation,
+        operation === "global_reembed" || operation === "global_import" ? "*" : entityId
+      );
+    }
+    if (operation === "ingest") {
+      this._addIngestJob(entityId, sourceRef);
+    } else if (operation === "global_reembed") {
+      this.activeMaintenanceJobs.add(this._globalReembedKey());
+    } else if (operation === "global_import") {
+      this.activeMaintenanceJobs.add(this._globalImportKey());
+    } else {
+      const keyFnName = `_${operation}Key`;
+      const keyFn = this[keyFnName];
+      this.activeMaintenanceJobs.add(keyFn.call(this, entityId));
+    }
+    this._notifyStatusSubscribers(entityId);
+  }
+  releaseLock(operation, entityId, sourceRef) {
+    if (operation === "ingest") {
+      this._removeIngestJob(entityId, sourceRef);
+    } else if (operation === "global_reembed") {
+      this.activeMaintenanceJobs.delete(this._globalReembedKey());
+    } else if (operation === "global_import") {
+      this.activeMaintenanceJobs.delete(this._globalImportKey());
+    } else {
+      const keyFnName = `_${operation}Key`;
+      const keyFn = this[keyFnName];
+      this.activeMaintenanceJobs.delete(keyFn.call(this, entityId));
+    }
+    this._notifyStatusSubscribers(entityId);
+  }
+  /**
+   * Returns true if acquireLock(operation, entityId) would throw WikiBusyError.
+   * Use for non-throwing conflict checks (e.g. auto-trigger gating in write()).
+   */
+  isBlocked(operation, entityId) {
+    if (operation !== "global_import" && this.activeMaintenanceJobs.has(this._globalImportKey())) return true;
+    switch (operation) {
+      case "librarian":
+        return this.activeMaintenanceJobs.has(this._librarianKey(entityId)) || this.activeMaintenanceJobs.has(this._pruneKey(entityId)) || this._isReembedActive(entityId) || this._isImportActiveFor(entityId) || this._isForgetActiveFor(entityId);
+      case "heal":
+        return this.activeMaintenanceJobs.has(this._healKey(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._isReembedActive(entityId) || this._isIngestActiveFor(entityId) || this._isImportActiveFor(entityId) || this._isForgetActiveFor(entityId);
+      default:
+        return false;
+    }
+  }
+  /**
+   * Auto-heal historically only gated on the heal self-key. Keep that behavior
+   * for write() auto-trigger paths while preserving stricter checks in acquireLock().
+   */
+  tryAcquireAutoHealLock(entityId) {
+    const healKey = this._healKey(entityId);
+    if (this.activeMaintenanceJobs.has(healKey)) return false;
+    this.activeMaintenanceJobs.add(healKey);
+    this._notifyStatusSubscribers(entityId);
+    return true;
+  }
+  /**
+   * Validates then acquires global + per-entity import locks atomically.
+   * Validates all entities before acquiring any lock (same as current importDump semantics).
+   */
+  acquireImportLocks(entityIds) {
+    for (const entityId of entityIds) {
+      if (this.activeMaintenanceJobs.has(this._importKey(entityId))) throw new WikiBusyError("import", entityId);
+      if (this.activeMaintenanceJobs.has(this._librarianKey(entityId))) throw new WikiBusyError("librarian", entityId);
+      if (this.activeMaintenanceJobs.has(this._healKey(entityId))) throw new WikiBusyError("heal", entityId);
+      if (this.activeMaintenanceJobs.has(this._pruneKey(entityId))) throw new WikiBusyError("prune", entityId);
+      if (this._isReembedActive(entityId)) throw new WikiBusyError("reembed", entityId);
+      if (this._isIngestActiveFor(entityId)) throw new WikiBusyError("ingest", entityId);
+      if (this._isForgetActiveFor(entityId)) throw new WikiBusyError("forget", entityId);
+    }
+    if (this.activeMaintenanceJobs.has(this._globalImportKey())) throw new WikiBusyError("import", "*");
+    this.activeMaintenanceJobs.add(this._globalImportKey());
+    for (const entityId of entityIds) {
+      this.activeMaintenanceJobs.add(this._importKey(entityId));
+    }
+  }
+  releaseImportLocks(entityIds) {
+    this.activeMaintenanceJobs.delete(this._globalImportKey());
+    for (const entityId of entityIds) {
+      this.activeMaintenanceJobs.delete(this._importKey(entityId));
+    }
+  }
+  getEntityStatus(entityId) {
+    return {
+      ingesting: this._isIngestActiveFor(entityId),
+      librarian: this.activeMaintenanceJobs.has(this._librarianKey(entityId)),
+      heal: this.activeMaintenanceJobs.has(this._healKey(entityId))
+    };
+  }
+  subscribeEntityStatus(entityId, callback) {
+    const initial = this.getEntityStatus(entityId);
+    let set = this.statusSubscribers.get(entityId);
+    if (!set) {
+      set = /* @__PURE__ */ new Set();
+      this.statusSubscribers.set(entityId, set);
+    }
+    const entry = { callback, last: this._copyEntityStatus(initial) };
+    set.add(entry);
+    try {
+      callback(this._copyEntityStatus(initial));
+    } catch (err) {
+      console.error(`[JobManager] callback error for entityId="${entityId}" during initial emission`, err);
+    }
+    let active = true;
+    return () => {
+      if (!active) return;
+      active = false;
+      const s = this.statusSubscribers.get(entityId);
+      if (!s) return;
+      s.delete(entry);
+      if (s.size === 0) this.statusSubscribers.delete(entityId);
+    };
+  }
+  _copyEntityStatus(s) {
+    return { ingesting: s.ingesting, librarian: s.librarian, heal: s.heal };
+  }
+  _notifyStatusSubscribers(entityId) {
+    if (entityId === "*") return;
+    const set = this.statusSubscribers.get(entityId);
+    if (!set || set.size === 0) return;
+    for (const entry of Array.from(set)) {
+      if (!set.has(entry)) continue;
+      const next = this.getEntityStatus(entityId);
+      if (entry.last.ingesting === next.ingesting && entry.last.librarian === next.librarian && entry.last.heal === next.heal) {
+        continue;
+      }
+      entry.last = this._copyEntityStatus(next);
+      try {
+        entry.callback(this._copyEntityStatus(next));
+      } catch (err) {
+        console.error(`[JobManager] callback error for entityId="${entityId}" during transition emission`, err);
+      }
+    }
+  }
+};
+
+// src/prompts.ts
+var LIBRARIAN_SYSTEM_PROMPT = `You are a knowledge extraction agent. Your job is to analyze recent episodic events and extract stable facts and actionable tasks about the user or entity.
+Return ONLY a valid JSON object matching this schema:
+{
+  "facts": [{ "title": "string (max 80 chars)", "body": "string (max 800 chars)", "tags": ["string"], "confidence": "certain|inferred|tentative" }],
+  "tasks": [{ "description": "string", "priority": "number (0-10)" }]
+}
+Keep facts concise. Do not return markdown, just raw JSON.`;
+var HEAL_SYSTEM_PROMPT = `You are a memory grooming agent. Your job is to review a full dump of facts and recent events to resolve contradictions, downgrade stale claims, and flag obsolete facts for deletion.
+Return ONLY a valid JSON object matching this schema:
+{
+  "downgraded": ["string (fact IDs)"],
+  "deleted": ["string (fact IDs)"],
+  "newFacts": [{ "title": "string (max 80 chars)", "body": "string (max 800 chars)", "tags": ["string"], "confidence": "certain|inferred|tentative" }]
+}
+Do not return markdown, just raw JSON.`;
+var INGEST_SYSTEM_PROMPT = `You are a document ingestion agent. Your job is to extract factual knowledge from the provided document chunk.
+Return ONLY a valid JSON object matching this schema:
+{
+  "facts": [{ "title": "string (max 80 chars)", "body": "string (max 800 chars)", "tags": ["string"], "confidence": "certain|inferred|tentative" }]
+}
+Extract verbatim factual content. Do not return markdown, just raw JSON.`;
+
+// src/services/PromptService.ts
+var PromptService = class {
+  constructor(globalOverrides) {
+    this.globalOverrides = globalOverrides;
+  }
+  hydrate(template, variables) {
+    return template.replace(/\{\{\s*(\w+)\s*\}\}/g, (_match, key) => {
+      const value = variables[key];
+      if (value === void 0) return _match;
+      return typeof value === "string" ? value : JSON.stringify(value, null, 2);
+    });
+  }
+  buildIngestPrompt(documentChunk, runtimeOverride) {
+    const template = runtimeOverride ?? this.globalOverrides?.ingestSystemPrompt ?? INGEST_SYSTEM_PROMPT;
+    if (/\{\{\s*documentChunk\s*\}\}/.test(template)) {
+      return {
+        systemPrompt: this.hydrate(template, { documentChunk }),
+        userPrompt: "Please extract the facts."
+      };
+    }
+    return {
+      systemPrompt: template,
+      userPrompt: `Document Chunk:
+${documentChunk}`
+    };
+  }
+  buildLibrarianPrompt(events, currentFacts, runtimeOverride) {
+    const template = runtimeOverride ?? this.globalOverrides?.librarianSystemPrompt ?? LIBRARIAN_SYSTEM_PROMPT;
+    if (/\{\{\s*events\s*\}\}/.test(template) || /\{\{\s*currentFacts\s*\}\}/.test(template)) {
+      return {
+        systemPrompt: this.hydrate(template, { events, currentFacts }),
+        userPrompt: "Please synthesize the context."
+      };
+    }
+    return {
+      systemPrompt: template,
+      userPrompt: `Events:
+${JSON.stringify(events, null, 2)}
+
+Current Facts:
+${JSON.stringify(currentFacts, null, 2)}`
+    };
+  }
+  buildHealPrompt(healCandidates, documentAnchors, allTasks, recentEvents, runtimeOverride) {
+    const template = runtimeOverride ?? this.globalOverrides?.healSystemPrompt ?? HEAL_SYSTEM_PROMPT;
+    if (/\{\{\s*healCandidates\s*\}\}/.test(template) || /\{\{\s*documentAnchors\s*\}\}/.test(template) || /\{\{\s*allTasks\s*\}\}/.test(template) || /\{\{\s*recentEvents\s*\}\}/.test(template)) {
+      return {
+        systemPrompt: this.hydrate(template, { healCandidates, documentAnchors, allTasks, recentEvents }),
+        userPrompt: "Please heal the memory graph."
+      };
+    }
+    return {
+      systemPrompt: template,
+      userPrompt: `Heal Candidates:
+${JSON.stringify(healCandidates, null, 2)}
+Document Anchors (DO NOT MODIFY OR DELETE):
+${JSON.stringify(documentAnchors, null, 2)}
+All Tasks:
+${JSON.stringify(allTasks, null, 2)}
+Recent Events:
+${JSON.stringify(recentEvents, null, 2)}
+The following document anchors are provided for contradiction detection only. Do not include them in \`downgraded\`, \`deleted\`, or \`newFacts\`.`
+    };
+  }
+};
+
+// src/utils/pure.ts
+function parseJsonResponse(text) {
+  const firstBrace = text.indexOf("{");
+  const firstBracket = text.indexOf("[");
+  let start;
+  let openChar;
+  let closeChar;
+  const useBrace = firstBrace !== -1 && (firstBracket === -1 || firstBrace < firstBracket);
+  if (useBrace) {
+    start = firstBrace;
+    openChar = "{";
+    closeChar = "}";
+  } else if (firstBracket !== -1) {
+    start = firstBracket;
+    openChar = "[";
+    closeChar = "]";
+  } else {
+    throw new SyntaxError("No JSON object/array found in LLM response");
+  }
+  let depth = 0;
+  let inString = false;
+  let escape = false;
+  let end = -1;
+  for (let i = start; i < text.length; i++) {
+    const ch = text[i];
+    if (escape) {
+      escape = false;
+      continue;
+    }
+    if (ch === "\\" && inString) {
+      escape = true;
+      continue;
+    }
+    if (ch === '"') {
+      inString = !inString;
+      continue;
+    }
+    if (inString) continue;
+    if (ch === openChar) {
+      depth++;
+      continue;
+    }
+    if (ch === closeChar) {
+      depth--;
+      if (depth === 0) {
+        end = i;
+        break;
+      }
+    }
+  }
+  if (end === -1) throw new SyntaxError("No JSON object/array found in LLM response");
+  return JSON.parse(text.slice(start, end + 1));
+}
+function sanitizeRankerError(err, sanitizeRankerErrors) {
+  if (sanitizeRankerErrors === false) {
+    return err instanceof Error ? err : new Error(String(err));
+  }
+  const typeName = err instanceof Error ? err.constructor?.name ?? "Error" : typeof err;
+  const innerCause = err instanceof Error && err.cause !== void 0 ? new Error(`Caused by: ${err.cause?.constructor?.name ?? typeof err.cause}`) : void 0;
+  const sanitized = new Error(
+    `VectorRanker ${typeName} (message scrubbed for security)`,
+    innerCause ? { cause: innerCause } : void 0
+  );
+  sanitized.name = typeName;
+  return sanitized;
+}
+function safeSlice(value, start, end) {
+  const length = value.length;
+  let safeStart = start < 0 ? Math.max(length + start, 0) : Math.min(start, length);
+  let safeEnd = end === void 0 ? length : end < 0 ? Math.max(length + end, 0) : Math.min(end, length);
+  if (safeStart > safeEnd) {
+    [safeStart, safeEnd] = [safeEnd, safeStart];
+  }
+  if (safeStart > 0 && safeStart < length && value.charCodeAt(safeStart) >= 56320 && value.charCodeAt(safeStart) <= 57343 && value.charCodeAt(safeStart - 1) >= 55296 && value.charCodeAt(safeStart - 1) <= 56319) {
+    safeStart--;
+  }
+  if (safeEnd > 0 && safeEnd < length && value.charCodeAt(safeEnd - 1) >= 55296 && value.charCodeAt(safeEnd - 1) <= 56319 && value.charCodeAt(safeEnd) >= 56320 && value.charCodeAt(safeEnd) <= 57343) {
+    safeEnd--;
+  }
+  return value.slice(safeStart, safeEnd);
+}
+function chunkText(input, maxChunkLength, overlap) {
+  const text = input.trim();
+  if (text.length === 0) return { chunks: [], truncated: false };
+  if (!Number.isInteger(maxChunkLength) || maxChunkLength < 2) {
+    throw new Error("maxChunkLength must be an integer >= 2");
+  }
+  if (!Number.isInteger(overlap) || overlap < 0 || overlap >= maxChunkLength) {
+    throw new Error("overlap must be a non-negative integer < maxChunkLength");
+  }
+  const chunks = [];
+  let truncated = false;
+  let cursor = 0;
+  const halfMax = Math.floor(maxChunkLength / 2);
+  while (cursor < text.length) {
+    const remaining = text.length - cursor;
+    if (remaining <= maxChunkLength) {
+      chunks.push(safeSlice(text, cursor, text.length));
+      break;
+    }
+    const windowEnd = cursor + maxChunkLength;
+    const minSplit = cursor + halfMax;
+    let splitPoint = -1;
+    const paraIdx = text.lastIndexOf("\n\n", windowEnd);
+    if (paraIdx >= minSplit && paraIdx + 2 <= windowEnd) {
+      splitPoint = paraIdx + 2;
+    }
+    if (splitPoint === -1) {
+      let lastTerm = -1;
+      for (let i = minSplit; i < windowEnd - 1; i++) {
+        const ch = text[i];
+        if ((ch === "." || ch === "!" || ch === "?") && /\s/.test(text[i + 1])) {
+          lastTerm = i + 2;
+        }
+      }
+      if (lastTerm !== -1 && lastTerm <= windowEnd) splitPoint = lastTerm;
+    }
+    if (splitPoint === -1) {
+      for (let i = windowEnd - 1; i >= minSplit; i--) {
+        if (/\s/.test(text[i])) {
+          splitPoint = i + 1;
+          break;
+        }
+      }
+    }
+    if (splitPoint === -1) {
+      truncated = true;
+      splitPoint = windowEnd;
+    }
+    chunks.push(safeSlice(text, cursor, splitPoint));
+    const next = Math.max(splitPoint - overlap, cursor + 1);
+    cursor = next;
+  }
+  return { chunks, truncated };
+}
+async function withConcurrency(tasks, limit) {
+  const results = new Array(tasks.length);
+  let index = 0;
+  let failed = false;
+  let firstError;
+  async function worker() {
+    while (index < tasks.length && !failed) {
+      const i = index++;
+      try {
+        results[i] = await tasks[i]();
+      } catch (e) {
+        if (!failed) {
+          failed = true;
+          firstError = e;
+        }
+        return;
+      }
+    }
+  }
+  const workerCount = tasks.length === 0 ? 0 : Math.min(Math.max(limit, 1), tasks.length);
+  await Promise.allSettled(Array.from({ length: workerCount }, worker));
+  if (failed) throw firstError;
+  return results;
+}
+function clip(value, max) {
+  if (typeof value !== "string") return "";
+  const s = value.trim();
+  return s.length <= max ? s : safeSlice(s, 0, max).trimEnd();
+}
+function validateTags(tags) {
+  if (!Array.isArray(tags)) return [];
+  return tags.filter((t) => typeof t === "string").map((t) => t.trim().toLowerCase()).filter((t) => t.length > 0 && t.length <= 40).slice(0, 6);
+}
+function validateFact(fact) {
+  if (typeof fact?.title !== "string" || typeof fact?.body !== "string") return null;
+  const title = clip(fact.title, 80);
+  const body = clip(fact.body, 800);
+  if (!title || !body) return null;
+  let confidence = fact.confidence;
+  if (confidence !== "certain" && confidence !== "tentative") confidence = "inferred";
+  return {
+    ...fact,
+    title,
+    body,
+    confidence,
+    tags: validateTags(fact.tags)
+  };
+}
+function validateTask(task) {
+  if (typeof task?.description !== "string") return null;
+  const description = clip(task.description, 200);
+  if (!description) return null;
+  let priority = task.priority;
+  if (typeof priority !== "number" || !isFinite(priority)) priority = 0;
+  priority = Math.max(0, Math.min(10, Math.round(priority)));
+  return {
+    ...task,
+    description,
+    priority
+  };
+}
+function normalizeSourceRef(value) {
+  if (typeof value !== "string") return null;
+  const cleaned = value.replace(/[^A-Za-z0-9._\- ]/g, "").trim().slice(0, 255);
+  return cleaned.length > 0 ? cleaned : null;
+}
+function normalizeSourceHash(value) {
+  if (typeof value !== "string") return null;
+  return /^[0-9a-f]{64}$/i.test(value) ? value.toLowerCase() : null;
+}
+function titleTokens(title) {
+  return new Set(title.toLowerCase().replace(/[^a-z0-9\s]/g, "").split(/\s+/).filter((t) => t.length >= 3));
+}
+function jaccardScore(a, b) {
+  if (a.size === 0 && b.size === 0) return 0;
+  const intersection = new Set([...a].filter((x) => b.has(x)));
+  const union = /* @__PURE__ */ new Set([...a, ...b]);
+  return intersection.size / union.size;
+}
+
+// src/utils/ids.ts
+function generateId(prefix = "") {
+  if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") {
+    return prefix + crypto.randomUUID().replace(/-/g, "").substring(0, 24);
+  }
+  if (typeof crypto !== "undefined" && typeof crypto.getRandomValues === "function") {
+    const bytes = new Uint8Array(16);
+    crypto.getRandomValues(bytes);
+    return prefix + Array.from(bytes).map((b) => b.toString(16).padStart(2, "0")).join("").substring(0, 24);
+  }
+  return prefix + Math.random().toString(36).substring(2, 15) + Math.random().toString(36).substring(2, 15);
+}
+
+// src/services/IngestionService.ts
+var IngestionService = class {
+  constructor(db, prefix, options, entryRepo, searchService, jobManager, embeddingService, promptService) {
+    this.db = db;
+    this.prefix = prefix;
+    this.options = options;
+    this.entryRepo = entryRepo;
+    this.searchService = searchService;
+    this.jobManager = jobManager;
+    this.embeddingService = embeddingService;
+    this.promptService = promptService ?? new PromptService(this.options.config?.prompts);
+  }
+  async ingestDocument(entityId, params) {
+    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 maxChunkLength = params.maxChunkLength ?? this.options.config?.maxChunkLength ?? 12e3;
+    const rawOverlap = params.chunkOverlap ?? this.options.config?.chunkOverlap ?? 400;
+    const chunkOverlap = Math.min(
+      Number.isFinite(rawOverlap) && rawOverlap >= 0 ? Math.floor(rawOverlap) : 400,
+      maxChunkLength - 1
+    );
+    const rawConcurrency = params.chunkConcurrency ?? this.options.config?.chunkConcurrency ?? 1;
+    const chunkConcurrency = Number.isFinite(rawConcurrency) && rawConcurrency >= 1 ? Math.floor(rawConcurrency) : 1;
+    if (typeof params.documentChunk !== "string") {
+      throw new Error(`documentChunk must be a string, received ${typeof params.documentChunk}`);
+    }
+    this.jobManager.acquireLock("ingest", entityId, sourceRef);
+    try {
+      const { chunks, truncated } = chunkText(params.documentChunk, maxChunkLength, chunkOverlap);
+      if (chunks.length === 0) return { truncated: false, chunks: 0 };
+      const chunkResults = await withConcurrency(
+        chunks.map((chunk) => async () => {
+          const { systemPrompt, userPrompt } = this.promptService.buildIngestPrompt(chunk, params.promptOverride);
+          const responseText = await this.options.llmProvider.generateText({ systemPrompt, userPrompt });
+          const result = parseJsonResponse(responseText);
+          return (Array.isArray(result.facts) ? result.facts : []).map(validateFact).filter((f) => f !== null);
+        }),
+        chunkConcurrency
+      );
+      const seen = /* @__PURE__ */ new Set();
+      const allValidFacts = [];
+      for (const facts of chunkResults) {
+        for (const fact of facts) {
+          const normalized = fact.title.trim().toLowerCase().replace(/\s+/g, " ");
+          if (!seen.has(normalized)) {
+            seen.add(normalized);
+            allValidFacts.push(fact);
+          }
+        }
+      }
+      const now = Date.now();
+      const insertedFacts = [];
+      const deletedSourceFactIds = [];
+      await this.db.withTransactionAsync(async (tx) => {
+        deletedSourceFactIds.push(...await this.entryRepo.findIdsBySource(entityId, sourceRef, null, tx, false));
+        await this.entryRepo.softDeleteBySource(entityId, tx, sourceRef, null);
+        for (const fact of allValidFacts) {
+          const id = generateId("fact_");
+          const wikiFact = {
+            id,
+            entity_id: entityId,
+            title: fact.title,
+            body: fact.body,
+            tags: fact.tags,
+            confidence: fact.confidence,
+            source_type: "immutable_document",
+            source_hash: sourceHash,
+            source_ref: sourceRef,
+            created_at: now,
+            updated_at: now,
+            last_accessed_at: null,
+            access_count: 0,
+            deleted_at: null
+          };
+          await this.entryRepo.upsert(wikiFact, tx);
+          insertedFacts.push({ id, entity_id: entityId, title: fact.title, body: fact.body, tags: JSON.stringify(fact.tags) });
+        }
+      });
+      await this.searchService.sync(entityId);
+      const uniqueDeletedSourceFactIds = Array.from(new Set(deletedSourceFactIds));
+      for (const factId of uniqueDeletedSourceFactIds) {
+        try {
+          await this.embeddingService.notifyEmbeddingPersisted(entityId, factId, null);
+        } catch (hookErr) {
+          console.warn(`[WikiMemory] onEmbeddingPersisted hook failed during ingest for ${factId}:`, hookErr);
+        }
+      }
+      for (const fact of insertedFacts) {
+        await this.embeddingService.embedFact(fact);
+      }
+      this.searchService.evictCache(entityId);
+      return { truncated, chunks: chunks.length };
+    } finally {
+      this.jobManager.releaseLock("ingest", entityId, sourceRef);
+    }
+  }
+};
+
+// src/services/MaintenanceService.ts
+var FUZZY_THRESHOLD = 0.5;
+var MIN_TOKENS_TO_QUALIFY = 3;
+var MaintenanceService = class {
+  constructor(db, prefix, options, entryRepo, taskRepo, eventRepo, metadataRepo, searchService, jobManager, embeddingService, promptService) {
+    this.db = db;
+    this.prefix = prefix;
+    this.options = options;
+    this.entryRepo = entryRepo;
+    this.taskRepo = taskRepo;
+    this.eventRepo = eventRepo;
+    this.metadataRepo = metadataRepo;
+    this.searchService = searchService;
+    this.jobManager = jobManager;
+    this.embeddingService = embeddingService;
+    this.promptService = promptService ?? new PromptService(this.options.config?.prompts);
+  }
+  async runPrune(entityId, options) {
+    this.jobManager.acquireLock("prune", entityId);
+    try {
+      const retainSoftDeletedFor = options?.retainSoftDeletedFor !== void 0 ? options.retainSoftDeletedFor : this.options.config?.pruneRetainSoftDeletedFor ?? 7;
+      const retainEventsFor = options?.retainEventsFor !== void 0 ? options.retainEventsFor : this.options.config?.pruneEventsAfter ?? 30;
+      const vacuum = options?.vacuum ?? false;
+      this._validatePruneDuration(retainSoftDeletedFor, "retainSoftDeletedFor");
+      this._validatePruneDuration(retainEventsFor, "retainEventsFor");
+      const now = Date.now();
+      let deletedEntries = 0;
+      let deletedTasks = 0;
+      let deletedEvents = 0;
+      if (retainSoftDeletedFor !== null) {
+        const cutoff = now - retainSoftDeletedFor * 864e5;
+        const entriesToDelete = await this.entryRepo.getPrunableMetadata(entityId, cutoff);
+        const succeeded = [];
+        let failure = null;
+        for (const row of entriesToDelete) {
+          try {
+            await this.embeddingService.notifyEmbeddingPersistedOrThrow(row.entity_id, row.id, null);
+            succeeded.push({ entity_id: row.entity_id, id: row.id });
+          } catch (err) {
+            failure = { factId: row.id, cause: err };
+            break;
+          }
+        }
+        const succeededIds = succeeded.map((r) => r.id);
+        await this.db.withTransactionAsync(async (tx) => {
+          if (succeededIds.length > 0) {
+            deletedEntries = await this.entryRepo.bulkDeletePruned(entityId, cutoff, succeededIds, tx);
+          }
+          deletedTasks = await this.taskRepo.bulkDeletePruned(entityId, cutoff, tx);
+        });
+        if (failure) {
+          await this.searchService.sync(entityId);
+          const remaining = entriesToDelete.length - succeeded.length - 1;
+          const isTimeout = failure.cause?.[HOOK_TIMEOUT_MARKER] === true;
+          if (isTimeout) {
+            throw new PrunePartialFailureError(
+              succeeded.length,
+              failure.factId,
+              remaining,
+              new Error("Deletion hook timed out"),
+              deletedTasks,
+              0
+            );
+          }
+          const errMsg = failure.cause?.message ?? "";
+          const isValidationError = errMsg.startsWith("Invalid deletionHookTimeoutMs");
+          const sanitizedCause = isValidationError ? failure.cause : this._sanitizeRankerError(failure.cause);
+          throw new PrunePartialFailureError(
+            succeeded.length,
+            failure.factId,
+            remaining,
+            sanitizedCause,
+            deletedTasks,
+            0
+          );
+        }
+      }
+      if (retainEventsFor !== null) {
+        const cutoff = now - retainEventsFor * 864e5;
+        const eventResult = await this.eventRepo.prune(entityId, cutoff);
+        deletedEvents = eventResult.changes;
+      }
+      if (vacuum) {
+        await this.metadataRepo.vacuum();
+      }
+      await this.searchService.sync(entityId);
+      return { entries: deletedEntries, tasks: deletedTasks, events: deletedEvents };
+    } finally {
+      this.jobManager.releaseLock("prune", entityId);
+    }
+  }
+  async runLibrarian(entityId, options) {
+    this.jobManager.acquireLock("librarian", entityId);
+    try {
+      await this.doRunLibrarian(entityId, options?.promptOverride);
+    } finally {
+      this.jobManager.releaseLock("librarian", entityId);
+    }
+  }
+  async runHeal(entityId, options) {
+    this.jobManager.acquireLock("heal", entityId);
+    try {
+      await this.doRunHeal(entityId, options?.promptOverride);
+    } finally {
+      this.jobManager.releaseLock("heal", entityId);
+    }
+  }
+  async runReembed(entityId, opts) {
+    const embedFn = this.options.llmProvider.embed;
+    if (!embedFn) return { embedded: 0, skipped: 0, failed: 0 };
+    const op = entityId ? "reembed" : "global_reembed";
+    this.jobManager.acquireLock(op, entityId ?? "*");
+    try {
+      const rows = await this.entryRepo.findAllForReembed(entityId);
+      this.searchService.evictCache(entityId);
+      const skipExisting = opts?.skipExisting ?? false;
+      let effectiveSkip = skipExisting;
+      if (skipExisting) {
+        const mismatchValue = await this.metadataRepo.getMeta("embedding_dimension_mismatch");
+        if (mismatchValue) {
+          if (entityId) {
+            const mismatchDim = parseInt(mismatchValue, 10);
+            const staleCount = await this.entryRepo.countStaleForEntity(entityId, mismatchDim);
+            if (staleCount > 0) effectiveSkip = false;
+          } else {
+            effectiveSkip = false;
+          }
+        }
+      }
+      let embedded = 0;
+      let skipped = 0;
+      let failed = 0;
+      try {
+        for (const row of rows) {
+          const existingBlob = row.embedding_blob;
+          const blobIsValid = !!existingBlob && existingBlob.byteLength > 0 && existingBlob.byteLength % 4 === 0;
+          if (effectiveSkip && blobIsValid) {
+            const vec = parseEmbedding(existingBlob, null);
+            if (vec !== null && vec.every((v) => Number.isFinite(v))) {
+              skipped++;
+              continue;
+            }
+          }
+          const success = await this.embeddingService.embedFact(row);
+          if (success) embedded++;
+          else failed++;
+        }
+        if (embedded > 0) {
+          await this.embeddingService.reconcileEmbeddingDimension();
+        }
+      } finally {
+        this.searchService.evictCache(entityId);
+      }
+      return { embedded, skipped, failed };
+    } finally {
+      this.jobManager.releaseLock(op, entityId ?? "*");
+    }
+  }
+  async forget(entityId, params) {
+    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");
+    }
+    this.jobManager.acquireLock("forget", entityId);
+    try {
+      const now = Date.now();
+      let deletedEntries = 0;
+      let deletedTasks = 0;
+      const deletedEntryIds = [];
+      await this.db.withTransactionAsync(async (tx) => {
+        if (params.clearAll) {
+          deletedEntryIds.push(...await this.entryRepo.findIdsBySource(entityId, null, null, tx, true));
+          deletedEntries = await this.entryRepo.bulkSoftDeleteByEntityId(entityId, tx);
+          deletedTasks = await this.taskRepo.bulkSoftDeleteByEntityId(entityId, tx);
+          await this.metadataRepo.updateCheckpoint(entityId, { memory: 0, heal: 0 }, tx);
+        } else {
+          const hasIdSelectors = params.entryId !== void 0 || params.taskId !== void 0;
+          const hasSourceSelectors = params.sourceRef !== void 0 || params.sourceHash !== void 0;
+          if (hasIdSelectors && hasSourceSelectors) {
+            throw new Error("forget() params are mutually exclusive: use entryId/taskId together, or sourceRef/sourceHash together, but not both in the same call");
+          }
+          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 (params.entryId) {
+            const entryId = await this.entryRepo.findIdById(params.entryId, entityId, tx);
+            if (entryId) deletedEntryIds.push(entryId);
+          }
+          if (sourceRef || sourceHash) {
+            deletedEntryIds.push(...await this.entryRepo.findIdsBySource(entityId, sourceRef, sourceHash, tx, true));
+          }
+          const entryPromise = params.entryId ? this.entryRepo.softDelete(params.entryId, entityId, tx).then((r) => r.changes > 0) : null;
+          const taskDeletedPromise = params.taskId ? this.taskRepo.softDeleteById(params.taskId, entityId, tx).then((r) => r.changes > 0) : null;
+          const refPromise = sourceRef || sourceHash ? this.entryRepo.softDeleteBySource(entityId, tx, sourceRef, sourceHash) : null;
+          const [entryResult, taskResult, refResult] = await Promise.all([
+            entryPromise ?? Promise.resolve(false),
+            taskDeletedPromise ?? Promise.resolve(false),
+            refPromise ?? Promise.resolve(0)
+          ]);
+          if (entryResult) deletedEntries++;
+          if (taskResult) deletedTasks++;
+          deletedEntries += refResult;
+        }
+      });
+      await this.searchService.sync(entityId);
+      const uniqueDeletedIds = Array.from(new Set(deletedEntryIds));
+      for (const factId of uniqueDeletedIds) {
+        try {
+          await this.embeddingService.notifyEmbeddingPersistedOrThrow(entityId, factId, null);
+        } catch (hookErr) {
+          const isTimeout = hookErr?.[HOOK_TIMEOUT_MARKER] === true;
+          if (isTimeout) {
+            throw new Error(`forget(${entityId}/${factId}) failed: ${hookErr.message}`);
+          }
+          const errMsg = hookErr?.message ?? "";
+          if (errMsg.startsWith("Invalid deletionHookTimeoutMs")) {
+            throw new Error(`forget(${entityId}/${factId}) failed: ${errMsg}`, { cause: hookErr });
+          }
+          throw new Error(`forget(${entityId}/${factId}) failed: ANN cleanup hook rejected`, { cause: this._sanitizeRankerError(hookErr) });
+        }
+      }
+      return { deleted: { entries: deletedEntries, tasks: deletedTasks } };
+    } finally {
+      this.jobManager.releaseLock("forget", entityId);
+    }
+  }
+  /** Core librarian pass (locks handled by {@link runLibrarian}). Package-internal orchestration hook. */
+  async doRunLibrarian(entityId, promptOverride) {
+    const events = await this.eventRepo.getRecent(entityId, 50);
+    const currentFactsRows = await this.entryRepo.findRecentByEntityId(entityId, 100);
+    const currentFacts = currentFactsRows.map((f) => {
+      const { embedding: _embedding, embedding_blob: _blob, ...rest } = f;
+      return {
+        ...rest,
+        tags: typeof rest.tags === "string" ? JSON.parse(rest.tags) : rest.tags
+      };
+    });
+    const { systemPrompt, userPrompt } = this.promptService.buildLibrarianPrompt(
+      events.reverse(),
+      currentFacts,
+      promptOverride
+    );
+    const responseText = await this.options.llmProvider.generateText({ systemPrompt, userPrompt });
+    const result = parseJsonResponse(responseText);
+    const facts = Array.isArray(result.facts) ? result.facts : [];
+    const tasks = Array.isArray(result.tasks) ? result.tasks : [];
+    const validFacts = facts.map(validateFact).filter((f) => f !== null);
+    const validTasks = tasks.map(validateTask).filter((t) => t !== null);
+    const now = Date.now();
+    const insertedFacts = [];
+    await this.db.withTransactionAsync(async (tx) => {
+      const factsForDedupe = await this.entryRepo.findRecentByEntityId(entityId, 100, tx);
+      for (const fact of validFacts) {
+        const newTokens = titleTokens(fact.title);
+        let skip = false;
+        if (newTokens.size >= MIN_TOKENS_TO_QUALIFY) {
+          for (const existing of factsForDedupe) {
+            if (existing.source_type !== "librarian_inferred") continue;
+            const existingTokens = titleTokens(existing.title);
+            if (existingTokens.size >= MIN_TOKENS_TO_QUALIFY) {
+              if (jaccardScore(newTokens, existingTokens) >= FUZZY_THRESHOLD) {
+                skip = true;
+                break;
+              }
+            }
+          }
+        }
+        if (skip) continue;
+        const id = generateId("fact_");
+        const factObj = {
+          id,
+          entity_id: entityId,
+          title: fact.title,
+          body: fact.body,
+          tags: fact.tags,
+          confidence: fact.confidence,
+          source_type: "librarian_inferred",
+          source_hash: null,
+          source_ref: null,
+          created_at: now,
+          updated_at: now,
+          last_accessed_at: null,
+          access_count: 0,
+          deleted_at: null
+        };
+        await this.entryRepo.upsert(factObj, tx);
+        insertedFacts.push({ id, entity_id: entityId, title: fact.title, body: fact.body, tags: JSON.stringify(fact.tags) });
+        factsForDedupe.push(factObj);
+      }
+      for (const task of validTasks) {
+        const id = generateId("task_");
+        const taskObj = {
+          id,
+          entity_id: entityId,
+          description: task.description,
+          status: "pending",
+          priority: task.priority,
+          created_at: now,
+          updated_at: now,
+          resolved_at: null,
+          deleted_at: null
+        };
+        await this.taskRepo.upsert(taskObj, tx);
+      }
+    });
+    await this.searchService.sync(entityId);
+    for (const fact of insertedFacts) {
+      await this.embeddingService.embedFact(fact);
+    }
+    this.searchService.evictCache(entityId);
+  }
+  /** Core heal pass (locks handled by {@link runHeal}). Package-internal orchestration hook. */
+  async doRunHeal(entityId, promptOverride) {
+    const now = Date.now();
+    const orphanAfterDays = this.options.config?.orphanAfterDays !== void 0 ? this.options.config?.orphanAfterDays : 30;
+    const staleInferredAfterDays = this.options.config?.staleInferredAfterDays !== void 0 ? this.options.config?.staleInferredAfterDays : 60;
+    const MS_PER_DAY = 24 * 60 * 60 * 1e3;
+    if (orphanAfterDays !== null && (typeof orphanAfterDays !== "number" || !Number.isFinite(orphanAfterDays) || orphanAfterDays < 0)) {
+      throw new Error("Invalid orphanAfterDays: must be a finite number >= 0 or null");
+    }
+    if (staleInferredAfterDays !== null && (typeof staleInferredAfterDays !== "number" || !Number.isFinite(staleInferredAfterDays) || staleInferredAfterDays < 0)) {
+      throw new Error("Invalid staleInferredAfterDays: must be a finite number >= 0 or null");
+    }
+    const orphanedIds = [];
+    await this.db.withTransactionAsync(async (tx) => {
+      if (orphanAfterDays !== null) {
+        const orphanThreshold = now - orphanAfterDays * MS_PER_DAY;
+        orphanedIds.push(...await this.entryRepo.markOrphaned(entityId, orphanThreshold, tx));
+      }
+      if (staleInferredAfterDays !== null) {
+        const staleThreshold = now - staleInferredAfterDays * MS_PER_DAY;
+        await this.entryRepo.downgradeStaleInferred(entityId, staleThreshold, tx);
+      }
+    });
+    for (const factId of orphanedIds) {
+      try {
+        await this.embeddingService.notifyEmbeddingPersisted(entityId, factId, null);
+      } catch (hookErr) {
+        console.warn(`[WikiMemory] onEmbeddingPersisted hook failed during heal orphan pass for ${factId}:`, hookErr);
+      }
+    }
+    const allFactsRows = await this.entryRepo.findAllByEntityId(entityId);
+    const allTasks = await this.taskRepo.findAllPending([entityId]);
+    const recentEvents = await this.eventRepo.getRecent(entityId, 20);
+    const healCandidates = allFactsRows.filter((f) => f.source_type !== "immutable_document");
+    const documentAnchors = allFactsRows.filter((f) => f.source_type === "immutable_document").map(({ id, title, source_ref }) => ({ id, title, source_ref }));
+    const healCandidatesForPrompt = healCandidates.map((f) => {
+      const { embedding: _embedding, embedding_blob: _blob, ...rest } = f;
+      return { ...rest, tags: typeof rest.tags === "string" ? JSON.parse(rest.tags) : rest.tags };
+    });
+    const { systemPrompt, userPrompt } = this.promptService.buildHealPrompt(
+      healCandidatesForPrompt,
+      documentAnchors,
+      allTasks,
+      recentEvents,
+      promptOverride
+    );
+    const responseText = await this.options.llmProvider.generateText({ systemPrompt, userPrompt });
+    const result = parseJsonResponse(responseText);
+    const mutableIds = new Set(healCandidates.map((f) => f.id));
+    const downgraded = Array.isArray(result.downgraded) ? result.downgraded : [];
+    const deleted = Array.isArray(result.deleted) ? result.deleted : [];
+    const newFacts = Array.isArray(result.newFacts) ? result.newFacts : [];
+    const safeDowngraded = Array.from(new Set(downgraded.filter((id) => mutableIds.has(id))));
+    const safeDeleted = Array.from(new Set(deleted.filter((id) => mutableIds.has(id))));
+    const validNewFacts = newFacts.map(validateFact).filter((f) => f !== null);
+    const insertedFacts = [];
+    const uniqueDeletedFactIds = Array.from(new Set(safeDeleted));
+    const healFactsForDedupe = [...healCandidates];
+    await this.db.withTransactionAsync(async (tx) => {
+      await this.entryRepo.downgradeByIds(safeDowngraded, entityId, tx);
+      await this.entryRepo.softDeleteByIds(safeDeleted, entityId, tx);
+      for (const fact of validNewFacts) {
+        const newTokens = titleTokens(fact.title);
+        let skip = false;
+        if (newTokens.size >= MIN_TOKENS_TO_QUALIFY) {
+          for (const existing of healFactsForDedupe) {
+            if (existing.source_type !== "librarian_inferred") continue;
+            const existingTokens = titleTokens(existing.title);
+            if (existingTokens.size >= MIN_TOKENS_TO_QUALIFY) {
+              if (jaccardScore(newTokens, existingTokens) >= FUZZY_THRESHOLD) {
+                skip = true;
+                break;
+              }
+            }
+          }
+        }
+        if (skip) continue;
+        const id = generateId("fact_");
+        const factObj = {
+          id,
+          entity_id: entityId,
+          title: fact.title,
+          body: fact.body,
+          tags: fact.tags,
+          confidence: fact.confidence,
+          source_type: "librarian_inferred",
+          source_hash: null,
+          source_ref: null,
+          created_at: now,
+          updated_at: now,
+          last_accessed_at: null,
+          access_count: 0,
+          deleted_at: null
+        };
+        await this.entryRepo.upsert(factObj, tx);
+        insertedFacts.push({ id, entity_id: entityId, title: fact.title, body: fact.body, tags: JSON.stringify(fact.tags) });
+        healFactsForDedupe.push(factObj);
+      }
+    });
+    await this.searchService.sync(entityId);
+    for (const factId of uniqueDeletedFactIds) {
+      try {
+        await this.embeddingService.notifyEmbeddingPersisted(entityId, factId, null);
+      } catch (hookErr) {
+        console.warn(`[WikiMemory] onEmbeddingPersisted hook failed during heal for ${factId}:`, hookErr);
+      }
+    }
+    for (const fact of insertedFacts) {
+      await this.embeddingService.embedFact(fact);
+    }
+    this.searchService.evictCache(entityId);
+  }
+  _validatePruneDuration(value, name) {
+    if (value !== null && value !== void 0 && (typeof value !== "number" || !isFinite(value) || value < 0)) {
+      throw new Error(`Invalid ${name}: must be a non-negative finite number or null`);
+    }
+  }
+  _sanitizeRankerError(err) {
+    return sanitizeRankerError(err, this.options.sanitizeRankerErrors);
+  }
+};
+
+// src/services/ImportExportService.ts
+var ImportExportService = class {
+  constructor(db, entryRepo, taskRepo, eventRepo, metadataRepo, searchService, jobManager, embeddingService) {
+    this.db = db;
+    this.entryRepo = entryRepo;
+    this.taskRepo = taskRepo;
+    this.eventRepo = eventRepo;
+    this.metadataRepo = metadataRepo;
+    this.searchService = searchService;
+    this.jobManager = jobManager;
+    this.embeddingService = embeddingService;
+  }
+  async exportDump(entityIds) {
+    let ids;
+    if (entityIds && entityIds.length > 0) {
+      ids = Array.from(new Set(entityIds));
+    } else {
+      ids = await this.metadataRepo.getDistinctEntityIds();
+    }
+    const entities = {};
+    const BATCH = 3;
+    for (let i = 0; i < ids.length; i += BATCH) {
+      const batch = ids.slice(i, i + BATCH);
+      const batchResults = await Promise.all(
+        batch.map(
+          async (id) => [
+            id,
+            await this.getFullBundle(id, { includeBlobs: true })
+          ]
+        )
+      );
+      for (const [id, bundle] of batchResults) {
+        entities[id] = bundle;
+      }
+    }
+    return { generatedAt: Date.now(), entities };
+  }
+  async importDump(dump, opts) {
+    const merge = opts?.merge ?? false;
+    const entityIds = Object.keys(dump.entities);
+    this.jobManager.acquireImportLocks(entityIds);
+    try {
+      await this.assertNoLegacySourceTypes();
+      for (const [entityId, bundle] of Object.entries(dump.entities)) {
+        await this.doImportEntity(entityId, bundle, merge);
+      }
+    } finally {
+      this.jobManager.releaseImportLocks(entityIds);
+    }
+  }
+  async getFullBundle(entityId, opts) {
+    const [factsRaw, tasks, events] = await Promise.all([
+      opts?.includeBlobs ? this.entryRepo.findAllByEntityIdWithBlobs(entityId) : this.entryRepo.findAllByEntityId(entityId),
+      this.taskRepo.findAllByEntityId(entityId),
+      this.eventRepo.getByEntityId(entityId, opts?.maxEvents)
+    ]);
+    const facts = factsRaw.map((f) => {
+      const {
+        embedding: _embedding,
+        embedding_blob,
+        ...rest
+      } = f;
+      const safeBlobCopy = opts?.includeBlobs && embedding_blob ? (() => {
+        const c = new ArrayBuffer(embedding_blob.byteLength);
+        new Uint8Array(c).set(embedding_blob);
+        return new Uint8Array(c);
+      })() : void 0;
+      const factBase = safeBlobCopy ? { ...rest, embedding_blob: safeBlobCopy } : rest;
+      return {
+        ...factBase,
+        tags: typeof factBase.tags === "string" ? JSON.parse(factBase.tags) : factBase.tags
+      };
+    });
+    return { facts, tasks, events };
+  }
+  /** Single-entity import transaction + post-processing; package-internal hook for tests. */
+  async doImportEntity(entityId, bundle, merge) {
+    const upsertedFactIds = /* @__PURE__ */ new Set();
+    const upsertedDeletedFactIds = /* @__PURE__ */ new Set();
+    const factsWithPreservedBlob = /* @__PURE__ */ new Map();
+    const preservedBlobDims = /* @__PURE__ */ new Set();
+    const softDeletedFactIds = [];
+    await this.db.withTransactionAsync(async (tx) => {
+      if (!merge) {
+        const deletedLiveFactIds = await this.entryRepo.findIdsBySource(
+          entityId,
+          null,
+          null,
+          tx,
+          false
+        );
+        softDeletedFactIds.push(...deletedLiveFactIds);
+        await this.entryRepo.bulkSoftDeleteByEntityId(entityId, tx);
+        await this.taskRepo.bulkSoftDeleteByEntityId(entityId, tx);
+        await this.metadataRepo.deleteCheckpoint(entityId, tx);
+      }
+      const factIds = bundle.facts.map((fact) => fact.id);
+      const existingFactsById = /* @__PURE__ */ new Map();
+      const existingFacts = await this.entryRepo.findExistingMetadataByIds(
+        factIds,
+        tx
+      );
+      for (const existingFact of existingFacts) {
+        existingFactsById.set(existingFact.id, existingFact);
+      }
+      for (const fact of bundle.facts) {
+        const sourceType = this._normalizeImportedSourceType(
+          String(fact.source_type),
+          {
+            entityId,
+            factId: fact.id
+          }
+        );
+        const safeUpdatedAt = Number.isFinite(fact.updated_at) ? fact.updated_at : 0;
+        const existing = existingFactsById.get(fact.id);
+        const rawBlobRaw = fact.embedding_blob;
+        let rawBlob = null;
+        if (rawBlobRaw instanceof Uint8Array) {
+          rawBlob = rawBlobRaw;
+        } else if (rawBlobRaw !== null && rawBlobRaw !== void 0 && typeof rawBlobRaw === "object") {
+          const obj = rawBlobRaw;
+          if (obj["type"] === "Buffer" && Array.isArray(obj["data"])) {
+            rawBlob = new Uint8Array(obj["data"]);
+          } else if (!Array.isArray(rawBlobRaw)) {
+            const entries = Object.keys(obj);
+            if (entries.length > 0 && entries.every((k) => /^\d+$/.test(k))) {
+              const len = entries.length;
+              rawBlob = new Uint8Array(len);
+              for (let i = 0; i < len; i++)
+                rawBlob[i] = obj[String(i)] ?? 0;
+            }
+          }
+        }
+        let blobData = null;
+        if (rawBlob !== null && rawBlob.byteLength > 0 && rawBlob.byteLength % 4 === 0) {
+          const copy = new ArrayBuffer(rawBlob.byteLength);
+          const alignedBlob = new Uint8Array(copy);
+          alignedBlob.set(rawBlob);
+          const floats = new Float32Array(copy, 0, rawBlob.byteLength / 4);
+          let allFinite = true;
+          for (let i = 0; i < floats.length; i++) {
+            if (!isFinite(floats[i])) {
+              allFinite = false;
+              break;
+            }
+          }
+          if (allFinite) {
+            blobData = alignedBlob;
+          }
+        }
+        if (existing) {
+          if (existing.entity_id !== entityId) {
+            this._warnCrossEntityCollision(
+              "entry",
+              fact.id,
+              existing.entity_id,
+              entityId
+            );
+            continue;
+          }
+          if (merge && safeUpdatedAt <= existing.updated_at) continue;
+        }
+        const factObj = {
+          id: fact.id,
+          entity_id: entityId,
+          title: fact.title,
+          body: fact.body,
+          tags: Array.isArray(fact.tags) ? fact.tags : [],
+          confidence: fact.confidence,
+          source_type: sourceType,
+          source_hash: fact.source_hash,
+          source_ref: fact.source_ref,
+          created_at: fact.created_at,
+          updated_at: safeUpdatedAt,
+          last_accessed_at: fact.last_accessed_at,
+          access_count: fact.access_count,
+          deleted_at: fact.deleted_at,
+          embedding_blob: blobData ?? void 0
+        };
+        await this.entryRepo.upsertForImport(factObj, tx);
+        if (blobData != null) {
+          factsWithPreservedBlob.set(fact.id, blobData);
+          if (!fact.deleted_at) preservedBlobDims.add(blobData.byteLength / 4);
+        }
+        existingFactsById.set(fact.id, {
+          id: fact.id,
+          entity_id: entityId,
+          updated_at: safeUpdatedAt
+        });
+        upsertedFactIds.add(fact.id);
+        if (fact.deleted_at) upsertedDeletedFactIds.add(fact.id);
+      }
+      const taskIds = bundle.tasks.map((task) => task.id);
+      const existingTasksById = /* @__PURE__ */ new Map();
+      const existingTasks = await this.taskRepo.findExistingMetadataByIds(
+        taskIds,
+        tx
+      );
+      for (const existingTask of existingTasks) {
+        existingTasksById.set(existingTask.id, existingTask);
+      }
+      for (const task of bundle.tasks) {
+        const safeUpdatedAt = Number.isFinite(task.updated_at) ? task.updated_at : 0;
+        const existing = existingTasksById.get(task.id);
+        if (existing) {
+          if (existing.entity_id !== entityId) {
+            this._warnCrossEntityCollision(
+              "task",
+              task.id,
+              existing.entity_id,
+              entityId
+            );
+            continue;
+          }
+          if (merge && safeUpdatedAt <= existing.updated_at) continue;
+        }
+        await this.taskRepo.upsertForImport(
+          {
+            id: task.id,
+            entity_id: entityId,
+            description: task.description,
+            status: task.status,
+            priority: task.priority,
+            created_at: task.created_at,
+            updated_at: safeUpdatedAt,
+            resolved_at: task.resolved_at,
+            deleted_at: task.deleted_at
+          },
+          tx,
+          safeUpdatedAt
+        );
+        existingTasksById.set(task.id, {
+          id: task.id,
+          entity_id: entityId,
+          updated_at: safeUpdatedAt
+        });
+      }
+      for (const event of bundle.events) {
+        await this.eventRepo.addIgnoreDuplicate(
+          {
+            id: event.id,
+            entity_id: entityId,
+            event_type: event.event_type,
+            summary: event.summary,
+            related_entry_id: event.related_entry_id ?? null,
+            created_at: event.created_at
+          },
+          tx
+        );
+      }
+    });
+    await this.searchService.sync(entityId);
+    for (const fact of bundle.facts) {
+      if (!fact.deleted_at && upsertedFactIds.has(fact.id) && !factsWithPreservedBlob.has(fact.id)) {
+        const embedded = await this.embeddingService.embedFact({
+          id: fact.id,
+          entity_id: entityId,
+          title: fact.title,
+          body: fact.body,
+          tags: Array.isArray(fact.tags) || typeof fact.tags === "string" ? fact.tags : []
+        });
+        if (!embedded) {
+          await this.embeddingService.notifyEmbeddingPersisted(entityId, fact.id, null);
+        }
+      }
+    }
+    for (const fact of bundle.facts) {
+      const blobData = factsWithPreservedBlob.get(fact.id);
+      if (blobData && !fact.deleted_at && upsertedFactIds.has(fact.id)) {
+        try {
+          const float32Vector = new Float32Array(
+            blobData.buffer,
+            blobData.byteOffset,
+            blobData.byteLength / 4
+          );
+          await this.embeddingService.notifyEmbeddingPersisted(
+            entityId,
+            fact.id,
+            float32Vector
+          );
+        } catch (hookErr) {
+          console.warn(
+            `[WikiMemory] onEmbeddingPersisted hook failed for preserved-blob fact ${fact.id}:`,
+            hookErr
+          );
+        }
+      }
+    }
+    for (const factId of softDeletedFactIds) {
+      if (!upsertedFactIds.has(factId) || upsertedDeletedFactIds.has(factId)) {
+        try {
+          await this.embeddingService.notifyEmbeddingPersisted(
+            entityId,
+            factId,
+            null
+          );
+        } catch (hookErr) {
+          console.warn(
+            `[WikiMemory] onEmbeddingPersisted(vector=null) hook failed for soft-deleted fact ${factId}:`,
+            hookErr
+          );
+        }
+      }
+    }
+    try {
+      const canonicalDimValue = await this.metadataRepo.getMeta(
+        "embedding_dimension"
+      );
+      const canonicalDim = canonicalDimValue ? parseInt(canonicalDimValue, 10) : null;
+      if (preservedBlobDims.size === 1) {
+        const preservedDim = [...preservedBlobDims][0];
+        if (canonicalDim === null || canonicalDim === preservedDim) {
+          await this.embeddingService.storeEmbeddingDimension(preservedDim);
+          const staleMismatchValue = await this.metadataRepo.getMeta(
+            "embedding_dimension_mismatch"
+          );
+          if (staleMismatchValue && parseInt(staleMismatchValue, 10) !== preservedDim) {
+            await this.metadataRepo.setMeta(
+              "embedding_dimension_mismatch",
+              String(preservedDim),
+              this.db
+            );
+          }
+          await this.embeddingService.reconcileEmbeddingDimension();
+        } else {
+          await this.metadataRepo.setMeta(
+            "embedding_dimension_mismatch",
+            String(canonicalDim),
+            this.db
+          );
+        }
+      } else if (preservedBlobDims.size > 1) {
+        if (canonicalDim === null) {
+          const sortedPreservedBlobDims = [...preservedBlobDims].sort(
+            (a, b) => a - b
+          );
+          await this.embeddingService.storeEmbeddingDimension(
+            sortedPreservedBlobDims[0]
+          );
+          await this.metadataRepo.setMeta(
+            "embedding_dimension_mismatch",
+            String(sortedPreservedBlobDims[0]),
+            this.db
+          );
+        } else {
+          await this.metadataRepo.setMeta(
+            "embedding_dimension_mismatch",
+            String(canonicalDim),
+            this.db
+          );
+        }
+      }
+    } finally {
+      this.searchService.evictCache(entityId);
+    }
+  }
+  _warnCrossEntityCollision(type, id, existingEntityId, targetEntityId) {
+    console.warn(
+      `[WikiMemory] importDump: ${type} id "${id}" already belongs to entity "${existingEntityId}"; skipping for entity "${targetEntityId}"`
+    );
+  }
+  _normalizeImportedSourceType(raw, ctx) {
+    if (raw === "user_document") return "immutable_document";
+    if (raw === "agent_inferred") return "librarian_inferred";
+    const allowed = [
+      "user_stated",
+      "librarian_inferred",
+      "user_confirmed",
+      "immutable_document"
+    ];
+    if (allowed.includes(raw))
+      return raw;
+    const where = ctx !== void 0 ? ` for entity "${ctx.entityId}" fact "${ctx.factId}"` : "";
+    throw new Error(
+      `importDump: invalid source_type "${raw}"${where} (expected one of: ${allowed.join(", ")}, or legacy aliases user_document / agent_inferred)`
+    );
+  }
+  async assertNoLegacySourceTypes() {
+    if (!await this.entryRepo.hasLegacySourceTypes()) return;
+    const count = await this.entryRepo.countLegacySourceTypes();
+    throw new Error(
+      `Database contains ${count} entries with legacy source_type values ('user_document' or 'agent_inferred'). These enum values were renamed in this release. Running without migration would allow legacy 'user_document' facts to bypass immutability guards, causing data corruption.
+
+${this.entryRepo.getLegacyMigrationSQL()}
+
+After running the migration SQL, restart your application.`
+    );
+  }
+};
+
+// src/services/EmbeddingService.ts
+var EmbeddingService = class {
+  constructor(db, options, entryRepo, metadataRepo) {
+    this.db = db;
+    this.options = options;
+    this.entryRepo = entryRepo;
+    this.metadataRepo = metadataRepo;
+  }
+  async storeEmbeddingDimension(dim) {
+    const existing = await this.metadataRepo.getMeta("embedding_dimension");
+    if (existing) {
+      const storedDim = parseInt(existing, 10);
+      if (storedDim !== dim) {
+        console.warn(
+          `[WikiMemory] Embedding dimension mismatch: stored ${storedDim}, got ${dim}. Call runReembed() to rebuild embeddings with the new model.`
+        );
+        await this.metadataRepo.setMeta("embedding_dimension_mismatch", String(dim), this.db);
+      }
+    } else {
+      await this.metadataRepo.setMeta("embedding_dimension", String(dim), this.db);
+    }
+  }
+  /** Promotes embedding_dimension_mismatch to canonical embedding_dimension when safe. */
+  async reconcileEmbeddingDimension() {
+    const mismatchValue = await this.metadataRepo.getMeta("embedding_dimension_mismatch");
+    if (!mismatchValue) return;
+    const newDim = parseInt(mismatchValue, 10);
+    const residualCount = await this.entryRepo.countStaleEmbeddings(newDim);
+    if (residualCount === 0) {
+      await this.metadataRepo.setMeta("embedding_dimension", mismatchValue, this.db);
+      await this.metadataRepo.clearDimensionMismatch(this.db);
+    }
+  }
+  async embedFact(fact) {
+    const embedFn = this.options.llmProvider.embed;
+    if (!embedFn) return false;
+    let tagsStr;
+    if (Array.isArray(fact.tags)) {
+      tagsStr = fact.tags.join(" ");
+    } else {
+      try {
+        const parsed = JSON.parse(fact.tags);
+        tagsStr = Array.isArray(parsed) ? parsed.join(" ") : fact.tags;
+      } catch {
+        tagsStr = fact.tags;
+      }
+    }
+    const text = `${fact.title} ${fact.body} ${tagsStr}`.trim();
+    try {
+      const vector = await embedFn(text);
+      if (vector.length === 0 || !vector.every((v) => typeof v === "number" && isFinite(v))) {
+        console.warn(`[WikiMemory] embedFact: embed() returned an invalid vector for ${fact.id}; skipping.`);
+        return false;
+      }
+      const float32Vector = new Float32Array(vector);
+      let hasNonFinite = false;
+      for (let i = 0; i < float32Vector.length; i++) {
+        if (!isFinite(float32Vector[i])) {
+          hasNonFinite = true;
+          break;
+        }
+      }
+      if (hasNonFinite) {
+        console.warn(`[WikiMemory] embedFact: embed() returned values that overflow float32 for ${fact.id}; skipping.`);
+        return false;
+      }
+      await this.storeEmbeddingDimension(float32Vector.length);
+      const blob = new Uint8Array(float32Vector.buffer);
+      await this.entryRepo.updateEmbeddingBlob(fact.id, blob);
+      try {
+        await this.notifyEmbeddingPersisted(fact.entity_id, fact.id, float32Vector);
+      } catch (hookErr) {
+        console.warn(`[WikiMemory] onEmbeddingPersisted hook failed for ${fact.id}:`, hookErr);
+      }
+      return true;
+    } catch (err) {
+      console.warn(`[WikiMemory] embedFact failed for ${fact.id}:`, err);
+      return false;
+    }
+  }
+  async notifyEmbeddingPersisted(entityId, factId, vector) {
+    if (!this.options.vectorRanker?.onEmbeddingPersisted) return;
+    const vectorCopy = vector ? vector.slice() : null;
+    await this.options.vectorRanker.onEmbeddingPersisted({
+      entityId,
+      factId,
+      vector: vectorCopy
+    });
+  }
+  async notifyEmbeddingPersistedOrThrow(entityId, factId, vector) {
+    if (!this.options.vectorRanker?.onEmbeddingPersisted) return;
+    if (this.options.forceDeleteIgnoreRankerHook === true) return;
+    const vectorCopy = vector ? vector.slice() : null;
+    const rawTimeout = this.options.deletionHookTimeoutMs ?? 3e4;
+    if (typeof rawTimeout !== "number" || !Number.isFinite(rawTimeout) || rawTimeout <= 0) {
+      throw new Error("Invalid deletionHookTimeoutMs: must be a positive finite number");
+    }
+    const timeoutMs = rawTimeout;
+    let timeoutHandle;
+    const timeoutPromise = new Promise((_, reject) => {
+      timeoutHandle = setTimeout(() => {
+        const timeoutError = new Error(`onEmbeddingPersisted timed out after ${timeoutMs}ms`);
+        timeoutError[HOOK_TIMEOUT_MARKER] = true;
+        reject(timeoutError);
+      }, timeoutMs);
+    });
+    const hookPromise = Promise.resolve().then(
+      () => this.options.vectorRanker.onEmbeddingPersisted({
+        entityId,
+        factId,
+        vector: vectorCopy
+      })
+    );
+    try {
+      await Promise.race([hookPromise, timeoutPromise]);
+    } catch (err) {
+      hookPromise.catch(() => {
+      });
+      throw err;
+    } finally {
+      if (timeoutHandle) clearTimeout(timeoutHandle);
+    }
+  }
+};
+
+// src/readOptions.ts
+function normalizeEntityIds(entityId) {
+  const input = Array.isArray(entityId) ? entityId : [entityId];
+  const seen = /* @__PURE__ */ new Set();
+  const normalized = [];
+  for (const id of input) {
+    if (seen.has(id)) continue;
+    seen.add(id);
+    normalized.push(id);
+  }
+  return normalized;
+}
+function sanitizeTierWeights(entityIds, tierWeights) {
+  if (tierWeights === void 0) return void 0;
+  const sanitized = /* @__PURE__ */ Object.create(null);
+  for (const entityId of entityIds) {
+    const raw = tierWeights[entityId];
+    if (raw === void 0 || !Number.isFinite(raw)) {
+      sanitized[entityId] = 1;
+    } else {
+      sanitized[entityId] = Math.max(0, raw);
+    }
+  }
+  return sanitized;
+}
+function applyTierWeight(score, entityId, sanitizedTierWeights) {
+  const weight = sanitizedTierWeights?.[entityId] ?? 1;
+  if (weight === 0) return -Infinity;
+  return score * weight;
+}
+function shouldExposeReadMetadata(entityId) {
+  return Array.isArray(entityId);
+}
+
+// src/services/RetrievalService.ts
+var RetrievalService = class {
+  constructor(options, entryRepo, taskRepo, eventRepo, metadataRepo, searchService) {
+    this.options = options;
+    this.entryRepo = entryRepo;
+    this.taskRepo = taskRepo;
+    this.eventRepo = eventRepo;
+    this.metadataRepo = metadataRepo;
+    this.searchService = searchService;
+  }
+  async read(entityId, query, options) {
+    const config = this.options.config;
+    const entityIds = normalizeEntityIds(entityId);
+    const sanitizedTierWeights = shouldExposeReadMetadata(entityId) ? sanitizeTierWeights(entityIds, options?.tierWeights) : void 0;
+    const exposeMetadata = shouldExposeReadMetadata(entityId);
+    if (entityIds.length === 0) {
+      const empty = { facts: [], tasks: [], events: [] };
+      if (exposeMetadata) {
+        empty.metadata = { query, entityIds: [] };
+        if (sanitizedTierWeights && Object.keys(sanitizedTierWeights).length > 0) empty.metadata.tierWeights = sanitizedTierWeights;
+      }
+      return empty;
+    }
+    const MAX_ENTITY_IDS = 100;
+    if (entityIds.length > MAX_ENTITY_IDS) {
+      throw new RangeError(`read() accepts at most ${MAX_ENTITY_IDS} entity IDs; received ${entityIds.length}`);
+    }
+    const nullByteId = entityIds.find((id) => id.includes("\0"));
+    if (nullByteId !== void 0) {
+      throw new TypeError(`entity_id values must not contain the null byte (\\x00); got "${nullByteId}"`);
+    }
+    const rawMaxResults = options?.maxResults ?? config?.maxResults ?? config?.maxFtsResults ?? 10;
+    const maxResults = Number.isFinite(rawMaxResults) ? Math.max(0, Math.trunc(rawMaxResults)) : 10;
+    const rawPreFilterLimit = options?.preFilterLimit === null ? void 0 : options?.preFilterLimit ?? config?.preFilterLimit;
+    const effectivePreFilterLimit = rawPreFilterLimit === void 0 ? void 0 : Number.isFinite(rawPreFilterLimit) ? Math.max(0, Math.trunc(rawPreFilterLimit)) : void 0;
+    const hybridWeight = options?.hybridWeight ?? config?.hybridWeight;
+    const weight = hybridWeight !== void 0 && !Number.isNaN(hybridWeight) ? Math.max(0, Math.min(1, hybridWeight)) : void 0;
+    const skipEmbed = weight === 0;
+    const embedFn = this.options.llmProvider.embed;
+    const trimmedQuery = query.trim();
+    let facts = [];
+    let scoreByFactId;
+    if (maxResults === 0) ; else if (trimmedQuery) {
+      let usedEmbed = false;
+      const scoredEntityIds = this._filterScoredEntities(entityIds, sanitizedTierWeights, options?.includeZeroWeightEntities);
+      if (scoredEntityIds.length === 0) {
+        usedEmbed = true;
+      } else if (!skipEmbed && embedFn) {
+        let rankerShouldRethrow = false;
+        let pendingRankerFallbackError;
+        try {
+          const queryVec = await embedFn(trimmedQuery);
+          if (queryVec.length === 0 || !queryVec.every((v) => typeof v === "number" && isFinite(v))) {
+            throw new Error(
+              "embed() returned an empty or non-finite vector. Falling back to keyword search."
+            );
+          }
+          const storedDimValue = await this.metadataRepo.getMeta("embedding_dimension");
+          if (storedDimValue) {
+            const storedDim = parseInt(storedDimValue, 10);
+            if (storedDim !== queryVec.length) {
+              throw new Error(
+                `Embedding dimension mismatch: stored ${storedDim}, query has ${queryVec.length}. Call runReembed() to rebuild embeddings with the new model.`
+              );
+            }
+          }
+          const mismatchedCount = await this.entryRepo.countDimensionMismatched(scoredEntityIds, queryVec.length);
+          if (mismatchedCount > 0) {
+            throw new Error(
+              `Some facts have embeddings that do not match the current model dimension. Call runReembed() to rebuild all embeddings consistently.`
+            );
+          }
+          const useRanker = Boolean(this.options.vectorRanker);
+          let candidateRows;
+          let populateCache = entityIds.length === 1;
+          let miniSearchScores;
+          if (effectivePreFilterLimit !== void 0) {
+            populateCache = false;
+            const preResults = this.searchService.searchKeyword(trimmedQuery, scoredEntityIds, Number.MAX_SAFE_INTEGER);
+            if (preResults.length === 0) {
+              candidateRows = null;
+            } else {
+              const topKResults = preResults.slice(0, effectivePreFilterLimit);
+              if (topKResults.length === 0) {
+                candidateRows = null;
+              } else {
+                const topKIds = topKResults.map((r) => r.id);
+                if (useRanker) {
+                  candidateRows = await this.entryRepo.findMetadataByIds(topKIds);
+                } else {
+                  candidateRows = await this.entryRepo.findWithEmbeddingsByIds(topKIds);
+                }
+                if (weight !== void 0 && weight < 1) {
+                  const maxMsScore = Math.max(1, topKResults[0]?.score ?? 1);
+                  miniSearchScores = new Map(topKResults.map((r) => [r.id, r.score / maxMsScore]));
+                }
+              }
+            }
+          } else {
+            if (useRanker) {
+              candidateRows = await this.entryRepo.findMetadataByEntityIds(scoredEntityIds);
+            } else {
+              candidateRows = await this.entryRepo.findWithEmbeddingsByEntityIds(scoredEntityIds);
+            }
+            if (weight !== void 0 && weight < 1) {
+              miniSearchScores = this.searchService.getMiniSearchScores(trimmedQuery, scoredEntityIds);
+            }
+          }
+          if (candidateRows === null) {
+            usedEmbed = true;
+          } else {
+            const entityCacheKey = entityIds.length === 1 ? entityIds[0] : entityIds.join("\0");
+            let scored;
+            if (useRanker) {
+              const candidateRowsByEntity = /* @__PURE__ */ new Map();
+              for (const row of candidateRows) {
+                const rows = candidateRowsByEntity.get(row.entity_id) ?? [];
+                rows.push(row);
+                candidateRowsByEntity.set(row.entity_id, rows);
+              }
+              try {
+                const rankerResultsByEntity = await Promise.all(
+                  scoredEntityIds.filter((id) => (candidateRowsByEntity.get(id)?.length ?? 0) > 0).map(async (scopedEntityId) => {
+                    const rowsForEntity = candidateRowsByEntity.get(scopedEntityId) ?? [];
+                    const candidateIds = effectivePreFilterLimit !== void 0 ? rowsForEntity.map((row) => row.id) : void 0;
+                    const ranked = await this._rankWithVectorRanker({
+                      entityId: scopedEntityId,
+                      queryVec,
+                      candidateIds,
+                      candidateRows: rowsForEntity,
+                      weight,
+                      miniSearchScores,
+                      limit: Math.max(maxResults * 2, maxResults + 50)
+                    });
+                    return ranked.map((row) => ({ ...row, entity_id: scopedEntityId }));
+                  })
+                );
+                scored = rankerResultsByEntity.flat();
+                const scoredIds = new Set(scored.map((s) => s.id));
+                const metadataById = new Map(
+                  candidateRows.filter((row) => scoredIds.has(row.id)).map((row) => [row.id, row])
+                );
+                scored = scored.map((row) => {
+                  const metadata = metadataById.get(row.id);
+                  return {
+                    ...row,
+                    updated_at: metadata?.updated_at ?? null,
+                    access_count: metadata?.access_count ?? null
+                  };
+                });
+                const isHybrid = weight !== void 0 && weight < 1;
+                const maxBackfill = isHybrid ? maxResults : Math.max(0, maxResults - scored.length);
+                if (maxBackfill > 0) {
+                  if (isHybrid) {
+                    const topK = [];
+                    for (const row of candidateRows) {
+                      if (scoredIds.has(row.id)) continue;
+                      const kwScore = miniSearchScores?.get(row.id) ?? 0;
+                      const candidate = { row, kwScore };
+                      if (topK.length < maxBackfill) {
+                        let insertIdx = topK.length;
+                        for (let i = 0; i < topK.length; i++) {
+                          const cmp = this._compareScoredRows(
+                            {
+                              id: candidate.row.id,
+                              score: candidate.kwScore,
+                              updated_at: candidate.row.updated_at,
+                              access_count: candidate.row.access_count
+                            },
+                            {
+                              id: topK[i].row.id,
+                              score: topK[i].kwScore,
+                              updated_at: topK[i].row.updated_at,
+                              access_count: topK[i].row.access_count
+                            }
+                          );
+                          if (cmp < 0) {
+                            insertIdx = i;
+                            break;
+                          }
+                        }
+                        topK.splice(insertIdx, 0, candidate);
+                      } else {
+                        const cmpWorst = this._compareScoredRows(
+                          {
+                            id: candidate.row.id,
+                            score: candidate.kwScore,
+                            updated_at: candidate.row.updated_at,
+                            access_count: candidate.row.access_count
+                          },
+                          {
+                            id: topK[maxBackfill - 1].row.id,
+                            score: topK[maxBackfill - 1].kwScore,
+                            updated_at: topK[maxBackfill - 1].row.updated_at,
+                            access_count: topK[maxBackfill - 1].row.access_count
+                          }
+                        );
+                        if (cmpWorst < 0) {
+                          let insertIdx = maxBackfill - 1;
+                          for (let i = 0; i < topK.length; i++) {
+                            const cmp = this._compareScoredRows(
+                              {
+                                id: candidate.row.id,
+                                score: candidate.kwScore,
+                                updated_at: candidate.row.updated_at,
+                                access_count: candidate.row.access_count
+                              },
+                              {
+                                id: topK[i].row.id,
+                                score: topK[i].kwScore,
+                                updated_at: topK[i].row.updated_at,
+                                access_count: topK[i].row.access_count
+                              }
+                            );
+                            if (cmp < 0) {
+                              insertIdx = i;
+                              break;
+                            }
+                          }
+                          topK.splice(insertIdx, 0, candidate);
+                          topK.pop();
+                        }
+                      }
+                    }
+                    for (const { row, kwScore } of topK) {
+                      scored.push({
+                        id: row.id,
+                        entity_id: row.entity_id,
+                        score: (1 - weight) * kwScore,
+                        updated_at: row.updated_at,
+                        access_count: row.access_count
+                      });
+                    }
+                  } else {
+                    const omitted = [];
+                    for (const row of candidateRows) {
+                      if (scoredIds.has(row.id)) continue;
+                      omitted.push({ id: row.id, entity_id: row.entity_id, score: -2, updated_at: row.updated_at, access_count: row.access_count });
+                    }
+                    if (omitted.length > 0) {
+                      this._tieBreakSort(omitted);
+                      scored.push(...omitted.slice(0, maxBackfill));
+                    }
+                  }
+                }
+              } catch (rankerErr) {
+                const rankerError = rankerErr instanceof Error ? rankerErr : new Error(String(rankerErr));
+                const policy = this.options.vectorRankerFallback ?? "js-cosine";
+                this.options.onVectorRankerFallback?.({
+                  error: this._sanitizeRankerError(rankerError),
+                  policy
+                });
+                if (policy === "throw") {
+                  rankerShouldRethrow = true;
+                  throw rankerError;
+                } else if (policy === "js-cosine") {
+                  let fallbackRows = candidateRows;
+                  if (fallbackRows && fallbackRows.length > 0 && !("embedding_blob" in fallbackRows[0])) {
+                    const rowIds = fallbackRows.map((r) => r.id);
+                    const embeddingRows = await this.entryRepo.findEmbeddingsByIds(rowIds);
+                    const embeddingsMap = new Map(embeddingRows.map((row) => [row.id, row]));
+                    fallbackRows = fallbackRows.map((r) => ({
+                      ...r,
+                      embedding_blob: embeddingsMap.get(r.id)?.embedding_blob ?? null,
+                      embedding: embeddingsMap.get(r.id)?.embedding ?? null
+                    }));
+                  }
+                  scored = await this.searchService.rankSemantic({
+                    entityId: entityCacheKey,
+                    queryVec,
+                    candidateRows: fallbackRows,
+                    weight,
+                    miniSearchScores,
+                    populateCache,
+                    limit: fallbackRows.length,
+                    skipSort: true
+                    // read() re-sorts after applying tier weights
+                  });
+                } else if (policy === "keyword") {
+                  const keywordOversampledLimit = Math.max(maxResults * 2, maxResults + 50);
+                  const topResults = this.searchService.searchKeyword(trimmedQuery, scoredEntityIds, keywordOversampledLimit);
+                  const topResultIds = new Set(topResults.map((r) => r.id));
+                  const candidateMap = new Map(candidateRows.filter((r) => topResultIds.has(r.id)).map((row) => [row.id, row]));
+                  scored = topResults.map((result) => {
+                    const metadata = candidateMap.get(result.id);
+                    const entityForScore = metadata?.entity_id ?? result.entity_id ?? "";
+                    return {
+                      id: result.id,
+                      entity_id: entityForScore,
+                      score: result.score ?? 0,
+                      access_count: metadata?.access_count ?? null,
+                      updated_at: metadata?.updated_at ?? null
+                    };
+                  });
+                } else {
+                  scored = [];
+                }
+                if (this.options.propagateRankerFailureToRetrievalFallback) {
+                  const mirrored = new Error("Vector ranker failed, falling back", {
+                    cause: this._sanitizeRankerError(rankerErr)
+                  });
+                  pendingRankerFallbackError = mirrored;
+                }
+              }
+            } else {
+              const jsCosineNeedsTierSort = sanitizedTierWeights !== void 0 && Object.values(sanitizedTierWeights).some((w) => w !== 1);
+              scored = await this.searchService.rankSemantic({
+                entityId: entityCacheKey,
+                queryVec,
+                candidateRows,
+                weight,
+                miniSearchScores,
+                populateCache,
+                limit: jsCosineNeedsTierSort ? candidateRows.length : maxResults,
+                skipSort: jsCosineNeedsTierSort
+                // read() re-sorts after applying tier weights
+              });
+            }
+            if (scored.length > 0) {
+              scored = scored.map((row) => ({
+                ...row,
+                score: applyTierWeight(row.score, row.entity_id, sanitizedTierWeights)
+              }));
+              this._tieBreakSort(scored);
+              const selectedScored = scored.slice(0, maxResults);
+              const topIds = selectedScored.map((s) => s.id);
+              if (exposeMetadata && trimmedQuery) {
+                scoreByFactId = new Map(selectedScored.map((s) => [s.id, Number.isFinite(s.score) ? s.score : 0]));
+              }
+              if (topIds.length > 0) {
+                const facts2 = await this._hydrateFactsByIds(topIds, entityIds);
+                if (facts2.length < topIds.length) {
+                  const hydrationById = new Set(facts2.map((f) => f.id));
+                  const missingIds = topIds.filter((id) => !hydrationById.has(id));
+                  const missingCount = missingIds.length;
+                  const sample = missingIds.slice(0, 5);
+                  const sampleSuffix = sample.length > 0 ? ` Missing ID sample: ${sample.join(", ")}${missingIds.length > sample.length ? ", ..." : ""}.` : "";
+                  const error = new Error(
+                    `Phase 2 fact hydration returned ${missingCount} fewer row(s) than ranked IDs. Rows may have been concurrently soft-deleted or filtered by deleted_at during hydration, or vector ranker output may include IDs that do not exist in requested entities.` + sampleSuffix
+                  );
+                  this.options.onRetrievalFallback?.(error);
+                }
+                facts = facts2;
+              }
+              if (pendingRankerFallbackError) {
+                this.options.onRetrievalFallback?.(pendingRankerFallbackError);
+                pendingRankerFallbackError = void 0;
+              }
+              usedEmbed = true;
+            } else {
+              if (pendingRankerFallbackError) {
+                this.options.onRetrievalFallback?.(pendingRankerFallbackError);
+                pendingRankerFallbackError = void 0;
+              }
+              usedEmbed = true;
+            }
+          }
+        } catch (err) {
+          const error = err instanceof Error ? err : new Error(String(err));
+          if (rankerShouldRethrow) {
+            throw error;
+          }
+          if (pendingRankerFallbackError) {
+            error.cause = pendingRankerFallbackError;
+            pendingRankerFallbackError = void 0;
+          }
+          this.options.onRetrievalFallback?.(error);
+        }
+      }
+      if (!usedEmbed && scoredEntityIds.length > 0) {
+        const fallbackOversampledLimit = Math.max(maxResults * 2, maxResults + 50);
+        const results = this.searchService.searchKeyword(trimmedQuery, scoredEntityIds, fallbackOversampledLimit);
+        const candidates = results.map((r) => ({
+          id: r.id,
+          entity_id: r.entity_id,
+          score: applyTierWeight(r.score ?? 0, r.entity_id, sanitizedTierWeights),
+          updated_at: null,
+          access_count: null
+        }));
+        this._tieBreakSort(candidates);
+        const topCandidates = candidates.slice(0, maxResults);
+        const topIds = topCandidates.map((c) => c.id);
+        if (topIds.length > 0) {
+          facts = await this._hydrateFactsByIds(topIds, entityIds);
+          if (exposeMetadata) {
+            scoreByFactId = new Map(topCandidates.map((c) => [c.id, Number.isFinite(c.score) ? c.score : 0]));
+          }
+        }
+      }
+      if (facts.length > 0) {
+        const ids = facts.map((f) => f.id);
+        const now = Date.now();
+        await this.entryRepo.trackAccess(ids, now);
+      }
+    } else {
+      facts = await this.entryRepo.findRecentByEntityIds(entityIds, maxResults);
+    }
+    const eventsLimit = Math.min(10 * entityIds.length, 100);
+    const [tasks, events] = await Promise.all([
+      this.taskRepo.findAllPending(entityIds, entityIds.length === 1 ? void 0 : Math.min(20 * entityIds.length, 200)),
+      entityIds.length === 1 ? this.eventRepo.getRecent(entityIds[0], eventsLimit) : this.eventRepo.getRecentForEntities(entityIds, eventsLimit)
+    ]);
+    let factScores;
+    if (exposeMetadata && trimmedQuery && scoreByFactId) {
+      factScores = Object.fromEntries(facts.map((fact) => [fact.id, scoreByFactId.get(fact.id) ?? 0]));
+    }
+    const bundle = { facts, tasks, events: events.reverse() };
+    if (exposeMetadata) {
+      bundle.metadata = { query, entityIds };
+      if (sanitizedTierWeights && Object.keys(sanitizedTierWeights).length > 0) bundle.metadata.tierWeights = sanitizedTierWeights;
+      if (factScores && Object.keys(factScores).length > 0) bundle.factScores = factScores;
+    }
+    return bundle;
+  }
+  /**
+   * Returns entity IDs that will participate in scored retrieval.
+   * Excludes zero-weight entities unless includeZeroWeightEntities is true.
+   */
+  _filterScoredEntities(entityIds, sanitizedTierWeights, includeZeroWeightEntities) {
+    return entityIds.filter((id) => {
+      const w = sanitizedTierWeights?.[id] ?? 1;
+      return includeZeroWeightEntities === true || w !== 0;
+    });
+  }
+  /**
+   * Stable tie-break sort: score desc → access_count desc → updated_at desc → id asc.
+   */
+  _tieBreakSort(items) {
+    items.sort((a, b) => this._compareScoredRows(a, b));
+  }
+  /**
+   * Comparator for score + deterministic tie-break fields.
+   * Negative return means "a ranks ahead of b" for descending score order.
+   */
+  _compareScoredRows(a, b) {
+    const scoreDiff = b.score - a.score;
+    if (!Number.isNaN(scoreDiff) && scoreDiff !== 0) return scoreDiff;
+    const accessCountDiff = (b.access_count ?? 0) - (a.access_count ?? 0);
+    if (accessCountDiff !== 0) return accessCountDiff;
+    const updatedAtDiff = (b.updated_at ?? 0) - (a.updated_at ?? 0);
+    if (updatedAtDiff !== 0) return updatedAtDiff;
+    return a.id.localeCompare(b.id);
+  }
+  /**
+   * Hydrate full facts by ID. Pass scopedEntityIds to restrict to requested namespaces in SQL
+   * (defense-in-depth against a rogue VectorRanker returning cross-entity IDs).
+   */
+  async _hydrateFactsByIds(ids, scopedEntityIds, tx) {
+    return this.entryRepo.findByIds(ids, scopedEntityIds, tx);
+  }
+  _sanitizeRankerError(err) {
+    return sanitizeRankerError(err, this.options.sanitizeRankerErrors);
+  }
+  /**
+   * Delegate semantic ranking to the injected VectorRanker.
+   * Caller should pass an oversampledLimit to preserve recall after re-ranking.
+   * Returns scored results ready for hybrid blending and tie-break sorting.
+   */
+  async _rankWithVectorRanker(args) {
+    const { entityId, candidateIds, candidateRows, weight, miniSearchScores, limit } = args;
+    const ranker = this.options.vectorRanker;
+    if (!ranker) {
+      throw new Error("vectorRanker not configured");
+    }
+    const queryVecCopy = args.queryVec instanceof Float32Array ? args.queryVec.slice() : Array.from(args.queryVec);
+    const rankerResults = await ranker.rankBySimilarity({
+      entityId,
+      queryVec: queryVecCopy,
+      candidateIds,
+      limit
+    });
+    const allowedIds = new Set(candidateRows.map((row) => row.id));
+    const seen = /* @__PURE__ */ new Set();
+    const normalized = [];
+    for (const r of rankerResults) {
+      if (normalized.length >= limit) break;
+      if (seen.has(r.id)) continue;
+      if (allowedIds && !allowedIds.has(r.id)) continue;
+      if (!Number.isFinite(r.semanticScore)) continue;
+      seen.add(r.id);
+      normalized.push(r);
+    }
+    const entityIdByCandidateId = new Map(candidateRows.map((row) => [row.id, row.entity_id]));
+    const scored = normalized.map((r) => {
+      let score = r.semanticScore;
+      if (weight !== void 0) {
+        const kwScore = miniSearchScores?.get(r.id) ?? 0;
+        score = weight * Math.max(0, r.semanticScore) + (1 - weight) * kwScore;
+      }
+      return {
+        id: r.id,
+        entity_id: entityIdByCandidateId.get(r.id),
+        // allowedIds filter above guarantees membership
+        score
+      };
+    });
+    return scored;
+  }
+};
+
+// src/services/WriteService.ts
+var WriteService = class {
+  constructor(db, options, eventRepo, metadataRepo, jobManager, maintenanceService) {
+    this.db = db;
+    this.options = options;
+    this.eventRepo = eventRepo;
+    this.metadataRepo = metadataRepo;
+    this.jobManager = jobManager;
+    this.maintenanceService = maintenanceService;
+  }
+  async write(entityId, event) {
+    const id = generateId("evt_");
+    const now = Date.now();
+    let eventType = event.event_type;
+    if (!["observation", "decision", "action", "outcome"].includes(eventType)) {
+      eventType = "observation";
+    }
+    const newEvent = {
+      id,
+      entity_id: entityId,
+      event_type: eventType,
+      summary: event.summary,
+      related_entry_id: event.related_entry_id || null,
+      created_at: now
+    };
+    let shouldRunLibrarian = false;
+    let librarianCount = 0;
+    let prevMemoryCheckpoint = 0;
+    await this.db.withTransactionAsync(async (tx) => {
+      await this.eventRepo.add(newEvent, tx);
+      const threshold = this.options.config?.autoLibrarianThreshold || 20;
+      const [count, cp] = await Promise.all([
+        this.eventRepo.count(entityId, tx),
+        this.metadataRepo.getCheckpoint(entityId, tx)
+      ]);
+      let memoryCheckpoint = cp.memory ?? 0;
+      if (memoryCheckpoint > count) memoryCheckpoint = 0;
+      if (count - memoryCheckpoint >= threshold) {
+        if (!this.jobManager.isBlocked("librarian", entityId)) {
+          shouldRunLibrarian = true;
+          librarianCount = count;
+          prevMemoryCheckpoint = memoryCheckpoint;
+          await this.metadataRepo.updateCheckpoint(entityId, { memory: count }, tx);
+        }
+      }
+    });
+    if (shouldRunLibrarian) {
+      try {
+        this.jobManager.acquireLock("librarian", entityId);
+        this.runLibrarianThenMaybeHeal(entityId, librarianCount, prevMemoryCheckpoint).catch(console.error).finally(() => {
+          this.jobManager.releaseLock("librarian", entityId);
+        });
+      } catch (e) {
+        if (!(e instanceof WikiBusyError)) throw e;
+        await this.metadataRepo.updateCheckpoint(entityId, { memory: prevMemoryCheckpoint }, this.db);
+      }
+    }
+  }
+  async runLibrarianThenMaybeHeal(entityId, currentEventCount, prevCheckpoint) {
+    try {
+      await this.maintenanceService.doRunLibrarian(entityId);
+      await this.metadataRepo.updateCheckpoint(entityId, { memory: currentEventCount }, this.db);
+    } catch (e) {
+      await this.metadataRepo.updateCheckpoint(entityId, { memory: prevCheckpoint }, this.db);
+      throw e;
+    }
+    const autoHealThreshold = this.options.config?.autoHealThreshold || 100;
+    const cp = await this.metadataRepo.getCheckpoint(entityId, this.db);
+    let healCheckpoint = cp.heal ?? 0;
+    if (healCheckpoint > currentEventCount) healCheckpoint = 0;
+    const shouldRunHeal = currentEventCount - healCheckpoint >= autoHealThreshold;
+    if (shouldRunHeal && this.jobManager.tryAcquireAutoHealLock(entityId)) {
+      try {
+        await this.maintenanceService.doRunHeal(entityId);
+        await this.metadataRepo.updateCheckpoint(entityId, { heal: currentEventCount }, this.db);
+      } finally {
+        this.jobManager.releaseLock("heal", entityId);
+      }
+    }
+  }
+};
+
+export { EmbeddingService, HOOK_TIMEOUT_MARKER, ImportExportService, IngestionService, JobManager, MaintenanceService, PromptService, PrunePartialFailureError, RetrievalService, SearchService, WikiBusyError, WriteService, __privateAdd, __privateGet, __privateSet, generateId, normalizeSourceHash, normalizeSourceRef, parseEmbedding };
+//# sourceMappingURL=chunk-2FGDZKC2.mjs.map
+//# sourceMappingURL=chunk-2FGDZKC2.mjs.map