@equationalapplications/core-llm-wiki 4.23.1 → 5.1.0

package/dist/index.d.mts

@@ -1,8 +1,53 @@
-import { M as MemoryBundle, F as FormatContextOptions, G as GraphNeighborhood, a as MemoryDump, b as FormattedMemoryDump, O as OntologyManifest, R as ReadOptions, S as SQLiteAdapter, W as WikiOptions, c as WikiMemory } from './testing-CBjAuTSl.mjs';
-export { E as EntityStatus, d as ExtractedFact, e as ExtractedFactEdge, f as ExtractedFactWithOntology, g as ExtractedTask, h as GraphTraversalOptions, H as HOOK_TIMEOUT_MARKER, L as LLMProvider, i as ONTOLOGY_BACKFILL_BATCH_SIZE, j as ONTOLOGY_BACKFILL_MAX_PROMPT_CHARS, k as ONTOLOGY_BACKFILL_RECHECK_MS, l as OntologyBackfillResult, m as OntologyConfig, n as OntologyEdgeType, o as OntologyMode, p as OntologyNodeType, q as OntologyPromptContext, r as OntologyUpdates, P as PromptOverrides, s as PromptService, t as PrunePartialFailureError, V as VectorRanker, u as VectorRankerFallback, v as VectorRankerRankArgs, w as VectorRankerSemanticResult, x as WikiBusyError, y as WikiBusyOperation, z as WikiCheckpoint, A as WikiConfig, B as WikiEdge, C as WikiEvent, D as WikiFact, I as WikiMemoryTestAccess, J as WikiOutboxEvent, K as WikiTask, N as WikiTransactionError } from './testing-CBjAuTSl.mjs';
+import { M as MemoryBundle, F as FormatContextOptions, G as GraphNeighborhood, a as MemoryDump, b as FormattedMemoryDump, O as OntologyManifest, R as ReadOptions, S as SQLiteAdapter, W as WikiOptions, c as WikiMemory } from './testing-DCRNie7k.mjs';
+export { E as EntityStatus, d as ExtractedFact, e as ExtractedFactEdge, f as ExtractedFactWithOntology, g as ExtractedTask, h as GraphTraversalOptions, H as HEAL_BATCH_SIZE, i as HEAL_RECHECK_MS, j as HOOK_TIMEOUT_MARKER, k as HealResult, L as LLMProvider, l as ONTOLOGY_BACKFILL_BATCH_SIZE, m as ONTOLOGY_BACKFILL_MAX_PROMPT_CHARS, n as ONTOLOGY_BACKFILL_RECHECK_MS, o as OntologyBackfillResult, p as OntologyConfig, q as OntologyEdgeType, r as OntologyMode, s as OntologyNodeType, t as OntologyPromptContext, u as OntologyUpdates, P as PromptOverrides, v as PromptService, w as PrunePartialFailureError, V as VectorRanker, x as VectorRankerFallback, y as VectorRankerRankArgs, z as VectorRankerSemanticResult, A as WikiBusyError, B as WikiBusyOperation, C as WikiCheckpoint, D as WikiConfig, I as WikiEdge, J as WikiEvent, K as WikiFact, N as WikiMemoryTestAccess, Q as WikiOutboxEvent, T as WikiTask, U as WikiTransactionError } from './testing-DCRNie7k.mjs';
 import { OkfFile } from '@equationalapplications/core-okf';
 import 'minisearch';
 
