@avantf/dsh-mem 0.4.2 → 0.6.1

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

@@ -1,5 +1,7 @@
-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 VectorsFixStoreReport } from '../../mem-contract/index.js';
+import type { SemanticBackend, VectorStore } from '../../mem-retrieval/index.js';
+import { ENTITY_SWEEP_BATCH, type EntitySweepReport } from './entity_sweep.js';
+import { DEFAULT_VECTOR_MIGRATION_BATCH, type VectorRepairTarget } from './vector_repair.js';
 import type { Db } from '../db/conn.js';
 import { type LexicalProbe } from './lexical.js';
 import { type FloorLeg } from './floors.js';
@@ -15,35 +17,22 @@ export type { DetectedContradiction, RememberResult as AddResult } from '../../m
 /**
  * Facts one derived-state sweep pass may rebuild (`reindexEntities`'s default budget).
  *
- * Bounds MEMORY, not only mission: the pass selects `content` for every row it takes, so an
- * "unbounded" pass (the CLI used to ask for `Number.MAX_SAFE_INTEGER`) builds an array of every
- * stale fact's text before rebuilding the first one. Callers that want the corpus drained loop
- * until `deferred === 0` instead.
+ * Re-exported from the shared sweep (`store/entity_sweep.ts`), which owns the loop and therefore the
+ * default: the public name has to keep working for the CLI (`cli/src/index.ts` passes it explicitly)
+ * and the plugin's heartbeat, but a second literal here would be a second answer to "how big is one
+ * pass".
  */
-export declare const ENTITY_SWEEP_BATCH = 2000;
+export { ENTITY_SWEEP_BATCH };
 /**
  * Rows one background vector-space migration slice may drop + re-encode.
  *
- * Small on purpose: the point of batching is that a query arriving mid-migration waits for at most
- * one ONNX forward pass batch, not for a whole corpus. At ~30 ms per bge-base-zh encode a batch of 16
- * is well under a second of contested model time, and the event loop is yielded between batches
- * (`yieldToEventLoop`). The value is a default, not a promise — `migrateVectorsBatch(batchSize)` takes
- * whatever the caller needs.
+ * Re-exported from the shared repair flow (`store/vector_repair.ts`), which owns the loop and
+ * therefore the default: the public name has to keep working for callers that pass it explicitly,
+ * but a second literal here would be a second answer to "how big is one slice".
  */
