@equationalapplications/core-llm-wiki 4.7.0 → 4.8.0

package/dist/index.js

@@ -6,6 +6,14 @@ function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
 
 var MiniSearch__default = /*#__PURE__*/_interopDefault(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"), member.set(obj, value), value);
+
 // src/db/schema.ts
 async function setupDatabase(db, prefix) {
   await db.execAsync(`
@@ -155,28 +163,6 @@ for (let i = 1; i < MIGRATIONS.length; i++) {
 }
 var CURRENT_SCHEMA_VERSION = MIGRATIONS.length > 0 ? MIGRATIONS[MIGRATIONS.length - 1].version : 0;
 
-// 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;
-  }
-};
-
 // src/repositories/BaseRepository.ts
 var BaseRepository = class {
   constructor(db, prefix) {
@@ -220,6 +206,28 @@ function mapRowToFact(row) {
     access_count: Number(row.access_count ?? 0)
   };
 }
+function normalizeEmbeddingBlobValue(blob) {
+  if (blob instanceof Uint8Array) return blob;
+  if (blob !== null && blob !== void 0 && typeof blob === "object") {
+    const obj = blob;
+    if (obj["type"] === "Buffer" && Array.isArray(obj["data"])) {
+      return new Uint8Array(obj["data"]);
+    }
+    const entries = Object.keys(obj);
+    if (entries.length > 0 && entries.every((k) => /^\d+$/.test(k))) {
+      const len = entries.length;
+      const arr = new Uint8Array(len);
+      for (let i = 0; i < len; i++) arr[i] = obj[String(i)] ?? 0;
+      return arr;
+    }
+  }
+  return null;
+}
+function mapRowToFactWithBlobs(row) {
+  const base = mapRowToFact(row);
+  const embeddingBlob = normalizeEmbeddingBlobValue(row.embedding_blob);
+  return embeddingBlob ? { ...base, embedding_blob: embeddingBlob } : base;
+}
 var EntryRepository = class extends BaseRepository {
   constructor(db, prefix, outbox) {
     super(db, prefix);
@@ -315,21 +323,7 @@ var EntryRepository = class extends BaseRepository {
    * Normalize an embedding blob value to Uint8Array or null.
    */
   normalizeEmbeddingBlob(blob) {
-    if (blob instanceof Uint8Array) return blob;
-    if (blob !== null && blob !== void 0 && typeof blob === "object") {
-      const obj = blob;
-      if (obj["type"] === "Buffer" && Array.isArray(obj["data"])) {
-        return new Uint8Array(obj["data"]);
-      }
-      const entries = Object.keys(obj);
-      if (entries.length > 0 && entries.every((k) => /^\d+$/.test(k))) {
-        const len = entries.length;
-        const arr = new Uint8Array(len);
-        for (let i = 0; i < len; i++) arr[i] = obj[String(i)] ?? 0;
-        return arr;
-      }
-    }
-    return null;
+    return normalizeEmbeddingBlobValue(blob);
   }
   /**
    * Fetch existing rows by IDs and return id/entity_id/updated_at for import collision resolution.
@@ -509,7 +503,7 @@ var EntryRepository = class extends BaseRepository {
   }
   /**
    * Fetch recent non-deleted entries for an entity (limited), ordered by updated_at DESC.
-   * Used by _doRunLibrarian().
+   * Used by MaintenanceService.doRunLibrarian().
    */
   async findRecentByEntityId(entityId, limit, tx) {
     const executor = this.getExecutor(tx);
@@ -519,6 +513,18 @@ var EntryRepository = class extends BaseRepository {
     );
     return rows.map(mapRowToFact);
   }
+  /**
+   * Fetch all non-deleted entries for an entity with embedding blobs preserved.
+   * Used by ImportExportService for export/import round-tripping.
+   */
+  async findAllByEntityIdWithBlobs(entityId, tx) {
+    const executor = this.getExecutor(tx);
+    const rows = await executor.getAllAsync(
+      `SELECT * FROM ${this.prefix}entries WHERE entity_id = ? AND deleted_at IS NULL ORDER BY updated_at DESC`,
+      [entityId]
+    );
+    return rows.map(mapRowToFactWithBlobs);
+  }
   /**
    * Count non-deleted entries for the given entities whose embedding_blob dimension
    * doesn't match queryVecLength. Used by read() to detect model-switch mismatches.
@@ -605,24 +611,19 @@ var EntryRepository = class extends BaseRepository {
   }
   /**
    * Mark orphaned entries (never accessed, old) as deleted.
-   * Used by _doRunHeal().
+   * Used by MaintenanceService.doRunHeal().
    */
   async markOrphaned(entityId, orphanThreshold, tx) {
     const executor = this.getExecutor(tx);
     const now = Date.now();
-    const orphanedRows = await executor.getAllAsync(
-      `SELECT id FROM ${this.prefix}entries
-       WHERE entity_id = ? AND access_count = 0 AND created_at <= ? AND source_type != 'immutable_document' AND deleted_at IS NULL`,
-      [entityId, orphanThreshold]
-    );
-    if (orphanedRows.length === 0) return 0;
-    const result = await executor.runAsync(
+    const updatedRows = await executor.getAllAsync(
       `UPDATE ${this.prefix}entries
        SET deleted_at = ?, updated_at = ?
-       WHERE entity_id = ? AND access_count = 0 AND created_at <= ? AND source_type != 'immutable_document' AND deleted_at IS NULL`,
+       WHERE entity_id = ? AND access_count = 0 AND created_at <= ? AND source_type != 'immutable_document' AND deleted_at IS NULL
+       RETURNING id`,
       [now, now, entityId, orphanThreshold]
     );
-    for (const row of orphanedRows) {
+    for (const row of updatedRows) {
       await this.outbox.push({
         entityId,
         tableName: "entries",
@@ -631,11 +632,11 @@ var EntryRepository = class extends BaseRepository {
         payload: { id: row.id, entity_id: entityId, deleted_at: now }
       }, tx);
     }
-    return result.changes;
+    return updatedRows.map((r) => r.id);
   }
   /**
    * Downgrade stale inferred entries to 'tentative'.
-   * Used by _doRunHeal().
+   * Used by MaintenanceService.doRunHeal().
    */
   async downgradeStaleInferred(entityId, staleThreshold, tx) {
     const executor = this.getExecutor(tx);
@@ -667,7 +668,7 @@ var EntryRepository = class extends BaseRepository {
   }
   /**
    * Downgrade specific entries to 'tentative' by IDs.
-   * Used by _doRunHeal().
+   * Used by MaintenanceService.doRunHeal().
    */
   async downgradeByIds(ids, entityId, tx) {
     if (ids.length === 0) return;
@@ -690,7 +691,7 @@ var EntryRepository = class extends BaseRepository {
   }
   /**
    * Soft-delete specific entries by IDs.
-   * Used by _doRunHeal().
+   * Used by MaintenanceService.doRunHeal().
    */
   async softDeleteByIds(ids, entityId, tx) {
     if (ids.length === 0) return;
@@ -1420,29 +1421,6 @@ var MetadataRepository = class extends BaseRepository {
   }
 };
 
-// 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/utils/cosine.ts
 function cosineSimilarity(a, b) {
   let dot = 0, normA = 0, normB = 0;
@@ -1484,267 +1462,168 @@ function parseEmbedding(blob, text) {
   return null;
 }
 
-// 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);
+// 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__default.default({
+      fields: ["title", "body", "tags"],
+      storeFields: ["entity_id"],
+      searchOptions: {
+        boost: { title: 2 },
+        fuzzy: 0.2,
+        prefix: true
+      }
+    });
   }
-  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;
+  /**
+   * 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 {
-      sanitized[entityId] = Math.max(0, raw);
+      this.vectorCache.clear();
     }
   }
-  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/WikiMemory.ts
-var HOOK_TIMEOUT_MARKER = /* @__PURE__ */ Symbol("WikiMemoryHookTimeout");
-function parseJsonResponse(text) {
-  const firstBrace = text.indexOf("{");
-  const firstBracket = text.indexOf("[");
-  let start;
-  let openChar;
-  let closeChar;
-  if (firstBrace !== -1 && (firstBracket === -1 || firstBrace < firstBracket)) {
-    start = firstBrace;
-    openChar = "{";
-    closeChar = "}";
-  } else if (firstBracket !== -1) {
-    start = firstBracket;
-    openChar = "[";
-    closeChar = "]";
-  } else {
-    throw new SyntaxError("No JSON object/array found in LLM response");
+  /**
+   * Fully resets the search service.
+   */
+  clearAll() {
+    this.vectorCache.clear();
+    this.miniSearch.removeAll();
+    this.miniSearchEntryIdsByEntity.clear();
   }
-  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;
+  /**
+   * 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 (ch === "\\" && inString) {
-      escape = true;
-      continue;
+    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;
     }
-    if (ch === '"') {
-      inString = !inString;
-      continue;
+    const canCache = populateCache && !tooLarge;
+    if (canCache && !entityCache) {
+      entityCache = /* @__PURE__ */ new Map();
     }
-    if (inString) continue;
-    if (ch === openChar) {
-      depth++;
-      continue;
+    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 (ch === closeChar) {
-      depth--;
-      if (depth === 0) {
-        end = i;
-        break;
+    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);
     }
   }
-  if (end === -1) throw new SyntaxError("No JSON object/array found in LLM response");
-  return JSON.parse(text.slice(start, end + 1));
-}
-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;
-  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;
-}
-var FUZZY_THRESHOLD = 0.5;
-var MIN_TOKENS_TO_QUALIFY = 3;
-var _WikiMemory = class _WikiMemory {
-  constructor(db, options) {
-    this.activeMaintenanceJobs = /* @__PURE__ */ new Set();
-    this.activeIngestJobs = /* @__PURE__ */ new Set();
-    this.statusSubscribers = /* @__PURE__ */ new Map();
-    this.miniSearch = new MiniSearch__default.default({
-      fields: ["title", "body", "tags"],
-      storeFields: ["entity_id"],
-      searchOptions: {
-        boost: { title: 2 },
-        fuzzy: 0.2,
-        prefix: true
-      }
-    });
-    this.miniSearchEntryIdsByEntity = /* @__PURE__ */ new Map();
-    this.vectorCache = /* @__PURE__ */ new Map();
-    this.db = db;
-    this.options = options;
-    this.prefix = options.config?.tablePrefix || "llm_wiki_";
-    this.outboxRepo = new OutboxRepository(db, this.prefix);
-    this.entryRepo = new EntryRepository(db, this.prefix, this.outboxRepo);
-    this.taskRepo = new TaskRepository(db, this.prefix, this.outboxRepo);
-    this.eventRepo = new EventRepository(db, this.prefix);
-    this.metadataRepo = new MetadataRepository(db, this.prefix);
-  }
   normalizeMiniSearchRow(row) {
     return {
       id: row.id,
@@ -1761,252 +1640,63 @@ var _WikiMemory = class _WikiMemory {
       })()
     };
   }
-  async rebuildMiniSearchIndex(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);
-    }
+  _tieBreakSort(items) {
+    items.sort((a, b) => this._compareScoredRows(a, b));
   }
-  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);
-    }
+  _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);
   }
