@equationalapplications/core-llm-wiki 4.7.0 → 4.8.0

package/dist/index.mjs

@@ -1,4 +1,5 @@
-import MiniSearch from 'minisearch';
+import { __privateAdd, EmbeddingService, SearchService, JobManager, PromptService, IngestionService, MaintenanceService, ImportExportService, RetrievalService, WriteService, __privateGet, __privateSet, normalizeSourceRef, normalizeSourceHash, generateId } from './chunk-2FGDZKC2.mjs';
+export { HOOK_TIMEOUT_MARKER, PromptService, PrunePartialFailureError, WikiBusyError, parseEmbedding } from './chunk-2FGDZKC2.mjs';
 
 // src/db/schema.ts
 async function setupDatabase(db, prefix) {
@@ -149,28 +150,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) {
@@ -214,6 +193,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);
@@ -309,21 +310,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.
@@ -503,7 +490,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);
@@ -513,6 +500,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.
@@ -599,24 +598,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",
@@ -625,11 +619,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);
@@ -661,7 +655,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;
@@ -684,7 +678,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;
@@ -905,19 +899,6 @@ var EntryRepository = class extends BaseRepository {
   }
 };
 
-// src/utils/ids.ts
-function generateId(prefix = "") {
-  if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") {
-    return prefix + crypto.randomUUID().replace(/-/g, "").substring(0, 24);
-  }
-  if (typeof crypto !== "undefined" && typeof crypto.getRandomValues === "function") {
-    const bytes = new Uint8Array(16);
-    crypto.getRandomValues(bytes);
-    return prefix + Array.from(bytes).map((b) => b.toString(16).padStart(2, "0")).join("").substring(0, 24);
-  }
-  return prefix + Math.random().toString(36).substring(2, 15) + Math.random().toString(36).substring(2, 15);
-}
-
 // src/repositories/OutboxRepository.ts
 var OutboxRepository = class extends BaseRepository {
   /**
@@ -1414,322 +1395,12 @@ 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;
-  const len = Math.min(a.length, b.length);
-  for (let i = 0; i < len; i++) {
-    dot += a[i] * b[i];
-    normA += a[i] * a[i];
-    normB += b[i] * b[i];
-  }
-  const denom = Math.sqrt(normA) * Math.sqrt(normB);
-  return denom === 0 ? 0 : dot / denom;
-}
-
-// src/utils/embedding.ts
-function parseEmbedding(blob, text) {
-  if (blob && blob.byteLength > 0) {
-    if (blob.byteLength % 4 !== 0) return null;
-    const copy = new ArrayBuffer(blob.byteLength);
-    new Uint8Array(copy).set(blob);
-    const vector = new Float32Array(copy);
-    for (const value of vector) {
-      if (!Number.isFinite(value)) return null;
-    }
-    return vector;
-  }
-  if (text) {
-    try {
-      const arr = JSON.parse(text);
-      if (!Array.isArray(arr) || !arr.every((v) => typeof v === "number" && isFinite(v))) return null;
-      const vector = new Float32Array(arr);
-      for (const value of vector) {
-        if (!Number.isFinite(value)) return null;
-      }
-      return vector;
-    } catch {
-      return null;
-    }
-  }
-  return null;
-}
-
-// src/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/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");
-  }
-  let depth = 0;
-  let inString = false;
-  let escape = false;
-  let end = -1;
-  for (let i = start; i < text.length; i++) {
-    const ch = text[i];
-    if (escape) {
-      escape = false;
-      continue;
-    }
-    if (ch === "\\" && inString) {
-      escape = true;
-      continue;
-    }
-    if (ch === '"') {
-      inString = !inString;
-      continue;
-    }
-    if (inString) continue;
-    if (ch === openChar) {
-      depth++;
-      continue;
-    }
-    if (ch === closeChar) {
-      depth--;
-      if (depth === 0) {
-        end = i;
-        break;
-      }
-    }
-  }
-  if (end === -1) throw new SyntaxError("No JSON object/array found in LLM response");
-  return JSON.parse(text.slice(start, end + 1));
-}
-function 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 {
+var _testAccessNonTestEnvWarned;
+var WikiMemory = class {
   constructor(db, options) {
-    this.activeMaintenanceJobs = /* @__PURE__ */ new Set();
-    this.activeIngestJobs = /* @__PURE__ */ new Set();
-    this.statusSubscribers = /* @__PURE__ */ new Map();
-    this.miniSearch = new MiniSearch({
-      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();
+    /** 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_";
@@ -1738,210 +1409,83 @@ var _WikiMemory = class _WikiMemory {
     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,
-      entity_id: row.entity_id,
-      title: row.title,
-      body: row.body,
-      tags: (() => {
-        try {
-          const parsed = JSON.parse(row.tags);
-          return Array.isArray(parsed) ? parsed.join(" ") : row.tags;
-        } catch {
-          return row.tags;
-        }
-      })()
-    };
-  }
-  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);
-    }
-  }
-  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);
-    }
-  }
-  /**
-   * 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);
-    }
-  }
-  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)`
+    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
+    );
+    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
     );
   }
-  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.`
-    );
-  }
-  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.
+   * 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).
    */
-  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);
+  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").');
     }
+    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`);
@@ -1975,7 +1519,7 @@ After running the migration SQL, restart your application.`
       }
     }
     if (entriesExistedBeforeSetup) {
-      await this.assertNoLegacySourceTypes();
+      await this.importExportService.assertNoLegacySourceTypes();
     }
     const rows = await this.entryRepo.findRowsForSourceRefMigration();
     await this.db.withTransactionAsync(async (tx) => {
@@ -1986,7 +1530,7 @@ After running the migration SQL, restart your application.`
         }
       }
     });
-    await this.rebuildMiniSearchIndex();
+    await this.searchService.sync();
   }
   async hasChanged(entityId, sourceRef, sourceHash) {
     const normalizedRef = normalizeSourceRef(sourceRef);
@@ -2002,1720 +1546,65 @@ After running the migration SQL, restart your application.`
     const normalizedStoredHash = normalizeSourceHash(storedHash);
     return normalizedStoredHash !== normalizedHash;
   }
-  _pruneKey(entityId) {
-    return `${this.prefix}:${entityId}:prune`;
-  }
-  _reembedKey(entityId) {
-    return `${this.prefix}:${entityId}:reembed`;
-  }
-  _globalReembedKey() {
-    return `${this.prefix}:reembed`;
-  }
-  _importKey(entityId) {
-    return `${this.prefix}:${entityId}:import`;
-  }
-  _globalImportKey() {
-    return `${this.prefix}:import`;
-  }
-  _forgetKey(entityId) {
-    return `${this.prefix}:${entityId}:forget`;
-  }
-  _isReembedActive(entityId) {
-    return this.activeMaintenanceJobs.has(this._reembedKey(entityId)) || this.activeMaintenanceJobs.has(this._globalReembedKey());
-  }
-  _isImportActiveFor(entityId) {
-    return this.activeMaintenanceJobs.has(this._importKey(entityId)) || this.activeMaintenanceJobs.has(this._globalImportKey());
-  }
-  _isForgetActiveFor(entityId) {
-    return this.activeMaintenanceJobs.has(this._forgetKey(entityId));
-  }
-  /** 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) {
-      if (k.startsWith(entityKeyPrefix) && k.endsWith(suffix)) return true;
-    }
-    return false;
-  }
-  /** Returns true if any ingest job is active for the given entity. */
-  _isIngestActiveFor(entityId) {
-    const entityKeyPrefix = `${this.prefix}:${entityId}:`;
-    for (const k of this.activeIngestJobs) {
-      if (k.startsWith(entityKeyPrefix)) return true;
-    }
-    return false;
-  }
-  _copyEntityStatus(s) {
-    return { ingesting: s.ingesting, librarian: s.librarian, heal: s.heal };
-  }
-  _notifyStatusSubscribers(entityId) {
-    const set = this.statusSubscribers.get(entityId);
-    if (!set || set.size === 0) return;
-    for (const entry of Array.from(set)) {
-      if (!set.has(entry)) continue;
-      const next = this.getEntityStatus(entityId);
-      if (entry.last.ingesting === next.ingesting && entry.last.librarian === next.librarian && entry.last.heal === next.heal) continue;
-      entry.last = this._copyEntityStatus(next);
-      try {
-        entry.callback(this._copyEntityStatus(next));
-      } catch (err) {
-        console.error(`[WikiMemory.subscribeEntityStatus] 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`);
-    }
-  }
   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;
-        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 (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);
-    }
+    return this.maintenanceService.runPrune(entityId, options);
   }
   async read(entityId, query, options) {
-    const config = this.options.config;
-    const entityIds = normalizeEntityIds(entityId);
-    const sanitizedTierWeights = shouldExposeReadMetadata(entityId) ? sanitizeTierWeights(entityIds, options?.tierWeights) : void 0;
-    const exposeMetadata = shouldExposeReadMetadata(entityId);
-    if (entityIds.length === 0) {
-      const empty = { facts: [], tasks: [], events: [] };
-      if (exposeMetadata) {
-        empty.metadata = { query, entityIds: [] };
-        if (sanitizedTierWeights && Object.keys(sanitizedTierWeights).length > 0) empty.metadata.tierWeights = sanitizedTierWeights;
-      }
-      return empty;
-    }
-    const MAX_ENTITY_IDS = 100;
-    if (entityIds.length > MAX_ENTITY_IDS) {
-      throw new RangeError(`read() accepts at most ${MAX_ENTITY_IDS} entity IDs; received ${entityIds.length}`);
-    }
-    const nullByteId = entityIds.find((id) => id.includes("\0"));
-    if (nullByteId !== void 0) {
-      throw new TypeError(`entity_id values must not contain the null byte (\\x00); got "${nullByteId}"`);
-    }
-    const rawMaxResults = options?.maxResults ?? config?.maxResults ?? config?.maxFtsResults ?? 10;
-    const maxResults = Number.isFinite(rawMaxResults) ? Math.max(0, Math.trunc(rawMaxResults)) : 10;
-    const rawPreFilterLimit = options?.preFilterLimit === null ? void 0 : options?.preFilterLimit ?? config?.preFilterLimit;
-    const effectivePreFilterLimit = rawPreFilterLimit === void 0 ? void 0 : Number.isFinite(rawPreFilterLimit) ? Math.max(0, Math.trunc(rawPreFilterLimit)) : void 0;
-    const hybridWeight = options?.hybridWeight ?? config?.hybridWeight;
-    const weight = hybridWeight !== void 0 && !Number.isNaN(hybridWeight) ? Math.max(0, Math.min(1, hybridWeight)) : void 0;
-    const skipEmbed = weight === 0;
-    const embedFn = this.options.llmProvider.embed;
-    const trimmedQuery = query.trim();
-    let facts = [];
-    let scoreByFactId;
-    if (maxResults === 0) ; else if (trimmedQuery) {
-      let usedEmbed = false;
-      const scoredEntityIds = this._filterScoredEntities(entityIds, sanitizedTierWeights, options?.includeZeroWeightEntities);
-      if (scoredEntityIds.length === 0) {
-        usedEmbed = true;
-      } else if (!skipEmbed && embedFn) {
-        let rankerShouldRethrow = false;
-        let pendingRankerFallbackError;
-        try {
-          const queryVec = await embedFn(trimmedQuery);
-          if (queryVec.length === 0 || !queryVec.every((v) => typeof v === "number" && isFinite(v))) {
-            throw new Error(
-              "embed() returned an empty or non-finite vector. Falling back to keyword search."
-            );
-          }
-          const storedDimValue = await this.metadataRepo.getMeta("embedding_dimension");
-          if (storedDimValue) {
-            const storedDim = parseInt(storedDimValue, 10);
-            if (storedDim !== queryVec.length) {
-              throw new Error(
-                `Embedding dimension mismatch: stored ${storedDim}, query has ${queryVec.length}. Call runReembed() to rebuild embeddings with the new model.`
-              );
-            }
-          }
-          const mismatchedCount = await this.entryRepo.countDimensionMismatched(scoredEntityIds, queryVec.length);
-          if (mismatchedCount > 0) {
-            throw new Error(
-              `Some facts have embeddings that do not match the current model dimension. Call runReembed() to rebuild all embeddings consistently.`
-            );
-          }
-          const useRanker = Boolean(this.options.vectorRanker);
-          let candidateRows;
-          let populateCache = entityIds.length === 1;
-          let miniSearchScores;
-          if (effectivePreFilterLimit !== void 0) {
-            populateCache = false;
-            const 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;
-          }
-          if (pendingRankerFallbackError) {
-            error.cause = pendingRankerFallbackError;
-            pendingRankerFallbackError = void 0;
-          }
-          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 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 (facts.length > 0) {
-        const ids = facts.map((f) => f.id);
-        const now = Date.now();
-        await this.entryRepo.trackAccess(ids, now);
-      }
-    } else {
-      facts = await this.entryRepo.findRecentByEntityIds(entityIds, maxResults);
-    }
-    const eventsLimit = Math.min(10 * entityIds.length, 100);
-    const [tasks, events] = await Promise.all([
-      this.taskRepo.findAllPending(entityIds, entityIds.length === 1 ? void 0 : Math.min(20 * entityIds.length, 200)),
-      entityIds.length === 1 ? this.eventRepo.getRecent(entityIds[0], eventsLimit) : this.eventRepo.getRecentForEntities(entityIds, eventsLimit)
-    ]);
-    let factScores;
-    if (exposeMetadata && trimmedQuery && scoreByFactId) {
-      factScores = Object.fromEntries(facts.map((fact) => [fact.id, scoreByFactId.get(fact.id) ?? 0]));
-    }
-    const bundle = { facts, tasks, events: events.reverse() };
-    if (exposeMetadata) {
-      bundle.metadata = { query, entityIds };
-      if (sanitizedTierWeights && Object.keys(sanitizedTierWeights).length > 0) bundle.metadata.tierWeights = sanitizedTierWeights;
-      if (factScores && Object.keys(factScores).length > 0) bundle.factScores = factScores;
-    }
-    return bundle;
-  }
-  /**
-   * Returns entity IDs that will participate in scored retrieval.
-   * Excludes zero-weight entities unless includeZeroWeightEntities is true.
-   */
-  _filterScoredEntities(entityIds, sanitizedTierWeights, includeZeroWeightEntities) {
-    return entityIds.filter((id) => {
-      const w = sanitizedTierWeights?.[id] ?? 1;
-      return includeZeroWeightEntities === true || w !== 0;
-    });
-  }
-  /**
-   * Stable tie-break sort: score desc → access_count desc → updated_at desc → id asc.
-   */
-  _tieBreakSort(items) {
-    items.sort((a, b) => this._compareScoredRows(a, b));
+    return this.retrievalService.read(entityId, query, options);
   }
-  /**
-   * 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);
+  async getMemoryBundle(entityId) {
+    return this.importExportService.getFullBundle(entityId, { maxEvents: 10 });
   }
-  /**
-   * 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);
+  async write(entityId, event) {
+    return this.writeService.write(entityId, event);
   }
   /**
-   * 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.
+   * @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.
    */
-  _sanitizeRankerError(err) {
-    if (this.options.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;
+  async runLibrarian(entityId, options) {
+    return this.maintenanceService.runLibrarian(entityId, options);
   }
   /**
-   * Score candidate rows using in-process JS cosine similarity.
-   * Applies hybrid blending (if weight set) and tie-break sorting before returning.
+   * @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 _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();
-    }
-    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 >= _WikiMemory.MAX_VECTOR_CACHE_ENTITIES) {
-          const oldestKey = this.vectorCache.keys().next().value;
-          if (oldestKey !== void 0) this.vectorCache.delete(oldestKey);
-        }
-        this.vectorCache.set(entityId, entityCache);
-      }
-    }
-    if (!skipSort) this._tieBreakSort(scored);
-    return scored.slice(0, limit);
-  }
-  /**
-   * Delegate semantic ranking to the injected VectorRanker.
-   * Caller should pass an oversampledLimit to preserve recall after re-ranking.
-   * Returns scored results ready for hybrid blending and tie-break sorting.
-   */
-  async _rankWithVectorRanker(args) {
-    const { entityId, candidateIds, candidateRows, weight, miniSearchScores, limit } = args;
-    const ranker = this.options.vectorRanker;
-    if (!ranker) {
-      throw new Error("vectorRanker not configured");
-    }
-    const queryVecCopy = args.queryVec instanceof Float32Array ? args.queryVec.slice() : Array.from(args.queryVec);
-    const rankerResults = await ranker.rankBySimilarity({
-      entityId,
-      queryVec: queryVecCopy,
-      candidateIds,
-      limit
-    });
-    const allowedIds = new Set(candidateRows.map((row) => row.id));
-    const seen = /* @__PURE__ */ new Set();
-    const normalized = [];
-    for (const r of rankerResults) {
-      if (normalized.length >= limit) break;
-      if (seen.has(r.id)) continue;
-      if (allowedIds && !allowedIds.has(r.id)) continue;
-      if (!Number.isFinite(r.semanticScore)) continue;
-      seen.add(r.id);
-      normalized.push(r);
-    }
-    const entityIdByCandidateId = new Map(candidateRows.map((row) => [row.id, row.entity_id]));
-    const scored = normalized.map((r) => {
-      let score = r.semanticScore;
-      if (weight !== void 0) {
-        const kwScore = miniSearchScores?.get(r.id) ?? 0;
-        score = weight * Math.max(0, r.semanticScore) + (1 - weight) * kwScore;
-      }
-      return {
-        id: r.id,
-        entity_id: entityIdByCandidateId.get(r.id),
-        // allowedIds filter above guarantees membership
-        score
-      };
-    });
-    return scored;
-  }
-  async getMemoryBundle(entityId) {
-    return this._getFullBundle(entityId, { maxEvents: 10 });
-  }
-  async write(entityId, event) {
-    const id = generateId("evt_");
-    const now = Date.now();
-    let eventType = event.event_type;
-    if (!["observation", "decision", "action", "outcome"].includes(eventType)) {
-      eventType = "observation";
-    }
-    const newEvent = {
-      id,
-      entity_id: entityId,
-      event_type: eventType,
-      summary: event.summary,
-      related_entry_id: event.related_entry_id || null,
-      created_at: now
-    };
-    let shouldRunLibrarian = false;
-    let librarianCount = 0;
-    let 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);
-        }
-      }
-    });
-    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);
-        try {
-          await this._doRunHeal(entityId);
-          await this.metadataRepo.updateCheckpoint(entityId, { heal: currentEventCount }, this.db);
-        } finally {
-          this.activeMaintenanceJobs.delete(healKey);
-          this._notifyStatusSubscribers(entityId);
-        }
-      }
-    }
-  }
-  async _doRunLibrarian(entityId) {
-    const events = await this.eventRepo.getRecent(entityId, 50);
-    const currentFactsRows = await this.entryRepo.findRecentByEntityId(entityId, 100);
-    const currentFacts = currentFactsRows.map((f) => {
-      const { embedding: _embedding, embedding_blob: _blob, ...rest } = f;
-      return {
-        ...rest,
-        tags: typeof rest.tags === "string" ? JSON.parse(rest.tags) : rest.tags
-      };
-    });
-    const 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 result = parseJsonResponse(responseText);
-    const facts = Array.isArray(result.facts) ? result.facts : [];
-    const tasks = Array.isArray(result.tasks) ? result.tasks : [];
-    const validFacts = facts.map(validateFact).filter((f) => f !== null);
-    const validTasks = tasks.map(validateTask).filter((t) => t !== null);
-    const now = Date.now();
-    const insertedFacts = [];
-    await this.db.withTransactionAsync(async (tx) => {
-      const factsForDedupe = await this.entryRepo.findRecentByEntityId(entityId, 100, tx);
-      for (const fact of validFacts) {
-        const newTokens = titleTokens(fact.title);
-        let skip = false;
-        if (newTokens.size >= MIN_TOKENS_TO_QUALIFY) {
-          for (const existing of factsForDedupe) {
-            if (existing.source_type !== "librarian_inferred") continue;
-            const existingTokens = titleTokens(existing.title);
-            if (existingTokens.size >= MIN_TOKENS_TO_QUALIFY) {
-              if (jaccardScore(newTokens, existingTokens) >= FUZZY_THRESHOLD) {
-                skip = true;
-                break;
-              }
-            }
-          }
-        }
-        if (skip) continue;
-        const id = generateId("fact_");
-        const factObj = {
-          id,
-          entity_id: entityId,
-          title: fact.title,
-          body: fact.body,
-          tags: fact.tags,
-          confidence: fact.confidence,
-          source_type: "librarian_inferred",
-          source_hash: null,
-          source_ref: null,
-          created_at: now,
-          updated_at: now,
-          last_accessed_at: null,
-          access_count: 0,
-          deleted_at: null
-        };
-        await this.entryRepo.upsert(factObj, tx);
-        insertedFacts.push({ id, entity_id: entityId, title: fact.title, body: fact.body, tags: JSON.stringify(fact.tags) });
-      }
-      for (const task of validTasks) {
-        const id = generateId("task_");
-        const taskObj = { id, entity_id: entityId, description: task.description, status: "pending", priority: task.priority, created_at: now, updated_at: now, resolved_at: null, deleted_at: null };
-        await this.taskRepo.upsert(taskObj, tx);
-      }
-    });
-    await this.rebuildMiniSearchIndex(entityId);
-    this.vectorCache.delete(entityId);
-    for (const fact of insertedFacts) {
-      await this.embedFact(fact);
-    }
-    this.vectorCache.delete(entityId);
-  }
-  async _doRunHeal(entityId) {
-    const now = Date.now();
-    const orphanAfterDays = this.options.config?.orphanAfterDays !== void 0 ? this.options.config.orphanAfterDays : 30;
-    const staleInferredAfterDays = this.options.config?.staleInferredAfterDays !== void 0 ? this.options.config.staleInferredAfterDays : 60;
-    const MS_PER_DAY = 24 * 60 * 60 * 1e3;
-    if (orphanAfterDays !== null && (typeof orphanAfterDays !== "number" || !Number.isFinite(orphanAfterDays) || orphanAfterDays < 0)) {
-      throw new Error("Invalid orphanAfterDays: must be a finite number >= 0 or null");
-    }
-    if (staleInferredAfterDays !== null && (typeof staleInferredAfterDays !== "number" || !Number.isFinite(staleInferredAfterDays) || staleInferredAfterDays < 0)) {
-      throw new Error("Invalid staleInferredAfterDays: must be a finite number >= 0 or null");
-    }
-    await this.db.withTransactionAsync(async (tx) => {
-      if (orphanAfterDays !== null) {
-        const orphanThreshold = now - orphanAfterDays * MS_PER_DAY;
-        await this.entryRepo.markOrphaned(entityId, orphanThreshold, tx);
-      }
-      if (staleInferredAfterDays !== null) {
-        const staleThreshold = now - staleInferredAfterDays * MS_PER_DAY;
-        await this.entryRepo.downgradeStaleInferred(entityId, staleThreshold, tx);
-      }
-    });
-    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 { 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 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 validNewFacts = newFacts.map(validateFact).filter((f) => f !== null);
-    const insertedFacts = [];
-    const uniqueDeletedFactIds = Array.from(new Set(safeDeleted));
-    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 id = generateId("fact_");
-        const factObj = {
-          id,
-          entity_id: entityId,
-          title: fact.title,
-          body: fact.body,
-          tags: fact.tags,
-          confidence: fact.confidence,
-          source_type: "librarian_inferred",
-          source_hash: null,
-          source_ref: null,
-          created_at: now,
-          updated_at: now,
-          last_accessed_at: null,
-          access_count: 0,
-          deleted_at: null
-        };
-        await this.entryRepo.upsert(factObj, tx);
-        insertedFacts.push({ id, entity_id: entityId, title: fact.title, body: fact.body, tags: JSON.stringify(fact.tags) });
-      }
-    });
-    this.vectorCache.delete(entityId);
-    await this.rebuildMiniSearchIndex(entityId);
-    for (const factId of uniqueDeletedFactIds) {
-      try {
-        await this._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);
-    }
-    this.vectorCache.delete(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);
-    }
-  }
-  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);
-    }
+  async runHeal(entityId, options) {
+    return this.maintenanceService.runHeal(entityId, options);
   }
   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);
