@avantf/dsh-mem 0.6.0 → 0.6.2

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`.

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

@@ -0,0 +1,171 @@
+/**
+ * The leg runner: how BOTH stores turn their own raw leg scores into `HybridLeg`s — plus the two
+ * leg SOURCES that were the same flow twice ({@link ftsLeg}, {@link semanticLeg}, §4.6 of
+ * `docs/vector-repair-shared-flow.md`). Both stores keep only their DAO/vstore primitives and their
+ * scope: the `-rank`/`rank` sign convention, the short-query fallback, `max(50, k)`, the dimension
+ * check's error and the Map insertion order live here once.
+ *
+ * `MemoryStore.searchLegs` and `KnowledgeStore.searchLegs` were the same skeleton written twice —
+ * a `leg()` wrapper whose `capped` flag is measured on the RAW (pre-floor) score set, the
+ * `applyTermFloor` / `applyScoreFloor` application, and the "semantic backend down ⇒ an EQUAL-WEIGHT
+ * empty leg with `droppedByFloor: 0`" fallback — and even the comments explaining them were the same
+ * paragraph twice. What legitimately differs is only the leg LIST and where each leg's scores come
+ * from: memory computes anchors once and shares them between the entity and HRR legs, has the HRR
+ * probe and the time-window scan; knowledge's entity leg is a query-driven async Jaccard. Those stay
+ * at the store, exactly as §2 of `docs/vector-repair-shared-flow.md` requires.
+ *
+ * WHY THE CAP IS MEASURED ON THE RAW SET. `size === cap` is the only observable "this leg was cut"
+ * signal (a leg that finished under the cap cannot have been trimmed), and it feeds the health
+ * counters so the headroom can be sized from data — what makes the cap measurable instead of a silent
+ * quality cliff (DESIGN §20.17). The relevance floors remove the tail anyway, so
+ * deriving the flag from the FLOORED size would erase the signal exactly when the cap bound. The
+ * floor functions only ever REMOVE entries, so the raw set is the honest measurement.
+ *
+ * WHY THE SEMANTIC LEG CARRIES NO `capped`. It is capped by the POOL size (`overFetch`), not by
+ * `legCap`, so comparing it against `legCap` would report a trim that never happened. That is why
+ * {@link LegRunner.semantic} is a separate method rather than a flag on {@link LegRunner.scored}:
+ * the absence is structural, not something a caller can forget to set.
+ *
+ * WHY COMPOSITION. No base class (see the spec §2): the two stores share no construction, DB, DAO or
+ * table, and a template-method base class would be a structural rewrite of two hub files. This is
+ * the same style as `store/common.ts` — free functions plus a small interface — so a THIRD store can
+ * be added by supplying its own leg list and sources and driving THIS runner (proved by a fake
+ * third store in `test/legs.spec.ts`).
+ *
+ * CONCURRENCY lives one level up, in `store/hybrid.ts`'s `runLegs`: it awaits the returned
+ * (value | promise) array concurrently and isolates a failing leg to itself. This module only BUILDS
+ * legs, so both stores get the same awaiting and isolation by construction.
+ *
+ * @module store/legs
+ */
+import { type FloorLeg } from './floors.js';
+import { type HybridContext, type HybridLeg } from './hybrid.js';
+import { type FtsTokenizer } from '../db/tokenizer.js';
+/**
+ * The legs {@link LegRunner.scored} may wrap: those whose raw score has an absolute scale a floor
+ * can cut. `semantic` is excluded on purpose — it shares `applyScoreFloor` but must not carry the
+ * cap signal, and it is reached through {@link LegRunner.semantic} (see the module comment).
+ */
+export type ScoredLeg = Exclude<FloorLeg, 'semantic'>;
+/** Build the leg runner for one query. `legCap` is the cap every non-semantic leg is measured against. */
+export interface LegRunner {
+    /** The per-leg row cap in force for this query (see `hybrid.ts`'s `legCapFor`). */
+    readonly cap: number;
+    /**
+     * Wrap raw scores that have NO floor of their own (memory's HRR probe and time-window scan): the
+     * cap signal is attached and nothing else — no `leg` label, no `droppedByFloor`, exactly as those
+     * legs have always shipped (they share the entity leg's weight and floor report).
+     */
+    plain(scores: Map<number, number>, weight: number): HybridLeg;
+    /**
+     * A score-floored leg: `applyScoreFloor` on the raw map, then the cap measured on the RAW map. The
+     * floored map is what the leg ships; `raw` is only ever read for the cap.
+     */
+    scored(name: ScoredLeg, raw: Map<number, number>, weight: number, floor: number): HybridLeg;
+    /**
+     * The FTS leg: the per-row term floor (`applyTermFloor`) needs the candidates' texts, read by the
+     * store for the whole raw set (one batched query). The cap is measured on the raw map.
+     */
+    term(name: 'fts', raw: Map<number, number>, texts: Map<number, string>, query: string, weight: number, floor: number): HybridLeg;
+    /**
+     * The semantic leg: score-floored like {@link scored}, but deliberately WITHOUT a `capped` key
+     * (see the module comment). The async model encode itself happens at the store, which is the only
+     * place that knows its backend and filters.
+     */
+    semantic(raw: Map<number, number>, weight: number, floor: number): HybridLeg;
+    /**
+     * The fallback for a DOWN semantic backend: an EMPTY leg at the SAME weight, reporting zero floor
+     * drops. Equal weight, not zero: the leg is absent, the weight contract (`RecallResult.weights`)
+     * must not move to a fourth value, and the orchestrator already rebalanced the weights for
+     * `semAvail === false` (`DEGRADED_WEIGHTS`).
+     */
+    semanticOff(weight: number): HybridLeg;
+}
+/**
+ * Build the leg runner for one query.
+ *
+ * The per-store leg ORDER is NOT here: it is the store's "leg list" (see §4.5 阶段 4) because leg
+ * index is part of the contract — `hybrid.ts`'s `unionLegs` merges the original and the
+ * self-reference rewrite runs BY INDEX, so a store that reordered its legs would silently re-map
+ * evidence. What this runner guarantees is that every leg, whichever order it lands in, gets the
+ * same wrapper, the same floor order and the same down-semantic fallback.
+ */
+export declare function makeLegRunner(ctx: Pick<HybridContext, 'legCap'>): LegRunner;
+/** The per-store pieces of the FTS leg — see {@link ftsLeg}. `Scope` is opaque to the flow. */
+export interface FtsLegOptions<Scope> {
+    query: string;
+    /** The per-leg row cap (the store's `legCap`), handed to whichever DAO statement runs. */
+    cap: number;
+    /** The store's scope shape (`{category, source}` / `{domain, source}`), passed straight through. */
+    scope: Scope;
+    /** The table's own tokenizer, for the `MATCH` build (`buildFtsQuery`). */
+    tokenizer: FtsTokenizer;
+    /** The FTS `MATCH` statement; its `rank` is bm25 (negative = better). */
+    search: (ftsQuery: string, scope: Scope, limit: number) => readonly {
+        id: number;
+        rank: number;
+    }[];
+    /** The short-query LIKE statement; its `rank` counts the terms the row contains (higher = better). */
+    substringSearch: (terms: readonly string[], scope: Scope, limit: number) => readonly {
+        id: number;
+        rank: number;
+    }[];
+}
+/**
+ * The FTS leg, shared by `MemoryStore.ftsPath` and `KnowledgeStore.ftsPath` (§4.6.1).
+ *
+ * The two were line-for-line the same flow — `buildFtsQuery` → the `MATCH` statement with NEGATED
+ * bm25, else `substringTerms` → the LIKE statement with `rank` — differing only in the DAO and the
+ * order its scope parameters bind. Both conventions are load-bearing and preserved verbatim:
+ *
+ *  - **bm25 is negative** (more negative = better match), so the `MATCH` branch negates it and higher
+ *    stays better everywhere downstream;
+ *  - **the LIKE `rank`** already counts contained terms, so it is used as-is, keeping the two branches
+ *    on the same "higher = better" scale;
+ *  - **an empty term list returns the empty map** (`substringTerms` yields none for a query with no
+ *    3-char run) — the leg is empty by construction, not by a query that matched nothing.
+ *
+ * THE SHORT-QUERY FALLBACK. `buildFtsQuery` returning `null` means the query carries no term the
+ * trigram index can express (measured: every term in the FTS table is 3 characters), which used to
+ * leave this leg empty by construction — the 2-char CJK shape. `substringTerms` is the one finer
+ * predicate the FTS5 trigram TABLE still answers (`LIKE '%…%'`), bounded by `cap`; the accuracy guard
+ * is the per-row term floor in `applyTermFloor`, which requires the row to CONTAIN the run.
+ */
+export declare function ftsLeg<Scope>(opts: FtsLegOptions<Scope>): Map<number, number>;
+/** The per-store pieces of the semantic leg — see {@link semanticLeg}. */
+export interface SemanticLegOptions {
+    query: string;
+    /** The requested leg size; the pool is over-fetched to `max(50, k)` below. */
+    k: number;
+    /** A caller-encoded vector for this exact query; skips {@link encode}. */
+    queryVector?: Float32Array;
+    /** Publishes the vector actually used, so the relaxed retry reuses it instead of re-encoding. */
+    onVector?: (vec: Float32Array) => void;
+    encode: (query: string) => Promise<Float32Array>;
+    /** The vstore's width, checked against the vector before it is scored. */
+    dim: number;
+    topk: (vec: Float32Array, k: number) => readonly {
+        id: number;
+        score: number;
+    }[];
+    /**
+     * The store's eligibility filter over the pool ids.
+     *
+     * `undefined` = **keep everything** — knowledge's "no domain/source asked" short-circuit stays a
+     * short-circuit (no lookup runs at all). A returned set is the allow-list; the flow still maps the
+     * pool in ITS order, so ids/scores/insertion order are the vstore's.
+     */
+    filterTopk: (ids: readonly number[]) => ReadonlySet<number> | undefined;
+}
+/**
+ * The semantic leg, shared by `MemoryStore.semanticPath` and `KnowledgeStore.semanticPath` (§4.6.2).
+ *
+ * The flow: encode (unless the caller supplied the vector) → dimension check → publish → over-fetch
+ * `max(50, k)` from the vstore → empty pool early-returns → filter → map id→score. Both stores used
+ * to spell all of it out; only the filter differs, and that difference lives in `filterTopk`.
+ *
+ * Preserved verbatim: the `max(50, k)` over-fetch (the pool must leave room for the filter to remove
+ * rows without shrinking the leg below `k`), the `RetrievalInputError` and its exact message, the
+ * empty-pool early return, and the returned map's insertion order (the vstore's pool order).
+ */
+export declare function semanticLeg(opts: SemanticLegOptions): Promise<Map<number, number>>;

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

@@ -40,6 +40,7 @@
  * path. Behaviour is unchanged there: a 2-char query scored 0 matched terms before and still does
  * (`{terms: 0, matched: 0}`), so the hint stays silent exactly as it did.
  */
+import { type FtsTokenizer } from '../db/tokenizer.js';
 /** How many of an input's terms a store holds. `terms === 0` means the input had nothing to test. */
 export interface LexicalProbe {
     terms: number;
@@ -109,3 +110,10 @@ export declare function looksRelevant(probe: LexicalProbe): boolean;
  * path is synchronous); the default keeps an exact count for the calibration recorded above.
  */
 export declare function probeTerms(text: string, holds: (term: string) => boolean, stopAt?: number): LexicalProbe;
+/**
+ * The store probe both stores' `lexicalProbe` used to spell out verbatim: build THIS store's MATCH
+ * expression for one term (the tokenizer is a property of the store's FTS table) and ask that
+ * table whether anything holds it. `probeTerms` owns the term set and the counting; this owns the
+ * one part that has to differ, which is now a single `holds` closure per store.
+ */
+export declare function probeStoreTerms(text: string, tokenizer: FtsTokenizer, holds: (ftsQuery: string) => boolean, stopAt?: number): LexicalProbe;

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

@@ -1,5 +1,7 @@
-import { type Config, type ContradictionRecord, type FactDetail, type FactPage, type FloorProfile, type RecallResult, type RememberResult, type SourceCoverage, type TrustDiagnostic, type ValidityCoverage, type VectorMigrationOutcome, type VectorMigrationProgress, type VectorSpaceHealth, type VectorsDiagnostic, type VectorsFixReport } from '../../mem-contract/index.js';
+import { type Config, type ContradictionRecord, type FactDetail, type FactPage, type FloorProfile, type RecallResult, type RememberResult, type SourceCoverage, type TrustDiagnostic, type ValidityCoverage, type VectorMigrationOutcome, type VectorMigrationProgress, type VectorSpaceHealth, type VectorsDiagnostic, type VectorsFixStoreReport } from '../../mem-contract/index.js';
 import type { SemanticBackend, VectorStore } from '../../mem-retrieval/index.js';
+import { ENTITY_SWEEP_BATCH, type EntitySweepReport } from './entity_sweep.js';
+import { DEFAULT_VECTOR_MIGRATION_BATCH, type VectorRepairTarget } from './vector_repair.js';
 import type { Db } from '../db/conn.js';
 import { type LexicalProbe } from './lexical.js';
 import { type FloorLeg } from './floors.js';
@@ -15,35 +17,22 @@ export type { DetectedContradiction, RememberResult as AddResult } from '../../m
 /**
  * Facts one derived-state sweep pass may rebuild (`reindexEntities`'s default budget).
  *
- * Bounds MEMORY, not only mission: the pass selects `content` for every row it takes, so an
- * "unbounded" pass (the CLI used to ask for `Number.MAX_SAFE_INTEGER`) builds an array of every
- * stale fact's text before rebuilding the first one. Callers that want the corpus drained loop
- * until `deferred === 0` instead.
+ * Re-exported from the shared sweep (`store/entity_sweep.ts`), which owns the loop and therefore the
+ * default: the public name has to keep working for the CLI (`cli/src/index.ts` passes it explicitly)
+ * and the plugin's heartbeat, but a second literal here would be a second answer to "how big is one
+ * pass".
  */
-export declare const ENTITY_SWEEP_BATCH = 2000;
+export { ENTITY_SWEEP_BATCH };
 /**
  * Rows one background vector-space migration slice may drop + re-encode.
  *
- * Small on purpose: the point of batching is that a query arriving mid-migration waits for at most
- * one ONNX forward pass batch, not for a whole corpus. At ~30 ms per bge-base-zh encode a batch of 16
- * is well under a second of contested model time, and the event loop is yielded between batches
- * (`yieldToEventLoop`). The value is a default, not a promise — `migrateVectorsBatch(batchSize)` takes
- * whatever the caller needs.
+ * Re-exported from the shared repair flow (`store/vector_repair.ts`), which owns the loop and
+ * therefore the default: the public name has to keep working for callers that pass it explicitly,
+ * but a second literal here would be a second answer to "how big is one slice".
  */
-export declare const DEFAULT_VECTOR_MIGRATION_BATCH = 16;
-/** What one derived-state sweep pass did (see `MemoryStore.reindexEntities`). */
-export interface EntitySweepReport {
-    /**
-     * Facts this pass RE-EXTRACTED, i.e. its batch size when it filled it. Counts rows VISITED and
-     * re-stamped, not rows whose extraction output differs — the stamp is what makes the corpus
-     * current, so a row re-extracted to the same names still counts (and is not rebuilt again).
-     */
-    rebuilt: number;
-    /** Facts still written by older rules after this pass. */
-    deferred: number;
-    /** Another pass was already running, so this one did nothing (`deferred` is still current). */
-    skipped: boolean;
-}
+export { DEFAULT_VECTOR_MIGRATION_BATCH };
+/** What one derived-state sweep pass did — re-exported from the shared loop (`store/entity_sweep.ts`). */
+export type { EntitySweepReport };
 /** What one bounded conflict-drain pass did (see `MemoryStore.drainConflicts`). */
 export interface ConflictDrainReport {
     /** Pairs newly logged by this pass. */
@@ -177,8 +166,14 @@ export declare class MemoryStore {
      * and building MATCH expressions for the wrong one is silent zero recall (see `db/tokenizer.ts`).
      */
     private readonly ftsTokenizer;
-    /** In-flight guard for `reindexEntities` (see there: the periodic callers can overlap). */
-    private entitySweepInFlight;
+    /**
+     * 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 keeps
+     * the rule where the loop is (the periodic callers can overlap), without a mutable field that two
+     * stores would each have to remember to hold.
+     */
+    private readonly entitySweepGuard;
     /**
      * Where the next conflict drain resumes (see `checkContradictions`). A scheduling cursor, not
      * derived state: nothing is lost when it resets, and the queue itself is in the database.
@@ -202,13 +197,19 @@ export declare class MemoryStore {
      */
     vectorSpace(): string;
     /**
-     * Rebuild the in-memory vstore from persisted `facts.semantic_vector` BLOBs.
-     * Without this the semantic path is silently empty after every process restart
-     * (the DB is the authoritative vector store; the vstore is a derived read model).
+     * Rebuild the in-memory vstore from persisted `facts.semantic_vector` BLOBs, and say loudly what
+     * belongs to another vector space.
+     *
+     * Without this the semantic path is silently empty after every process restart (the DB is the
+     * authoritative vector store; the vstore is a derived read model). Only ACTIVE facts are indexed:
+     * archived facts are filtered out of every retrieval path anyway, so loading them would only grow
+     * the index forever — `archive()` evicts and `restore()` re-adds, keeping the invariant.
      *
-     * Only ACTIVE facts are indexed: archived facts are filtered out of every
-     * retrieval path anyway, so loading them would only grow the index forever.
-     * `archive()` evicts and `restore()` re-adds, keeping the invariant.
+     * The reload, the `{ stale, space_stale, legacy }` count and the warning are the SHARED open-time
+     * step (`store/vector_repair.ts`); this store's half is the row read. A dim-valid vector from
+     * another space is still RANKED (the reload cannot tell the difference), so a silent model swap
+     * would mix two spaces in one index — acting on it is the manual fix's job for the operator path
+     * and the bounded background migration's for the automatic one.
      */
     private reloadIndex;
     /**
@@ -244,6 +245,14 @@ export declare class MemoryStore {
      * stamped the marker anyway — a permanent, silent exemption).
      */
     private detectContradictions;
+    /**
+     * This store's half of the shared encode-and-persist flow (`store/vector_repair.ts`): the backend
+     * call, the live index and the single-row write. The write records the VECTOR SPACE, not just the
+     * backend name — a same-width model swap is otherwise indistinguishable from "already encoded"
+     * (DESIGN §20) — and `setSemanticVector` re-queues the fact for the conflict check.
+     */
+    private vectorWriteTarget;
+    private warnIndexFailure;
     /** Best-effort semantic indexing: encode the fact and add it to the vstore. */
     private maybeIndexSemantic;
     update(fact_id: number, content: string, category?: string, ttlDays?: number, opts?: FactWriteOptions): Promise<RememberResult>;
@@ -381,54 +390,60 @@ export declare class MemoryStore {
      */
     private classifyVectors;
     /**
-     * Repair the semantic read model, in ONE bounded slice or in full:
-     *  (a) reload persisted, dim-valid vectors missing from the live index
-     *      (restart / index loss — needs no model),
-     *  (b) drop persisted vectors whose dim no longer matches `semantic.dim` so a
-     *      re-encode can replace them (never `add()` a stale vector — the store
-     *      throws on dim mismatch),
-     *  (c) encode active facts that have no vector yet (needs the semantic backend),
-     *  (d) re-encode vectors written in ANOTHER vector space (a model swap, or the one-time
-     *      adoption of a store predating the space id).
+     * 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 and the drop-before-encode order — lives there once,
+     * for both stores.
+     */
+    vectorRepairTarget(): VectorRepairTarget;
+    /**
+     * {@link classifyVectors} reduced to what the repair flow steps on: the counts, the ids to drop
+     * (bounded by `limit`) and the decoded vectors that can go back into a lost live index.
+     */
+    private classifyRepairVectors;
+    /** Put usable persisted vectors missing from the live index back into it (no model needed). */
+    private reindexUsableVectors;
+    /**
+     * Unusable bytes (dim mismatch) and foreign-space vectors both have to go before a re-encode can
+     * pick them up, and for the same reason: `add()` would keep ranking them otherwise. Only the slice
+     * the flow is about to re-encode is passed in, so a process that dies mid-migration leaves at most
+     * one batch vector-less — those rows are exactly the `missing` rows the next run resumes on.
+     *
+     * `clearVectors` re-queues each fact for the conflict check (`conflict_checked = 0`): the vector
+     * the embedding leg was checked against is gone, so the check has to run again.
+     */
+    private dropRepairVectors;
+    /**
+     * Encode the ACTIVE facts that still have no vector in this space (needs the semantic backend).
      *
-     * `limit` is what makes the SAME logic usable as a background migration: at most that many rows are
-     * dropped and at most that many are re-encoded, so one call is a bounded unit of work the caller can
-     * yield between. `vectorsFix` passes no limit (the explicit operator action drains everything);
-     * `migrateVectorsBatch` passes the migration's batch size.
+     * Every row lands through `setSemanticVector`, which re-queues the fact for the conflict check —
+     * the same rule as {@link dropRepairVectors}: a fact whose vector the leg could not see when it
+     * ran has not been checked.
      */
-    private repairVectors;
+    private reencodeMissingVectors;
     /**
      * 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 `VectorsFixReport`).
+     * the preview also reports `would_warm` (see the contract's `VectorsFixStoreReport`).
      */
-    vectorsFix(dryRun?: boolean): Promise<VectorsFixReport>;
+    vectorsFix(dryRun?: boolean): Promise<VectorsFixStoreReport>;
     /**
      * ONE bounded slice of the vector-space migration: at most `batchSize` rows are dropped and
      * 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.
-     *
-     * Resumability is a property of the DATABASE, not of this process: every slice re-derives what is
-     * stale from the persisted width/space, so a restart simply continues where the last slice stopped.
      */
     migrateVectorsBatch(batchSize?: number): Promise<VectorMigrationProgress>;
     /**
      * Drive the bounded background migration until the store is current, the model is unavailable, or
-     * `shouldStop()` turns true (plugin unmount / process shutdown). A batch FAILURE never rejects: it is
-     * logged and reported as `remaining > 0`, which is what makes the next heartbeat a retry (the caller
-     * still owns the outer catch for a closed database, e.g. a shutdown racing the first read). Never
-     * blocks the event loop for longer than one batch.
-     *
-     * Honours `semantic.auto_migrate` (default on) — the switch exists so a host that must not spend CPU
-     * on background re-encoding can leave the loud warning and the manual entry as the only path.
+     * `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 callers (and its tests) already use.
      */
     migrateVectors(opts?: {
         batchSize?: number;
         shouldStop?: () => boolean;
         onProgress?: (progress: VectorMigrationOutcome) => void;
     }): Promise<VectorMigrationOutcome>;