+/**
+ * Slices a string like `String.prototype.slice`, but clamps out-of-range
+ * indices instead of relying on JS's implicit clamping, normalizes a
+ * start-after-end range by swapping the two bounds, and nudges either bound
+ * off a UTF-16 surrogate pair boundary so slicing never splits one code
+ * point in half.
+ *
+ * @param value - The source string to slice.
+ * @param start - Start index; negative counts from the end, out-of-range
+ *   values are clamped to `[0, value.length]`.
+ * @param end - End index (exclusive); defaults to `value.length` when
+ *   omitted. Same clamping/negative-index rules as `start`.
+ * @returns The sliced substring, never splitting a surrogate pair.
+ */
+declare function safeSlice(value: string, start: number, end?: number): string;
+/**
+ * Splits `input` into chunks of at most `maxChunkLength` characters,
+ * preferring to split on a paragraph break, then a sentence terminator,
+ * then whitespace, falling back to a hard cut only when none of those are
+ * found within the window. Consecutive chunks overlap by up to `overlap`
+ * characters so context isn't lost at a chunk boundary. This is the exact
+ * chunking algorithm `IngestionService.ingestDocument` uses before
+ * embedding, so callers can reproduce ingest-time chunk boundaries exactly
+ * given the same `maxChunkLength`/`overlap` (see `DEFAULT_MAX_CHUNK_LENGTH`
+ * and `DEFAULT_CHUNK_OVERLAP` for the defaults ingest uses).
+ *
+ * @param input - The text to chunk; leading/trailing whitespace is trimmed
+ *   before chunking. Empty/whitespace-only input returns the empty result
+ *   below without validating `maxChunkLength`/`overlap`.
+ * @param maxChunkLength - For non-empty input, maximum characters per chunk;
+ *   must be an integer >= 2.
+ * @param overlap - For non-empty input, maximum number of characters each
+ *   chunk repeats from the end of the previous chunk; must be a
+ *   non-negative integer less than `maxChunkLength`. A chunk repeats fewer
+ *   characters when the previous chunk was shorter than `overlap`.
+ * @returns `chunks` — the resulting chunk strings (empty array for
+ *   empty/whitespace-only input); `truncated` — `true` if any split had to
+ *   fall back to a hard cut (no paragraph/sentence/whitespace boundary
+ *   found in the window).
+ */
+declare function chunkText(input: string, maxChunkLength: number, overlap: number): {
+    chunks: string[];
+    truncated: boolean;
+};
+
 declare function formatContext(bundle: MemoryBundle, options?: FormatContextOptions): string;
 
 /**
@@ -38,6 +83,22 @@ type GetRandomValues = (bytes: Uint8Array) => void;
  */
 declare function configureRandomSource(fn: GetRandomValues | null): void;
 
