@avantf/dsh-mem 0.4.2 → 0.6.0

package/lib/engine/mem/db/vectors.d.ts

@@ -3,18 +3,44 @@ import type { VectorStore } from '../../mem-retrieval/index.js';
 export declare function float32ToBytes(vec: Float32Array): Buffer;
 export declare function bytesToFloat32(buf: Uint8Array | null | undefined): Float32Array | null;
 /**
- * Identity of a VECTOR SPACE: which backend, which model, how wide.
+ * Identity of a VECTOR SPACE — the REPRESENTATION FINGERPRINT.
  *
  * Persisted beside every vector (`facts.embedding_model`, `doc_chunks.embedding_model`) so
- * "these vectors came from a different model" is detectable. It used to record only the
- * backend name, which made a same-width model swap (bge-small-zh → bge-m3, both 512d)
- * indistinguishable from "already encoded": the two spaces then shared one index and were
- * ranked against each other.
+ * "these vectors came from a different representation" is detectable. It used to record only the
+ * backend name, then `backend/model/dim`; both were blind to the rest of what decides which
+ * coordinates a vector lives in — pooling, normalization, the truncation window, and the weights
+ * behind an unchanged repo name. The space id now embeds:
+ *
+ *  - {@link VECTOR_SPACE_FORMAT}, a format version. Bumping it is a deliberate ONE-TIME full
+ *    re-encode of every existing library (the old ids simply are not equal to any new id), which
+ *    is exactly why the stale-vector warning has to explain that case instead of calling it a
+ *    model swap (see `reportStaleVectors`);
+ *  - the backend, model and width, as before;
+ *  - the backend's declared representation (`representationKey`): pooling / normalize /
+ *    max_input_tokens / model revision. The revision is omitted when the family sidecar could not
+ *    be read — a documented degradation, never a crash.
  *
  * The vector STORE is deliberately not part of the identity: numpy vs hnswlib indexes the
  * same vectors, so switching it must not trigger re-encoding (that is `reloadIndex`).
  */
-export declare function vectorSpaceId(backend: string, model: string, dim: number): string;
+export declare const VECTOR_SPACE_FORMAT = 2;
+/** `v<format>/` — the prefix every current-format space id starts with (and old ids do not). */
+export declare const VECTOR_SPACE_FORMAT_PREFIX: string;
+/**
+ * @param backend - the `SemanticBackend` name.
+ * @param model - the configured model id.
+ * @param dim - the configured width.
+ * @param representation - the normalized representation key (`representationKey`). Omitted by
+ *   callers with no backend in hand (benchmarks, the pure id tests); such an id is still
+ *   format-prefixed, so it can never equal a pre-fingerprint id.
+ */
+export declare function vectorSpaceId(backend: string, model: string, dim: number, representation?: string): string;
+/**
+ * `true` when a recorded space id predates the representation fingerprint (`v2/…`), or comes from a
+ * format this build does not know. The distinction is what lets the warning explain a one-time
+ * format upgrade separately from "another model's vectors are in this index".
+ */
+export declare function isPreFingerprintSpace(recorded: string | null | undefined): boolean;
 /**
  * Rebuild a live vstore from persisted vector BLOBs — the restart-recovery path
  * shared by both stores (the two copies had already drifted: memory warned on

package/lib/engine/mem/entities/extract.d.ts

@@ -6,7 +6,7 @@
  * Note: nodejieba's `tag()` returns `{ word, tag }` objects, and its POS flag set
  * differs from Python jieba (e.g. proper nouns → `nr`, 名动词 → `vn`).
  */