-  /**
-   * After a successful runReembed(), promote the pending `embedding_dimension_mismatch`
-   * value to the canonical `embedding_dimension` key and clear the mismatch flag.
-   * This ensures future read() calls use embedding-based retrieval rather than staying
-   * stuck on the MiniSearch fallback.
-   */
-  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);
-    }
+};
+/**
+ * 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;
   }
-  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;
-    }
-  }
-  _librarianKey(entityId) {
-    return `${this.prefix}:${entityId}:librarian`;
-  }
-  _healKey(entityId) {
-    return `${this.prefix}:${entityId}:heal`;
-  }
-  _warnCrossEntityCollision(type, id, existingEntityId, targetEntityId) {
-    console.warn(`[WikiMemory] importDump: ${type} id "${id}" already belongs to entity "${existingEntityId}"; skipping for entity "${targetEntityId}"`);
-  }
-  /** Maps pre-rename enum strings from older dumps to current source_type values. */
-  _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)`
-    );
+};
+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;
   }
-  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()}
+};
+var HOOK_TIMEOUT_MARKER = /* @__PURE__ */ Symbol("WikiMemoryHookTimeout");
 
-After running the migration SQL, restart your application.`
-    );
-  }
-  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
-    });
-  }
-  /**
-   * GDPR-critical variant: awaits the hook with a timeout and rethrows failures.
-   * Use ONLY on deletion paths. forget() calls after soft-delete UPDATE; runPrune()
-   * calls before hard DELETE. For best-effort sync, use _notifyEmbeddingPersisted.
-   */
-  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(
-      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);
-    }
-  }
-  async setup() {
-    const entriesExistedBeforeSetup = await this.metadataRepo.tableExists(`${this.prefix}entries`);
-    await setupDatabase(this.db, this.prefix);
-    let currentVersion;
-    if (!entriesExistedBeforeSetup) {
-      await this.metadataRepo.setMeta("schema_version", String(CURRENT_SCHEMA_VERSION), this.db);
-      currentVersion = CURRENT_SCHEMA_VERSION;
-    } else {
-      const schemaVersionValue = await this.metadataRepo.getMeta("schema_version");
-      if (schemaVersionValue) {
-        currentVersion = parseInt(schemaVersionValue, 10);
-        if (!Number.isFinite(currentVersion)) currentVersion = 0;
-      } else {
-        const ftsDdl = await this.metadataRepo.getTableDdl(`${this.prefix}entries_fts`);
-        const hasPorter = /tokenize\s*=\s*['"]porter\s+unicode61['"]/i.test(ftsDdl ?? "");
-        currentVersion = hasPorter ? 1 : 0;
-      }
-    }
-    for (const migration of MIGRATIONS) {
-      if (migration.version > currentVersion) {
-        await migration.run(this.db, this.prefix);
-        await this.metadataRepo.setMeta("schema_version", String(migration.version), this.db);
-        currentVersion = migration.version;
-      }
-    }
-    if (entriesExistedBeforeSetup) {
-      const schemaVersionCheck = await this.metadataRepo.getMeta("schema_version");
-      if (!schemaVersionCheck) {
-        await this.metadataRepo.setMeta("schema_version", String(currentVersion), this.db);
-      }
-    }
-    if (entriesExistedBeforeSetup) {
-      await this.assertNoLegacySourceTypes();
-    }
-    const rows = await this.entryRepo.findRowsForSourceRefMigration();
-    await this.db.withTransactionAsync(async (tx) => {
-      for (const row of rows) {
-        const normalized = normalizeSourceRef(row.source_ref);
-        if (normalized !== row.source_ref) {
-          await this.entryRepo.updateSourceRefByRowid(row.rowid, normalized, tx);
-        }
-      }
-    });
-    await this.rebuildMiniSearchIndex();
-  }
-  async hasChanged(entityId, sourceRef, sourceHash) {
-    const normalizedRef = normalizeSourceRef(sourceRef);
-    if (!normalizedRef) {
-      throw new Error(`Invalid sourceRef: "${sourceRef}"`);
-    }
-    const normalizedHash = normalizeSourceHash(sourceHash);
-    if (!normalizedHash) {
-      throw new Error(`Invalid sourceHash: must be a 64-character hex string (normalized to lowercase)`);
-    }
-    const storedHash = await this.entryRepo.findLatestSourceHash(entityId, normalizedRef);
-    if (storedHash === null) return true;
-    const normalizedStoredHash = normalizeSourceHash(storedHash);
-    return normalizedStoredHash !== normalizedHash;
+// 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`;
@@ -2026,6 +1716,12 @@ After running the migration SQL, restart your application.`
   _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());
   }
@@ -2035,7 +1731,6 @@ After running the migration SQL, restart your application.`
   _isForgetActiveFor(entityId) {
     return this.activeMaintenanceJobs.has(this._forgetKey(entityId));
   }
-  /** Returns true if any maintenance job has the given operation suffix (e.g. ':prune'). */
   _isAnyMaintenanceActiveWithSuffix(suffix) {
     const entityKeyPrefix = `${this.prefix}:`;
     for (const k of this.activeMaintenanceJobs) {
@@ -2043,794 +1738,874 @@ After running the migration SQL, restart your application.`
     }
     return false;
   }
-  /** Returns true if any ingest job is active for the given entity. */
+  _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) {
-    const entityKeyPrefix = `${this.prefix}:${entityId}:`;
-    for (const k of this.activeIngestJobs) {
-      if (k.startsWith(entityKeyPrefix)) return true;
+    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", "*");
     }
-    return false;
+    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;
+      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(`[WikiMemory.subscribeEntityStatus] callback error for entityId="${entityId}" during transition emission`, err);
+        console.error(`[JobManager] callback error for entityId="${entityId}" during transition emission`, err);
       }
     }
   }
-  _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`);
-    }
+};
+
+// 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");
   }
