@avantf/dsh-mem 0.4.2 → 0.6.0

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

@@ -3,18 +3,16 @@
  *
  * `MemoryStore.search` and `KnowledgeStore.search` used to carry parallel copies of this flow
  * (~80 lines each: limit normalization → weights → over-fetch → leg cap → fuse → live filter →
- * rerank → slice → output budget → health event). The legs themselves are legitimately
- * store-specific — different tables, different filters (`category` vs `domain`/`source`), and only
- * memory has the HRR probe — but the ORCHESTRATION is one algorithm, and two copies of it drifted:
+ * slice → output budget → health event). The legs themselves are legitimately store-specific —
+ * different tables, different filters (`category` vs `domain`/`source`), and only memory has the
+ * HRR probe — but the ORCHESTRATION is one algorithm, and two copies of it drifted:
  *
  *   - the `NaN` limit guard existed only in memory, so a non-finite limit reached knowledge's SQL
  *     `LIMIT` and took the whole cross-store query down with it (`Promise.all` has no per-leg catch);
  *   - `retriever.over_fetch_factor` was read only by memory, while knowledge hardcoded `limit * 3`,
  *     so one config knob silently meant two different things;
  *   - `recordLegCapped()` was called only by memory, so a capped knowledge leg was unobservable —
- *     exactly the blindness DESIGN §20.17 says the counter exists to remove;
- *   - the reranker's used/fallback flags were a helper in memory and an inline expression in
- *     knowledge.
+ *     exactly the blindness DESIGN §20.17 says the counter exists to remove.
  *
  * Fixing those one at a time would leave the next drift a matter of when. The stores now supply
  * their legs and their hit mapping; everything that can drift lives here once.
@@ -26,7 +24,7 @@
  * @module store/hybrid
  */
 import { type Config, type FloorProfile, type RecallResult, type RetrievalFloorDrops, type RetrievalFloors } from '../../mem-contract/index.js';
-import { type BudgetInput, type Hit, type Reranker, type SemanticBackend } from '../../mem-retrieval/index.js';
+import { type BudgetInput, type Hit, type SemanticBackend } from '../../mem-retrieval/index.js';
 import { type FloorLeg } from './floors.js';
 /** The `limit` a caller gets when it passes nothing usable. */
 export declare const DEFAULT_SEARCH_LIMIT = 10;
