@modusensus/dsh-mneme 0.8.5 → 0.8.7

package/src/store.js

@@ -1,5 +1,7 @@
 import { DatabaseSync } from "node:sqlite";
 import { randomUUID } from "node:crypto";
+import { statSync } from "node:fs";
+import { contentHashOf } from "./content-hash.js";
 
 const SCHEMA = `
 CREATE TABLE IF NOT EXISTS memories (
@@ -13,6 +15,7 @@ CREATE TABLE IF NOT EXISTS memories (
   archived    INTEGER NOT NULL DEFAULT 0,
   source      TEXT,
   content_history TEXT,
+  content_hash TEXT,
   embedding   TEXT,
   epistemic_status TEXT NOT NULL DEFAULT 'subjective',
   last_accessed_at  TEXT,
@@ -192,7 +195,8 @@ CREATE TABLE IF NOT EXISTS llm_audit_logs (
   status            TEXT NOT NULL,          -- success | error | skipped
   error_message     TEXT,
   related_memory_ids TEXT,                  -- JSON: ids the call operated on
-  metadata          TEXT                    -- JSON: free-form extras
+  metadata          TEXT,                   -- JSON: free-form extras
+  session_key       TEXT                    -- #254 写入准入的会话键（LLM 调用行恒 NULL）
 );
 CREATE INDEX IF NOT EXISTS idx_llm_audit_timestamp ON llm_audit_logs(timestamp);
 CREATE INDEX IF NOT EXISTS idx_llm_audit_source ON llm_audit_logs(trigger_source);
@@ -405,6 +409,7 @@ function toRow(row) {
     type: row.type,
     title: row.title,
     content: row.content,
+    content_hash: row.content_hash ?? undefined,
     tags: parseTags(row.tags),
     importance: row.importance,
     forgotten: row.forgotten === 1,
@@ -607,7 +612,9 @@ function toLlmAudit(row) {
     status: row.status,
     error_message: row.error_message ?? undefined,
     related_memory_ids: parseJsonArray(row.related_memory_ids),
-    metadata
+    metadata,
+    // #254 写入准入的会话键；LLM 调用行恒 NULL。
+    session_key: row.session_key ?? undefined
   };
 }
 
@@ -711,6 +718,34 @@ export function createStore(path) {
   addColumn("memories", "workspace_scope_source", "ALTER TABLE memories ADD COLUMN workspace_scope_source TEXT");
   addColumn("memories", "scope_decided_at", "ALTER TABLE memories ADD COLUMN scope_decided_at TEXT");
 
+  // #254 计量信号：内容归一化哈希（口径与动机写在 content-hash.js 的文件头）。派生
+  // 列，不参与任何判定——只给「同一内容又被写了一次」当等值锚。索引建在加列之后：
+  // 老库打开时 SCHEMA 的 CREATE TABLE 对既有表不生效，列还不存在，把索引写进 SCHEMA
+  // 会直接报 no such column（与下方 llm_audit_logs.session_key 同理）。
+  addColumn("memories", "content_hash", "ALTER TABLE memories ADD COLUMN content_hash TEXT");
+  // 列序是 content_hash 打头：哈希几乎唯一，等值 seek 就已收窄到候选行，type 只当同
+  // 一次 seek 里的第二列过滤；反过来（type 打头）下面的存量回填就得全表扫——每次打开
+  // 都要把全部正文读一遍。
+  db.exec("CREATE INDEX IF NOT EXISTS idx_memories_content_hash ON memories(content_hash, type)");
+  // 存量回填：老库（含归档区）的行都没有值，而「归档行纳入去重候选集」这条口径正是
+  // 要靠既有归档行出数据。只算 NULL 行、幂等；改口径不是补 NULL 能修好的，要整列重算
+  // （见 content-hash.js 的文件头）。空标题空正文的行算不出锚，跳过不写——否则每次
+  // 打开都要为这些行再跑一遍 UPDATE。
+  {
+    const updates = db
+      .prepare("SELECT id, title, content FROM memories WHERE content_hash IS NULL")
+      .all()
+      .map((row) => [contentHashOf(row), row.id])
+      .filter(([hash]) => hash);
+    if (updates.length) {
+      const stmt = db.prepare("UPDATE memories SET content_hash = ? WHERE id = ? AND content_hash IS NULL");
+      // 一个事务包住整批：逐条自动提交是每行一次 WAL 提交，几千行的存量库上纯属浪费。
+      runAtomically(() => {
+        for (const [hash, id] of updates) stmt.run(hash, id);
+      });
+    }
+  }
+
   // Legacy dream_runs without policy_epoch → backfill with the default epoch.
   addColumn("dream_runs", "policy_epoch", "ALTER TABLE dream_runs ADD COLUMN policy_epoch INTEGER NOT NULL DEFAULT 0");
   addColumn("dream_runs", "run_type", "ALTER TABLE dream_runs ADD COLUMN run_type TEXT NOT NULL DEFAULT 'auto'");
@@ -724,6 +759,13 @@ export function createStore(path) {
   addColumn("mirror_state", "applied_generation", "ALTER TABLE mirror_state ADD COLUMN applied_generation INTEGER NOT NULL DEFAULT 0");
   addColumn("mirror_state", "type_status", "ALTER TABLE mirror_state ADD COLUMN type_status TEXT");
 
+  // #254 写入准入（第一阶段只计量）：准入决策行按会话聚合——「会话内新建了几行」
+  // 与「同话题重复间隔」都靠它算出来，所以会话键必须是可等值查询的列，而不是塞在
+  // metadata 里做 JSON 匹配。列可空且不带 DEFAULT（存量行零重写）。索引建在加列
+  // 之后：老库打开时列还不存在（SCHEMA 的 CREATE TABLE 只对新建库生效）。
+  addColumn("llm_audit_logs", "session_key", "ALTER TABLE llm_audit_logs ADD COLUMN session_key TEXT");
+  db.exec("CREATE INDEX IF NOT EXISTS idx_llm_audit_session ON llm_audit_logs(session_key);");
+
   // Audit peer F: a legacy DB may hold a non-integer generation/applied_generation
   // (pre-v0.3.9 the JS gate truncated with Math.trunc and SQLite's CHECK only
   // enforced >= 0). Such a value is ambiguous — it cannot map to a real applied
@@ -942,6 +984,8 @@ export function createStore(path) {
     const importance = Number.isInteger(memory.importance) ? memory.importance : 3;
     const evidence = Array.isArray(memory.evidence) ? JSON.stringify(memory.evidence) : null;
     const docPath = typeof memory.doc_path === "string" && memory.doc_path.trim() ? memory.doc_path : null;
+    // #254 计量锚：由本行的 title/content 派生，调用方传什么都以这里算出的为准。
+    const contentHash = contentHashOf(memory);
     const embedding = Array.isArray(memory.embedding) && memory.embedding.length
       ? JSON.stringify(memory.embedding)
       : null;
@@ -952,8 +996,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, created_at, updated_at)
-         VALUES (?, ?, ?, ?, ?, ?, 0, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`
+        `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, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`
       ).run(
         id,
         type,
@@ -976,6 +1020,7 @@ export function createStore(path) {
         normalizeOccurredAt(memory.occurred_at),
         evidence,
         docPath,
+        contentHash,
         now,
         now
       );
@@ -988,6 +1033,41 @@ export function createStore(path) {
     return getById(id);
   }
 
+  /**
+   * #254 计量：与本次写入「归一化内容哈希」相同的既有行（去重候选集）。
+   * 结构化锚先收窄成本：按哈希等值 seek（走 idx_memories_content_hash，哈希几乎唯
+   * 一，落在候选集上的行只有几条），再按 type 与 scope 三维过滤——不是全表扫、也不
+   * 逐行比哈希。scope 用 IS 比（NULL 安全）：未标注行互相匹配、与已标注行不匹配，
+   * 与 service.js 去重键（scopeKeyOf）同口径；入参先按 store 自己的 normalizeScopeText
+   * 归一，免得调用方传 " foo " 就漏配。
+   * 归档行与已遗忘行都在集内：#275 的分界是「出口止体积、不止重复」——被质量闸归档
+   * 的同一个事实必须仍能判成重复，否则同样的内容再写一次又是一条新行（#254 拍板：
+   * 归档行纳入去重候选集）。
+   * 排序即取舍：活跃行排在归档/遗忘行之前，再按 updated_at 倒序。LIMIT 先于调用方的
+   * 「活区优先」判断执行，而归档动作本身会顶 updated_at——纯按时间倒序时，同键命中一
+   * 旦超过窗口宽度，活跃行就被归档行挤出候选集，调用方只能看到归档命中，把「活跃重复」
+   * 误报成「归档重复」，恰好把这条信号要分流的两类弄反。
+   * @returns {Array<{id: string, archived: boolean, forgotten: boolean}>} 活跃行优先，其后按最近写入
+   */
+  function findContentHashMatches({ type, hash, agent_scope: agentScope, workspace_scope: workspaceScope, sensitivity, limit = 10 } = {}) {
+    if (!hash || !type) return [];
+    const lim = Number.isInteger(limit) && limit > 0 ? Math.min(limit, 50) : 10;
+    const rows = db.prepare(
+      `SELECT id, archived, forgotten FROM memories
+       WHERE type = ? AND content_hash = ?
+         AND agent_scope IS ? AND workspace_scope IS ? AND sensitivity IS ?
+       ORDER BY archived ASC, forgotten ASC, updated_at DESC, id LIMIT ?`
+    ).all(
+      type,
+      hash,
+      normalizeScopeText(agentScope),
+      normalizeScopeText(workspaceScope),
+      normalizeScopeText(sensitivity),
+      lim
+    );
+    return rows.map((row) => ({ id: row.id, archived: row.archived === 1, forgotten: row.forgotten === 1 }));
+  }
+
   function update(id, patch) {
     const existing = getById(id);
     if (!existing) throw new Error(`memory not found: ${id}`);
@@ -1034,13 +1114,18 @@ export function createStore(path) {
     const nextDecidedAt = patch.scope_decided_at !== undefined
       ? normalizeOccurredAt(patch.scope_decided_at)
       : (existing.scope_decided_at ?? null);
+    // #254：标题或正文变了，锚跟着重算——它是当前内容的派生物，留旧值等于让「这行
+    // 现在装的什么」和标记对不上。
+    const nextTitle = patch.title ?? existing.title;
+    const nextContent = patch.content ?? existing.content;
+    const contentHash = contentHashOf({ title: nextTitle, content: nextContent });
     runAtomically(() => {
       db.prepare(
-        `UPDATE memories SET type=?, title=?, content=?, tags=?, importance=?, source=?, content_history=?, quality_score=?, embedding=?, epistemic_status=?, agent_scope=?, workspace_scope=?, agent_scope_source=?, workspace_scope_source=?, scope_decided_at=?, evidence=?, updated_at=? WHERE id=?`
+        `UPDATE memories SET type=?, title=?, content=?, tags=?, importance=?, source=?, content_history=?, quality_score=?, embedding=?, epistemic_status=?, agent_scope=?, workspace_scope=?, agent_scope_source=?, workspace_scope_source=?, scope_decided_at=?, evidence=?, content_hash=?, updated_at=? WHERE id=?`
       ).run(
         type,
-        patch.title ?? existing.title,
-        patch.content ?? existing.content,
+        nextTitle,
+        nextContent,
         JSON.stringify(patch.tags ?? existing.tags),
         Number.isInteger(patch.importance) ? patch.importance : existing.importance,
         patch.source !== undefined ? patch.source : (existing.source ?? null),
@@ -1054,6 +1139,7 @@ export function createStore(path) {
         nextWorkspaceSource,
         nextDecidedAt,
         evidence,
+        contentHash,
         now,
         id
       );
@@ -1115,15 +1201,19 @@ export function createStore(path) {
     // dirty == false — recoverMirror sees no debt and the mirror stays stale.
     // Wrapping both in one transaction means a CAS miss rolls back cleanly too
     // (no write, no generation bump).
+    // 同 update：#254 的锚随标题/正文重算（CAS 路径也改这两列）。
+    const nextTitle = patch.title ?? existing.title;
+    const nextContent = patch.content ?? existing.content;
+    const contentHash = contentHashOf({ title: nextTitle, content: nextContent });
     let applied = false;
     runAtomically(() => {
       const result = db.prepare(
-        `UPDATE memories SET type=?, title=?, content=?, tags=?, importance=?, source=?, content_history=?, quality_score=?, embedding=?, epistemic_status=?, updated_at=?
+        `UPDATE memories SET type=?, title=?, content=?, tags=?, importance=?, source=?, content_history=?, quality_score=?, embedding=?, epistemic_status=?, content_hash=?, updated_at=?
          WHERE id=? AND updated_at=?`
       ).run(
         type,
-        patch.title ?? existing.title,
-        patch.content ?? existing.content,
+        nextTitle,
+        nextContent,
         JSON.stringify(patch.tags ?? existing.tags),
         Number.isInteger(patch.importance) ? patch.importance : existing.importance,
         patch.source !== undefined ? patch.source : (existing.source ?? null),
@@ -1131,6 +1221,7 @@ export function createStore(path) {
         qualityScore,
         embedding,
         epistemicStatus,
+        contentHash,
         now,
         id,
         expectedUpdatedAt
@@ -1182,15 +1273,15 @@ export function createStore(path) {
   function demoteToSummary(id, summary, { minRefTimeMs } = {}) {
     let changed = false;
     runAtomically(() => {
-      const row = db.prepare("SELECT last_accessed_at, content, _full_content FROM memories WHERE id = ?").get(id);
+      const row = db.prepare("SELECT title, last_accessed_at, content, _full_content FROM memories WHERE id = ?").get(id);
       if (!row || row._full_content) return;
       if (minRefTimeMs !== undefined && row.last_accessed_at) {
         const lastMs = Date.parse(row.last_accessed_at);
         if (lastMs >= minRefTimeMs) return; // touched after snapshot — still hot
       }
       db.prepare(
-        "UPDATE memories SET content = ?, _full_content = ?, updated_at = ? WHERE id = ?"
-      ).run(summary, row.content, nowIso(), id);
+        "UPDATE memories SET content = ?, _full_content = ?, content_hash = ?, updated_at = ? WHERE id = ?"
+      ).run(summary, row.content, contentHashOf({ title: row.title, content: summary }), nowIso(), id);
       incrementGeneration();
       changed = true;
     });
@@ -1201,11 +1292,11 @@ export function createStore(path) {
   function restoreContent(id) {
     let changed = false;
     runAtomically(() => {
-      const row = db.prepare("SELECT content, _full_content FROM memories WHERE id = ?").get(id);
+      const row = db.prepare("SELECT title, content, _full_content FROM memories WHERE id = ?").get(id);
       if (!row || !row._full_content) return;
       db.prepare(
-        "UPDATE memories SET content = ?, _full_content = NULL, updated_at = ? WHERE id = ?"
-      ).run(row._full_content, nowIso(), id);
+        "UPDATE memories SET content = ?, _full_content = NULL, content_hash = ?, updated_at = ? WHERE id = ?"
+      ).run(row._full_content, contentHashOf({ title: row.title, content: row._full_content }), nowIso(), id);
       incrementGeneration();
       changed = true;
     });
@@ -1532,6 +1623,22 @@ export function createStore(path) {
     return rows.map(toDreamRun);
   }
 
+  // Issue #89：上次实际开跑时刻（epoch ms），从审计表恢复——调度器的 lastRunAt
+  // 只活在内存里，进程重启即归零，闸门对新实例放行 → 重启后立刻连发。审计表
+  // 本来就逐 run 落库（failed/degraded 也算 run），直接读它就是事实源，零迁移。
+  function lastDreamRunAt(runType = null) {
+    const row = runType
+      ? db.prepare(
+          "SELECT created_at FROM dream_runs WHERE run_type = ? ORDER BY created_at DESC, id LIMIT 1"
+        ).get(runType)
+      : db.prepare(
+          "SELECT created_at FROM dream_runs ORDER BY created_at DESC, id LIMIT 1"
+        ).get();
+    if (!row?.created_at) return 0;
+    const ms = Date.parse(row.created_at);
+    return Number.isFinite(ms) ? ms : 0;
+  }
+
   /**
    * Latest ruling-rule version seen on the audit trail. policy_epoch is a config
    * value stamped onto each run by the caller; reading the newest row's epoch
@@ -1750,8 +1857,8 @@ export function createStore(path) {
     db.prepare(
       `INSERT INTO llm_audit_logs (timestamp, trigger_source, operation_type, model_id,
         input_tokens, output_tokens, total_tokens, cost_usd, duration_ms, status,
-        error_message, related_memory_ids, metadata)
-       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`
+        error_message, related_memory_ids, metadata, session_key)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`
     ).run(
       entry.timestamp ?? now,
       entry.trigger_source,
@@ -1767,12 +1874,13 @@ export function createStore(path) {
       JSON.stringify(entry.related_memory_ids ?? []),
       entry.metadata !== undefined
         ? (typeof entry.metadata === "string" ? entry.metadata : JSON.stringify(entry.metadata))
-        : null
+        : null,
+      entry.session_key ?? null
     );
     return toLlmAudit(db.prepare("SELECT * FROM llm_audit_logs ORDER BY id DESC LIMIT 1").get());
   }
 
-  function listLlmAudits({ limit = 50, offset = 0, source } = {}) {
+  function listLlmAudits({ limit = 50, offset = 0, source, sessionKey } = {}) {
     const { limit: lim, offset: off } = sanitizePage(limit, offset, 50);
     const clauses = [];
     const params = [];
@@ -1780,6 +1888,11 @@ export function createStore(path) {
       clauses.push("trigger_source = ?");
       params.push(source);
     }
+    // #254 写入准入：会话内的话题回填只需要该会话的行（走 idx_llm_audit_session）。
+    if (sessionKey) {
+      clauses.push("session_key = ?");
+      params.push(sessionKey);
+    }
     const where = clauses.length ? `WHERE ${clauses.join(" AND ")}` : "";
     const rows = db.prepare(
       `SELECT * FROM llm_audit_logs ${where} ORDER BY timestamp DESC, id DESC LIMIT ? OFFSET ?`
@@ -1787,13 +1900,17 @@ export function createStore(path) {
     return rows.map(toLlmAudit);
   }
 
-  function countLlmAudits({ source } = {}) {
+  function countLlmAudits({ source, sessionKey } = {}) {
     const clauses = [];
     const params = [];
     if (source) {
       clauses.push("trigger_source = ?");
       params.push(source);
     }
+    if (sessionKey) {
+      clauses.push("session_key = ?");
+      params.push(sessionKey);
+    }
     const where = clauses.length ? `WHERE ${clauses.join(" AND ")}` : "";
     return db.prepare(`SELECT count(*) AS c FROM llm_audit_logs ${where}`).get(...params).c;
   }
@@ -1842,6 +1959,106 @@ export function createStore(path) {
     return db.prepare("DELETE FROM llm_audit_logs WHERE timestamp < ?").run(before).changes;
   }
 
+  // --- 存储生命周期：无损回收（#275 第一批）--------------------------------
+  //
+  // 两项都零价值判断、零条数变化：行数不变，只把不可重建/不可达的内容丢掉。
+  // 删行不在本模块里（维护者拍板 3：裁列同意、删行不同意）——dream_runs 的骨架、
+  // LLM 决策原文与 receipt 永不删。
+
+  /**
+   * 历史 run 的输入快照统计（#275 A 项，dry-run 用）。
+   *
+   * `input` 这一列的含义**按 run_type 分叉**：auto / sleep 的 run 存的是当时的记忆库
+   * 快照（可由记忆库重建），organize 的 run 存的是 apply 的重放载荷——`organize.js`
+   * 的 apply 直接读它（`snapshot = Array.isArray(report.input) ? report.input : []`），
+   * 置空会让 apply 找不到候选、静默什么都不做却照写回执并盖上 applied_at，那份报告
+   * 从此永远重放不了。所以 organize 行不在可清范围里（同一列，两种语义，只能按 type 分）。
+   *
+   * `bytes` 是列文本大小，只作上界（真实释放看 VACUUM 前后）。
+   * @returns {{runs: number, bytes: number}}
+   */
+  function dreamRunInputStats(before) {
+    const row = db.prepare(
+      `SELECT count(*) AS c, COALESCE(SUM(LENGTH(input)), 0) AS b
+         FROM dream_runs
+        WHERE input IS NOT NULL AND created_at < ? AND run_type != 'organize'`
+    ).get(before);
+    return { runs: row.c, bytes: row.b };
+  }
+
+  /** 置空历史 run 的输入快照（organize 的重放载荷除外）。返回实际改动的行数。 */
+  function clearDreamRunInputs(before) {
+    return db.prepare(
+      `UPDATE dream_runs SET input = NULL
+        WHERE input IS NOT NULL AND created_at < ? AND run_type != 'organize'`
+    ).run(before).changes;
+  }
+
+  /**
+   * 归档行仍带的向量统计（#275 B 项）。检索 SQL 恒带 `archived = 0`，所以这部分
+   * 向量按定义不可达，清掉不改变任何检索结果。
+   * @returns {{rows: number, bytes: number}}
+   */
+  function archivedEmbeddingStats() {
+    const row = db.prepare(
+      `SELECT count(*) AS c, COALESCE(SUM(LENGTH(embedding)), 0) AS b
+         FROM memories WHERE archived = 1 AND embedding IS NOT NULL`
+    ).get();
+    return { rows: row.c, bytes: row.b };
+  }
+
+  /** 清掉归档行的向量。返回实际改动行数。 */
+  function clearArchivedEmbeddings() {
+    const changed = db.prepare(
+      "UPDATE memories SET embedding = NULL WHERE archived = 1 AND embedding IS NOT NULL"
+    ).run().changes;
+    // Issue #202 的单条失效点在 setEmbedding 里，批量清走不到它——整表清缓存最省事，
+    // 代价只是活跃行下次检索多解析一次（FIFO 上限 4000，自愈）。
+    if (changed > 0) embeddingCache.clear();
+    return changed;
+  }
+
+  /**
+   * 库文件与页统计（#275 报告口径）：回收收益按 VACUUM 前后体积量，不按列字节估——
+   * 实际释放来自溢出页与索引页的回收，列文本大小只是上界。
+   *
+   * 体积是**磁盘足迹**：WAL 模式下主文件之外还有 `-wal` / `-shm`，只量主文件会把
+   * 「刚清完还没落盘」的那部分算漏（实测过：VACUUM 后主文件可能一动不动，要等一次
+   * checkpoint）。所以三份一起量；`:memory:` 库没有文件。
+   */
+  function storageStats() {
+    const pageSize = db.prepare("PRAGMA page_size").get().page_size;
+    const pageCount = db.prepare("PRAGMA page_count").get().page_count;
+    const freelistCount = db.prepare("PRAGMA freelist_count").get().freelist_count;
+    const sizeOf = (p) => {
+      try {
+        return statSync(p).size;
+      } catch {
+        return 0;
+      }
+    };
+    let fileBytes = null;
+    if (typeof path === "string" && path !== ":memory:") {
+      fileBytes = sizeOf(path) + sizeOf(`${path}-wal`) + sizeOf(`${path}-shm`);
+    }
+    return { path: typeof path === "string" ? path : null, pageSize, pageCount, freelistCount, fileBytes };
+  }
+
+  /**
+   * 整库 VACUUM（#275 的手动步骤）：代价 O(库大小) 且需要排他写锁，所以只在显式
+   * 入口里跑，绝不挂启动路径、也不开 auto_vacuum。
+   *
+   * 收尾补一次 `wal_checkpoint(TRUNCATE)`：WAL 模式下 VACUUM 重排的是主文件里的页，
+   * 已回收的空间可能还挂在 WAL 里，不 checkpoint 就量不到体积下降——报告口径要的是
+   * 真实释放量，量不到等于没做（评审实测：VACUUM 后主文件长度不变，checkpoint 后才降）。
+   */
+  function vacuum() {
+    const started = Date.now();
+    db.exec("VACUUM");
+    db.exec("PRAGMA wal_checkpoint(TRUNCATE)");
+    return { duration_ms: Date.now() - started };
+  }
+
   // --- failure memories ----------------------------------------------------
 
   /**
@@ -2469,6 +2686,8 @@ export function createStore(path) {
     saveDocument,
     update,
     compareAndUpdate,
+    // #254：写入准入的内容哈希候选集（只读）。
+    findContentHashMatches,
     remove,
     setForget,
     setArchived,
@@ -2486,6 +2705,7 @@ export function createStore(path) {
     needsEmbedding,
     searchVector,
     saveDreamRun,
+    lastDreamRunAt,
     getDreamRun,
     listDreamRuns,
     getLatestPolicyEpoch,
@@ -2506,6 +2726,13 @@ export function createStore(path) {
     countLlmAudits,
     getLlmAuditStats,
     deleteOldLlmAudits,
+    // 存储生命周期（#275 第一批）：无损回收的统计、清理与体积口径。
+    dreamRunInputStats,
+    clearDreamRunInputs,
+    archivedEmbeddingStats,
+    clearArchivedEmbeddings,
+    storageStats,
+    vacuum,
     saveFailure,
     listFailures,
     getFailureStats,

package/src/tools.js

@@ -1,11 +1,12 @@
 import { defineTool } from "@deepseek-ai/dsh-tools";
-import { createScopeResolver, normalizeExplicitScope } from "./scope.js";
+import { createScopeResolver, normalizeExplicitScope, sessionKeyOf } from "./scope.js";
 import { describeLocalRuntime, resolveRuntimeEntry } from "./runtime/loader.js";
 import { defaultRuntimeDir } from "./runtime/layout.js";
 import { hostModulesDir, loadRuntimeManifest, provisionRuntime } from "./runtime/provision.js";
 import { matchesPlatform } from "./runtime/closure.js";
 import { verifyPayload } from "./runtime/verify.js";
 import { TOOL_GUIDE } from "./guide.js";
+import { injectChildEnabled } from "./config.js";
 
 const TEXT_OUTPUT = (text) => [{ type: "text", text }];
 // Per-registry tool-name registry: guards against duplicate registration on
@@ -84,11 +85,13 @@ export function createTools(ctx, service, config, embedder) {
   // flag 关闭时恒返回 null——写入不标注，检索不加权，行为与 A1 前完全一致。
   // logger 透传：registry 反查失败时 warnOnce 才有出口（否则静默降级无观测）。
   const resolveSessionScope = createScopeResolver({ ctx, config, logger: ctx.logger });
-  // #249 第一批：能力说明（injectGuidanceEnabled）开启时，给「何时用」最有歧义
-  // 的两个工具补一句判断指引。工具描述常驻、不进每轮上下文，这个位子零注入
-  // 成本；关闭时描述逐字节不变，也不动其他工具的文案。
+  // #249 能力说明（injectGuidanceEnabled）：开启时给「何时用」最有歧义的两个
+  // 工具补一句判断指引。工具描述常驻、不进每轮上下文，这个位子零注入成本；
+  // 关闭时描述逐字节不变，也不动其他工具的文案。
+  // 它是注入父开关的子项（#249 第二批）：`autoInject` 关掉时这里同样不生效——
+  // 工具描述是这个子项唯一住在注入器之外的落点，不在闸门内就漏了。
   const withToolGuide = (name, description) =>
-    config?.injectGuidanceEnabled === true && TOOL_GUIDE[name] ? `${description}${TOOL_GUIDE[name]}` : description;
+    injectChildEnabled(config, "injectGuidanceEnabled") && TOOL_GUIDE[name] ? `${description}${TOOL_GUIDE[name]}` : description;
 
   // 复核项 4（issue #170）：strictScope 下他 scope（explicit）的行对工具侧按
   // 「不存在」处理——update/delete 与 memory_get 同款无存在性泄漏。strictScope
@@ -162,6 +165,10 @@ export function createTools(ctx, service, config, embedder) {
           ? { value: normalizeExplicitScope(args.workspace_scope), source: "explicit" }
           : autoStamping && scope ? { value: scope.workspace_scope, source: "auto" } : null;
         const { action, memory } = service.saveWithDedupe({
+          // #254 写入准入（第一阶段只计量）的计数单位：会话键作为瞬时字段随写入
+          // 传递（与 _mergeInto / _overwrite 同款约定，不落库）。缺会话身份的宿主
+          // 返回 null = 这次写入不进预算。
+          _sessionKey: sessionKeyOf(exec),
           type: args.type,
           title: args.title,
           content: args.content,
@@ -482,7 +489,11 @@ export function createTools(ctx, service, config, embedder) {
         "intersects evidence with real memory ids (all-fabricated evidence is rejected; unknown ids are dropped and the row " +
         "is tagged evidence_degraded), and dedupes: re-registering the same path or title supersedes the old row (the old " +
         "file is never touched; content_history stays traceable), while a merely near-duplicate summary of a different " +
-        "document row is rejected — update that row instead. Use for 'where is the conclusion doc for this project?' " +
+        "document row is rejected — update that row instead. On success the absorbed atomic evidence rows leave the active " +
+        "face in the same transaction (recoverable, nothing deleted); constraint/preference rows and other " +
+        "document/summary rows are never auto-archived, and keep_evidence_active: true opts out. Ids this same document " +
+        "absorbed on an earlier version still count as its evidence, so re-registering a new version is not read as " +
+        "fabricated evidence. Use for 'where is the conclusion doc for this project?' " +
         "lookups; atomic facts still go to memory_save.",
       parameters: {
         path: { type: "string", required: true, description: "Absolute path of the document file (~ is expanded); must already exist as a non-empty regular file. The full text stays agent-owned — this pipeline never touches it." },
@@ -490,7 +501,8 @@ export function createTools(ctx, service, config, embedder) {
         summary: { type: "string", required: true, description: "One-paragraph summary stored in the DB and used for injection (any language)" },
         tags: { type: "array", items: { type: "string" }, description: "Optional tags (English recommended)" },
         importance: { type: "integer", description: "1-5 (default 3); the summary row injects at the next-priority tier within documentInjectBudget when importance >= threshold" },
-        evidence: { type: "array", items: { type: "string" }, description: "Memory ids this document is grounded in; each is verified against the store (fabricated evidence is rejected; unknown/archived ids are dropped and the row is tagged evidence_degraded)" },
+        evidence: { type: "array", items: { type: "string" }, description: "Memory ids this document is grounded in (atomic facts, not other pointer rows); each is verified against the store — fabricated evidence is rejected, unknown/archived ids are dropped and the row is tagged evidence_degraded, except ids this same document absorbed on an earlier version, which stay its evidence. On success the absorbed atomic rows leave the active face unless keep_evidence_active is true." },
+        keep_evidence_active: { type: "boolean", description: "Opt out of archiving the evidence rows absorbed by this document. Default false: after a successful registration the absorbed atomic rows leave the active face (recoverable, nothing deleted; constraint/preference rows and other document/summary rows are never auto-archived)." },
         source: { type: "string", description: "Optional provenance" },
         sensitivity: { type: "string", description: "Optional sensitivity label (free-form, e.g. personal). Part of the supersede matching key — same path/title with a different sensitivity stays a separate document." },
         agent_scope: { type: "string", description: "Optional explicit agent-scope declaration (issue #170): 'global' or '*' makes this document visible to every agent; any other value narrows it to that label. Overrides the automatic carrier label for this write; honored even when automatic scope labeling is disabled." },
@@ -506,12 +518,13 @@ export function createTools(ctx, service, config, embedder) {
             superseded_id: { type: "string" },
             evidence_kept: { type: "integer", required: true },
             evidence_dropped: { type: "integer", required: true },
+            evidence_archived: { type: "integer", required: true },
             degraded: { type: "boolean", required: true }
           }
         },
         render: (_args, value) => {
           const sup = value.superseded_id ? ` (supersedes ${value.superseded_id})` : "";
-          const ev = ` | evidence: ${value.evidence_kept} kept, ${value.evidence_dropped} dropped${value.degraded ? " [degraded]" : ""}`;
+          const ev = ` | evidence: ${value.evidence_kept} kept, ${value.evidence_dropped} dropped, ${value.evidence_archived} archived${value.degraded ? " [degraded]" : ""}`;
           return TEXT_OUTPUT(`document ${value.action}: ${value.id}${sup}${ev}`);
         }
       },
@@ -550,13 +563,18 @@ export function createTools(ctx, service, config, embedder) {
           ...(args.sensitivity !== undefined ? { sensitivity: args.sensitivity } : {}),
           ...(agentLabel ? { agent_scope: agentLabel.value, agent_scope_source: agentLabel.source } : {}),
           ...(workspaceLabel ? { workspace_scope: workspaceLabel.value, workspace_scope_source: workspaceLabel.source } : {})
-        }, { hiddenEvidenceIds: hiddenEvidence });
+        }, {
+          hiddenEvidenceIds: hiddenEvidence,
+          // 默认开着归档（#275 拍板 5）；agent 显式要保留活跃面时走 keep_evidence_active。
+          archiveEvidence: args.keep_evidence_active !== true
+        });
         return {
           action: result.action,
           id: result.memory.id,
           ...(result.superseded ? { superseded_id: result.superseded.id } : {}),
           evidence_kept: result.evidence_kept,
           evidence_dropped: result.evidence_dropped,
+          evidence_archived: result.evidence_archived,
           degraded: result.degraded
         };
       }