@modusensus/dsh-mneme 0.8.5 → 0.8.7

package/lib/index.js

@@ -1,6 +1,10 @@
 import { createStore } from "./store.js";
 import { createMirror, TYPE_FILE } from "./mirror.js";
+import { createDocumentIndex } from "./document-index.js";
+import { resolveDocumentDir } from "./document.js";
 import { createService } from "./service.js";
+// #254 写入准入（第一阶段只计量，不拦截）：见 src/write-admission.js 的文件头。
+import { createWriteAdmission } from "./write-admission.js";
 import { createTools } from "./tools.js";
 import { createInjector } from "./inject.js";
 import { createSummarizer } from "./summarize.js";
@@ -8,6 +12,8 @@ import { createDreamScheduler } from "./dream.js";
 import { createSleepScheduler, runSleep } from "./dream/sleep.js";
 import { createApi } from "./api.js";
 import { createStandaloneApi } from "./api-standalone.js";
+// #275 存储生命周期第一批：无损回收（手动入口，不挂启动路径）。
+import { createMaintenance } from "./maintenance.js";
 import { createSettings } from "./settings.js";
 import { createCommandManager } from "./commands.js";
 import { createEmbedder } from "./embedding.js";
@@ -43,7 +49,15 @@ export { Config };
 // unit-testable; the extractor only ever sees a callLLM(messages, options)
 // => Promise<string>. The route always carries a real provider/model (dsh-llm
 // GenerateOptions requires both) — never a bare stream.