-  async runPrune(entityId, options) {
-    const pruneKey = this._pruneKey(entityId);
-    const ingestPrefix = `${this.prefix}:${entityId}:`;
-    let isIngestRunning = false;
-    for (const k of this.activeIngestJobs) {
-      if (k.startsWith(ingestPrefix)) {
-        isIngestRunning = true;
+  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;
       }
     }
-    let blockingOperation = null;
-    if (this.activeMaintenanceJobs.has(pruneKey)) {
-      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 (isIngestRunning) {
-      blockingOperation = "ingest";
-    } else if (this._isImportActiveFor(entityId)) {
-      blockingOperation = "import";
-    } else if (this._isForgetActiveFor(entityId)) {
-      blockingOperation = "forget";
-    }
-    if (blockingOperation !== null) {
-      throw new WikiBusyError(blockingOperation, entityId);
-    }
-    this.activeMaintenanceJobs.add(pruneKey);
-    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._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.rebuildMiniSearchIndex(entityId);
-          this.vectorCache.delete(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
-              // events not yet deleted at this point
-            );
-          }
-          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
-            // events not yet deleted at this point
-          );
+  }
+  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 (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.rebuildMiniSearchIndex(entityId);
-      this.vectorCache.delete(entityId);
-      return { entries: deletedEntries, tasks: deletedTasks, events: deletedEvents };
-    } finally {
-      this.activeMaintenanceJobs.delete(pruneKey);
+      if (lastTerm !== -1 && lastTerm <= windowEnd) splitPoint = lastTerm;
     }
-  }
-  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;
+    if (splitPoint === -1) {
+      for (let i = windowEnd - 1; i >= minSplit; i--) {
+        if (/\s/.test(text[i])) {
+          splitPoint = i + 1;
+          break;
+        }
       }
-      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}`);
+    if (splitPoint === -1) {
+      truncated = true;
+      splitPoint = windowEnd;
     }
-    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}"`);
+    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 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 entityIdSet = new Set(scoredEntityIds);
-            const preResults = this.miniSearch.search(trimmedQuery, {
-              filter: (r) => entityIdSet.has(r.entity_id),
-              combineWith: "OR"
-            });
-            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) {
-              const entityIdSet = new Set(scoredEntityIds);
-              const msResults = this.miniSearch.search(trimmedQuery, {
-                filter: (r) => entityIdSet.has(r.entity_id),
-                combineWith: "OR"
-              });
-              const maxMsScore = Math.max(1, msResults[0]?.score ?? 1);
-              miniSearchScores = new Map(msResults.map((r) => [r.id, r.score / maxMsScore]));
-            }
-          }
-          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._rankWithJsCosine({
-                    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 scoredEntityIdSet = new Set(scoredEntityIds);
-                  const msResults = this.miniSearch.search(trimmedQuery, {
-                    filter: (r) => scoredEntityIdSet.has(r.entity_id),
-                    combineWith: "OR"
-                  });
-                  const keywordOversampledLimit = Math.max(maxResults * 2, maxResults + 50);
-                  const topResults = msResults.slice(0, 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._rankWithJsCosine({
-                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;
+  }
+  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/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/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);
           }
-          if (pendingRankerFallbackError) {
-            error.cause = pendingRankerFallbackError;
-            pendingRankerFallbackError = void 0;
+        }
+      }
+      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;
           }
