@equationalapplications/core-llm-wiki 4.23.1 → 5.1.0

package/README.md

@@ -92,8 +92,8 @@ const wikiMemory = new WikiMemory(db, {
     maxResults: 10,                    // default: 10
     autoLibrarianThreshold: 20,        // default: 20 — events before librarian auto-runs
     autoHealThreshold: 100,            // default: 100 — events before heal auto-runs
-    maxChunkLength: 12000,             // default: 12000 (char count per ingestDocument chunk)
-    chunkOverlap: 400,                 // default: 400 (overlap between chunks in characters)
+    maxChunkLength: 12000,             // default: 12000 (char count per ingestDocument chunk; exported as DEFAULT_MAX_CHUNK_LENGTH)
+    chunkOverlap: 400,                 // default: 400 (overlap between chunks in characters; exported as DEFAULT_CHUNK_OVERLAP)
     chunkConcurrency: 1,               // default: 1 (parallel LLM calls per ingestDocument)
     pruneRetainSoftDeletedFor: 7,      // default: 7 (days before hard-deleting soft-deleted facts)
     pruneEventsAfter: 30,              // default: 30 (days before hard-deleting old events)
@@ -798,6 +798,33 @@ configureRandomSource(getRandomValues);
 
 `@equationalapplications/expo-llm-wiki` does this automatically on import (main entry and `/factory` subpath). If you use `@equationalapplications/core-llm-wiki` directly on React Native without the expo package, you must call `configureRandomSource()` yourself or polyfill `globalThis.crypto.getRandomValues`.
 
+## Chunking Utilities
+
+`ingestDocument()` splits a document into chunks before extraction. That same chunking is exported as a pure function, so a consumer can reproduce ingest-time chunk boundaries exactly — useful for recovering the passage a fact was extracted from, by re-chunking the source and ranking chunks against the fact's stored embedding.
+
+```typescript
+import {
+  chunkText,
+  safeSlice,
+  DEFAULT_MAX_CHUNK_LENGTH,  // 12000
+  DEFAULT_CHUNK_OVERLAP,     // 400
+} from '@equationalapplications/core-llm-wiki';
+
+const { chunks, truncated } = chunkText(
+  sourceDocument,
+  DEFAULT_MAX_CHUNK_LENGTH,
+  DEFAULT_CHUNK_OVERLAP
+);
+```
+
+`chunkText(input, maxChunkLength, overlap)` returns `{ chunks, truncated }`. It prefers to split on a paragraph break, then a sentence terminator, then whitespace, falling back to a hard cut only when none is found within the window — `truncated` is `true` if any split needed that fallback. Consecutive chunks repeat up to `overlap` characters so context isn't lost at a boundary (less than `overlap` when the previous chunk was shorter than that). Empty/whitespace-only input returns `{ chunks: [], truncated: false }` without validating `maxChunkLength`/`overlap`; otherwise throws if `maxChunkLength` is not an integer >= 2, or if `overlap` is not a non-negative integer < `maxChunkLength`.
+
+`safeSlice(value, start, end?)` slices like `String.prototype.slice` but clamps out-of-range indices, swaps a start-after-end range, and never splits a UTF-16 surrogate pair.
+
+`DEFAULT_MAX_CHUNK_LENGTH` and `DEFAULT_CHUNK_OVERLAP` are the values `ingestDocument()` uses when neither the call nor `WikiConfig` overrides them. Pass the same values your host app configured (`config.maxChunkLength` / `config.chunkOverlap`) to match a non-default ingest.
+
+> **Note:** `ingestDocument()` clamps the resolved overlap — whether it came from `chunkOverlap`, `WikiConfig`, or `DEFAULT_CHUNK_OVERLAP` — to `maxChunkLength - 1`. The clamp is evaluated on every call and is a no-op at the shipped defaults (`400 < 12000 - 1`), but it also bites when a custom `maxChunkLength` alone leaves the resolved overlap too large (e.g. `maxChunkLength: 100` with the default overlap `400` ingests at an effective overlap of `99`). That clamp is internal: passing the unclamped pair straight to `chunkText` throws, since it requires `overlap < maxChunkLength`. Apply the same `Math.min(overlap, maxChunkLength - 1)` yourself when re-chunking under a custom config.
+
 ## Adapter Interface
 
 Implement `SQLiteAdapter` to use your platform's SQLite driver:

package/dist/{chunk-MYZJLVX4.mjs → chunk-DM7BKDCV.mjs}

@@ -789,144 +789,6 @@ var JobManager = class {
   }
 };
 
-// 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.`;
-var ONTOLOGY_BACKFILL_SYSTEM_PROMPT = `You are a knowledge classification agent. You will receive existing memory facts that currently have no ontology type. For each input fact { "id", "title", "body", "tags" }, assign the best matching okf_type from the ontology manifest and optionally propose edges to related facts by title.
-Return ONLY a valid JSON object matching this schema:
-{
-  "classifications": [
-    { "id": "string (input fact id, copied verbatim)", "okf_type": "string (manifest node type slug)", "edges": [{ "edge_type": "string", "target_title": "string" }] }
-  ]
-}
-If no manifest type fits a fact, omit that fact from "classifications" entirely \u2014 do not guess.
-Do not return markdown, just raw JSON.`;
-
-// src/services/PromptService.ts
-var PromptService = class {
-  constructor(globalOverrides) {
-    this.globalOverrides = globalOverrides;
-  }
-  hydrate(template, variables) {
-    return template.replace(/\{\{\s*(\w+)\s*\}\}/g, (_match, key) => {
-      const value = variables[key];
-      if (value === void 0) return _match;
-      return typeof value === "string" ? value : JSON.stringify(value, null, 2);
-    });
-  }
-  hasOntologyPlaceholders(template) {
-    return /\{\{\s*ontology(?:Manifest|ModeInstructions)\s*\}\}/.test(template);
-  }
-  buildSystemPrompt(template, variables, ontologyContext) {
-    const shouldHydrate = Object.keys(variables).some(
-      (key) => new RegExp(`\\{\\{\\s*${key}\\s*\\}\\}`).test(template)
-    ) || ontologyContext != null && this.hasOntologyPlaceholders(template);
-    const hydrated = shouldHydrate ? this.hydrate(template, { ...variables, ...ontologyContext ?? {} }) : template;
-    return this.hasOntologyPlaceholders(template) ? ontologyContext != null ? hydrated : hydrated.replace(/\{\{\s*ontology(?:Manifest|ModeInstructions)\s*\}\}/g, "") : this.appendOntology(hydrated, ontologyContext);
-  }
-  appendOntology(systemPrompt, ctx) {
-    if (!ctx) return systemPrompt;
-    return `${systemPrompt}
-
-${ctx.ontologyModeInstructions}`;
-  }
-  buildIngestPrompt(documentChunk, runtimeOverride, ontologyContext) {
-    const template = runtimeOverride ?? this.globalOverrides?.ingestSystemPrompt ?? INGEST_SYSTEM_PROMPT;
-    const hasDocumentChunk = /\{\{\s*documentChunk\s*\}\}/.test(template);
-    if (hasDocumentChunk || this.hasOntologyPlaceholders(template)) {
-      return {
-        systemPrompt: this.buildSystemPrompt(template, { documentChunk }, ontologyContext),
-        userPrompt: hasDocumentChunk ? "Please extract the facts." : `Document Chunk:
-${documentChunk}`
-      };
-    }
-    return {
-      systemPrompt: this.appendOntology(template, ontologyContext),
-      userPrompt: `Document Chunk:
-${documentChunk}`
-    };
-  }
-  buildLibrarianPrompt(events, currentFacts, runtimeOverride, ontologyContext) {
-    const template = runtimeOverride ?? this.globalOverrides?.librarianSystemPrompt ?? LIBRARIAN_SYSTEM_PROMPT;
-    const hasEvents = /\{\{\s*events\s*\}\}/.test(template);
-    const hasCurrentFacts = /\{\{\s*currentFacts\s*\}\}/.test(template);
-    if (hasEvents || hasCurrentFacts || this.hasOntologyPlaceholders(template)) {
-      return {
-        systemPrompt: this.buildSystemPrompt(template, { events, currentFacts }, ontologyContext),
-        userPrompt: hasEvents || hasCurrentFacts ? "Please synthesize the context." : `Events:
-${JSON.stringify(events, null, 2)}
-
-Current Facts:
-${JSON.stringify(currentFacts, null, 2)}`
-      };
-    }
-    return {
-      systemPrompt: this.appendOntology(template, ontologyContext),
-      userPrompt: `Events:
-${JSON.stringify(events, null, 2)}
-
-Current Facts:
-${JSON.stringify(currentFacts, null, 2)}`
-    };
-  }
-  buildHealPrompt(healCandidates, documentAnchors, allTasks, recentEvents, runtimeOverride) {
-    const template = runtimeOverride ?? this.globalOverrides?.healSystemPrompt ?? HEAL_SYSTEM_PROMPT;
-    if (/\{\{\s*healCandidates\s*\}\}/.test(template) || /\{\{\s*documentAnchors\s*\}\}/.test(template) || /\{\{\s*allTasks\s*\}\}/.test(template) || /\{\{\s*recentEvents\s*\}\}/.test(template)) {
-      return {
-        systemPrompt: this.hydrate(template, { healCandidates, documentAnchors, allTasks, recentEvents }),
-        userPrompt: "Please heal the memory graph."
-      };
-    }
-    return {
-      systemPrompt: template,
-      userPrompt: `Heal Candidates:
-${JSON.stringify(healCandidates, null, 2)}
-Document Anchors (DO NOT MODIFY OR DELETE):
-${JSON.stringify(documentAnchors, null, 2)}
-All Tasks:
-${JSON.stringify(allTasks, null, 2)}
-Recent Events:
-${JSON.stringify(recentEvents, null, 2)}
-The following document anchors are provided for contradiction detection only. Do not include them in \`downgraded\`, \`deleted\`, or \`newFacts\`.`
-    };
-  }
-  buildOntologyBackfillPrompt(facts, runtimeOverride, ontologyContext) {
-    const template = runtimeOverride ?? this.globalOverrides?.ontologyBackfillSystemPrompt ?? ONTOLOGY_BACKFILL_SYSTEM_PROMPT;
-    const hasFacts = /\{\{\s*facts\s*\}\}/.test(template);
-    if (hasFacts || this.hasOntologyPlaceholders(template)) {
-      return {
-        systemPrompt: this.buildSystemPrompt(template, { facts }, ontologyContext),
-        userPrompt: hasFacts ? "Please classify the facts." : `Facts:
-${JSON.stringify(facts, null, 2)}`
-      };
-    }
-    return {
-      systemPrompt: this.appendOntology(template, ontologyContext),
-      userPrompt: `Facts:
-${JSON.stringify(facts, null, 2)}`
-    };
-  }
-};
-
 // src/utils/pure.ts
 function parseJsonResponse(text) {
   const firstBrace = text.indexOf("{");
@@ -1142,6 +1004,148 @@ function jaccardScore(a, b) {
   return intersection.size / union.size;
 }
 
+// src/prompts.ts
+var LIBRARIAN_SYSTEM_PROMPT = `You are a knowledge extraction agent. Your job is to analyze recent episodic events and extract stable facts and actionable tasks about the user or entity.
+Return ONLY a valid JSON object matching this schema:
+{
+  "facts": [{ "title": "string (max 80 chars)", "body": "string (max 800 chars)", "tags": ["string"], "confidence": "certain|inferred|tentative" }],
+  "tasks": [{ "description": "string", "priority": "number (0-10)" }]
+}
+Keep facts concise. Do not return markdown, just raw JSON.`;
+var HEAL_SYSTEM_PROMPT = `You are a memory grooming agent. Your job is to review a full dump of facts and recent events to resolve contradictions, downgrade stale claims, and flag obsolete facts for deletion.
+Return ONLY a valid JSON object matching this schema:
+{
+  "downgraded": ["string (fact IDs)"],
+  "deleted": ["string (fact IDs)"],
+  "newFacts": [{ "title": "string (max 80 chars)", "body": "string (max 800 chars)", "tags": ["string"], "confidence": "certain|inferred|tentative" }]
+}
+Do not return markdown, just raw JSON.`;
+var INGEST_SYSTEM_PROMPT = `You are a document ingestion agent. Your job is to extract factual knowledge from the provided document chunk.
+Return ONLY a valid JSON object matching this schema:
+{
+  "facts": [{ "title": "string (max 80 chars)", "body": "string (max 800 chars)", "tags": ["string"], "confidence": "certain|inferred|tentative" }]
+}
+Extract verbatim factual content. Do not return markdown, just raw JSON.`;
+var ONTOLOGY_BACKFILL_SYSTEM_PROMPT = `You are a knowledge classification agent. You will receive existing memory facts that currently have no ontology type. For each input fact { "id", "title", "body", "tags" }, assign the best matching okf_type from the ontology manifest and optionally propose edges to related facts by title.
+Return ONLY a valid JSON object matching this schema:
+{
+  "classifications": [
+    { "id": "string (input fact id, copied verbatim)", "okf_type": "string (manifest node type slug)", "edges": [{ "edge_type": "string", "target_title": "string" }] }
+  ]
+}
+If no manifest type fits a fact, omit that fact from "classifications" entirely \u2014 do not guess.
+Do not return markdown, just raw JSON.`;
+
+// src/services/PromptService.ts
+var PromptService = class {
+  constructor(globalOverrides) {
+    this.globalOverrides = globalOverrides;
+  }
+  hydrate(template, variables) {
+    return template.replace(/\{\{\s*(\w+)\s*\}\}/g, (_match, key) => {
+      const value = variables[key];
+      if (value === void 0) return _match;
+      return typeof value === "string" ? value : JSON.stringify(value, null, 2);
+    });
+  }
+  hasOntologyPlaceholders(template) {
+    return /\{\{\s*ontology(?:Manifest|ModeInstructions)\s*\}\}/.test(template);
+  }
+  buildSystemPrompt(template, variables, ontologyContext) {
+    const shouldHydrate = Object.keys(variables).some(
+      (key) => new RegExp(`\\{\\{\\s*${key}\\s*\\}\\}`).test(template)
+    ) || ontologyContext != null && this.hasOntologyPlaceholders(template);
+    const hydrated = shouldHydrate ? this.hydrate(template, { ...variables, ...ontologyContext ?? {} }) : template;
+    return this.hasOntologyPlaceholders(template) ? ontologyContext != null ? hydrated : hydrated.replace(/\{\{\s*ontology(?:Manifest|ModeInstructions)\s*\}\}/g, "") : this.appendOntology(hydrated, ontologyContext);
+  }
+  appendOntology(systemPrompt, ctx) {
+    if (!ctx) return systemPrompt;
+    return `${systemPrompt}
+
+${ctx.ontologyModeInstructions}`;
+  }
+  buildIngestPrompt(documentChunk, runtimeOverride, ontologyContext) {
+    const template = runtimeOverride ?? this.globalOverrides?.ingestSystemPrompt ?? INGEST_SYSTEM_PROMPT;
+    const hasDocumentChunk = /\{\{\s*documentChunk\s*\}\}/.test(template);
+    if (hasDocumentChunk || this.hasOntologyPlaceholders(template)) {
+      return {
+        systemPrompt: this.buildSystemPrompt(template, { documentChunk }, ontologyContext),
+        userPrompt: hasDocumentChunk ? "Please extract the facts." : `Document Chunk:
+${documentChunk}`
+      };
+    }
+    return {
+      systemPrompt: this.appendOntology(template, ontologyContext),
+      userPrompt: `Document Chunk:
+${documentChunk}`
+    };
+  }
+  buildLibrarianPrompt(events, currentFacts, runtimeOverride, ontologyContext) {
+    const template = runtimeOverride ?? this.globalOverrides?.librarianSystemPrompt ?? LIBRARIAN_SYSTEM_PROMPT;
+    const hasEvents = /\{\{\s*events\s*\}\}/.test(template);
+    const hasCurrentFacts = /\{\{\s*currentFacts\s*\}\}/.test(template);
+    if (hasEvents || hasCurrentFacts || this.hasOntologyPlaceholders(template)) {
+      return {
+        systemPrompt: this.buildSystemPrompt(template, { events, currentFacts }, ontologyContext),
+        userPrompt: hasEvents || hasCurrentFacts ? "Please synthesize the context." : `Events:
+${JSON.stringify(events, null, 2)}
+
+Current Facts:
+${JSON.stringify(currentFacts, null, 2)}`
+      };
+    }
+    return {
+      systemPrompt: this.appendOntology(template, ontologyContext),
+      userPrompt: `Events:
+${JSON.stringify(events, null, 2)}
+
+Current Facts:
+${JSON.stringify(currentFacts, null, 2)}`
+    };
+  }
+  buildHealPrompt(healCandidates, documentAnchors, allTasks, recentEvents, runtimeOverride) {
+    const template = runtimeOverride ?? this.globalOverrides?.healSystemPrompt ?? HEAL_SYSTEM_PROMPT;
+    if (/\{\{\s*healCandidates\s*\}\}/.test(template) || /\{\{\s*documentAnchors\s*\}\}/.test(template) || /\{\{\s*allTasks\s*\}\}/.test(template) || /\{\{\s*recentEvents\s*\}\}/.test(template)) {
+      return {
+        systemPrompt: this.hydrate(template, { healCandidates, documentAnchors, allTasks, recentEvents }),
+        userPrompt: "Please heal the memory graph."
+      };
+    }
+    return {
+      systemPrompt: template,
+      userPrompt: `Heal Candidates:
+${JSON.stringify(healCandidates, null, 2)}
+Document Anchors (DO NOT MODIFY OR DELETE):
+${JSON.stringify(documentAnchors, null, 2)}
+All Tasks:
+${JSON.stringify(allTasks, null, 2)}
+Recent Events:
+${JSON.stringify(recentEvents, null, 2)}
+The following document anchors are provided for contradiction detection only. Do not include them in \`downgraded\`, \`deleted\`, or \`newFacts\`.`
+    };
+  }
+  buildOntologyBackfillPrompt(facts, runtimeOverride, ontologyContext) {
+    const template = runtimeOverride ?? this.globalOverrides?.ontologyBackfillSystemPrompt ?? ONTOLOGY_BACKFILL_SYSTEM_PROMPT;
+    const hasFacts = /\{\{\s*facts\s*\}\}/.test(template);
+    if (hasFacts || this.hasOntologyPlaceholders(template)) {
+      return {
+        systemPrompt: this.buildSystemPrompt(template, { facts }, ontologyContext),
+        userPrompt: hasFacts ? "Please classify the facts." : `Facts:
+${JSON.stringify(facts, null, 2)}`
+      };
+    }
+    return {
+      systemPrompt: this.appendOntology(template, ontologyContext),
+      userPrompt: `Facts:
+${JSON.stringify(facts, null, 2)}`
+    };
+  }
+};
+
+// src/utils/chunkingDefaults.ts
+var DEFAULT_MAX_CHUNK_LENGTH = 12e3;
+var DEFAULT_CHUNK_OVERLAP = 400;
+
 // src/services/IngestionService.ts
 var IngestionService = class {
   constructor(db, prefix, options, entryRepo, searchService, jobManager, embeddingService, promptService, ontologyService) {
@@ -1160,10 +1164,10 @@ var IngestionService = class {
     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 maxChunkLength = params.maxChunkLength ?? this.options.config?.maxChunkLength ?? DEFAULT_MAX_CHUNK_LENGTH;
+    const rawOverlap = params.chunkOverlap ?? this.options.config?.chunkOverlap ?? DEFAULT_CHUNK_OVERLAP;
     const chunkOverlap = Math.min(
-      Number.isFinite(rawOverlap) && rawOverlap >= 0 ? Math.floor(rawOverlap) : 400,
+      Number.isFinite(rawOverlap) && rawOverlap >= 0 ? Math.floor(rawOverlap) : DEFAULT_CHUNK_OVERLAP,
       maxChunkLength - 1
     );
     const rawConcurrency = params.chunkConcurrency ?? this.options.config?.chunkConcurrency ?? 1;
@@ -1569,6 +1573,8 @@ var ONTOLOGY_BACKFILL_RECHECK_MS = 7 * 24 * 60 * 60 * 1e3;
 var HEAL_MAX_ANCHORS = 50;
 var HEAL_ANCHOR_SEARCH_OVERFETCH = 4;
 var HEAL_MAX_PROMPT_CHARS = 4e4;
+var HEAL_BATCH_SIZE = 25;
+var HEAL_RECHECK_MS = 7 * 24 * 60 * 60 * 1e3;
 var MaintenanceService = class {
   constructor(db, prefix, options, entryRepo, taskRepo, eventRepo, metadataRepo, searchService, jobManager, embeddingService, promptService, ontologyService) {
     this.db = db;
@@ -1669,7 +1675,7 @@ var MaintenanceService = class {
   async runHeal(entityId, options) {
     this.jobManager.acquireLock("heal", entityId);
     try {
-      await this.doRunHeal(entityId, options?.promptOverride);
+      return await this.doRunHeal(entityId, options);
     } finally {
       this.jobManager.releaseLock("heal", entityId);
     }
@@ -1921,9 +1927,21 @@ var MaintenanceService = class {
     }
     this.searchService.evictCache(entityId);
   }
-  /** Core heal pass (locks handled by {@link runHeal}). Package-internal orchestration hook. */
-  async doRunHeal(entityId, promptOverride) {
+  /**
+   * Core heal pass (locks handled by {@link runHeal}). Package-internal orchestration hook.
+   *
+   * Bounded: at most `batchSize` candidates per pass (#67). Loop on
+   * `result.remaining > 0` for convergence — see {@link HealResult.remaining}
+   * for what convergence means here.
+   */
+  async doRunHeal(entityId, options) {
+    const promptOverride = options?.promptOverride;
+    const batchSize = options?.batchSize ?? HEAL_BATCH_SIZE;
+    if (!Number.isInteger(batchSize) || batchSize < 1) {
+      throw new Error("Invalid batchSize: must be an integer >= 1");
+    }
     const now = Date.now();
+    const recheckCutoff = now - HEAL_RECHECK_MS;
     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;
@@ -1934,6 +1952,7 @@ var MaintenanceService = class {
       throw new Error("Invalid staleInferredAfterDays: must be a finite number >= 0 or null");
     }
     const orphanedIds = [];
+    const staleDowngradedIds = [];
     await this.db.withTransactionAsync(async (tx) => {
       if (orphanAfterDays !== null) {
         const orphanThreshold = now - orphanAfterDays * MS_PER_DAY;
@@ -1941,7 +1960,7 @@ var MaintenanceService = class {
       }
       if (staleInferredAfterDays !== null) {
         const staleThreshold = now - staleInferredAfterDays * MS_PER_DAY;
-        await this.entryRepo.downgradeStaleInferred(entityId, staleThreshold, tx);
+        staleDowngradedIds.push(...await this.entryRepo.downgradeStaleInferred(entityId, staleThreshold, tx));
       }
     });
     for (const factId of orphanedIds) {
@@ -1951,7 +1970,21 @@ var MaintenanceService = class {
         console.warn(`[WikiMemory] onEmbeddingPersisted hook failed during heal orphan pass for ${factId}:`, hookErr);
       }
     }
-    const healCandidates = await this.entryRepo.findHealCandidatesByEntityId(entityId);
+    const healCandidates = await this.entryRepo.findHealCandidatesByEntityId(entityId, batchSize, recheckCutoff);
+    if (healCandidates.length === 0) {
+      await this.searchService.sync(entityId);
+      this.searchService.evictCache(entityId);
+      const counts2 = await this.entryRepo.countHealCandidatesByEntityId(entityId, recheckCutoff);
+      return {
+        scanned: 0,
+        downgraded: staleDowngradedIds.length,
+        deleted: orphanedIds.length,
+        newFactsCreated: 0,
+        skipped: 0,
+        remaining: counts2.eligible,
+        deferred: counts2.deferred
+      };
+    }
     const allTasks = await this.taskRepo.findAllPending([entityId]);
     const recentEvents = await this.eventRepo.getRecent(entityId, 20);
     const toPromptShape = (f) => {
@@ -2004,7 +2037,7 @@ var MaintenanceService = class {
     const validNewFacts = newFacts.map(validateFact).filter((f) => f !== null);
     const insertedFacts = [];
     const uniqueDeletedFactIds = Array.from(new Set(safeDeleted));
-    const healFactsForDedupe = [...healCandidates];
+    const healFactsForDedupe = (await this.entryRepo.findInferredTitlesByEntityId(entityId)).filter((f) => !safeDeletedSet.has(f.id));
     await this.db.withTransactionAsync(async (tx) => {
       await this.entryRepo.downgradeByIds(safeDowngraded, entityId, tx);
       await this.entryRepo.softDeleteByIds(safeDeleted, entityId, tx);
@@ -2013,7 +2046,6 @@ var MaintenanceService = class {
         let skip = false;
         if (newTokens.size >= MIN_TOKENS_TO_QUALIFY) {
           for (const existing of healFactsForDedupe) {
-            if (existing.source_type !== "librarian_inferred") continue;
             const existingTokens = titleTokens(existing.title);
             if (existingTokens.size >= MIN_TOKENS_TO_QUALIFY) {
               if (jaccardScore(newTokens, existingTokens) >= FUZZY_THRESHOLD) {
@@ -2043,8 +2075,14 @@ var MaintenanceService = class {
         };
         await this.entryRepo.upsert(factObj, tx);
         insertedFacts.push({ id, entity_id: entityId, title: fact.title, body: fact.body, tags: JSON.stringify(fact.tags) });
-        healFactsForDedupe.push(factObj);
+        healFactsForDedupe.push({ id, title: fact.title });
       }
+      await this.entryRepo.markHealChecked(
+        [...healCandidates.map((f) => f.id), ...insertedFacts.map((f) => f.id)],
+        entityId,
+        now,
+        tx
+      );
     });
     await this.searchService.sync(entityId);
     for (const factId of uniqueDeletedFactIds) {
@@ -2058,6 +2096,20 @@ var MaintenanceService = class {
       await this.embeddingService.embedFact(fact);
     }
     this.searchService.evictCache(entityId);
+    let scanned = outcome.skipped.length;
+    for (const batchResult of outcome.results) scanned += batchResult.batch.length;
+    const allDowngraded = /* @__PURE__ */ new Set([...staleDowngradedIds, ...safeDowngraded]);
+    const allDeleted = /* @__PURE__ */ new Set([...orphanedIds, ...uniqueDeletedFactIds]);
+    const counts = await this.entryRepo.countHealCandidatesByEntityId(entityId, recheckCutoff);
+    return {
+      scanned,
+      downgraded: allDowngraded.size,
+      deleted: allDeleted.size,
+      newFactsCreated: insertedFacts.length,
+      skipped: outcome.skipped.length,
+      remaining: counts.eligible,
+      deferred: counts.deferred
+    };
   }
   /** Core ontology backfill pass (locks handled by {@link runOntologyBackfill}). Package-internal orchestration hook. */
   async doRunOntologyBackfill(entityId, options) {
@@ -3433,6 +3485,7 @@ var WriteService = class {
     let shouldRunLibrarian = false;
     let librarianCount = 0;
     let prevMemoryCheckpoint = 0;
+    let eventCount = 0;
     await this.db.withTransactionAsync(async (tx) => {
       await this.eventRepo.add(newEvent, tx);
       const threshold = this.options.config?.autoLibrarianThreshold || 20;
@@ -3440,6 +3493,7 @@ var WriteService = class {
         this.eventRepo.count(entityId, tx),
         this.metadataRepo.getCheckpoint(entityId, tx)
       ]);
+      eventCount = count;
       let memoryCheckpoint = cp.memory ?? 0;
       if (memoryCheckpoint > count) memoryCheckpoint = 0;
       if (count - memoryCheckpoint >= threshold) {
@@ -3461,6 +3515,8 @@ var WriteService = class {
         if (!(e instanceof WikiBusyError)) throw e;
         await this.metadataRepo.updateCheckpoint(entityId, { memory: prevMemoryCheckpoint }, this.db);
       }
+    } else if (!this.jobManager.isBlocked("librarian", entityId)) {
+      this.maybeRunHeal(entityId, eventCount).catch(console.error);
     }
   }
   async runLibrarianThenMaybeHeal(entityId, currentEventCount, prevCheckpoint) {
@@ -3471,6 +3527,14 @@ var WriteService = class {
       await this.metadataRepo.updateCheckpoint(entityId, { memory: prevCheckpoint }, this.db);
       throw e;
     }
+    await this.maybeRunHeal(entityId, currentEventCount);
+  }
+  /**
+   * Run one bounded auto-heal pass if the heal checkpoint has fallen
+   * `autoHealThreshold` events behind. Called after every write (see
+   * {@link write}) so a partial pass retries on the next write.
+   */
+  async maybeRunHeal(entityId, currentEventCount) {
     const autoHealThreshold = this.options.config?.autoHealThreshold || 100;
     const cp = await this.metadataRepo.getCheckpoint(entityId, this.db);
     let healCheckpoint = cp.heal ?? 0;
@@ -3478,8 +3542,10 @@ var WriteService = class {
     const shouldRunHeal = currentEventCount - healCheckpoint >= autoHealThreshold;
     if (shouldRunHeal && this.jobManager.tryAcquireAutoHealLock(entityId)) {
       try {
-        await this.maintenanceService.doRunHeal(entityId);
-        await this.metadataRepo.updateCheckpoint(entityId, { heal: currentEventCount }, this.db);
+        const result = await this.maintenanceService.doRunHeal(entityId);
+        if (result.remaining === 0) {
+          await this.metadataRepo.updateCheckpoint(entityId, { heal: currentEventCount }, this.db);
+        }
       } finally {
         this.jobManager.releaseLock("heal", entityId);
       }
@@ -3487,6 +3553,6 @@ var WriteService = class {
   }
 };
 
-export { BaseRepository, EmbeddingService, HOOK_TIMEOUT_MARKER, ImportExportService, IngestionService, JobManager, MaintenanceService, MetadataRepository, ONTOLOGY_BACKFILL_BATCH_SIZE, ONTOLOGY_BACKFILL_MAX_PROMPT_CHARS, ONTOLOGY_BACKFILL_RECHECK_MS, ONTOLOGY_BACKFILL_SYSTEM_PROMPT, PromptService, PrunePartialFailureError, RetrievalService, SearchService, WikiBusyError, WikiTransactionError, WriteService, __privateAdd, __privateGet, __privateSet, configureRandomSource, emptyManifest, entitySummaryMetaKey, extractSqliteCode, generateId, normalizeSourceHash, normalizeSourceRef, normalizeTitleKey, parseEmbedding, resolveEdgeDefinitions, resolveNodeType, validateInlineEdges, validateManifest };
-//# sourceMappingURL=chunk-MYZJLVX4.mjs.map
-//# sourceMappingURL=chunk-MYZJLVX4.mjs.map
+export { BaseRepository, DEFAULT_CHUNK_OVERLAP, DEFAULT_MAX_CHUNK_LENGTH, EmbeddingService, HEAL_BATCH_SIZE, HEAL_RECHECK_MS, HOOK_TIMEOUT_MARKER, ImportExportService, IngestionService, JobManager, MaintenanceService, MetadataRepository, ONTOLOGY_BACKFILL_BATCH_SIZE, ONTOLOGY_BACKFILL_MAX_PROMPT_CHARS, ONTOLOGY_BACKFILL_RECHECK_MS, ONTOLOGY_BACKFILL_SYSTEM_PROMPT, PromptService, PrunePartialFailureError, RetrievalService, SearchService, WikiBusyError, WikiTransactionError, WriteService, __privateAdd, __privateGet, __privateSet, chunkText, configureRandomSource, emptyManifest, entitySummaryMetaKey, extractSqliteCode, generateId, normalizeSourceHash, normalizeSourceRef, normalizeTitleKey, parseEmbedding, resolveEdgeDefinitions, resolveNodeType, safeSlice, validateInlineEdges, validateManifest };
+//# sourceMappingURL=chunk-DM7BKDCV.mjs.map
+//# sourceMappingURL=chunk-DM7BKDCV.mjs.map