@avantf/dsh-mem 0.6.0 → 0.6.1

package/lib/client.js

@@ -5346,6 +5346,7 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
 				offset: count.optional(),
 				reason: optionalText.optional(),
 				dry_run: bool.optional(),
+				store: optionalText.optional(),
 				contradiction_id: count.optional(),
 				resolution: optionalText.optional(),
 				loser_fact_id: count.optional()

package/lib/engine/mem/db/dao/chunks.d.ts

@@ -104,12 +104,48 @@ export declare class ChunksDao {
         vec: Buffer;
         embedding_model: string | null;
     }[];
+    /**
+     * Vector-space health of the WHOLE chunk corpus, by kind, WITHOUT decoding a single blob.
+     *
+     * The same two counts the open-time warning reports (`stale` = wrong width, `space_stale` = same
+     * width but another recorded space — `embedding_model IS NOT` is null-safe, so a row with no
+     * recorded space counts as foreign exactly like the JS comparison in `reloadIndex`) plus `missing`
+     * (no vector at all), which is the third reason the semantic leg cannot use a chunk.
+     *
+     * This is what lets the shared repair flow read "what is stale" cheaply per slice instead of
+     * re-scanning and hashing the corpus (`corpusState` reads every text; a batched migration must
+     * not).
+     */
+    vectorSpaceCounts(space: string, expectedBytes: number): {
+        stale: number;
+        space_stale: number;
+        missing: number;
+    };
+    /** Chunks with no persisted vector — the repair flow's `missing` term in `remaining`. */
+    countMissingVectors(): number;
+    /**
+     * Chunks the semantic leg cannot use (no vector / wrong width / another space), bounded and
+     * ordered by id — the repair flow's encode source.
+     *
+     * The content-hash check `vectorReusable` adds is deliberately NOT here: a chunk whose vector is
+     * in the current space is usable even if its text was edited behind the store's back, and that
+     * (rarer) case belongs to `kb_reindex`, which re-derives every leg. Repairing the SPACE must not
+     * pay a jieba/hash pass over the corpus to find rows the space change did not touch.
+     */
+    staleVectorRows(space: string, expectedBytes: number, limit: number): {
+        chunk_id: number;
+        text: string;
+    }[];
     count(): number;
     /**
-     * Replace the entity rows of the given chunks in one transaction (`replace` clears the
-     * old rows first — used by reindex, where the extractor may have changed).
+     * Replace the entity rows of the given chunks in one transaction.
+     *
+     * `replace` is REQUIRED, not defaulted: `true` clears the old rows first (the entity sweep, where
+     * the extractor may have changed), `false` is the ingest path, where the chunk ids are freshly
+     * inserted and an absent old row set. A default would let one caller silently inherit the other's
+     * semantics — an extra `DELETE` per chunk on ingest, or an append-on-top-of-stale sweep.
      */
-    replaceEntities(rows: readonly ChunkEntityRow[], replace?: boolean): void;
+    replaceEntities(rows: readonly ChunkEntityRow[], replace: boolean): void;
     /** Batched entity bags: `Map<chunkId, names>` (ids with none are absent). */
     entityBags(ids: readonly number[]): Map<number, string[]>;
     /** Chunk body + owning-document identity for the fused candidate ids. */