-export function createEntityStreamAdapter({ llm, agentDefaultModel, logger }) {
+//
+// Issue #250: it also accounts for itself. Entity extraction is the background
+// LLM path that runs on every memory write, yet it never reached
+// llm_audit_logs — the adapter only ever held an llm handle, so it had no way
+// to call service.saveLlmAudit. It now takes service (+ config for the shared
+// llmAudit.enabled gate) and writes one row per stream attempt, matching the
+// contract of runAuditedLlm in dream.js: a rejected effort attempt records its
+// own error row and the retry records its own success row.
+export function createEntityStreamAdapter({ llm, agentDefaultModel, logger, service, config }) {
   return async function streamEntityText(messages, options = {}) {
     let route = {};
     if (options.provider) route.provider = options.provider;
@@ -58,8 +72,38 @@ export function createEntityStreamAdapter({ llm, agentDefaultModel, logger }) {
       } catch { /* fall through to whatever route we already have */ }
     }
     const effort = options.reasoningEffort;
+    // 没有解析出 provider/model 就没有可归属的模型——与 dream 的 resolveRoute
+    // 无路由早退同口径，那种情况不写审计行。
+    const modelId = route.provider && route.model ? `${route.provider}:${route.model}` : "";
     const tryStream = (withEffort) => {
       let text = "";
+      let inputTokens = 0;
+      let outputTokens = 0;
+      const startedAt = Date.now();
+      const timestamp = new Date(startedAt).toISOString();
+      // 记账是 best-effort：写审计行失败只 warn，绝不反噬抽取本身（CONTRIBUTING
+      // 的 fail-safe 硬约定）。
+      const writeAudit = (status, errorMessage) => {
+        if (config?.llmAudit?.enabled === false || !modelId || typeof service?.saveLlmAudit !== "function") return;
+        try {
+          service.saveLlmAudit({
+            timestamp,
+            trigger_source: "entityExtract",
+            operation_type: "entity_extract",
+            model_id: modelId,
+            input_tokens: inputTokens,
+            output_tokens: outputTokens,
+            total_tokens: inputTokens + outputTokens,
+            cost_usd: 0,
+            duration_ms: Date.now() - startedAt,
+            status,
+            error_message: errorMessage,
+            related_memory_ids: []
+          });
+        } catch (auditError) {
+          logger?.warn?.(`dsh-mneme: entity extraction llm audit write failed: ${String(auditError)}`);
+        }
+      };
       return (async () => {
         for await (const chunk of llm.stream({
           ...route,
@@ -68,11 +112,26 @@ export function createEntityStreamAdapter({ llm, agentDefaultModel, logger }) {
           messages
         })) {
           if (chunk.type === "text-delta" && typeof chunk.text === "string") text += chunk.text;
-          if (chunk.type === "finish" && (chunk.reason?.kind === "error" || chunk.reason?.kind === "aborted")) return undefined;
+          // DSH 的 StreamChunk 契约把用量嵌在 chunk.usage（TokenUsage）；兼容直接
+          // 平铺在 chunk 上的旧形态。归一放在这里，下面只需认平铺形状——与
+          // dream.js 的 streamText 同一处理。
+          if (chunk.type === "usage") {
+            const u = chunk.usage ?? chunk;
+            const i = u.input_tokens ?? u.inputTokens ?? u.prompt_tokens ?? u.promptTokens;
+            const o = u.output_tokens ?? u.outputTokens ?? u.completion_tokens ?? u.completionTokens;
+            if (Number.isFinite(i)) inputTokens = i;
+            if (Number.isFinite(o)) outputTokens = o;
+          }
+          if (chunk.type === "finish" && (chunk.reason?.kind === "error" || chunk.reason?.kind === "aborted")) {
+            writeAudit("error", "llm stream aborted or errored");
+            return undefined;
+          }
         }
+        writeAudit("success", null);
         return text;
       })().catch((err) => {
         logger?.warn?.(`[dsh-mneme] entity extraction llm stream failed: ${String(err)}`);
+        writeAudit("error", String(err?.message ?? err));
         return undefined;
       });
     };
@@ -140,15 +199,6 @@ export const apply = (ctx, config) => {
   try {
     store.deleteOldFailures(new Date(Date.now() - 90 * 86400000).toISOString());
   } catch { /* non-fatal */ }
-  // Bug8: enforce llm_audit_logs retention on boot (config.llmAudit.retentionDays,
-  // default 90). Best-effort like the failure prune — the audit trail is
-  // bookkeeping and a failed purge must never block plugin boot.
-  try {
-    if (rawCfg.llmAudit?.enabled !== false) {
-      const retentionMs = Number.isInteger(rawCfg.llmAudit?.retentionDays) ? rawCfg.llmAudit.retentionDays : 90;
-      store.deleteOldLlmAudits(new Date(Date.now() - retentionMs * 86400000).toISOString());
-    }
-  } catch { /* non-fatal */ }
 
   // User-configurable settings (profile, rules, panel mode, standalone API
   // token) share the same SQLite file in dedicated tables, isolated from
@@ -187,10 +237,46 @@ export const apply = (ctx, config) => {
     cfg[objKey] = { ...(cfg[objKey] ?? {}), ...sub };
   }
 
+  // Bug8 的启动期清理放在装配之后：面板把 llmAudit.* 写进 kv、经 nestedFlags 合进
+  // cfg，而写入侧（dream / summarize / 写入准入）读的都是装配后的 cfg——清理若读
+  // rawCfg，面板改了保留期它不认，更糟的是「开不开审计」与写入侧可能取到不同的值
+  // （raw 说关 → 不清理，cfg 说开 → 照写，审计表就无保留期地长）。保留期默认 90 天、
+  // 失败只 warn，与失败表清理同款：账本清理绝不许挡住插件启动。
+  try {
+    if (cfg.llmAudit?.enabled !== false) {
+      const retentionMs = Number.isInteger(cfg.llmAudit?.retentionDays) ? cfg.llmAudit.retentionDays : 90;
+      store.deleteOldLlmAudits(new Date(Date.now() - retentionMs * 86400000).toISOString());
+    }
+  } catch { /* non-fatal */ }
+
   // 记忆语言（memory.language）：本实例逐层传入 inject / summarize / dream /
   // sleep / mirror，多实例（如 agent preset 内挂载）互不影响。
   const mirror = createMirror(memoryDir, langOf(cfg));
-  const service = createService({ store, mirror, config: cfg, logger: ctx.logger });
+
+  // #296 第二批：managed 文档目录。解析与 memoryDir 同一套（空 = 跟随 memoryDir 的
+  // <memoryDir>/documents/，~ 展开，相对路径落在 memoryDir 下）。索引对象总是建：
+  // 闸关时它只承担「清掉陈旧 index.md」这一件事，与 documents.md 在闸关时被镜像删
+  // 掉同一口径。建目录与写索引失败都只 warn，不阻断插件加载（它们是机器产物）。
+  const documentDir = resolveDocumentDir(memoryDir, cfg.documentDir);
+  const documentIndex = createDocumentIndex(documentDir, langOf(cfg));
+  if (cfg.documentMemoryEnabled === true) {
+    const ensured = documentIndex.ensure();
+    if (!ensured.ok) {
+      ctx.logger?.warn?.(`[dsh-mneme] documentDir is not writable: ${documentDir}: ${ensured.error}`);
+    }
+    // 启动即渲染一次：索引不该等到第一次业务写才存在（删掉它之后重启也能自愈）。
+    const synced = documentIndex.sync(store.list({ type: "document", limit: null }));
+    if (!synced.ok) ctx.logger?.warn?.(`[dsh-mneme] document index sync failed: ${synced.error}`);
+  } else {
+    documentIndex.remove();
+  }
+
+  // 写入准入实例：本批次只做计量（决策恒放行、写审计行），所以不需要新开关——它
+  // 不改变任何写入行为，也不新增拦截分支；既有的 llmAudit.enabled 关掉时它同样
+  // 不写（那个开关连审计行的启动期清理一起关掉）。第二阶段把拦截打开时才按仓库
+  // 惯例引入 opt-in 默认关的配置键，届时只改这一个实例的构造与 service 的调用点。
+  const writeAdmission = createWriteAdmission({ store, config: cfg, logger: ctx.logger });
+  const service = createService({ store, mirror, config: cfg, logger: ctx.logger, documentIndex, writeAdmission });
 
   // F-NEW-03: if the mirror sync failed last run (persisted dirty state), retry
   // a safe re-render at boot so a stale mirror converges without needing a
@@ -273,6 +359,9 @@ export const apply = (ctx, config) => {
         dimension: cfg.localEmbedDimension,
         device: cfg.localEmbedDevice,
         batchSize: cfg.localEmbedBatchSize,
+        // 池化方式必须与模型的训练口径一致（BGE 系 = CLS）。它既进 embed() 的调用，
+        // 也进 modelHash —— 池化改了就是换向量空间，既有索引会被判失配并重建。
+        pooling: cfg.localEmbedPooling,
         cacheDir: cfg.embedModelCacheDir,
         runtimeDir: cfg.runtimeDir,
         // #188：embedModelMirror 接成 transformers 的下载镜像（此前死配置）。
@@ -403,6 +492,7 @@ export const apply = (ctx, config) => {
       minIntervalMs: (cfg.dreamMinIntervalMinutes ?? 0) * 60000,
       logger: ctx.logger,
       semantic: { embedder, vectorIndex },
+      lastRunAtSeed: store.lastDreamRunAt("auto"),
       onRun: () => (dream ? dream.runDream(ctx, service, cfg) : Promise.resolve({ ok: true, skipped: true }))
     });
     service.setDreamHook(() => dream.maybeSchedule(service));
@@ -419,6 +509,7 @@ export const apply = (ctx, config) => {
       service,
       config: cfg,
       logger: ctx.logger,
+      lastRunAtSeed: store.lastDreamRunAt("sleep"),
       onRun: (signal) => (sleep ? runSleep(ctx, service, cfg, ctx.logger, { embedder, vectorIndex }, signal) : Promise.resolve({ ok: true, skipped: true }))
     });
     service.setSleepHook(() => sleep.noteWrite());
@@ -442,7 +533,11 @@ export const apply = (ctx, config) => {
       const streamEntityText = createEntityStreamAdapter({
         llm: ctx.llm,
         agentDefaultModel: ctx.agentDefaultModel,
-        logger: ctx.logger
+        logger: ctx.logger,
+        // Issue #250: the adapter needs service to write its llm_audit_logs row
+        // (it never had it) and config for the shared llmAudit.enabled gate.
+        service,
+        config: cfg
       });
       service.setEntityExtractor((memory) =>
         extractEntities(memory, { store, config: cfg, callLLM: streamEntityText, logger: ctx.logger })
@@ -487,13 +582,19 @@ export const apply = (ctx, config) => {
     disposers.push(api.dispose);
   }
 
+  // #275 存储生命周期第一批：无损回收的手动入口。刻意不挂启动路径、不接定时器——
+  // 这一步是不可逆的内容丢弃，只由人显式触发（`dsh-mneme reclaim`）。实例在这里建、
+  // 在 standalone API 上暴露，是为了让 CLI 能在插件进程内跑（VACUUM 要排他锁，跟宿主
+  // 抢锁的那条路走不通）。
+  const maintenance = createMaintenance({ store, config: cfg, logger: ctx.logger });
+
   // Standalone external API (v0.7.12): plain node:http server for ecosystem
   // integrations outside the DSH host. Persisted external_api settings win
   // over the bundle config (enabled/port); the Bearer token lives in the same
   // kv and is auto-generated on first boot by createStandaloneApi. Binding a
   // non-loopback host is the operator's documented responsibility.
   if ((settings.getExternalApi?.()?.enabled ?? cfg.externalApiEnabled) === true) {
-    const standalone = createStandaloneApi({ service, store, config: cfg, logger: ctx.logger, settings });
+    const standalone = createStandaloneApi({ service, store, config: cfg, logger: ctx.logger, settings, maintenance });
     disposers.push(() => standalone.server.close());
     standalone.ready.catch((error) => {
       ctx.logger?.warn?.(`[dsh-mneme] standalone API failed to start: ${String(error)}`);

package/lib/inject.js

@@ -3,6 +3,7 @@ import { createHotMemory } from "./hot-memory.js";
 import { STR, langOf } from "./lang.js";
 import { MEMORY_GUIDE_SECTION } from "./guide.js";
 import { adaptiveInjectBudget } from "./search/adaptive.js";
+import { injectChildEnabled } from "./config.js";
 
 // Issue #179：注入预览的数据底座。systemPrompt 渲染是同步回调，面板只能事后
 // 拉取，所以在这里旁路缓存「最近一帧组装」——快照就是本次渲染用过的同一份
@@ -283,12 +284,15 @@ export function createInjector(ctx, service, settings, config) {
     return escapePromptVars(lines.join("\n"));
   }
 
-  // #249 第一批：能力说明的系统提示段。order 150 = 插件指引段的既有惯例
+  // #249 能力说明的系统提示段。order 150 = 插件指引段的既有惯例
   // （ACP 的 ACP_SYSTEM_PROMPT 与 mnemon 的 routing 段都在 150）。文本是常量、
   // 同会话内不随轮次变化，故不影响其后的前缀缓存，也不逐轮复读。宿主若不提供
   // section seam 就静默跳过——#249 §3 的口径是「只用现成 seam，拿不到位的语义
   // 降级处理」：能力说明仍落在工具描述上，不算失败。
-  const guideSection = config.injectGuidanceEnabled === true && typeof ctx.systemPrompt?.section === "function"
+  // 走父／子闸门（#249 第二批）：注入器本身只在 `autoInject` 开时挂载，这里是
+  // 第二道、也是同一个判据的显式落点——两处消费点共用 injectChildEnabled，
+  // 不在各自的地方重写「父关则子不生效」。
+  const guideSection = injectChildEnabled(config, "injectGuidanceEnabled") && typeof ctx.systemPrompt?.section === "function"
     ? ctx.systemPrompt.section({ name: "memory-guide", order: 150, text: MEMORY_GUIDE_SECTION })
     : null;
 

package/lib/lang.js

@@ -196,12 +196,23 @@ export const STR = {
 
   // --- mirror.js：镜像文件标签（渲染随实例语言；解析两种语言都认） ----------------
   mirrorLabel: {
-    zh: { type: "类型", importance: "重要性", tags: "标签", updated: "更新时间", source: "来源" },
-    en: { type: "Type", importance: "Importance", tags: "Tags", updated: "Updated", source: "Source" }
+    zh: { type: "类型", importance: "重要性", tags: "标签", updated: "更新时间", source: "来源", scope: "作用域", sensitivity: "敏感度" },
+    en: { type: "Type", importance: "Importance", tags: "Tags", updated: "Updated", source: "Source", scope: "Scope", sensitivity: "Sensitivity" }
   },
   mirrorHeader: {
-    zh: (name) => `# ${name} — dsh-mneme 镜像\n\n<!-- 手工编辑此文件会被合并回记忆库（人工优先）。 -->\n\n`,
-    en: (name) => `# ${name} — dsh-mneme mirror\n\n<!-- Manual edits to this file are merged back into the memory store (human edits win). -->\n\n`
+    zh: (name) => `# ${name} — dsh-mneme 镜像\n\n<!-- 条目标题与正文可编辑，会被合并回记忆库（人工优先）；文件头与条目元数据行由机器维护，改动会在下次同步时被覆盖。 -->\n\n`,
+    en: (name) => `# ${name} — dsh-mneme mirror\n\n<!-- Entry titles and bodies are editable and merged back into the memory store (human edits win); the file header and entry metadata lines are machine-owned and get overwritten on the next sync. -->\n\n`
+  },
+  // document 的镜像只有指针行（#296 第二批）：没有可编辑的正文，手工改动一律被
+  // 下次同步覆盖——所以不能复用上面那句「可编辑、会被合并回记忆库」。
+  mirrorReadonlyHeader: {
+    zh: (name) => `# ${name} — dsh-mneme 只读视图\n\n<!-- 只含指针行：id + 标题 + 摘要首句 + 文件路径，不含正文。正文在路径指向的文件里，批注请写进记忆库；本文件由机器维护，手工改动会在下次同步时被覆盖。 -->\n\n`,
+    en: (name) => `# ${name} — dsh-mneme read-only view\n\n<!-- Pointer rows only: id + title + first sentence of the summary + file path, never the full text. The document itself lives at that path, annotations belong in the memory store, and this file is machine-owned: hand edits are overwritten on the next sync. -->\n\n`
+  },
+  // documentDir 的 index.md（#296 第二批）：整文件机器所有、可从库重建。
+  documentIndexHeader: {
+    zh: () => "# document 索引 — dsh-mneme\n\n<!-- 整文件机器所有，可从记忆库随时重建（所以这里不写生成时间）；要批注请写进记忆库（memory_save）。managed = 文件在 documentDir 内。 -->\n\n",
+    en: () => "# document index — dsh-mneme\n\n<!-- Machine-owned as a whole and rebuildable from the memory store at any time (which is why it carries no generation timestamp). Annotations belong in the memory store (memory_save). managed = the file sits inside documentDir. -->\n\n"
   },
 
   prompts: PROMPTS

package/lib/local-embedder.js

@@ -21,6 +21,32 @@ function modelHash(model) {
   return `${model}#${hashString(model)}`;
 }
 
+/**
+ * Model families whose embedding is the CLS token rather than a mean over tokens.
+ *
+ * BGE (BAAI/bge-*) is trained that way: the model's own `1_Pooling/config.json`
+ * declares `pooling_mode_cls_token: true` / `pooling_mode_mean_tokens: false`, and
+ * the official README says "select the last hidden state of the first token" plus
+ * L2 normalization. transformers.js's `feature-extraction` defaults to `mean`, so
+ * feeding it a BGE model silently produces slightly-off vectors — no error, just a
+ * worse ranking. This table is the extension point: a family goes in only once its
+ * pooling is confirmed against the model's own `1_Pooling` (or equivalent) config.
+ */
+const CLS_POOLED_MODEL_PATTERNS = [/bge/i];
+
+/**
+ * Resolve the pooling to embed with.
+ *
+ * `auto` (default) picks by model family — BGE → `cls`, everything else → `mean`,
+ * so models that were never affected keep their exact previous behavior. An
+ * explicit `cls` / `mean` wins over the family table.
+ */
+export function resolvePooling(pooling, model) {
+  const mode = String(pooling ?? "auto").trim().toLowerCase();
+  if (mode === "cls" || mode === "mean") return mode;
+  return CLS_POOLED_MODEL_PATTERNS.some((re) => re.test(String(model ?? ""))) ? "cls" : "mean";
+}
+
 /**
  * Lazy default loader: dynamic import keeps module load cheap.
  *
@@ -71,8 +97,9 @@ function tensorToRows(tensor) {
 
 /**
  * ONNX text embedder backed by transformers.js (onnxruntime-node underneath).
- * Runs fully offline with mean pooling + L2 normalization for BERT-style
- * models like bge-small-zh. `engineFactory` is injectable for tests.
+ * Runs fully offline; pooling is resolved per model family (BGE → CLS, else mean —
+ * see resolvePooling) and vectors are L2-normalized. `engineFactory` is injectable
+ * for tests.
  */
 export class LocalEmbedder {
   constructor(opts = {}) {
@@ -87,6 +114,10 @@ export class LocalEmbedder {
     // （含测试）保持裸 fetch 的现状，配置默认值由 index.js 传进来。
     this.resilientModelDownload = opts.resilientModelDownload === true;
     this.useDtype = opts.useDtype || "q8";
+    // 池化：配置值（auto/cls/mean）→ 生效值（cls/mean）。解析结果既进 embed()，
+    // 也进 modelHash —— 换池化就是换向量空间，旧索引必须被判失配后重建。
+    this.poolingMode = String(opts.pooling ?? "auto").trim().toLowerCase();
+    this.pooling = resolvePooling(this.poolingMode, this.model);
     // 模型镜像下载源（embedModelMirror，#188 补充）：空 = transformers 默认。
     this.remoteHost = String(opts.remoteHost ?? "").trim();
     this.logger = opts.logger ?? null;
@@ -114,19 +145,19 @@ export class LocalEmbedder {
     this.extractor = await this.engineFactory("feature-extraction", this.model, options);
     this.ready = true; // service reads this to flush queued re-embeds
     this.logger?.info?.(
-      `[dsh-mneme] local embedder ready: ${this.model} (dim=${this._dimension}, device=${this.device})`
+      `[dsh-mneme] local embedder ready: ${this.model} (dim=${this._dimension}, device=${this.device}, pooling=${this.pooling})`
     );
     return this;
   }
 
-  /** Embed many texts with mean pooling; chunks at batchSize. */
+  /** Embed many texts with the model's pooling; chunks at batchSize. */
   async embed(texts) {
     if (!Array.isArray(texts)) throw new TypeError("embed expects an array of strings");
     if (!this.extractor) throw new Error("LocalEmbedder not initialized");
     const out = [];
     for (let i = 0; i < texts.length; i += this.batchSize) {
       const chunk = texts.slice(i, i + this.batchSize);
-      const tensor = await this.extractor(chunk, { pooling: "mean", normalize: true });
+      const tensor = await this.extractor(chunk, { pooling: this.pooling, normalize: true });
       out.push(...tensorToRows(tensor));
     }
     return out;
@@ -142,7 +173,14 @@ export class LocalEmbedder {
   }
 
   get modelHash() {
-    return modelHash(this.model);
+    // Pooling is part of the vector space: a CLS index cannot be queried with mean
+    // vectors (or vice versa). Keep the historical `model#hash` shape for `mean` so
+    // indexes that were never affected are not invalidated needlessly; every other
+    // pooling gets a fingerprint of its own, which makes the index-consistency gate
+    // flag the stale mean-space index and rebuild it.
+    return this.pooling === "mean"
+      ? modelHash(this.model)
+      : modelHash(`${this.model}@${this.pooling}`);
   }
 
   dispose() {

package/lib/maintenance.js

@@ -0,0 +1,142 @@
+// #275 存储生命周期第一批：无损回收的维护入口。
+//
+// 为什么是「手动入口 + dry-run + receipt」而不是后台任务：这两步都是不可逆的内容
+// 丢弃（历史 run 的输入快照置空、归档行的向量置空），该由人在看得见数字的时候按下
+// （维护者 2026-09-23 拍板：不挂启动自动跑，VACUUM 约 0.8s 说明它就该是个随手跑的
+// 东西）。所以模块里没有任何定时器，挂点只有两个：standalone 数据面的
+// `POST /maintenance/reclaim` 与它上面的 `dsh-mneme reclaim` 子命令。
+//
+// 两项都零价值判断、零条数变化：
+//   A `dream_runs.input` 置空。这一列的含义按 run_type 分叉：auto / sleep 的 run 存的
+//     是当时的记忆库快照，可由记忆库重建；**organize 的 run 存的是 apply 的重放载荷**，
+//     置空会让那次 apply 静默空转并把报告锁死，所以 organize 行不在可清范围内（谓词
+//     在 store.dreamRunInputStats / clearDreamRunInputs 里）。run 的骨架、LLM 决策原文
+//     与 receipt 一律保留，行永不删（拍板 3：裁列同意、删行不同意）。
+//   B 归档行向量置空：检索 SQL 恒带 `archived = 0`，这部分向量按定义不可达。它不是
+//     单程票——取消归档时 service 会重新排队嵌入（archiveMemory 的还原分支）。
+//
+// 报告口径（拍板 2）：收益按 VACUUM 前后体积量，不按列字节估——实际释放来自溢出页与
+// 索引页回收，列文本大小只是上界，所以两个数分开报，不混成一个「省了多少」。
+//
+// 与 #254 的分界（拍板 4）：本入口止体积、不止重复。归档区里同主题堆积是出口问题，
+// 归 #254 的写入准入与后续的整理动作面，这里一条记忆都不碰。
+export const RECLAIM_TRIGGER_SOURCE = "maintenance";
+export const RECLAIM_OPERATION_TYPE = "storage_reclaim";
+// 输入快照的默认保留窗口：7 天内仍可能被离线回放（近期 run 的决策上下文），更早的
+// 重建成本低于留存成本。窗口由调用方显式给，不做成配置键——配置键意味着有个周期性
+// 消费者，而本批次刻意不接周期动作。
+export const DEFAULT_INPUT_RETENTION_DAYS = 7;
+
+/**
+ * 无损回收（#275 第一批）。返回一个函数：同一条代码路径跑 dry-run 与执行，dry-run
+ * 只是不落 UPDATE/VACUUM，所以「报出来的数字」与「执行时的数字」出自同一处统计。
+ *
+ * @param {object} deps
+ * @param {object} deps.store 存储层（dreamRunInputStats / clearDreamRunInputs /
+ *   archivedEmbeddingStats / clearArchivedEmbeddings / storageStats / vacuum / saveLlmAudit）
+ * @param {object} [deps.config] 已解析配置（读 llmAudit.enabled：关掉 audit 时不落 receipt）
+ * @param {object} [deps.logger]
+ * @param {() => number} [deps.now] 时钟注入（测试用）
+ */
+export function createMaintenance({ store, config, logger, now = Date.now } = {}) {
+  const warn = (msg) => {
+    try {
+      logger?.warn?.(msg);
+    } catch { /* 日志故障不能影响回收本身 */ }
+  };
+
+  /** receipt 落到 llm_audit_logs（既有 bookkeeping 表，不触发写钩子）。 */
+  function writeReceipt(report) {
+    if (config?.llmAudit?.enabled === false) return null;
+    try {
+      const row = store.saveLlmAudit({
+        trigger_source: RECLAIM_TRIGGER_SOURCE,
+        operation_type: RECLAIM_OPERATION_TYPE,
+        // 不是模型调用，但该列 NOT NULL——用显式占位串，免得混进按路由分组的花费统计。
+        model_id: "-",
+        status: "success",
+        metadata: {
+          older_than_days: report.olderThanDays,
+          cleared: report.cleared,
+          size_before: report.size.before_bytes,
+          size_after: report.size.after_bytes,
+          vacuum: report.vacuum.ran,
+          duration_ms: report.duration_ms
+        }
+      });
+      return row?.id ?? null;
+    } catch (e) {
+      // 回执失败只 warn：清理已经发生了，不能因为记不上账就当作没发生（也不能反噬）。
+      warn(`[dsh-mneme] storage reclaim receipt failed: ${String(e)}`);
+      return null;
+    }
+  }
+
+  /**
+   * @param {object} [opts]
+   * @param {number} [opts.olderThanDays] 输入快照的保留窗口（天）；0 = 清掉全部快照
+   * @param {boolean} [opts.vacuum] 是否在清理后 VACUUM（默认否：它要排他锁，由人决定）
+   * @param {boolean} [opts.dryRun] 默认 true——只报数字，不改一个字节
+   * @returns {object} 报告（dry-run 与执行同形状，执行时多 receipt 字段）
+   */
+  function reclaim({ olderThanDays = DEFAULT_INPUT_RETENTION_DAYS, vacuum = false, dryRun = true } = {}) {
+    const days = Number.isFinite(olderThanDays) && olderThanDays >= 0 ? olderThanDays : DEFAULT_INPUT_RETENTION_DAYS;
+    const cutoff = new Date(now() - days * 86400000).toISOString();
+    const started = now();
+    const before = store.storageStats();
+    const inputs = store.dreamRunInputStats(cutoff);
+    const embeddings = store.archivedEmbeddingStats();
+    const report = {
+      dryRun,
+      olderThanDays: days,
+      cutoff,
+      // planned = 这次会动几行；cleared = 实际动了几行（dry-run 恒 0）
+      planned: { dream_run_inputs: inputs.runs, archived_embeddings: embeddings.rows },
+      // 列文本大小：上界，不是回收量（真实释放看下面的 size 差值）
+      column_bytes: { dream_run_inputs: inputs.bytes, archived_embeddings: embeddings.bytes },
+      cleared: { dream_run_inputs: 0, archived_embeddings: 0 },
+      size: {
+        before_bytes: before.fileBytes,
+        after_bytes: before.fileBytes,
+        // 空闲页就是「现在 VACUUM 能立刻收回来的那部分」，带上它 dry-run 才有个能
+        // 参照的量（真实数字仍然只有做完才知道）
+        freelist_pages: before.freelistCount,
+        freelist_bytes: before.freelistCount * before.pageSize,
+        page_count: before.pageCount
+      },
+      vacuum: { requested: vacuum === true, ran: false, duration_ms: null, error: null },
+      receipt: null,
+      duration_ms: 0
+    };
+    if (dryRun) {
+      report.duration_ms = now() - started;
+      return report;
+    }
+    report.cleared.dream_run_inputs = store.clearDreamRunInputs(cutoff);
+    report.cleared.archived_embeddings = store.clearArchivedEmbeddings();
+    if (report.vacuum.requested) {
+      // VACUUM 失败不能把前面的清理一起吞掉：两个 UPDATE 已经各自提交了，此时抛出去
+      // 就是「数据已经不可逆地清了，但没有任何回执」。所以失败记进报告、回执照写，
+      // 让调用方看到「清了 N 行，VACUUM 没跑成」——锁被别的进程占着（SQLITE_BUSY）是
+      // 最常见的成因，重跑一次 --apply --vacuum 即可（清理是幂等的）。
+      try {
+        const result = store.vacuum();
+        report.vacuum.ran = true;
+        report.vacuum.duration_ms = result.duration_ms;
+      } catch (e) {
+        report.vacuum.error = String(e);
+        warn(`[dsh-mneme] storage reclaim vacuum failed: ${String(e)}`);
+      }
+    }
+    const after = store.storageStats();
+    report.size.after_bytes = after.fileBytes;
+    report.size.freelist_pages = after.freelistCount;
+    report.size.freelist_bytes = after.freelistCount * after.pageSize;
+    report.size.page_count = after.pageCount;
+    report.duration_ms = now() - started;
+    report.receipt = writeReceipt(report);
+    return report;
+  }
+
+  return { reclaim };
+}