+/**
+ * Default maximum characters per chunk that `ingestDocument` uses when a
+ * caller doesn't override `maxChunkLength` (directly or via
+ * `WikiOptions.config.maxChunkLength`).
+ */
+declare const DEFAULT_MAX_CHUNK_LENGTH = 12000;
+/**
+ * Default/fallback character overlap between consecutive chunks.
+ * `ingestDocument` uses this when a caller doesn't override `chunkOverlap`
+ * (directly or via `WikiOptions.config.chunkOverlap`), and clamps the
+ * effective overlap (including this default) to `maxChunkLength - 1` when
+ * needed. The clamp is a no-op for the shipped defaults; it can also apply
+ * when a custom `maxChunkLength` makes the resolved overlap too large.
+ */
+declare const DEFAULT_CHUNK_OVERLAP = 400;
+
 interface LibrarianOptions {
     /** If provided, replaces the default Librarian system instructions. */
     systemPrompt?: string;
@@ -64,4 +125,4 @@ declare const ONTOLOGY_BACKFILL_SYSTEM_PROMPT = "You are a knowledge classificat
 
 declare function createWiki(db: SQLiteAdapter, options: WikiOptions): WikiMemory;
 
-export { DEFAULT_LIBRARIAN_SYNTHESIS_PROMPT, FormatContextOptions, FormattedMemoryDump, GraphNeighborhood, type LibrarianOptions, type LibrarianPromptVariables, MemoryBundle, MemoryDump, ONTOLOGY_BACKFILL_SYSTEM_PROMPT, type OkfImportOptions, OntologyManifest, ReadOptions, SQLiteAdapter, WikiMemory, WikiOptions, configureRandomSource, createWiki, formatContext, formatGraphContext, formatMemoryDump, formatOkfBundle, hydrateLibrarianPrompt, mapLibrarianOptionsToReadOptions, parseEmbedding, parseOkfBundle, validateLibrarianPromptTemplate, validateManifest };
+export { DEFAULT_CHUNK_OVERLAP, DEFAULT_LIBRARIAN_SYNTHESIS_PROMPT, DEFAULT_MAX_CHUNK_LENGTH, FormatContextOptions, FormattedMemoryDump, GraphNeighborhood, type LibrarianOptions, type LibrarianPromptVariables, MemoryBundle, MemoryDump, ONTOLOGY_BACKFILL_SYSTEM_PROMPT, type OkfImportOptions, OntologyManifest, ReadOptions, SQLiteAdapter, WikiMemory, WikiOptions, chunkText, configureRandomSource, createWiki, formatContext, formatGraphContext, formatMemoryDump, formatOkfBundle, hydrateLibrarianPrompt, mapLibrarianOptionsToReadOptions, parseEmbedding, parseOkfBundle, safeSlice, validateLibrarianPromptTemplate, validateManifest };

package/dist/index.d.ts

@@ -1,8 +1,53 @@
-import { M as MemoryBundle, F as FormatContextOptions, G as GraphNeighborhood, a as MemoryDump, b as FormattedMemoryDump, O as OntologyManifest, R as ReadOptions, S as SQLiteAdapter, W as WikiOptions, c as WikiMemory } from './testing-CBjAuTSl.js';
-export { E as EntityStatus, d as ExtractedFact, e as ExtractedFactEdge, f as ExtractedFactWithOntology, g as ExtractedTask, h as GraphTraversalOptions, H as HOOK_TIMEOUT_MARKER, L as LLMProvider, i as ONTOLOGY_BACKFILL_BATCH_SIZE, j as ONTOLOGY_BACKFILL_MAX_PROMPT_CHARS, k as ONTOLOGY_BACKFILL_RECHECK_MS, l as OntologyBackfillResult, m as OntologyConfig, n as OntologyEdgeType, o as OntologyMode, p as OntologyNodeType, q as OntologyPromptContext, r as OntologyUpdates, P as PromptOverrides, s as PromptService, t as PrunePartialFailureError, V as VectorRanker, u as VectorRankerFallback, v as VectorRankerRankArgs, w as VectorRankerSemanticResult, x as WikiBusyError, y as WikiBusyOperation, z as WikiCheckpoint, A as WikiConfig, B as WikiEdge, C as WikiEvent, D as WikiFact, I as WikiMemoryTestAccess, J as WikiOutboxEvent, K as WikiTask, N as WikiTransactionError } from './testing-CBjAuTSl.js';
+import { M as MemoryBundle, F as FormatContextOptions, G as GraphNeighborhood, a as MemoryDump, b as FormattedMemoryDump, O as OntologyManifest, R as ReadOptions, S as SQLiteAdapter, W as WikiOptions, c as WikiMemory } from './testing-DCRNie7k.js';
+export { E as EntityStatus, d as ExtractedFact, e as ExtractedFactEdge, f as ExtractedFactWithOntology, g as ExtractedTask, h as GraphTraversalOptions, H as HEAL_BATCH_SIZE, i as HEAL_RECHECK_MS, j as HOOK_TIMEOUT_MARKER, k as HealResult, L as LLMProvider, l as ONTOLOGY_BACKFILL_BATCH_SIZE, m as ONTOLOGY_BACKFILL_MAX_PROMPT_CHARS, n as ONTOLOGY_BACKFILL_RECHECK_MS, o as OntologyBackfillResult, p as OntologyConfig, q as OntologyEdgeType, r as OntologyMode, s as OntologyNodeType, t as OntologyPromptContext, u as OntologyUpdates, P as PromptOverrides, v as PromptService, w as PrunePartialFailureError, V as VectorRanker, x as VectorRankerFallback, y as VectorRankerRankArgs, z as VectorRankerSemanticResult, A as WikiBusyError, B as WikiBusyOperation, C as WikiCheckpoint, D as WikiConfig, I as WikiEdge, J as WikiEvent, K as WikiFact, N as WikiMemoryTestAccess, Q as WikiOutboxEvent, T as WikiTask, U as WikiTransactionError } from './testing-DCRNie7k.js';
 import { OkfFile } from '@equationalapplications/core-okf';
 import 'minisearch';
 
+/**
+ * Slices a string like `String.prototype.slice`, but clamps out-of-range
+ * indices instead of relying on JS's implicit clamping, normalizes a
+ * start-after-end range by swapping the two bounds, and nudges either bound
+ * off a UTF-16 surrogate pair boundary so slicing never splits one code
+ * point in half.
+ *
+ * @param value - The source string to slice.
+ * @param start - Start index; negative counts from the end, out-of-range
+ *   values are clamped to `[0, value.length]`.
+ * @param end - End index (exclusive); defaults to `value.length` when
+ *   omitted. Same clamping/negative-index rules as `start`.
+ * @returns The sliced substring, never splitting a surrogate pair.
+ */
+declare function safeSlice(value: string, start: number, end?: number): string;
+/**
+ * Splits `input` into chunks of at most `maxChunkLength` characters,
+ * preferring to split on a paragraph break, then a sentence terminator,
+ * then whitespace, falling back to a hard cut only when none of those are
+ * found within the window. Consecutive chunks overlap by up to `overlap`
+ * characters so context isn't lost at a chunk boundary. This is the exact
+ * chunking algorithm `IngestionService.ingestDocument` uses before
+ * embedding, so callers can reproduce ingest-time chunk boundaries exactly
+ * given the same `maxChunkLength`/`overlap` (see `DEFAULT_MAX_CHUNK_LENGTH`
+ * and `DEFAULT_CHUNK_OVERLAP` for the defaults ingest uses).
+ *
+ * @param input - The text to chunk; leading/trailing whitespace is trimmed
+ *   before chunking. Empty/whitespace-only input returns the empty result
+ *   below without validating `maxChunkLength`/`overlap`.
+ * @param maxChunkLength - For non-empty input, maximum characters per chunk;
+ *   must be an integer >= 2.
+ * @param overlap - For non-empty input, maximum number of characters each
+ *   chunk repeats from the end of the previous chunk; must be a
+ *   non-negative integer less than `maxChunkLength`. A chunk repeats fewer
+ *   characters when the previous chunk was shorter than `overlap`.
+ * @returns `chunks` — the resulting chunk strings (empty array for
+ *   empty/whitespace-only input); `truncated` — `true` if any split had to
+ *   fall back to a hard cut (no paragraph/sentence/whitespace boundary
+ *   found in the window).
+ */
+declare function chunkText(input: string, maxChunkLength: number, overlap: number): {
+    chunks: string[];
+    truncated: boolean;
+};
+
 declare function formatContext(bundle: MemoryBundle, options?: FormatContextOptions): string;
 
 /**
@@ -38,6 +83,22 @@ type GetRandomValues = (bytes: Uint8Array) => void;
  */
 declare function configureRandomSource(fn: GetRandomValues | null): void;
 
+/**
+ * Default maximum characters per chunk that `ingestDocument` uses when a
+ * caller doesn't override `maxChunkLength` (directly or via
+ * `WikiOptions.config.maxChunkLength`).
+ */
+declare const DEFAULT_MAX_CHUNK_LENGTH = 12000;
+/**
+ * Default/fallback character overlap between consecutive chunks.
+ * `ingestDocument` uses this when a caller doesn't override `chunkOverlap`
+ * (directly or via `WikiOptions.config.chunkOverlap`), and clamps the
+ * effective overlap (including this default) to `maxChunkLength - 1` when
+ * needed. The clamp is a no-op for the shipped defaults; it can also apply
+ * when a custom `maxChunkLength` makes the resolved overlap too large.
+ */
+declare const DEFAULT_CHUNK_OVERLAP = 400;
+
 interface LibrarianOptions {
     /** If provided, replaces the default Librarian system instructions. */
     systemPrompt?: string;
@@ -64,4 +125,4 @@ declare const ONTOLOGY_BACKFILL_SYSTEM_PROMPT = "You are a knowledge classificat
 
 declare function createWiki(db: SQLiteAdapter, options: WikiOptions): WikiMemory;
 
-export { DEFAULT_LIBRARIAN_SYNTHESIS_PROMPT, FormatContextOptions, FormattedMemoryDump, GraphNeighborhood, type LibrarianOptions, type LibrarianPromptVariables, MemoryBundle, MemoryDump, ONTOLOGY_BACKFILL_SYSTEM_PROMPT, type OkfImportOptions, OntologyManifest, ReadOptions, SQLiteAdapter, WikiMemory, WikiOptions, configureRandomSource, createWiki, formatContext, formatGraphContext, formatMemoryDump, formatOkfBundle, hydrateLibrarianPrompt, mapLibrarianOptionsToReadOptions, parseEmbedding, parseOkfBundle, validateLibrarianPromptTemplate, validateManifest };
+export { DEFAULT_CHUNK_OVERLAP, DEFAULT_LIBRARIAN_SYNTHESIS_PROMPT, DEFAULT_MAX_CHUNK_LENGTH, FormatContextOptions, FormattedMemoryDump, GraphNeighborhood, type LibrarianOptions, type LibrarianPromptVariables, MemoryBundle, MemoryDump, ONTOLOGY_BACKFILL_SYSTEM_PROMPT, type OkfImportOptions, OntologyManifest, ReadOptions, SQLiteAdapter, WikiMemory, WikiOptions, chunkText, configureRandomSource, createWiki, formatContext, formatGraphContext, formatMemoryDump, formatOkfBundle, hydrateLibrarianPrompt, mapLibrarianOptionsToReadOptions, parseEmbedding, parseOkfBundle, safeSlice, validateLibrarianPromptTemplate, validateManifest };

package/dist/index.js

@@ -36,7 +36,8 @@ async function setupDatabase(db, prefix) {
       embedding TEXT,
       embedding_blob BLOB,
       okf_type TEXT,
-      ontology_checked_at INTEGER
+      ontology_checked_at INTEGER,
+      heal_checked_at INTEGER
     );
 
     CREATE INDEX IF NOT EXISTS ${prefix}entries_entity_idx ON ${prefix}entries(entity_id);
@@ -353,6 +354,20 @@ var MIGRATIONS = [
         );
       }
     }
