@avantf/dsh-mem 0.4.2 → 0.6.1

package/lib/engine/mem/db/dao/facts.d.ts

@@ -7,7 +7,8 @@
  */
 import type { Db } from '../port.js';
 /**
- * Every `facts` column EXCEPT the two BLOBs (`hrr_vector` ~8 KB, `semantic_vector` ~2 KB per row).
+ * Every `facts` column EXCEPT the two BLOBs (`hrr_vector` ~8 KB, `semantic_vector` ~2 KB per row)
+ * and the two DEPRECATED provenance columns (`mirror_source` / `mirror_target`, see below).
  *
  * Multi-row reads that only need scalars used to be `SELECT *`, so a page of the admin list and
  * every recall's trust settlement dragged the whole vector corpus through the driver — tens of
@@ -17,10 +18,15 @@ import type { Db } from '../port.js';
  * `getById` deliberately still selects everything: `restore` re-indexes the persisted vector it
  * reads off that one row.
  *
- * `test/db_lifecycle.spec.ts` asserts this list against `PRAGMA table_info(facts)`, so a new column
- * fails a test instead of silently vanishing from these two reads.
+ * `mirror_source` was written as the constant `'user'` at the single INSERT below and
+ * `mirror_target` never had a writer; neither had a reader left once the model-facing views
+ * dropped them (零迁移：the COLUMNS stay in `db/schema.ts` for a later migration to clean up,
+ * only this projection and the INSERT stop touching them).
+ *
+ * `test/db_lifecycle.spec.ts` asserts this list against `PRAGMA table_info(facts)` MINUS those
+ * two deprecations, so a new column fails a test instead of silently vanishing from these reads.
  */
-export declare const FACT_COLUMNS_NO_BLOB = "fact_id, content, category, tags, trust_score, settle_clock,\n    pinned, pinned_at, bonus_count, bonus_window_at, last_reinforced_at, archived_clock,\n    retrieval_count, helpful_count, last_retrieved_at, embedding_model, vector_store, status,\n    supersedes_id, entities_version, conflict_checked, archived_at, archive_reason, ttl_days,\n    mirror_source, mirror_target, created_at, updated_at";
+export declare const FACT_COLUMNS_NO_BLOB = "fact_id, content, category, tags, trust_score, settle_clock,\n    pinned, pinned_at, bonus_count, bonus_window_at, last_reinforced_at, archived_clock,\n    retrieval_count, helpful_count, last_retrieved_at, embedding_model, vector_store, status,\n    supersedes_id, entities_version, conflict_checked, archived_at, archive_reason, ttl_days,\n    valid_from, valid_to, assert_count, created_at, updated_at";
 /**
  * The FTS leg's exact SQL, exported so the plan guard (`test/fts_plan.spec.ts`) and the bench
  * control group EXPLAIN the production text itself instead of a copy that can silently drift.
@@ -53,6 +59,21 @@ export declare const FACT_COLUMNS_NO_BLOB = "fact_id, content, category, tags, t
  * `INDEXED BY`, which pins the plan against `PRAGMA optimize` flipping it back.
  */
 export declare const FTS_SEARCH_SQL = "SELECT f.rowid AS id, bm25(facts_fts) AS rank FROM facts_fts f\n         JOIN facts fa NOT INDEXED ON fa.fact_id = f.rowid\n         WHERE facts_fts MATCH ? AND fa.status = 'active' AND (? IS NULL OR fa.category = ?)\n         ORDER BY rank ASC\n         LIMIT ?";