@@ -127,11 +163,31 @@ export declare class ChunksDao {
      * for the rows that are actually out of date (DESIGN §20).
      */
     corpusState(domain?: string): ChunkStateRow[];
+    /**
+     * Chunk rows whose `chunk_entities` were produced by OLDER extraction rules — the entity sweep's
+     * selection, bounded and ordered by id.
+     *
+     * `COALESCE(entities_version, 0) < :version`, not `entities_version != :version`: the column is
+     * NULLABLE on purpose (a row written before the derived-state columns existed must look stale
+     * exactly once and be adopted by the first rebuild — see `ChunkStateRow`), and a bare `<` would
+     * evaluate to NULL for those rows and let them hide from the sweep forever.
+     *
+     * The predicate is index-served in id order (`doc_chunks` is keyed by `chunk_id`), so the LIMIT
+     * bounds what is READ, not only what is rebuilt — the same property `FactsDao.staleEntityRows`
+     * documents for the memory side.
+     */
+    chunkEntityRows(version: number, limit: number, domain?: string): {
+        chunk_id: number;
+        text: string;
+    }[];
+    /** How many chunks still carry entity rows from older rules — the sweep's `deferred` source. */
+    countStaleEntityChunks(version: number, domain?: string): number;
     /** Rebuild the FTS index from the content table (write-path maintenance). */
     rebuildFts(): void;
     /** Active chunks sharing at least one entity name with the query (jaccard candidate set). */
     /**
-     * Entity-overlap candidates, most-shared first and CAPPED (see the memory store's sibling).
+     * Entity-overlap candidates, highest-score first and CAPPED (see the memory store's sibling;
+     * the score/order tail itself lives in `./shared.js#entityCandidateTail`).
      *
      * `limit` is applied per name-batch and the batches are unioned, so the result is bounded by
      * `limit x ceil(names/batch)` — corpus-independent, which is what this query can promise. The

package/lib/engine/mem/db/dao/shared.d.ts

@@ -0,0 +1,153 @@
+/**
+ * The DAO layer's SHARED ALGORITHMS AND CONTRACTS.
+ *
+ * DAOs are split by AGGREGATE, not by store (`docs/vector-repair-shared-flow.md` §2), and each
+ * aggregate keeps its own SQL text: replacing a readable statement with a generic
+ * table/column-parameterized builder would cost the comments' index reasoning without converging a
+ * business rule — a `count`/`get`/`delete`/`list` one-liner is a different aggregate's statement,
+ * not a fork (§4.5 "明确不收敛").
+ *
+ * What DOES get one implementation here is the part that is literally "one rule, two tables":
+ *
+ *  - the entity-candidate leg's SCORE and ORDER, plus its batch/union loop
+ *    ({@link entityCandidates} / {@link entityCandidateTail});
+ *  - the batched `UPDATE … SET entities_version = ?` ({@link setEntitiesVersionBatch});
+ *  - the short-query LIKE fallback's build/guard/double-bind protocol
+ *    ({@link likeSubstringLeg});
+ *  - the document-frequency query shape ({@link queryDocFrequency});
+ *  - the batched "entity-name bags for a row-id set" read ({@link entityBags}).
+ *
+ * Each caller still supplies its own statement (or its `FROM`/name/filter pieces), so the SQL stays
+ * at the call site while the rule lives here exactly once. No base class: every export is a free
+ * function, the style `store/common.ts` established.
+ */
+import type { Db } from '../port.js';
+/**
+ * The entity-candidate leg's ORDER contract — the tail every candidate statement ends with.
+ *
+ * The formula is the leg's own score (anchored Jaccard with a saturating union,
+ * `store/entity_leg.ts`): `shared / (queryWidth + min(total - shared, widthCap))`. Ordering by it is
+ * load-bearing, not cosmetic: `fuse` scales each leg by its maximum, and a survivor's scaled value
+ * is unchanged only when the ordering — and therefore the maximum — survives the trim. A narrower
+ * row sharing one entity can therefore outrank a wide one sharing two, and the cap keeps it.
+ * `total ASC` is only a deterministic tie-break among equal ratios, and the id makes the order total.
+ *
+ * `idColumn` is the aggregate's own id (`fa.fact_id` / `ce.chunk_id`); that, the `total` subquery's
+ * table and the filter predicates are the ONLY differences between the two statements.
+ */
+export declare function entityCandidateTail(idColumn: string): string;
+/** One call to the shared entity-candidate runner — see {@link entityCandidates}. */
+export interface EntityCandidateQuery {
+    /** The (anchor) names to match: one `IN (…)`, or one per batch when {@link batchNames}. */
+    names: readonly string[];
+    /**
+     * NULL-able filter values bound right AFTER the name list and BEFORE `queryWidth`, in the SQL's
+     * own order (both callers spell their predicates as `(? IS NULL OR …)`, so a value the filter
+     * does not use is still bound as `null`).
+     */
+    filterParams: readonly unknown[];
+    limit: number;
+    /** The query's FULL entity count (`W` in `store/entity_leg.ts`); `widthCap` is its saturating cap. */
+    queryWidth: number;
+    widthCap: number;
+    /**
+     * `true` (knowledge): run one statement per name-batch and UNION the ids, because the query can in
+     * principle carry more names than a single `IN (…)` may bind. A union of per-batch tops is NOT a
+     * top-N, so that caller must enforce its real cap on the union AFTER scoring.
+     * `false` (memory): one statement and one exact `LIMIT` — the store's names are request-bounded,
+     * so a single `LIMIT` is already the top-N and the cap argument above holds bit-for-bit.
+     */
+    batchNames: boolean;
+    /**
+     * The full statement for one placeholder list; it must project `id`, `shared`, `total` and end
+     * with {@link entityCandidateTail}.
+     */
+    sql: (placeholders: string) => string;
+}
+/**
+ * Run an entity-candidate query: bind order, batching and union are shared; the SQL is the caller's.
+ *
+ * Bind order (identical in both aggregates): `<names …>, <filterParams …>, queryWidth, widthCap, limit`.
+ */
+export declare function entityCandidates(db: Db, q: EntityCandidateQuery): number[];
+/**
+ * The batched `UPDATE … SET entities_version = ?` shared by `FactsDao` and `ChunksDao`.
+ *
+ * Only the aggregate's `table` / `idColumn` differ. Returns the summed `changes`; the knowledge
+ * caller ignores it (its method's signature returns `void`), the memory caller's `number` is
+ * unchanged.
+ */
+export declare function setEntitiesVersionBatch(db: Db, table: string, idColumn: string, ids: readonly number[], version: number): number;
+/** The per-aggregate pieces of the document-frequency query — see {@link queryDocFrequency}. */
+export interface DocFrequencyQuery {
+    /** `FROM …` with its JOINs: everything between the projection and `WHERE`. */
+    from: string;
+    /** The name expression (`e.name`, `name`), used as the alias, the IN predicate and `GROUP BY`. */
+    nameExpr: string;
+    /** A constant predicate ANDed after the IN clause; it must add NO bind parameters. */
+    where?: string;
+}
+/**
+ * Document frequency — "how many rows carry each name".
+ *
+ * Shared by `EntitiesDao.activeDocFrequency` and `ChunksDao.docFrequency`; the only difference is
+ * the population the caller's `where`/`from` describe (memory counts ACTIVE facts, knowledge has no
+ * status column and counts chunks). Only the caller's QUERY names are looked up, so this is one
+ * indexed COUNT per name rather than a corpus scan. A name absent from the map has frequency 0.
+ */
+export declare function queryDocFrequency(db: Db, names: readonly string[], q: DocFrequencyQuery): Map<string, number>;
+/** The two SQL fragments {@link likeSubstringLeg} hands back to the caller's statement builder. */
+export interface LikeSubstringFragments {
+    /** The `WHERE` predicate (OR of the term patterns). */
+    any: string;
+    /** The score expression (count of the terms the row contains), to be aliased as `rank`. */
+    count: string;
+}
+/**
+ * The SHORT-QUERY LIKE fallback shared by `FactsDao.ftsSubstringSearch` and
+ * `ChunksDao.ftsSubstringSearch`.
+ *
+ * The predicate text itself already comes from `db/tokenizer.ts#likeSubstring`; this owns the
+ * protocol AROUND it, which both copies spelled out:
+ *
+ *  1. build the fragments — empty terms yield no patterns, which means "match nothing" ⇒ `[]`;
+ *  2. `count` lands in the SELECT and `any` in the WHERE, so the SAME pattern list is bound TWICE:
+ *     once with the SELECT's placeholders, then — after the caller's filter params — with the
+ *     WHERE's;
+ *  3. `LIMIT ?` last, defaulting to `-1` (unbounded; the store bounds the leg).
+ *
+ * `ORDER BY rank DESC, <id> ASC` stays in the caller's SQL: the id column is aggregate-specific and
+ * `rank` must read the SELECT alias, so the fragments and the patterns are built once and used twice.
+ */
+export declare function likeSubstringLeg(db: Db, column: string, terms: readonly string[], buildSql: (fragments: LikeSubstringFragments) => string, filterParams?: readonly unknown[], limit?: number): {
+    id: number;
+    rank: number;
+}[];
+/** The per-aggregate SQL pieces of {@link entityBags}. */
+export interface EntityBagsQuery {
+    /** `FROM …` with its alias: `fact_entities fe` / `chunk_entities`. */
+    table: string;
+    /** The id expression, also the `WHERE … IN (…)` subject: `fe.fact_id` / `chunk_id`. */
+    keyColumn: string;
+    /** The name expression: `e.name` / `name`. */
+    nameColumn: string;
+    /** The `JOIN` that reaches the name vocabulary, for aggregates that have one (`''`/omitted for `chunk_entities`). */
+    joinEntities?: string;
+    /**
+     * The DEFAULT semantics — the one real difference between the two callers, so it is explicit:
+     *
+     *  - `true` (memory): every requested id is pre-seeded with `[]` in the REQUEST's order, so the
+     *    caller can assume `bags.get(id)` exists. Names are appended in row order after that;
+     *  - `false` (knowledge): only rows that actually carry entities appear (the caller uses `?? []`).
+     */
+    seedEmpty: boolean;
+}
+/**
+ * Batched entity-name bags for a row-id set: `Map<rowId, names>`.
+ *
+ * Shared by `EntitiesDao.bagsForFacts` and `ChunksDao.entityBags` (§4.6.3): one `IN (…)` statement
+ * per `batches()` slice, rows folded into the map in first-seen order. The SQL SHAPE is the only
+ * aggregate-specific part (`table` / `keyColumn` / `nameColumn` / `joinEntities`); the crucial
+ * `seedEmpty` difference above is the caller's to declare and stays observable.
+ */
+export declare function entityBags(db: Db, ids: readonly number[], q: EntityBagsQuery): Map<number, string[]>;

package/lib/engine/mem/eval/index.d.ts

@@ -0,0 +1,4 @@
+export * from './metrics.js';
+export * from './loader.js';
+export * from './runner.js';
+export * from './write_metrics.js';

package/lib/engine/mem/index.d.ts

@@ -20,6 +20,7 @@ export * from './dispatch.js';
 export * from './runtime.js';
 export * from './store/memory.js';
 export * from './store/knowledge.js';
+export * from './store/vector_repair.js';
 export * from './store/hybrid.js';
 export * from './store/source_picker.js';
 export * from './store/lexical.js';

package/lib/engine/mem/runtime.d.ts

@@ -1,4 +1,4 @@
-import type { AdminRequest, KbAddRequest, KbConflictReport, KbRequest, QueryRequest, RecallRequest, RecallResult, RememberRequest } from '../mem-contract/index.js';
+import type { AdminRequest, KbAddRequest, KbConflictReport, KbRequest, QueryRequest, RecallRequest, RecallResult, RememberRequest, VectorsFixReport } from '../mem-contract/index.js';
 import { type AvantfLogger, type StatsSummary } from '../mem-contract/index.js';
 import { type SemanticBackend } from '../mem-retrieval/index.js';
 import { type LoadedConfig } from './config/loader.js';
@@ -153,7 +153,7 @@ export type AdminDispatch = {
     }>): StoreResult<MemoryStore, 'vectorsDiagnose'>;
     (req: Extract<AdminRequest, {
         action: 'vectors_fix';
-    }>): StoreResult<MemoryStore, 'vectorsFix'>;
+    }>): Promise<VectorsFixReport>;
     (req: Extract<AdminRequest, {
         action: 'contradict_check';
     }>): StoreResult<MemoryStore, 'checkContradictions'>;

