@avantf/dsh-mem 0.8.1 → 0.10.0

package/lib/engine/mem/lifecycle/maintenance.d.ts

@@ -4,8 +4,10 @@
  *
  * Surface stability (D10): the original report keys are all preserved
  * (`decayed / archived_ttl / archived_age / purged / purged_ids / archived_ids`)
- * and the new detail is purely additive. `archived_age` now means "non-TTL
- * automatic archival" = `forgot + idle`.
+ * and the new detail is purely additive. `archived_ttl` / `archived_idle` are kept as
+ * CONSTANT 0 and marked `@deprecated`: TTL and idle archival are gone (v2), but a report key
+ * is a surface scripts read — deleting it would break them for nothing. `archived_age` now
+ * means "the automatic archival that still exists" = `forgot`.
  *
  * The `maintenance` action forces a FULL pass (no settle budget); the automatic
  * startup/heartbeat passes use `tick_max_facts`.
@@ -15,8 +17,9 @@ import type { Db } from '../db/conn.js';
 export interface MaintenanceResult {
     /** Rows whose trust was materialized by the settle sweep (see tick.ts). */
     decayed: number;
+    /** @deprecated TTL archival is gone (v2); always 0, kept so existing report readers keep working. */
     archived_ttl: number;
-    /** Non-TTL automatic archival = `forgot + idle` (kept name, widened meaning). */
+    /** The automatic archival this pass performed = `forgot` (name kept, D10). */
     archived_age: number;
     purged: number;
     /** Fact ids physically deleted by the purge — callers evict their vectors from the live index. */
@@ -26,10 +29,11 @@ export interface MaintenanceResult {
     settled: number;
     clock: number;
     archived_forgot: number;
+    /** @deprecated Idle archival is gone (v2); always 0, kept for the same reason as `archived_ttl`. */
     archived_idle: number;
     /** Rows still pending settle because the budget ran out (always 0 for a forced pass). */
     skipped: number;
-    /** Rows still due for TTL/forgot/idle because the budget ran out (0 for a forced pass). */
+    /** Rows still due for forgot because the budget ran out (0 for a forced pass). */
     archived_deferred: number;
     /** Rows still due for purge when the budget ran out (0 for a forced pass). */
     purged_deferred: number;

package/lib/engine/mem/lifecycle/tick.d.ts

@@ -1,16 +1,19 @@
 /**
- * One trust/lifecycle tick (spec docs/TRUST_MODEL.md §4) — five ordered statements:
+ * One trust/lifecycle tick (spec docs/TRUST_MODEL.md §4) — three ordered statements:
  *
  *   ① settle   — materialize decay for every row whose ACTIVE DAY changed
- *   ② TTL      — calendar expiry (explicit instruction; pinned is not exempt)
- *   ③ forgot   — trust ≤ forget_threshold after settling (pinned exempt)
- *   ④ idle     — calendar fallback: unused for `idle_calendar_days`
- *   ⑤ purge    — physical delete of archived rows past the window
+ *   ② forgot   — trust ≤ forget_threshold after settling (pinned exempt)
+ *   ③ purge    — physical delete of archived rows past the window
+ *
+ * The calendar clocks are GONE (v2): there is no TTL step and no idle fallback, so a fact's
+ * lifetime is decided by the active-day curve alone and "expired" is expressed by an explicit
+ * `update` / `archive` (docs/TRUST_MODEL.md §3.4). `pinned` is therefore never archived by an
+ * automatic pass.
  *
  * EVERY step is budgeted by the same `tick_max_facts`, not just ①.
  *
  * It used to say "only ① is budgeted; ②③④⑤ only ever touch critical rows", and that reading is
- * wrong in the direction that matters: ②③④⑤ each run inside the tick's ONE `IMMEDIATE` transaction,
+ * wrong in the direction that matters: every step runs inside the tick's ONE `IMMEDIATE` transaction,
  * which holds the write lock for its whole duration, so an unbounded archive or purge pass over a
  * large corpus blocks every other process (and the startup path, which is where the tick runs) for
  * as long as it takes. Bounding each step is what keeps that lock short; `archived_deferred` and
@@ -24,17 +27,15 @@ export interface TickResult {
     clock: number;
     /** Rows materialized by ① (equals "trust actually changed" — see the note in runTrustTick). */
     settled: number;
-    archived_ttl: number;
     archived_forgot: number;
-    archived_idle: number;
     purged: number;
     purged_ids: number[];
     archived_ids: number[];
     /** Rows still awaiting ① when the budget ran out (0 for a full pass). */
     skipped: number;
-    /** Rows still due for ②③④ when the budget ran out (0 when the pass finished them). */
+    /** Rows still due for ② when the budget ran out (0 when the pass finished them). */
     archived_deferred: number;
-    /** Rows still due for ⑤ when the budget ran out (0 when the pass finished them). */
+    /** Rows still due for ③ when the budget ran out (0 when the pass finished them). */
     purged_deferred: number;
 }
 export declare function runTrustTick(db: Db, cfg: Config, opts: {

package/lib/engine/mem/lifecycle/trust.d.ts

@@ -3,13 +3,22 @@
  * (`clock` / `nowMs` are always injected, so every rule is unit-testable).
  *
  * Spec: docs/TRUST_MODEL.md §2. Key rules encoded here:
- *  - `eff = pinned ? 1 : clamp(trust − step × (clock − settle_clock), 0, 1)` (§2.2)
+ *  - `eff = pinned ? 1 : clamp(T(clock − settle_clock), 0, 1)` (§2.2), where `T(days)` is the decay
+ *    curve of `contract/src/trust_curve.ts` — the ONE implementation of the formula
  *  - recall only ever RAISES trust (`max(eff, …)`, R2) and never pins (D11)
  *  - zero-gain recalls neither consume quota nor stamp `last_reinforced_at` (R10)
- *  - explicit feedback can pin (snap to 1.0) or forget immediately (§2.4)
+ *  - permanent is set ONLY by an explicit `pin`; no write path moves a fact across that line (§2.4)
  *  - `enabled=false` degrades `eff()` to the stored value (D12)
  */
 import type { Config } from '../../mem-contract/index.js';
+import { formatUtcTs, parseUtcTs, type TrustCurve } from '../../mem-contract/index.js';
+/**
+ * The UTC stamp parse/render pair is `@avantf/mem-contract/time` — ONE implementation, shared with
+ * the two display faces (`formatOffsetIso` for the model, `formatLocalHuman` for the UI), so the
+ * "a zone-less stamp means UTC" rule cannot drift between the trust math and what a reader sees.
+ * Re-exported here because this module is where the trust code (and its specs) have always found it.
+ */
+export { formatUtcTs, parseUtcTs };
 export declare const DAY_MS = 86400000;
 /** Guard for "did the number actually move" comparisons. */
 export declare const EPSILON = 1e-9;
@@ -24,20 +33,9 @@ export interface TrustRow {
     status: string;
 }
 export declare function clamp01(v: number): number;
+/** The curve of one `trust` section — the single mapping from config keys to the math. */
+export declare function trustCurveOf(cfg: TrustConfig): TrustCurve;
 export declare function isPinned(row: Pick<TrustRow, 'pinned'>): boolean;
-/**
- * `'YYYY-MM-DD HH:MM:SS'` (SQLite UTC) or ISO → epoch ms; null/garbage → null.
- *
- * A stamp with NO zone designator is read as UTC, not as local time. `Date.parse` treats a zone-less
- * ISO string as LOCAL, and everything in this store is written in UTC (`CURRENT_TIMESTAMP`, and
- * {@link formatUtcTs}), so handing one over as-is would shift every quota window and every decay
- * measurement by the host's UTC offset — a fact reinforced at 23:00 UTC+8 would look reinforced 8
- * hours earlier, and the 24h cap would open or close at the wrong moment. An explicit `Z` or
- * `±HH:MM` is left alone.
- */
-export declare function parseUtcTs(ts: string | null | undefined): number | null;
-/** Epoch ms → `'YYYY-MM-DD HH:MM:SS'` (the SQLite `CURRENT_TIMESTAMP` shape, UTC). */
-export declare function formatUtcTs(ms: number): string;
 /** eff(f) — the trust a caller should act on right now (spec §2.2). */
 export declare function effectiveTrust(row: TrustRow, clock: number, cfg: TrustConfig, enabled?: boolean): number;
 /**
@@ -48,8 +46,9 @@ export declare function effectiveTrust(row: TrustRow, clock: number, cfg: TrustC
  */
 export declare function displayTrust(row: TrustRow, clock: number, cfg: TrustConfig, enabled?: boolean): number;
 /**
- * Remaining active days: `eff / step`. `null` for pinned rows, non-active rows and
- * when trust is disabled — the contract's `remaining_days` (spec §6 / R11).
+ * Remaining active days: the inverse of the curve at the current eff (`daysToZero`).
+ * `null` for pinned rows, non-active rows and when trust is disabled — the contract's
+ * `remaining_days` (spec §6 / R11).
  */
 export declare function remainingDays(row: TrustRow, clock: number, cfg: TrustConfig, enabled?: boolean): number | null;
 /** Everything a recall write needs to persist (spec §2.3). */
@@ -66,25 +65,13 @@ export interface RecallOutcome {
  * Apply one recall to a fact: settle, then grant a bonus inside the daily quota.
  * Returns `next === settled` when the quota is exhausted, the ceiling is reached,
  * the fact is pinned, or the gain would be zero (R2/R10/D11).
- */
-export declare function grantRecallBonus(row: TrustRow, clock: number, nowMs: number, cfg: TrustConfig, enabled?: boolean): RecallOutcome;
-/** Everything a feedback write needs to persist (spec §2.4). */
-interface FeedbackOutcome {
-    settled: number;
-    next: number;
-    pin: boolean;
-    forget: boolean;
-    /** true when the row was left untouched (pinned / archived). */
-    untouched: boolean;
-    bonusCount: number;
-    windowAt: string;
-}
-/**
- * Apply one explicit `helpful` (+1) / `unhelpful` (-1) step.
  *
- * Pinned and archived rows are untouched (R7): only `helpful_count` changes for
- * them, so a pinned fact can never end up storing 0.95 while displaying 1.0.
- * When `feedback_daily_cap > 0` feedback shares the per-fact 24h window counter.
+ * The gain is SEGMENTED at the frozen anchor `BASE_TRUST` (D20):
+ *  - strictly below the base: `min(BASE_TRUST, T + recall_gain_below_base)`, so the shipped
+ *    `recall_gain_below_base: 0.1` takes 0.05 → 0.5 in five recalls and never past the base;
+ *  - AT OR ABOVE the base: `recall_gain_above_base × marginal_decay^count`, capped at the ceiling
+ *    INVERTED from `max_retention_days` (there is no `recall_ceiling` key any more, D16). The
+ *    boundary is strictly `<` on purpose: a fact sitting exactly on the base (a fresh one, on the
+ *    first recall after it has finished settling) takes the above-base branch and starts climbing.
  */
-export declare function applyFeedbackDelta(row: TrustRow, clock: number, delta: number, nowMs: number, cfg: TrustConfig, enabled?: boolean): FeedbackOutcome;
-export {};
+export declare function grantRecallBonus(row: TrustRow, clock: number, nowMs: number, cfg: TrustConfig, enabled?: boolean): RecallOutcome;

package/lib/engine/mem/modelBootstrap.d.ts

@@ -1,3 +1,4 @@
+import { type JiebaStatus } from './entities/extract.js';
 import type { AvantfRuntime } from './runtime.js';
 /** The statuses the base's verdict can carry (kept structural — see the note above). */
 export type DshCompatStatus = 'ok' | 'version-mismatch' | 'version-unknown' | 'probe-skipped' | 'probe-failed';
@@ -72,6 +73,34 @@ export declare function warmModels(rt: AvantfRuntime, options?: WarmOptions, rep
  * @returns how long the idle gate waited (ms), or `0` when it was not requested.
  */
 export declare function awaitStartupGate(options?: WarmOptions): Promise<number>;
+/**
+ * The tokenizer states this module reports — one line per observation, in the order they happen.
+ *
+ * Process-wide on purpose, because the thing being described is: `entities/extract.ts` memoizes the
+ * load per process, and a provisioned module root that arrives later (`useTokenizerModuleDir`) can
+ * turn the same memo from "unavailable" into "ready". Without the previous verdict a slow repair
+ * prints a bare contradiction (`unavailable in 1ms` … `ready in 623ms`); with it the second line
+ * says it is a recovery, and the first one knows enough to say it was not final.
+ */
+export type TokenizerVerdict = 'unknown' | 'ready' | 'degraded';
+/** One line to log, and the verdict it leaves behind. */
+export interface TokenizerReport {
+    level: 'info' | 'warn';
+    message: string;
+    next: TokenizerVerdict;
+}
+/**
+ * The line one tokenizer observation deserves.
+ *
+ * `previous` is what makes the pair readable: a `ready` after a `degraded` is a RECOVERY (the
+ * earlier probe ran before a loadable copy existed — the provisioned root had not been handed over,
+ * or the package was not installed yet), not a change of story. A `degraded` line never claims more
+ * than it knows: it names the reason and the two ways to fix it, and says that a loadable copy
+ * arriving later is picked up automatically.
+ *
+ * Exported for the test that pins those transitions; it has no side effects.
+ */
+export declare function tokenizerReport(status: JiebaStatus, elapsedMs: number, previous: TokenizerVerdict): TokenizerReport;
 /**
  * Non-blocking embedding warm, for a caller that knows the model files are already on disk.
  *

package/lib/engine/mem/runtime.d.ts

@@ -123,11 +123,10 @@ export type RecallHitsResult = StoreResult<MemoryStore, 'searchMemory'>;
 /** The payload of `mem_recall.titles`: an exact page or a fuzzy shortlist of title candidates. */
 export type RecallTitlesResult = StoreResult<MemoryStore, 'titles'>;
 /**
- * `remember` dispatches to five store operations whose RESULTS differ: `add`/`update` return the
- * written fact, `remove` a flag, the feedback actions the new counter (or `null`). One plain
- * signature would either say `unknown` — leaving every caller to invent a cast, which is how a
- * caller ends up reading a field that does not exist — or a union that forces every caller to
- * narrow first. The callable type says what each ACTION returns.
+ * `remember` dispatches to three store operations whose RESULTS differ: `add`/`update` return the
+ * written fact, `remove` a flag. One plain signature would either say `unknown` — leaving every
+ * caller to invent a cast, which is how a caller ends up reading a field that does not exist — or a
+ * union that forces every caller to narrow first. The callable type says what each ACTION returns.
  */
 export type RememberDispatch = {
     (req: Extract<RememberRequest, {
@@ -139,9 +138,6 @@ export type RememberDispatch = {
     (req: Extract<RememberRequest, {
         action: 'remove';
     }>): Promise<StoreResult<MemoryStore, 'remove'>>;
-    (req: Extract<RememberRequest, {
-        action: 'helpful' | 'unhelpful';
-    }>): Promise<StoreResult<MemoryStore, 'helpful'>>;
     (req: RememberRequest, rules?: RememberWriteRules): Promise<unknown>;
 };
 /**

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

@@ -4,13 +4,15 @@
  *
  * RESTORE IS NOT IMPORT. `import` / `merge` (see `facts_io.ts`) are CONTENT-IDENTITY UNIONS: new
  * rows get new ids, only ACTIVE facts travel, and every value the document carries beyond
- * kind/ttl/sources/validity is counted as dropped. Restore is the opposite promise — "put this
- * library back exactly as it was" — which is only answerable if the target is EMPTY:
+ * kind/sources/event time is counted as dropped (the retired `ttl_days` / `valid_to` are ignored).
+ * Restore is the opposite promise — "put this library back exactly as it was" — which is only
+ * answerable if the target is EMPTY:
  *
  *   - `facts` is written DIRECTLY, one transaction, keeping `fact_id`, status, timestamps,
- *     `trust_score`, `settle_clock`, counters, pin state, TTL, validity, the supersedes pointer and
- *     the mirror bookkeeping. A non-empty target is REFUSED (never merged into), because "restore"
- *     that silently unions two histories is a different, unreviewable operation.
+ *     `trust_score`, `settle_clock`, counters, pin state, TTL (format only), event time, the
+ *     supersedes pointer and the mirror bookkeeping. A non-empty target is REFUSED (never merged
+ *     into), because "restore" that silently unions two histories is a different, unreviewable
+ *     operation.
  *   - Rows are inserted in `source_id` ASCENDING order, so the row a `supersedes` pointer names
  *     already exists when the pointer is written. v1 documents carry the same pointer as
  *     `supersedes_source_id`, so both versions resolve identically.
@@ -64,7 +66,7 @@ export declare const RESTORE_VECTOR_HINT: string;
  * rather than trust). A field counts as missing when the document does not carry the key at all —
  * `null` is a value the document states ("unknown"), not an absence.
  */
-export declare const RESTORE_METADATA_FIELDS: readonly ["kind", "title", "created_at", "updated_at", "trust_score", "pinned", "pinned_at", "assert_count", "helpful_count", "last_reinforced_at", "ttl_days", "valid_from", "valid_to", "supersedes_source_id", "archive", "sources", "settle_clock", "bonus_count", "bonus_window_at", "retrieval_count", "last_retrieved_at", "mirror_source", "mirror_target", "entities_version", "conflict_checked", "relations"];
+export declare const RESTORE_METADATA_FIELDS: readonly ["kind", "title", "created_at", "updated_at", "trust_score", "pinned", "pinned_at", "assert_count", "helpful_count", "last_reinforced_at", "ttl_days", "valid_from", "supersedes_source_id", "archive", "sources", "settle_clock", "bonus_count", "bonus_window_at", "retrieval_count", "last_retrieved_at", "mirror_source", "mirror_target", "entities_version", "conflict_checked", "relations"];
 export type RestoreMetadataField = (typeof RESTORE_METADATA_FIELDS)[number];
 /** Per-field count of facts whose document did not carry that field. */
 export type RestoreMetadataMissing = Record<RestoreMetadataField, number>;

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

@@ -1,6 +1,6 @@
 /**
- * The memory adapter for the shared `@avantf/graph-recall` port
- * (docs/GRAPH_RECALL_LIBRARY.md §6, Phase 3b).
+ * The memory adapter for the shared `@avantf/graph-recall` port (Phase 3b). The port — and the
+ * obligations an adapter must honour — is documented in that package's README.
  *
  * WHY THIS FILE EXISTS. The library owns the traversal algorithms (one hop, reverse, two hops, AND,
  * neighbours) and knows nothing about SQLite; memory owns the storage and therefore must supply a

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

@@ -104,7 +104,13 @@ export interface SearchInput {
      * verify it, so it must come from the same backend.
      */
     queryVector?: Float32Array;
-    /** Per-call output token budget; `0` = unlimited, omitted = `retriever.max_output_tokens`. */
+    /**
+     * Per-call output token budget; `0` = unlimited, omitted = `retriever.max_output_tokens`.
+     *
+     * A pure time recall (no `query`) is the one exception: omitting it there means NO budget at all.
+     * That page is already bounded by its own `limit` (50 by default), so a budget on top would only
+     * rewrite the text of rows the caller asked to see (see `timePage`).
+     */
     maxTokens?: number;
     /**
      * Relevance-floor profile for this query. Omitted = the default policy: the configured (strict)
@@ -158,17 +164,15 @@ export interface SearchInput {
 /**
  * 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.
+ * Both 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
+ * or an event time.
  */
 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;
     /**
      * The journal title (JOURNAL_TITLE_SEARCH §2.2/§11.1). `undefined` = not given, `null` = "no
      * title", a string = the (already normalized) title. On a revision an omitted title INHERITS the
@@ -242,7 +246,10 @@ export interface TitleInput {
 export interface MemorySearchInput extends Omit<SearchInput, 'query'> {
     /** The literal query. Omitted = a pure time window (then `time` is required). */
     query?: string;
-    /** The exact page's first row (default 0). Only read when the literal pass matches. */
+    /**
+     * The page's first row (default 0). Read by the exact/facts passes and by the pure time window,
+     * where it walks the window one page at a time (see `timePage`).
+     */
     offset?: number;
 }
 export declare class MemoryStore {
@@ -331,7 +338,7 @@ export declare class MemoryStore {
      * and every existing assertion on it — is unchanged; only the warning's wording uses it.
      */
     private vectorSpaceCounts;
-    add(content: string, kind?: MemoryKind, ttlDays?: number, opts?: FactWriteOptions): Promise<RememberResult>;
+    add(content: string, kind?: MemoryKind, 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.
@@ -358,24 +365,16 @@ export declare class MemoryStore {
     private warnIndexFailure;
     /** Best-effort semantic indexing: encode the fact and add it to the vstore. */
     private maybeIndexSemantic;
-    update(fact_id: number, content: string, kind?: MemoryKind, ttlDays?: number, opts?: FactWriteOptions): Promise<RememberResult>;
+    update(fact_id: number, content: string, kind?: MemoryKind, opts?: FactWriteOptions): Promise<RememberResult>;
     remove(fact_id: number, reason?: string): Promise<boolean>;
     archive(fact_id: number, reason?: string): Promise<boolean>;
     /**
-     * Bring an archived fact back (spec §2.6): a `forgot` fact is lifted to
-     * `recall_floor` (otherwise the very next tick would re-archive it, R4), the
-     * idle clock is refreshed (otherwise an `idle`-archived fact dies again, R18),
+     * Bring an archived fact back (spec §2.6): a `forgot` fact is lifted to the frozen base
+     * `BASE_TRUST` (otherwise the very next tick would re-archive it, R4),
+     * `last_retrieved_at` is refreshed (observation only — no clock reads it any more),
      * and `settle_clock` moves to now so the downtime is not charged.
      */
     restore(fact_id: number): Promise<boolean>;
-    helpful(fact_id: number): Promise<number | null>;
-    unhelpful(fact_id: number): Promise<number | null>;
-    /**
-     * Explicit feedback (spec §2.4). Pinned/archived rows only move `helpful_count`
-     * (R7); otherwise the decay is settled first, then `±feedback_delta`, pin at the
-     * permanent threshold (snap to 1.0) or archive immediately at the forget line.
-     */
-    private applyFeedback;
     /** Permanent-memory administration (spec §6). */
     pin(fact_id: number): Promise<boolean>;
     unpin(fact_id: number): Promise<boolean>;
@@ -455,7 +454,37 @@ export declare class MemoryStore {
     private sweepConflicts;
     /** Async bootstrap the semantic backend (download/config model) without blocking. */
     warmupSemantic(): Promise<boolean>;
-    /** List contradiction candidates (`resolved` 0 = open, 1 = closed with a recorded verdict). */
+    /**
+     * Point the semantic backend at a shared runtime-dependency root (the base provider's
+     * `runtime-deps` handle) before it warms. Best-effort by contract: a backend without external
+     * module resolution ignores it, and a missing root is reported by the backend itself.
+     */
+    useSemanticModuleDir(dir: string): void;
+    /**
+     * Point the vector store at a shared runtime-dependency root for its NATIVE binding
+     * (`hnswlib-node`), after the DSH plugin's native self-heal item is ready.
+     *
+     * Same best-effort contract as {@link useSemanticModuleDir}: a store with no native binding (the
+     * brute-force backend, or an `auto` store still on it) ignores it, and a store that already fell
+     * back to brute force rebuilds its tracked vectors under the new root. Nothing here decides whether
+     * a root should exist — the caller's dependency audit does.
+     */
+    useNativeModuleDir(dir: string): void;
+    /**
+     * Vectors currently in the LIVE index (sync, one map read).
+     *
+     * Exposed for the plugin's dependency audit: an `hnswlib-node` notice is conditioned on the corpus
+     * actually being large enough for an ANN index to matter (`min_vectors`), and a session line that
+     * asks "how big is the store right now" must not run a database query to answer.
+     */
+    liveVectorCount(): number;
+    /**
+     * List contradiction candidates (`resolved` 0 = open, 1 = closed with a recorded verdict).
+     *
+     * `detected_at` is mapped to the model face's instant shape here (the DAO hands back the raw UTC
+     * column): this payload is what the 记忆 tab's 未处理矛盾 table and the CLI both render, and it must
+     * not be the one surface still printing a zone-less stamp.
+     */
     listContradictions(opts?: {
         resolved?: number;
         kind?: MemoryKind;
@@ -695,10 +724,21 @@ export declare class MemoryStore {
      * ({@link timePage}, `mode:"time"`): the window is the whole question, so there is nothing to
      * match, plan or rank.
      *
-     * The exact, facts and relation passes reinforce the facts they return, exactly like the fuzzy
-     * pass does for its hits: all are recalls the caller actually reads. A caller that must stay
-     * read-only passes `track: false` (the conditional hint's probe does). Exact, facts, relation and
-     * time also honour the caller's output budget (their text is the caller's to bound).
+     * What a pass does to the rows it returns is one decision, and it is deliberately NOT uniform:
+     *
+     *  - the RELATION and FUZZY passes REINFORCE them ({@link reinforce}): each answers a question
+     *    the caller asked, so the rows are what it read;
+     *  - the TIME, EXACT and FACTS passes record USAGE ONLY ({@link touchOnly}): they hand back a
+     *    LIST the caller browses — page 2 of a listing is not a second recall — so "it was looked
+     *    at" still moves `retrieval_count` / `last_retrieved_at` (the dormancy clock) while
+     *    `trust_score` / `bonus_count` stay where they are.
+     *
+     * A caller that must stay read-only passes `track: false` (the conditional hint's probe does);
+     * that branch writes nothing at all, usage included. Exact, facts, relation and time also honour
+     * the caller's output budget (their text is the caller's to bound). The one difference is the
+     * DEFAULT: a time window applies no budget unless the caller names one — its page size (`limit`)
+     * is what bounds the list, and the budget would only rewrite rows the caller asked for (see
+     * {@link timePage}).
      *
      * It does NOT emit a retrieval-health event. Those counters describe the retrieval PIPELINE
      * (legs, fusion, semantic-live rate); none of an exact, facts, relation or time answer ran a leg,
@@ -714,9 +754,21 @@ export declare class MemoryStore {
      * happened that day" reads in the order it happened; `score` is the constant 1 exactly like the
      * exact page's, because there is no relevance number here for the model to compare.
      *
-     * It honours `kind`/`source`, pages with the same `offset`/`limit` (default 10, cap 50) and the
-     * same `max_tokens` budget as every other recall, and reinforces the rows it returns unless
-     * `track: false` — a window the caller reads is a recall like any other.
+     * The PAGE is the contract's, not the caller's guess: `limit` omitted means one page of
+     * {@link TIME_DEFAULT_LIMIT} rows (the same 50 the contract caps an explicit page at), and an
+     * explicit `limit` (1-50) still wins. A window that holds more than one page is the normal case
+     * for a busy day, so the envelope does not leave the caller to infer the shortfall: it reports
+     * `remaining = total - (offset + hits.length)`, the count still unseen.
+     *
+     * The output budget is honoured only when the caller names it (`max_tokens`). Falling back to the
+     * configured `retrieval.max_output_tokens` here would rewrite the text of a window's rows behind a
+     * page the caller already bounded with `limit` — the page size is the knob for "how much of the
+     * list", and the budget stays a knob for a RANKED result (exact/facts/relation/hybrid unchanged).
+     * `max_tokens` (including the contract's `0` = unlimited) is passed through unchanged.
+     *
+     * It honours `kind`/`source`, and records usage ONLY for the rows it returns unless `track: false`
+     * ({@link touchOnly}). A window is listed so the caller can look through it, not recalled into an
+     * answer: the dormancy clock (`retrieval_count` / `last_retrieved_at`) moves, trust does not.
      */
     private timePage;
     /**
@@ -753,8 +805,8 @@ export declare class MemoryStore {
      *    malformed window is the caller's error exactly as it is in the exact page;
      *  - the page is FACT-level (`total`/`offset`/`limit`/`truncated`), and the caller's output budget
      *    only shortens `content` — dropping a row would make `total` disagree with the page;
-     *  - the returned facts are reinforced unless `track: false`, like every other recall the caller
-     *    actually reads.
+     *  - the returned facts get usage recorded but NO reinforcement unless `track: false`: a facts
+     *    page is a list the caller browses, so only the dormancy clock moves ({@link touchOnly}).
      */
     private factPage;
     /**
@@ -928,6 +980,17 @@ export declare class MemoryStore {
     flushHealth(): Promise<void>;
     /** Retrieval bookkeeping: `retrieval_count` + the "last used" clock (spec §2.5). */
     private touchUsage;
+    /**
+     * Record the USAGE of these facts and nothing else — no trust bonus, no quota, no
+     * `last_reinforced_at`.
+     *
+     * This is the paginated passes' half of {@link reinforce}: `timePage` / `exactContentPage` /
+     * `factPage` return a list the caller browses rather than a recall it acted on, so "someone
+     * looked at this row" still moves `retrieval_count` / `last_retrieved_at` (observation and
+     * export only — no lifecycle step reads that clock) while `trust_score` / `bonus_count` stay
+     * put.
+     */
+    private touchOnly;
     /**
      * 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);
@@ -975,13 +1038,11 @@ export declare class MemoryStore {
     /**
      * Insert (or resolve to) a fact row.
      *
-     * `kind` / `ttlDays` are `undefined` when the CALLER specified nothing — the
-     * distinction is load-bearing. A duplicate-content hit must not clobber the existing
-     * row's values with the insert defaults: re-adding a fact without a kind used to
-     * reset it to `general`, and reviving an archived one silently cleared an explicit TTL.
-     * The rule for all three branches is therefore: an explicitly provided value lands, an
-     * omitted one keeps what the row already has, and a brand-new row falls back to the
-     * defaults (`general` / `0`).
+     * `kind` is `undefined` when the CALLER specified nothing — the distinction is load-bearing.
+     * A duplicate-content hit must not clobber the existing row's value with the insert default:
+     * re-adding a fact without a kind used to reset it to `general`. The rule for all three
+     * branches is therefore: an explicitly provided value lands, an omitted one keeps what the row
+     * already has, and a brand-new row falls back to the default (`note`).
      */
     private persistFact;
     /**

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

@@ -5,6 +5,16 @@ export declare const EXACT_MIN_LATIN = 3;
 /** The default page of an exact result, and its hard cap. */
 export declare const EXACT_DEFAULT_LIMIT = 10;
 export declare const EXACT_MAX_LIMIT = 50;
+/**
+ * The default page of a PURE TIME window (`mem_recall.search` with no `query`), and its cap.
+ *
+ * A window is a list, not a ranked shortlist: the caller asked "what happened then", and one page of
+ * ten would silently answer a tenth of the day. It is therefore answered with the widest page the
+ * contract allows (`EXACT_MAX_LIMIT`), and the envelope states how much is left
+ * (`remaining`) instead of leaving the caller to infer it from `truncated`. Omitting `limit` never
+ * means "everything": a window that has outgrown one page is exactly when a cap matters.
+ */
+export declare const TIME_DEFAULT_LIMIT = 50;
 /**
  * The widest literal match set that still counts as an ANSWER (P1-2, REVIEW-2026-10-24).
  *

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

@@ -107,7 +107,7 @@ export declare function timeParams(range: TimeRange | undefined): (string | numb
  */
 export declare function dayInZone(ms: number, timeZone?: string): string;
 /**
- * One stored `valid_from`/`valid_to` string → epoch ms, using the SAME grammar as the filters.
+ * One stored event-time (`valid_from`) string → epoch ms, using the SAME grammar as the filters.
  *
  * This is what the write path stamps into `valid_from_ms` and what migration 12's backfill applies to
  * existing rows, so "the event time a caller wrote" and "the event time a window compares" can never

package/lib/engine/mem/trustHeartbeat.d.ts

@@ -1,6 +1,6 @@
 /**
  * The trust heartbeat: the interval beat that advances the active-day clock and performs the
- * settle / forget / idle / purge sweeps (TRUST_MODEL.md §5), shared by the DSH plugin and the MCP
+ * settle / forget / purge sweeps (TRUST_MODEL.md §5), shared by the DSH plugin and the MCP
  * server.
  *
  * The two surfaces used to install it separately, and the copies drifted in exactly the places a