+/**
+ * {@link FTS_SEARCH_SQL} with the P-08 source predicate, as a SEPARATE statement rather than one
+ * more `(? IS NULL OR …)` branch in the shared text.
+ *
+ * The unfiltered statement's query plan is guarded by `test/fts_plan.spec.ts` (the external-content
+ * MATCH must not become the inner loop on a fresh, un-analyzed database), and the guard EXPLAINs
+ * `FTS_SEARCH_SQL` itself. Keeping the two texts apart means the default path's plan is provably
+ * unchanged, and the filtered path is a NEW statement with its own comment instead of a silent
+ * modification of the guarded one.
+ *
+ * `EXISTS`, never a JOIN on `fact_sources`: a fact with several sources would fan out into several
+ * rows, and this leg is `ORDER BY bm25 … LIMIT cap` — the duplicates would eat cap slots and shrink
+ * recall behind the caller's back.
+ */
+export declare const FTS_SEARCH_SQL_FILTERED = "SELECT f.rowid AS id, bm25(facts_fts) AS rank FROM facts_fts f\n         JOIN facts fa NOT INDEXED ON fa.fact_id = f.rowid\n         WHERE facts_fts MATCH ? AND fa.status = 'active' AND (? IS NULL OR fa.category = ?)\n           AND (? IS NULL OR EXISTS (\n                 SELECT 1 FROM fact_sources fs WHERE fs.fact_id = fa.fact_id AND fs.ref = ?\n               ))\n         ORDER BY rank ASC\n         LIMIT ?";
 export declare class FactsDao {
     private readonly db;
     constructor(db: Db);
@@ -89,10 +110,12 @@ export declare class FactsDao {
     rowsByIds(ids: readonly number[]): Record<string, unknown>[];
     /** `fact_id → content` for a hit set (never N+1). */
     textsByIds(ids: readonly number[]): Map<number, string>;
-    /** `fact_id → created_at/updated_at` for a hit set (the recall hit's two timestamps). */
+    /** `fact_id → created_at/updated_at/validity` for a hit set (the recall hit's timestamps). */
     timesByIds(ids: readonly number[]): Map<number, {
         created_at: string;
         updated_at: string | null;
+        valid_from: string | null;
+        valid_to: string | null;
     }>;
     /** Active rows that carry a persisted vector (index classification). */
     activeVectorRows(): {
@@ -149,10 +172,75 @@ export declare class FactsDao {
         pinnedAt: string | null;
         windowAt: string;
         createdAt: string;
+        /**
+         * P-13: the caller's event time / known end, written straight onto the new row. `null` means
+         * "unknown" and is what an omitted argument leaves (the column has no default on purpose).
+         * `assert_count` is deliberately NOT named: the column default (1) is the semantics — "this
+         * content has been asserted once" — and naming it here would be a second place to keep in step.
+         */
+        validFrom?: string | null;
+        validTo?: string | null;
     }): {
         changes: number;
         lastInsertRowid: number | bigint;
     };
+    /**
+     * P-10: land an explicitly given validity on a row that already exists (a duplicate `add` whose
+     * caller named `event_date` / `valid_until`). Omitted arguments keep what the row has, exactly
+     * like `category`/`ttl_days` (see `add`'s doc).
+     */
+    applyValidity(factId: number, validFrom: string | undefined, validTo: string | undefined): void;
+    /** P-10: the row's assertion counter (`1` when the column is somehow NULL on a legacy row). */
+    assertCount(factId: number): number;
+    /**
+     * P-10: a verbatim re-assertion of an EXISTING active fact. Returns the new count.
+     *
+     * Only the pure-duplicate branch calls this: reviving an archived row is a resurrection, not a
+     * new assertion (`assert_count` answers "how many times was this said", and the archived row's
+     * own count already recorded that). `RETURNING` keeps the read and the write one statement, so
+     * two processes cannot interleave between them.
+     */
+    incrementAssertCount(factId: number): number;
+    /**
+     * P-07 audit: stamp `valid_to` on a row that is leaving the active corpus (supersede / a
+     * contradiction verdict). `COALESCE` keeps an end the caller already declared (`valid_until`):
+     * overwriting it with the archival instant would replace a real answer with an administrative one.
+     */
+    markValidTo(factId: number, at: string): void;
+    /**
+     * P-07: "who superseded this fact", derived from the existing `supersedes_id` link — no
+     * redundant column. `MIN` is deterministic when several revisions named the same predecessor
+     * (which a merge can produce); the caller renders it as a single direct successor.
+     */
+    supersededBy(factId: number): number | null;
+    /** P-13 coverage: ACTIVE facts that carry an event time (the `admin stats` numerator). */
+    countActiveWithValidFrom(): number;
+    /**
+     * P-11: the ids of ACTIVE facts whose EVENT time (`valid_from`) falls inside an INCLUSIVE local
+     * day range, newest first, capped.
+     *
+     * The comparison is on the DATE PREFIX (`substr(valid_from, 1, 10)`) rather than on the raw text:
+     * `valid_from` is whatever ISO string the caller wrote (`2026-09-15` or
+     * `2026-09-15T09:30:00+08:00`), and a lexicographic range over the full strings would put a
+     * midnight timestamp on the wrong side of a day boundary. Day granularity is the unit the window
+     * parser speaks (`store/time_window.ts`), so `substr` is the matching one. No index can serve it;
+     * the leg is default-OFF and capped, and a full scan of `facts` for one enabled query is the
+     * accepted cost (see the leg's own comment).
+     *
+     * The `GLOB` is a SHAPE guard, not decoration: the prefix is compared LEXICOGRAPHICALLY, so a
+     * non-padded `2026-9-5` (which `Date.parse` accepts, so `normalizeEventTime` stores it) would sort
+     * AFTER `2026-09-30` and leak into an October window. Requiring the canonical zero-padded prefix
+     * excludes such a value from the leg entirely — the same "no usable event time" treatment, never a
+     * mis-binned one.
+     *
+     * `valid_from IS NOT NULL` is the P-11 discipline written into SQL: a fact with no event time is
+     * NOT a candidate here, and there is deliberately no `COALESCE(valid_from, created_at)` fallback —
+     * mixing a write clock into an event-time axis is exactly what this leg must not do.
+     *
+     * `EXISTS`, never a JOIN on `fact_sources` (the {@link FTS_SEARCH_SQL_FILTERED} rule): the cap is
+     * `LIMIT`, and a multi-source fact would eat cap slots with duplicate rows.
+     */
+    windowRows(fromDate: string, toDate: string, category: string | undefined, cap: number, source?: string): number[];
     findByContent(content: string): Record<string, unknown> | undefined;
     /**
      * ACTIVE facts whose entity/triple rows were produced by OLDER extraction rules.
@@ -283,8 +371,8 @@ export declare class FactsDao {
      *    index in order and filter per row (measured 9.8 ms for a category with 17 rows at 33k),
      *    i.e. it would trade a fast path for a slow one to save an index we do not need.
      */
-    page(status: string, category: string | undefined, limit: number, offset: number): Record<string, unknown>[];
-    countInStatus(status: string, category?: string): number;
+    page(status: string, category: string | undefined, limit: number, offset: number, source?: string): Record<string, unknown>[];
+    countInStatus(status: string, category?: string, source?: string): number;
     /** Every ACTIVE fact (the report's `active`). */
     countActive(): number;
     /** ACTIVE and permanent — pinned facts are exempt from decay (the report's `pinned`). */
@@ -344,7 +432,7 @@ export declare class FactsDao {
      * facts with a cap of 200 it silently made 32.8k of them unreachable. Recency is the honest
      * prior for a memory store and `idx_facts_created(status, created_at DESC)` already serves it.
      */
-    activeHrrRows(category?: string, limit?: number): {
+    activeHrrRows(category?: string, limit?: number, source?: string): {
         fact_id: number;
         hrr_vector: Uint8Array;
     }[];
@@ -356,12 +444,12 @@ export declare class FactsDao {
      * which is the same information the HRR bundle encodes (its atoms ARE the entity names), so the
      * narrowing removes the O(N) part rather than a meaningful part of the ranking.
      */
-    hrrRowsForFacts(ids: readonly number[], category?: string): {
+    hrrRowsForFacts(ids: readonly number[], category?: string, source?: string): {
         fact_id: number;
         hrr_vector: Uint8Array;
     }[];
-    /** ACTIVE subset of `ids` in one category (`null` = any) — the semantic leg's filter. */
-    activeIdsIn(ids: readonly number[], category?: string): number[];
+    /** ACTIVE subset of `ids` in one category/source (`null` = any) — the semantic leg's filter. */
+    activeIdsIn(ids: readonly number[], category?: string, source?: string): number[];
     /** `retrieval_count` + the "last used" clock (spec §2.5), batched. */
     touchUsage(ids: readonly number[]): void;
     /** Recall bonus not granted: only the settled trust moved. */
@@ -376,7 +464,22 @@ export declare class FactsDao {
      * that JOIN from becoming the drive (see {@link FTS_SEARCH_SQL}, which carries the plans and
      * measurements).
      */
-    ftsSearch(ftsQuery: string, category?: string, limit?: number): {
+    ftsSearch(ftsQuery: string, category?: string, limit?: number, source?: string): {
+        id: number;
+        rank: number;
+    }[];
+    /**
+     * The SHORT-QUERY fallback leg: rows whose `content` contains at least one of the terms as a
+     * contiguous substring, scored by how many it contains.
+     *
+     * Reached only when `buildFtsQuery` produced nothing (a 2-char CJK query — see
+     * `db/tokenizer.ts#likeSubstring` and `store/lexical.ts`), so it cannot move an indexed query.
+     * `rank` is the number of distinct terms the row contains, which is the same quantity
+     * `applyTermFloor` grades with; ties break on ascending id, matching `fuse`'s own tie rule, so a
+     * single-term query (all ranks 1) has a deterministic order. `ORDER BY rank` must read the SELECT
+     * alias, so the LIKE expressions are built once and bound twice — same fragment, same order.
+     */
+    ftsSubstringSearch(terms: readonly string[], category?: string, limit?: number, source?: string): {
         id: number;
         rank: number;
     }[];

package/lib/engine/mem/db/dao/shared.d.ts

@@ -0,0 +1,153 @@
+/**
+ * The DAO layer's SHARED ALGORITHMS AND CONTRACTS.
+ *
+ * DAOs are split by AGGREGATE, not by store (`docs/vector-repair-shared-flow.md` §2), and each
+ * aggregate keeps its own SQL text: replacing a readable statement with a generic
+ * table/column-parameterized builder would cost the comments' index reasoning without converging a
+ * business rule — a `count`/`get`/`delete`/`list` one-liner is a different aggregate's statement,
+ * not a fork (§4.5 "明确不收敛").
+ *
+ * What DOES get one implementation here is the part that is literally "one rule, two tables":
+ *
+ *  - the entity-candidate leg's SCORE and ORDER, plus its batch/union loop
+ *    ({@link entityCandidates} / {@link entityCandidateTail});
+ *  - the batched `UPDATE … SET entities_version = ?` ({@link setEntitiesVersionBatch});
+ *  - the short-query LIKE fallback's build/guard/double-bind protocol
+ *    ({@link likeSubstringLeg});
+ *  - the document-frequency query shape ({@link queryDocFrequency});
+ *  - the batched "entity-name bags for a row-id set" read ({@link entityBags}).
+ *
+ * Each caller still supplies its own statement (or its `FROM`/name/filter pieces), so the SQL stays
+ * at the call site while the rule lives here exactly once. No base class: every export is a free
+ * function, the style `store/common.ts` established.
+ */
+import type { Db } from '../port.js';
+/**
+ * The entity-candidate leg's ORDER contract — the tail every candidate statement ends with.
+ *
+ * The formula is the leg's own score (anchored Jaccard with a saturating union,
+ * `store/entity_leg.ts`): `shared / (queryWidth + min(total - shared, widthCap))`. Ordering by it is
+ * load-bearing, not cosmetic: `fuse` scales each leg by its maximum, and a survivor's scaled value
+ * is unchanged only when the ordering — and therefore the maximum — survives the trim. A narrower
+ * row sharing one entity can therefore outrank a wide one sharing two, and the cap keeps it.
+ * `total ASC` is only a deterministic tie-break among equal ratios, and the id makes the order total.
+ *
+ * `idColumn` is the aggregate's own id (`fa.fact_id` / `ce.chunk_id`); that, the `total` subquery's
+ * table and the filter predicates are the ONLY differences between the two statements.
+ */
+export declare function entityCandidateTail(idColumn: string): string;
+/** One call to the shared entity-candidate runner — see {@link entityCandidates}. */
+export interface EntityCandidateQuery {
+    /** The (anchor) names to match: one `IN (…)`, or one per batch when {@link batchNames}. */
+    names: readonly string[];
+    /**
+     * NULL-able filter values bound right AFTER the name list and BEFORE `queryWidth`, in the SQL's
+     * own order (both callers spell their predicates as `(? IS NULL OR …)`, so a value the filter
+     * does not use is still bound as `null`).
+     */
+    filterParams: readonly unknown[];
+    limit: number;
+    /** The query's FULL entity count (`W` in `store/entity_leg.ts`); `widthCap` is its saturating cap. */
+    queryWidth: number;
+    widthCap: number;
+    /**
+     * `true` (knowledge): run one statement per name-batch and UNION the ids, because the query can in
+     * principle carry more names than a single `IN (…)` may bind. A union of per-batch tops is NOT a
+     * top-N, so that caller must enforce its real cap on the union AFTER scoring.
+     * `false` (memory): one statement and one exact `LIMIT` — the store's names are request-bounded,
+     * so a single `LIMIT` is already the top-N and the cap argument above holds bit-for-bit.
+     */
+    batchNames: boolean;
+    /**
+     * The full statement for one placeholder list; it must project `id`, `shared`, `total` and end
+     * with {@link entityCandidateTail}.
+     */
+    sql: (placeholders: string) => string;
+}
+/**
+ * Run an entity-candidate query: bind order, batching and union are shared; the SQL is the caller's.
+ *
+ * Bind order (identical in both aggregates): `<names …>, <filterParams …>, queryWidth, widthCap, limit`.
+ */
+export declare function entityCandidates(db: Db, q: EntityCandidateQuery): number[];
+/**
+ * The batched `UPDATE … SET entities_version = ?` shared by `FactsDao` and `ChunksDao`.
+ *
+ * Only the aggregate's `table` / `idColumn` differ. Returns the summed `changes`; the knowledge
+ * caller ignores it (its method's signature returns `void`), the memory caller's `number` is
+ * unchanged.
+ */
+export declare function setEntitiesVersionBatch(db: Db, table: string, idColumn: string, ids: readonly number[], version: number): number;
+/** The per-aggregate pieces of the document-frequency query — see {@link queryDocFrequency}. */
+export interface DocFrequencyQuery {
+    /** `FROM …` with its JOINs: everything between the projection and `WHERE`. */
+    from: string;
+    /** The name expression (`e.name`, `name`), used as the alias, the IN predicate and `GROUP BY`. */
+    nameExpr: string;
+    /** A constant predicate ANDed after the IN clause; it must add NO bind parameters. */
+    where?: string;
+}
+/**
+ * Document frequency — "how many rows carry each name".
+ *
+ * Shared by `EntitiesDao.activeDocFrequency` and `ChunksDao.docFrequency`; the only difference is
+ * the population the caller's `where`/`from` describe (memory counts ACTIVE facts, knowledge has no
+ * status column and counts chunks). Only the caller's QUERY names are looked up, so this is one
+ * indexed COUNT per name rather than a corpus scan. A name absent from the map has frequency 0.
+ */
+export declare function queryDocFrequency(db: Db, names: readonly string[], q: DocFrequencyQuery): Map<string, number>;
+/** The two SQL fragments {@link likeSubstringLeg} hands back to the caller's statement builder. */
+export interface LikeSubstringFragments {
+    /** The `WHERE` predicate (OR of the term patterns). */
+    any: string;
+    /** The score expression (count of the terms the row contains), to be aliased as `rank`. */
+    count: string;
+}
+/**
+ * The SHORT-QUERY LIKE fallback shared by `FactsDao.ftsSubstringSearch` and
+ * `ChunksDao.ftsSubstringSearch`.
+ *
+ * The predicate text itself already comes from `db/tokenizer.ts#likeSubstring`; this owns the
+ * protocol AROUND it, which both copies spelled out:
+ *
+ *  1. build the fragments — empty terms yield no patterns, which means "match nothing" ⇒ `[]`;
+ *  2. `count` lands in the SELECT and `any` in the WHERE, so the SAME pattern list is bound TWICE:
+ *     once with the SELECT's placeholders, then — after the caller's filter params — with the
+ *     WHERE's;
+ *  3. `LIMIT ?` last, defaulting to `-1` (unbounded; the store bounds the leg).
+ *
+ * `ORDER BY rank DESC, <id> ASC` stays in the caller's SQL: the id column is aggregate-specific and
+ * `rank` must read the SELECT alias, so the fragments and the patterns are built once and used twice.
+ */
+export declare function likeSubstringLeg(db: Db, column: string, terms: readonly string[], buildSql: (fragments: LikeSubstringFragments) => string, filterParams?: readonly unknown[], limit?: number): {
+    id: number;
+    rank: number;
+}[];
+/** The per-aggregate SQL pieces of {@link entityBags}. */
+export interface EntityBagsQuery {
+    /** `FROM …` with its alias: `fact_entities fe` / `chunk_entities`. */
+    table: string;
+    /** The id expression, also the `WHERE … IN (…)` subject: `fe.fact_id` / `chunk_id`. */
+    keyColumn: string;
+    /** The name expression: `e.name` / `name`. */
+    nameColumn: string;
+    /** The `JOIN` that reaches the name vocabulary, for aggregates that have one (`''`/omitted for `chunk_entities`). */
+    joinEntities?: string;
+    /**
+     * The DEFAULT semantics — the one real difference between the two callers, so it is explicit:
+     *
+     *  - `true` (memory): every requested id is pre-seeded with `[]` in the REQUEST's order, so the
+     *    caller can assume `bags.get(id)` exists. Names are appended in row order after that;
+     *  - `false` (knowledge): only rows that actually carry entities appear (the caller uses `?? []`).
+     */
+    seedEmpty: boolean;
+}
+/**
+ * Batched entity-name bags for a row-id set: `Map<rowId, names>`.
+ *
+ * Shared by `EntitiesDao.bagsForFacts` and `ChunksDao.entityBags` (§4.6.3): one `IN (…)` statement
+ * per `batches()` slice, rows folded into the map in first-seen order. The SQL SHAPE is the only
+ * aggregate-specific part (`table` / `keyColumn` / `nameColumn` / `joinEntities`); the crucial
+ * `seedEmpty` difference above is the caller's to declare and stays observable.
+ */
+export declare function entityBags(db: Db, ids: readonly number[], q: EntityBagsQuery): Map<number, string[]>;

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

@@ -0,0 +1,26 @@
+/**
+ * P-07 validity invariants, as SQL an operator (or a test) can run against a database.
+ *
+ * The batch-1 fields are DISPLAY/AUDIT data — no retrieval leg reads them — so nothing in the read
+ * path would notice if a write stopped stamping them. These two statements are the check that
+ * cannot be satisfied vacuously: each has a planted-violation test in
+ * `test/fact_provenance.spec.ts` proving it reports a real inconsistency.
+ *
+ * ① The two SEMANTIC retirement paths (`update`'s supersede and a `true_positive` contradiction
+ *    verdict) archive a fact because it stopped being true. Both must leave an end time, or the
+ *    audit trail says "retired, cause known, end unknown". Lifecycle archival (`ttl` / `forgot` /
+ *    `idle` / `manual`) is deliberately NOT in the set: those are retention decisions, not statements
+ *    about when the fact stopped being true.
+ *
+ * ② A known end cannot precede a known start.
+ */
+import type { Db } from './port.js';
+/** Facts retired by a semantic path (`replaced` / `contradiction`) without a recorded end time. */
+export declare const RETIRED_WITHOUT_VALID_TO_SQL = "SELECT COUNT(*) AS n FROM facts\n  WHERE status = 'archived' AND archive_reason IN ('replaced', 'contradiction') AND valid_to IS NULL";
+/** Rows whose known end precedes their known start. */
+export declare const VALID_TO_BEFORE_VALID_FROM_SQL = "SELECT COUNT(*) AS n FROM facts\n  WHERE valid_from IS NOT NULL AND valid_to IS NOT NULL AND valid_to < valid_from";
+/** Every P-07 invariant, evaluated. All-zero is the healthy state. */
+export declare function validityInvariantViolations(db: Db): {
+    retired_without_valid_to: number;
+    valid_to_before_valid_from: number;
+};

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

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[];