@modusensus/dsh-mneme 0.3.7 → 0.3.9

package/README.md

@@ -5,7 +5,7 @@
 [![npm version](https://img.shields.io/npm/v/@modusensus/dsh-mneme?color=blue&label=npm)](https://www.npmjs.com/package/@modusensus/dsh-mneme)
 [![license](https://img.shields.io/badge/license-MIT-green)](LICENSE)
 [![Awesome](https://awesome-dsh-plugin.com/badge.svg)](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin)
-[![tests](https://img.shields.io/badge/tests-443%20passed-success)](https://github.com/modusensus/dsh-mneme)
+[![tests](https://img.shields.io/badge/tests-450%20passed-success)](https://github.com/modusensus/dsh-mneme)
 
 > 给 DeepSeek Harness 的跨会话记忆插件：让 Agent 记住你、记住项目、自动整理记忆。**Mneme**（Μνήμη）——希腊记忆女神 Mnemosyne 之名，掌管记忆与梦境，正如 autoDream 在后台巩固记忆。
 
@@ -18,6 +18,11 @@
 - **SQLite 主存储**：`~/.dsh/memory/memory.db`，`node:sqlite` 内置，零原生依赖
 - **Markdown 镜像**：`preferences.md` / `projects.md` / `decisions.md` / `history.md` / `summary.md`，人类可读、可手工编辑（**人工修改优先**合并回库）
 - **4+1 种记忆类型**：`preference`（偏好）/ `project`（项目）/ `decision`（决策）/ `history`（历史）/ `summary`（总览）
+- **镜像同步状态机（v0.3.6+）**：mirror 与主库强一致，用 `generation`（期望轮次）/ `applied_generation`（已应用轮次）建模同步债务
+  - 业务写操作在**自身事务内原子递增** desired generation——崩溃在 COMMIT 后、渲染前，重启也能凭 durable 债务恢复，绝不静默跳过（v0.3.8）
+  - `generation` 用 SQLite 原子语句递增，多进程并发零丢失；带 `CHECK` 上界，负数/溢出拒绝
+  - 逐 type 记录 `committed / failed / pending` 回执，健康端点区分 `ok / degraded / unknown`
+  - 状态写失败不静默：同步失败落日志并留债务，重启自动收敛
 
 ### 模型工具（7 个）
 
@@ -106,6 +111,29 @@ v0.3.0 起新增**记忆基因**层：从记忆里抽取**命名实体**、**带
 
 > 📖 详见 [实体结构化记忆设计](docs/ENTITIES.md) · [语义增强架构](docs/SEMANTIC.md) · [本地模型部署指南](docs/LOCAL_MODEL.md) · [从 v0.1 升级说明](docs/MIGRATION.md)
 
+## 🆕 最近版本亮点
+
+| 版本 | 亮点 |
+|------|------|
+| **v0.3.9** | 修复第三方审计 4 项 FAIL：CAS 同事务原子化、Mirror 降级回执透传、逐 type 物理终态收敛、Generation 强整数校验与并发初始化稳定化 |
+| **v0.3.8** | audit peer 复验 6 项运行时阻断全部修复：desired generation 同事务原子递增（崩溃窗口不再静默跳过）、同步失败不静默、原子 generation 增量（多进程零丢失）、逐 type committed/failed/pending 回执、读取失败显式 unknown、generation 上界/负数 CHECK |
+| **v0.3.7** | 启动竞态修复：人工编辑 md 镜像后重启向量重建失败（回灌移入 init 就绪后 + scheduleEmbed 就绪门） |
+| **v0.3.6** | mirror 同步状态机：generation/applied_generation 债务建模、F-NEW-03 mirror 健康状态、持久 dirty + 启动 recoverMirror |
+| **v0.3.0** | 记忆基因：实体/属性/关系三表 + 时间轴 + 实体搜索 + autoDream supersedes |
+
+## 🗺️ 进化路线图
+
+| 版本 | 状态 | 主题 | 说明 |
+|------|------|------|------|
+| v0.2.x | ✅ 完成 | 语义增强 + 反思更新 | 本地 Embedding/Rerank/聚类、`failure_memories` 失败追踪 |
+| v0.3.0 | ✅ 完成 | 记忆基因 | entities/attrs/relations 三表 + 时间轴 + 实体搜索 |
+| v0.3.6–0.3.8 | ✅ 完成 | 镜像一致性 + 审计加固 | generation 同步状态机、audit peer 6 项运行时阻断修复、450 测试全绿 |
+| v0.3.9 | ✅ 完成 | 审计加固 A/B/D/F | compareAndUpdate 同事务原子性、degraded 回执、逐 type 物理终态、整数 fail-closed、并发初始化稳定 |
+| **v0.4.0** | ⏳ 规划 | 反思性成长 | 纠错双向回流（改记忆同时反思"为什么记错/召回错"）+ 规则演进（从 failure 提炼规律注入系统提示）+ 自适应参数 |
+| **v0.5.0+** | 🚀 远期 | 自进化记忆 | 兴趣漂移跟踪 + 跨 workspace 记忆共享（等 DSH 支持） |
+
+> 新能力一律做成**可开关的功能**（配置启用/关闭），默认保守开启、不破坏现有行为。`failure_memories` 表与 autoDream 决策引擎已为 v0.4.0 铺好路。
+
 ## 📦 安装
 
 ### 前置条件
@@ -243,7 +271,7 @@ src/
 lib/
 ├── client.js         # Web 面板（手写 ModuleLoader bundle）
 └── *.js              # src 的同步分发产物
-test/                 # 443 个 node:test 测试（含审计与三轴线压测不变量）
+test/                 # 450 个 node:test 测试（含审计与三轴线压测不变量）
 scripts/              # e2e-dsh.js 端到端演示 · stress-dsh.js 三轴线压测 · sync-lib.js 同步
 ```
 
@@ -252,7 +280,7 @@ scripts/              # e2e-dsh.js 端到端演示 · stress-dsh.js 三轴线压
 ```bash
 cd dsh-mneme
 npm install        # 安装 peer 依赖（以 devDependencies 形式，用于本地测试）
-npm test           # 运行 443 个测试
+npm test           # 运行 450 个测试
 npm run stress     # 三轴线压测：长会话检索 / 冲突仲裁 / 多 Agent 并发（离线 mock LLM）
 npm run sync       # 把 src/ 同步到 lib/（发布时由 prepack 钩子自动执行）
 ```

package/lib/api.js

@@ -289,6 +289,14 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
         sendJson(res, 200, { mirror: { dirty: null, status: "unknown", last_error: null, last_attempt: null, success_at: null } });
         return;
       }
+      // Real read failure surfaces as dirty === null (peer blocker 5): report
+      // unknown explicitly instead of collapsing into a false "ok"/"degraded".
+      if (state.dirty === null) {
+        sendJson(res, 200, {
+          mirror: { dirty: null, status: "unknown", last_error: null, last_attempt: null, success_at: null }
+        });
+        return;
+      }
       // Sanitized: boolean dirty + coarse status only; error string is mapped to
       // a bounded code, never echoed verbatim.
       let code = null;
@@ -346,7 +354,7 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
   });
 
   return {
-    routes: 7,
+    routes: 9,
     dispose: () => {
       for (const dispose of disposers) dispose();
     }

package/lib/mirror.js

@@ -128,21 +128,33 @@ export function createMirror(dir) {
     for (const m of memories) {
       (byType[m.type] ??= []).push(m);
     }
+    // Per-type physical outcomes (audit peer D): a failed write for one type
+    // must not abort the whole render. Each type is written (or pruned) in its
+    // own try/catch and the result reported so the caller can persist per-type
+    // committed/failed receipts — a file that was already written is a real
+    // physical commit even when a sibling type errors.
+    const results = {};
     for (const type of Object.keys(TYPE_FILE)) {
-      const file = filePath(type);
-      const items = (byType[type] ?? [])
-        .slice()
-        .sort((a, b) => (a.updated_at < b.updated_at ? 1 : -1));
-      if (items.length === 0) {
-        // no memories of this type: drop any stale mirror file so deleted
-        // memories do not "resurrect" via readHumanEdits
-        rmSync(file, { force: true });
-        continue;
+      try {
+        const file = filePath(type);
+        const items = (byType[type] ?? [])
+          .slice()
+          .sort((a, b) => (a.updated_at < b.updated_at ? 1 : -1));
+        if (items.length === 0) {
+          // no memories of this type: drop any stale mirror file so deleted
+          // memories do not "resurrect" via readHumanEdits
+          rmSync(file, { force: true });
+        } else {
+          const header = `# ${TYPE_FILE[type]} — dsh-mneme 镜像\n\n<!-- 手工编辑此文件会被合并回记忆库（人工优先）。 -->\n\n`;
+          const body = items.map(renderMemory).join("\n");
+          writeFileSync(file, header + body, "utf8");
+        }
+        results[type] = { ok: true };
+      } catch (error) {
+        results[type] = { ok: false, error: error?.message ?? String(error) };
       }
-      const header = `# ${TYPE_FILE[type]} — dsh-mneme 镜像\n\n<!-- 手工编辑此文件会被合并回记忆库（人工优先）。 -->\n\n`;
-      const body = items.map(renderMemory).join("\n");
-      writeFileSync(file, header + body, "utf8");
     }
+    return results;
   }
 
   return { filePath, sync, readHumanEdits };

package/lib/service.js

@@ -384,10 +384,12 @@ export function createService({ store, mirror, config, onWrite, logger }) {
       throw error;
     } finally {
       txDepth--;
-      try {
-        syncMirror();
-      } catch (error) {
-        logger?.warn?.("syncMirror failed after transaction:", error);
+      // Sync failures are surfaced, not swallowed (peer blocker 2): the mirror
+      // debt was already recorded by markMirrorDirty inside syncMirror, so a
+      // restart recovers — but the operator must see it now, not after restart.
+      const syncResult = syncMirror();
+      if (!syncResult?.success && !syncResult?.deferred) {
+        logger?.warn?.("mirror sync failed after transaction:", syncResult?.error);
       }
       notifyWrite();
     }
@@ -408,7 +410,7 @@ export function createService({ store, mirror, config, onWrite, logger }) {
         tags: memory.tags ?? existing.tags,
         title: memory.title ?? existing.title
       });
-      syncMirror();
+      afterSync("write");
       notifyWrite();
       scheduleEmbed(merged);
       return { action: "merged", memory: merged };
@@ -421,7 +423,7 @@ export function createService({ store, mirror, config, onWrite, logger }) {
       importance: memory.importance ?? 3,
       source: memory.source ?? "manual"
     });
-    syncMirror();
+    afterSync("write");
     notifyWrite();
     scheduleEmbed(created);
     scheduleEntityExtraction(created);
@@ -481,7 +483,7 @@ export function createService({ store, mirror, config, onWrite, logger }) {
       }
     }
     if (applied) {
-      syncMirror();
+      afterSync("write");
       notifyWrite();
     }
     return applied;
@@ -577,16 +579,17 @@ export function createService({ store, mirror, config, onWrite, logger }) {
   //   - 逐 type 用 setTypeStatus 记录部分成功/失败（type_status JSON）；
   //   - 所有 store 状态写入各自 try/catch，失败只 warn，绝不向外抛（F-NEW-03）。
   function syncMirror() {
-    if (txDepth > 0 || !mirror) return; // deferred to the transaction's commit
+    if (txDepth > 0 || !mirror) return { success: true, deferred: true }; // deferred to the transaction's commit
     const now = new Date().toISOString();
     let gen;
     try {
-      // 绑定本次期望轮次，必须在任何渲染之前，避免制造幽灵债务
-      const state = store.incrementGeneration();
-      gen = state.generation;
+      // desired generation 已在业务写事务中原子递增（peer blocker 1）；这里
+      // 直接读当前值作为本次同步的目标轮次，不再自行 incrementGeneration。
+      const state = store.getMirrorState();
+      gen = state?.generation ?? 0;
     } catch (stateError) {
-      logger?.warn?.("syncMirror: incrementGeneration failed:", stateError);
-      return;
+      logger?.warn?.("syncMirror: getMirrorState failed:", stateError);
+      return { success: false, error: stateError?.message ?? String(stateError) };
     }
     // coveredTypes 提到 try 外初始化：即使 store.list 先抛错，catch 分支也有
     // 合法的空 Set 可迭代，保证 syncMirror 自身绝不抛（fail-safe）。
@@ -600,43 +603,89 @@ export function createService({ store, mirror, config, onWrite, logger }) {
         }
       }
 
-      // 全量渲染
-      mirror.sync(reconcileHumanEdits(list));
-
-      // 成功：CAS/fence 绑定到本地 gen，旧 worker（gen 已过期）会被拦截
-      try {
-        store.markMirrorCleanForGeneration(gen, now);
-      } catch (stateError) {
-        logger?.warn?.("syncMirror: markMirrorCleanForGeneration failed:", stateError);
+      // Per-type physical outcome (audit peer D): mirror.sync writes each type
+      // file independently and reports per-type success/failure. A type whose
+      // file was physically committed must be marked committed even when a
+      // sibling type errors — the old code batch-failed every type on any error,
+      // leaving committed files mislabeled as failed and masking partial state.
+      // Absent entries (a type with no memories) count as success: sync prunes
+      // the stale file, which is itself a completed physical state.
+      let allOk = true;
+      const results = mirror.sync(reconcileHumanEdits(list)) ?? {};
+      for (const type of Object.keys(TYPE_FILE)) {
+        const r = results[type];
+        const ok = !r || r.ok === true;
+        if (!ok) allOk = false;
+        try {
+          if (ok) {
+            store.setTypeStatus(type, { status: "committed", applied_gen: gen, last_error: null });
+          } else {
+            store.setTypeStatus(type, { status: "failed", last_error: r.error ?? "mirror sync failed" });
+          }
+        } catch (stateError) {
+          logger?.warn?.(`syncMirror: setTypeStatus(${type}) failed:`, stateError);
+        }
       }
-      // 逐 type 标记为 clean
-      for (const type of coveredTypes) {
+
+      // 全部 type 物理收敛：CAS/fence 绑定到本地 gen，旧 worker（gen 已过期）会被
+      // 拦截。此步失败说明核心 clean 状态没写成功，向上层报失败（不再静默）。
+      if (allOk) {
         try {
-          store.setTypeStatus(type, { dirty: false, applied_gen: gen, last_error: null });
+          store.markMirrorCleanForGeneration(gen, now);
         } catch (stateError) {
-          logger?.warn?.(`syncMirror: setTypeStatus(${type}) clean failed:`, stateError);
+          logger?.warn?.("syncMirror: markMirrorCleanForGeneration failed:", stateError);
+          return { success: false, error: stateError?.message ?? String(stateError) };
         }
+        return { success: true };
       }
+
+      // 部分 type 失败：持久 dirty（债务绑定到新轮次），下次 recover 只补未收敛
+      // 的 type。committed 的 type 已应用本轮 gen，不因兄弟失败被回滚。
+      const failedTypes = Object.entries(results)
+        .filter(([, r]) => r && r.ok === false)
+        .map(([t]) => t);
+      try {
+        store.markMirrorDirty(`mirror sync failed for: ${failedTypes.join(", ")}`, now);
+      } catch (stateError) {
+        logger?.warn?.("syncMirror: markMirrorDirty failed:", stateError);
+      }
+      return { success: false, error: `mirror sync failed for: ${failedTypes.join(", ")}` };
     } catch (error) {
       const errMsg = error?.message ?? String(error);
       logger?.warn?.("syncMirror failed:", error);
       try {
-        // 债务绑定到新的一轮（desired generation +1）
+        // 债务绑定到新的一轮（desired generation 原子递增；即便 dirty 写失败，
+        // generation 已推进，recoverMirror 仍能捕获，不产生 false-clean）。
         store.markMirrorDirty(errMsg, now);
       } catch (stateError) {
         logger?.warn?.("syncMirror: markMirrorDirty failed:", stateError);
       }
-      // 逐 type 标记为 dirty（applied_gen 不动）
+      // 逐 type 标记为 failed（applied_gen 不动）
       for (const type of coveredTypes) {
         try {
-          store.setTypeStatus(type, { dirty: true, last_error: errMsg });
+          store.setTypeStatus(type, { status: "failed", last_error: errMsg });
         } catch (stateError) {
-          logger?.warn?.(`syncMirror: setTypeStatus(${type}) dirty failed:`, stateError);
+          logger?.warn?.(`syncMirror: setTypeStatus(${type}) failed:`, stateError);
         }
       }
+      return { success: false, error: errMsg };
     }
   }
 
+  // afterSync: run syncMirror and surface a failure to the operator instead of
+  // swallowing it (peer blocker 2 + audit peer B). The mirror debt has already
+  // been persisted by markMirrorDirty inside syncMirror, so a restart recovers —
+  // but the calling write path must not report clean while the mirror is
+  // known-stale. Returns the sync result so the caller can attach an explicit
+  // degraded/pending receipt to its return value instead of faking success.
+  function afterSync(label) {
+    const r = syncMirror();
+    if (!r?.success && !r?.deferred) {
+      logger?.warn?.(`${label}: mirror sync failed (will recover on restart):`, r?.error);
+    }
+    return r;
+  }
+
   // recoverMirror: 启动/手动 reconcile 时根据持久 dirty 状态决定是否恢复同步
   // （F-NEW-03 + v0.3.6）。触发条件不只是 dirty——还检查
   // generation > applied_generation（有未应用的债务），这样 COMMIT→dirty 崩溃
@@ -718,10 +767,11 @@ export function createService({ store, mirror, config, onWrite, logger }) {
         success_at: state.success_at ?? null
       };
     } catch (error) {
-      // fail-safe：状态读取失败也不向外抛
+      // fail-safe：状态读取失败也不向外抛，但必须显式表达"未知"而非伪装成
+      // 干净（peer blocker 5：真实读取失败要显式 unknown，不得归一为 dirty:false）。
       logger?.warn?.("getMirrorHealth failed:", error);
       return {
-        dirty: false,
+        dirty: null,
         last_error: error?.message ?? String(error),
         last_attempt: null,
         success_at: null
@@ -780,7 +830,7 @@ export function createService({ store, mirror, config, onWrite, logger }) {
     getById: (id) => store.getById(id),
     remove: (id) => {
       store.remove(id);
-      syncMirror();
+      afterSync("write");
       notifyWrite();
     },
     update: (id, p, ctx = {}) => {
@@ -806,9 +856,20 @@ export function createService({ store, mirror, config, onWrite, logger }) {
           memory_id: id
         });
       }
-      syncMirror();
+      const sync = afterSync("write");
       notifyWrite();
       scheduleEmbed(updated);
+      // Audit peer B: when the mirror sync failed, the store write landed but
+      // the mirror did not converge — return an explicit degraded receipt rather
+      // than a plain success. Non-enumerable so existing deepEqual assertions on
+      // the memory shape keep passing.
+      if (!sync?.success && !sync?.deferred) {
+        Object.defineProperty(updated, "_mirror", {
+          value: { status: "degraded", error: sync?.error ?? "mirror sync failed" },
+          enumerable: false,
+          configurable: true
+        });
+      }
       return updated;
     },
     // Compare-and-set update: applies the patch only when the row still carries
@@ -835,19 +896,27 @@ export function createService({ store, mirror, config, onWrite, logger }) {
           memory_id: id
         });
       }
-      syncMirror();
+      const sync = afterSync("write");
       notifyWrite();
       scheduleEmbed(updated);
+      // Audit peer B: mirror sync failure on a CAS write must surface too.
+      if (!sync?.success && !sync?.deferred) {
+        Object.defineProperty(updated, "_mirror", {
+          value: { status: "degraded", error: sync?.error ?? "mirror sync failed" },
+          enumerable: false,
+          configurable: true
+        });
+      }
       return updated;
     },
     setForget: (id, f) => {
       const updated = store.setForget(id, f);
-      syncMirror();
+      afterSync("write");
       return updated;
     },
     setArchived: (id, f) => {
       const updated = store.setArchived(id, f);
-      syncMirror();
+      afterSync("write");
       return updated;
     },
     // autoDream audit trail: passthroughs deliberately bypass write hooks —