+  },
+  {
+    version: 8,
+    description: "Add heal_checked_at to entries for heal recheck cooldown",
+    run: async (db, prefix) => {
+      const cols = await db.getAllAsync(
+        `PRAGMA table_info(${prefix}entries)`
+      );
+      if (!cols.some((c) => c.name === "heal_checked_at")) {
+        await db.execAsync(
+          `ALTER TABLE ${prefix}entries ADD COLUMN heal_checked_at INTEGER`
+        );
+      }
+    }
   }
 ];
 for (let i = 1; i < MIGRATIONS.length; i++) {
@@ -709,17 +724,21 @@ var EntryRepository = class extends BaseRepository {
   }
   /**
    * Fetch live, mutable entries for an entity — everything heal is allowed to
-   * downgrade or delete. Heal previously loaded every row via
-   * findAllByEntityId and filtered in JS, which on a document-heavy corpus
-   * meant loading 2560 rows to keep 31.
+   * downgrade or delete — oldest first, capped at `limit`, skipping anything
+   * stamped inside the recheck cooldown (heal_checked_at > recheckCutoff).
+   *
+   * Oldest-first rather than newest-first: with a cooldown in place, newest-first
+   * would keep re-selecting recently-touched facts every pass while older ones
+   * wait indefinitely to even enter a batch.
    */
-  async findHealCandidatesByEntityId(entityId, tx) {
+  async findHealCandidatesByEntityId(entityId, limit, recheckCutoff, tx) {
     const executor = this.getExecutor(tx);
     const rows = await executor.getAllAsync(
       `SELECT * FROM ${this.prefix}entries
        WHERE entity_id = ? AND deleted_at IS NULL AND source_type != 'immutable_document'
-       ORDER BY updated_at DESC`,
-      [entityId]
+         AND (heal_checked_at IS NULL OR heal_checked_at <= ?)
+       ORDER BY updated_at ASC LIMIT ?`,
+      [entityId, recheckCutoff, limit]
     );
     return rows.map(mapRowToFact);
   }
@@ -882,6 +901,10 @@ var EntryRepository = class extends BaseRepository {
   /**
    * Downgrade stale inferred entries to 'tentative'.
    * Used by MaintenanceService.doRunHeal().
+   *
+   * Returns the ids it downgraded so the caller can fold them into
+   * {@link HealResult.downgraded} without double-counting a fact the model also
+   * downgraded in the same pass.
    */
   async downgradeStaleInferred(entityId, staleThreshold, tx) {
     const executor = this.getExecutor(tx);
@@ -893,8 +916,8 @@ var EntryRepository = class extends BaseRepository {
          AND source_type != 'immutable_document' AND deleted_at IS NULL`,
       [entityId, staleThreshold, staleThreshold]
     );
-    if (eligibleRows.length === 0) return 0;
-    const result = await executor.runAsync(
+    if (eligibleRows.length === 0) return [];
+    await executor.runAsync(
       `UPDATE ${this.prefix}entries
        SET confidence = 'tentative', updated_at = ?
        WHERE entity_id = ? AND confidence = 'inferred' AND (last_accessed_at <= ? OR (last_accessed_at IS NULL AND created_at <= ?)) AND source_type != 'immutable_document' AND deleted_at IS NULL`,
@@ -909,7 +932,7 @@ var EntryRepository = class extends BaseRepository {
         payload: { id: row.id, entity_id: entityId, confidence: "tentative", updated_at: now }
       }, tx);
     }
-    return result.changes;
+    return eligibleRows.map((r) => r.id);
   }
   /**
    * Downgrade specific entries to 'tentative' by IDs.
@@ -1228,6 +1251,58 @@ var EntryRepository = class extends BaseRepository {
     );
     return rows.map((r) => ({ id: r.id, title: r.title, okf_type: r.okf_type ?? null }));
   }
+  /** Counts live mutable facts: eligible (past cooldown) vs deferred (in cooldown). */
+  async countHealCandidatesByEntityId(entityId, recheckCutoff, tx) {
+    const executor = this.getExecutor(tx);
+    const row = await executor.getFirstAsync(
+      `SELECT
+         SUM(CASE WHEN heal_checked_at IS NULL OR heal_checked_at <= ? THEN 1 ELSE 0 END) AS eligible,
+         SUM(CASE WHEN heal_checked_at IS NOT NULL AND heal_checked_at > ? THEN 1 ELSE 0 END) AS deferred
+       FROM ${this.prefix}entries
+       WHERE entity_id = ? AND deleted_at IS NULL AND source_type != 'immutable_document'`,
+      [recheckCutoff, recheckCutoff, entityId]
+    );
+    return { eligible: Number(row?.eligible ?? 0), deferred: Number(row?.deferred ?? 0) };
+  }
+  /**
+   * Stamps the heal recheck cooldown. NEVER touches updated_at — import merge
+   * resolution is last-write-wins on updated_at and a bump here would make an
+   * unchanged local fact beat a genuinely newer remote edit.
+   *
+   * Soft-deleted rows are skipped: a candidate heal deleted earlier in the same
+   * transaction is no longer a candidate under any future pass, so its cooldown
+   * value is irrelevant. This means the stamped count can be lower than the
+   * offered-candidate count.
+   */
+  async markHealChecked(ids, entityId, now, tx) {
+    if (ids.length === 0) return;
+    for (let i = 0; i < ids.length; i += this.chunkSize) {
+      const chunk = ids.slice(i, i + this.chunkSize);
+      const placeholders = chunk.map(() => "?").join(",");
+      await tx.runAsync(
+        `UPDATE ${this.prefix}entries SET heal_checked_at = ?
+         WHERE id IN (${placeholders}) AND entity_id = ? AND deleted_at IS NULL`,
+        [now, ...chunk, entityId]
+      );
+    }
+  }
+  /**
+   * Lightweight full-breadth index (id, title) over all live librarian_inferred
+   * facts. This is heal's fuzzy-dedupe corpus, deliberately kept independent of
+   * the bounded candidate window: seeding dedupe from a batchSize-limited read
+   * would let a synthesized fact duplicating a fact outside the window pass the
+   * Jaccard check, and a convergence loop would multiply those duplicates across
+   * passes. Mirrors findTitleIndexByEntityId — full breadth, two columns, cheap.
+   */
+  async findInferredTitlesByEntityId(entityId, tx) {
+    const executor = this.getExecutor(tx);
+    const rows = await executor.getAllAsync(
+      `SELECT id, title FROM ${this.prefix}entries
+       WHERE entity_id = ? AND deleted_at IS NULL AND source_type = 'librarian_inferred'`,
+      [entityId]
+    );
+    return rows.map((r) => ({ id: r.id, title: r.title }));
+  }
 };
 
 // src/utils/ids.ts
@@ -2988,6 +3063,10 @@ ${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) {
@@ -3006,10 +3085,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;
@@ -3252,6 +3331,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;
@@ -3352,7 +3433,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);
     }