package/lib/engine/mem/store/entity_sweep.d.ts

@@ -0,0 +1,121 @@
+/**
+ * The ONE entity-version sweep both stores run.
+ *
+ * `entities_version` is the stamp that says "these entity rows were produced by the CURRENT
+ * extraction rules". A rule change makes every row carrying an older stamp stale, and the only way
+ * to close that gap is to re-extract those rows' text — for memory the entity links, the triples and
+ * the HRR bundle derived from them; for knowledge the `chunk_entities` rows. That SKELETON was
+ * written twice and drifted apart in exactly the ways a copy drifts: memory had the in-flight guard,
+ * the budget clamp and the `{rebuilt, deferred, skipped}` report, while knowledge had the same
+ * selection inlined in `reindex` with no guard at all. This module is the one copy; the stores
+ * contribute a per-aggregate adapter (which rows, how to extract, what to write) and nothing else.
+ *
+ * Layering, deliberate: this is an ORCHESTRATION rule, not SQL, so it lives beside `common.ts` and
+ * `legs.ts` in `store/` — the DAO layer stays split by aggregate and keeps its own statements
+ * (`docs/vector-repair-shared-flow.md` §2 / §7).
+ *
+ * What must NOT move here: the extractor, the rows a store writes, and that store's side effects.
+ * Memory's transaction also replaces triples, moves the HRR bundle and re-queues the conflict check
+ * (both conflict legs read what the sweep rebuilt); knowledge replaces `chunk_entities` under
+ * `MAX_ENTITIES_PER_CHUNK`. Those are domain semantics, and folding them in would trade one
+ * duplicated loop for two conditional branches.
+ *
+ * @module store/entity_sweep
+ */
+/**
+ * What one bounded sweep pass did.
+ *
+ * `rebuilt` counts rows this pass re-extracted AND wrote — its batch size when it filled it. The
+ * stamp is what makes a corpus current, so a row re-extracted to the same names still counts (and is
+ * not selected again); a row whose write FAILED does not, because its old stamp survives. It is
+ * deliberately not "rows whose extraction output changed", which no caller could use: they drain a
+ * stale corpus by looping until `deferred === 0`.
+ */
+export interface EntitySweepReport {
+    /** Rows this pass re-extracted and wrote (its batch size, when it filled it and nothing failed). */
+    rebuilt: number;
+    /** Rows still carrying an older stamp after this pass. */
+    deferred: number;
+    /** Another pass was already running, so this one did nothing (`deferred` is still current). */
+    skipped: boolean;
+}
+/**
+ * Rows one sweep pass may rebuild when the caller names no budget.
+ *
+ * `MemoryStore.reindexEntities` has always defaulted to this, and the CLI passes it explicitly; it
+ * lives here so the shared loop and that public re-export cannot drift. Bounds MEMORY, not only
+ * mission: a pass selects every chosen row's text before rebuilding the first one.
+ */
+export declare const ENTITY_SWEEP_BATCH = 2000;
+/**
+ * A row the sweep may rebuild, as far as the SHARED loop is concerned.
+ *
+ * Deliberately unconstrained: the loop only routes a row from the selection to the adapter's own
+ * `extractAndWriteEntities`, so it must not name any column. Memory's row carries
+ * `{ fact_id, content }`, knowledge's `{ chunk_id, text }` — parameterizing the loop over the
+ * store's row type is what keeps those names out of the orchestration layer.
+ */
+export type EntitySweepRow = object;
+/**
+ * Per-store primitives. One adapter per aggregate, deliberately narrow.
+ *
+ * `staleEntityBatch` returns BOTH the scope's full stale count and a bounded slice in one read: the
+ * loop needs the remaining count for its report and the rows for its mission, and two queries would
+ * scan the same table twice. The two numbers must describe the same population: `total` counts every
+ * row the store's scope considers stale (memory: every ACTIVE fact; knowledge: every chunk of the
+ * sweep's domain scope), and `rows` is that population ordered by id, truncated to `limit`.
+ */
+export interface EntitySweepTarget<T extends EntitySweepRow> {
+    /**
+     * The scope's full stale count plus at most `limit` of those rows, ordered by id.
+     *
+     * `limit` is `maxPerPass`; the loop calls this once per pass. Both numbers must describe the SAME
+     * population — `total` is every stale row of the store's scope (memory: every ACTIVE fact;
+     * knowledge: every chunk of the sweep's domain), `rows` is that population truncated.
+     */
+    staleEntityBatch(limit: number): {
+        total: number;
+        rows: readonly T[];
+    };
+    /**
+     * Optional count-only read of the SAME population as {@link staleEntityBatch}'s `total`.
+     *
+     * It exists for the guard branch, which needs the current deferred count and no rows; absent, that
+     * branch falls back to `staleEntityBatch(0).total`. The loop holds the guard for the whole pass and
+     * each store is single-threaded, so the count cannot move between the two calls it makes.
+     */
+    staleEntityCount?(): number;
+    /** Re-extract one row's text and write that store's derived rows. May throw; the loop isolates. */
+    extractAndWriteEntities(row: T): Promise<void>;
+    /**
+     * Log a row this pass could not rebuild. Required, not defaulted: only the store knows which
+     * column names the row in its own logs (`fact_id` / `chunk_id`), and a shared warning cannot.
+     */
+    onRowError(row: T, error: unknown): void;
+}
+/** Everything {@link sweepVersionedEntities} needs beyond the adapter. */
+export interface EntitySweepOptions {
+    /** Rows this pass may rebuild; defaults to {@link ENTITY_SWEEP_BATCH}, clamped at 0. */
+    budget?: number;
+    /** Return `true` to stop before the next row (plugin unloading, runtime closed). */
+    shouldStop?: () => boolean;
+}
+/**
+ * Re-extract the entity rows written by older extraction rules, ONE bounded pass.
+ *
+ * The contract, in order: take the guard (an overlapping pass reports `skipped` and does nothing);
+ * read the scope's stale count and at most `maxPerPass` rows; re-extract each row through the
+ * adapter, isolating failures; report `{ rebuilt, deferred, skipped }`.
+ *
+ * Not an unbounded drain, on purpose: this is reachable from a settings-page button and a periodic
+ * heartbeat, so it must not block on a whole stale corpus. Callers that want the corpus current loop
+ * until `deferred === 0` (the CLI does).
+ *
+ * A row whose extraction or write throws is skipped, not fatal: the transaction that stamps the
+ * version never ran, so the row is still stale and the NEXT pass retries it — the same retry contract
+ * the knowledge store used per chunk. Letting the throw escape would instead abandon the rest of the
+ * batch with no report of what was done.
+ *
+ * @param guard the store's stable in-flight identity (see {@link SWEEPING})
+ */
+export declare function sweepVersionedEntities<T extends EntitySweepRow>(target: EntitySweepTarget<T>, guard: object, opts?: EntitySweepOptions): Promise<EntitySweepReport>;

