@avantf/dsh-mem 0.4.2 → 0.6.1

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

@@ -0,0 +1,88 @@
+/**
+ * The two arms the P-02 regression net runs, over the derived cases from `derive.ts`.
+ *
+ *  - `stubRank` / `runDerivedCaseStub`: a DETERMINISTIC, model-free retriever that scores a fact by
+ *    how many of the query's literal fragments it contains. It exists to prove the FIXTURE, not the
+ *    product: a planted carrier that literally contains the bridge must outrank the gold in the base
+ *    arm, and removing it must put the gold back at rank 1. That is the "counterfactual self-check"
+ *    the collision sensitivity requirement asks for, and it needs no model to be meaningful.
+ *  - `runDerivedCaseReal`: the same cases driven through a real runtime (`remember` + `recall`), for
+ *    the nightly job. It is duck-typed so this module does not depend on the runtime.
+ *
+ * The two arms share ONE outcome shape, so a report can say which arm produced which numbers.
+ */
+import { type DerivedCase, type GuardKind } from './derive.js';
+export interface RankedFacts {
+    /** Fact indices, best first. */
+    ranked: number[];
+    /** The stub score of each ranked fact (parallel to `ranked`). */
+    scores: number[];
+}
+/**
+ * Deterministic lexical-overlap stub: score = number of the query's distinct fragments the fact
+ * contains literally. Raw count, deliberately NOT length-normalized — the pathology under test is
+ * "a long unrelated note that happens to contain the bridge out-scores the short gold", which a
+ * per-character normalization would erase.
+ */
+export declare function stubRank(query: string, facts: readonly string[], k?: number): RankedFacts;
+export interface DerivedQueryOutcome {
+    query: string;
+    guard: GuardKind;
+    ranked: number[];
+    scores: number[];
+    gold_rank: number | null;
+    carrier_rank: number | null;
+    must_include_ok: boolean;
+    must_exclude_ok: boolean;
+    /** The fixture's own recorded collision rate (fraction of non-gold facts sharing a fragment). */
+    collision_rate: number;
+}
+export interface CollisionCheckOutcome {
+    /** `true` when the planted carrier really does outrank the gold in the base arm. */
+    base_carrier_before_gold: boolean;
+    /** `true` when removing the carrier puts the gold first (the counterfactual arm). */
+    counterfactual_gold_top1: boolean;
+}
+export interface DerivedCaseOutcome {
+    id: string;
+    /** Arm label so a merged report cannot confuse stub numbers with real ones. */
+    arm: 'stub' | 'real';
+    queries: DerivedQueryOutcome[];
+    collision_self_check: CollisionCheckOutcome | null;
+}
+export declare function runDerivedCaseStub(c: DerivedCase): DerivedCaseOutcome;
+export interface DerivedSuiteOutcome {
+    arm: 'stub';
+    cases: DerivedCaseOutcome[];
+    all_collision_self_checks_pass: boolean;
+    /** A retriever that emits any query containing a time expression has broken the guard. */
+    any_time_word_query: boolean;
+    /** Every `irrelevant` negative-control query must come back empty. */
+    all_irrelevant_empty: boolean;
+}
+export declare function runDerivedSuiteStub(cases: readonly DerivedCase[]): DerivedSuiteOutcome;
+/** The slice of the runtime the real arm needs. Duck-typed on purpose (no runtime import). */
+export interface DerivedRuntimePort {
+    remember(req: {
+        action: 'add';
+        content: string;
+    }): Promise<{
+        fact_id: number;
+    }>;
+    recall(req: {
+        action: 'search';
+        query: string;
+        limit?: number;
+    }): Promise<{
+        hits: {
+            ref_id: number;
+        }[];
+    }>;
+}
+/** Seed a case's facts and return the fact ids in `setup_facts` order. */
+export declare function seedDerivedFacts(rt: DerivedRuntimePort, facts: readonly string[]): Promise<number[]>;
+/**
+ * Drive one derived case through a real runtime. The `k` of each query is honored with `limit`
+ * (the derived queries use k=3), and the returned order is the store's own.
+ */
+export declare function runDerivedCaseReal(rt: DerivedRuntimePort, c: DerivedCase): Promise<DerivedCaseOutcome>;

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

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

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

