@avantf/dsh-mem 0.4.2 → 0.6.1

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

@@ -3,18 +3,16 @@
  *
  * `MemoryStore.search` and `KnowledgeStore.search` used to carry parallel copies of this flow
  * (~80 lines each: limit normalization → weights → over-fetch → leg cap → fuse → live filter →
- * rerank → slice → output budget → health event). The legs themselves are legitimately
- * store-specific — different tables, different filters (`category` vs `domain`/`source`), and only
- * memory has the HRR probe — but the ORCHESTRATION is one algorithm, and two copies of it drifted:
+ * slice → output budget → health event). The legs themselves are legitimately store-specific —
+ * different tables, different filters (`category` vs `domain`/`source`), and only memory has the
+ * HRR probe — but the ORCHESTRATION is one algorithm, and two copies of it drifted:
  *
  *   - the `NaN` limit guard existed only in memory, so a non-finite limit reached knowledge's SQL
  *     `LIMIT` and took the whole cross-store query down with it (`Promise.all` has no per-leg catch);
  *   - `retriever.over_fetch_factor` was read only by memory, while knowledge hardcoded `limit * 3`,
  *     so one config knob silently meant two different things;
  *   - `recordLegCapped()` was called only by memory, so a capped knowledge leg was unobservable —
- *     exactly the blindness DESIGN §20.17 says the counter exists to remove;
- *   - the reranker's used/fallback flags were a helper in memory and an inline expression in
- *     knowledge.
+ *     exactly the blindness DESIGN §20.17 says the counter exists to remove.
  *
  * Fixing those one at a time would leave the next drift a matter of when. The stores now supply
  * their legs and their hit mapping; everything that can drift lives here once.
@@ -26,7 +24,7 @@
  * @module store/hybrid
  */
 import { type Config, type FloorProfile, type RecallResult, type RetrievalFloorDrops, type RetrievalFloors } from '../../mem-contract/index.js';
-import { type BudgetInput, type Hit, type Reranker, type SemanticBackend } from '../../mem-retrieval/index.js';
+import { type BudgetInput, type Hit, type SemanticBackend } from '../../mem-retrieval/index.js';
 import { type FloorLeg } from './floors.js';
 /** The `limit` a caller gets when it passes nothing usable. */
 export declare const DEFAULT_SEARCH_LIMIT = 10;