-interface ExtractedEntity {
+export interface ExtractedEntity {
     name: string;
     type: string;
     method: string;

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

@@ -0,0 +1,120 @@
+/**
+ * Deterministic query-derivation engine for the P-02 regression net.
+ *
+ * The shipped 41-query fixture is frozen to the last bit, so it cannot grow to cover a new
+ * pathology without re-freezing seven numbers. This engine derives NEW queries from a corpus
+ * instead, with no model and no clock: the same facts + seed always produce byte-identical cases.
+ *
+ * What it derives, per gold fact:
+ *  - one query assembled from the gold's SHARED literal fragments plus a bridge fragment the gold
+ *    does NOT contain (so the query is never answered by simply echoing the gold's own text);
+ *  - one planted, unrelated, LONG carrier fact that literally contains the bridge (requirement ②);
+ *  - the collision rate of the query against the non-gold facts;
+ *  - the counterfactual arm (requirement ③): removing the carrier must put the gold back at rank 1.
+ *
+ * The two guards:
+ *  - `no_time_word`: an emitted query may not contain a time expression (a temporal query belongs to
+ *    a different leg, and would confound "did the ranking change?" with "did the clock move").
+ *    Offending candidates are DROPPED and counted, not silently kept.
+ *  - `irrelevant`: a negative-control query that shares no fragment with any fact; a retriever that
+ *    answers it is returning something for nothing.
+ *
+ * Requirement ① (a corpus with the real store's length distribution) is served by
+ * {@link synthesizeCorpus}, whose output mirrors the measured profile in
+ * `docs/bench/BASELINE_REPORT.md` §0.1 (9 / 243 / 313 / 409 / 882 characters); {@link analyzeCorpus}
+ * reports how close a corpus actually is so the caller can assert it rather than trust it.
+ */
+export interface LengthProfile {
+    min: number;
+    p25: number;
+    median: number;
+    p75: number;
+    max: number;
+}
+/**
+ * The measured ACTIVE-corpus shape on 2026-10-06 (`docs/bench/BASELINE_REPORT.md` §0.1:
+ * 86 active, min/p25/median/p75/max = 9/243/313/409/882 characters). Frozen here so a fixture can
+ * be checked against the real store's shape instead of against a guess.
+ */
+export declare const REAL_LENGTH_PROFILE: LengthProfile;
+export interface CorpusAnalysis {
+    n: number;
+    length_profile: LengthProfile;
+    /** Fraction of facts whose length falls inside the real p25..p75 band. */
+    in_band_rate: number;
+}
+export declare function lengthProfileOf(lengths: readonly number[]): LengthProfile;
+export declare function analyzeCorpus(facts: readonly string[]): CorpusAnalysis;
+/**
+ * The literal unit of collision: latin/digit words of length ≥ 2, and CJK bigrams.
+ *
+ * Bigrams are the CJK unit on purpose — it is what a trigram FTS index cannot fully guard, and it
+ * is exactly the granularity of the 2026-10-04 self-referential ranking incident (`用户是`, a
+ * fragment an unrelated note happened to contain).
+ */
+export declare function fragmentsOf(text: string): string[];
+export declare function timeWordsIn(text: string): string[];
+export type GuardKind = 'none' | 'no_time_word' | 'irrelevant';
+export interface DerivedQuery {
+    query: string;
+    k: number;
+    /** Index of the gold fact in `setup_facts`, or null for a negative-control query. */
+    gold_index: number | null;
+    must_include: number[];
+    must_exclude: number[];
+    guard: GuardKind;
+    /** The literal fragments the query is built from. */
+    fragments: string[];
+    /** Fraction of the NON-gold facts that literally share at least one query fragment. */
+    collision_rate: number;
+    /** Index of the planted fragment carrier in `setup_facts`, when this query has one. */
+    carrier_index: number | null;
+}
+export interface CollisionSelfCheck {
+    query_index: number;
+    carrier_index: number;
+    gold_index: number;
+    /** The fixture is only meaningful if the carrier actually outranks the gold in the base arm. */
+    base_carrier_before_gold: boolean;
+    /** …and if removing it puts the gold first (the counterfactual arm). */
+    counterfactual_gold_top1: boolean;
+}
+export interface DerivedCase {
+    id: string;
+    setup_facts: string[];
+    queries: DerivedQuery[];
+    analysis: CorpusAnalysis;
+    collision: CollisionSelfCheck | null;
+    guards: {
+        /** Candidates dropped because they contained a time expression (cumulative across the suite). */
+        no_time_word_dropped: number;
+        /** Negative-control queries emitted. */
+        irrelevant_queries: number;
+    };
+}
+export interface DeriveOptions {
+    seed?: number;
+    /** Maximum number of gold facts to derive a case from. */
+    maxGolds?: number;
+    /** Shared fragments folded into one query. */
+    fragmentsPerQuery?: number;
+    /** Target character length of a planted carrier (default: the real store's p75). */
+    carrierLength?: number;
+}
+/**
+ * Derive one case per shared-fragment gold fact (deterministic order, capped by `maxGolds`).
+ *
+ * The bridge fragment is a NONCE because the engine may not call a model: a real paraphrase's bridge
+ * (`我是谁？` → `用户是谁`, introducing `用户是`) cannot be produced without one. The nonce plays the
+ * same mechanical role — a literal the gold does not contain and an unrelated fact does — and the
+ * point of the fixture is the collision arithmetic, which is identical.
+ */
+export declare function deriveCases(facts: readonly string[], opts?: DeriveOptions): DerivedCase[];
+/**
+ * A deterministic corpus whose length distribution mirrors the real store's (requirement ①).
+ *
+ * `n` short-to-long facts are generated by padding a short seed sentence with the same unrelated
+ * filler the carriers use; the caller is expected to assert the result with {@link analyzeCorpus}
+ * rather than trust the generator.
+ */
+export declare function synthesizeCorpus(n: number, seed?: number): string[];

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

@@ -24,4 +24,4 @@ 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

@@ -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

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