-          this.options.onRetrievalFallback?.(error);
         }
-      }
-      if (!usedEmbed && scoredEntityIds.length > 0) {
-        const fallbackEntityIdSet = new Set(scoredEntityIds);
-        const fallbackOversampledLimit = Math.max(maxResults * 2, maxResults + 50);
-        const results = this.miniSearch.search(trimmedQuery, {
-          filter: (r) => fallbackEntityIdSet.has(r.entity_id),
-          combineWith: "OR"
+        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);
         });
-        const candidates = results.slice(0, fallbackOversampledLimit).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 (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 (facts.length > 0) {
-        const ids = facts.map((f) => f.id);
-        const now = Date.now();
-        await this.entryRepo.trackAccess(ids, now);
+      if (retainEventsFor !== null) {
+        const cutoff = now - retainEventsFor * 864e5;
+        const eventResult = await this.eventRepo.prune(entityId, cutoff);
+        deletedEvents = eventResult.changes;
       }
-    } 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;
+      if (vacuum) {
+        await this.metadataRepo.vacuum();
+      }
+      await this.searchService.sync(entityId);
+      return { entries: deletedEntries, tasks: deletedTasks, events: deletedEvents };
+    } finally {
+      this.jobManager.releaseLock("prune", entityId);
     }
-    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);
-  }
-  /**
-   * Strip potentially sensitive data from ranker errors before exposing to host callbacks.
-   * Preserves error type for debugging but removes message/stack that may contain credentials.
-   * Recursively sanitizes one level of .cause; deeper chains collapse to type only.
-   */
-  _sanitizeRankerError(err) {
-    if (this.options.sanitizeRankerErrors === false) {
-      return err instanceof Error ? err : new Error(String(err));
+  async runLibrarian(entityId, options) {
+    this.jobManager.acquireLock("librarian", entityId);
+    try {
+      await this.doRunLibrarian(entityId, options?.promptOverride);
+    } finally {
+      this.jobManager.releaseLock("librarian", entityId);
     }
-    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;
   }
-  /**
-   * Score candidate rows using in-process JS cosine similarity.
-   * Applies hybrid blending (if weight set) and tie-break sorting before returning.
-   */
-  async _rankWithJsCosine(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 > _WikiMemory.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();
+  async runHeal(entityId, options) {
+    this.jobManager.acquireLock("heal", entityId);
+    try {
+      await this.doRunHeal(entityId, options?.promptOverride);
+    } finally {
+      this.jobManager.releaseLock("heal", entityId);
     }
-    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;
+  }
+  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;
+          }
         }
-      } 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 >= _WikiMemory.MAX_VECTOR_CACHE_ENTITIES) {
-          const oldestKey = this.vectorCache.keys().next().value;
-          if (oldestKey !== void 0) this.vectorCache.delete(oldestKey);
+      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++;
         }
