@max-null/dsh-memory 0.12.2 → 0.14.0

package/README.md

@@ -151,8 +151,13 @@ node scripts/scan-orphans.mjs [根目录]       # 清点「当前代码打不开
 node scripts/unzstd-frames.mjs <源> <目标>   # 解多帧 zstd（读 DSH 会话日志用）
 node scripts/ancestor-probe.mjs plan [--cwd <cwd>]   # 复算祖先链（只读）；seed/check/clean 验 ④-A
 node scripts/analyze-cooccurrence.mjs        # 关键词共现分析（记忆之间有没有关系网，只读）
+npm run check:memory        # 记忆文件存量体检（只读；0 = 全绿 / 1 = 有不合规 / 2 = 用法错）
 ```
 
 ## 依赖（peerDependencies，由宿主提供）
 
-`@deepseek-ai/cordis`、`@deepseek-ai/dsh-storage`、`@deepseek-ai/dsh-storage-domain`、`@deepseek-ai/dsh-storage-json`、`@deepseek-ai/dsh-system-prompt`、`@deepseek-ai/dsh-tools`
+`@deepseek-ai/cordis`（`^4.0.1`），以及 `@deepseek-ai/dsh-storage`、`@deepseek-ai/dsh-storage-domain`、`@deepseek-ai/dsh-storage-json`、`@deepseek-ai/dsh-system-prompt`、`@deepseek-ai/dsh-tools`、`@deepseek-ai/dsh-typert-protocol`——后面六个声明为 **`>=0.1.1-rc.1 <0.3.0`**。
+
+**为什么写显式范围而不是 caret**：caret 的上界是「下一个 minor」——`^0.1.1-rc.1` 展开为 `>=0.1.1-rc.1 <0.2.0-0`，内核一跨 minor 就判定不满足。而 peer 不满足时插件**不会被加载，也不会出现在 `did not activate` 列表里**：它在进入 fiber 图之前就被跳过，界面不报错，只表现为少一批功能。写成显式范围让 0.1 线与 0.2 线都能装载。
+
+**验证过的内核**：`0.1.1-rc.2`（原基线）与 `0.2.0-rc.1`（0.12.2 起——typecheck 用其类型定义零错误，并在隔离实例实机加载，三个失败信号全为 0）。下限保持原值不变：它是作者实际验证过的最早版本，比它更早的内核没验证过，不声称支持。

package/dist/anchors.d.ts

@@ -7,8 +7,19 @@
  * 只有一次 `existsSync`，与读环境变量同量级。此前这里写的是「探测必须零 IO」，那句话把
  * 「禁止 spawn」误写成了「禁止一切系统调用」——0.12.0 加 `path-exists` 时改正。
  */
-/** 受控词汇表：写入时只能从这四种里选，不能自创（自创的锚点无法机械校验）。 */
-export type AnchorKind = 'env' | 'tool-list' | 'self-version' | 'path-exists';
+/**
+ * 受控词汇表：写入时只能从这几种里选，不能自创（自创的锚点无法机械校验）。
+ *
+ * **这是全仓库唯一的一份定义。** 工具 schema 的 `enum`、存储 zod 的 `z.enum`、以及
+ * `AnchorKind` 类型全部从它派生——2026-09-25 那次「154 条 project 记忆全部失联」的根因
+ * 就是同一份集合写了两处、加 `path-exists` 时漏了第三处（`engine.ts` 的 zod 仍只有 3 个
+ * kind，写入放行、加载才炸）。三份副本各自维护，漏改是**结构性必然**，不是疏忽。
+ *
+ * @see docs/设计/2026-09-25-写入兜底与失败可见化-设计方案.md §四.4
+ */
+export declare const ANCHOR_KINDS: readonly ["env", "tool-list", "self-version", "path-exists"];
+/** 受控词汇表推导出的类型——别再手写一遍这个联合。 */
+export type AnchorKind = (typeof ANCHOR_KINDS)[number];
 /** 一条记忆声明的锚点。 */
 export interface MemoryAnchor {
     kind: AnchorKind;

package/dist/anchors.js

@@ -9,6 +9,17 @@
  */
 import { existsSync } from 'node:fs';
 import { isAbsolute, resolve } from 'node:path';
+/**
+ * 受控词汇表：写入时只能从这几种里选，不能自创（自创的锚点无法机械校验）。
+ *
+ * **这是全仓库唯一的一份定义。** 工具 schema 的 `enum`、存储 zod 的 `z.enum`、以及
+ * `AnchorKind` 类型全部从它派生——2026-09-25 那次「154 条 project 记忆全部失联」的根因
+ * 就是同一份集合写了两处、加 `path-exists` 时漏了第三处（`engine.ts` 的 zod 仍只有 3 个
+ * kind，写入放行、加载才炸）。三份副本各自维护，漏改是**结构性必然**，不是疏忽。
+ *
+ * @see docs/设计/2026-09-25-写入兜底与失败可见化-设计方案.md §四.4
+ */
+export const ANCHOR_KINDS = ['env', 'tool-list', 'self-version', 'path-exists'];
 /**
  * 探测某个锚点当前的取值。
  *
@@ -40,8 +51,14 @@ export function probeAnchor(anchor, probes) {
             const target = relative ? resolve(probes.workspaceCwd, anchor.name) : anchor.name;
             return existsSync(target) ? 'present' : 'absent';
         }
-        default:
+        default: {
+            // 编译期穷尽性：`ANCHOR_KINDS` 新增取值而这里忘了加 case 时，下面这行会报错。
+            // 运行期仍然返回 `undefined`（「未校验」）而不是抛错——数据里可能躺着旧版本写下的
+            // 未知 kind，探测路径不该因为一条坏记录把整个启动校验带崩。
+            const unhandled = anchor.kind;
+            void unhandled;
             return undefined;
+        }
     }
 }
 /**

package/dist/engine.d.ts

@@ -5,6 +5,7 @@
  * is always created `suggested` and becomes effective only through `setStatus`.
  */
 import { Service } from '@deepseek-ai/cordis';
+import { z } from 'zod';
 import { type PromptFile } from './prompt-files.ts';
 import type { AnchorProbes, MemoryAnchor } from './anchors.ts';
 import type { MemorySource, SourceStat } from './query-log.ts';
@@ -205,6 +206,24 @@ export interface SweepItem {
     id: string;
     summary: string;
 }
+/** 一条「自动降级若生效就会被撤下」的常驻（2026-09-29 起只计量、不生效）。 */
+export interface AutoDemoteCandidate extends SweepItem {
+    /** 距上次命中（从未命中则回退最后更新）的天数——这是定阈值时要看的那个分布。 */
+    idleDays: number;
+}
+/**
+ * 自动降级的判据（纯函数，2026-09-29 抽出）：只针对**自动升上来的**常驻注入——人工
+ * 开的开关不会被时间悄悄关掉（那是人的决定，不是信号的结论）。
+ *
+ * 抽成纯函数是因为它有两个调用方，而两者对「能不能写」的要求相反：`demoteStale` 在写
+ * 路径上（`writeScope` 之内），而 `sweep` 承诺只读（连时间戳都不写）。判据各写一份迟早
+ * 漂移成「体检说该降、降级说不用降」这类两套口径——所以只留这一份。
+ *
+ * @param record - 参与判定的记录。
+ * @param threshold - 闲置多久算候选（毫秒时间戳，早于它才算）。
+ * @returns 该记录是否属于本会被撤下的常驻。
+ */
+export declare function isAutoDemoteCandidate(record: MemoryRecord, threshold: number): boolean;
 /**
  * 只读体检的产出（{@link MemoryEngine.sweep}）。四类各有明确的消费者，不做「算了没人读」的采样
  * ——候选与新失效会进注入诊断行（模型每轮可见），久未命中与全量留给按需调用。
@@ -222,6 +241,14 @@ export interface SweepReport {
     candidates: Array<SweepItem & {
         hitCount: number;
     }>;
+    /**
+     * **自动降级若生效**会被撤下的常驻（2026-09-29 起只计量不生效）。
+     *
+     * 与 `longUnused` 正好互补：那个查的是「非常驻且久未命中」（可清理），这个查的是
+     * 「自动升上来的常驻且久未命中」（会被时间规则撤下）。留着它是因为阈值 `AUTO_DEMOTE_DAYS`
+     * 至今没有分布依据——等这张清单积累出「实际闲置多久」的形状，才有得可定。
+     */
+    autoDemoteCandidates: AutoDemoteCandidate[];
     /** 常驻与注入预算的占用：总数 / 实际进注入 / 预算（无限制时不出现）/ 被挤掉几条。 */
     resident: {
         total: number;
@@ -229,6 +256,21 @@ export interface SweepReport {
         budget: number | undefined;
         omitted: number;
     };
+    /**
+     * 数据完整性声明（门二，2026-09-25）：这次体检**实际读到了哪些存储**。
+     *
+     * 加它是因为「读不到就说读不到，比读到了但少一半更有价值」：project 侧打不开时，前面
+     * 几项会给出一个**看起来正常但偏小**的数字，而没有任何信号说明它少了什么。宁可报告
+     * 显式写「未纳入」，也不要让人对着一个残缺的全景做判断。
+     *
+     * - `included`：project 侧已纳入；
+     * - `absent`：本次没有工作区上下文（`projectCwd` 为空），不是故障；
+     * - `unreadable`：**尝试过但打不开**——此时 `projectError` 给出原因，前几项的数字只覆盖 global。
+     */
+    coverage: {
+        project: 'included' | 'absent' | 'unreadable';
+        projectError?: string;
+    };
 }
 declare module '@deepseek-ai/cordis' {
     interface Context {
@@ -239,6 +281,69 @@ declare module '@deepseek-ai/cordis' {
         'memory/changed'(change: MemoryChange): void;
     }
 }
+/**
+ * 存储块的 schema（门三的判据来源，2026-09-25）。
+ *
+ * **导出是为了让离线扫描器（`scripts/check-memory-files.mjs`）用它而不是自己再写一套**——
+ * 两份判据会漂移，而漂移的方向恰好是「扫描器说没事、打开时炸」这种最难查的形态。
+ */
+export declare const blockSchema: z.ZodObject<{
+    namespace: z.ZodEnum<{
+        global: "global";
+        project: "project";
+    }>;
+    status: z.ZodEnum<{
+        suggested: "suggested";
+        approved: "approved";
+        auto: "auto";
+        suggest: "suggest";
+    }>;
+    injected: z.ZodOptional<z.ZodBoolean>;
+    quarantined: z.ZodOptional<z.ZodBoolean>;
+    quarantineReason: z.ZodOptional<z.ZodString>;
+    hitCount: z.ZodOptional<z.ZodNumber>;
+    source: z.ZodOptional<z.ZodEnum<{
+        agent: "agent";
+        human: "human";
+    }>>;
+    injectedAuto: z.ZodOptional<z.ZodBoolean>;
+    anchor: z.ZodOptional<z.ZodObject<{
+        kind: z.ZodEnum<{
+            env: "env";
+            "tool-list": "tool-list";
+            "self-version": "self-version";
+            "path-exists": "path-exists";
+        }>;
+        name: z.ZodOptional<z.ZodString>;
+        value: z.ZodString;
+    }, z.core.$strip>>;
+    stale: z.ZodOptional<z.ZodBoolean>;
+    staleReason: z.ZodOptional<z.ZodString>;
+    content: z.ZodString;
+    keywords: z.ZodArray<z.ZodString>;
+    createdAt: z.ZodNumber;
+    updatedAt: z.ZodNumber;
+    lastUsedAt: z.ZodOptional<z.ZodNumber>;
+    vector: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
+    kind: z.ZodOptional<z.ZodEnum<{
+        fact: "fact";
+        prompt: "prompt";
+    }>>;
+    meta: z.ZodOptional<z.ZodObject<{
+        seq: z.ZodOptional<z.ZodNumber>;
+        name: z.ZodString;
+        dimension: z.ZodOptional<z.ZodString>;
+        difficulty: z.ZodOptional<z.ZodString>;
+        tags: z.ZodArray<z.ZodString>;
+        summary: z.ZodString;
+        path: z.ZodString;
+        mtime: z.ZodNumber;
+        source: z.ZodEnum<{
+            user: "user";
+            agent: "agent";
+        }>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
 /**
  * 嵌入能力（0.5.2 混合检索）：缺省不配置 = 纯 BM25（行为不变）；
  * 配置后 memory_search 以 BM25 与语义结果做 RRF 融合，向量持久化到
@@ -296,6 +401,12 @@ export declare class MemoryEngine extends Service {
     private readonly neighborOpenings;
     /** 进行中的工作区打开（key → promise）：并发调用复用同一次，见 {@link projectTableFor}。 */
     private readonly projectOpenings;
+    /**
+     * 打不开的工作区表（门二，2026-09-25）：key = 规范化 cwd，值 = 失败描述。
+     *
+     * 成功的打开会清掉对应项——「现在好没好」比「曾经坏过」更有用。见 {@link projectTableFor}。
+     */
+    private readonly projectOpenErrors;
     private projectFacilities;
     /** backend 只注册一次（registry 重名抛 duplicate；reload 清缓存后不得重复注册）。 */
     private registeredProjectBackends;
@@ -449,6 +560,28 @@ export declare class MemoryEngine extends Service {
      * 那时同步缓存已被清空（同 {@link markUsedInner} 的注释）。
      */
     private locateRecord;
+    /**
+     * **唯一**允许写块的地方（门一，2026-09-25）：写前跑一次存储 schema，不合格就抛。
+     *
+     * ⚠️ `KvTable` 上有**三个**写方法（`put` / `update` / `delete`），这道门只守 `put`。
+     * 截至 0.14.0 全仓只用了 `put` 与 `delete`——`delete` 不需要校验（**删掉一条不合规的
+     * 记录正是修复手段**），而 `update`（域内原子读改写，绕过本方法）**尚未被使用**。
+     * 将来若要用 `update`，它同样必须过 schema——否则门一就漏了一半。
+     *
+     * 为什么要有这道门：写入路径此前**完全不校验**，而不合规的记录会让整个 domain 在
+     * **下次打开时**打不开——`dsh-storage-domain` 逐条校验，一条不合格即整体失败。于是故障
+     * 被推迟到重启之后，表现为「整个工作区的记忆消失」：2026-09-25 那次 154 条 project 记忆
+     * 全部不可见（数据一条没丢，丢的是可读性），链条正是**写入放行 → 加载才炸 → 失败还被吞**。
+     * 三层里任何一层立住都不会发生，这一道补的是第一层。
+     *
+     * 失败**抛错**而不是静默降级：降级只是把「写入放行」的坑换到别处，且调用方看不到原因。
+     * 错误里带上 zod 的 issue（哪个字段、什么值、期望什么）。
+     *
+     * @param table - 目标表（global 或某个工作区）。
+     * @param id - 记录 id。
+     * @param block - 待写入的块；校验通过后写回 `parsed.data`，保证 strip 与默认值行为与读路径一致。
+     */
+    private putBlock;
     /**
      * 写入协调覆盖的存储文件：global + **全部已打开的工作区表** + 本次 cwd。
      *
@@ -570,9 +703,24 @@ export declare class MemoryEngine extends Service {
      * @param now - 当前时间（测试注入用）。
      * @returns 被撤下的条数（诊断与日志用）。
      */
-    demoteStale(projectCwd?: string, now?: number): Promise<number>;
-    /** {@link demoteStale} 的实现体；必须经 `writeScope` 进入。 */
-    private demoteStaleInner;
+    /**
+     * 自动降级的**计量**（2026-09-29 起不再生效）：列出「若判据生效会被撤下」的常驻，
+     * **不修改任何状态**。
+     *
+     * 为什么停掉撤销：那个阈值（`AUTO_DEMOTE_DAYS`）至今没有分布依据——它是 2026-09-15
+     * 从面板的折叠阈值 `COLD_DAYS` 借来的。两者的代价不对等：展示阈值折错了点一下就能
+     * 展开，而行为阈值一撤，0.12.0 取消了自动升之后基本不会自己回来。按「没有真实分布时
+     * 拍任何数字都是误杀面」（借自 dsh-mneme 的写入准入阶段一），在拿到分布之前不该继续
+     * 用这个数字动真格的。
+     *
+     * 候选由 {@link sweep} 的 `autoDemoteCandidates` 报出，积累出「实际闲置多久」的形状
+     * 之后再定阈值。判据是 `isAutoDemoteCandidate`——与体检共用一份，不各写一份。
+     *
+     * @param projectCwd - 会话工作区；给了就连工作区表一起扫。
+     * @param now - 当前时间（测试注入用）。
+     * @returns 本会被撤下的常驻清单，按闲置天数降序。
+     */
+    demoteStale(projectCwd?: string, now?: number): Promise<AutoDemoteCandidate[]>;
     /**
      * 锚点批量校验（2026-09-15）：会话启动时调一次，把失效的条目标成 `stale`。
      *

package/dist/engine.js

@@ -17,7 +17,7 @@ import { bm25FieldScores, cosineSimilarity, rrfFuse } from "./bm25.js";
 import { parsePromptFile, scanPromptDir, writePromptFile } from "./prompt-files.js";
 import { detectSensitive } from "./quarantine.js";
 import { SELF_VERSION } from "./self.js";
-import { anchorHolds } from "./anchors.js";
+import { ANCHOR_KINDS, anchorHolds } from "./anchors.js";
 import { DEFAULT_INJECTION_BUDGET, DEFAULT_SUMMARY_CHARS, deriveSummary, renderInjection, } from "./injection.js";
 import { QueryLog, rankGapCandidates, summarizeQueryLog, summarizeSources } from "./query-log.js";
 /** Brand a string as a {@link MemoryId} (compile-time only). */
@@ -54,7 +54,34 @@ const AUTO_DEMOTE_DAYS = 30;
  * 会把正常记录报成待清理。
  */
 const DEFAULT_SWEEP_DAYS = 90;
-const blockSchema = z.object({
+/**
+ * 自动降级的判据（纯函数，2026-09-29 抽出）：只针对**自动升上来的**常驻注入——人工
+ * 开的开关不会被时间悄悄关掉（那是人的决定，不是信号的结论）。
+ *
+ * 抽成纯函数是因为它有两个调用方，而两者对「能不能写」的要求相反：`demoteStale` 在写
+ * 路径上（`writeScope` 之内），而 `sweep` 承诺只读（连时间戳都不写）。判据各写一份迟早
+ * 漂移成「体检说该降、降级说不用降」这类两套口径——所以只留这一份。
+ *
+ * @param record - 参与判定的记录。
+ * @param threshold - 闲置多久算候选（毫秒时间戳，早于它才算）。
+ * @returns 该记录是否属于本会被撤下的常驻。
+ */
+export function isAutoDemoteCandidate(record, threshold) {
+    if (record.injectedAuto !== true)
+        return false;
+    if (record.quarantined === true)
+        return false;
+    if (record.status !== 'approved')
+        return false;
+    return (record.lastUsedAt ?? record.updatedAt) <= threshold;
+}
+/**
+ * 存储块的 schema（门三的判据来源，2026-09-25）。
+ *
+ * **导出是为了让离线扫描器（`scripts/check-memory-files.mjs`）用它而不是自己再写一套**——
+ * 两份判据会漂移，而漂移的方向恰好是「扫描器说没事、打开时炸」这种最难查的形态。
+ */
+export const blockSchema = z.object({
     namespace: z.enum(['global', 'project']),
     status: z.enum(['suggested', 'approved', 'auto', 'suggest']),
     injected: z.boolean().optional(),
@@ -64,7 +91,7 @@ const blockSchema = z.object({
     source: z.enum(['agent', 'human']).optional(),
     injectedAuto: z.boolean().optional(),
     anchor: z.object({
-        kind: z.enum(['env', 'tool-list', 'self-version']),
+        kind: z.enum(ANCHOR_KINDS),
         name: z.string().optional(),
         value: z.string(),
     }).optional(),
@@ -89,6 +116,16 @@ const blockSchema = z.object({
         source: z.enum(['user', 'agent']),
     }).optional(),
 });
+/**
+ * 把 zod 的 issue 压成一行（门一，2026-09-25）。
+ *
+ * 排查成本的大头在「从 domain 打不开倒推」——`dsh-storage-domain` 封装后的错误只给到
+ * 「哪个 domain 的哪条记录不合规」（`stored record '<id>' in table 'blocks' does not
+ * match its schema`），**说不出是哪个字段、什么值、期望什么**。这行补的就是那段。
+ */
+function describeIssues(error) {
+    return error.issues.map(issue => `${issue.path.join('.') || '(root)'}: ${issue.message}`).join('; ');
+}
 /** Shared table shape; the two domains differ only by name and backend route. */
 function memorySpec(name) {
     return defineDomain({
@@ -189,6 +226,12 @@ export class MemoryEngine extends Service {
     neighborOpenings = new Map();
     /** 进行中的工作区打开（key → promise）：并发调用复用同一次，见 {@link projectTableFor}。 */
     projectOpenings = new Map();
+    /**
+     * 打不开的工作区表（门二，2026-09-25）：key = 规范化 cwd，值 = 失败描述。
+     *
+     * 成功的打开会清掉对应项——「现在好没好」比「曾经坏过」更有用。见 {@link projectTableFor}。
+     */
+    projectOpenErrors = new Map();
     projectFacilities = new Map();
     /** backend 只注册一次（registry 重名抛 duplicate；reload 清缓存后不得重复注册）。 */
     registeredProjectBackends = new Set();
@@ -278,7 +321,20 @@ export class MemoryEngine extends Service {
         const opening = this.openProjectTable(key);
         this.projectOpenings.set(key, opening);
         try {
-            return await opening;
+            const table = await opening;
+            this.projectOpenErrors.delete(key);
+            return table;
+        }
+        catch (error) {
+            // 门二（2026-09-25 故障的直接教训）：打不开要说出来。此前这里让异常上抛、由调用方
+            // `catch(() => undefined)` 吞掉，于是一条不合规记录能让**整个工作区的记忆静默消失**
+            // ——用户只在「注入数 184 → 30」这种恰好被注意到的数字上才发现（154 条 project
+            // 记忆全部不可见，数据一条没丢，丢的是可读性）。
+            //
+            // 这里仍然上抛：调用方的 undefined 语义不变（它们按「没有 project 部分」继续），
+            // 变的只是**失败被记下来了**，`memory_sweep` 据此声明数据完整性。
+            this.projectOpenErrors.set(key, error instanceof Error ? error.message : String(error));
+            throw error;
         }
         finally {
             this.projectOpenings.delete(key);
@@ -547,12 +603,33 @@ export class MemoryEngine extends Service {
         }));
         const candidates = this.candidates(projectCwd)
             .map(record => ({ id: String(record.id), summary: brief(record), hitCount: record.hitCount ?? 0 }));
+        // 自动降级的候选（2026-09-29）：判据与 `demoteStale` 共用同一个纯函数，但这里
+        // 只列出来、不撤下——`sweep` 承诺只读。它的用途是让那个至今没有分布依据的阈值
+        // 变得可观察：这张清单里的 `idleDays` 积累一段时间后，就是定阈值的依据。
+        const demoteThreshold = now - AUTO_DEMOTE_DAYS * 24 * 60 * 60 * 1000;
+        const autoDemoteCandidates = records
+            .filter(record => isAutoDemoteCandidate(record, demoteThreshold))
+            .map(record => ({
+            id: String(record.id),
+            summary: brief(record),
+            idleDays: Math.floor((now - (record.lastUsedAt ?? record.updatedAt)) / (24 * 60 * 60 * 1000)),
+        }));
         const resident = this.recallRecords(projectCwd);
         const rendered = renderInjection(resident, this.config.injectionBudget ?? DEFAULT_INJECTION_BUDGET, summaryChars);
+        // 完整性声明（门二）：上面那些读取都经过 `projectTableFor`，打不开的话它已把原因记在
+        // `projectOpenErrors` 里。这里只判断「该不该有 project 侧」与「有没有失败记录」——
+        // 没有工作区上下文是 `absent`（不是故障），有上下文又打不开才是 `unreadable`。
+        const projectKey = projectCwd === undefined || projectCwd === '' ? undefined : join(projectCwd);
+        const projectError = projectKey === undefined ? undefined : this.projectOpenErrors.get(projectKey);
+        const coverage = projectKey === undefined
+            ? { project: 'absent' }
+            : projectError === undefined ? { project: 'included' } : { project: 'unreadable', projectError };
         const report = {
             stale,
             longUnused,
             candidates,
+            autoDemoteCandidates,
+            coverage,
             resident: {
                 total: resident.length,
                 injected: rendered.lines.length,
@@ -613,6 +690,34 @@ export class MemoryEngine extends Service {
         }
         return undefined;
     }
+    /**
+     * **唯一**允许写块的地方（门一，2026-09-25）：写前跑一次存储 schema，不合格就抛。
+     *
+     * ⚠️ `KvTable` 上有**三个**写方法（`put` / `update` / `delete`），这道门只守 `put`。
+     * 截至 0.14.0 全仓只用了 `put` 与 `delete`——`delete` 不需要校验（**删掉一条不合规的
+     * 记录正是修复手段**），而 `update`（域内原子读改写，绕过本方法）**尚未被使用**。
+     * 将来若要用 `update`，它同样必须过 schema——否则门一就漏了一半。
+     *
+     * 为什么要有这道门：写入路径此前**完全不校验**，而不合规的记录会让整个 domain 在
+     * **下次打开时**打不开——`dsh-storage-domain` 逐条校验，一条不合格即整体失败。于是故障
+     * 被推迟到重启之后，表现为「整个工作区的记忆消失」：2026-09-25 那次 154 条 project 记忆
+     * 全部不可见（数据一条没丢，丢的是可读性），链条正是**写入放行 → 加载才炸 → 失败还被吞**。
+     * 三层里任何一层立住都不会发生，这一道补的是第一层。
+     *
+     * 失败**抛错**而不是静默降级：降级只是把「写入放行」的坑换到别处，且调用方看不到原因。
+     * 错误里带上 zod 的 issue（哪个字段、什么值、期望什么）。
+     *
+     * @param table - 目标表（global 或某个工作区）。
+     * @param id - 记录 id。
+     * @param block - 待写入的块；校验通过后写回 `parsed.data`，保证 strip 与默认值行为与读路径一致。
+     */
+    async putBlock(table, id, block) {
+        const parsed = blockSchema.safeParse(block);
+        if (!parsed.success) {
+            throw new Error(`memory: refusing to store an invalid record ${id} — ${describeIssues(parsed.error)}`);
+        }
+        await table.put(id, parsed.data);
+    }
     /**
      * 写入协调覆盖的存储文件：global + **全部已打开的工作区表** + 本次 cwd。
      *
@@ -704,7 +809,7 @@ export class MemoryEngine extends Service {
                 ? { quarantined: true, ...verdict.reason === undefined ? {} : { quarantineReason: verdict.reason } }
                 : {},
         };
-        await table.put(id, block);
+        await this.putBlock(table, id, block);
         const record = toRecord(id, block);
         this.ctx.emit('memory/changed', { operation: 'remembered', record });
         return record;
@@ -807,7 +912,7 @@ export class MemoryEngine extends Service {
                 fresh.set(String(missingRecord.id), [...vector]);
                 const block = missingRecord.table.get(missingRecord.id);
                 if (block !== undefined) {
-                    await missingRecord.table.put(missingRecord.id, { ...block, vector: [...vector] });
+                    await this.putBlock(missingRecord.table, missingRecord.id, { ...block, vector: [...vector] });
                 }
             }
         }
@@ -844,9 +949,13 @@ export class MemoryEngine extends Service {
                 this.ctx.logger?.info?.(`dsh-memory: 旧数据迁移 放行 ${migration.approved} / 隔离 ${migration.quarantined}`
                     + ` / 回填计数 ${migration.counted}`);
             }
-            const demoted = await this.demoteStale(projectCwd);
-            if (demoted > 0)
-                this.ctx.logger?.info?.(`dsh-memory: 长期未命中，撤下常驻 ${demoted} 条`);
+            // 自动降级自 2026-09-29 起只计量不生效（阈值缺分布依据，见 `demoteStale`）。
+            // 这里只报一行，让人知道有多少条落在那个数字的另一侧、最久的闲置了多久。
+            const demoteCandidates = await this.demoteStale(projectCwd);
+            if (demoteCandidates.length > 0) {
+                this.ctx.logger?.info?.(`dsh-memory: ${demoteCandidates.length} 条常驻闲置超 ${AUTO_DEMOTE_DAYS} 天`
+                    + `（只计量不生效；最久 ${demoteCandidates[0]?.idleDays ?? 0} 天）`);
+            }
             const staled = await this.verifyAnchors(this.anchorProbes(projectCwd), projectCwd);
             if (staled > 0)
                 this.ctx.logger?.info?.(`dsh-memory: 锚点校验更新 ${staled} 条`);
@@ -949,7 +1058,7 @@ export class MemoryEngine extends Service {
             hitCount: (block.hitCount ?? 0) + 1,
             lastUsedAt: now,
         };
-        await table.put(id, updated);
+        await this.putBlock(table, id, updated);
     }
     // ── 查询日志与影响力统计（⑥ 2026-09-15）────────────────────────────────
     /** 查询日志（惰性创建；位置见 {@link queryLogPath}）。 */
@@ -1047,37 +1156,35 @@ export class MemoryEngine extends Service {
      * @param now - 当前时间（测试注入用）。
      * @returns 被撤下的条数（诊断与日志用）。
      */
+    /**
+     * 自动降级的**计量**（2026-09-29 起不再生效）：列出「若判据生效会被撤下」的常驻，
+     * **不修改任何状态**。
+     *
+     * 为什么停掉撤销：那个阈值（`AUTO_DEMOTE_DAYS`）至今没有分布依据——它是 2026-09-15
+     * 从面板的折叠阈值 `COLD_DAYS` 借来的。两者的代价不对等：展示阈值折错了点一下就能
+     * 展开，而行为阈值一撤，0.12.0 取消了自动升之后基本不会自己回来。按「没有真实分布时
+     * 拍任何数字都是误杀面」（借自 dsh-mneme 的写入准入阶段一），在拿到分布之前不该继续
+     * 用这个数字动真格的。
+     *
+     * 候选由 {@link sweep} 的 `autoDemoteCandidates` 报出，积累出「实际闲置多久」的形状
+     * 之后再定阈值。判据是 `isAutoDemoteCandidate`——与体检共用一份，不各写一份。
+     *
+     * @param projectCwd - 会话工作区；给了就连工作区表一起扫。
+     * @param now - 当前时间（测试注入用）。
+     * @returns 本会被撤下的常驻清单，按闲置天数降序。
+     */
     async demoteStale(projectCwd, now = Date.now()) {
-        return this.writeScope(projectCwd, () => this.demoteStaleInner(projectCwd, now));
-    }
-    /** {@link demoteStale} 的实现体；必须经 `writeScope` 进入。 */
-    async demoteStaleInner(projectCwd, now = Date.now()) {
         const threshold = now - AUTO_DEMOTE_DAYS * 24 * 60 * 60 * 1000;
-        const tables = [this.requireTable('global')];
-        if (projectCwd !== undefined && projectCwd !== '') {
-            const project = await this.projectTableFor(projectCwd);
-            if (project !== undefined)
-                tables.push(project);
-        }
-        let demoted = 0;
-        for (const table of tables) {
-            // 先快照键值对：put 会改到底层 Map，边遍历边写不安全
-            for (const [id, block] of [...table.entries()]) {
-                if (block.injectedAuto !== true)
-                    continue;
-                if (block.quarantined === true)
-                    continue;
-                if (normalizeBlock(block).status !== 'approved')
-                    continue;
-                const last = block.lastUsedAt ?? block.updatedAt;
-                if (last > threshold)
-                    continue;
-                await table.put(id, { ...block, injected: false, injectedAuto: false });
-                this.ctx.emit('memory/changed', { operation: 'injected', id: MemoryId(id), injected: false });
-                demoted += 1;
-            }
-        }
-        return demoted;
+        const summaryChars = this.config.summaryChars ?? DEFAULT_SUMMARY_CHARS;
+        const records = await this.allRecords(undefined, projectCwd);
+        return records
+            .filter(record => isAutoDemoteCandidate(record, threshold))
+            .map(record => ({
+            id: String(record.id),
+            summary: deriveSummary(record.content, summaryChars),
+            idleDays: Math.floor((now - (record.lastUsedAt ?? record.updatedAt)) / (24 * 60 * 60 * 1000)),
+        }))
+            .sort((left, right) => right.idleDays - left.idleDays);
     }
     /**
      * 锚点批量校验（2026-09-15）：会话启动时调一次，把失效的条目标成 `stale`。
@@ -1130,7 +1237,7 @@ export class MemoryEngine extends Service {
                         injected: false,
                         injectedAuto: false,
                     };
-                await table.put(id, updated);
+                await this.putBlock(table, id, updated);
                 this.ctx.emit('memory/changed', { operation: 'status', id: MemoryId(id), status: normalizeBlock(updated).status });
                 changed += 1;
             }
@@ -1216,7 +1323,7 @@ export class MemoryEngine extends Service {
                     stats.counted += 1;
                 }
                 if (updated !== undefined)
-                    await table.put(id, updated);
+                    await this.putBlock(table, id, updated);
             }
         }
         return stats;
@@ -1265,7 +1372,7 @@ export class MemoryEngine extends Service {
             throw new Error(`memory '${id}' is already stored in '${to}'`);
         // 先写目标、再删源：中间态里它同时存在于两处（重复好过丢失），而两次写同处一个
         // writeScope，外部看不到中间态。
-        await destination.put(id, found.block);
+        await this.putBlock(destination, id, found.block);
         await found.table.delete(id);
         // 继承只向上，而 global 人人可见——所以「移进 global」与「移进自己的某个祖先」都能
         // 让源层继续看得见它；反过来（global → 某工作区、祖先 → 后代）就是缩小范围。
@@ -1349,7 +1456,7 @@ export class MemoryEngine extends Service {
             ...status === 'approved' ? { quarantined: false, quarantineReason: undefined } : {},
             updatedAt: Date.now(),
         };
-        await table.put(id, updated);
+        await this.putBlock(table, id, updated);
         const record = toRecord(id, updated);
         this.ctx.emit('memory/changed', { operation: 'status', id, status });
         return record;
@@ -1386,7 +1493,7 @@ export class MemoryEngine extends Service {
             injectedAuto: false,
             updatedAt: Date.now(),
         };
-        await found.table.put(id, updated);
+        await this.putBlock(found.table, id, updated);
         const record = toRecord(id, updated);
         this.ctx.emit('memory/changed', { operation: 'injected', id, injected });
         return record;
@@ -1445,7 +1552,7 @@ export class MemoryEngine extends Service {
             injectedAuto: false,
             updatedAt: Date.now(),
         };
-        await found.table.put(id, updated);
+        await this.putBlock(found.table, id, updated);
         this.ctx.emit('memory/changed', { operation: 'status', id, status: normalizeBlock(updated).status });
         return updated;
     }
@@ -1531,7 +1638,7 @@ export class MemoryEngine extends Service {
             throw new Error(`cannot update unknown memory '${id}'`);
         const { table, block } = found;
         const updated = applyPatch(block);
-        await table.put(id, updated);
+        await this.putBlock(table, id, updated);
         return publish(block, updated);
     }
     /**
@@ -1679,7 +1786,7 @@ export class MemoryEngine extends Service {
                     source: file.meta.source,
                 },
             };
-            await table.put(id, block);
+            await this.putBlock(table, id, block);
             changed++;
         }
         for (const record of existing) {

package/dist/index.js

@@ -7,6 +7,7 @@
 import { defineTool } from '@deepseek-ai/dsh-tools';
 import { MemoryEngine } from "./engine.js";
 import { MemoryGateway } from "./remote.js";
+import { ANCHOR_KINDS } from "./anchors.js";
 import { mountMemoryApi } from "./routes.js";
 import { SELF_DESCRIPTION } from "./self.js";
 import { DEFAULT_INJECTION_BUDGET, DEFAULT_SUMMARY_CHARS, candidateNotice, indexNotice, neighborNotice, neutralizeBraces, omittedNotice, renderInjection, staleNotice } from "./injection.js";
@@ -64,7 +65,7 @@ const RECORD_SCHEMA = {
             additionalProperties: false,
             description: '有效性锚点：这个值一变，这条记忆就自动失效。`memory_update` 传新值即改写（当场重新校验），传 `null` 即清除。',
             properties: {
-                kind: { type: 'string', required: true, enum: ['env', 'tool-list', 'self-version', 'path-exists'] },
+                kind: { type: 'string', required: true, enum: [...ANCHOR_KINDS] },
                 name: { type: 'string' },
                 value: { type: 'string', required: true },
             },
@@ -141,6 +142,30 @@ const SWEEP_SCHEMA = {
                 omitted: { type: 'number', required: true },
             },
         },
+        autoDemoteCandidates: {
+            type: 'array',
+            required: true,
+            description: '自动降级若生效会被撤下的常驻（0.13.0 起只计量不生效）。`idleDays` 就是定那个阈值要看的分布。',
+            items: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    id: { type: 'string', required: true },
+                    summary: { type: 'string', required: true },
+                    idleDays: { type: 'number', required: true },
+                },
+            },
+        },
+        coverage: {
+            type: 'object',
+            required: true,
+            additionalProperties: false,
+            description: '数据完整性声明（0.14.0）：本次体检实际读到了哪些存储。`project` 为 `unreadable` 时，前面几项只覆盖 global——别对着一个看起来正常的偏小数字做判断。',
+            properties: {
+                project: { type: 'string', required: true, enum: ['included', 'absent', 'unreadable'] },
+                projectError: { type: 'string', description: '`unreadable` 时的原因；其余情况不出现。' },
+            },
+        },
     },
 };
 /** 模板记录（0.6.0）：不暴露本地文件路径（meta.path 引擎内部使用）。 */
@@ -375,7 +400,7 @@ export async function apply(ctx, config) {
                 additionalProperties: false,
                 description: 'Optional validity anchor: bind this memory to a probeable environment value so it auto-expires when that value changes. Use only for facts that depend on the environment (tool behaviour under a specific version, config decided by an env var). 可选锚点：把记忆绑到可探测的环境值，值变了自动失效。只用于「随环境变化的事实」。',
                 properties: {
-                    kind: { type: 'string', required: true, enum: ['env', 'tool-list', 'self-version', 'path-exists'], description: 'env = a named environment variable; tool-list = the available tool set; self-version = this plugin version; path-exists = a path that should still exist (`name` = the path, `value` = `present` or `absent`).' },
+                    kind: { type: 'string', required: true, enum: [...ANCHOR_KINDS], description: 'env = a named environment variable; tool-list = the available tool set; self-version = this plugin version; path-exists = a path that should still exist (`name` = the path, `value` = `present` or `absent`).' },
                     name: { type: 'string', description: 'For kind=env: the variable name.' },
                     value: { type: 'string', required: true, description: 'The value probed at write time.' },
                 },
@@ -636,7 +661,7 @@ export async function apply(ctx, config) {
                         type: 'object',
                         additionalProperties: false,
                         properties: {
-                            kind: { type: 'string', required: true, enum: ['env', 'tool-list', 'self-version', 'path-exists'], description: 'env = a named environment variable; tool-list = the available tool set; self-version = this plugin version; path-exists = a path that should still exist (`name` = the path, `value` = `present` or `absent`).' },
+                            kind: { type: 'string', required: true, enum: [...ANCHOR_KINDS], description: 'env = a named environment variable; tool-list = the available tool set; self-version = this plugin version; path-exists = a path that should still exist (`name` = the path, `value` = `present` or `absent`).' },
                             name: { type: 'string', description: 'For kind=env: the variable name. For kind=path-exists: the path (relative paths resolve against the session workspace).' },
                             value: { type: 'string', required: true, description: 'The value probed at write time.' },
                         },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@max-null/dsh-memory",
-  "version": "0.12.2",
+  "version": "0.14.0",
   "description": "Cross-session plaintext memory plugin for the DeepSeek Harness — deterministic BM25 recall, writes take effect immediately, signal-driven injection, no embeddings",
   "license": "MIT",
   "publishConfig": {
@@ -27,7 +27,8 @@
     "scripts/scan-orphans.mjs",
     "scripts/unzstd-frames.mjs",
     "scripts/ancestor-probe.mjs",
-    "scripts/analyze-cooccurrence.mjs"
+    "scripts/analyze-cooccurrence.mjs",
+    "scripts/check-memory-files.mjs"
   ],
   "dsh": {
     "bundle": {
@@ -60,6 +61,7 @@
     "typecheck": "tsc --noEmit -p tsconfig.json",
     "test": "vitest run",
     "mutate:check": "node scripts/mutate-check.mjs",
+    "check:memory": "node scripts/check-memory-files.mjs",
     "prepublishOnly": "npm run build"
   },
   "dependencies": {

package/scripts/check-memory-files.mjs

@@ -0,0 +1,128 @@
+#!/usr/bin/env node
+/**
+ * 记忆存储文件的存量体检（门三，2026-09-25）。
+ *
+ * **能回答什么**：给出的记忆文件里，有没有**不合规的存储块**——那种块会让整个 domain 在
+ * 下次打开时失败（`dsh-storage-domain` 逐条校验，一条不合格即整体失败），表现为「整个工作区
+ * 的记忆静默消失」。2026-09-25 那次 154 条 project 记忆全部不可见就是这么来的：写入放行、
+ * 加载才炸、失败还被吞。
+ *
+ * **判据怎么算**：用插件自己的 `blockSchema`（从 `dist/engine.js` import）逐条 `safeParse`。
+ * 同源是刻意的——另写一套判定迟早漂移成「扫描器说没事、打开时炸」这种最难查的形态。
+ *
+ * **哪些情况答不了**：
+ *   - 只校验 `tables.blocks` 里的条目，不校验外层信封结构；
+ *   - 不处理压缩帧（那是 `unzstd-frames.mjs` 的事）；
+ *   - 不判断「记录该不该存在」——那是价值判断，本脚本只看格式。
+ *
+ * 用法：
+ *   node scripts/check-memory-files.mjs              # 扫 $DSH_HOME 与当前目录下的记忆文件
+ *   node scripts/check-memory-files.mjs <路径...>    # 扫指定文件或目录（目录会递归找 *.json）
+ *
+ * 退出码：0 = 全绿 / 1 = 命中不合规 / 2 = 用法或环境错误。
+ *
+ * 前置：本脚本 import 编译产物 `dist/engine.js`，所以要先 `npm run build`。
+ */
+
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join, resolve } from 'node:path'
+
+const USAGE = 2
+
+function fail(message) {
+  console.error(`check-memory-files: ${message}`)
+  process.exit(USAGE)
+}
+
+let blockSchema
+try {
+  ({ blockSchema } = await import('../dist/engine.js'))
+} catch (error) {
+  fail(
+    `无法加载 dist/engine.js（先跑 npm run build）：${error instanceof Error ? error.message : String(error)}`,
+  )
+}
+if (blockSchema === undefined) fail('dist/engine.js 没有导出 blockSchema——构建产物太旧？')
+
+/** 递归收集目录下的 *.json（跳过 node_modules）。 */
+function collect(target, out = []) {
+  let stat
+  try {
+    stat = statSync(target)
+  } catch {
+    return out
+  }
+  if (stat.isFile()) {
+    if (target.endsWith('.json')) out.push(target)
+    return out
+  }
+  if (!stat.isDirectory()) return out
+  if (target.includes('node_modules')) return out
+  for (const entry of readdirSync(target, { withFileTypes: true })) {
+    if (entry.name === 'node_modules') continue
+    collect(join(target, entry.name), out)
+  }
+  return out
+}
+
+/** 默认扫描目标：$DSH_HOME/storages 与当前目录的 .dsh/storages。 */
+function defaultTargets() {
+  const dshHome = process.env.DSH_HOME ?? join(homedir(), '.dsh')
+  const targets = [join(dshHome, 'storages'), join(process.cwd(), '.dsh', 'storages')]
+  return targets.filter(existsSync)
+}
+
+const args = process.argv.slice(2)
+const explicit = args.length > 0
+const targets = explicit ? args.map(arg => resolve(arg)) : defaultTargets()
+
+// 显式给的路径必须存在。**把「什么都没扫到」报成「全绿」是同一个病**——偏小的数字看起来
+// 正常，而判断者会据此认为存量是干净的。门二存在的理由就是这句话。
+if (explicit) {
+  const missing = targets.filter(target => !existsSync(target))
+  if (missing.length > 0) fail(`路径不存在：${missing.join('、')}`)
+}
+if (targets.length === 0) fail('没有可扫描的目标（既没给路径，也没找到 $DSH_HOME/storages 或 ./.dsh/storages）')
+
+const files = [...new Set(targets.flatMap(target => collect(target)))].sort()
+let scanned = 0
+let records = 0
+const violations = []
+
+for (const file of files) {
+  let raw
+  try {
+    raw = JSON.parse(readFileSync(file, 'utf8'))
+  } catch {
+    continue // 不是 JSON（或不是存储文件）—— 不是本脚本的事
+  }
+  const blocks = raw?.tables?.blocks
+  if (blocks === null || typeof blocks !== 'object') continue
+  scanned += 1
+  for (const [id, block] of Object.entries(blocks)) {
+    records += 1
+    const parsed = blockSchema.safeParse(block)
+    if (parsed.success) continue
+    const issues = parsed.error.issues
+      .map(issue => `${issue.path.join('.') || '(root)'}: ${issue.message}`)
+      .join('; ')
+    violations.push({ file, id, issues })
+  }
+}
+
+console.log(`check-memory-files: 扫描 ${scanned} 个记忆文件 / ${records} 条记录`)
+// 一个记忆文件都没扫到，同样是可疑的——不能报「全部合规」。判断者需要知道这次体检
+// **没有覆盖任何东西**（同门二：读不到就说读不到）。
+if (scanned === 0) fail(`看了 ${files.length} 个 JSON，但没有一个是记忆文件——目标选对了吗？`)
+if (violations.length === 0) {
+  console.log('check-memory-files: ✅ 全部合规')
+  process.exit(0)
+}
+
+console.error(`check-memory-files: ✗ ${violations.length} 条不合规——它们会让所在 domain 打不开`)
+for (const violation of violations) {
+  console.error(`  ${violation.file}`)
+  console.error(`    ${violation.id}: ${violation.issues}`)
+}
+process.exit(1)