@avantf/dsh-mem 0.4.1 → 0.6.0

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 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';
@@ -21,6 +21,16 @@ export type { DetectedContradiction, RememberResult as AddResult } from '../../m
  * until `deferred === 0` instead.
  */
 export declare const ENTITY_SWEEP_BATCH = 2000;
+/**
+ * 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.
+ */
+export declare const DEFAULT_VECTOR_MIGRATION_BATCH = 16;
 /** What one derived-state sweep pass did (see `MemoryStore.reindexEntities`). */
 export interface EntitySweepReport {
     /**
@@ -78,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;
@@ -124,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.
      *
@@ -150,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);
     /**
@@ -161,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
@@ -173,7 +211,23 @@ export declare class MemoryStore {
      * `archive()` evicts and `restore()` re-adds, keeping the invariant.
      */
     private reloadIndex;
-    add(content: string, category?: string, ttlDays?: number): Promise<RememberResult>;
+    /**
+     * Cheapest possible DETECTION of "the embedding space changed under this store": counts of ACTIVE
+     * persisted vectors whose width or recorded space id no longer matches the one this store writes
+     * into. Reads blob LENGTHS only — never decodes — so the `/mem` status surface and the startup
+     * warning can afford it at any corpus size.
+     *
+     * The counts are the same two `VectorsDiagnostic` already separates (`stale` / `space_stale`); this
+     * is the read model those surfaces use instead of the full diagnose pass.
+     */
+    vectorSpaceHealth(): VectorSpaceHealth;
+    /**
+     * {@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.
@@ -192,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;
     /**
@@ -230,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;
@@ -317,7 +381,7 @@ export declare class MemoryStore {
      */
     private classifyVectors;
     /**
-     * Repair the semantic read model:
+     * 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
@@ -325,12 +389,46 @@ export declare class MemoryStore {
      *      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). Deliberately here and not at open: this is
-     *      the only path that re-encodes the whole table, so it is an explicit, counted action.
+     *      adoption of a store predating the space id).
+     *
+     * `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.
+     */
+    private repairVectors;
+    /**
+     * 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`).
      */
     vectorsFix(dryRun?: boolean): Promise<VectorsFixReport>;
+    /**
+     * 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.
+     */
+    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
@@ -420,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
@@ -499,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;
     /**
@@ -515,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. */
@@ -21,14 +20,7 @@ export declare const ConfigSchema: z.ZodObject<{
         mirror: z.ZodDefault<z.ZodString>;
         cache_dir: z.ZodDefault<z.ZodString>;
         auto_download: 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>;
+        auto_migrate: z.ZodDefault<z.ZodBoolean>;
     }, z.core.$strip>>;
     vectorStore: z.ZodPrefault<z.ZodObject<{
         backend: z.ZodDefault<z.ZodString>;
@@ -47,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>;
@@ -119,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

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

@@ -54,12 +54,18 @@ export declare const RememberUnion: z.ZodDiscriminatedUnion<[z.ZodObject<{
     content: z.ZodString;
     category: z.ZodOptional<z.ZodString>;
     ttl_days: z.ZodOptional<z.ZodNumber>;
+    source_ref: z.ZodOptional<z.ZodString>;
+    event_date: z.ZodOptional<z.ZodString>;
+    valid_until: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>, z.ZodObject<{
     action: z.ZodLiteral<"update">;
     fact_id: z.ZodNumber;
     content: z.ZodString;
     category: z.ZodOptional<z.ZodString>;
     ttl_days: z.ZodOptional<z.ZodNumber>;
+    source_ref: z.ZodOptional<z.ZodString>;
+    event_date: z.ZodOptional<z.ZodString>;
+    valid_until: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>, z.ZodObject<{
     action: z.ZodLiteral<"remove">;
     fact_id: z.ZodNumber;
@@ -77,12 +83,14 @@ export declare const RecallUnion: z.ZodDiscriminatedUnion<[z.ZodObject<{
     action: z.ZodLiteral<"search">;
     query: z.ZodString;
     category: z.ZodOptional<z.ZodString>;
+    source: z.ZodOptional<z.ZodString>;
     limit: z.ZodOptional<z.ZodNumber>;
     max_tokens: z.ZodOptional<z.ZodNumber>;
     floors: z.ZodOptional<z.ZodEnum<{
         strict: "strict";
         loose: "loose";
     }>>;
+    include_scores: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>, z.ZodObject<{
     action: z.ZodLiteral<"ask">;
     subj: z.ZodOptional<z.ZodString>;
@@ -127,6 +135,7 @@ export declare const AdminUnion: z.ZodDiscriminatedUnion<[z.ZodObject<{
         active: "active";
         archived: "archived";
     }>>;
+    source: z.ZodOptional<z.ZodString>;
     limit: z.ZodOptional<z.ZodNumber>;
     offset: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>, z.ZodObject<{
@@ -220,6 +229,7 @@ export declare const QueryUnion: z.ZodObject<{
         strict: "strict";
         loose: "loose";
     }>>;
+    include_scores: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>;
 export type QueryRequest = z.infer<typeof QueryUnion>;
 /** Transport-agnostic tool spec: name / key / description / zod input. */