@@ -23,3 +23,27 @@ export interface AggregateMetrics {
     must_exclude_pass_rate: number;
 }
 export declare function aggregate(perQuery: PerQueryMetrics[]): AggregateMetrics;
+/** Discounted cumulative gain at k (binary relevance). */
+export declare function dcgAtK(actual: number[], expected: number[], k: number): number;
+/**
+ * nDCG@k (binary relevance).
+ *
+ * 0 when there is nothing relevant to find (and when the ideal ranking is empty), never NaN — the
+ * per-query value is averaged and a NaN would poison the whole aggregate.
+ */
+export declare function ndcgAtK(actual: number[], expected: number[], k: number): number;
+/** How many relevant results appear in the first `n` slots. */
+export declare function relevantInTop(actual: number[], expected: number[], n: number): number;
+/** The window "top-3 relevant count" is measured over. */
+export declare const TOP_N = 3;
+export interface RankingMetrics {
+    n_queries: number;
+    mean_ndcg_at_k: number;
+    /** Relevant results inside the top {@link TOP_N}, summed over queries. */
+    top3_relevant_total: number;
+    /** Mean relevant results inside the top {@link TOP_N}. */
+    mean_top3_relevant: number;
+    /** Fraction of queries with at least one relevant result in the top {@link TOP_N}. */
+    top3_hit_rate: number;
+}
+export declare function aggregateRanking(perQuery: PerQueryMetrics[]): RankingMetrics;

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

@@ -1,10 +1,17 @@
-import { type PerQueryMetrics, type AggregateMetrics } from './metrics.js';
+import { type PerQueryMetrics, type AggregateMetrics, type RankingMetrics } from './metrics.js';
 import type { EvalCase } from './loader.js';
 /** A retrieve function over the case's facts, returning indices in relevance order. */
 type RetrieveFn = (query: string, k: number, facts: string[]) => Promise<number[]>;
 interface EvalReport {
     perQuery: PerQueryMetrics[];
     summary: AggregateMetrics;
+    /**
+     * P-02 ranking-quality metrics. A SIBLING of `summary`, never a key inside it: `eval_zh.spec.ts`
+     * asserts `summary` with `toEqual` over exactly seven keys, so a new key there would turn a
+     * frozen-number regression into a key-set failure. `perQuery` is unchanged, so the bench
+     * harness's `(ids, scores)` fingerprint over it cannot move.
+     */
+    ranking: RankingMetrics;
 }
 export declare function evaluateCases(cases: EvalCase[], retrieve: RetrieveFn): Promise<EvalReport>;
 export {};

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

@@ -20,8 +20,9 @@ export * from './dispatch.js';
 export * from './runtime.js';
 export * from './store/memory.js';
 export * from './store/knowledge.js';
+export * from './store/vector_repair.js';
 export * from './store/hybrid.js';
 export * from './store/source_picker.js';
 export * from './store/lexical.js';
 export * from './store/floors.js';
-export { registerSemanticBackend, registerReranker, registerVectorStore, type Reranker, type SemanticBackend, type VectorStore, } from '../mem-retrieval/index.js';
+export { registerSemanticBackend, registerVectorStore, type SemanticBackend, type VectorStore, } from '../mem-retrieval/index.js';

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

