@avantf/dsh-mem 0.6.0 → 0.6.1

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;
     /**