@@ -3604,9 +3685,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;
@@ -3617,6 +3710,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;
@@ -3624,7 +3718,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) {
@@ -3634,7 +3728,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) => {
@@ -3687,7 +3795,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);
@@ -3696,7 +3804,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) {
@@ -3726,8 +3833,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) {
@@ -3741,6 +3854,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) {
@@ -5116,6 +5243,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;
@@ -5123,6 +5251,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) {
@@ -5144,6 +5273,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) {
@@ -5154,6 +5285,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;
@@ -5161,8 +5300,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);
       }
@@ -5513,9 +5654,23 @@ var WikiMemory = class {
     return this.maintenanceService.runLibrarian(entityId, options);
   }
   /**
+   * Reviews stored facts with the LLM: removes orphans, downgrades stale
+   * inferences, synthesizes corrections.
+   *
+   * Bounded per call: covers at most `batchSize` candidates (default 25), so
+   * one call no longer sweeps the whole entity. Hosts own the cadence; loop
+   * `while (result.remaining > 0)` for convergence.
+   *
+   * `remaining === 0` means "every mutable fact is inside the 7-day recheck
+   * cooldown", not "there is no more work" — heal's candidate set is the live
+   * mutable corpus, not a draining backlog, so it climbs back as the cooldown
+   * lapses and as new facts are written. Do not write a loop expecting a drain.
+   *
    * @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.
+   * @param options.batchSize - Candidates per run (default 25) for providers with
+   * tighter context limits.
    */
   async runHeal(entityId, options) {
     return this.maintenanceService.runHeal(entityId, options);
@@ -6375,7 +6530,11 @@ function createWiki(db, options) {
   return new WikiMemory(db, options);
 }
 
+exports.DEFAULT_CHUNK_OVERLAP = DEFAULT_CHUNK_OVERLAP;
 exports.DEFAULT_LIBRARIAN_SYNTHESIS_PROMPT = DEFAULT_LIBRARIAN_SYNTHESIS_PROMPT;
+exports.DEFAULT_MAX_CHUNK_LENGTH = DEFAULT_MAX_CHUNK_LENGTH;
+exports.HEAL_BATCH_SIZE = HEAL_BATCH_SIZE;
+exports.HEAL_RECHECK_MS = HEAL_RECHECK_MS;
 exports.HOOK_TIMEOUT_MARKER = HOOK_TIMEOUT_MARKER;
 exports.ONTOLOGY_BACKFILL_BATCH_SIZE = ONTOLOGY_BACKFILL_BATCH_SIZE;
 exports.ONTOLOGY_BACKFILL_MAX_PROMPT_CHARS = ONTOLOGY_BACKFILL_MAX_PROMPT_CHARS;
@@ -6386,6 +6545,7 @@ exports.PrunePartialFailureError = PrunePartialFailureError;
 exports.WikiBusyError = WikiBusyError;
 exports.WikiMemory = WikiMemory;
 exports.WikiTransactionError = WikiTransactionError;
+exports.chunkText = chunkText;
 exports.configureRandomSource = configureRandomSource;
 exports.createWiki = createWiki;
 exports.formatContext = formatContext;
@@ -6396,6 +6556,7 @@ exports.hydrateLibrarianPrompt = hydrateLibrarianPrompt;
 exports.mapLibrarianOptionsToReadOptions = mapLibrarianOptionsToReadOptions;
 exports.parseEmbedding = parseEmbedding;
 exports.parseOkfBundle = parseOkfBundle;
+exports.safeSlice = safeSlice;
 exports.validateLibrarianPromptTemplate = validateLibrarianPromptTemplate;
 exports.validateManifest = validateManifest;
 //# sourceMappingURL=index.js.map