-        this.vectorCache.set(entityId, entityCache);
-      }
-    }
-    if (!skipSort) this._tieBreakSort(scored);
-    return scored.slice(0, limit);
-  }
-  /**
-   * 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;
+        if (embedded > 0) {
+          await this.embeddingService.reconcileEmbeddingDimension();
+        }
+      } finally {
+        this.searchService.evictCache(entityId);
       }
-      return {
-        id: r.id,
-        entity_id: entityIdByCandidateId.get(r.id),
-        // allowedIds filter above guarantees membership
-        score
-      };
-    });
-    return scored;
-  }
-  async getMemoryBundle(entityId) {
-    return this._getFullBundle(entityId, { maxEvents: 10 });
+      return { embedded, skipped, failed };
+    } finally {
+      this.jobManager.releaseLock(op, entityId ?? "*");
+    }
   }
-  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";
+  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");
     }
-    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 librarianJobKey = null;
-    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) {
-        const jobKey = this._librarianKey(entityId);
-        if (!this.activeMaintenanceJobs.has(jobKey) && !this.activeMaintenanceJobs.has(this._pruneKey(entityId)) && !this._isReembedActive(entityId) && !this._isImportActiveFor(entityId) && !this._isForgetActiveFor(entityId)) {
-          shouldRunLibrarian = true;
-          librarianCount = count;
-          librarianJobKey = jobKey;
-          await this.metadataRepo.updateCheckpoint(entityId, { memory: count }, tx);
+    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;
         }
-      }
-    });
-    if (shouldRunLibrarian && librarianJobKey !== null) {
-      this.activeMaintenanceJobs.add(librarianJobKey);
-      this._notifyStatusSubscribers(entityId);
-      this.runLibrarianThenMaybeHeal(entityId, librarianCount).catch(console.error).finally(() => {
-        this.activeMaintenanceJobs.delete(librarianJobKey);
-        this._notifyStatusSubscribers(entityId);
       });
-    }
-  }
-  async runLibrarianThenMaybeHeal(entityId, currentEventCount) {
-    await this._doRunLibrarian(entityId);
-    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) {
-      const healKey = this._healKey(entityId);
-      if (!this.activeMaintenanceJobs.has(healKey)) {
-        this.activeMaintenanceJobs.add(healKey);
-        this._notifyStatusSubscribers(entityId);
+      await this.searchService.sync(entityId);
+      const uniqueDeletedIds = Array.from(new Set(deletedEntryIds));
+      for (const factId of uniqueDeletedIds) {
         try {
-          await this._doRunHeal(entityId);
-          await this.metadataRepo.updateCheckpoint(entityId, { heal: currentEventCount }, this.db);
-        } finally {
-          this.activeMaintenanceJobs.delete(healKey);
-          this._notifyStatusSubscribers(entityId);
+          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);
     }
   }
-  async _doRunLibrarian(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) => {
@@ -2840,15 +2615,12 @@ After running the migration SQL, restart your application.`
         tags: typeof rest.tags === "string" ? JSON.parse(rest.tags) : rest.tags
       };
     });
-    const userPrompt = `Events:
-${JSON.stringify(events.reverse(), null, 2)}
-
-Current Facts:
-${JSON.stringify(currentFacts, null, 2)}`;
-    const responseText = await this.options.llmProvider.generateText({
-      systemPrompt: LIBRARIAN_SYSTEM_PROMPT,
-      userPrompt
-    });
+    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 : [];
@@ -2893,24 +2665,35 @@ ${JSON.stringify(currentFacts, null, 2)}`;
         };
         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 };
+        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.rebuildMiniSearchIndex(entityId);
-    this.vectorCache.delete(entityId);
+    await this.searchService.sync(entityId);
     for (const fact of insertedFacts) {
-      await this.embedFact(fact);
+      await this.embeddingService.embedFact(fact);
     }
-    this.vectorCache.delete(entityId);
+    this.searchService.evictCache(entityId);
   }
-  async _doRunHeal(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 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");
@@ -2918,55 +2701,71 @@ ${JSON.stringify(currentFacts, null, 2)}`;
     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;
-        await this.entryRepo.markOrphaned(entityId, orphanThreshold, tx);
+        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 userPrompt = `Heal Candidates:
-${JSON.stringify(healCandidates.map((f) => {
+    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 };
-    }), 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\`.`;
-    const responseText = await this.options.llmProvider.generateText({
-      systemPrompt: HEAL_SYSTEM_PROMPT,
-      userPrompt
     });
+    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 = downgraded.filter((id) => mutableIds.has(id));
-    const safeDeleted = deleted.filter((id) => mutableIds.has(id));
+    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,
@@ -2986,241 +2785,94 @@ The following document anchors are provided for contradiction detection only. Do
         };
         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);
       }
     });
-    this.vectorCache.delete(entityId);
-    await this.rebuildMiniSearchIndex(entityId);
+    await this.searchService.sync(entityId);
     for (const factId of uniqueDeletedFactIds) {
       try {
-        await this._notifyEmbeddingPersisted(entityId, factId, null);
+        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.embedFact(fact);
+      await this.embeddingService.embedFact(fact);
     }
-    this.vectorCache.delete(entityId);
+    this.searchService.evictCache(entityId);
   }
-  async runLibrarian(entityId) {
-    const jobKey = this._librarianKey(entityId);
-    if (this.activeMaintenanceJobs.has(jobKey)) {
-      throw new WikiBusyError("librarian", entityId);
-    }
-    if (this.activeMaintenanceJobs.has(this._pruneKey(entityId))) {
-      throw new WikiBusyError("prune", entityId);
-    }
-    if (this._isReembedActive(entityId)) {
-      throw new WikiBusyError("reembed", entityId);
-    }
-    if (this._isImportActiveFor(entityId)) {
-      throw new WikiBusyError("import", entityId);
-    }
-    if (this._isForgetActiveFor(entityId)) {
-      throw new WikiBusyError("forget", entityId);
-    }
-    this.activeMaintenanceJobs.add(jobKey);
-    this._notifyStatusSubscribers(entityId);
-    try {
-      await this._doRunLibrarian(entityId);
-    } finally {
-      this.activeMaintenanceJobs.delete(jobKey);
-      this._notifyStatusSubscribers(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`);
     }
   }
-  async runHeal(entityId) {
-    const jobKey = this._healKey(entityId);
-    if (this.activeMaintenanceJobs.has(jobKey)) {
-      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._isImportActiveFor(entityId)) {
-      throw new WikiBusyError("import", entityId);
-    }
-    if (this._isForgetActiveFor(entityId)) {
-      throw new WikiBusyError("forget", entityId);
-    }
-    this.activeMaintenanceJobs.add(jobKey);
-    this._notifyStatusSubscribers(entityId);
-    try {
-      await this._doRunHeal(entityId);
-    } finally {
-      this.activeMaintenanceJobs.delete(jobKey);
-      this._notifyStatusSubscribers(entityId);
-    }
+  _sanitizeRankerError(err) {
+    return sanitizeRankerError(err, this.options.sanitizeRankerErrors);
   }
-  async runReembed(entityId, opts) {
-    const embedFn = this.options.llmProvider.embed;
-    if (!embedFn) return { embedded: 0, skipped: 0, failed: 0 };
-    const reembedKey = entityId ? this._reembedKey(entityId) : this._globalReembedKey();
-    if (this.activeMaintenanceJobs.has(reembedKey)) {
-      throw new WikiBusyError("reembed", entityId ?? "*");
-    }
-    if (entityId) {
-      if (this.activeMaintenanceJobs.has(this._globalReembedKey())) {
-        throw new WikiBusyError("reembed", entityId);
-      }
-      if (this.activeMaintenanceJobs.has(this._pruneKey(entityId))) {
-        throw new WikiBusyError("prune", 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._isIngestActiveFor(entityId)) {
-        throw new WikiBusyError("ingest", entityId);
-      }
-      if (this._isImportActiveFor(entityId)) {
-        throw new WikiBusyError("import", entityId);
-      }
-      if (this._isForgetActiveFor(entityId)) {
-        throw new WikiBusyError("forget", entityId);
-      }
-    } else {
-      if (this._isAnyMaintenanceActiveWithSuffix(":reembed")) {
-        throw new WikiBusyError("reembed", "*");
-      }
-      if (this._isAnyMaintenanceActiveWithSuffix(":prune")) {
-        throw new WikiBusyError("prune", "*");
-      }
-      if (this._isAnyMaintenanceActiveWithSuffix(":librarian")) {
-        throw new WikiBusyError("librarian", "*");
-      }
-      if (this._isAnyMaintenanceActiveWithSuffix(":heal")) {
-        throw new WikiBusyError("heal", "*");
-      }
-      if (this.activeIngestJobs.size > 0) {
-        throw new WikiBusyError("ingest", "*");
-      }
-      if (this._isAnyMaintenanceActiveWithSuffix(":import")) {
-        throw new WikiBusyError("import", "*");
-      }
-      if (this._isAnyMaintenanceActiveWithSuffix(":forget")) {
-        throw new WikiBusyError("forget", "*");
-      }
-    }
-    this.activeMaintenanceJobs.add(reembedKey);
-    try {
-      const rows = await this.entryRepo.findAllForReembed(entityId);
-      if (entityId) {
-        this.vectorCache.delete(entityId);
-      } else {
-        this.vectorCache.clear();
-      }
-      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.embedFact(row);
-          if (success) embedded++;
-          else failed++;
-        }
-        if (embedded > 0) {
-          await this._reconcileEmbeddingDimension();
-        }
-      } finally {
-        if (entityId) {
-          this.vectorCache.delete(entityId);
-        } else {
-          this.vectorCache.clear();
-        }
-      }
-      return { embedded, skipped, failed };
-    } finally {
-      this.activeMaintenanceJobs.delete(reembedKey);
-    }
+};
+
+// 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;
   }
-  getEntityStatus(entityId) {
-    const ingestPrefix = `${this.prefix}:${entityId}:`;
-    let ingesting = false;
-    for (const k of this.activeIngestJobs) {
-      if (k.startsWith(ingestPrefix)) {
-        ingesting = true;
-        break;
-      }
+  async exportDump(entityIds) {
+    let ids;
+    if (entityIds && entityIds.length > 0) {
+      ids = Array.from(new Set(entityIds));
+    } else {
+      ids = await this.metadataRepo.getDistinctEntityIds();
     }
-    return {
-      ingesting,
-      librarian: this.activeMaintenanceJobs.has(this._librarianKey(entityId)),
-      heal: this.activeMaintenanceJobs.has(this._healKey(entityId))
-    };
-  }
-  /**
-   * Subscribe to {@link EntityStatus} changes for a single entity. The callback
-   * is invoked synchronously once with the current status before this method
-   * returns, then again on every transition where any of `ingesting`,
-   * `librarian`, or `heal` flips. No polling, no duplicate snapshots.
-   *
-   * Returns an idempotent unsubscribe function.
-   *
-   * See also {@link getEntityStatus} for a synchronous point-in-time read.
-   */
-  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 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;
+      }
     }
