dsh-prime-memory 0.16.1-beta.0 → 0.16.1

package/CHANGELOG.md

@@ -58,6 +58,10 @@
 
 ## [0.16.1] — 2026-09-24
 
+### 新增
+
+- **记录面板「退场筛查」**：软删记录按设计不隐藏（可恢复），但与活跃记录混排不便分辨——现在列表工具行加了三态筛选「**全部 / 仅活跃 / 仅退场**」。后端 `listL1` 补同口径三态过滤（缺省全量，快照/重建不受影响；`retired:true` 与 `listRetiredL1` 同一判据，两份视图看到同一批行）；契约 `ListRecordsRequest.retired?: boolean`。筛查仅浏览路径生效——关键词检索只覆盖检索面，已退场记录本就不在其中。「加载更多」与删除/恢复后的自动刷新都会保持当前筛查态。
+
 ### 修复
 
 - **面板「删除记忆」确认后看似毫无反应——退场态没有透传给 UI。** 软删（retire）在服务端一直正常（`valid_to` 闭合 + 撤出检索面 + 可恢复），但按设计活动列表**保留**退场记录（`l1-retire` 测试钉死「面板浏览路径不隐藏退场记录」），而 `UiRecord` 契约里根本没有"是否已退场"字段、活动列表的记录行也没有任何视觉差异，"已退场"区又默认折叠——用户确认删除后看到的是**一条一模一样的记录**，自然以为"删除没生效"。

package/dist/client.js

@@ -3226,6 +3226,11 @@ var __defProp = Object.defineProperty;
 		// client/src/tabs/RecordsTab.tsx
 		var import_react15 = require("react");
 		var import_jsx_runtime15 = require("react/jsx-runtime");