@@ -40,8 +40,8 @@ export interface WarmOptions {
     deferTokenizerUntilIdle?: boolean;
 }
 /**
- * Fire-and-forget model bootstrap for DSH startup. Configures the semantic /
- * rerank model env (mirror + cache) and triggers the model download/load
+ * Fire-and-forget model bootstrap for DSH startup. Configures the semantic
+ * model env (mirror + cache) and triggers the model download/load
  * asynchronously, without blocking the plugin's `apply`. Returns the availability
  * of the semantic path once the download/load completes.
  *

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

@@ -1,4 +1,4 @@
-import type { AdminRequest, KbAddRequest, KbConflictReport, KbRequest, QueryRequest, RecallRequest, RecallResult, RememberRequest } from '../mem-contract/index.js';
+import type { AdminRequest, KbAddRequest, KbConflictReport, KbRequest, QueryRequest, RecallRequest, RecallResult, RememberRequest, VectorsFixReport } from '../mem-contract/index.js';
 import { type AvantfLogger, type StatsSummary } from '../mem-contract/index.js';
 import { type SemanticBackend } from '../mem-retrieval/index.js';
 import { type LoadedConfig } from './config/loader.js';
@@ -20,7 +20,7 @@ export interface RuntimeOptions {
     semantic?: SemanticBackend;
     /**
      * The family framework's managed roots, as the built-in defaults for `tools.dir` and
-     * `semantic.cache_dir` / `rerank.cache_dir` (see `LoadConfigOptions.managedRoots`).
+     * `semantic.cache_dir` (see `LoadConfigOptions.managedRoots`).
      *
      * The DSH plugin passes `<family home>/tools` and `<family home>/models` while
      * `@avantf/dsh-plugin-base` owns the fetching; the CLI and the MCP server pass nothing, because they
@@ -153,7 +153,7 @@ export type AdminDispatch = {
     }>): StoreResult<MemoryStore, 'vectorsDiagnose'>;
     (req: Extract<AdminRequest, {
         action: 'vectors_fix';
-    }>): StoreResult<MemoryStore, 'vectorsFix'>;
+    }>): Promise<VectorsFixReport>;
     (req: Extract<AdminRequest, {
         action: 'contradict_check';
     }>): StoreResult<MemoryStore, 'checkContradictions'>;

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

@@ -28,10 +28,25 @@ export declare function normalizeWrites(values: readonly string[]): string[];
 /**
  * Identity of the vector space a store currently writes into.
  *
- * A change of backend, model or width makes every stored vector stale, and the point of recording
- * the identity is that such a change is DETECTED instead of silently mixing two spaces in one index.
+ * A change of backend, model, width — or of anything else that decides which coordinates a vector
+ * lives in (pooling, normalization, the input window, the model revision behind an unchanged repo
+ * name) — makes every stored vector stale. The point of recording the identity is that such a
+ * change is DETECTED instead of silently mixing two spaces in one index. The backend declares its
+ * representation (`SemanticBackend.representation`); one that does not is fingerprinted as
+ * `rep=undeclared`, which is honest rather than a claim nobody verified.
  */
 export declare function vectorSpaceOf(semantic: SemanticBackend, model: string): string;
+/** The two contract counts plus the internal "predates the representation fingerprint" split. */
+export interface StaleVectorCounts {
+    stale: number;
+    space_stale: number;
+    /**
+     * Of {@link space_stale}, how many were written BEFORE the representation fingerprint (`v2/…`).
+     * The count is what makes the warning able to say "this is a one-time format upgrade" instead of
+     * blaming a model swap the operator never made.
+     */
+    legacy?: number;
+}
 /**
  * Drop ids from the vector index, in one batch when the backend supports it.
  *
@@ -59,10 +74,7 @@ export declare function evictVectors(vstore: VectorStore, ids: readonly number[]
  * @param counts how many persisted vectors are unusable in the current space, by kind
  * @param fix    the manual entry that re-encodes them, as the operator would type it
  */
