dsh-prime-memory 0.16.1-beta.1 → 0.16.2

package/dist/index.js

@@ -22,7 +22,7 @@ import { NoopEmbeddingService } from './store/embedding.js';
 import { EmbeddingManager, EmbeddingSourceStore, makeLocalServiceFactory, resolveInitialEmbedding, } from './store/embedding-source.js';
 import { ModelDownloadQueue } from './store/download-queue.js';
 import { PINNED_TRANSFORMERS_VERSION, RuntimeInstaller } from './store/runtime-installer.js';
-import { ensureDir } from './util/io.js';
+import { cleanupOrphanTmp, ensureDir } from './util/io.js';
 import { L0Store } from './store/l0.js';
 import { L1Store } from './store/l1.js';
 import { PersonaStore } from './store/persona.js';
@@ -81,6 +81,17 @@ export async function apply(ctx, config) {
         storageOk = false;
         logger.error(`[memory] 数据目录不可写,记忆功能停用: ${dataDir} (${err instanceof Error ? err.message : String(err)})`);
     }
+    // 孤儿 tmp 扫描:进程被 kill -9 / 断电时原子写会留下 tmp(写失败路径已 unlink,
+    // 只在硬中断下残留)。放在 store 载入之前——此刻还没有任何写者,清不掉"正在写"的文件。
+    // 清理失败绝不影响启动(残留 tmp 不参与任何读路径)。
+    if (storageOk) {
+        try {
+            await cleanupOrphanTmp(dataDir, logger);
+        }
+        catch (err) {
+            logger.warn(`[memory] 孤儿临时文件扫描失败(忽略): ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
     // ── 记忆模式运行时开关(官方 settings 服务,live 生效;缺失时恒开) ──
     const live = registerLiveSettings(ctx, logger);
     /** 插件停机标志:置位后不再发起后台 embeddings 调用(dispose 序最先设置)。 */
@@ -153,7 +164,7 @@ export async function apply(ctx, config) {
             chat: new PersonaStore(dataDir, 'chat', logger),
             work: new PersonaStore(dataDir, 'work', logger),
         },
-        state: new StateStore(StateStore.pathFor(dataDir)),
+        state: new StateStore(StateStore.pathFor(dataDir), logger),
         // 激活槽位(active slot):独立 slots.json,高频小改不拖累 checkpoint 原子写
         slots: new SlotStore(SlotStore.pathFor(dataDir), logger, {
             maxSlots: config.slots.maxSlots,

package/dist/pipeline/reconcile-run.d.ts

@@ -1,3 +1,4 @@
+import { RECONCILE_STATE_FILE_VERSION } from '../store/file-versions.js';
 import type { EvidenceSource } from '../store/evidence-source.js';
 import type { MemoryLogger } from '../types.js';
 import { type MemoryVerdict, type ReconcileDeps, type ReconcileInput, type ReconcileState } from './reconcile.js';
@@ -49,7 +50,7 @@ export interface ReconcilePlan {
 }
 /** 断点续跑状态文件。 */
 export interface ReconcileRunState {
-    version: 1;
+    version: typeof RECONCILE_STATE_FILE_VERSION;
     runId: string;
     startedAt: number;
     updatedAt: number;
@@ -62,8 +63,17 @@ export declare function contentHash(text: string): string;
 export declare function resumeKey(memory: Pick<ReconcileInput, 'id' | 'text'>): string;
 /** 状态文件路径(与 `pendingPathFor` / `state.json` 同目录)。 */
 export declare function reconcileStatePathFor(dataDir: string): string;
-/** 读状态;**文件损坏/版本不符一律当作空状态**,不抛(续跑状态坏了不该阻止运行)。 */
-export declare function loadRunState(file: string): Promise<ReconcileRunState | undefined>;
+/**
+ * 读状态。
+ *
+ * **读侧分类**(文件层加固 T2.10,审计 D2 点名补上):原注释写「文件损坏/版本不符
+ * 一律当作空状态」——损坏**不再静默**:`missing` 是首次运行(不告警),而
+ * `corrupt` / `unreadable` / `unknown_version` 一律记诊断后才按空状态继续。
+ * 「不覆盖」由 `atomicWriteJson` 的覆盖保护兜住(损坏文件写不进去,会显式报错)。
+ *
+ * 仍然**不抛**:续跑状态只是"跳过已判条目"的优化,坏了重跑一遍即可,不该阻止运行。
+ */
+export declare function loadRunState(file: string, logger?: MemoryLogger): Promise<ReconcileRunState | undefined>;
 /**
  * 预估并裁剪。
  *

package/dist/pipeline/reconcile-run.js

@@ -20,7 +20,8 @@
  */
 import { createHash } from 'node:crypto';
 import { CHARS_PER_TOKEN } from '../util/context-occupancy.js';
-import { atomicWriteJson, readJsonIfExists } from '../util/io.js';
+import { atomicWriteJson, readJsonStrict } from '../util/io.js';
+import { RECONCILE_STATE_FILE_VERSION } from '../store/file-versions.js';
 import { renderReport, runReconcile, } from './reconcile.js';
 export const DEFAULT_RECONCILE_BUDGET = {
     maxRecords: 50,
@@ -40,13 +41,34 @@ export function resumeKey(memory) {
 export function reconcileStatePathFor(dataDir) {
     return `${dataDir.replace(/[\\/]+$/, '')}/reconcile-state.json`;
 }
-/** 读状态;**文件损坏/版本不符一律当作空状态**,不抛(续跑状态坏了不该阻止运行)。 */
-export async function loadRunState(file) {
-    const raw = await readJsonIfExists(file);
-    if (!raw || raw.version !== 1 || !Array.isArray(raw.done))
+/**
+ * 读状态。
+ *
+ * **读侧分类**(文件层加固 T2.10,审计 D2 点名补上):原注释写「文件损坏/版本不符
+ * 一律当作空状态」——损坏**不再静默**:`missing` 是首次运行(不告警),而
+ * `corrupt` / `unreadable` / `unknown_version` 一律记诊断后才按空状态继续。
+ * 「不覆盖」由 `atomicWriteJson` 的覆盖保护兜住(损坏文件写不进去,会显式报错)。
+ *
+ * 仍然**不抛**:续跑状态只是"跳过已判条目"的优化,坏了重跑一遍即可,不该阻止运行。
+ */
+export async function loadRunState(file, logger) {
+    const r = await readJsonStrict(file, {
+        expectedVersion: RECONCILE_STATE_FILE_VERSION,
+    });
+    if (!r.ok) {
+        if (r.reason === 'missing')
+            return undefined;
+        const why = r.reason === 'corrupt' ? '损坏' : r.reason === 'unknown_version' ? '版本未知' : '不可读';
+        logger?.warn(`[memory] 冲突续跑状态${why}(本次全量重核,原文件不覆盖): ${file}${r.detail ? ` — ${r.detail}` : ''}`);
         return undefined;
+    }
+    const raw = r.value;
+    if (!Array.isArray(raw.done)) {
+        logger?.warn(`[memory] 冲突续跑状态形状不符(缺 done 数组,本次全量重核): ${file}`);
+        return undefined;
+    }
     return {
-        version: 1,
+        version: RECONCILE_STATE_FILE_VERSION,
         runId: typeof raw.runId === 'string' ? raw.runId : '',
         startedAt: typeof raw.startedAt === 'number' ? raw.startedAt : 0,
         updatedAt: typeof raw.updatedAt === 'number' ? raw.updatedAt : 0,
@@ -149,10 +171,10 @@ export function renderEstimate(estimate, budget) {
  */
 export async function executeReconcile(deps, plan, opts = {}) {
     const stateFile = opts.stateFile;
-    const previous = stateFile === undefined ? undefined : await loadRunState(stateFile);
+    const previous = stateFile === undefined ? undefined : await loadRunState(stateFile, opts.logger);
     const done = new Set(previous?.done ?? []);
     const state = previous ?? {
-        version: 1,
+        version: RECONCILE_STATE_FILE_VERSION,
         runId: createHash('sha1').update(String(Date.now())).digest('hex').slice(0, 12),
         startedAt: Date.now(),
         updatedAt: Date.now(),
@@ -198,7 +220,13 @@ export async function executeReconcile(deps, plan, opts = {}) {
 }
 /** 清空续跑状态(显式动作:下次运行会重核所有条目,**会重复计费**)。 */
 export async function resetRunState(file) {
-    await atomicWriteJson(file, { version: 1, runId: '', startedAt: 0, updatedAt: 0, done: [] });
+    await atomicWriteJson(file, {
+        version: RECONCILE_STATE_FILE_VERSION,
+        runId: '',
+        startedAt: 0,
+        updatedAt: 0,
+        done: [],
+    });
 }
 /** 供装配层使用:把证据面与 judge 组装成 deps。 */
 export function makeReconcileDeps(evidence, judge, logger) {

package/dist/pipeline/runner.d.ts

@@ -70,6 +70,9 @@ export declare class MemoryRunner {
     /** 停止标志(dispose 序置位):不再取新任务;进行中任务自然收尾。 */
     private stopped;
     private pending;
+    /** pending.json 的只读降级原因(undefined = 正常):非空时不再回写缓冲。 */
+    private pendingDegraded;
+    private pendingDegradedLogged;
     /** 各档位桶渐进阈值(1 起步翻倍至稳态毕业;随 pending.json 持久化)。 */
     private warmup;
     /** 每会话最后活动时间(闲置兜底判定用)。 */

package/dist/pipeline/runner.js

@@ -162,6 +162,9 @@ export class MemoryRunner {
     /** 停止标志(dispose 序置位):不再取新任务;进行中任务自然收尾。 */
     stopped = false;
     pending = emptyPending();
+    /** pending.json 的只读降级原因(undefined = 正常):非空时不再回写缓冲。 */
+    pendingDegraded;
+    pendingDegradedLogged = false;
     /** 各档位桶渐进阈值(1 起步翻倍至稳态毕业;随 pending.json 持久化)。 */
     warmup = freshWarmup();
     /** 每会话最后活动时间(闲置兜底判定用)。 */
@@ -199,7 +202,8 @@ export class MemoryRunner {
         }
         // 恢复未蒸馏缓冲(上次进程退出前未蒸馏的消息,含失败待重试与攒阈值中途的)
         try {
-            const { buckets: loaded, warmup } = await loadPending(this.pendingFile, this.logger);
+            const { buckets: loaded, warmup, degraded } = await loadPending(this.pendingFile, this.logger);
+            this.pendingDegraded = degraded;
             for (const key of PENDING_MODES) {
                 if (loaded[key].length > PENDING_BUCKET_CAP)
                     loaded[key] = loaded[key].slice(-PENDING_BUCKET_CAP);
@@ -486,6 +490,16 @@ export class MemoryRunner {
      *  非重建轮持久化前按桶截断到上限:重建取消后的大桶不至于在后续每次
      *  蒸馏尝试时反复整量序列化落盘(多 MB 级 IO);重建轮豁免维持。 */
     async persistPending(noBufferCap = false) {
+        // 只读降级(pending.json 损坏或版本未知):缓冲不再落盘,但**蒸馏照常跑**——
+        // 缓冲只是"待蒸馏队列",丢了不回写最多是重启后重蒸馏一轮,
+        // 而按旧解释覆盖新格式会真的弄坏文件。
+        if (this.pendingDegraded !== undefined) {
+            if (!this.pendingDegradedLogged) {
+                this.pendingDegradedLogged = true;
+                this.logger.warn(`[memory] 未蒸馏缓冲处于只读降级(${this.pendingDegraded}),已停止回写(磁盘文件保持不变)`);
+            }
+            return;
+        }
         try {
             if (!noBufferCap) {
                 for (const key of PENDING_MODES) {

package/dist/store/embedding-source.d.ts

@@ -19,10 +19,36 @@ export declare class EmbeddingSourceStore {
     private readonly file;
     private writeQueue;
     private readonly logger?;
+    /** 只读降级原因(undefined = 正常):文件损坏/不可读时置位,此后 `set()` 一律失败。 */
+    private degraded;
+    /** 本进程上次成功写入的磁盘内容(紧凑 JSON);并发冲突判据。 */
+    private lastPersisted;
     constructor(dataDir: string, logger?: MemoryLogger);
     get(): EmbeddingSourceState;
+    /**
+     * 读侧 strict 化(文件层加固 T2.11)。
+     *
+     * 旧实现是「裸 readFile + 外层 `catch {}`」:那个 catch 同时吞掉 ENOENT 与
+     * **JSON 解析错误**,于是「文件损坏」与「首次运行」长得一模一样——既无告警,
+     * 也会在随后被回写覆盖。现在三态分开:
+     * - `missing` → 默认 remote(历史行为,老用户无感),**不告警**;
+     * - `corrupt` / `unreadable` → 告警 + **只读降级**(后续 `set()` 抛错,不覆盖原文件);
+     * - 形状非法(解析成功但字段不对)→ 告警,同样按默认 remote 起步。
+     */
     init(): Promise<void>;
+    /**
+     * 改状态并写穿持久化。
+     *
+     * **失败必须对调用方可观测**:旧实现是 `writeQueue.then(persist).catch(() => {})`,
+     * 写失败后 `await` 照样 resolve——调用方以为已落盘,重启却回到旧源(G6 静默失败)。
+     * 现在本次 await 直接抛出;队列本身用 `.catch()` 兜住,免得一次失败把后续
+     * set 永久钉在 rejected 链上。
+     */
     set(next: EmbeddingSourceState): Promise<void>;
+    /**
+     * 落盘。走 `atomicWriteText` 而不是自研 tmp+rename:白拿文件级 fsync、
+     * 随机 tmp 名(旧实现的固定名 `*.tmp` 在多实例下会撞名)、以及失败路径清理。
+     */
     private persist;
 }
 export interface InitialEmbedding {

package/dist/store/embedding-source.js

@@ -13,8 +13,8 @@
  *   重嵌取消/部分失败 → 已切换(物理表即新维度,meta 已同步),缺失向量由周期
  *   backfill 补齐——不回滚(回滚需要再 drop 一次表,得不偿失)。
  */
-import { promises as fs } from 'node:fs';
 import * as path from 'node:path';
+import { readJsonStrict, rmwJson } from '../util/io.js';
 import { NoopEmbeddingService, RemoteEmbeddingService } from './embedding.js';
 import { catalogById, MODEL_CATALOG } from './model-catalog.js';
 import { LocalEmbeddingService } from './local-embedding.js';
@@ -28,6 +28,10 @@ export class EmbeddingSourceStore {
     file;
     writeQueue = Promise.resolve();
     logger;
+    /** 只读降级原因(undefined = 正常):文件损坏/不可读时置位,此后 `set()` 一律失败。 */
+    degraded;
+    /** 本进程上次成功写入的磁盘内容(紧凑 JSON);并发冲突判据。 */
+    lastPersisted;
     constructor(dataDir, logger) {
         this.file = path.join(dataDir, 'embedding-source.json');
         this.logger = logger;
@@ -35,31 +39,70 @@ export class EmbeddingSourceStore {
     get() {
         return { ...this.state };
     }
+    /**
+     * 读侧 strict 化(文件层加固 T2.11)。
+     *
+     * 旧实现是「裸 readFile + 外层 `catch {}`」:那个 catch 同时吞掉 ENOENT 与
+     * **JSON 解析错误**,于是「文件损坏」与「首次运行」长得一模一样——既无告警,
+     * 也会在随后被回写覆盖。现在三态分开:
+     * - `missing` → 默认 remote(历史行为,老用户无感),**不告警**;
+     * - `corrupt` / `unreadable` → 告警 + **只读降级**(后续 `set()` 抛错,不覆盖原文件);
+     * - 形状非法(解析成功但字段不对)→ 告警,同样按默认 remote 起步。
+     */
     async init() {
-        try {
-            const raw = await fs.readFile(this.file, 'utf8');
-            const parsed = JSON.parse(raw);
-            if ((parsed.source === 'remote' || parsed.source === 'local' || parsed.source === 'off') &&
-                (parsed.activeModel === null || typeof parsed.activeModel === 'string')) {
-                this.state = { source: parsed.source, activeModel: parsed.activeModel };
-            }
-            else {
-                this.logger?.warn('[memory] 嵌入源状态文件损坏,按默认 remote 起步');
-            }
+        const r = await readJsonStrict(this.file);
+        if (!r.ok) {
+            if (r.reason === 'missing')
+                return;
+            this.degraded = r.reason;
+            this.logger?.warn(`[memory] 嵌入源状态文件${r.reason === 'corrupt' ? '损坏' : '不可读'}(${this.file}): ` +
+                `按默认 remote 起步且**不回写**,原文件已保留${r.detail ? ` — ${r.detail}` : ''}`);
+            return;
+        }
+        const parsed = r.value;
+        if ((parsed.source === 'remote' || parsed.source === 'local' || parsed.source === 'off') &&
+            (parsed.activeModel === null || typeof parsed.activeModel === 'string')) {
+            this.state = { source: parsed.source, activeModel: parsed.activeModel };
+            this.lastPersisted = JSON.stringify(this.state);
         }
-        catch {
-            // 无文件 = 历史行为(跟随部署配置的远程嵌入)
+        else {
+            this.logger?.warn('[memory] 嵌入源状态文件形状非法,按默认 remote 起步');
         }
     }
+    /**
+     * 改状态并写穿持久化。
+     *
+     * **失败必须对调用方可观测**:旧实现是 `writeQueue.then(persist).catch(() => {})`,
+     * 写失败后 `await` 照样 resolve——调用方以为已落盘,重启却回到旧源(G6 静默失败)。
+     * 现在本次 await 直接抛出;队列本身用 `.catch()` 兜住,免得一次失败把后续
+     * set 永久钉在 rejected 链上。
+     */
     async set(next) {
+        if (this.degraded !== undefined) {
+            // 损坏文件绝不覆盖:重启会回到旧源,但用户至少能看到这条失败(不再"改了没生效")
+            throw new Error(`嵌入源状态文件${this.degraded === 'corrupt' ? '已损坏' : '不可读'},拒绝覆盖: ${this.file}`);
+        }
         this.state = { source: next.source, activeModel: next.activeModel };
-        this.writeQueue = this.writeQueue.then(() => this.persist()).catch(() => { });
-        await this.writeQueue;
+        const write = this.writeQueue.then(() => this.persist());
+        this.writeQueue = write.catch(() => { });
+        await write;
     }
+    /**
+     * 落盘。走 `atomicWriteText` 而不是自研 tmp+rename:白拿文件级 fsync、
+     * 随机 tmp 名(旧实现的固定名 `*.tmp` 在多实例下会撞名)、以及失败路径清理。
+     */
     async persist() {
-        const tmp = this.file + '.tmp';
-        await fs.writeFile(tmp, JSON.stringify(this.state, null, 2), 'utf8');
-        await fs.rename(tmp, this.file);
+        // 锁内 RMW(T4.11):嵌入源是"改一次落一次"的低频写,锁开销可忽略;
+        // 两个实例并发 set 时,后写的那个会看到磁盘与自己的上次写入不同 → 显式失败。
+        await rmwJson(this.file, async (cur) => {
+            const diskRaw = cur.ok ? JSON.stringify(cur.value) : undefined;
+            if (this.lastPersisted !== undefined && diskRaw !== undefined && diskRaw !== this.lastPersisted) {
+                throw new Error(`嵌入源状态已被其它进程更新,本次写入已取消以避免覆盖;请重试该操作`);
+            }
+            const next = { source: this.state.source, activeModel: this.state.activeModel };
+            this.lastPersisted = JSON.stringify(next);
+            return { next, result: undefined };
+        }, { logger: this.logger, purpose: 'embedding-source-rmw' });
     }
 }
 /** 远程档部署上限:baseUrl + model + 维度 + enabled。apiKey 可选(本地免 key 自托管
@@ -403,13 +446,21 @@ export class EmbeddingManager {
                 if (result.error)
                     throw new Error(result.error);
             }
-            await this.sourceStore.set(next);
+            // 落盘失败不等于切换失败:走到这里服务已换、物理表已按新维度重建——真相是
+            // "本次会话用新源、重启回旧源"。旧实现把失败吞掉(§6.2),UI 却显示完全成功,
+            // 于是用户以为已保存。这里如实报出来,不再把两种结果混成一个 'done'。
+            let persistNote = '';
+            try {
+                await this.sourceStore.set(next);
+            }
+            catch (err) {
+                persistNote = ';状态持久化失败,重启将回到旧嵌入源';
+                this.deps.logger.warn(`[memory] 嵌入源状态持久化失败(本次会话仍用新源): ${err instanceof Error ? err.message : String(err)}`);
+            }
             this.activeNote = undefined;
             this.applyPhase = 'done';
             this.applyMessage =
-                next.source === 'off'
-                    ? '已切换为关键词检索'
-                    : '切换完成' + pendingNote;
+                (next.source === 'off' ? '已切换为关键词检索' : '切换完成' + pendingNote) + persistNote;
         }
         catch (err) {
             this.applyPhase = 'error';

package/dist/store/file-versions.d.ts

@@ -0,0 +1,27 @@
+/**
+ * 持久化文件的 schema 版本(单一事实源)。
+ *
+ * 以前这些字面量散落在各 store(`version: 1` × 15 / `version: 2` × 2),读侧
+ * 有的校验有的不校验(findings §3.2)。集中到这里后:
+ * - 写侧统一用常量,不会写出"自己都不认识"的版本;
+ * - 读侧统一拿常量做 `expectedVersion`,未知版本才有判据(fail-closed 的前提)。
+ *
+ * 注意:**只收持久化文件的 schema 版本**。契约版本 / 快照版本 / 协议版本等
+ * 非持久化用途的字面量不在此列(它们有各自的常量)。
+ */
+/** `state.json`:v1 = 平铺,v2 = 分族(chat/work)。 */
+export declare const STATE_FILE_VERSION = 2;
+/** v1 平铺格式的版本号(迁移判定用;`undefined` 亦按 v1 处理)。 */
+export declare const STATE_FILE_VERSION_LEGACY = 1;
+/** `slots.json`。 */
+export declare const SLOTS_FILE_VERSION = 1;
+/** `session-modes.json`。 */
+export declare const SESSION_MODES_FILE_VERSION = 1;
+/** `occupancy.json`。 */
+export declare const OCCUPANCY_FILE_VERSION = 1;
+/** `recall-dedupe.json`。 */
+export declare const RECALL_DEDUPE_FILE_VERSION = 1;
+/** `pending.json`。 */
+export declare const PENDING_FILE_VERSION = 1;
+/** `reconcile-state.json`。 */
+export declare const RECONCILE_STATE_FILE_VERSION = 1;

package/dist/store/file-versions.js

@@ -0,0 +1,27 @@
+/**
+ * 持久化文件的 schema 版本(单一事实源)。
+ *
+ * 以前这些字面量散落在各 store(`version: 1` × 15 / `version: 2` × 2),读侧
+ * 有的校验有的不校验(findings §3.2)。集中到这里后:
+ * - 写侧统一用常量,不会写出"自己都不认识"的版本;
+ * - 读侧统一拿常量做 `expectedVersion`,未知版本才有判据(fail-closed 的前提)。
+ *
+ * 注意:**只收持久化文件的 schema 版本**。契约版本 / 快照版本 / 协议版本等
+ * 非持久化用途的字面量不在此列(它们有各自的常量)。
+ */
+/** `state.json`:v1 = 平铺,v2 = 分族(chat/work)。 */
+export const STATE_FILE_VERSION = 2;
+/** v1 平铺格式的版本号(迁移判定用;`undefined` 亦按 v1 处理)。 */
+export const STATE_FILE_VERSION_LEGACY = 1;
+/** `slots.json`。 */
+export const SLOTS_FILE_VERSION = 1;
+/** `session-modes.json`。 */
+export const SESSION_MODES_FILE_VERSION = 1;
+/** `occupancy.json`。 */
+export const OCCUPANCY_FILE_VERSION = 1;
+/** `recall-dedupe.json`。 */
+export const RECALL_DEDUPE_FILE_VERSION = 1;
+/** `pending.json`。 */
+export const PENDING_FILE_VERSION = 1;
+/** `reconcile-state.json`。 */
+export const RECONCILE_STATE_FILE_VERSION = 1;

package/dist/store/l1-snapshot.d.ts

@@ -1,4 +1,4 @@
-import type { MemoryRecord } from '../types.js';
+import type { MemoryLogger, MemoryRecord } from '../types.js';
 import type { ConflictPair } from './conflicts.js';
 export declare const SNAPSHOT_VERSION = 1;
 /** 快照里的一节:行数 + 内容哈希。哈希是"内容有没有变"的判据,行数看不出来。 */
@@ -63,6 +63,7 @@ export interface SnapshotSummary {
  */
 export declare function listSnapshots(dataDir: string, opts?: {
     limit?: number;
+    logger?: MemoryLogger;
 }): Promise<{
     items: SnapshotSummary[];
     total: number;
@@ -128,9 +129,22 @@ export interface CreateSnapshotResult {
  */
 export declare function projectConflictsForHash(rows: readonly ConflictPair[]): Array<Record<string, unknown>>;
 export declare function createL1Snapshot(db: SnapshotDbLike, dir: string, reason: string, now?: Date): Promise<CreateSnapshotResult>;
-/** 读快照清单;不存在或版本不符返回 undefined。 */
+/**
+ * 读快照清单。
+ *
+ * **读侧分类**(文件层加固 T2.7):
+ * - 缺失 / 版本不符 → `undefined`(沿用既有"这份快照不可用"的语义);
+ * - **损坏 / 不可读 → 抛错**:旧实现把损坏也压成 `undefined`,于是"清单坏了"和
+ *   "没有清单"在调用方眼里一样——恢复时会选中一个半截快照却报 0 条成功。
+ */
 export declare function readSnapshotManifest(dir: string): Promise<L1SnapshotManifest | undefined>;
-/** 读回快照里的记录(与 `createL1Snapshot` 的写入格式必须成对:`atomicWriteJson` ↔ `readJsonIfExists`)。 */
+/**
+ * 读回快照里的记录(与 `createL1Snapshot` 的写入格式必须成对)。
+ *
+ * **损坏不再返回空数组**:空数组会让"记录文件坏了"表现成"这份快照有 0 条记录",
+ * 恢复下去就是静默丢数据。缺文件同样抛错——建快照时正文与清单是成对写入的,
+ * 只缺其一说明这份快照本身不完整。
+ */
 export declare function readSnapshotRecords(dir: string): Promise<MemoryRecord[]>;
 /** 快照与当前库的差异。 */
 export interface SnapshotVerification {

package/dist/store/l1-snapshot.js

@@ -34,7 +34,7 @@
  */
 import { createHash } from 'node:crypto';
 import { readdir } from 'node:fs/promises';
-import { atomicWriteJson, readJsonIfExists } from '../util/io.js';
+import { atomicWriteJson, readJsonStrict } from '../util/io.js';
 export const SNAPSHOT_VERSION = 1;
 /** 快照目录名:`l1-<时间戳>-<原因>`。**时间戳在前**,目录自然按时间排序。 */
 export function snapshotDirName(createdAt, reason) {
@@ -102,7 +102,16 @@ export async function listSnapshots(dataDir, opts = {}) {
         if (!isSnapshotName(name))
             continue;
         const dir = `${root}/${name}`;
-        const manifest = await readSnapshotManifest(dir);
+        let manifest;
+        try {
+            manifest = await readSnapshotManifest(dir);
+        }
+        catch (err) {
+            // 单个快照清单损坏不该让整个列表拿不到:跳过它,但**必须留诊断**
+            // (旧实现把损坏当"没有清单"静默略过,用户永远不知道坏了一份)
+            opts.logger?.warn(`[memory] 快照清单损坏,已从列表中排除: ${dir} — ${err instanceof Error ? err.message : String(err)}`);
+            continue;
+        }
         if (manifest === undefined)
             continue;
         items.push({
@@ -222,17 +231,39 @@ export async function createL1Snapshot(db, dir, reason, now = new Date()) {
     await atomicWriteJson(`${dir}/manifest.json`, manifest);
     return { dir, name: snapshotNameOf(dir), manifest, records };
 }
-/** 读快照清单;不存在或版本不符返回 undefined。 */
+/**
+ * 读快照清单。
+ *
+ * **读侧分类**(文件层加固 T2.7):
+ * - 缺失 / 版本不符 → `undefined`(沿用既有"这份快照不可用"的语义);
+ * - **损坏 / 不可读 → 抛错**:旧实现把损坏也压成 `undefined`,于是"清单坏了"和
+ *   "没有清单"在调用方眼里一样——恢复时会选中一个半截快照却报 0 条成功。
+ */
 export async function readSnapshotManifest(dir) {
-    const raw = await readJsonIfExists(`${dir}/manifest.json`);
-    if (!raw || raw.version !== SNAPSHOT_VERSION)
+    const r = await readJsonStrict(`${dir}/manifest.json`, {
+        expectedVersion: SNAPSHOT_VERSION,
+    });
+    if (r.ok)
+        return r.value;
+    if (r.reason === 'missing' || r.reason === 'unknown_version')
         return undefined;
-    return raw;
+    throw new Error(`快照清单${r.reason === 'corrupt' ? '已损坏' : '不可读'}(${dir})${r.detail ? ` — ${r.detail}` : ''};` +
+        `原文件未改动,请人工确认后再恢复`);
 }
-/** 读回快照里的记录(与 `createL1Snapshot` 的写入格式必须成对:`atomicWriteJson` ↔ `readJsonIfExists`)。 */
+/**
+ * 读回快照里的记录(与 `createL1Snapshot` 的写入格式必须成对)。
+ *
+ * **损坏不再返回空数组**:空数组会让"记录文件坏了"表现成"这份快照有 0 条记录",
+ * 恢复下去就是静默丢数据。缺文件同样抛错——建快照时正文与清单是成对写入的,
+ * 只缺其一说明这份快照本身不完整。
+ */
 export async function readSnapshotRecords(dir) {
-    const raw = await readJsonIfExists(`${dir}/l1-records.json`);
-    return Array.isArray(raw) ? raw : [];
+    const r = await readJsonStrict(`${dir}/l1-records.json`);
+    if (!r.ok) {
+        const why = r.reason === 'missing' ? '缺失' : r.reason === 'corrupt' ? '已损坏' : '不可读';
+        throw new Error(`快照记录${why}(${dir})${r.detail ? ` — ${r.detail}` : ''}`);
+    }
+    return Array.isArray(r.value) ? r.value : [];
 }
 /** 比对快照与当前库(**按内容哈希**,不是按行数)。 */
 export async function verifySnapshot(db, dir) {

package/dist/store/l1.js

@@ -306,7 +306,7 @@ export class L1Store {
     // ───────────────────────────────────────────────────────────────────────────
     /** 可用快照列表(按时间倒序;面板/工具据此选一份来恢复)。 */
     listSnapshots(opts = {}) {
-        return listSnapshotsIn(this.dataDir, opts);
+        return listSnapshotsIn(this.dataDir, { ...opts, logger: this.logger });
     }
     /**
      * 名字 → 真实快照。

package/dist/store/occupancy.d.ts

@@ -7,10 +7,20 @@ export declare class OccupancyStore {
     private readonly file;
     private readonly entries;
     private persistFailed;
+    /** 只读降级原因(undefined = 正常):非空时内存账目照常有效,但停止回写。 */
+    private degraded;
+    private degradedLogged;
+    /** 本进程上次成功写入的磁盘内容(紧凑 JSON);并发冲突判据:磁盘与它不同 = 别人写过。 */
+    private lastPersisted;
     /** 串行化持久化写(避免并发原子写撞临时文件名);init 链最前(先载入再落盘,防丢更新)。 */
     private writeChain;
     constructor(dataDir: string, logger?: MemoryLogger | undefined);
-    /** 载入持久化账目(合并进内存——构造与载入之间发生的 save 不丢);失败降级内存态。 */
+    /**
+     * 载入持久化账目(合并进内存——构造与载入之间发生的 save 不丢);失败降级内存态。
+     *
+     * **读侧分类**(文件层加固 T2):缺失合法;损坏/不可读 → 告警 + 只读降级(禁写);
+     * 未知版本 → **仍按当前形状读取** + 只读降级(本 store 无迁移路径)。
+     */
     private init;
     /**
      * 该会话的持久化账目(热路径同步读;从未注入/已复位返回 null)。