+		function retiredSelOf(r) {
+		  if (r === "active") return false;
+		  if (r === "retired") return true;
+		  return void 0;
+		}
 		var TYPE_CHOICES = [
 		  "persona",
 		  "episodic",
@@ -3255,9 +3260,10 @@ var __defProp = Object.defineProperty;
 		  const [sceneFilter, setSceneFilter] = (0, import_react15.useState)("");
 		  const [hallFilter, setHallFilter] = (0, import_react15.useState)([]);
 		  const [tagFilter, setTagFilter] = (0, import_react15.useState)("");
+		  const [retiredFilter, setRetiredFilter] = (0, import_react15.useState)("");
 		  const [rooms, setRooms] = (0, import_react15.useState)([]);
 		  const [wingCatalog, setHallCatalog] = (0, import_react15.useState)(null);
-		  const [last, setLast] = (0, import_react15.useState)({ query: "", type: "", scene: "", halls: [], tag: "" });
+		  const [last, setLast] = (0, import_react15.useState)({ query: "", type: "", scene: "", halls: [], tag: "", retired: "" });
 		  const seqRef = (0, import_react15.useRef)(0);
 		  const fetchPage = (0, import_react15.useCallback)(
 		    (conds, offset, append) => {
@@ -3270,6 +3276,8 @@ var __defProp = Object.defineProperty;
 		      if (conds.scene) payload.scene = conds.scene;
 		      if (conds.halls.length > 0) payload.halls = conds.halls;
 		      if (conds.tag) payload.tag = conds.tag;
+		      const retiredSel = retiredSelOf(conds.retired);
+		      if (retiredSel !== void 0) payload.retired = retiredSel;
 		      rpc("dsh-memory/list-records", payload).then((r) => {
 		        if (token !== seqRef.current) return;
 		        setLoading(false);
@@ -3294,7 +3302,13 @@ var __defProp = Object.defineProperty;
 		    [rpc]
 		  );
 		  const search = () => {
-		    const conds = { query: query.trim(), type: typeFilter, scene: sceneFilter, halls: hallFilter, tag: tagFilter };
+		    const conds = { query: query.trim(), type: typeFilter, scene: sceneFilter, halls: hallFilter, tag: tagFilter, retired: retiredFilter };
+		    setLast(conds);
+		    fetchPage(conds, 0, false);
+		  };
+		  const applyRetiredFilter = (next) => {
+		    setRetiredFilter(next);
+		    const conds = { query: query.trim(), type: typeFilter, scene: sceneFilter, halls: hallFilter, tag: tagFilter, retired: next };
 		    setLast(conds);
 		    fetchPage(conds, 0, false);
 		  };
@@ -3305,7 +3319,7 @@ var __defProp = Object.defineProperty;
 		    });
 		  }, [rpc]);
 		  (0, import_react15.useEffect)(() => {
-		    fetchPage({ query: "", type: "", scene: "", halls: [], tag: "" }, 0, false);
+		    fetchPage({ query: "", type: "", scene: "", halls: [], tag: "", retired: "" }, 0, false);
 		    loadRooms();
 		  }, [fetchPage, loadRooms]);
 		  const loadHiPriv = (0, import_react15.useCallback)(() => {
@@ -3486,7 +3500,7 @@ var __defProp = Object.defineProperty;
 		            onClick: () => {
 		              const next = on ? "" : r.room;
 		              setTagFilter(next);
-		              const conds = { query: query.trim(), type: typeFilter, scene: sceneFilter, halls: hallFilter, tag: next };
+		              const conds = { query: query.trim(), type: typeFilter, scene: sceneFilter, halls: hallFilter, tag: next, retired: retiredFilter };
 		              setLast(conds);
 		              fetchPage(conds, 0, false);
 		            },
@@ -3508,6 +3522,29 @@ var __defProp = Object.defineProperty;
 		    ] }) : /* @__PURE__ */ (0, import_jsx_runtime15.jsx)("div", { style: { ...S.muted, marginBottom: 10 }, children: "Room 分类：暂无（由反刍涌现的标签自动生成，无需手工建立）" }),
 		    /* @__PURE__ */ (0, import_jsx_runtime15.jsxs)("div", { style: { ...S.flexRow, marginBottom: 10 }, children: [
 		      /* @__PURE__ */ (0, import_jsx_runtime15.jsx)("span", { style: S.muted, children: loading ? "加载中…" : countText }),
+		      /* @__PURE__ */ (0, import_jsx_runtime15.jsx)("span", { style: S.muted, children: "退场筛查" }),
+		      [["", "全部"], ["active", "仅活跃"], ["retired", "仅退场"]].map(([val, label]) => {
+		        const on = retiredFilter === val;
+		        return /* @__PURE__ */ (0, import_jsx_runtime15.jsx)(
+		          "button",
+		          {
+		            type: "button",
+		            title: val === "" ? "活跃与已退场混排（已退场的带徽标）" : val === "active" ? "只看未退场的记忆" : "只看已退场（软删）的记忆，可在此恢复",
+		            onClick: () => applyRetiredFilter(val),
+		            style: {
+		              cursor: "pointer",
+		              fontSize: 12,
+		              padding: "2px 10px",
+		              borderRadius: 999,
+		              border: on ? "1px solid var(--dsh-mem-accent)" : "1px solid var(--dsh-mem-border)",
+		              background: on ? "var(--dsh-mem-bg-inset)" : "transparent",
+		              color: on ? "var(--dsh-mem-accent)" : "var(--dsh-mem-text-2)"
+		            },
+		            children: label
+		          },
+		          val
+		        );
+		      }),
 		      /* @__PURE__ */ (0, import_jsx_runtime15.jsx)(
 		        NButton,
 		        {

package/dist/contract.d.ts

@@ -650,6 +650,12 @@ export interface ListRecordsRequest {
      * Room 由 tags 派生(自生长),故这里传的是**具体 tag 名**而非枚举 id。
      */
     tag?: string;
+    /**
+     * 退场(软删)筛查:三态。省略 = 全部(活跃+已退场混排,靠 `UiRecord.retired`
+     * 徽标区分);`false` = 仅活跃;`true` = 仅已退场。
+     * **仅浏览路径生效**:关键词检索只覆盖检索面,已退场记录本就不在其中。
+     */
+    retired?: boolean;
     /** 1~200,默认 50。 */
     limit?: number;
     /** 0~1_000_000。 */

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/stats.js

@@ -746,6 +746,9 @@ export async function handleEndpoint(endpoint, payload, deps) {
             const p = (payload ?? {});
             if (p.query !== undefined && p.query.length > 4096)
                 throw new Error('query 过长(≤4096 字符)');
+            // 退场筛查:三态(缺省=全部混排/false=仅活跃/true=仅已退场)。显式布尔才透传,
+            // 其余值(字符串/数字等)一律视为缺省——宁可宽看,不可静默筛掉一半。
+            const retiredSel = typeof p.retired === 'boolean' ? p.retired : undefined;
             // Room 过滤:tag 是**自生长**的 slug(无枚举),只做形状与长度校验(SQL 侧参数化)
             const tagSel = typeof p.tag === 'string' ? p.tag.trim().slice(0, 64) : '';
             if (tagSel && !isTag(tagSel))
@@ -803,7 +806,9 @@ export async function handleEndpoint(endpoint, payload, deps) {
                 };
                 return resp;
             }
-            const { items, total } = stores.l1.list({ type: p.type || undefined, scene: p.scene || undefined, hall: p.hall || undefined, halls: wingSel.length > 0 ? wingSel : undefined, tag: tagSel || undefined, limit, offset });
+            // 退场筛查仅浏览路径透传;检索路径不接——FTS/向量里本就没有已退场行,
+            // 接了只会让「仅退场+关键词」永远空结果,不如如实不筛。
+            const { items, total } = stores.l1.list({ type: p.type || undefined, scene: p.scene || undefined, hall: p.hall || undefined, halls: wingSel.length > 0 ? wingSel : undefined, tag: tagSel || undefined, retired: retiredSel, limit, offset });
             const resp = {
                 items: items.map(hitToUiRecord),
                 hasMore: offset + items.length < total,

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 {