@avantf/dsh-mem 0.8.1 → 0.10.0

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

@@ -8,6 +8,135 @@ import { z } from 'zod';
  * past the window SILENTLY, so every derivation has to agree on the number.
  */
 export declare const DEFAULT_MODEL_WINDOW_TOKENS = 512;
+/** One audit entry. `kind` decides which probe runs, and which of `specifier`/`item` is required. */
+export declare const DependencyAuditEntrySchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    id: z.ZodString;
+    severity: z.ZodEnum<{
+        info: "info";
+        warning: "warning";
+        degraded: "degraded";
+    }>;
+    when: z.ZodEnum<{
+        degraded: "degraded";
+        failed: "failed";
+        missing: "missing";
+    }>;
+    min_vectors: z.ZodOptional<z.ZodNumber>;
+    body: z.ZodString;
+    kind: z.ZodLiteral<"module">;
+    specifier: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    id: z.ZodString;
+    severity: z.ZodEnum<{
+        info: "info";
+        warning: "warning";
+        degraded: "degraded";
+    }>;
+    when: z.ZodEnum<{
+        degraded: "degraded";
+        failed: "failed";
+        missing: "missing";
+    }>;
+    min_vectors: z.ZodOptional<z.ZodNumber>;
+    body: z.ZodString;
+    kind: z.ZodLiteral<"runtime-deps">;
+    item: z.ZodString;
+}, z.core.$strip>], "kind">;
+/** One configured audit entry, discriminated by `kind`. */
+export type DependencyAuditEntry = z.infer<typeof DependencyAuditEntrySchema>;
+/**
+ * One `runtime-deps` declaration as SHIPPED WITH THE PLUGIN (`packages/plugin/res/runtime-deps.yaml`).
+ *
+ * WHY IT IS A RESOURCE AND NOT USER CONFIG. The package set, the sources, the attempts, the verify
+ * list and the audit sentences are facts about THIS BUILD: which module the local backend imports,
+ * which native bindings this release looks for, what a session should be told when one of them is
+ * absent. Leaving them to `configs/common.yaml` made every deployment responsible for keeping that
+ * list correct — a stale copy would install a module no code loads, or silently drop the audit — and
+ * the shipped defaults were only ever the plugin's own declaration anyway. The operator keeps the one
+ * thing that really is a per-deployment decision (the two `enabled` switches); the DATA travels in the
+ * package, next to the code that reads it.
+ *
+ * Validation is strict on purpose: the file is read from the INSTALL directory at mount, and a
+ * malformed one is a packaging bug. The plugin logs it and degrades (no self-heal item, no audit)
+ * rather than throwing out of the mount — see `packages/plugin/src/runtime_deps_resource.ts`.
+ *
+ * The schema is the SINGLE definition of the file's shape: the loader validates with it, and the
+ * plugin maps it to the base provider's objects field by field (the base never reads YAML).
+ */
+export declare const RuntimeDepsResourceSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    semantic: z.ZodObject<{
+        packages: z.ZodRecord<z.ZodString, z.ZodString>;
+        sources: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            registry: z.ZodDefault<z.ZodString>;
+            cache: z.ZodDefault<z.ZodString>;
+        }, z.core.$strip>>;
+        attempts: z.ZodArray<z.ZodObject<{
+            source: z.ZodString;
+            manager: z.ZodOptional<z.ZodEnum<{
+                npm: "npm";
+                pnpm: "pnpm";
+            }>>;
+            env: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+            allowScripts: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strip>>;
+        verify: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>;
+    native: z.ZodObject<{
+        packages: z.ZodRecord<z.ZodString, z.ZodString>;
+        sources: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            registry: z.ZodDefault<z.ZodString>;
+            cache: z.ZodDefault<z.ZodString>;
+        }, z.core.$strip>>;
+        attempts: z.ZodArray<z.ZodObject<{
+            source: z.ZodString;
+            manager: z.ZodOptional<z.ZodEnum<{
+                npm: "npm";
+                pnpm: "pnpm";
+            }>>;
+            env: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+            allowScripts: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strip>>;
+        verify: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>;
+    audit: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        id: z.ZodString;
+        severity: z.ZodEnum<{
+            info: "info";
+            warning: "warning";
+            degraded: "degraded";
+        }>;
+        when: z.ZodEnum<{
+            degraded: "degraded";
+            failed: "failed";
+            missing: "missing";
+        }>;
+        min_vectors: z.ZodOptional<z.ZodNumber>;
+        body: z.ZodString;
+        kind: z.ZodLiteral<"module">;
+        specifier: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        id: z.ZodString;
+        severity: z.ZodEnum<{
+            info: "info";
+            warning: "warning";
+            degraded: "degraded";
+        }>;
+        when: z.ZodEnum<{
+            degraded: "degraded";
+            failed: "failed";
+            missing: "missing";
+        }>;
+        min_vectors: z.ZodOptional<z.ZodNumber>;
+        body: z.ZodString;
+        kind: z.ZodLiteral<"runtime-deps">;
+        item: z.ZodString;
+    }, z.core.$strip>], "kind">>;
+}, z.core.$strip>;
+/** The parsed `res/runtime-deps.yaml`. */
+export type RuntimeDepsResource = z.infer<typeof RuntimeDepsResourceSchema>;
 /** The merged runtime config shared by the memory store and the retrieval stack. */
 export declare const ConfigSchema: z.ZodObject<{
     dataHome: z.ZodDefault<z.ZodString>;
@@ -20,6 +149,12 @@ export declare const ConfigSchema: z.ZodObject<{
         cache_dir: z.ZodDefault<z.ZodString>;
         auto_download: z.ZodDefault<z.ZodBoolean>;
         auto_migrate: z.ZodDefault<z.ZodBoolean>;
+        self_heal: z.ZodPrefault<z.ZodObject<{
+            enabled: z.ZodDefault<z.ZodBoolean>;
+        }, z.core.$strip>>;
+        native_self_heal: z.ZodPrefault<z.ZodObject<{
+            enabled: z.ZodDefault<z.ZodBoolean>;
+        }, z.core.$strip>>;
     }, z.core.$strip>>;
     vectorStore: z.ZodPrefault<z.ZodObject<{
         backend: z.ZodDefault<z.ZodString>;
@@ -47,20 +182,20 @@ export declare const ConfigSchema: z.ZodObject<{
     }, z.core.$strip>>;
     trust: z.ZodPrefault<z.ZodObject<{
         enabled: z.ZodDefault<z.ZodBoolean>;
-        start: z.ZodDefault<z.ZodNumber>;
-        decay_per_day: z.ZodDefault<z.ZodNumber>;
+        base_lifetime_days: z.ZodDefault<z.ZodNumber>;
+        max_retention_days: z.ZodDefault<z.ZodNumber>;
+        decay_shape: z.ZodDefault<z.ZodEnum<{
+            linear: "linear";
+            accelerating: "accelerating";
+        }>>;
+        decay_curvature: z.ZodDefault<z.ZodNumber>;
         forget_threshold: z.ZodDefault<z.ZodNumber>;
-        permanent_threshold: z.ZodDefault<z.ZodNumber>;
-        recall_floor: z.ZodDefault<z.ZodNumber>;
-        recall_delta: z.ZodDefault<z.ZodNumber>;
+        recall_gain_below_base: z.ZodDefault<z.ZodNumber>;
+        recall_gain_above_base: z.ZodDefault<z.ZodNumber>;
         recall_daily_cap: z.ZodDefault<z.ZodNumber>;
         recall_marginal_decay: z.ZodDefault<z.ZodNumber>;
-        recall_ceiling: z.ZodDefault<z.ZodNumber>;
-        feedback_delta: z.ZodDefault<z.ZodNumber>;
-        feedback_daily_cap: z.ZodDefault<z.ZodNumber>;
         inherit_trust_on_update: z.ZodDefault<z.ZodBoolean>;
         purge_skips_pinned: z.ZodDefault<z.ZodBoolean>;
-        idle_calendar_days: z.ZodDefault<z.ZodNumber>;
         tick_max_facts: z.ZodDefault<z.ZodNumber>;
         presence: z.ZodPrefault<z.ZodObject<{
             mode: z.ZodDefault<z.ZodEnum<{

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

@@ -1,8 +1,10 @@
 export * from './types.js';
 export * from './config.js';
+export * from './trust_curve.js';
 export * from './family.js';
 export * from './tools.js';
 export * from './remote.js';
 export * from './log.js';
 export * from './env.js';
 export * from './text.js';
+export * from './time.js';

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

@@ -0,0 +1,75 @@
+/**
+ * The ONE place a stored timestamp turns into a string a human (or a model) reads.
+ *
+ * ── THE BUG THIS MODULE EXISTS FOR ───────────────────────────────────────────────────────────────
+ *
+ * `facts.created_at` / `updated_at` / `archived_at` (and `contradiction_log.detected_at`, and the
+ * retrieval-health stamp) are written by SQLite's `DEFAULT CURRENT_TIMESTAMP`, which is **UTC**, and
+ * `store/memory.ts` used to hand the raw text up to every surface. Two consequences, both reported as
+ * "记忆时间显示不对":
+ *
+ *  1. the UI printed `2026-10-28 11:58:48` as if it were a local wall clock (Asia/Shanghai really
+ *     meant `19:58:48`), because a zone-less string cannot say otherwise;
+ *  2. the MODEL received the same zone-less string next to `event_date`, which is a calendar DATE
+ *     with no time and no zone. Two different kinds of value, one shape — the model had to guess
+ *     which one it was looking at, and it cannot.
+ *
+ * ── THE SPLIT THIS MODULE ENFORCES ───────────────────────────────────────────────────────────────
+ *
+ * Storage stays UTC and stays byte-identical (`facts_io` export/import/snapshot is a compatibility
+ * surface and is deliberately NOT routed through here). The fix is in the two DISPLAY faces:
+ *
+ *  - {@link formatOffsetIso} — the MODEL face (`mem_recall` hits, `mem_admin list/detail/
+ *    contradictions`, `mem_admin stats`, the CLI and MCP that print those payloads): an ISO-8601
+ *    instant **with an explicit offset**, e.g. `2026-10-28T19:58:48+08:00`, rendered in the host's
+ *    local zone. The offset is part of the string, so the model needs no conversion and the value is
+ *    never ambiguous again — while `event_date` stays `2026-10-28`, a calendar date with no zone.
+ *  - {@link formatLocalHuman} — the HUMAN face (the 记忆 tab): `2026-10-28 19:58`, the same instant,
+ *    local, to the minute.
+ *
+ * Both read the input through the SAME parser ({@link parseUtcTs}) and the same instant, so the two
+ * faces cannot disagree. The UI deliberately formats the model face's OWN string rather than
+ * re-deriving one from the raw column: the input it gets already carries an offset, `parseUtcTs`
+ * leaves an explicit offset alone, and there is therefore exactly ONE parse rule and ONE pair of
+ * renderers in the repository — not a second opinion in the browser.
+ *
+ * Dependency-free on purpose: this module is reachable from the DSH client bundle through the
+ * `@avantf/mem-contract/time` subpath (the bundle must not pull in the tool schemas / zod). It has no
+ * DSH host and no DB, so the engine, the CLI and the MCP face can all use it.
+ *
+ * @module contract/time
+ */
+/**
+ * `'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 (that is what makes a `formatOffsetIso` output safe to feed back in).
+ */
+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;
+/**
+ * The MODEL face: an instant as ISO-8601 with an explicit offset, in the host's local zone
+ * (`2026-10-28T19:58:48+08:00`).
+ *
+ * `null` — never `''` and never a fabricated stamp — when the value is absent or unreadable, so a
+ * caller keeps its own "unknown" spelling (`''` for `created_at`, `null` for `updated_at`) instead of
+ * rendering an empty time. `+00:00` (not `Z`) on a UTC host: the shape MUST carry a sign, which is
+ * what a caller regex-checks.
+ */
+export declare function formatOffsetIso(ts: string | null | undefined): string | null;
+/**
+ * The HUMAN face: the same instant as local wall-clock text to the minute (`2026-10-28 19:58`).
+ *
+ * Seconds are deliberately dropped: the list/detail lines and the health line are read at a glance,
+ * and `HH:MM` is the whole useful resolution there. `null` for an absent/unreadable value (same
+ * contract as {@link formatOffsetIso}), so a caller prints its own 「未知」/`—` placeholder.
+ *
+ * NOT for `event_date` / `valid_from`: those are calendar dates the CALLER wrote (`2026-10-28`), with
+ * no time and no zone. Running one through here would invent a midnight in the host's zone.
+ */
+export declare function formatLocalHuman(ts: string | null | undefined): string | null;

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

@@ -91,7 +91,7 @@ export declare function modelFacingToolResult(toolKey: string, action: unknown,
  */
 export declare const EXPORT_STATUSES: readonly ["active", "archived", "all"];
 export type ExportStatus = StatusFilter;
-export declare const REMEMBER_ACTIONS: readonly ["add", "update", "remove", "helpful", "unhelpful"];
+export declare const REMEMBER_ACTIONS: readonly ["add", "update", "remove"];
 export declare const RememberUnion: z.ZodDiscriminatedUnion<[z.ZodObject<{
     action: z.ZodLiteral<"add">;
     content: z.ZodString;
@@ -100,10 +100,8 @@ export declare const RememberUnion: z.ZodDiscriminatedUnion<[z.ZodObject<{
         note: "note";
     }>>;
     title: 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>;
     relations: z.ZodOptional<z.ZodArray<z.ZodObject<{
         subject: z.ZodString;
         predicate: z.ZodString;
@@ -119,10 +117,8 @@ export declare const RememberUnion: z.ZodDiscriminatedUnion<[z.ZodObject<{
     }>>;
     title: z.ZodOptional<z.ZodString>;
     retitle: z.ZodOptional<z.ZodLiteral<true>>;
-    ttl_days: z.ZodOptional<z.ZodNumber>;
     source_ref: z.ZodOptional<z.ZodString>;
     event_date: z.ZodOptional<z.ZodString>;
-    valid_until: z.ZodOptional<z.ZodString>;
     relations: z.ZodOptional<z.ZodArray<z.ZodObject<{
         subject: z.ZodString;
         predicate: z.ZodString;
@@ -132,12 +128,6 @@ export declare const RememberUnion: z.ZodDiscriminatedUnion<[z.ZodObject<{
     action: z.ZodLiteral<"remove">;
     fact_id: z.ZodNumber;
     reason: z.ZodOptional<z.ZodString>;
-}, z.core.$strip>, z.ZodObject<{
-    action: z.ZodLiteral<"helpful">;
-    fact_id: z.ZodNumber;
-}, z.core.$strip>, z.ZodObject<{
-    action: z.ZodLiteral<"unhelpful">;
-    fact_id: z.ZodNumber;
 }, z.core.$strip>], "action">;
 /**
  * The runtime/CLI-visible write request. The base zod union keeps `kind` optional so the CLI's
@@ -146,9 +136,13 @@ export declare const RememberUnion: z.ZodDiscriminatedUnion<[z.ZodObject<{
  */
 export type RememberRequest = z.infer<typeof RememberUnion>;
 /**
- * The writes the model may make. `helpful` / `unhelpful` are operator feedback: the model cannot
- * observe the retention clocks they move, and a model that could would be able to "refresh" a fact by
- * voting on it — the exact behaviour the retention policy exists to prevent.
+ * The writes the model may make — `MODEL_REMEMBER_ACTIONS` and `REMEMBER_ACTIONS` are the same three
+ * again since the operator-side `helpful` / `unhelpful` actions were removed: a vote on a fact was a
+ * way to move its retention clock, and a model able to vote could "refresh" a fact by voting on it.
+ *
+ * Permanent is set by ONE route only: an explicit `pin` from a human (`mem_admin` / CLI / settings
+ * page). Do NOT re-add an action that promotes or demotes a fact from a write path — that is the
+ * behaviour the retention policy exists to prevent.
  */
 export declare const MODEL_REMEMBER_ACTIONS: readonly ["add", "update", "remove"];
 export declare const ModelRememberUnion: z.ZodDiscriminatedUnion<readonly z.core.$ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>[], string>;
@@ -341,7 +335,7 @@ export declare const TOOL_SPECS: ToolSpec[];
  *
  * Descriptions are authored per action ("action=update 时必填"), so taking the
  * first branch's text verbatim told a model that `fact_id` only matters for
- * `update` although `remove/helpful/unhelpful` require it too. The action-clause
+ * `update` although `remove` requires it too. The action-clause
  * is stripped and replaced by the derived set of actions that make the field
  * required.
  *

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

@@ -0,0 +1,119 @@
+/**
+ * The trust decay curve — PURE functions, no IO, no config object of its own.
+ *
+ * This file is the ONE implementation of "how much trust is left after N active days" and of every
+ * inverse of it. `core/lifecycle/trust.ts` (read path, recall reinforcement), the tick's settle
+ * statement (`db/dao/facts.ts`) and the config's load-time validation (`config.ts`) all delegate
+ * here, so a change of shape cannot leave one of them behind (docs/TRUST_MODEL.md §2.2, DESIGN §18).
+ *
+ * It lives in the CONTRACT package because the load-time validation needs the same math, and the
+ * dependency direction is core → contract, never the reverse.
+ *
+ * ## The two shapes
+ *
+ * `linear` (TRUST_MODEL D7, the P3 equivalent tier): trust falls by a constant amount per active
+ * day, `slope = BASE_TRUST / base_lifetime_days` ⇒ a fact that starts at `BASE_TRUST` reaches 0
+ * after exactly `base_lifetime_days` active days.
+ *
+ * `accelerating` (the v2 target shape): `dT/dt = −λ·(a + 1 − T)` — the closer to 1, the slower the
+ * decay, so "almost permanent" facts really linger. Closed form (plan §3.1):
+ *
+ *     T(t) = (1 + a) − ((1 + a) − T₀)·e^(λt)      λ = ln((1 + a)/(1 + a − BASE_TRUST)) / B
+ *
+ * Note the POSITIVE exponent: `u = a + 1 − T` grows, so `e^(λt)` is the decay direction here (the
+ * plan writes it this way, and the closed-form test pins it). `a = decay_curvature`.
+ *
+ * ## Units
+ *
+ * `days` is ALWAYS the ACTIVE-DAY counter (`avantf_stats.trust_clock`), never wall time.
+ */
+/**
+ * The frozen anchor (TRUST_MODEL D20): a new fact's initial trust, the trust value the lifetime
+ * anchor is defined at (`daysToZero(BASE_TRUST) === base_lifetime_days`), and the divider between
+ * the two recall-reinforcement segments. One constant on purpose — the three uses must never be
+ * configurable apart, or "a new fact lives 90 active days" stops being true.
+ */
+export declare const BASE_TRUST = 0.5;
+/** The decay shapes `decay_shape` accepts. */
+export declare const DECAY_SHAPES: readonly ["linear", "accelerating"];
+export type DecayShape = (typeof DECAY_SHAPES)[number];
+/** The curve parameters, flattened from the `trust` config section (no config import: structural). */
+export interface TrustCurve {
+    shape: DecayShape;
+    /** `decay_curvature` — the floor term `a` of the accelerating shape; unused by `linear`. */
+    curvature: number;
+    /** `base_lifetime_days` — the active days `BASE_TRUST → 0` takes. */
+    baseDays: number;
+}
+/** Read the curve out of the `trust` section (the single mapping from keys to math). */
+export declare function curveOf(trust: {
+    decay_shape: DecayShape;
+    decay_curvature: number;
+    base_lifetime_days: number;
+}): TrustCurve;
+/**
+ * Trust units lost per active day — the LINEAR slope, `BASE_TRUST / base_lifetime_days`.
+ *
+ * `linear` is the only shape with a constant slope; for `accelerating` this returns the LOCAL slope
+ * at the anchor `T = BASE_TRUST` (`λ·(BASE_TRUST + a)`). It exists as the building block of the
+ * `linear` branch of {@link trustAfterDays} / {@link ceilingForDays} and for the tests that pin the
+ * anchor; it is deliberately NOT a scalar stand-in for the curve — anything that needs "how much
+ * trust is left after N days" uses {@link trustAfterDays}, and anything that needs "N days from a
+ * threshold" uses {@link ceilingForDays}. (An earlier caller — `trust_diagnose.forgetting_soon` —
+ * used it as a linear rate and was wrong once `accelerating` became the default.)
+ */
+export declare function slopeOf(shape: DecayShape, curvature: number, baseDays: number): number;
+/**
+ * `λ = ln((1 + a) / (1 + a − BASE_TRUST)) / baseDays` — pinned so the anchor holds:
+ * `λ·baseDays = ln((1 + a)/(0.5 + a))`, i.e. `daysToZero(BASE_TRUST) === baseDays` for ANY `a`.
+ */
+export declare function lambdaFor(curvature: number, baseDays: number): number;
+/**
+ * `T − days·slope` (linear) or the closed form `(1 + a) − ((1 + a) − T)·e^(λ·days)`.
+ *
+ * UNCLAMPED on purpose: callers clamp to `[0, 1]` themselves (`effectiveTrust`'s read path and the
+ * settle write both must clamp, and a shared clamp here would hide a caller that forgot).
+ */
+export declare function trustAfterDays(T: number, days: number, cfg: TrustCurve): number;
+/**
+ * Active days between two trust values, `t(T0 → T1)`.
+ *
+ * `linear`: `(T0 − T1) / slope`; `accelerating`: `ln((1 + a − T1)/(1 + a − T0)) / λ`. Both are
+ * signed the natural way (a RISING target yields a negative number of days), so the formula is
+ * usable as an inverse without special cases. Returns `NaN` only for an out-of-domain input
+ * (`T > 1 + a` on the accelerating branch), which the config validation makes unreachable.
+ */
+export declare function daysBetween(T0: number, T1: number, cfg: TrustCurve): number;
+/** Active days until the value reaches 0 — `remainingDays`'s whole body. */
+export declare function daysToZero(T: number, cfg: TrustCurve): number;
+/**
+ * The trust ceiling a `max_retention_days` promises: after being reinforced up to `ceiling`, a fact
+ * survives `days` more active days.
+ *
+ * `linear`: `days · slope` (= `days / (2·baseDays)`); `accelerating`: `(1 + a)(1 − e^(−λ·days))`.
+ * This is an INVERSION (`daysToZero(ceilingForDays(R)) === R`), not a configuration value — the
+ * config has no `recall_ceiling` key any more (D16).
+ */
+export declare function ceilingForDays(days: number, cfg: TrustCurve): number;
+/**
+ * The inverse of {@link ceilingForDays}: how many active days a given ceiling is worth. Used by the
+ * deprecated-key warning (`config/loader.ts`) to translate an old `recall_ceiling` value, and by the
+ * validation messages.
+ */
+export declare function retentionDaysForCeiling(ceiling: number, cfg: TrustCurve): number;
+/**
+ * `R_max` of the accelerating shape — the days at which the ceiling reaches 1 (`ceiling → ∞`).
+ *
+ *     R_max = baseDays · ln((1 + a)/a) / ln((1 + a)/(1 + a − BASE_TRUST))
+ *
+ * `max_retention_days` must stay strictly below it, or a reinforced fact would stop aging like
+ * `pinned` does (D14: permanent is set only by a person).
+ */
+export declare function RMAX(curvature: number, baseDays: number): number;
+/**
+ * The shape-aware upper bound on `max_retention_days`: the days at which the ceiling hits 1.
+ *
+ * `linear`: `2·baseDays` (the ceiling is `days/(2·baseDays)`); `accelerating`: {@link RMAX}. Both
+ * are STRICT bounds — at the bound the ceiling is exactly 1, which `superRefine` rejects.
+ */
+export declare function retentionDaysLimit(shape: DecayShape, curvature: number, baseDays: number): number;

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

@@ -74,6 +74,25 @@ export type StatusFilter = (typeof STATUS_FILTERS)[number];
  * SEARCH query shares the bound because it is compared against the stored title with `=`/`LIKE`.
  */
 export declare const TITLE_MAX_CHARS = 120;
+/**
+ * ── TWO KINDS OF TIME, TWO SHAPES (the "记忆时间显示不对" fix) ────────────────────────────────────
+ *
+ * Every INSTANT in a payload (`created_at`, `updated_at`, `archived_at`, `pinned_at`,
+ * `last_reinforced_at`, `bonus_window_at`, `detected_at`, the health stamp) is an ISO-8601 instant
+ * **with an explicit offset in the host's local zone** — `2026-10-28T19:58:48+08:00` — produced by
+ * `@avantf/mem-contract/time`'s `formatOffsetIso`. Storage is unchanged (SQLite `CURRENT_TIMESTAMP`
+ * is UTC, and the `facts_io` export/import/snapshot document keeps the SQLite text), so this is a
+ * RENDERING rule, not a storage one: the model gets an unambiguous instant it never has to convert,
+ * and a UI can `Date.parse` it directly.
+ *
+ * `event_date` / `valid_from` is the OTHER kind: a calendar DATE the caller wrote (`2026-10-28`),
+ * with no time and no zone. It is never passed through the instant renderer, and the two must not be
+ * confused: `created_at` answers "when was this recorded", `event_date` answers "as of which day is
+ * this true".
+ *
+ * A UI that shows these to a human formats them through `formatLocalHuman` (the same module): local
+ * wall clock to the minute, `2026-10-28 19:58`.
+ */
 export interface FactSummary {
     fact_id: number;
     content: string;
@@ -95,8 +114,15 @@ export interface FactSummary {
     pinned: boolean;
     /** Remaining ACTIVE days before `forgot`; null when pinned / non-active / trust disabled. */
     remaining_days: number | null;
+    /**
+     * @deprecated No writer since `helpful` / `unhelpful` were removed (2026-10-28). The column stays
+     * because it is part of the export/import/snapshot format, so an old document still round-trips;
+     * the value is whatever the row last carried. Do not build new logic on it.
+     */
     helpful_count: number;
+    /** When the memory was first recorded — an INSTANT, ISO-8601 with the host's offset. */
     created_at: string;
+    /** When it was archived — an INSTANT (ISO-8601 with offset), `null` while active. */
     archived_at: string | null;
     archive_reason: string | null;
 }
@@ -152,15 +178,21 @@ export interface FactDetail extends FactSummary {
     relations: FactRelation[];
     /** Active-day clock value at the last settle. */
     settle_clock: number;
+    /** When it was pinned — an INSTANT (ISO-8601 with offset), `null` when never pinned. */
     pinned_at: string | null;
+    /** When trust was last raised by a recall — an INSTANT (ISO-8601 with offset). */
     last_reinforced_at: string | null;
     /**
      * When this row was last CHANGED (edit/pin/unpin/reinforce/archive/restore). Retrieval and the
      * daily settle do not write it, so it is not `last_retrieved_at`; `null` on a legacy row.
+     *
+     * An INSTANT (ISO-8601 with the host's offset) — compare it with `created_at`, never with
+     * `valid_from`, which is a calendar date.
      */
     updated_at: string | null;
     /** Effective reinforcement events in the current 24h window (recall + feedback). */
     bonus_count: number;
+    /** Start of that window — an INSTANT (ISO-8601 with offset), `null` when no window is open. */
     bonus_window_at: string | null;
     /**
      * P-08: where this fact came from, as recorded rows. Empty when the writer gave no `source_ref`
@@ -168,12 +200,13 @@ export interface FactDetail extends FactSummary {
      */
     sources: FactSourceView[];
     /**
-     * P-07: when the fact became true / stopped being true. `null` = unknown; `valid_to` set while
-     * the row is still `active` means "still valid, known to end at T" (the state
-     * `mem_remember valid_until` creates), while an archived row's `valid_to` is an audit stamp.
+     * P-07/P-13: when the fact became true (the caller's `event_date`) — a CALENDAR DATE
+     * (`YYYY-MM-DD`), with no time and no zone, exactly as the caller wrote it. `null` = unknown. It is
+     * the `event` time axis — NOT a validity window: v2 removed the "known end" (`valid_until`)
+     * entirely, so "this is no longer true" is expressed by `update` or `archive`, never by a deadline
+     * field. Do not compare it with `created_at`/`updated_at`: those are instants.
      */
     valid_from: string | null;
-    valid_to: string | null;
     /**
      * P-07: the fact that supersedes this one, DERIVED from the existing `supersedes_id` link
      * (reverse lookup) — no redundant column. `null` when nothing supersedes it.
@@ -203,12 +236,15 @@ export interface RecallHit {
      * When this hit was first recorded: a fact's revision chain keeps the ORIGINAL row's
      * `created_at` across a supersede (`mem_remember update`), so this is when the memory was
      * first asserted, not when its current text was written (see `updated_at`).
+     *
+     * An INSTANT: ISO-8601 with the host's explicit offset (`2026-10-28T19:58:48+08:00`), so no
+     * conversion is needed and it can never be mistaken for `valid_from`'s calendar date.
      */
     created_at: string;
     /**
      * When this row was last CHANGED — an edit, pin/unpin, reinforcement, archive or restore.
      * Retrieval and the daily settle deliberately do not write it, so it never means "last
-     * retrieved"; a copy can carry `null` on a legacy row.
+     * retrieved"; a copy can carry `null` on a legacy row. An INSTANT (ISO-8601 with offset).
      */
     updated_at: string | null;
     /**
@@ -235,12 +271,16 @@ export interface RecallHit {
      */
     final?: number;
     /**
-     * P-07/P-13: the fact's event time / known end, serialized ONLY when non-null (the same
-     * convention as {@link RecallHit.truncated}). `null` means "unknown", and omitting the key keeps
-     * every pre-P-07 envelope byte-identical. Both are display/audit only — no leg filters on them.
+     * P-07/P-13: the fact's event time, serialized ONLY when non-null (the same convention as
+     * {@link RecallHit.truncated}). `null` means "unknown", and omitting the key keeps every pre-P-07
+     * envelope byte-identical. Display only — no leg filters on it.
+     *
+     * A CALENDAR DATE (`YYYY-MM-DD`), not an instant: the caller wrote it, it has no time and no zone,
+     * and it is deliberately NOT rendered in the host's zone. `created_at`/`updated_at` on the same
+     * hit are instants with an offset — the two answer different questions ("as of which day is this
+     * true" vs "when was it recorded").
      */
     valid_from?: string;
-    valid_to?: string;
     /**
      * The fact's title, when it has one (journal entries normally do, notes usually do not).
      *
@@ -277,9 +317,14 @@ export interface TitleCandidate {
     matched_title: string;
     memory_kind: MemoryKind;
     status: FactStatus;
+    /** When the memory was first recorded — an INSTANT (ISO-8601 with the host's offset). */
     created_at: string;
+    /** When it was last changed — an INSTANT (ISO-8601 with offset), `null` when never revised. */
     updated_at: string | null;
-    /** The fact's event time (`valid_from`), when it has one — the journal axis that tells two entries apart. */
+    /**
+     * The fact's event time (`valid_from`), when it has one — the journal axis that tells two entries
+     * apart. A CALENDAR DATE (`YYYY-MM-DD`), never an instant: `created_at` is the instant.
+     */
     event_date?: string;
     /** The first characters of the content, for judging "same transaction or not"; absent when `include_excerpt` is false. */
     excerpt?: string;
@@ -306,9 +351,20 @@ export type ExactSearchResult = ExactPageEnvelope & {
  * The window IS the question: no literal pass, no relation plan, no fuzzy legs. `hits` are the
  * active facts inside the window, newest first along `time.field`, and `score` is the same constant
  * 1 the exact page reports — there is no relevance number here to compare with anything.
+ *
+ * A window is a LIST, so its page is bounded like every other page (default 50, cap 50) and the
+ * envelope has to say how much of the list is not on it: {@link TimeSearchResult.remaining} is that
+ * number, spelled out instead of left for the caller to derive from `truncated`.
  */
 export type TimeSearchResult = ExactPageEnvelope & {
     mode: 'time';
+    /**
+     * How many rows of the window this answer does NOT show: `total - (offset + hits.length)`, never
+     * negative. `0` means the window is exhausted (either it fits, or the caller reached its last
+     * page). It is the count a caller needs to continue — `truncated` alone says "there is more"
+     * without saying how much.
+     */
+    remaining: number;
     hits: RecallHit[];
 };
 /**
@@ -369,7 +425,9 @@ export interface RelationEvidence {
     /** The memory layer, so a caller knows whether it is reading a journal or a note. */
     memory_kind: MemoryKind;
     title?: string;
+    /** When the memory was first recorded — an INSTANT (ISO-8601 with the host's offset). */
     created_at: string;
+    /** When it was last changed — an INSTANT (ISO-8601 with offset), `null` when never revised. */
     updated_at: string | null;
     /** Set when the output budget shortened `text` (never when the evidence itself was dropped). */
     truncated?: boolean;
@@ -436,9 +494,11 @@ export interface FactEvidence {
     /** `active` for every row this stage returns; carried so the field is explicit, not implied. */
     status: FactStatus;
     title?: string;
-    /** The fact's event time (`valid_from`), when it has one. */
+    /** The fact's event time (`valid_from`) — a CALENDAR DATE (`YYYY-MM-DD`), when it has one. */
     event_date?: string;
+    /** When the memory was first recorded — an INSTANT (ISO-8601 with the host's offset). */
     created_at: string;
+    /** When it was last changed — an INSTANT (ISO-8601 with offset), `null` when never revised. */
     updated_at: string | null;
     /** Set when the output budget shortened `content` (never when the fact itself was dropped). */
     truncated?: boolean;
@@ -591,6 +651,7 @@ export interface ContradictionRecord {
     fact_a: number;
     fact_b: number;
     score: number;
+    /** When the pair was detected — an INSTANT (ISO-8601 with the host's offset). */
     detected_at: string;
     content_a: string;
     content_b: string;
@@ -684,6 +745,7 @@ export interface RetrievalHealthSummary {
     legs_capped: number;
     /** Candidates removed by a leg's relevance floor (see `RetrievalHealth`). */
     candidates_dropped_by_floor: number;
+    /** When a counter last moved — an INSTANT (ISO-8601 with the host's offset), `null` before any. */
     updated_at: string | null;
     by_kind: Record<string, KindHealth>;
 }
@@ -777,7 +839,6 @@ export interface TrustDiagnostic {
     forgetting_soon: number;
     reinforced_today: number;
     bonus_granted_today: number;
-    idle_candidates: number;
     archived_by_reason: Record<string, number>;
     oldest_settle_clock: number | null;
     /**