@avantf/dsh-mem 0.4.1 → 0.6.0

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

@@ -59,3 +59,26 @@ export declare const MAX_FTS_PHRASES = 64;
  * once when the tokenizer fallback landed).
  */
 export declare function buildFtsQuery(query: string, tokenizer?: FtsTokenizer): string | null;
+/**
+ * The `LIKE` predicate that matches `column` against every term as a contiguous SUBSTRING.
+ *
+ * This is the SHORT-QUERY FALLBACK's search primitive: the trigram index holds no term under three
+ * characters (measured on the live store: `fts5vocab` over `facts_fts` = 27906 terms, all length 3),
+ * and a 2-char `MATCH` returns zero rows — quoted or prefixed. An FTS5 trigram table does still
+ * answer a substring `LIKE`, but only by SCANNING when the pattern is shorter than three characters
+ * (SQLite documents the index as usable from three), so callers must bound the result themselves.
+ * See `store/lexical.ts` for the precision guard and why only 2-char CJK runs reach here.
+ *
+ * `ESCAPE` is not decoration: the terms are the caller's text, so a `%` or `_` in one would silently
+ * turn a literal query into a wildcard. The fragment is built once and shared by BOTH stores' DAOs,
+ * the way {@link buildFtsQuery} is — the two copies of that rule had already drifted once.
+ *
+ * @returns `any` / `count` (SQL expressions over the SAME bind order) and the patterns. `count` is
+ *   the number of terms the row contains, i.e. the fallback leg's relevance score; `any` is its
+ *   `WHERE` clause. Empty terms are dropped, so a caller never gets a `%%` that matches everything.
+ */
+export declare function likeSubstring(column: string, terms: readonly string[]): {
+    any: string;
+    count: string;
+    params: string[];
+};

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
@@ -23,13 +49,19 @@ export declare function vectorSpaceId(backend: string, model: string, dim: numbe
  * The rows come from the owning store's DAO (DESIGN §19): this helper decodes and
  * filters them, it never runs SQL itself.
  *
+ * A row whose width does not fit the store is skipped (never `add()`ed — the store
+ * would throw). The OWNING store reports that condition itself, as one actionable
+ * line with the count, the reason and the manual re-encode entry (`reportStaleVectors`),
+ * so this helper stays quiet: two warnings for one condition read as two problems.
+ *
  * @param rows - `id` (fact/chunk id) + `vec` (BLOB), as read back from the store.
- * @param label - store name used in the dim-mismatch warning.
+ * @param _label - store name; unused here (the owning store owns the warning), kept so call sites read
+ *                 as "which store is reloading".
  */
 export declare function reloadVectorIndex(vstore: VectorStore, rows: readonly {
     id: number;
     vec: Uint8Array | null;
-}[], label: string): {
+}[], _label: string): {
     loaded: number;
     skipped: number;
 };

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

@@ -4,7 +4,7 @@
  * Small on purpose: `MemoryStore` and `KnowledgeStore` are separate stores over separate databases
  * and should stay that way (AGENTS.md). What they must NOT have is two copies of the same
  * three-line helper, because a fix then lands in one of them — which is exactly what happened to the
- * retrieval orchestration (see `store/hybrid.ts`) and to the foreign-vector-space warning below: the
+ * retrieval orchestration (see `store/hybrid.ts`) and to the stale-vector warning below: the
  * memory store checked whether its persisted vectors came from the CURRENT vector space and told the
  * operator how to fix it, while the knowledge store checked only the width, so a model swap left two
  * spaces silently mixed in one index until someone happened to run `kb_reindex`.
@@ -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.
  *
@@ -40,19 +55,26 @@ export declare function vectorSpaceOf(semantic: SemanticBackend, model: string):
  */
 export declare function evictVectors(vstore: VectorStore, ids: readonly number[]): void;
 /**
- * Tell the operator that persisted vectors came from ANOTHER vector space.
+ * Tell the operator that persisted vectors came from ANOTHER vector space — loudly, and with the
+ * manual remedy.
  *
- * A dim-valid vector from a different space is still RANKED — the reload cannot tell the difference
- * — so a silent model swap would mix two spaces in one index and degrade every semantic query
- * without an error anywhere. Said once per process; acting on it is the operator's choice because
- * re-encoding is a real cost (and they should see the count first).
+ * Changing the embedding space (model, width, pooling, normalization) is a DATA MIGRATION: the
+ * persisted bytes stay valid-looking but are no longer comparable with the current query vector, so
+ * the semantic leg must not serve them. Measured on the real library after the 512→768 default-model
+ * swap: 78 of 80 ACTIVE facts fell out of the semantic leg and retrieval silently degraded to
+ * lexical+entity (every probe query answered with the same unrelated short fact), with no error
+ * anywhere. The count, the reason and the ONE manual entry have to be visible at start.
+ *
+ * Both halves are reported in one message because they are one condition seen two ways: a changed
+ * WIDTH (`stale`, whose bytes cannot even be decoded into the current store) and a changed SPACE at
+ * the same width (`space_stale`, whose bytes decode but rank in another model's coordinates).
  *
  * @param kind   store label for the message (`memory` / `knowledge`)
  * @param space  the vector space the store writes into now
- * @param foreign how many persisted vectors were written in a different one
- * @param fix    the action that re-encodes them, as the operator would type it
+ * @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 reportForeignVectors(kind: string, space: string, foreign: 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;