-export declare const DEFAULT_VECTOR_MIGRATION_BATCH = 16;
-/** What one derived-state sweep pass did (see `MemoryStore.reindexEntities`). */
-export interface EntitySweepReport {
-    /**
-     * Facts this pass RE-EXTRACTED, i.e. its batch size when it filled it. Counts rows VISITED and
-     * re-stamped, not rows whose extraction output differs — the stamp is what makes the corpus
-     * current, so a row re-extracted to the same names still counts (and is not rebuilt again).
-     */
-    rebuilt: number;
-    /** Facts still written by older rules after this pass. */
-    deferred: number;
-    /** Another pass was already running, so this one did nothing (`deferred` is still current). */
-    skipped: boolean;
-}
+export { DEFAULT_VECTOR_MIGRATION_BATCH };
+/** What one derived-state sweep pass did — re-exported from the shared loop (`store/entity_sweep.ts`). */
+export type { EntitySweepReport };
 /** What one bounded conflict-drain pass did (see `MemoryStore.drainConflicts`). */
 export interface ConflictDrainReport {
     /** Pairs newly logged by this pass. */
@@ -88,6 +77,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 +130,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.
      *
@@ -153,14 +166,20 @@ export declare class MemoryStore {
      * and building MATCH expressions for the wrong one is silent zero recall (see `db/tokenizer.ts`).
      */
     private readonly ftsTokenizer;
-    /** In-flight guard for `reindexEntities` (see there: the periodic callers can overlap). */
-    private entitySweepInFlight;
+    /**
+     * Identity object for the shared entity sweep's in-flight guard (`store/entity_sweep.ts`).
+     *
+     * The guard itself lives in that module; this is only the per-store identity it keys on. It keeps
+     * the rule where the loop is (the periodic callers can overlap), without a mutable field that two
+     * stores would each have to remember to hold.
+     */
+    private readonly entitySweepGuard;
     /**
      * Where the next conflict drain resumes (see `checkContradictions`). A scheduling cursor, not
      * 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,16 +190,26 @@ export declare class MemoryStore {
     trustTick(opts?: {
         budget?: number | null;
     }): TickResult;
-    /** Identity of the vector space this store currently writes into (`vectorSpaceId`). */
-    private vectorSpace;
     /**
-     * Rebuild the in-memory vstore from persisted `facts.semantic_vector` BLOBs.
-     * Without this the semantic path is silently empty after every process restart
-     * (the DB is the authoritative vector store; the vstore is a derived read model).
+     * 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, and say loudly what
+     * belongs to another vector space.
+     *
+     * Without this the semantic path is silently empty after every process restart (the DB is the
+     * authoritative vector store; the vstore is a derived read model). Only ACTIVE facts are indexed:
+     * archived facts are filtered out of every retrieval path anyway, so loading them would only grow
+     * the index forever — `archive()` evicts and `restore()` re-adds, keeping the invariant.
      *
-     * Only ACTIVE facts are indexed: archived facts are filtered out of every
-     * retrieval path anyway, so loading them would only grow the index forever.
-     * `archive()` evicts and `restore()` re-adds, keeping the invariant.
+     * The reload, the `{ stale, space_stale, legacy }` count and the warning are the SHARED open-time
+     * step (`store/vector_repair.ts`); this store's half is the row read. A dim-valid vector from
+     * another space is still RANKED (the reload cannot tell the difference), so a silent model swap
+     * would mix two spaces in one index — acting on it is the manual fix's job for the operator path
+     * and the bounded background migration's for the automatic one.
      */
     private reloadIndex;
     /**
@@ -193,7 +222,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.
@@ -210,9 +245,17 @@ export declare class MemoryStore {
      * stamped the marker anyway — a permanent, silent exemption).
      */
     private detectContradictions;
+    /**
+     * This store's half of the shared encode-and-persist flow (`store/vector_repair.ts`): the backend
+     * call, the live index and the single-row write. The write records the VECTOR SPACE, not just the
+     * backend name — a same-width model swap is otherwise indistinguishable from "already encoded"
+     * (DESIGN §20) — and `setSemanticVector` re-queues the fact for the conflict check.
+     */
+    private vectorWriteTarget;
+    private warnIndexFailure;
     /** 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 +293,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;
@@ -337,54 +390,60 @@ export declare class MemoryStore {
      */
     private classifyVectors;
     /**
-     * Repair the semantic read model, in ONE bounded slice or in full:
-     *  (a) reload persisted, dim-valid vectors missing from the live index
-     *      (restart / index loss — needs no model),
-     *  (b) drop persisted vectors whose dim no longer matches `semantic.dim` so a
-     *      re-encode can replace them (never `add()` a stale vector — the store
-     *      throws on dim mismatch),
-     *  (c) encode active facts that have no vector yet (needs the semantic backend),
-     *  (d) re-encode vectors written in ANOTHER vector space (a model swap, or the one-time
-     *      adoption of a store predating the space id).
+     * This store's half of the shared repair flow (`store/vector_repair.ts`): the primitives the flow
+     * steps. The flow itself — batch size, event-loop yield, stop / resume / no-progress rules,
+     * `semantic.auto_migrate`, the dry-run split and the drop-before-encode order — lives there once,
+     * for both stores.
+     */
+    vectorRepairTarget(): VectorRepairTarget;
+    /**
+     * {@link classifyVectors} reduced to what the repair flow steps on: the counts, the ids to drop
+     * (bounded by `limit`) and the decoded vectors that can go back into a lost live index.
+     */
+    private classifyRepairVectors;
+    /** Put usable persisted vectors missing from the live index back into it (no model needed). */
+    private reindexUsableVectors;
+    /**
+     * Unusable bytes (dim mismatch) and foreign-space vectors both have to go before a re-encode can
+     * pick them up, and for the same reason: `add()` would keep ranking them otherwise. Only the slice
+     * the flow is about to re-encode is passed in, so a process that dies mid-migration leaves at most
+     * one batch vector-less — those rows are exactly the `missing` rows the next run resumes on.
      *
-     * `limit` is what makes the SAME logic usable as a background migration: at most that many rows are
-     * dropped and at most that many are re-encoded, so one call is a bounded unit of work the caller can
-     * yield between. `vectorsFix` passes no limit (the explicit operator action drains everything);
-     * `migrateVectorsBatch` passes the migration's batch size.
+     * `clearVectors` re-queues each fact for the conflict check (`conflict_checked = 0`): the vector
+     * the embedding leg was checked against is gone, so the check has to run again.
      */
-    private repairVectors;
+    private dropRepairVectors;
+    /**
+     * Encode the ACTIVE facts that still have no vector in this space (needs the semantic backend).
+     *
+     * Every row lands through `setSemanticVector`, which re-queues the fact for the conflict check —
+     * the same rule as {@link dropRepairVectors}: a fact whose vector the leg could not see when it
+     * ran has not been checked.
+     */
+    private reencodeMissingVectors;
     /**
      * The explicit, unbounded repair behind `mem_admin vectors_fix` / `avantf-mem vectors --fix`.
      * `dry_run` previews every count without writing — and without loading the model, which is why
-     * the preview also reports `would_warm` (see the contract's `VectorsFixReport`).
+     * the preview also reports `would_warm` (see the contract's `VectorsFixStoreReport`).
      */
-    vectorsFix(dryRun?: boolean): Promise<VectorsFixReport>;
+    vectorsFix(dryRun?: boolean): Promise<VectorsFixStoreReport>;
     /**
      * ONE bounded slice of the vector-space migration: at most `batchSize` rows are dropped and
      * re-encoded, so the caller keeps control of the event loop between slices. This is the unit the
      * background migration ({@link migrateVectors}) and its tests drive.
-     *
-     * Resumability is a property of the DATABASE, not of this process: every slice re-derives what is
-     * stale from the persisted width/space, so a restart simply continues where the last slice stopped.
      */
     migrateVectorsBatch(batchSize?: number): Promise<VectorMigrationProgress>;
     /**
      * Drive the bounded background migration until the store is current, the model is unavailable, or
-     * `shouldStop()` turns true (plugin unmount / process shutdown). A batch FAILURE never rejects: it is
-     * logged and reported as `remaining > 0`, which is what makes the next heartbeat a retry (the caller
-     * still owns the outer catch for a closed database, e.g. a shutdown racing the first read). Never
-     * blocks the event loop for longer than one batch.
-     *
-     * Honours `semantic.auto_migrate` (default on) — the switch exists so a host that must not spend CPU
-     * on background re-encoding can leave the loud warning and the manual entry as the only path.
+     * `shouldStop()` turns true (plugin unmount / process shutdown). The loop, the `semantic.auto_migrate`
+     * switch, the no-progress rule and the store-named logging all live in the shared flow
+     * (`store/vector_repair.ts`); this is the one-store entry callers (and its tests) already use.
      */
     migrateVectors(opts?: {
         batchSize?: number;
         shouldStop?: () => boolean;
         onProgress?: (progress: VectorMigrationOutcome) => void;
     }): Promise<VectorMigrationOutcome>;
-    /** Active rows the semantic leg still cannot use (old width, old space, or no vector at all). */
-    private migrationRemaining;
     /**
      * One lifecycle pass, owned by the store so the DB writes and the live-index
      * invariant (ACTIVE vectors only) are maintained in ONE place — the runtime no
@@ -422,14 +481,10 @@ export declare class MemoryStore {
      * loop until `deferred === 0` — `budget` bounds MEMORY as well as mission, since the pass reads
      * every selected row's `content` before rebuilding the first one.
      *
-     * The in-flight guard is here rather than at the callers because the callers CAN overlap: the
-     * plugin's heartbeat and `maintenance` are both periodic, and `staleEntityRows` is ORDERED, so
-     * two concurrent passes would select the same rows and re-tag them twice. Overlap is not
-     * corruption (each fact is stamped in its own transaction) — it is duplicated mission in a
-     * single-threaded process. A pass that finds one running reports `skipped` and does nothing.
-     *
-     * `budget` is clamped at 0: SQLite reads a negative LIMIT as "no limit" (`LIMIT -1`), so a
-     * caller asking for "-1 rows" would silently get the whole corpus — the opposite of bounded.
+     * The loop, the budget clamp, the in-flight guard and the `{rebuilt, deferred, skipped}` report all
+     * live in `store/entity_sweep.ts` now — this method is memory's adapter for it, so knowledge's
+     * entity leg and this one cannot drift apart again. What stays HERE is the domain half: the stale
+     * selection (`facts.staleEntityRows`, ACTIVE facts only) and the per-fact write below.
      */
     reindexEntities(budget?: number): Promise<EntitySweepReport>;
     /**
@@ -439,8 +494,6 @@ export declare class MemoryStore {
      * `ContradictionsDao.resolveForFact`).
      */
     private retireConflicts;
-    /** Drop vectors of archived/purged facts from the live index (batched). */
-    private evictVectors;
     /**
      * Entities that co-occur with `entity` across ACTIVE facts, ranked by occurrence
      * count. Archived (incl. superseded) facts are excluded — their entities are not
@@ -474,20 +527,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
@@ -525,7 +590,10 @@ export declare class MemoryStore {
      * Semantic leg. `queryVector` short-circuits the encode when the caller already
      * encoded this exact query (the cross-store router does, for both stores at once);
      * `onVector` publishes the vector this leg actually used, so the relaxed retry pass can reuse it
-     * instead of re-encoding (performance review §7.7 / P8).
+     * instead of re-encoding (performance review §7.7 / P8). The flow is shared
+     * (`store/legs.ts#semanticLeg`); the only memory-specific piece is the filter — the vstore has no
+     * notion of status/category/source, so candidates go through the DB and archived/purged facts,
+     * other categories and other sources never leak into the leg.
      */
     private semanticPath;
     /**
@@ -553,8 +621,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 +644,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;