@@ -63,8 +61,12 @@ export interface HybridLeg {
     capped?: boolean;
     /**
      * Which floor governs this leg, for {@link HybridResult.dropped_by_floor}'s per-leg breakdown.
-     * The HRR probe shares the Jaccard floor; naming it separately keeps a narrowed candidate set
-     * attributable without double-counting the Jaccard leg's own drops.
+     * The HRR probe shares the entity (`jaccard`) floor; naming it separately keeps a narrowed
+     * candidate set attributable without double-counting the entity leg's own drops.
+     *
+     * The `jaccard` KEY is historical: the entity leg's metric is now anchored Jaccard with a
+     * saturating union, whose unit (and the `min_jaccard` floor on it) is defined in
+     * `store/entity_leg.ts` — read that before re-calibrating the knob.
      */
     leg?: keyof RetrievalFloorDrops;
     /** Candidates this leg removed because they fell below its floor. */
@@ -113,7 +115,6 @@ export interface HybridDeps<H> {
     kind: 'memory' | 'knowledge';
     config: Config;
     semantic: SemanticBackend;
-    reranker: Reranker;
     /**
      * The legs to fuse, as promises (or values). Awaited concurrently; a rejection costs that leg
      * only. The async setup a store needs before it can build its legs — memory extracts the query's
@@ -121,7 +122,7 @@ export interface HybridDeps<H> {
      * body, before the array is returned.
      */
     legs(ctx: HybridContext): Promise<readonly (HybridLeg | Promise<HybridLeg>)[]>;
-    /** Text for the fused ids: the live filter, the reranker's input, and the hit bodies. */
+    /** Text for the fused ids: the live filter and the hit bodies. */
     texts(ids: number[]): Map<number, string>;
     /** Build the caller-facing hits from the ranked, live, already-sliced ids. */
     hits(ranked: readonly Hit[], texts: Map<number, string>): H[];
@@ -177,6 +178,12 @@ export interface HybridPlan {
      * `queries` counts questions instead of legs (DESIGN §20.5).
      */
     recordStats?: boolean;
+    /**
+     * P-01: attach per-leg evidence to the returned hits (`RecallHit.scores` / `final`). Default
+     * false, and that default is load-bearing: the evidence is explanation only, so a caller that did
+     * not ask must not pay for it in tokens (`fuse` skips building the arrays entirely).
+     */
+    includeScores?: boolean;
 }
 /** A hit after the output budget: `text` may have been shortened, and `truncated` says so. */
 export type Budgeted<T> = T & {
@@ -207,17 +214,6 @@ export interface HybridResult<H> {
  * rather than per store, because the health counter compares against whatever this returns.
  */
 export declare function legCapFor(config: Config, overFetch: number): number;
-/**
- * Whether the configured reranker is actually in use — the two flags a retrieval event carries.
- *
- * "Configured" is not "used": a reranker that is selected but unavailable falls back to the fused
- * order, and counting that as a rerank would make the counter lie in exactly the case it exists to
- * expose (the reference implementation leaves `rerank_fallback` unfeedable).
- */
-export declare function rerankState(reranker: Reranker): {
-    used: boolean;
-    fallback: boolean;
-};
 /**
  * Bound a ranked hit list to a token budget, marking what was shortened.
  *
@@ -233,9 +229,8 @@ export declare function applyOutputBudget<H extends BudgetInput>(config: Config,
 /**
  * Run one hybrid search.
  *
- * The order of the last three steps is load-bearing: rerank the over-fetched pool, THEN slice to
- * `limit`, THEN apply the output budget, and only then tell the store what was returned. Slicing
- * before the rerank would rank an arbitrary subset; budgeting before the slice would spend the
- * budget on hits that are about to be dropped.
+ * The order of the last steps is load-bearing: slice the fused (over-fetched) pool to `limit`,
+ * THEN apply the output budget, and only then tell the store what was returned. Budgeting before
+ * the slice would spend the budget on hits that are about to be dropped.
  */
 export declare function hybridSearch<H extends BudgetInput>(deps: HybridDeps<H>, plan: HybridPlan): Promise<HybridResult<H>>;

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

@@ -1,5 +1,5 @@
 import { type AvantfLogger, type Config, type DocumentDetail, type DocumentSummary, type DomainCatalog, type FloorProfile, type ImportResult, type IngestResult, type KbConflictReport, type KbIngestConflict, type KbSyncReport, type KnowledgeConfig, type RecallHit, type ReindexReport } from '../../mem-contract/index.js';
-import type { Reranker, SemanticBackend, VectorStore } from '../../mem-retrieval/index.js';
+import type { SemanticBackend, VectorStore } from '../../mem-retrieval/index.js';
 import { type LexicalProbe } from './lexical.js';
 import { type FloorLeg } from './floors.js';
 import { type HybridResult } from './hybrid.js';
@@ -43,6 +43,8 @@ export interface KnowledgeSearchOptions {
      * store-level "last result" field would race two concurrent queries.
      */
     onResult?: (result: HybridResult<RecallHit>) => void;
+    /** P-01: attach per-leg evidence (`scores` / `final`) to every hit. Default false. */
+    includeScores?: boolean;
 }
 /**
  * One identity a write will land on: the title it will use, the resolved local path it would read
@@ -87,7 +89,6 @@ export type IngestMode = 'add' | 'replace';
 export declare class KnowledgeStore {
     private readonly semantic;
     private readonly vstore;
-    private readonly reranker;
     /** The store config file `addDomain` writes the allowlist back to (`knowledgeConfigPath(home)`). */
     private readonly domainConfigPath;
     private readonly logger?;
@@ -127,7 +128,7 @@ export declare class KnowledgeStore {
     private readonly allowedDomains;
     /** Whether the config allowlist is active (non-empty); `false` = `domains: []` = no restriction. */
     private readonly domainsRestricted;
-    constructor(dbPath: string, config: Config, kbConfig: KnowledgeConfig, semantic: SemanticBackend, vstore: VectorStore, reranker: Reranker, 
+    constructor(dbPath: string, config: Config, kbConfig: KnowledgeConfig, semantic: SemanticBackend, vstore: VectorStore, 
     /** The store config file `addDomain` writes the allowlist back to (`knowledgeConfigPath(home)`). */
     domainConfigPath: string, logger?: AvantfLogger | undefined);
     /**
@@ -302,11 +303,12 @@ export declare class KnowledgeStore {
      */
     private encodeAndStore;
     /**
-     * Identity of the vector space this store currently writes into (DESIGN §20): a change of
-     * backend, model or width makes every stored chunk vector stale, and the whole point of
-     * recording it is that such a change is DETECTED instead of silently mixing two spaces.
+     * Identity of the vector space this store currently writes into (DESIGN §20): the representation
+     * fingerprint — backend, model, width AND the backend's declared pooling/normalization/input
+     * window/model revision — so any representation change makes stored chunk vectors stale instead
+     * of silently mixing two spaces. Public so diagnostics and tests can name the space.
      */
-    private vectorSpace;
+    vectorSpace(): string;
     /**
      * A stored vector is reusable when it exists, matches the space, and its text is unchanged.
      *
@@ -434,7 +436,7 @@ export declare class KnowledgeStore {
      * and the chunk→hit mapping.
      *
      * The limit normalization, the over-fetch factor, the leg cap, the capped-leg counter, the
-     * degraded weights, the rerank and the output budget all live there now. They used to be copied
+     * degraded weights and the output budget all live there now. They used to be copied
      * here, and every fix landed on the memory side only — a `NaN` limit reached this store's SQL and
      * took the whole cross-store query down with it, `retriever.over_fetch_factor` meant something
      * different per store, and a capped knowledge leg was invisible to the health counters.
@@ -463,7 +465,14 @@ export declare class KnowledgeStore {
      */
     lexicalProbe(text: string, stopAt?: number): LexicalProbe;
     private ftsPath;
-    /** Entity overlap against entities extracted AT INGEST time (chunk_entities) — no corpus scan. */
+    /**
+     * Entity overlap against entities extracted AT INGEST time (chunk_entities) — no corpus scan.
+     *
+     * Same metric as the memory store's sibling (`store/entity_leg.ts` carries the measurement and
+     * the reasoning): anchored Jaccard with a saturating union over the query's rare entities, so a
+     * wide chunk cannot dilute the denominator and a corpus-wide word cannot drag the whole knowledge
+     * base in.
+     */
     private jaccardPath;
 }
 export interface Chunk {

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

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

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

@@ -1,5 +1,5 @@
-import { type Config, type ContradictionRecord, type FactDetail, type FactPage, type FloorProfile, type RecallResult, type RememberResult, type TrustDiagnostic, type VectorMigrationOutcome, type VectorMigrationProgress, type VectorSpaceHealth, type VectorsDiagnostic, type VectorsFixReport } from '../../mem-contract/index.js';
-import type { Reranker, SemanticBackend, VectorStore } from '../../mem-retrieval/index.js';
+import { type Config, type ContradictionRecord, type FactDetail, type FactPage, type FloorProfile, type RecallResult, type RememberResult, type SourceCoverage, type TrustDiagnostic, type ValidityCoverage, type VectorMigrationOutcome, type VectorMigrationProgress, type VectorSpaceHealth, type VectorsDiagnostic, type VectorsFixReport } from '../../mem-contract/index.js';
+import type { SemanticBackend, VectorStore } from '../../mem-retrieval/index.js';
 import type { Db } from '../db/conn.js';
 import { type LexicalProbe } from './lexical.js';
 import { type FloorLeg } from './floors.js';
@@ -88,6 +88,13 @@ export interface ContradictionResolution {
 export interface SearchInput {
     query: string;
     category?: string;
+    /**
+     * P-08: restrict every leg to facts whose `fact_sources.ref` equals this value. Applied INSIDE
+     * each leg's SQL (an `EXISTS` predicate, before its `LIMIT cap`), never as a post-fusion filter:
+     * pruning after fusion would return fewer than `limit` and would make the relaxed-floor retry
+     * mistake a source-empty result for "the floors were too strict".
+     */
+    source?: string;
     limit?: number;
     /** Also fuse the HRR entity-probe path (used by `recall.probe`). */
     includeHrr?: boolean;
@@ -134,17 +141,34 @@ export interface SearchInput {
      * `track`, which is about the dormancy clock — a caller may want one without the other.
      */
     recordStats?: boolean;
+    /** P-01: attach per-leg evidence (`scores` / `final`) to the returned hits. Default false. */
+    includeScores?: boolean;
+}
+/**
+ * P-08 / P-13 write-side extras on `add` / `update`.
+ *
+ * All three are optional and "omitted" has one meaning everywhere: do not write (a new row's
+ * NULL/1 default, or the existing row's value on a duplicate) — the store never invents a source,
+ * an event time or an end date.
+ */
+export interface FactWriteOptions {
+    /** P-08: `fact_sources` provenance. `kind:` prefix selects the kind, else `manual`. */
+    sourceRef?: string;
+    /** P-13: event time → `valid_from`. */
+    eventDate?: string;
+    /** P-13: known end → `valid_to`, WITHOUT archiving the row. */
+    validUntil?: string;
 }
 export declare class MemoryStore {
     private readonly db;
     private readonly config;
     private readonly semantic;
     private readonly vstore;
-    private readonly reranker;
     private readonly contradictions;
     private readonly facts;
     private readonly entities;
     private readonly triples;
+    private readonly sources;
     /**
      * The tokenizer `facts_fts` was ACTUALLY built with, read from the database at open.
      *
@@ -160,7 +184,7 @@ export declare class MemoryStore {
      * derived state: nothing is lost when it resets, and the queue itself is in the database.
      */
     private conflictDrainCursor;
-    constructor(db: Db, config: Config, semantic: SemanticBackend, vstore: VectorStore, reranker: Reranker, 
+    constructor(db: Db, config: Config, semantic: SemanticBackend, vstore: VectorStore, 
     /** The store's database path, used ONLY to name the vector index snapshot beside it. */
     dbPath?: string);
     /**
@@ -171,8 +195,12 @@ export declare class MemoryStore {
     trustTick(opts?: {
         budget?: number | null;
     }): TickResult;
-    /** Identity of the vector space this store currently writes into (`vectorSpaceId`). */
-    private vectorSpace;
+    /**
+     * Identity of the vector space this store currently writes into — the REPRESENTATION fingerprint
+     * (`vectorSpaceId` + the backend's declared pooling/normalize/window/revision), not just the
+     * model name. Public so diagnostics and tests can name the space the store would record.
+     */
+    vectorSpace(): string;
     /**
      * Rebuild the in-memory vstore from persisted `facts.semantic_vector` BLOBs.
      * Without this the semantic path is silently empty after every process restart
@@ -193,7 +221,13 @@ export declare class MemoryStore {
      * is the read model those surfaces use instead of the full diagnose pass.
      */
     vectorSpaceHealth(): VectorSpaceHealth;
-    add(content: string, category?: string, ttlDays?: number): Promise<RememberResult>;
+    /**
+     * {@link vectorSpaceHealth} plus the internal `legacy` split (how many `space_stale` rows predate
+     * the representation fingerprint). Kept off the contract type so the public detection surface —
+     * and every existing assertion on it — is unchanged; only the warning's wording uses it.
+     */
+    private vectorSpaceCounts;
+    add(content: string, category?: string, ttlDays?: number, opts?: FactWriteOptions): Promise<RememberResult>;
     /**
      * Write-path contradiction detection (DESIGN §11): check the fact that was just
      * written against the corpus, then report its FULL open-conflict set.
@@ -212,7 +246,7 @@ export declare class MemoryStore {
     private detectContradictions;
     /** Best-effort semantic indexing: encode the fact and add it to the vstore. */
     private maybeIndexSemantic;
-    update(fact_id: number, content: string, category?: string, ttlDays?: number): Promise<RememberResult>;
+    update(fact_id: number, content: string, category?: string, ttlDays?: number, opts?: FactWriteOptions): Promise<RememberResult>;
     remove(fact_id: number, reason?: string): boolean;
     archive(fact_id: number, reason?: string): boolean;
     /**
@@ -250,7 +284,17 @@ export declare class MemoryStore {
      * @returns the page, the page size (`count`), the matching total, and whether
      * more rows remain after this page.
      */
-    list(category?: string, status?: string, limit?: number, offset?: number): FactPage;
+    list(category?: string, status?: string, limit?: number, offset?: number, 
+    /** P-08: only facts whose `fact_sources.ref` equals this value (reverse provenance lookup). */
+    source?: string): FactPage;
+    /**
+     * P-08 coverage over the ACTIVE corpus, for `admin stats`: the share of facts that can answer
+     * "why do I remember this". Reported from day one so the field cannot quietly become a second
+     * `mirror_source` (filled but meaningless).
+     */
+    sourceCoverage(): SourceCoverage;
+    /** P-13 coverage over the ACTIVE corpus: the share of facts carrying an event time. */
+    validityCoverage(): ValidityCoverage;
     countByStatus(): {
         active: number;
         archived: number;
@@ -474,20 +518,32 @@ export declare class MemoryStore {
      * rescale the survivors. That covers the Jaccard and FTS legs. It does NOT cover the HRR leg, whose
      * candidates arrive in the JACCARD leg's order (or by recency in its fallback), so its cap can
      * remove its own highest scorer and `v / max` really does move. Accepted — the cap bounds per-query
-     * mission and the pool is reranked afterwards — but do not read these scores as comparable across
-     * different cap/over-fetch settings; see `docs/PROVENANCE_REVIEW.md` N5 for the missing differential.
+     * mission — but do not read these scores as comparable across different cap/over-fetch settings;
+     * see `docs/PROVENANCE_REVIEW.md` N5 for the missing differential.
      */
     private searchLegs;
     /**
-     * Whether the configured reranker is actually in use — the two flags a retrieval event
-     * carries. Exposed so the cross-store router can report ONE event for a merged query with the
-     * same honesty as a single-store search (both stores share this adapter, and the derivation lives
-     * in `store/hybrid.ts` rather than being re-spelled per store).
+     * P-11: active facts whose EVENT time (`valid_from`) falls in the query's own time window.
+     *
+     * THREE DELIBERATE PROPERTIES, each of which the acceptance criteria name:
+     *
+     *  1. **Only `valid_from`.** A fact with no event time is not a candidate, and there is no
+     *     fallback to `created_at`: mixing a write clock into the event-time axis would make the leg
+     *     "work" on a corpus where it measured zero effect and would answer "上个月做了什么" with
+     *     facts merely WRITTEN last month.
+     *  2. **A leg, not a filter.** The window only ever ADDS candidates at a constant score; it never
+     *     removes one another leg (or the FTS/entity/semantic path) produced. A hard pre-filter would
+     *     drop gold facts whose event time is outside the phrase's window but whose text is the answer.
+     *  3. **Constant score, capped.** Every in-window fact scores 1, so `fuse`'s per-leg max-scaling
+     *     is cap-INVARIANT for this leg (any survivor IS the maximum) and the ranking WITHIN the
+     *     window stays the other legs' business. The constant is why "which of last month's facts is
+     *     the answer" is not decided by a date.
+     *
+     * Cost: one non-indexable scan (the date prefix is computed, so no index can serve it) of the
+     * active corpus, capped at `legCap`. It runs only when `retriever.time_window` is on — the whole
+     * point of the default-OFF switch.
      */
-    rerankState(): {
-        used: boolean;
-        fallback: boolean;
-    };
+    private timeWindowPath;
     /**
      * The one fact→RecallHit mapper (kind/source_ref/entities shape lives here ONLY;
      * chain/reason/ask/search all used to carry byte-identical copies, three of them
@@ -553,8 +609,15 @@ export declare class MemoryStore {
     lexicalProbe(text: string, stopAt?: number): LexicalProbe;
     private ftsPath;
     /**
-     * Jaccard leg over the precomputed candidate set (see `search`): the candidates are the facts
-     * sharing at least one query entity, pre-ranked by how many they share and already capped.
+     * Entity leg over the precomputed candidate set (see `searchLegs`): the candidates are the facts
+     * sharing at least one ANCHOR query entity, pre-ranked by how many they share and already capped.
+     *
+     * The score is anchored Jaccard with a saturating union —
+     * `|anchors ∩ F| / (queryWidth + min(|F \ anchors|, ENTITY_UNION_CAP))`; `store/entity_leg.ts`
+     * carries why the old `|Q ∩ F| / |Q ∪ F|` was structurally unreachable for short queries, and why
+     * the generic-word filter keeps the wider denominator from dragging the corpus in. The fact set is
+     * read per candidate and the score is recomputed here even though the DAO ordered by it, so one
+     * formula stays in charge (the DAO's `total` tie-break only orders equal scores).
      */
     private jaccardPath;
     /**
@@ -569,6 +632,16 @@ export declare class MemoryStore {
      * defaults (`general` / `0`).
      */
     private persistFact;
+    /**
+     * P-08: land the provenance rows for one write.
+     *
+     * Rules, in order: an explicit `source_ref` is recorded (classified by its `kind:` prefix); on a
+     * REVISION with none given, the replaced row's sources are copied forward (it is the same logical
+     * fact, and the new row would otherwise become untraceable); on a plain duplicate, nothing is
+     * added (its sources are already there). Nothing is ever invented — an omitted source on a first
+     * add leaves the fact with no `fact_sources` row at all, which is what the stats coverage reports.
+     */
+    private recordSources;
     /**
      * Link the revision chain and archive the superseded fact — on both the fresh-insert
      * and duplicate-content branches.

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

@@ -0,0 +1,34 @@
+/**
+ * Write-side secret / PII shape guard (P-03) — a PURE function, no store, no IO.
+ *
+ * The memory store is a long-lived, backed-up, sometimes-remote copy of what the model chose to
+ * write down, so a plaintext credential that reaches it is hard to retract. This guard refuses a
+ * fact whose TEXT matches a HIGH-CONFIDENCE credential/PII shape. It is deliberately narrow: only
+ * shapes that a false positive is unlikely to produce, because a guard that refuses legitimate
+ * notes is worse than no guard — the model learns to stop recording.
+ *
+ * What it does NOT do, by design:
+ *  - no rewriting (a silently redacted fact is a lie the caller cannot see);
+ *  - no scanning of what is already stored (writes only, never a retroactive sweep);
+ *  - no knowledge-base coverage (`kb_add` ingests user-provided documents and is out of scope);
+ *  - no config/override path (the refusal carries its own remedy: record WHERE the secret lives).
+ *
+ * The refusal message is the interface: it names the shape and tells the caller what to write
+ * instead. The plugin turns a thrown store error into a tool error through its existing `wireErr`
+ * path, so no new field and no new error surface is introduced.
+ */
+export type SecretKind = 'provider-key' | 'private-key' | 'connection-string' | 'card-number' | 'national-id';
+export interface SecretShape {
+    kind: SecretKind;
+    /** Human-readable name of the shape, safe to put in an error (never the matched value). */
+    label: string;
+}
+/**
+ * The guard. Returns the matched SHAPE (never the matched text) or `null`.
+ *
+ * Order is by specificity: a PEM block or a known prefix is a stronger signal than a bare number,
+ * so a fact that carries both is reported as the credential it obviously is.
+ */
+export declare function detectSecretShape(text: string): SecretShape | null;
+/** The refusal the caller sees — names the shape and says what to write instead. */
+export declare function secretRefusalMessage(shape: SecretShape): string;

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

@@ -0,0 +1,74 @@
+/**
+ * P-11 · the deterministic Chinese time-expression parser behind the (default-OFF) time-window leg.
+ *
+ * WHAT THIS IS. One pure function that turns a query's own text into ONE half-open window
+ * `[start, end)` in epoch milliseconds, plus the `rule` that produced it. It has no clock of its
+ * own — `now` is a parameter (default `new Date()`), so a caller can pin it ("pinned_now") and get
+ * bit-identical answers from any machine. No third-party date library, no locale data: only `Date`
+ * and regexes.
+ *
+ * WHY THE LEG NEEDS IT AT ALL. "上个月做了什么" carries its evidence in the TIME EXPRESSION, not in
+ * the words: the fact that answers it reads "完成了支付网关的重构" and shares no query term. No
+ * lexical, entity or semantic leg can see that; the window is the only usable signal.
+ *
+ * PARITY WITH THE BENCHMARK HARNESS. The rules, boundaries and `rule` names mirror
+ * `scripts/spikes/bench-r4-lib.mjs`'s `parseTimeWindow` verbatim (that is the copy the A2 derived
+ * "time" shape and the round-4/round-6 cards already use to pick their windows). The benchmark
+ * harness is NOT modified, so a production/harness disagreement would show up as an unreproducible
+ * measurement — keep the two in step. The ONE intended addition here is Chinese numerals in
+ * `最近N天` ("最近三天"), which the spike's `\d+` cannot express.
+ *
+ * WHAT IT DELIBERATELY DOES NOT PARSE. Quarter words (`上季度`, `第三季度`) and anything else outside
+ * the table below return `undefined` rather than a guess: a wrong window would silently boost the
+ * wrong facts, and "no window" only leaves the other legs exactly as they were.
+ *
+ * @module store/time_window
+ */
+/** Milliseconds in a day. Rolling windows use it the way the spike does (no DST in the zh corpus). */
+export declare const DAY_MS = 86400000;
+/** One parsed window. `end` is EXCLUSIVE. */
+export interface TimeWindow {
+    /** Inclusive start, epoch ms. */
+    start: number;
+    /** Exclusive end, epoch ms. */
+    end: number;
+    /** The spike's rule label (also what the benchmark reports as the query's time shape). */
+    rule: string;
+    /** The literal span that matched, verbatim. */
+    matched: string;
+}
+/** Inclusive local-day bounds, the form the SQL predicate compares `valid_from`'s date prefix with. */
+export interface DayBounds {
+    from: string;
+    to: string;
+}
+/**
+ * Parse an arabic or Chinese cardinal (`3`, `三`, `十`, `十三`, `二十一`) for the `最近N天` window.
+ *
+ * Capped at what a day count can plausibly be: values above 99 are treated as unparseable rather
+ * than silently producing a decade-long window. Returns `undefined` when the text is not a number
+ * this grammar knows, so the caller can fall through to the next rule.
+ */
+export declare function parseCount(text: string): number | undefined;
+/**
+ * The first time window in `text`, or `undefined` when the text carries no expression from the
+ * table. Ordered ABSOLUTE before RELATIVE (the spike's order): a text naming a concrete date must
+ * not be re-read as a relative one.
+ */
+export declare function parseTimeWindow(text: string, now?: Date): TimeWindow | undefined;
+/** Local `YYYY-MM-DD` for an epoch-ms instant (the form `valid_from`'s prefix is compared against). */
+export declare function localDayString(ms: number): string;
+/**
+ * The INCLUSIVE local-day bounds of a window, for a `substr(valid_from,1,10) BETWEEN ? AND ?`
+ * predicate.
+ *
+ * `end` is exclusive in epoch terms, and an event time is stored at day granularity (`2026-09-15`)
+ * or finer; `end - 1ms` therefore names the last DAY the window can contain. That is what makes
+ * `最近三天` include today (`end` is "now", so `end - 1ms` is still today) while `上个月` stops at
+ * the month's last day (`end` is the 1st, so `end - 1ms` is the last day of the previous month)
+ * instead of leaking the 1st of the current one.
+ *
+ * An empty or inverted window yields `from > to`, and the SQL `BETWEEN` then matches nothing —
+ * the honest answer for "最近0天".
+ */
+export declare function windowDayBounds(window: TimeWindow): DayBounds;

package/lib/engine/mem-contract/config.d.ts

@@ -1,13 +1,12 @@
 import { z } from 'zod';
 /**
- * Input window of the SHIPPED models: `Xenova/bge-base-zh-v1.5` (embedder) and
- * `Xenova/bge-reranker-base` (reranker) both read 512 tokens. (The previous default embedder,
- * `Xenova/bge-small-zh-v1.5`, shares the same 512-token window — this constant did NOT move when
- * the embedder changed; only its vector width did, 512 → 768.)
+ * Input window of the SHIPPED model: `Xenova/bge-base-zh-v1.5` reads 512 tokens. (The previous
+ * default embedder, `Xenova/bge-small-zh-v1.5`, shares the same 512-token window — this constant
+ * did NOT move when the embedder changed; only its vector width did, 512 → 768.)
  *
- * Exported because more than one default derives from it: the embedder's fallback window, the
- * reranker's pair budget (retrieval-core), and `knowledge.chunk_size` below. transformers.js
- * truncates past the window SILENTLY, so every derivation has to agree on the number.
+ * Exported because more than one default derives from it: the embedder's fallback window and
+ * `knowledge.chunk_size` below. transformers.js truncates past the window SILENTLY, so every
+ * derivation has to agree on the number.
  */
 export declare const DEFAULT_MODEL_WINDOW_TOKENS = 512;
 /** The merged runtime config shared by memory and knowledge stores. */
@@ -23,14 +22,6 @@ export declare const ConfigSchema: z.ZodObject<{
         auto_download: z.ZodDefault<z.ZodBoolean>;
         auto_migrate: z.ZodDefault<z.ZodBoolean>;
     }, z.core.$strip>>;
-    rerank: z.ZodPrefault<z.ZodObject<{
-        backend: z.ZodDefault<z.ZodString>;
-        local_model: z.ZodDefault<z.ZodString>;
-        max_input_tokens: z.ZodDefault<z.ZodNumber>;
-        mirror: z.ZodDefault<z.ZodString>;
-        cache_dir: z.ZodDefault<z.ZodString>;
-        auto_download: z.ZodDefault<z.ZodBoolean>;
-    }, z.core.$strip>>;
     vectorStore: z.ZodPrefault<z.ZodObject<{
         backend: z.ZodDefault<z.ZodString>;
         auto_thresholds: z.ZodDefault<z.ZodObject<{
@@ -48,6 +39,7 @@ export declare const ConfigSchema: z.ZodObject<{
         min_fts_terms: z.ZodDefault<z.ZodNumber>;
         min_jaccard: z.ZodDefault<z.ZodNumber>;
         leg_cap: z.ZodDefault<z.ZodNumber>;
+        time_window: z.ZodDefault<z.ZodBoolean>;
     }, z.core.$strip>>;
     lifecycle: z.ZodPrefault<z.ZodObject<{
         purge_after_archived_days: z.ZodDefault<z.ZodNumber>;
@@ -120,8 +112,8 @@ export declare const KnowledgeConfigSchema: z.ZodObject<{
     chunk_size: z.ZodDefault<z.ZodNumber>;
     chunk_overlap: z.ZodDefault<z.ZodNumber>;
     source_priority: z.ZodDefault<z.ZodEnum<{
-        none: "none";
         workspace: "workspace";
+        none: "none";
     }>>;
     ingest: z.ZodPrefault<z.ZodObject<{
         local_roots: z.ZodDefault<z.ZodArray<z.ZodString>>;

package/lib/engine/mem-contract/family.d.ts

@@ -4,7 +4,7 @@
  *
  * `@avantf/dsh-plugin-base` (the family's environment framework) installs everything it manages under a
  * single root: `$AVANTF_HOME` when set, else `~/.avantf/env`. `tools` holds external binaries
- * (pandoc), `models` the downloaded embedding/rerank weights in the flat layout the transformers.js
+ * (pandoc), `models` the downloaded embedding weights in the flat layout the transformers.js
  * cache reads. The engine's built-in defaults point HERE, not at the pre-framework
  * `~/.avantf/{tools,models}`: those legacy directories are no longer a fallback anywhere, so a
  * machine that never creates them loses nothing, and no process resolves a path that only missions