-    }
+    return this.maintenanceService.runReembed(entityId, opts);
   }
   getEntityStatus(entityId) {
-    const ingestPrefix = `${this.prefix}:${entityId}:`;
-    let ingesting = false;
-    for (const k of this.activeIngestJobs) {
-      if (k.startsWith(ingestPrefix)) {
-        ingesting = true;
-        break;
-      }
-    }
-    return {
-      ingesting,
-      librarian: this.activeMaintenanceJobs.has(this._librarianKey(entityId)),
-      heal: this.activeMaintenanceJobs.has(this._healKey(entityId))
-    };
+    return this.jobManager.getEntityStatus(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 entry = { callback, last: this._copyEntityStatus(initial) };
-    set.add(entry);
-    try {
-      callback(this._copyEntityStatus(initial));
-    } catch (err) {
-      console.error(`[WikiMemory.subscribeEntityStatus] 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);
-    };
+    return this.jobManager.subscribeEntityStatus(entityId, callback);
   }
   clearVectorCache() {
-    this.vectorCache.clear();
-  }
-  async _getFullBundle(entityId, opts) {
-    const [factsRaw, tasks, events] = await Promise.all([
-      this.entryRepo.findAllByEntityId(entityId),
-      this.taskRepo.findAllByEntityId(entityId),
-      this.eventRepo.getByEntityId(entityId, opts?.maxEvents)
-    ]);
-    const facts = factsRaw.map((f) => {
-      const { embedding: _embedding, embedding_blob, ...rest } = f;
-      const safeBlobCopy = opts?.includeBlobs && embedding_blob ? (() => {
-        const c = new ArrayBuffer(embedding_blob.byteLength);
-        new Uint8Array(c).set(embedding_blob);
-        return new Uint8Array(c);
-      })() : void 0;
-      const factBase = safeBlobCopy ? { ...rest, embedding_blob: safeBlobCopy } : rest;
-      return {
-        ...factBase,
-        tags: typeof factBase.tags === "string" ? JSON.parse(factBase.tags) : factBase.tags
-      };
-    });
-    return { facts, tasks, events };
+    this.searchService.evictCache();
   }
   async exportDump(entityIds) {
-    let ids;
-    if (entityIds && entityIds.length > 0) {
-      ids = Array.from(new Set(entityIds));
-    } else {
-      ids = await this.metadataRepo.getDistinctEntityIds();
-    }
-    const entities = {};
-    const BATCH = 3;
-    for (let i = 0; i < ids.length; i += BATCH) {
-      const batch = ids.slice(i, i + BATCH);
-      const batchResults = await Promise.all(
-        batch.map(async (id) => [id, await this._getFullBundle(id, { includeBlobs: true })])
-      );
-      for (const [id, bundle] of batchResults) {
-        entities[id] = bundle;
-      }
-    }
-    return { generatedAt: Date.now(), entities };
+    return this.importExportService.exportDump(entityIds);
   }
   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);
-      }
-      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));
-    }
-    try {
-      await this.assertNoLegacySourceTypes();
-      for (const [entityId, bundle] of Object.entries(dump.entities)) {
-        await this._doImportEntity(entityId, bundle, merge);
-      }
-    } finally {
-      this.activeMaintenanceJobs.delete(this._globalImportKey());
-      for (const entityId of entityIds) {
-        this.activeMaintenanceJobs.delete(this._importKey(entityId));
-      }
-    }
-  }
-  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
-        });
-        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;
-            }
-          }
-        }
-        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) {
-            if (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) {
-            if (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);
-      }
-    });
-    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 : []
-        });
-      }
-    }
-    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);
-        }
-      }
-    }
-    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);
-        }
-      }
-    }
-    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);
-        }
-      }
-    } finally {
-      this.vectorCache.delete(entityId);
-    }
+    return this.importExportService.importDump(dump, opts);
   }
   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);
-    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) }
-          );
-        }
-      }
-      return { deleted: { entries: deletedEntries, tasks: deletedTasks } };
-    } finally {
-      this.activeMaintenanceJobs.delete(forgetKey);
-    }
+    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) {
-    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}`);
-    }
-    const jobKey = `${this.prefix}:${entityId}:${sourceRef}`;
-    if (this.activeIngestJobs.has(jobKey)) {
-      throw new WikiBusyError("ingest", 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.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);
-        }
-      }
-      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);
-    }
+    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) {
@@ -3982,6 +1871,6 @@ function createWiki(db, options) {
   return new WikiMemory(db, options);
 }
 
-export { DEFAULT_LIBRARIAN_SYNTHESIS_PROMPT, PrunePartialFailureError, WikiBusyError, WikiMemory, createWiki, formatContext, formatMemoryDump, hydrateLibrarianPrompt, mapLibrarianOptionsToReadOptions, parseEmbedding, validateLibrarianPromptTemplate };
+export { DEFAULT_LIBRARIAN_SYNTHESIS_PROMPT, WikiMemory, createWiki, formatContext, formatMemoryDump, hydrateLibrarianPrompt, mapLibrarianOptionsToReadOptions, validateLibrarianPromptTemplate };
 //# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map