@avantf/dsh-mem 0.9.0 → 0.10.0

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;
@@ -380,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;
@@ -447,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;
@@ -602,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;
@@ -695,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>;
 }
@@ -788,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;
     /**