@modusensus/dsh-mneme 0.8.15 → 0.9.0

package/lib/store.js

@@ -13,6 +13,10 @@ CREATE TABLE IF NOT EXISTS memories (
   importance  INTEGER NOT NULL DEFAULT 3,
   forgotten   INTEGER NOT NULL DEFAULT 0,
   archived    INTEGER NOT NULL DEFAULT 0,
+  -- Issue #275 第二批：归档时刻的精确列。archived 是标志位，updated_at 只是
+  -- 「最后一次写」——对已归档行做一次 update 就会刷它，代理口径因此高估归档
+  -- 净增速率。本列只在「从活跃面进入归档面」那一次落值，取消归档置 NULL。
+  archived_at TEXT,
   source      TEXT,
   content_history TEXT,
   content_hash TEXT,
@@ -215,6 +219,52 @@ CREATE TABLE IF NOT EXISTS distill_cursors (
   updated_at TEXT NOT NULL
 );
 
+-- #399 蒸馏窗口的原始公开记录（凭证）。蒸馏此前只把会话压成记忆、原文随即消失，
+-- 于是「这句原文没进任何记忆」永远不可测——留存一份原始副本，蒸馏就从「替换」
+-- 降级成「叠加索引」（arXiv 2609.36059 §3 Eq.1：与原文并存的旁路索引不丢信息）。
+-- 主键 (session_id, seq) 承担幂等：额度耗尽 / 宿主重启后会重跑同一 seq 窗口
+-- （summarize.js 的 max-runs 门刻意不消费游标），重跑必须不产生重复记录。
+-- 落盘文本不受 distillMaxChars / trim() 三刀约束——留存的意义就是整段原文。
+-- 刻意不加 sensitivity 列：机密级是**记忆级**判断，写记录那一刻它还不存在
+-- （一个窗口里什么都有），加了就是往 schema 里写一个做不到的承诺。
+CREATE TABLE IF NOT EXISTS distill_records (
+  session_id   TEXT    NOT NULL,
+  seq          INTEGER NOT NULL,
+  role         TEXT    NOT NULL,   -- user | assistant | agent（lang.js 的三种公开形态）
+  text         TEXT    NOT NULL,   -- 未截断的公开正文
+  window_id    TEXT,
+  distilled_at TEXT    NOT NULL,
+  PRIMARY KEY (session_id, seq)
+);
+CREATE INDEX IF NOT EXISTS idx_distill_records_window ON distill_records(window_id);
+-- 到期裁剪按 distilled_at 扫（与 llm_audit_logs.timestamp 同一口径）。
+CREATE INDEX IF NOT EXISTS idx_distill_records_distilled_at ON distill_records(distilled_at);
+
+-- #399 记忆级溯源：一条记忆由哪个蒸馏窗口的哪个 seq 区间派生。归因用**区间**而非
+-- 逐事件外键——蒸馏窗口本身就是连续 seq 段，窗口级归因第一步够用。
+-- 删除语义：到期裁剪只删 distill_records，本表保留并指向空区间（面板/CLI 显示
+-- 「来源已过期」），绝不级联删记忆；删记忆只清链接、记录保留——一个窗口的凭证
+-- 不该因删掉其中一条派生记忆而消失。
+-- memory_id 是 TEXT 而非 issue 草稿里的 INTEGER：memories.id 是 TEXT 主键，
+-- 类型必须与父表一致（否则 join 恒空）。
+-- ON DELETE CASCADE 在本库**不生效**——store.js 从不打开 PRAGMA foreign_keys，
+-- 全库唯一那条 REFERENCES 也一直是惰性的。与其为一个新表翻转全局 pragma
+-- （会同时改变既有 recall_events 的写入行为），不如在 remove() 里显式清链接：
+-- 语义相同、影响面只在本表。见 remove() 的注释。
+CREATE TABLE IF NOT EXISTS memory_provenance (
+  memory_id  TEXT    NOT NULL REFERENCES memories(id) ON DELETE CASCADE,
+  session_id TEXT    NOT NULL,
+  seq_start  INTEGER NOT NULL,
+  seq_end    INTEGER NOT NULL,
+  created_at TEXT    NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_memory_provenance_memory ON memory_provenance(memory_id);
+CREATE INDEX IF NOT EXISTS idx_memory_provenance_session ON memory_provenance(session_id);
+-- issue 草稿没有唯一约束，但重跑同一窗口会重复插同一链接（幂等测试锁 1 会挂）。
+-- 同一 (记忆, 会话, 区间) 只有一条事实，用唯一索引 + ON CONFLICT DO NOTHING 表达。
+CREATE UNIQUE INDEX IF NOT EXISTS idx_memory_provenance_link
+  ON memory_provenance(memory_id, session_id, seq_start, seq_end);
+
 -- entity gene (v0.3.0): named entities mentioned across memories, with
 -- time-boxed attributes (valid_from → valid_until) and typed relations.
 -- Attributes follow the snapshot style: saveAttr invalidates the previous
@@ -453,6 +503,10 @@ function toRow(row) {
     importance: row.importance,
     forgotten: row.forgotten === 1,
     archived: row.archived === 1,
+    // Issue #275 第二批：NULL（存量归档行、或落地前的历史数据）读作 undefined，
+    // 与 sensitivity/occurred_at 同款——调用方必须显式处理「时刻不可知」，不能
+    // 顺手 `?? updated_at` 把代理口径捡回来。
+    archived_at: row.archived_at ?? undefined,
     source: row.source ?? undefined,
     content_history: parseJsonArray(row.content_history),
     evidence: parseJsonArray(row.evidence),
@@ -741,6 +795,11 @@ export function createStore(path) {
   };
 
   addColumn("memories", "archived", "ALTER TABLE memories ADD COLUMN archived INTEGER NOT NULL DEFAULT 0");
+  // Issue #275 第二批：归档时刻精确列。可空不带 DEFAULT——存量库的已归档行
+  // 零重写，读侧 NULL = 「本列落地前归档，时刻不可追溯」。刻意不回填：用
+  // updated_at 回填等于把被推翻的代理口径重新固化进列里，偏差（偏高）会从
+  // 「已知的口径差」变成「看不见的脏数据」。
+  addColumn("memories", "archived_at", "ALTER TABLE memories ADD COLUMN archived_at TEXT");
   addColumn("memories", "embedding", "ALTER TABLE memories ADD COLUMN embedding TEXT");
   addColumn("memories", "last_accessed_at", "ALTER TABLE memories ADD COLUMN last_accessed_at TEXT");
   addColumn("memories", "_full_content", "ALTER TABLE memories ADD COLUMN _full_content TEXT");
@@ -1058,8 +1117,8 @@ export function createStore(path) {
       : inferEpistemicStatus(memory);
     runAtomically(() => {
       db.prepare(
-        `INSERT INTO memories (id, type, title, content, tags, importance, forgotten, archived, source, content_history, quality_score, embedding, epistemic_status, agent_scope, workspace_scope, agent_scope_source, workspace_scope_source, scope_decided_at, sensitivity, occurred_at, evidence, doc_path, content_hash, created_at, updated_at)
-         VALUES (?, ?, ?, ?, ?, ?, 0, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`
+        `INSERT INTO memories (id, type, title, content, tags, importance, forgotten, archived, archived_at, source, content_history, quality_score, embedding, epistemic_status, agent_scope, workspace_scope, agent_scope_source, workspace_scope_source, scope_decided_at, sensitivity, occurred_at, evidence, doc_path, content_hash, created_at, updated_at)
+         VALUES (?, ?, ?, ?, ?, ?, 0, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`
       ).run(
         id,
         type,
@@ -1068,6 +1127,10 @@ export function createStore(path) {
         tags,
         importance,
         memory.archived ? 1 : 0,
+        // 铸造即归档的行（store.save({archived:true})）：归档时刻就是入库时刻。
+        // 不写这一格的话，archived=1 而 archived_at=NULL 会落在「存量行」语义里，
+        // 精确口径读侧只能把它当不可追溯——明明是当下发生的归档，白丢一条记录。
+        memory.archived ? now : null,
         memory.source ?? null,
         JSON.stringify(memory.content_history ?? []),
         Number.isFinite(memory.quality_score) ? memory.quality_score : null,
@@ -1218,6 +1281,12 @@ export function createStore(path) {
 
   function remove(id) {
     runAtomically(() => {
+      // #399：memory_provenance 的 ON DELETE CASCADE 在本库是惰性的（createStore
+      // 从不打开 PRAGMA foreign_keys），所以链接在这里显式清。不用翻转全局 pragma
+      // 换这一条级联：那会同时激活 recall_events 那条既有的 REFERENCES，改变一个
+      // 与 #399 无关的写入路径。记录本身（distill_records）不删——删掉一条派生记忆
+      // 不该让整个窗口的原文凭证消失。
+      db.prepare("DELETE FROM memory_provenance WHERE memory_id = ?").run(id);
       db.prepare("DELETE FROM memories WHERE id = ?").run(id);
       // Mirror sync must reflect the deletion; bump desired generation so a
       // crash between the delete and syncMirror leaves a recoverable debt.
@@ -1308,10 +1377,27 @@ export function createStore(path) {
     return getById(id);
   }
 
+  // Issue #275 第二批：archived_at 是「从活跃面进入归档面」那一刻的精确记录。
+  // updated_at 照旧刷新（本函数自 v0.2 起的既有语义，其他读侧依赖它——面板排序、
+  // 快照哈希、CAS），两列职责分开：updated_at = 最后一次写，archived_at = 归档时刻。
+  // 幂等：已是归档态再调 archived=true，不刷新 archived_at（重复归档不是新一次
+  // 归档，否则「重复调 setArchived」又变成一次净增——那正是代理口径被推翻的原因）。
   function setArchived(id, archived) {
+    const next = archived ? 1 : 0;
     runAtomically(() => {
-      db.prepare("UPDATE memories SET archived = ?, updated_at = ? WHERE id = ?")
-        .run(archived ? 1 : 0, nowIso(), id);
+      // nowIso 在事务内取（与改动前一致）：单调顶推的时间戳不该被一次回滚白白消耗。
+      const now = nowIso();
+      // CASE 里的 archived 是**更新前**的值（SQLite UPDATE 表达式语义）：
+      //   活跃 → 归档：落当前时刻；已归档 → 归档：保留原值（含存量 NULL，不回填）；
+      //   任意 → 取消归档：清 NULL。
+      // 幂等刻意选「重复归档不刷新时刻」：否则「对同一行重复调 setArchived(true)」
+      // 会再被算成本窗口新进——那正是本批要消灭的代理口径偏高，换个入口复活而已。
+      db.prepare(
+        `UPDATE memories SET archived = ?,
+           archived_at = CASE WHEN ? = 1 AND archived = 0 THEN ? WHEN ? = 0 THEN NULL ELSE archived_at END,
+           updated_at = ?
+         WHERE id = ?`
+      ).run(next, next, now, next, now, id);
       incrementGeneration();
     });
     return getById(id);
@@ -1479,11 +1565,24 @@ export function createStore(path) {
     // "chrono" is pure newest-first — the stable order paged browsing (month
     // tree, infinite scroll) needs; importance ordering would interleave
     // months across pages.
-    const orderBy = order === "chrono" ? "updated_at DESC, id DESC" : "importance DESC, updated_at DESC, id";
+    // #430：chrono 的 **无界档** 不再追加 id 平局键。updated_at 上有 #202 建的
+    // 索引，而带 id 的第二项排序键用不上它——5k 行实测同一份 SQL 只差这一项：
+    // 100.6ms（带 id，EXPLAIN 多一个 USE TEMP B-TREE）对 23.4ms（纯 updated_at，
+    // 直接走 idx_memories_updated）。分页档位必须留平局键（跨页拼接要求稳定，
+    // 同刻两行在新旧页之间可能漏一条或重复一条）；无界档没有跨页拼接，今天唯一
+    // 的调用方 syncMirror 只用它算覆盖集，与顺序无关。
+    const orderBy = order === "chrono"
+      ? (unbounded ? "updated_at DESC" : "updated_at DESC, id DESC")
+      : "importance DESC, updated_at DESC, id";
+    // Issue #430：与 all() 共用同一份显式列清单（memoryColumns 由 PRAGMA 派生，
+    // 排除 embedding）。toRow 本就不输出向量，SELECT * 只是把全表最重的列拖进
+    // 内存再丢弃——无界档实测 5k 行 263ms → 117ms，窗口档 50ms → 41ms，本函数
+    // 的全部调用方（分页浏览、document 索引、sleep 池、注册器全量扫描）一起受益。
+    const projected = `SELECT ${memoryColumnList} FROM memories`;
     const rows = unbounded
-      ? db.prepare(`SELECT * FROM memories ${where} ORDER BY ${orderBy}`).all(...params)
+      ? db.prepare(`${projected} ${where} ORDER BY ${orderBy}`).all(...params)
       : db.prepare(
-          `SELECT * FROM memories ${where} ORDER BY ${orderBy} LIMIT ? OFFSET ?`
+          `${projected} ${where} ORDER BY ${orderBy} LIMIT ? OFFSET ?`
         ).all(...params, lim, off);
     return rows.map(toRow);
   }
@@ -1495,6 +1594,18 @@ export function createStore(path) {
     return rows.map(toRow);
   }
 
+  // Issue #430：写路径要的「最近若干条正文」。质量过滤的近重复判定只读 content
+  // 这一列 + 前 20 行，此前写成 all().slice(0, 20) —— 全表逐行 toRow（27 字段、
+  // 三次 JSON 解析）之后只截前 20 条正文；5k 行实测 100ms 级 → 0.06ms 级。
+  // 口径与 all() 的前 N 条严格一致：不加 WHERE（archived/forgotten 仍参与近重复
+  // 判定）、updated_at DESC、同刻顺序未定义。limit 走 sanitizePage，非正整数
+  // 落回 20，调用方不必自己防 0/undefined。
+  function recentContents(limit = 20) {
+    const { limit: lim } = sanitizePage(limit, 0, 20);
+    const rows = db.prepare("SELECT content FROM memories ORDER BY updated_at DESC LIMIT ?").all(lim);
+    return rows.map((row) => row.content ?? "");
+  }
+
   /** Set (or clear with null) the embedding vector of a memory. */
   function setEmbedding(id, vector) {
     const json = Array.isArray(vector) && vector.length ? JSON.stringify(vector) : null;
@@ -1882,6 +1993,30 @@ export function createStore(path) {
 
   // --- recall evaluation trail (方案 B: separate from the production audit) -
 
+  /**
+   * Rolling purge of the recall_runs production audit (v0.7.0): with recordRecall
+   * defaulting ON, the table would otherwise grow unboundedly on a busy store.
+   * Drop rows older than `days` (config.recallRetentionDays, default 90).
+   * created_at is an ISO TEXT string, so the ISO bound compares lexicographically.
+   * Returns the number of rows deleted (bookkeeping — never throws on empty).
+   *
+   * 2026-10-14 找回：这一对（本函数 + index.js 的启动调用）在 dd0ed78「release:
+   * v0.7.12 + 编码记忆(codingRetrospect)蒸馏/…（合并 #73 与 #74）」里被整块弄丢。
+   * 该提交不是 merge（单亲 cb5ec63），store.js 是从一个没有这段的版本重建的，
+   * 于是函数与调用一起蒸发，而配置键 recallRetentionDays、README.md 与
+   * docs/CONFIGURATION.md 的「recall_runs 滚动清理保留天数」一直留到今天。
+   * 实测后果（2026-10-14 快照）：本机 recall_runs 18,442 行、跨度 2026-09-08 →
+   * 2026-10-13，即从那一天起只增不减。注意这张表是**活的、只增的**：同一个 10-13
+   * 当天 14:43Z 是 18,442 行、20:47Z 已是 20,029 行，几小时就差一千五——所以任何
+   * 行数只在测它的那一刻成立，引用时必须带时刻，否则日后对不上会被误读成出了错。
+   * 这份审计里现在装的是用户原话，不是无信息的空串。
+   */
+  function purgeRecallRunsOlderThan(days) {
+    const cutoff = new Date(Date.now() - days * 86400000).toISOString();
+    const result = db.prepare("DELETE FROM recall_runs WHERE created_at < ?").run(cutoff);
+    return result.changes;
+  }
+
   /**
    * Persist one retrieval-evaluation snapshot into recall_evals — the test/eval
    * sibling of recall_runs, deliberately stored apart so eval snapshots never
@@ -2011,8 +2146,16 @@ export function createStore(path) {
 
   /**
    * Aggregate LLM spend over the last `days`: total calls/tokens/duration/cost,
-   * broken down by trigger_source and by status. Used by the API's
-   * /llm-audit/stats endpoint so the Web panel can show where budget goes.
+   * broken down by trigger_source, by status, by operation_type and by day.
+   * Used by the API's /llm-audit/stats endpoint so the Web panel can show
+   * where budget goes.
+   *
+   * by_operation / by_day exist because by_source is too coarse for the
+   * "where did the tokens go" panel: trigger_source merges dream_consolidate
+   * and dream_summarize into one autoDream bucket, hiding the single largest
+   * cost item (37% of 7-day tokens in the 2026-10 audit). by_day feeds the
+   * 7-day trend bars. Both are additive — by_source/by_status keep their
+   * shape (two tests assert on them).
    */
   function getLlmAuditStats({ days = 7 } = {}) {
     const since = new Date(Date.now() - days * 86400000).toISOString();
@@ -2034,6 +2177,22 @@ export function createStore(path) {
     const byStatus = db.prepare(
       "SELECT status, count(*) AS c FROM llm_audit_logs WHERE timestamp >= ? GROUP BY status"
     ).all(since);
+    const byOperation = db.prepare(
+      `SELECT operation_type AS operation, count(*) AS c,
+              COALESCE(SUM(input_tokens), 0) AS input_tokens,
+              COALESCE(SUM(output_tokens), 0) AS output_tokens,
+              COALESCE(SUM(total_tokens), 0) AS total_tokens
+       FROM llm_audit_logs WHERE timestamp >= ?
+       GROUP BY operation_type ORDER BY total_tokens DESC`
+    ).all(since);
+    const byDay = db.prepare(
+      `SELECT date(timestamp) AS day, count(*) AS c,
+              COALESCE(SUM(input_tokens), 0) AS input_tokens,
+              COALESCE(SUM(output_tokens), 0) AS output_tokens,
+              COALESCE(SUM(total_tokens), 0) AS total_tokens
+       FROM llm_audit_logs WHERE timestamp >= ?
+       GROUP BY date(timestamp) ORDER BY day ASC`
+    ).all(since);
     return {
       days,
       since,
@@ -2044,7 +2203,9 @@ export function createStore(path) {
       total_duration_ms: total.d,
       total_cost_usd: Number(total.cst),
       by_source: bySource,
-      by_status: byStatus
+      by_status: byStatus,
+      by_operation: byOperation,
+      by_day: byDay
     };
   }
 
@@ -2053,6 +2214,77 @@ export function createStore(path) {
     return db.prepare("DELETE FROM llm_audit_logs WHERE timestamp < ?").run(before).changes;
   }
 
+  // --- 蒸馏原始记录与记忆级溯源（#399）-------------------------------------
+
+  /**
+   * 落盘一个蒸馏窗口的公开记录（#399）。
+   *
+   * `INSERT OR IGNORE` 而非 OR REPLACE：主键 (session_id, seq) 的冲突只可能来自
+   * **同一窗口的重跑**（max-runs 门耗尽额度、宿主重启都会重跑同一 seq 段，见
+   * summarize.js 里「max-runs 刻意不消费游标」的注释），而重跑必须幂等——同一
+   * seq 的原文没有第二次「更真」的版本，保留首次落盘时间才诚实。
+   * @param {Array<{seq:number, role:string, text:string, windowId?:string, distilledAt:string}>} records
+   * @returns {number} 实际插入行数（被忽略的冲突不计）
+   */
+  function saveDistillRecords(records) {
+    if (!Array.isArray(records) || records.length === 0) return 0;
+    const stmt = db.prepare(
+      `INSERT OR IGNORE INTO distill_records (session_id, seq, role, text, window_id, distilled_at)
+       VALUES (?, ?, ?, ?, ?, ?)`
+    );
+    let inserted = 0;
+    for (const r of records) {
+      inserted += stmt.run(r.sessionId, r.seq, r.role, r.text, r.windowId ?? null, r.distilledAt).changes;
+    }
+    return inserted;
+  }
+
+  /**
+   * 到期记录统计（#275 回收报告口径，dry-run 用）。`bytes` 是列文本大小上界。
+   * @returns {{rows: number, bytes: number}}
+   */
+  function distillRecordStats(before) {
+    const row = db.prepare(
+      `SELECT count(*) AS c, COALESCE(SUM(LENGTH(text)), 0) AS b
+         FROM distill_records WHERE distilled_at < ?`
+    ).get(before);
+    return { rows: row.c, bytes: row.b };
+  }
+
+  /**
+   * 删除到期原始记录。返回实际删除行数。
+   *
+   * 只删 distill_records——memory_provenance 的链接**刻意保留**并从此指向空区间，
+   * 面板/CLI 显示「来源已过期」。级联删链接会把「这条记忆有来源、只是来源到期」
+   * 降级成「这条记忆无来源」，把可观测性削成不可观测（#399 删除语义）。
+   */
+  function clearDistillRecords(before) {
+    return db.prepare("DELETE FROM distill_records WHERE distilled_at < ?").run(before).changes;
+  }
+
+  /**
+   * 记一条记忆级溯源链接（#399）：某条记忆派生自某会话的 seq 区间。
+   *
+   * `ON CONFLICT DO NOTHING` 配合 idx_memory_provenance_link 唯一索引吸收同窗口
+   * 重跑的重复链接（否则幂等测试锁会挂）。
+   * @returns {number} 实际插入行数
+   */
+  function saveMemoryProvenance({ memoryId, sessionId, seqStart, seqEnd, createdAt }) {
+    return db.prepare(
+      `INSERT INTO memory_provenance (memory_id, session_id, seq_start, seq_end, created_at)
+       VALUES (?, ?, ?, ?, ?)
+       ON CONFLICT DO NOTHING`
+    ).run(memoryId, sessionId, seqStart, seqEnd, createdAt).changes;
+  }
+
+  /** 一条记忆的全部溯源链接（#399 面板/CLI 读取面）。 */
+  function provenanceFor(memoryId) {
+    return db.prepare(
+      `SELECT memory_id, session_id, seq_start, seq_end, created_at
+         FROM memory_provenance WHERE memory_id = ? ORDER BY created_at, session_id, seq_start`
+    ).all(memoryId);
+  }
+
   // --- 存储生命周期：无损回收（#275 第一批）--------------------------------
   //
   // 两项都零价值判断、零条数变化：行数不变，只把不可重建/不可达的内容丢掉。
@@ -2919,6 +3151,8 @@ export function createStore(path) {
     getUnrecalledSince,
     list,
     all,
+    // #430：有界单列读，写路径（质量过滤）用。
+    recentContents,
     search,
     setEmbedding,
     getEmbeddings,
@@ -2939,6 +3173,7 @@ export function createStore(path) {
     getRecallRun,
     listRecallRuns,
     listRecallRunsSince,
+    purgeRecallRunsOlderThan,
     saveRecallEval,
     getRecallEval,
     listRecallEvals,
@@ -2949,6 +3184,12 @@ export function createStore(path) {
     countLlmAudits,
     getLlmAuditStats,
     deleteOldLlmAudits,
+    // 蒸馏原始记录与记忆级溯源（#399）：窗口凭证的写入/统计/裁剪，链接的读写。
+    saveDistillRecords,
+    distillRecordStats,
+    clearDistillRecords,
+    saveMemoryProvenance,
+    provenanceFor,
     // 存储生命周期（#275 第一批）：无损回收的统计、清理与体积口径。
     dreamRunInputStats,
     clearDreamRunInputs,