-export declare function reportStaleVectors(kind: string, space: string, counts: {
-    stale: number;
-    space_stale: number;
-}, fix: string): void;
+export declare function reportStaleVectors(kind: string, space: string, counts: StaleVectorCounts, fix: string): void;
 /**
  * Hand the event loop back between two synchronous batches.
  *

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

@@ -0,0 +1,95 @@
+/**
+ * The entity leg's metric: ANCHORED JACCARD WITH A SATURATING UNION.
+ *
+ * WHY THE OLD METRIC FAILED SHORT QUERIES. The leg scored the plain Jaccard ratio
+ * `|Q ∩ F| / |Q ∪ F|`. Both stores are written by the SAME entity extractor, which keeps every
+ * noun-ish token, so a real memory fact carries ~31 entity names (measured on the live store:
+ * min 3 / median 31 / max 66; `scripts/ENTITY_TOKENIZER_VALUE.md`). A query extracts one or two.
+ * Even a PERFECT 1-entity match is then `1 / (1 + 31 - 1) ≈ 0.03`, so with `min_jaccard` at any
+ * useful value the leg is unreachable for a short query BY CONSTRUCTION — measured: 1-entity
+ * queries could clear 0.2 against 2 of 80 facts. Extracting MORE entities only grows the
+ * denominator (the tokenizer direction was measured and rejected), so the fix has to be the
+ * metric, not the extractor.
+ *
+ * THE METRIC. `A` is the query's ANCHOR entities (below). The score keeps the Jaccard form — so a
+ * fact that is "about" the query outranks one that merely contains it — but the fact's own width
+ * enters through a SATURATING term:
+ *
+ *     score(A, W, F) = |A ∩ F| / ( W + min(|F \ A|, ENTITY_UNION_CAP) )
+ *
+ * The query side is `W`, the query's FULL entity count, not `|A|`: the Jaccard denominator is the
+ * union, and the query's own width belongs in it whether or not each entity turned out to be
+ * discriminative (a question that names five things asks for more than one that names one). When
+ * every query entity is an anchor (the frozen eval set) and the fact is no wider than
+ * `W + ENTITY_UNION_CAP`, this IS the plain Jaccard ratio `|Q ∩ F| / |Q ∪ F|` — those facts keep
+ * their EXACT old score and ordering (verified bit-for-bit on all four eval arms). Past the cap the
+ * denominator stops growing, so a wide fact that genuinely mentions a query's rare entity is
+ * REACHABLE instead of being divided into oblivion. The cap is not a free parameter: the floor is
+ * 0.2 and a two-entity query sharing ONE entity must still clear it (`1 / (2 + C) >= 0.2 ⇒ C <= 3`),
+ * so `C = 3` is the largest fact penalty that keeps that shape.
+ *
+ * WHY ANCHORS (IDF FILTERING). Removing the width blow-up alone would let a corpus-wide word
+ * (`用户` / `插件` / `任务` …) admit EVERY fact that mentions it — "drag the whole store in". The
+ * extracted bags are dominated by such words, so the precision lever is rarity: an entity is an
+ * ANCHOR when its document frequency over the active corpus is at most {@link anchorCeiling}. Only
+ * anchors can produce candidates or contribute to the numerator; a query whose entities are ALL
+ * generic therefore yields no entity evidence and the other legs answer it. That is deliberate
+ * (silent beats noisy), and the FTS leg's 2-char substring fallback (§20.20⑦) serves the 2-char
+ * shape.
+ *
+ * WHAT `W` COUNTS, AND WHY IT IS NOT `|A|`. `W` is the query's FULL entity count — every entity the
+ * extractor returned, generic or absent included. A Jaccard denominator is the union of what the
+ * query asked for, and the old metric counted all of it; keeping `W` there is what makes a narrow
+ * fact's score IDENTICAL to the old ratio, so the frozen eval and every narrow real fact keep their
+ * exact numbers and ordering. Dropping the absent entities from `W` was measured and moved the live
+ * eval (`CI 用哪个 Python 版本` lost rank 1): a query that names things the corpus does not carry
+ * really is asking for more, and the floor is calibrated against that.
+ *
+ * THE CEILING SCALES WITH THE CORPUS, WITH A FLOOR. A fixed count would mean different things on a
+ * 3-fact eval case and a 300k-fact store, and a purely relative one would call every entity
+ * "generic" on a tiny corpus (`ceil(0.2 * 3) = 1` filters any name that appears twice — which is
+ * every name in a 3-fact relation case). {@link ANCHOR_MIN} forgives small corpora; the relative
+ * term is what bites on a real store. Both are calibrated, not guessed: DESIGN §20.19.
+ *
+ * @module store/entity_leg
+ */
+/** An entity is an anchor at or below `max(ANCHOR_MIN, ceil(ANCHOR_RATE × activeFacts))`. */
+export declare const ANCHOR_RATE = 0.2;
+/**
+ * Small-corpus forgiveness, and its bound.
+ *
+ * Without it, `ceil(0.2 × 3) = 1` would call every name appearing twice "generic" — which is every
+ * name in a 3-fact relation case — and the eval set would lose its entity leg entirely. This is
+ * measured, not guessed: at `2` the eval corpus calls `Python` (carried by all three facts of its
+ * case) generic, and `CI 用哪个 Python 版本` loses its answer's entity evidence to the FTS leg —
+ * the live arm regressed `must_exclude`, the degraded arm lost rank 1 on that query. `4` keeps a
+ * name a small corpus repeats; the relative term is what bites on a real store (a 3-fact case
+ * filters nothing, by design).
+ */
+export declare const ANCHOR_MIN = 4;
+/**
+ * How many entities a fact may carry beyond the query's anchors before the width penalty stops
+ * growing (see the module doc: derived from the 0.2 floor and the 2-anchor reachability
+ * requirement, `1 / (2 + C) >= 0.2`).
+ */
+export declare const ENTITY_UNION_CAP = 3;
+/** The document-frequency ceiling for a corpus of `corpus` active facts/chunks. */
+export declare function anchorCeiling(corpus: number): number;
+/**
+ * The query entities that may serve as evidence.
+ *
+ * `df` is the DOCUMENT FREQUENCY of each query entity over the active corpus (how many facts /
+ * chunks carry it). An entity is kept when it occurs at least once and at most
+ * {@link anchorCeiling} times; the returned order is the input order (the caller only needs the
+ * set, and a stable order keeps the SQL/scoring deterministic).
+ */
+export declare function selectAnchors(queryEntities: Iterable<string>, df: ReadonlyMap<string, number>, corpus: number): string[];
+/**
+ * The leg's raw score, in [0, 1] — see the module doc for the formula and the constants.
+ *
+ * `0` for an empty anchor set (no discriminative query entity) and for "shares none". `queryWidth`
+ * is the query's full entity count (`W`), which keeps the narrow-fact case identical to the old
+ * Jaccard ratio; the fact's width only matters up to {@link ENTITY_UNION_CAP} extra entities, so a
+ * wide bag cannot divide a short query into nothing while a narrow one still ranks above a wide one.
+ */
+export declare function anchoredOverlap(anchors: readonly string[], queryWidth: number, factEntities: ReadonlySet<string>): number;

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

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

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