-    /** Active rows the semantic leg still cannot use (old width, old space, or no vector at all). */
-    private migrationRemaining;
     /**
      * One lifecycle pass, owned by the store so the DB writes and the live-index
      * invariant (ACTIVE vectors only) are maintained in ONE place — the runtime no
@@ -466,14 +481,10 @@ export declare class MemoryStore {
      * loop until `deferred === 0` — `budget` bounds MEMORY as well as mission, since the pass reads
      * every selected row's `content` before rebuilding the first one.
      *
-     * The in-flight guard is here rather than at the callers because the callers CAN overlap: the
-     * plugin's heartbeat and `maintenance` are both periodic, and `staleEntityRows` is ORDERED, so
-     * two concurrent passes would select the same rows and re-tag them twice. Overlap is not
-     * corruption (each fact is stamped in its own transaction) — it is duplicated mission in a
-     * single-threaded process. A pass that finds one running reports `skipped` and does nothing.
-     *
-     * `budget` is clamped at 0: SQLite reads a negative LIMIT as "no limit" (`LIMIT -1`), so a
-     * caller asking for "-1 rows" would silently get the whole corpus — the opposite of bounded.
+     * The loop, the budget clamp, the in-flight guard and the `{rebuilt, deferred, skipped}` report all
+     * live in `store/entity_sweep.ts` now — this method is memory's adapter for it, so knowledge's
+     * entity leg and this one cannot drift apart again. What stays HERE is the domain half: the stale
+     * selection (`facts.staleEntityRows`, ACTIVE facts only) and the per-fact write below.
      */
     reindexEntities(budget?: number): Promise<EntitySweepReport>;
     /**
@@ -483,8 +494,6 @@ export declare class MemoryStore {
      * `ContradictionsDao.resolveForFact`).
      */
     private retireConflicts;
-    /** Drop vectors of archived/purged facts from the live index (batched). */
-    private evictVectors;
     /**
      * Entities that co-occur with `entity` across ACTIVE facts, ranked by occurrence
      * count. Archived (incl. superseded) facts are excluded — their entities are not
@@ -581,7 +590,10 @@ export declare class MemoryStore {
      * Semantic leg. `queryVector` short-circuits the encode when the caller already
      * encoded this exact query (the cross-store router does, for both stores at once);
      * `onVector` publishes the vector this leg actually used, so the relaxed retry pass can reuse it
-     * instead of re-encoding (performance review §7.7 / P8).
+     * instead of re-encoding (performance review §7.7 / P8). The flow is shared
+     * (`store/legs.ts#semanticLeg`); the only memory-specific piece is the filter — the vstore has no
+     * notion of status/category/source, so candidates go through the DB and archived/purged facts,
+     * other categories and other sources never leak into the leg.
      */
     private semanticPath;
     /**