@equationalapplications/core-llm-wiki 4.23.1 → 5.1.0

package/dist/{testing-CBjAuTSl.d.mts → testing-DCRNie7k.d.mts}

@@ -100,6 +100,39 @@ interface OntologyBackfillResult {
      * Stamped with the recheck cooldown, so they reappear as `deferred` next pass. */
     skipped: number;
 }
+/** Result of a single heal run. */
+interface HealResult {
+    /**
+     * Heal candidates sent to the model this run. Counts candidates whose batch
+     * came back unusable and landed in `skipped` as well — they reached the
+     * provider too, so this is provider exposure, not successful throughput.
+     */
+    scanned: number;
+    /**
+     * Facts whose confidence was lowered to `tentative` — the stale-inferred SQL
+     * pass (`inferred` → `tentative`) plus any model-directed downgrades, deduped.
+     */
+    downgraded: number;
+    /** Facts soft-deleted — the orphan-marking SQL pass plus model-directed deletes, deduped. */
+    deleted: number;
+    /** New facts synthesized by heal. */
+    newFactsCreated: number;
+    /** Candidates a batch could not process even alone, skipped so the pass could finish. */
+    skipped: number;
+    /**
+     * Heal candidates still eligible after this run — convergence signal: loop while > 0.
+     *
+     * This does NOT mean what it means for OntologyBackfillResult. Untyped facts are
+     * a finite backlog that drains permanently; heal's candidates are the live mutable
+     * corpus. `remaining === 0` means "every mutable fact is inside the recheck
+     * cooldown", not "there is no more work" — it climbs back as the cooldown lapses
+     * and as new facts are written. A host loop terminates, but it converges to
+     * "corpus swept once this cooldown window", not to a drained queue.
+     */
+    remaining: number;
+    /** Heal candidates inside the recheck cooldown. */
+    deferred: number;
+}
 interface WikiConfig {
     /**
      * Prefix applied to every SQL table/index/trigger name. Must match
@@ -664,11 +697,14 @@ declare class EntryRepository extends BaseRepository {
     findAllByEntityId(entityId: string, tx?: SQLiteAdapter): Promise<WikiFact[]>;
     /**
      * 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.
      */
-    findHealCandidatesByEntityId(entityId: string, tx?: SQLiteAdapter): Promise<WikiFact[]>;
+    findHealCandidatesByEntityId(entityId: string, limit: number, recheckCutoff: number, tx?: SQLiteAdapter): Promise<WikiFact[]>;
     /**
      * Resolve search hits to document anchors. The MiniSearch index holds every
      * fact, not only immutable_document rows, so the source-type restriction has
@@ -719,8 +755,12 @@ declare class EntryRepository 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.
      */
-    downgradeStaleInferred(entityId: string, staleThreshold: number, tx: SQLiteAdapter): Promise<number>;
+    downgradeStaleInferred(entityId: string, staleThreshold: number, tx: SQLiteAdapter): Promise<string[]>;
     /**
      * Downgrade specific entries to 'tentative' by IDs.
      * Used by MaintenanceService.doRunHeal().
@@ -804,6 +844,34 @@ declare class EntryRepository extends BaseRepository {
         title: string;
         okf_type: string | null;
     }>>;
+    /** Counts live mutable facts: eligible (past cooldown) vs deferred (in cooldown). */
+    countHealCandidatesByEntityId(entityId: string, recheckCutoff: number, tx?: SQLiteAdapter): Promise<{
+        eligible: number;
+        deferred: number;
+    }>;
+    /**
+     * 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.
+     */
+    markHealChecked(ids: string[], entityId: string, now: number, tx: SQLiteAdapter): Promise<void>;
+    /**
+     * 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.
+     */
+    findInferredTitlesByEntityId(entityId: string, tx?: SQLiteAdapter): Promise<Array<{
+        id: string;
+        title: string;
+    }>>;
 }
 
 declare class MetadataRepository extends BaseRepository {
@@ -1203,6 +1271,15 @@ declare class EventRepository extends BaseRepository {
 declare const ONTOLOGY_BACKFILL_BATCH_SIZE = 25;
 declare const ONTOLOGY_BACKFILL_MAX_PROMPT_CHARS = 40000;
 declare const ONTOLOGY_BACKFILL_RECHECK_MS: number;
+/**
+ * Heal candidates fetched per pass. Bounds the pool runBatched draws from, not
+ * the size of an individual LLM call — runBatched still packs ~10 candidates per
+ * request and splits further on failure. At this default one pass costs roughly
+ * 2-3 provider calls instead of an unbounded count (#67).
+ */
+declare const HEAL_BATCH_SIZE = 25;
+/** Cooldown before an already-healed fact is offered again. Matches ontology backfill. */
+declare const HEAL_RECHECK_MS: number;
 declare class MaintenanceService {
     private db;
     private prefix;
@@ -1231,7 +1308,8 @@ declare class MaintenanceService {
     }): Promise<void>;
     runHeal(entityId: string, options?: {
         promptOverride?: string;
-    }): Promise<void>;
+        batchSize?: number;
+    }): Promise<HealResult>;
     runOntologyBackfill(entityId: string, options?: {
         promptOverride?: string;
         batchSize?: number;
@@ -1258,8 +1336,17 @@ declare class MaintenanceService {
     }>;
     /** Core librarian pass (locks handled by {@link runLibrarian}). Package-internal orchestration hook. */
     doRunLibrarian(entityId: string, promptOverride?: string): Promise<void>;
-    /** Core heal pass (locks handled by {@link runHeal}). Package-internal orchestration hook. */
-    doRunHeal(entityId: string, promptOverride?: string): Promise<void>;
+    /**
+     * 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.
+     */
+    doRunHeal(entityId: string, options?: {
+        promptOverride?: string;
+        batchSize?: number;
+    }): Promise<HealResult>;
     /** Core ontology backfill pass (locks handled by {@link runOntologyBackfill}). Package-internal orchestration hook. */
     doRunOntologyBackfill(entityId: string, options?: {
         promptOverride?: string;
@@ -1371,6 +1458,12 @@ declare class WriteService {
     constructor(db: SQLiteAdapter, options: WikiOptions, entryRepo: EntryRepository, eventRepo: EventRepository, metadataRepo: MetadataRepository, jobManager: JobManager, maintenanceService: MaintenanceService);
     write(entityId: string, event: Omit<WikiEvent, 'id' | 'entity_id' | 'created_at'>): Promise<void>;
     private runLibrarianThenMaybeHeal;
+    /**
+     * 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.
+     */
+    private maybeRunHeal;
 }
 
 /**
@@ -1452,13 +1545,28 @@ declare class WikiMemory {
         promptOverride?: string;
     }): Promise<void>;
     /**
+     * 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.
      */
     runHeal(entityId: string, options?: {
         promptOverride?: string;
-    }): Promise<void>;
+        batchSize?: number;
+    }): Promise<HealResult>;
     /**
      * Types already-persisted untyped facts (okf_type IS NULL) in place via one
      * librarian-style LLM call. Strictly additive: never creates, deletes, or
@@ -1552,4 +1660,4 @@ declare class WikiMemory {
     }): Promise<void>;
 }
 
-export { WriteService as $, type WikiConfig as A, type WikiEdge as B, type WikiEvent as C, type WikiFact as D, type EntityStatus as E, type FormatContextOptions as F, type GraphNeighborhood as G, HOOK_TIMEOUT_MARKER as H, type WikiMemoryTestAccess as I, type WikiOutboxEvent as J, type WikiTask as K, type LLMProvider as L, type MemoryBundle as M, WikiTransactionError as N, type OntologyManifest as O, type PromptOverrides as P, EmbeddingService as Q, type ReadOptions as R, type SQLiteAdapter as S, ImportExportService as T, IngestionService as U, type VectorRanker as V, type WikiOptions as W, JobManager as X, MaintenanceService as Y, RetrievalService as Z, SearchService as _, type MemoryDump as a, type FormattedMemoryDump as b, WikiMemory as c, type ExtractedFact as d, type ExtractedFactEdge as e, type ExtractedFactWithOntology as f, type ExtractedTask as g, type GraphTraversalOptions as h, ONTOLOGY_BACKFILL_BATCH_SIZE as i, ONTOLOGY_BACKFILL_MAX_PROMPT_CHARS as j, ONTOLOGY_BACKFILL_RECHECK_MS as k, type OntologyBackfillResult as l, type OntologyConfig as m, type OntologyEdgeType as n, type OntologyMode as o, type OntologyNodeType as p, type OntologyPromptContext as q, type OntologyUpdates as r, PromptService as s, PrunePartialFailureError as t, type VectorRankerFallback as u, type VectorRankerRankArgs as v, type VectorRankerSemanticResult as w, WikiBusyError as x, type WikiBusyOperation as y, type WikiCheckpoint as z };
+export { MaintenanceService as $, WikiBusyError as A, type WikiBusyOperation as B, type WikiCheckpoint as C, type WikiConfig as D, type EntityStatus as E, type FormatContextOptions as F, type GraphNeighborhood as G, HEAL_BATCH_SIZE as H, type WikiEdge as I, type WikiEvent as J, type WikiFact as K, type LLMProvider as L, type MemoryBundle as M, type WikiMemoryTestAccess as N, type OntologyManifest as O, type PromptOverrides as P, type WikiOutboxEvent as Q, type ReadOptions as R, type SQLiteAdapter as S, type WikiTask as T, WikiTransactionError as U, type VectorRanker as V, type WikiOptions as W, EmbeddingService as X, ImportExportService as Y, IngestionService as Z, JobManager as _, type MemoryDump as a, RetrievalService as a0, SearchService as a1, WriteService as a2, type FormattedMemoryDump as b, WikiMemory as c, type ExtractedFact as d, type ExtractedFactEdge as e, type ExtractedFactWithOntology as f, type ExtractedTask as g, type GraphTraversalOptions as h, HEAL_RECHECK_MS as i, HOOK_TIMEOUT_MARKER as j, type HealResult as k, ONTOLOGY_BACKFILL_BATCH_SIZE as l, ONTOLOGY_BACKFILL_MAX_PROMPT_CHARS as m, ONTOLOGY_BACKFILL_RECHECK_MS as n, type OntologyBackfillResult as o, type OntologyConfig as p, type OntologyEdgeType as q, type OntologyMode as r, type OntologyNodeType as s, type OntologyPromptContext as t, type OntologyUpdates as u, PromptService as v, PrunePartialFailureError as w, type VectorRankerFallback as x, type VectorRankerRankArgs as y, type VectorRankerSemanticResult as z };

package/dist/{testing-CBjAuTSl.d.ts → testing-DCRNie7k.d.ts}

@@ -100,6 +100,39 @@ interface OntologyBackfillResult {
      * Stamped with the recheck cooldown, so they reappear as `deferred` next pass. */
     skipped: number;
 }
+/** Result of a single heal run. */
+interface HealResult {
+    /**
+     * Heal candidates sent to the model this run. Counts candidates whose batch
+     * came back unusable and landed in `skipped` as well — they reached the
+     * provider too, so this is provider exposure, not successful throughput.
+     */
+    scanned: number;
+    /**
+     * Facts whose confidence was lowered to `tentative` — the stale-inferred SQL
+     * pass (`inferred` → `tentative`) plus any model-directed downgrades, deduped.
+     */
+    downgraded: number;
+    /** Facts soft-deleted — the orphan-marking SQL pass plus model-directed deletes, deduped. */
+    deleted: number;
+    /** New facts synthesized by heal. */
+    newFactsCreated: number;
+    /** Candidates a batch could not process even alone, skipped so the pass could finish. */
+    skipped: number;
+    /**
+     * Heal candidates still eligible after this run — convergence signal: loop while > 0.
+     *
+     * This does NOT mean what it means for OntologyBackfillResult. Untyped facts are
+     * a finite backlog that drains permanently; heal's candidates are the live mutable
+     * corpus. `remaining === 0` means "every mutable fact is inside the recheck
+     * cooldown", not "there is no more work" — it climbs back as the cooldown lapses
+     * and as new facts are written. A host loop terminates, but it converges to
+     * "corpus swept once this cooldown window", not to a drained queue.
+     */
+    remaining: number;
+    /** Heal candidates inside the recheck cooldown. */
+    deferred: number;
+}
 interface WikiConfig {
     /**
      * Prefix applied to every SQL table/index/trigger name. Must match
@@ -664,11 +697,14 @@ declare class EntryRepository extends BaseRepository {
     findAllByEntityId(entityId: string, tx?: SQLiteAdapter): Promise<WikiFact[]>;
     /**
      * 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.
      */
-    findHealCandidatesByEntityId(entityId: string, tx?: SQLiteAdapter): Promise<WikiFact[]>;
+    findHealCandidatesByEntityId(entityId: string, limit: number, recheckCutoff: number, tx?: SQLiteAdapter): Promise<WikiFact[]>;
     /**
      * Resolve search hits to document anchors. The MiniSearch index holds every
      * fact, not only immutable_document rows, so the source-type restriction has
@@ -719,8 +755,12 @@ declare class EntryRepository 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.
      */
-    downgradeStaleInferred(entityId: string, staleThreshold: number, tx: SQLiteAdapter): Promise<number>;
+    downgradeStaleInferred(entityId: string, staleThreshold: number, tx: SQLiteAdapter): Promise<string[]>;
     /**
      * Downgrade specific entries to 'tentative' by IDs.
      * Used by MaintenanceService.doRunHeal().
@@ -804,6 +844,34 @@ declare class EntryRepository extends BaseRepository {
         title: string;
         okf_type: string | null;
     }>>;
+    /** Counts live mutable facts: eligible (past cooldown) vs deferred (in cooldown). */
+    countHealCandidatesByEntityId(entityId: string, recheckCutoff: number, tx?: SQLiteAdapter): Promise<{
+        eligible: number;
+        deferred: number;
+    }>;
+    /**
+     * 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.
+     */
+    markHealChecked(ids: string[], entityId: string, now: number, tx: SQLiteAdapter): Promise<void>;
+    /**
+     * 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.
+     */
+    findInferredTitlesByEntityId(entityId: string, tx?: SQLiteAdapter): Promise<Array<{
+        id: string;
+        title: string;
+    }>>;
 }
 
 declare class MetadataRepository extends BaseRepository {
@@ -1203,6 +1271,15 @@ declare class EventRepository extends BaseRepository {
 declare const ONTOLOGY_BACKFILL_BATCH_SIZE = 25;
 declare const ONTOLOGY_BACKFILL_MAX_PROMPT_CHARS = 40000;
 declare const ONTOLOGY_BACKFILL_RECHECK_MS: number;
+/**
+ * Heal candidates fetched per pass. Bounds the pool runBatched draws from, not
+ * the size of an individual LLM call — runBatched still packs ~10 candidates per
+ * request and splits further on failure. At this default one pass costs roughly
+ * 2-3 provider calls instead of an unbounded count (#67).
+ */
+declare const HEAL_BATCH_SIZE = 25;
+/** Cooldown before an already-healed fact is offered again. Matches ontology backfill. */
+declare const HEAL_RECHECK_MS: number;
 declare class MaintenanceService {
     private db;
     private prefix;
@@ -1231,7 +1308,8 @@ declare class MaintenanceService {
     }): Promise<void>;
     runHeal(entityId: string, options?: {
         promptOverride?: string;
-    }): Promise<void>;
+        batchSize?: number;
+    }): Promise<HealResult>;
     runOntologyBackfill(entityId: string, options?: {
         promptOverride?: string;
         batchSize?: number;
@@ -1258,8 +1336,17 @@ declare class MaintenanceService {
     }>;
     /** Core librarian pass (locks handled by {@link runLibrarian}). Package-internal orchestration hook. */
     doRunLibrarian(entityId: string, promptOverride?: string): Promise<void>;
-    /** Core heal pass (locks handled by {@link runHeal}). Package-internal orchestration hook. */
-    doRunHeal(entityId: string, promptOverride?: string): Promise<void>;
+    /**
+     * 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.
+     */
+    doRunHeal(entityId: string, options?: {
+        promptOverride?: string;
+        batchSize?: number;
+    }): Promise<HealResult>;
     /** Core ontology backfill pass (locks handled by {@link runOntologyBackfill}). Package-internal orchestration hook. */
     doRunOntologyBackfill(entityId: string, options?: {
         promptOverride?: string;
@@ -1371,6 +1458,12 @@ declare class WriteService {
     constructor(db: SQLiteAdapter, options: WikiOptions, entryRepo: EntryRepository, eventRepo: EventRepository, metadataRepo: MetadataRepository, jobManager: JobManager, maintenanceService: MaintenanceService);
     write(entityId: string, event: Omit<WikiEvent, 'id' | 'entity_id' | 'created_at'>): Promise<void>;
     private runLibrarianThenMaybeHeal;
+    /**
+     * 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.
+     */
+    private maybeRunHeal;
 }
 
 /**
@@ -1452,13 +1545,28 @@ declare class WikiMemory {
         promptOverride?: string;
     }): Promise<void>;
     /**
+     * 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.
      */
     runHeal(entityId: string, options?: {
         promptOverride?: string;
-    }): Promise<void>;
+        batchSize?: number;
+    }): Promise<HealResult>;
     /**
      * Types already-persisted untyped facts (okf_type IS NULL) in place via one
      * librarian-style LLM call. Strictly additive: never creates, deletes, or
@@ -1552,4 +1660,4 @@ declare class WikiMemory {
     }): Promise<void>;
 }
 
-export { WriteService as $, type WikiConfig as A, type WikiEdge as B, type WikiEvent as C, type WikiFact as D, type EntityStatus as E, type FormatContextOptions as F, type GraphNeighborhood as G, HOOK_TIMEOUT_MARKER as H, type WikiMemoryTestAccess as I, type WikiOutboxEvent as J, type WikiTask as K, type LLMProvider as L, type MemoryBundle as M, WikiTransactionError as N, type OntologyManifest as O, type PromptOverrides as P, EmbeddingService as Q, type ReadOptions as R, type SQLiteAdapter as S, ImportExportService as T, IngestionService as U, type VectorRanker as V, type WikiOptions as W, JobManager as X, MaintenanceService as Y, RetrievalService as Z, SearchService as _, type MemoryDump as a, type FormattedMemoryDump as b, WikiMemory as c, type ExtractedFact as d, type ExtractedFactEdge as e, type ExtractedFactWithOntology as f, type ExtractedTask as g, type GraphTraversalOptions as h, ONTOLOGY_BACKFILL_BATCH_SIZE as i, ONTOLOGY_BACKFILL_MAX_PROMPT_CHARS as j, ONTOLOGY_BACKFILL_RECHECK_MS as k, type OntologyBackfillResult as l, type OntologyConfig as m, type OntologyEdgeType as n, type OntologyMode as o, type OntologyNodeType as p, type OntologyPromptContext as q, type OntologyUpdates as r, PromptService as s, PrunePartialFailureError as t, type VectorRankerFallback as u, type VectorRankerRankArgs as v, type VectorRankerSemanticResult as w, WikiBusyError as x, type WikiBusyOperation as y, type WikiCheckpoint as z };
+export { MaintenanceService as $, WikiBusyError as A, type WikiBusyOperation as B, type WikiCheckpoint as C, type WikiConfig as D, type EntityStatus as E, type FormatContextOptions as F, type GraphNeighborhood as G, HEAL_BATCH_SIZE as H, type WikiEdge as I, type WikiEvent as J, type WikiFact as K, type LLMProvider as L, type MemoryBundle as M, type WikiMemoryTestAccess as N, type OntologyManifest as O, type PromptOverrides as P, type WikiOutboxEvent as Q, type ReadOptions as R, type SQLiteAdapter as S, type WikiTask as T, WikiTransactionError as U, type VectorRanker as V, type WikiOptions as W, EmbeddingService as X, ImportExportService as Y, IngestionService as Z, JobManager as _, type MemoryDump as a, RetrievalService as a0, SearchService as a1, WriteService as a2, type FormattedMemoryDump as b, WikiMemory as c, type ExtractedFact as d, type ExtractedFactEdge as e, type ExtractedFactWithOntology as f, type ExtractedTask as g, type GraphTraversalOptions as h, HEAL_RECHECK_MS as i, HOOK_TIMEOUT_MARKER as j, type HealResult as k, ONTOLOGY_BACKFILL_BATCH_SIZE as l, ONTOLOGY_BACKFILL_MAX_PROMPT_CHARS as m, ONTOLOGY_BACKFILL_RECHECK_MS as n, type OntologyBackfillResult as o, type OntologyConfig as p, type OntologyEdgeType as q, type OntologyMode as r, type OntologyNodeType as s, type OntologyPromptContext as t, type OntologyUpdates as u, PromptService as v, PrunePartialFailureError as w, type VectorRankerFallback as x, type VectorRankerRankArgs as y, type VectorRankerSemanticResult as z };

package/dist/testing.d.mts

@@ -1,2 +1,2 @@
-export { Q as EmbeddingService, T as ImportExportService, U as IngestionService, X as JobManager, X as JobManagerType, Y as MaintenanceService, Z as RetrievalService, _ as SearchService, _ as SearchServiceType, I as WikiMemoryTestAccess, $ as WriteService } from './testing-CBjAuTSl.mjs';
+export { X as EmbeddingService, Y as ImportExportService, Z as IngestionService, _ as JobManager, _ as JobManagerType, $ as MaintenanceService, a0 as RetrievalService, a1 as SearchService, a1 as SearchServiceType, N as WikiMemoryTestAccess, a2 as WriteService } from './testing-DCRNie7k.mjs';
 import 'minisearch';

package/dist/testing.d.ts

@@ -1,2 +1,2 @@
-export { Q as EmbeddingService, T as ImportExportService, U as IngestionService, X as JobManager, X as JobManagerType, Y as MaintenanceService, Z as RetrievalService, _ as SearchService, _ as SearchServiceType, I as WikiMemoryTestAccess, $ as WriteService } from './testing-CBjAuTSl.js';
+export { X as EmbeddingService, Y as ImportExportService, Z as IngestionService, _ as JobManager, _ as JobManagerType, $ as MaintenanceService, a0 as RetrievalService, a1 as SearchService, a1 as SearchServiceType, N as WikiMemoryTestAccess, a2 as WriteService } from './testing-DCRNie7k.js';
 import 'minisearch';

package/dist/testing.js

@@ -969,6 +969,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) {
@@ -987,10 +991,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;
@@ -1261,6 +1265,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;
@@ -1361,7 +1367,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);
     }
@@ -1613,9 +1619,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;
@@ -1626,6 +1644,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;
@@ -1633,7 +1652,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) {
@@ -1643,7 +1662,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) => {
@@ -1696,7 +1729,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);
@@ -1705,7 +1738,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) {
@@ -1735,8 +1767,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) {
@@ -1750,6 +1788,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) {
@@ -3113,6 +3165,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;
@@ -3120,6 +3173,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) {
@@ -3141,6 +3195,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) {
@@ -3151,6 +3207,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;
@@ -3158,8 +3222,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);
       }