-    const entry = { callback, last: this._copyEntityStatus(initial) };
-    set.add(entry);
+    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 {
-      callback(this._copyEntityStatus(initial));
-    } catch (err) {
-      console.error(`[WikiMemory.subscribeEntityStatus] callback error for entityId="${entityId}" during initial emission`, err);
+      await this.assertNoLegacySourceTypes();
+      for (const [entityId, bundle] of Object.entries(dump.entities)) {
+        await this.doImportEntity(entityId, bundle, merge);
+      }
+    } finally {
+      this.jobManager.releaseImportLocks(entityIds);
     }
-    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);
-    };
-  }
-  clearVectorCache() {
-    this.vectorCache.clear();
   }
-  async _getFullBundle(entityId, opts) {
+  async getFullBundle(entityId, opts) {
     const [factsRaw, tasks, events] = await Promise.all([
-      this.entryRepo.findAllByEntityId(entityId),
+      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 {
+        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);
@@ -3234,494 +2886,1272 @@ The following document anchors are provided for contradiction detection only. Do
     });
     return { facts, tasks, events };
   }
-  async exportDump(entityIds) {
-    let ids;
-    if (entityIds && entityIds.length > 0) {
-      ids = Array.from(new Set(entityIds));
-    } else {
-      ids = await this.metadataRepo.getDistinctEntityIds();
+  /** 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);
+        }
+      }
     }
-    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 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"
       );
-      for (const [id, bundle] of batchResults) {
-        entities[id] = bundle;
+      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);
     }
-    return { generatedAt: Date.now(), entities };
   }
-  async importDump(dump, opts) {
-    const merge = opts?.merge ?? false;
-    const entityIds = Object.keys(dump.entities);
-    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);
+  /** 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;
       }
-      if (this.activeMaintenanceJobs.has(this._pruneKey(entityId))) {
-        throw new WikiBusyError("prune", entityId);
+    }
+    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;
       }
-      if (this._isReembedActive(entityId)) {
-        throw new WikiBusyError("reembed", entityId);
+      const float32Vector = new Float32Array(vector);
+      let hasNonFinite = false;
+      for (let i = 0; i < float32Vector.length; i++) {
+        if (!isFinite(float32Vector[i])) {
+          hasNonFinite = true;
+          break;
+        }
       }
-      if (this._isIngestActiveFor(entityId)) {
-        throw new WikiBusyError("ingest", entityId);
+      if (hasNonFinite) {
+        console.warn(`[WikiMemory] embedFact: embed() returned values that overflow float32 for ${fact.id}; skipping.`);
+        return false;
       }
-      if (this._isForgetActiveFor(entityId)) {
-        throw new WikiBusyError("forget", entityId);
+      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;
     }
-    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));
+  }
+  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 this.assertNoLegacySourceTypes();
-      for (const [entityId, bundle] of Object.entries(dump.entities)) {
-        await this._doImportEntity(entityId, bundle, merge);
-      }
+      await Promise.race([hookPromise, timeoutPromise]);
+    } catch (err) {
+      hookPromise.catch(() => {
+      });
+      throw err;
     } finally {
-      this.activeMaintenanceJobs.delete(this._globalImportKey());
-      for (const entityId of entityIds) {
-        this.activeMaintenanceJobs.delete(this._importKey(entityId));
-      }
+      if (timeoutHandle) clearTimeout(timeoutHandle);
     }
   }
-  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);
+};
+
+// 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;
       }
-      for (const fact of bundle.facts) {
-        const sourceType = this._normalizeImportedSourceType(String(fact.source_type), {
-          entityId,
-          factId: fact.id
-        });
-        JSON.stringify(Array.isArray(fact.tags) ? fact.tags : []);
-        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;
+      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);
             }
           }
-        }
-        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 (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;
             }
           }
-          if (allFinite) {
-            blobData = alignedBlob;
-          }
-        }
-        if (existing) {
-          if (existing.entity_id !== entityId) {
-            this._warnCrossEntityCollision("entry", fact.id, existing.entity_id, entityId);
-            continue;
+        } catch (err) {
+          const error = err instanceof Error ? err : new Error(String(err));
+          if (rankerShouldRethrow) {
+            throw error;
           }
-          if (merge) {
-            if (safeUpdatedAt <= existing.updated_at) continue;
+          if (pendingRankerFallbackError) {
+            error.cause = pendingRankerFallbackError;
+            pendingRankerFallbackError = void 0;
           }
+          this.options.onRetrievalFallback?.(error);
         }
-        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) {
-            if (safeUpdatedAt <= existing.updated_at) continue;
+      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]));
           }
         }
-        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);
+      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;
     });
-    this.vectorCache.delete(entityId);
-    await this.rebuildMiniSearchIndex(entityId);
-    for (const fact of bundle.facts) {
-      if (!fact.deleted_at && upsertedFactIds.has(fact.id) && !factsWithPreservedBlob.has(fact.id)) {
-        await this.embedFact({
-          id: fact.id,
-          entity_id: entityId,
-          // Use authoritative entityId from dump key, not fact.entity_id
-          title: fact.title,
-          body: fact.body,
-          tags: Array.isArray(fact.tags) || typeof fact.tags === "string" ? fact.tags : []
-        });
-      }
+  }
+  /**
+   * 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");
     }
-    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._notifyEmbeddingPersisted(entityId, fact.id, float32Vector);
-        } catch (hookErr) {
-          console.warn(`[WikiMemory] onEmbeddingPersisted hook failed for preserved-blob fact ${fact.id}:`, hookErr);
-        }
-      }
+    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);
     }
-    for (const factId of softDeletedFactIds) {
-      if (!upsertedFactIds.has(factId) || upsertedDeletedFactIds.has(factId)) {
-        try {
-          await this._notifyEmbeddingPersisted(entityId, factId, null);
-        } catch (hookErr) {
-          console.warn(`[WikiMemory] onEmbeddingPersisted(vector=null) hook failed for soft-deleted fact ${factId}:`, hookErr);
-        }
+    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";
     }
-    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.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._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.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);
+    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);
         }
       }
-    } finally {
-      this.vectorCache.delete(entityId);
+    });
+    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 forget(entityId, params) {
-    let blockingOperation = null;
-    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";
-    }
-    if (blockingOperation !== null) {
-      throw new WikiBusyError(blockingOperation, entityId);
-    }
-    const forgetKey = this._forgetKey(entityId);
-    this.activeMaintenanceJobs.add(forgetKey);
+  async runLibrarianThenMaybeHeal(entityId, currentEventCount, prevCheckpoint) {
     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));
-          const entriesRes = await this.entryRepo.bulkSoftDeleteByEntityId(entityId, tx);
-          const tasksRes = await this.taskRepo.bulkSoftDeleteByEntityId(entityId, tx);
-          await this.metadataRepo.updateCheckpoint(entityId, { memory: 0, heal: 0 }, tx);
-          deletedEntries = entriesRes;
-          deletedTasks = tasksRes;
-        } 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.rebuildMiniSearchIndex(entityId);
-      this.vectorCache.delete(entityId);
-      const uniqueDeletedIds = Array.from(new Set(deletedEntryIds));
-      for (const factId of uniqueDeletedIds) {
-        try {
-          await this._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 ?? "";
-          const isValidationError = errMsg.startsWith("Invalid deletionHookTimeoutMs");
-          if (isValidationError) {
-            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) }
-          );
-        }
+      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);
       }
-      return { deleted: { entries: deletedEntries, tasks: deletedTasks } };
-    } finally {
-      this.activeMaintenanceJobs.delete(forgetKey);
     }
   }
-  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
+};
+
+// src/WikiMemory.ts
+var _testAccessNonTestEnvWarned;
+var WikiMemory = class {
+  constructor(db, options) {
+    /** Emits `__testAccess` console warning at most once per instance when NODE_ENV ≠ "test". */
+    __privateAdd(this, _testAccessNonTestEnvWarned, false);
+    this.db = db;
+    this.options = options;
+    this.prefix = options.config?.tablePrefix || "llm_wiki_";
+    this.outboxRepo = new OutboxRepository(db, this.prefix);
+    this.entryRepo = new EntryRepository(db, this.prefix, this.outboxRepo);
+    this.taskRepo = new TaskRepository(db, this.prefix, this.outboxRepo);
+    this.eventRepo = new EventRepository(db, this.prefix);
+    this.metadataRepo = new MetadataRepository(db, this.prefix);
+    this.embeddingService = new EmbeddingService(this.db, this.options, this.entryRepo, this.metadataRepo);
+    this.searchService = new SearchService(this.entryRepo);
+    this.jobManager = new JobManager(this.prefix);
+    this.promptService = new PromptService(options.config?.prompts);
+    this.ingestionService = new IngestionService(
+      this.db,
+      this.prefix,
+      this.options,
+      this.entryRepo,
+      this.searchService,
+      this.jobManager,
+      this.embeddingService,
+      this.promptService
     );
-    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}`);
-    }
-    const jobKey = `${this.prefix}:${entityId}:${sourceRef}`;
-    if (this.activeIngestJobs.has(jobKey)) {
-      throw new WikiBusyError("ingest", entityId);
+    this.maintenanceService = new MaintenanceService(
+      this.db,
+      this.prefix,
+      this.options,
+      this.entryRepo,
+      this.taskRepo,
+      this.eventRepo,
+      this.metadataRepo,
+      this.searchService,
+      this.jobManager,
+      this.embeddingService,
+      this.promptService
+    );
+    this.importExportService = new ImportExportService(
+      this.db,
+      this.entryRepo,
+      this.taskRepo,
+      this.eventRepo,
+      this.metadataRepo,
+      this.searchService,
+      this.jobManager,
+      this.embeddingService
+    );
+    this.retrievalService = new RetrievalService(
+      this.options,
+      this.entryRepo,
+      this.taskRepo,
+      this.eventRepo,
+      this.metadataRepo,
+      this.searchService
+    );
+    this.writeService = new WriteService(
+      this.db,
+      this.options,
+      this.eventRepo,
+      this.metadataRepo,
+      this.jobManager,
+      this.maintenanceService
+    );
+  }
+  /**
+   * Explicit escape hatch for test suites: typed access to composed services for mocks/spies.
+   * If `NODE_ENV` is not `"test"`, emits a single `console.warn` per instance (skipped when `process` is undefined).
+   */
+  get __testAccess() {
+    const processEnv = typeof globalThis !== "undefined" ? globalThis.process?.env : void 0;
+    if (processEnv !== void 0 && processEnv.NODE_ENV !== "test" && !__privateGet(this, _testAccessNonTestEnvWarned)) {
+      __privateSet(this, _testAccessNonTestEnvWarned, true);
+      console.warn('Warning: WikiMemory.__testAccess is intended for tests (NODE_ENV !== "test").');
     }
-    if (this.activeMaintenanceJobs.has(this._pruneKey(entityId))) {
-      throw new WikiBusyError("prune", entityId);
+    return {
+      embeddingService: this.embeddingService,
+      importExportService: this.importExportService,
+      ingestionService: this.ingestionService,
+      maintenanceService: this.maintenanceService,
+      retrievalService: this.retrievalService,
+      searchService: this.searchService,
+      writeService: this.writeService,
+      promptService: this.promptService,
+      entryRepo: this.entryRepo,
+      metadataRepo: this.metadataRepo,
+      jobManager: this.jobManager
+    };
+  }
+  async setup() {
+    const entriesExistedBeforeSetup = await this.metadataRepo.tableExists(`${this.prefix}entries`);
+    await setupDatabase(this.db, this.prefix);
+    let currentVersion;
+    if (!entriesExistedBeforeSetup) {
+      await this.metadataRepo.setMeta("schema_version", String(CURRENT_SCHEMA_VERSION), this.db);
+      currentVersion = CURRENT_SCHEMA_VERSION;
+    } else {
+      const schemaVersionValue = await this.metadataRepo.getMeta("schema_version");
+      if (schemaVersionValue) {
+        currentVersion = parseInt(schemaVersionValue, 10);
+        if (!Number.isFinite(currentVersion)) currentVersion = 0;
+      } else {
+        const ftsDdl = await this.metadataRepo.getTableDdl(`${this.prefix}entries_fts`);
+        const hasPorter = /tokenize\s*=\s*['"]porter\s+unicode61['"]/i.test(ftsDdl ?? "");
+        currentVersion = hasPorter ? 1 : 0;
+      }
     }
-    if (this._isReembedActive(entityId)) {
-      throw new WikiBusyError("reembed", entityId);
+    for (const migration of MIGRATIONS) {
+      if (migration.version > currentVersion) {
+        await migration.run(this.db, this.prefix);
+        await this.metadataRepo.setMeta("schema_version", String(migration.version), this.db);
+        currentVersion = migration.version;
+      }
     }
-    if (this._isImportActiveFor(entityId)) {
-      throw new WikiBusyError("import", entityId);
+    if (entriesExistedBeforeSetup) {
+      const schemaVersionCheck = await this.metadataRepo.getMeta("schema_version");
+      if (!schemaVersionCheck) {
+        await this.metadataRepo.setMeta("schema_version", String(currentVersion), this.db);
+      }
     }
-    if (this._isForgetActiveFor(entityId)) {
-      throw new WikiBusyError("forget", entityId);
+    if (entriesExistedBeforeSetup) {
+      await this.importExportService.assertNoLegacySourceTypes();
     }
-    this.activeIngestJobs.add(jobKey);
-    this._notifyStatusSubscribers(entityId);
-    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 userPrompt = `Document Chunk:
-${chunk}`;
-          const responseText = await this.options.llmProvider.generateText({
-            systemPrompt: INGEST_SYSTEM_PROMPT,
-            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.rebuildMiniSearchIndex(entityId);
-      this.vectorCache.delete(entityId);
-      const uniqueDeletedSourceFactIds = Array.from(new Set(deletedSourceFactIds));
-      for (const factId of uniqueDeletedSourceFactIds) {
-        try {
-          await this._notifyEmbeddingPersisted(entityId, factId, null);
-        } catch (hookErr) {
-          console.warn(`[WikiMemory] onEmbeddingPersisted hook failed during ingest for ${factId}:`, hookErr);
+    const rows = await this.entryRepo.findRowsForSourceRefMigration();
+    await this.db.withTransactionAsync(async (tx) => {
+      for (const row of rows) {
+        const normalized = normalizeSourceRef(row.source_ref);
+        if (normalized !== row.source_ref) {
+          await this.entryRepo.updateSourceRefByRowid(row.rowid, normalized, tx);
         }
       }
-      for (const fact of insertedFacts) {
-        await this.embedFact(fact);
-      }
-      this.vectorCache.delete(entityId);
-      return { truncated, chunks: chunks.length };
-    } finally {
-      this.activeIngestJobs.delete(jobKey);
-      this._notifyStatusSubscribers(entityId);
+    });
+    await this.searchService.sync();
+  }
+  async hasChanged(entityId, sourceRef, sourceHash) {
+    const normalizedRef = normalizeSourceRef(sourceRef);
+    if (!normalizedRef) {
+      throw new Error(`Invalid sourceRef: "${sourceRef}"`);
+    }
+    const normalizedHash = normalizeSourceHash(sourceHash);
+    if (!normalizedHash) {
+      throw new Error(`Invalid sourceHash: must be a 64-character hex string (normalized to lowercase)`);
     }
+    const storedHash = await this.entryRepo.findLatestSourceHash(entityId, normalizedRef);
+    if (storedHash === null) return true;
+    const normalizedStoredHash = normalizeSourceHash(storedHash);
+    return normalizedStoredHash !== normalizedHash;
+  }
+  async runPrune(entityId, options) {
+    return this.maintenanceService.runPrune(entityId, options);
+  }
+  async read(entityId, query, options) {
+    return this.retrievalService.read(entityId, query, options);
+  }
+  async getMemoryBundle(entityId) {
+    return this.importExportService.getFullBundle(entityId, { maxEvents: 10 });
+  }
+  async write(entityId, event) {
+    return this.writeService.write(entityId, event);
+  }
+  /**
+   * @param options.promptOverride - Applies only to this manual call. Does NOT affect
+   * WriteService-triggered auto-runs. For persistent prompt customization across auto-runs,
+   * set `options.config.prompts.librarianSystemPrompt` at WikiMemory construction time.
+   */
+  async runLibrarian(entityId, options) {
+    return this.maintenanceService.runLibrarian(entityId, options);
+  }
+  /**
+   * @param options.promptOverride - Applies only to this manual call. Does NOT affect
+   * WriteService-triggered auto-runs. For persistent prompt customization across auto-runs,
+   * set `options.config.prompts.healSystemPrompt` at WikiMemory construction time.
+   */
+  async runHeal(entityId, options) {
+    return this.maintenanceService.runHeal(entityId, options);
+  }
+  async runReembed(entityId, opts) {
+    return this.maintenanceService.runReembed(entityId, opts);
+  }
+  getEntityStatus(entityId) {
+    return this.jobManager.getEntityStatus(entityId);
+  }
+  subscribeEntityStatus(entityId, callback) {
+    return this.jobManager.subscribeEntityStatus(entityId, callback);
+  }
+  clearVectorCache() {
+    this.searchService.evictCache();
+  }
+  async exportDump(entityIds) {
+    return this.importExportService.exportDump(entityIds);
+  }
+  async importDump(dump, opts) {
+    return this.importExportService.importDump(dump, opts);
+  }
+  async forget(entityId, params) {
+    return this.maintenanceService.forget(entityId, params);
+  }
+  /**
+   * @param params.promptOverride - Overrides the system prompt for this ingest call only.
+   * For persistent customization, set `options.config.prompts.ingestSystemPrompt` at
+   * WikiMemory construction time.
+   */
+  async ingestDocument(entityId, params) {
+    return this.ingestionService.ingestDocument(entityId, params);
   }
 };
-/**
- * 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).
- */
-_WikiMemory.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.
- */
-_WikiMemory.MAX_VECTOR_CACHE_FACTS_PER_ENTITY = 500;
-var WikiMemory = _WikiMemory;
+_testAccessNonTestEnvWarned = new WeakMap();
 
 // src/utils/formatContext.ts
 function validateMaxOption(value, name) {
@@ -3989,6 +4419,8 @@ function createWiki(db, options) {
 }
 
 exports.DEFAULT_LIBRARIAN_SYNTHESIS_PROMPT = DEFAULT_LIBRARIAN_SYNTHESIS_PROMPT;
+exports.HOOK_TIMEOUT_MARKER = HOOK_TIMEOUT_MARKER;
+exports.PromptService = PromptService;
 exports.PrunePartialFailureError = PrunePartialFailureError;
 exports.WikiBusyError = WikiBusyError;
 exports.WikiMemory = WikiMemory;