package/lib/engine/mem/store/hybrid.d.ts

@@ -234,3 +234,53 @@ export declare function applyOutputBudget<H extends BudgetInput>(config: Config,
  * the slice would spend the budget on hits that are about to be dropped.
  */
 export declare function hybridSearch<H extends BudgetInput>(deps: HybridDeps<H>, plan: HybridPlan): Promise<HybridResult<H>>;
+/**
+ * The search-entry fields `MemoryStore.search` and `KnowledgeStore.search` hand to the orchestrator.
+ * Both stores' option types (`SearchInput` / `KnowledgeSearchOptions`) satisfy this structurally;
+ * everything else on them (`category` / `source` / `domain` / `includeHrr` / `track` / `onResult`) is
+ * leg- or domain-specific and stays at the store.
+ */
+export interface HybridSearchEntryFields {
+    limit?: number;
+    /**
+     * Knowledge only: overrides the config-derived pool size. Memory's `SearchInput` has no such field
+     * and leaves the plan key absent (see {@link runHybridSearch}).
+     */
+    overFetch?: number;
+    maxTokens?: number;
+    queryVector?: Float32Array;
+    recordStats?: boolean;
+    floors?: FloorProfile;
+    includeScores?: boolean;
+    relaxLegs?: readonly FloorLeg[];
+    rewriteQuery?: (query: string) => string | undefined;
+}
+/**
+ * Map a store's search arguments onto {@link HybridPlan} and run {@link hybridSearch}. ONE copy.
+ *
+ * Before this, `MemoryStore.search` and `KnowledgeStore.search` carried the mapping verbatim side by
+ * side: the same field list, the same conditional spreads, the same call. That list is part of the
+ * orchestrator's contract, so an option added to one entry point and not the other would silently
+ * make the two stores query differently — the same shape of drift this module already documents
+ * (`NaN` limit, `over_fetch_factor`, unrecorded capped legs).
+ *
+ * The conditional spreads are deliberate, not cosmetic: a caller that did not pass `overFetch` /
+ * `includeScores` / `relaxLegs` / `rewriteQuery` leaves the plan key ABSENT rather than
+ * present-with-`undefined`. The orchestrator reads all four through `??` / `=== true` today, so the
+ * two are indistinguishable now — but the plan is a contract, and widening it with keys the caller
+ * never set is how "absent means default" decays into "present-undefined means set to nothing".
+ */
+export declare function runHybridSearch<H extends BudgetInput>(deps: HybridDeps<H>, query: string, fields: HybridSearchEntryFields | undefined): Promise<HybridResult<H>>;
+/**
+ * The mapping itself, separated from the call so it can be pinned directly: the contract here is
+ * the SHAPE of the plan (which keys exist), which no behavioural assertion inside `hybridSearch`
+ * could observe once every optional field is read through `??` / `=== true`.
+ */
+export declare function hybridPlanOf(query: string, fields: HybridSearchEntryFields | undefined): HybridPlan;
+/**
+ * Build a store's {@link HybridDeps} — the ONE construction site for the contract fields both stores
+ * share (`kind` / `config` / `semantic` / `legs` / `texts` / `hits` / `onReturn`). The per-store half
+ * is `parts`; the stores used to spell the whole object out twice, so a new required `HybridDeps`
+ * field was a change to remember in two places.
+ */
+export declare function makeHybridDeps<H>(kind: 'memory' | 'knowledge', config: Config, semantic: SemanticBackend, parts: Pick<HybridDeps<H>, 'legs' | 'texts' | 'hits' | 'onReturn'>): HybridDeps<H>;

package/lib/engine/mem/store/knowledge.d.ts

@@ -1,8 +1,9 @@
-import { type AvantfLogger, type Config, type DocumentDetail, type DocumentSummary, type DomainCatalog, type FloorProfile, type ImportResult, type IngestResult, type KbConflictReport, type KbIngestConflict, type KbSyncReport, type KnowledgeConfig, type RecallHit, type ReindexReport } from '../../mem-contract/index.js';
+import { type AvantfLogger, type Config, type DocumentDetail, type DocumentSummary, type DomainCatalog, type FloorProfile, type ImportResult, type IngestResult, type KbConflictReport, type KbIngestConflict, type KbSyncReport, type KnowledgeConfig, type RecallHit, type ReindexReport, type VectorMigrationOutcome, type VectorMigrationProgress, type VectorSpaceHealth, type VectorsFixStoreReport } from '../../mem-contract/index.js';
 import type { SemanticBackend, VectorStore } from '../../mem-retrieval/index.js';
 import { type LexicalProbe } from './lexical.js';
 import { type FloorLeg } from './floors.js';
 import { type HybridResult } from './hybrid.js';
+import { type VectorRepairTarget } from './vector_repair.js';
 /** Options for {@link KnowledgeStore.search}. */
 export interface KnowledgeSearchOptions {
     domain?: string;
@@ -110,6 +111,15 @@ export declare class KnowledgeStore {
     private readonly docFiles;
     /** > 0 while a batch (directory import) is writing: commits and baseline refreshes wait. */
     private deferCorpusWrites;
+    /**
+     * Identity object for the shared entity sweep's in-flight guard (`store/entity_sweep.ts`).
+     *
+     * The guard itself lives in that module; this is only the per-store identity it keys on. It exists
+     * as a field — rather than the adapter object, which is built per call — because the guard must
+     * survive between two overlapping calls: `reindex` can be reached from a tool call and the
+     * settings-page button at once, and both would select the same stale chunks.
+     */
+    private readonly entitySweepGuard;
     /**
      * Per-file stamps (`path → mtimeMs:size`) and the file-set they were taken from, so a reconcile
      * can ask "what changed?" for the price of one `stat` per document instead of reading and
@@ -132,13 +142,18 @@ export declare class KnowledgeStore {
     /** The store config file `addDomain` writes the allowlist back to (`knowledgeConfigPath(home)`). */
     domainConfigPath: string, logger?: AvantfLogger | undefined);
     /**
-     * Rebuild the in-memory vstore from persisted chunk vectors.
+     * Rebuild the in-memory vstore from persisted chunk vectors, and say loudly what belongs to
+     * another vector space.
+     *
+     * Also detects a VECTOR-SPACE change, which the reload itself cannot see: the reload checks the
+     * width, and a different model at the same width produces dim-valid vectors that are then ranked
+     * against the current query's — two spaces mixed in one index, with no error anywhere.
      *
-     * Also detects a VECTOR-SPACE change, which the reload itself cannot see: `reloadVectorIndex`
-     * checks the width, and a different model at the same width produces dim-valid vectors that are
-     * then ranked against the current query's — two spaces mixed in one index, with no error anywhere.
-     * The memory store always said something about this; the knowledge store did not, so a model swap
-     * degraded every semantic query here until someone happened to run `kb_reindex`.
+     * The reload, the count and the warning are the SHARED open-time step (`store/vector_repair.ts`),
+     * which is what turned the knowledge store from "warns about a swapped model but never repairs it"
+     * into the same automatic path memory has always had; this store's half is the row read. The
+     * manual entry stays `vectors --fix` (the vector-only repair); `kb_reindex` remains the full
+     * FTS + entities + vectors re-entry.
      */
     private reloadIndex;
     /**
@@ -243,8 +258,6 @@ export declare class KnowledgeStore {
     warnings?: string[]): Promise<IngestResult>;
     /** Materialize one document's editable copy; returns the `file` / `file_error` result fields. */
     private writeManagedFile;
-    /** Batched eviction from the live vector index (removeMany when the backend supports it). */
-    private evictVectors;
     /** The resolved ingestion boundary (see `ingest_guard.ts`). */
     private get ingestLimits();
     /**
@@ -288,7 +301,8 @@ export declare class KnowledgeStore {
      */
     private writeReusedVectors;
     /**
-     * Encode texts ONE AT A TIME, writing every `WRITE_BATCH` vectors in one transaction.
+     * This store's half of the shared encode-and-persist flow (`store/vector_repair.ts`): the backend
+     * call, the live index and the `WRITE_BATCH` transaction this store measured its way into.
      *
      * The model call is deliberately NOT batched, and that is a MEASURED decision, not an omission:
      * a batched forward pass pads each item to the longest in its group, and real chunks span 53–550
@@ -299,7 +313,17 @@ export declare class KnowledgeStore {
      * length-sorted) for callers whose texts suit it.
      *
      * What DID pay off is the write side: one commit per `WRITE_BATCH` chunks instead of one per
-     * chunk (measured 14.2 µs/row vs 2.2 µs/row), and the transaction never spans an `await`.
+     * chunk (measured 14.2 µs/row vs 2.2 µs/row), and the transaction never spans an `await` — that
+     * is the `writeBatch` below.
+     */
+    private encodeWriteTarget;
+    /**
+     * Encode texts one at a time and persist them in `WRITE_BATCH` transactions.
+     *
+     * A failed chunk is skipped, not thrown: the rows are already committed and their old vectors
+     * evicted by the ingest path, so a throw here would leave the caller with a failed ingest and NO
+     * COUNT of what was skipped. The shortfall travels back to the tool result
+     * (`IngestResult.vectors_failed`) instead of living only in a log line.
      */
     private encodeAndStore;
     /**
@@ -309,6 +333,59 @@ export declare class KnowledgeStore {
      * of silently mixing two spaces. Public so diagnostics and tests can name the space.
      */
     vectorSpace(): string;
+    /**
+     * Cheapest possible DETECTION of "the embedding space changed under this store": counts of
+     * persisted chunk vectors whose width or recorded space id no longer matches the one this store
+     * writes into. Reads blob LENGTHS only — never decodes — so the startup warning and the background
+     * drive can afford it at any corpus size.
+     */
+    vectorSpaceHealth(): VectorSpaceHealth;
+    /** {@link vectorSpaceHealth} plus `missing`, the third term of the repair flow's `remaining`. */
+    private vectorSpaceCounts;
+    /** Async bootstrap the semantic backend (the shared flow's explicit-fix warmup). */
+    warmupSemantic(): Promise<boolean>;
+    /**
+     * This store's half of the shared repair flow (`store/vector_repair.ts`): the primitives the flow
+     * steps. The flow itself — batch size, event-loop yield, stop / resume / no-progress rules,
+     * `semantic.auto_migrate`, the dry-run split — lives there once, for both stores.
+     */
+    vectorRepairTarget(): VectorRepairTarget;
+    /**
+     * The chunks the semantic leg cannot use (no vector / wrong width / another space). One SQL
+     * aggregate over blob lengths; `dropIds` is empty because knowledge overwrites in place.
+     */
+    private classifyRepairVectors;
+    /**
+     * Encode + persist up to `limit` chunks the semantic leg cannot use, bounded and ordered by id.
+     *
+     * It does NOT re-extract entities or rebuild FTS: that is `kb_reindex`'s job, and the whole point
+     * of the automatic repair is that the vector half can run on its own — which is exactly the
+     * objection the "known boundary" in DESIGN §20 used to raise against a background run.
+     */
+    private reencodeStaleChunks;
+    /**
+     * The explicit, unbounded repair behind `mem_admin vectors_fix` / `avantf-mem vectors --fix`.
+     * `dry_run` previews every count without writing — and without loading the model, which is why
+     * the preview also reports `would_warm` (see the contract's `VectorsFixStoreReport`).
+     */
+    vectorsFix(dryRun?: boolean): Promise<VectorsFixStoreReport>;
+    /**
+     * ONE bounded slice of the vector-space migration: at most `batchSize` chunks are re-encoded, so
+     * the caller keeps control of the event loop between slices. This is the unit the background
+     * migration ({@link migrateVectors}) and its tests drive.
+     */
+    migrateVectorsBatch(batchSize?: number): Promise<VectorMigrationProgress>;
+    /**
+     * Drive the bounded background migration for this store until it is current, the model is
+     * unavailable, or `shouldStop()` turns true (plugin unmount / process shutdown). The loop, the
+     * `semantic.auto_migrate` switch, the no-progress rule and the store-named logging all live in the
+     * shared flow (`store/vector_repair.ts`); this is the one-store entry.
+     */
+    migrateVectors(opts?: {
+        batchSize?: number;
+        shouldStop?: () => boolean;
+        onProgress?: (progress: VectorMigrationOutcome) => void;
+    }): Promise<VectorMigrationOutcome>;
     /**
      * A stored vector is reusable when it exists, matches the space, and its text is unchanged.
      *
@@ -319,8 +396,28 @@ export declare class KnowledgeStore {
      * the store would keep serving a vector for text it no longer holds.
      */
     private vectorReusable;
-    /** One transaction replacing the entity rows of the given chunks (shared by ingest + reindex). */
+    /**
+     * Extract one chunk's entity names, bounded by `MAX_ENTITIES_PER_CHUNK`.
+     *
+     * The bound is here, not in either caller: it is a property of what `chunk_entities` may hold for
+     * one chunk, and the ingest path and the sweep must not disagree about it.
+     */
+    private extractRowEntities;
+    /** One transaction replacing the entity rows of the given chunks (the ingest path). */
     private replaceChunkEntities;
+    /**
+     * The per-row primitive of the shared entity sweep (`store/entity_sweep.ts`).
+     *
+     * Replaces ONE chunk's entity rows and stamps that same row with `ENTITY_EXTRACTOR_VERSION`, in one
+     * transaction. Knowledge's domain difference from memory is exactly this: memory's transaction also
+     * moves triples, the HRR bundle and the conflict queue, while a chunk has none of those — its
+     * derived state is the entity names alone.
+     *
+     * Per row, not per batch, because the sweep's contract is that a failure leaves THAT row stale and
+     * retryable: inside a batched transaction one bad extraction would roll back the whole batch, and
+     * rows it never reached would look stamped.
+     */
+    private replaceRowEntities;
     /**
      * Ingest local files/directories. Every path goes through the SAME boundary as
      * `ingestUri` — a bare `kb_import` on `~/.ssh` would otherwise be the exact
@@ -459,6 +556,13 @@ export declare class KnowledgeStore {
      * re-encoding (performance review §7.7 / P8).
      */
     private semanticPath;
+    /**
+     * The semantic leg's scope filter, as a `filterTopk` primitive: `undefined` when NO domain/source
+     * was asked means "keep the whole pool" — the short-circuit is preserved, so no `chunks.meta`
+     * lookup runs at all. Otherwise one batched lookup, and rows whose domain/source do not match (or
+     * whose chunk is gone) are dropped.
+     */
+    private scopeFilter;
     /**
      * Sync relevance probe for the plugin's conditional hint (DESIGN §12). Same contract as
      * `MemoryStore.lexicalProbe` — see `store/lexical.ts`.