@avantf/dsh-mem 0.9.0 → 0.10.0

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/memory.d.ts

@@ -164,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
@@ -340,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.
@@ -367,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>;
@@ -488,7 +478,13 @@ export declare class MemoryStore {
      * 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). */
+    /**
+     * 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;
@@ -728,13 +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). 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}).
+     * 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,
@@ -762,8 +766,9 @@ export declare class MemoryStore {
      * 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 reinforces the rows it returns unless `track: false` — a window
-     * the caller reads is a recall like any other.
+     * 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;
     /**
@@ -800,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;
     /**
@@ -975,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);
@@ -1022,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/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

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

@@ -182,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;