@@ -5,9 +5,9 @@
  * MAXIMUM, so every leg's head is 1.0 by construction and the fused number is only comparable
  * WITHIN one query. A cutoff on the fused score would therefore mean a different thing per query
  * (and would move whenever a leg's head changed). The legs' raw numbers do have an absolute scale —
- * cosine for the semantic leg, the Jaccard ratio for the entity leg, "distinct query terms hit" for
- * FTS — so that is where the floors live. The side benefit is that flooring a leg's tail cannot
- * move its maximum, so the cap-invariance §20.17 relies on is untouched.
+ * cosine for the semantic leg, anchored Jaccard for the entity leg (`store/entity_leg.ts`),
+ * "distinct query terms hit" for FTS — so that is where the floors live. The side benefit is that
+ * flooring a leg's tail cannot move its maximum, so the cap-invariance §20.17 relies on is untouched.
  *
  * THREE FLOORS, ONE SHAPE. `min_semantic_similarity` / `min_fts_terms` / `min_jaccard`; each `0`
  * means "this leg is not gated", and a candidate EQUAL to its floor is KEPT (only strictly-lower
@@ -49,14 +49,25 @@
  * of its own is bounded instead: it costs one extra query, only when the strict answer was empty,
  * and it can still report "nothing relevant" for a genuinely unrelated question.
  *
- * FTS REACHABILITY. `min_fts_terms` counts distinct query terms a row hits, but a query can only
- * produce so many terms (`relevanceTerms`: latin words ≥5 chars + CJK 3-grams) — a 3-character CJK
- * query yields exactly ONE trigram, so a configured bar of 2 is unreachable and that leg is empty
- * for it by construction. The effective bar is therefore `min(configured, termCount)`, and
- * `termCount` is that of the text being GRADED — with 方案 A's augmentation the original and the
- * rewrite are different texts with different counts, so each resolves its own bar
- * (`store/hybrid.ts`). Resolving the rewrite from the original's count is the defect that let a
- * single incidental trigram pass a bar it could not reach (2026-10-04).
+ * FTS REACHABILITY, AND THE SHORT-QUERY FALLBACK. `min_fts_terms` counts distinct query terms a row
+ * hits, but a query can only produce so many terms — a 3-character CJK query yields exactly ONE
+ * trigram, so a configured bar of 2 is unreachable and that leg is empty for it by construction. The
+ * effective bar is therefore `min(configured, termCount)`, and `termCount` is that of the text being
+ * GRADED — with 方案 A's augmentation the original and the rewrite are different texts with
+ * different counts, so each resolves its own bar (`store/hybrid.ts`). Resolving the rewrite from the
+ * original's count is the defect that let a single incidental trigram pass a bar it could not reach
+ * (2026-10-04).
+ *
+ * That clamp still leaves the shape with NO term at all: a 2-char CJK query (`buildFtsQuery` returns
+ * `null` — the trigram index holds no term under three characters, measured on the live store). The
+ * term set is therefore {@link gradedTerms}: when the query yields no index-expressible term, the
+ * 2-char CJK runs themselves become the terms, and the legs search/grade them as SUBSTRINGS
+ * (`content LIKE '%…%'`, the finer predicate an FTS5 trigram table still exposes; see
+ * `store/lexical.ts`). The clamp stays the same rule and stays honest — one substring term is
+ * `min(configured, 1)`, and {@link applyTermFloor} re-derives it from the query it is grading, so
+ * the reported number is the applied number. The guard against the noise a 2-char term invites is
+ * the term itself: the row must CONTAIN the run contiguously (not merely share a trigram), and a
+ * multi-run query must contain `min(configured, runs)` of them.
  *
  * @module store/floors
  */
@@ -86,16 +97,20 @@ export type FloorLeg = 'semantic' | 'fts' | 'jaccard';
  *  - fts: NOT a constant — {@link looseTermFloor}, half the query's distinct terms with a floor of
  *    1. `1` here is the "no terms to scale by" baseline (the previously constant value); a query
  *    that cannot produce terms is not graded at all, and one that produces a single term (every
- *    3-char CJK query) is already graded against that one term by the reachability clamp.
- *  - jaccard **0.15** (positive — the previous `0` was the ungated hole this closes). Measured, not
- *    guessed, on two corpora: (a) the live store, 64 active facts, the common-entity questions a
- *    real user asks about this repo ("插件怎么安装" / "任务怎么拆分" / "知识库在哪里" …) put their
- *    TOP non-answering entity candidate at Jaccard 0.0909 and most at 0.02–0.07, so 0.15 removes that
- *    whole tail; (b) the gold-labelled 35-query eval set, where the LOWEST Jaccard any answering pair
- *    reached is 0.25 (「老王喜欢什么风格」) — a bottom line above 0.25 starts dropping gold pairs,
- *    while 0.15 filters none. The entity leg cannot fully separate the two classes on short queries
- *    (a one-entity query against a one-entity fact is 1.0 by construction, and non-gold pairs reach
- *    0.667), so this is deliberately a "no incidental small overlap" line, not a relevance classifier.
+ *    3-char CJK query, and every 2-char one through the substring fallback) is already graded
+ *    against that one term by the reachability clamp.
+ *  - jaccard **0.15** (positive — the previous `0` was the ungated hole this closes). The metric was
+ *    recalibrated on 2026-10-04 (`store/entity_leg.ts`): the leg still scores a Jaccard ratio, but
+ *    over the query's ANCHOR entities and with the fact's extra-entity term SATURATED at
+ *    `ENTITY_UNION_CAP`. 0.15 on that unit means "shares at least one discriminative entity" for any
+ *    query with up to six anchors (`1/6 = 0.167 > 0.15`), i.e. the bottom line that cannot be lowered
+ *    to "any incidental overlap" without admitting a length-dependent fraction. The old Jaccard
+ *    calibration, kept for the record: (a) on the live store the top non-answering candidate for
+ *    common-entity questions sat at 0.0909 and most at 0.02–0.07; (b) the lowest Jaccard any
+ *    answering pair on the gold 35-query set reached was 0.25. The entity leg cannot separate the
+ *    classes on short queries by itself, so this is deliberately a "no incidental small overlap"
+ *    line, not a relevance classifier — see `store/entity_leg.ts` for why the fact's own width was
+ *    saturated rather than used as the separator.
  */
 export declare const LOOSE_FLOORS: RetrievalFloors;
 /**
@@ -116,10 +131,10 @@ export declare function emptyFloorDrops(): RetrievalFloorDrops;
  * The FTS bar actually applied to a query carrying `termCount` distinct terms.
  *
  * A query cannot be graded against more terms than it has (see the module comment: a 3-char CJK
- * query has one trigram), so the configured bar is CLAMPED to the reachable maximum. `termCount`
- * `0`/omitted leaves the value alone — such a query is not graded at all by {@link applyTermFloor},
- * and changing the REPORTED value there would misdescribe what the caller is reading. `0` stays `0`
- * (the operator's off switch).
+ * query has one trigram, and a 2-char one has one substring term), so the configured bar is CLAMPED
+ * to the reachable maximum. `termCount` `0`/omitted leaves the value alone — such a query is not
+ * graded at all by {@link applyTermFloor}, and changing the REPORTED value there would misdescribe
+ * what the caller is reading. `0` stays `0` (the operator's off switch).
  *
  * This is the ONE place the clamp lives; `resolveFloors` (what the result reports / a run is handed)
  * and `applyTermFloor` (what the leg does) both call it, so the number a run reads is the number its
@@ -133,7 +148,7 @@ export interface FloorResolution {
     /** `loose` lowers each configured floor (see {@link LOOSE_FLOORS}); absent means `strict`. */
     profile?: FloorProfile;
     /**
-     * The distinct term count of the text being GRADED (`relevanceTerms(text).length`), for the FTS
+     * The distinct term count of the text being GRADED (`gradedTerms(text).length`), for the FTS
      * clamp. It must describe the query the legs will actually run on: under 方案 A's augmentation the
      * rewrite is a DIFFERENT text with its own term count, and resolving both runs from the original's
      * count is the defect that let one incidental trigram through (see `store/hybrid.ts`). Callers with
@@ -182,16 +197,21 @@ export declare function applyScoreFloor(scores: Map<number, number>, floor: numb
  *
  * Substring containment, case-insensitively: FTS5's trigram tokenizer matches a quoted phrase by
  * consecutive trigrams and is ASCII-case-insensitive, which is the same predicate as "the term
- * occurs in the text". `relevanceTerms` lowercases its latin words, so the comparison has to.
+ * occurs in the text" — and the 2-char fallback terms ARE substrings by construction
+ * (`store/lexical.ts`), so one predicate covers both. `relevanceTerms` lowercases its latin words,
+ * so the comparison has to.
  */
 export declare function countMatchedTerms(text: string, terms: readonly string[]): number;
 /**
  * Apply the per-row FTS floor to one FTS leg's scores.
  *
- * The terms come from `relevanceTerms(query)` (latin words ≥ 5 chars + every CJK 3-gram) — the same
- * tokenisation the conditional-hint probe uses, so "relevant enough" means one thing in this repo.
- * A query with NO such term is not graded at all: there is nothing to count, and dropping every row
- * on a technicality would turn a 3–4 char latin query (`buildFtsQuery` still emits it) into silence.
+ * The terms come from `gradedTerms(query)` — latin words ≥ 5 chars + every CJK 3-gram, and (only
+ * when the query produces no such term) the 2-char CJK runs as substrings. The indexed terms are
+ * the same tokenisation the conditional-hint probe uses, so "relevant enough" means one thing in
+ * this repo; the fallback exists because the hint path may stay silent while the LEG must not
+ * (`store/lexical.ts`). A query with NO such term is not graded at all: there is nothing to count,
+ * and dropping every row on a technicality would turn a 3–4 char latin query (`buildFtsQuery` still
+ * emits it) into silence.
  *
  * The bar itself is {@link effectiveTermFloor}: a query that can only produce one term (a 3-char CJK
  * query is one trigram) is measured against that one term, not against a configured 2 it could never