@@ -63,8 +61,12 @@ export interface HybridLeg {
     capped?: boolean;
     /**
      * Which floor governs this leg, for {@link HybridResult.dropped_by_floor}'s per-leg breakdown.
-     * The HRR probe shares the Jaccard floor; naming it separately keeps a narrowed candidate set
-     * attributable without double-counting the Jaccard leg's own drops.
+     * The HRR probe shares the entity (`jaccard`) floor; naming it separately keeps a narrowed
+     * candidate set attributable without double-counting the entity leg's own drops.
+     *
+     * The `jaccard` KEY is historical: the entity leg's metric is now anchored Jaccard with a
+     * saturating union, whose unit (and the `min_jaccard` floor on it) is defined in
+     * `store/entity_leg.ts` — read that before re-calibrating the knob.
      */
     leg?: keyof RetrievalFloorDrops;
     /** Candidates this leg removed because they fell below its floor. */
@@ -113,7 +115,6 @@ export interface HybridDeps<H> {
     kind: 'memory' | 'knowledge';
     config: Config;
     semantic: SemanticBackend;
-    reranker: Reranker;
     /**
      * The legs to fuse, as promises (or values). Awaited concurrently; a rejection costs that leg
      * only. The async setup a store needs before it can build its legs — memory extracts the query's
@@ -121,7 +122,7 @@ export interface HybridDeps<H> {
      * body, before the array is returned.
      */
     legs(ctx: HybridContext): Promise<readonly (HybridLeg | Promise<HybridLeg>)[]>;
-    /** Text for the fused ids: the live filter, the reranker's input, and the hit bodies. */
+    /** Text for the fused ids: the live filter and the hit bodies. */
     texts(ids: number[]): Map<number, string>;
     /** Build the caller-facing hits from the ranked, live, already-sliced ids. */
     hits(ranked: readonly Hit[], texts: Map<number, string>): H[];
@@ -177,6 +178,12 @@ export interface HybridPlan {
      * `queries` counts questions instead of legs (DESIGN §20.5).
      */
     recordStats?: boolean;
+    /**
+     * P-01: attach per-leg evidence to the returned hits (`RecallHit.scores` / `final`). Default
+     * false, and that default is load-bearing: the evidence is explanation only, so a caller that did
+     * not ask must not pay for it in tokens (`fuse` skips building the arrays entirely).
+     */
+    includeScores?: boolean;
 }
 /** A hit after the output budget: `text` may have been shortened, and `truncated` says so. */
 export type Budgeted<T> = T & {
@@ -207,17 +214,6 @@ export interface HybridResult<H> {
  * rather than per store, because the health counter compares against whatever this returns.
  */
 export declare function legCapFor(config: Config, overFetch: number): number;
-/**
- * Whether the configured reranker is actually in use — the two flags a retrieval event carries.
- *
- * "Configured" is not "used": a reranker that is selected but unavailable falls back to the fused
- * order, and counting that as a rerank would make the counter lie in exactly the case it exists to
- * expose (the reference implementation leaves `rerank_fallback` unfeedable).
- */
-export declare function rerankState(reranker: Reranker): {
-    used: boolean;
-    fallback: boolean;
-};
 /**
  * Bound a ranked hit list to a token budget, marking what was shortened.
  *
@@ -233,9 +229,58 @@ export declare function applyOutputBudget<H extends BudgetInput>(config: Config,
 /**
  * Run one hybrid search.
  *
- * The order of the last three steps is load-bearing: rerank the over-fetched pool, THEN slice to
- * `limit`, THEN apply the output budget, and only then tell the store what was returned. Slicing
- * before the rerank would rank an arbitrary subset; budgeting before the slice would spend the
- * budget on hits that are about to be dropped.
+ * The order of the last steps is load-bearing: slice the fused (over-fetched) pool to `limit`,
+ * THEN apply the output budget, and only then tell the store what was returned. Budgeting before
+ * 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 { Reranker, SemanticBackend, VectorStore } from '../../mem-retrieval/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;
@@ -43,6 +44,8 @@ export interface KnowledgeSearchOptions {
      * store-level "last result" field would race two concurrent queries.
      */
     onResult?: (result: HybridResult<RecallHit>) => void;
+    /** P-01: attach per-leg evidence (`scores` / `final`) to every hit. Default false. */
+    includeScores?: boolean;
 }
 /**
  * One identity a write will land on: the title it will use, the resolved local path it would read
@@ -87,7 +90,6 @@ export type IngestMode = 'add' | 'replace';
 export declare class KnowledgeStore {
     private readonly semantic;
     private readonly vstore;
-    private readonly reranker;
     /** The store config file `addDomain` writes the allowlist back to (`knowledgeConfigPath(home)`). */
     private readonly domainConfigPath;
     private readonly logger?;
@@ -109,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
@@ -127,17 +138,22 @@ export declare class KnowledgeStore {
     private readonly allowedDomains;
     /** Whether the config allowlist is active (non-empty); `false` = `domains: []` = no restriction. */
     private readonly domainsRestricted;
-    constructor(dbPath: string, config: Config, kbConfig: KnowledgeConfig, semantic: SemanticBackend, vstore: VectorStore, reranker: Reranker, 
+    constructor(dbPath: string, config: Config, kbConfig: KnowledgeConfig, semantic: SemanticBackend, vstore: VectorStore, 
     /** 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: `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`.
+     * 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.
+     *
+     * 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;
     /**
@@ -242,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();
     /**
@@ -287,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
@@ -298,15 +313,79 @@ 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;
     /**
-     * Identity of the vector space this store currently writes into (DESIGN §20): a change of
-     * backend, model or width makes every stored chunk vector stale, and the whole point of
-     * recording it is that such a change is DETECTED instead of silently mixing two spaces.
+     * Identity of the vector space this store currently writes into (DESIGN §20): the representation
+     * fingerprint — backend, model, width AND the backend's declared pooling/normalization/input
+     * window/model revision — so any representation change makes stored chunk vectors stale instead
+     * 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.
      */
-    private vectorSpace;
+    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.
      *
@@ -317,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
@@ -434,7 +533,7 @@ export declare class KnowledgeStore {
      * and the chunk→hit mapping.
      *
      * The limit normalization, the over-fetch factor, the leg cap, the capped-leg counter, the
-     * degraded weights, the rerank and the output budget all live there now. They used to be copied
+     * degraded weights and the output budget all live there now. They used to be copied
      * here, and every fix landed on the memory side only — a `NaN` limit reached this store's SQL and
      * took the whole cross-store query down with it, `retriever.over_fetch_factor` meant something
      * different per store, and a capped knowledge leg was invisible to the health counters.
@@ -457,13 +556,27 @@ 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`.
      */
     lexicalProbe(text: string, stopAt?: number): LexicalProbe;
     private ftsPath;
-    /** Entity overlap against entities extracted AT INGEST time (chunk_entities) — no corpus scan. */
+    /**
+     * Entity overlap against entities extracted AT INGEST time (chunk_entities) — no corpus scan.
+     *
+     * Same metric as the memory store's sibling (`store/entity_leg.ts` carries the measurement and
+     * the reasoning): anchored Jaccard with a saturating union over the query's rare entities, so a
+     * wide chunk cannot dilute the denominator and a corpus-wide word cannot drag the whole knowledge
+     * base in.
+     */
     private jaccardPath;
 }
 export interface Chunk {

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

@@ -25,7 +25,22 @@
  * `matched >= 2`, with the margin between 2 and 1 rather than a tuned threshold inside a
  * continuum. A single-word query (`cgroup`) scores 1 and stays silent on purpose: one term is not
  * evidence.
+ *
+ * THE SHORT-CJK FALLBACK (and why the hint probe does NOT use it). The trigram index has no term
+ * shorter than three characters — measured on the live store: `fts5vocab` over `facts_fts` holds
+ * 27906 distinct terms and EVERY one is 3 characters (and a 2-char `MATCH` returns nothing, even as
+ * a prefix query). So a 2-char CJK query produces no FTS term at all and that leg is empty by
+ * construction. The FTS LEG therefore falls back to the one finer predicate the FTS5 trigram TABLE
+ * does expose: `content LIKE '%…%'`, which matches a 2-char run by scanning (no index can serve a
+ * 2-char pattern). See {@link substringTerms} / {@link gradedTerms}.
+ *
+ * The conditional-hint probe deliberately keeps the index-expressible terms only: it is
+ * SYNCHRONOUS and runs on every step's prompt assembly, so it must stay a bounded number of
+ * `LIMIT 1` index lookups — an O(corpus) scan per 2-char term would put a full scan on the prompt
+ * 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;
@@ -46,6 +61,36 @@ export type RelevanceHit = boolean;
  * caller runs one `LIMIT 1` MATCH per term and counts the hits.
  */
 export declare function relevanceTerms(text: string, cap?: number): string[];
+/**
+ * The terms the FTS leg falls back to when the trigram index can express NONE of the query.
+ *
+ * A 2-char CJK run IS the finer granularity the FTS5 trigram TABLE can still answer — not as an
+ * indexed token (the vocabulary holds 3-character terms only, measured; a 2-char `MATCH`, quoted or
+ * prefixed, returns zero rows) but as the substring predicate FTS5 exposes on a trigram table
+ * (`content LIKE '%…%'`, which falls back to a scan for patterns under three characters). One-char
+ * runs are deliberately NOT included: a single character is not evidence (the same reason
+ * {@link looksRelevant} needs two terms), and it would make the leg match a large share of any
+ * corpus. Latin runs are not included either — `buildFtsQuery` already admits latin tokens from
+ * three characters, and the module's own floor (5, `MIN_LATIN`) is a separate, measured decision.
+ *
+ * PRECISION GUARD. The fallback is graded by the SAME per-row floor as the indexed path and by the
+ * reachability clamp: for a single 2-char term the effective bar is 1, and the term is a substring,
+ * so "the row contains the query's characters CONTIGUOUSLY" is what admits it — not "shares one
+ * incidental trigram". A two-run query ('李娜 张伟') produces two substring terms and is judged
+ * against `min(configured, 2)`, i.e. both runs must occur in the row.
+ */
+export declare function substringTerms(text: string, cap?: number): string[];
+/**
+ * The term set the FTS leg is SEARCHED and GRADED with — the one definition of "the query's terms"
+ * for that leg (`store/floors.ts` grades with it, `store/hybrid.ts` resolves the reachability clamp
+ * from it, and the stores build their MATCH / substring probe from it).
+ *
+ * The fallback is whole-query, not per run: any text that yields even one index-expressible term is
+ * returned UNCHANGED from {@link relevanceTerms}. That is what keeps every long query bit-identical
+ * (a mixed text like `缓存失效 李娜` keeps only its trigrams, exactly as before) and confines the
+ * new behaviour to the shape that had NO leg at all.
+ */
+export declare function gradedTerms(text: string, cap?: number): string[];
 /**
  * The gate itself: is this store worth telling the model about?
  *
@@ -65,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;