@modusensus/dsh-mneme 0.3.7 → 0.3.8

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;

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）。
@@ -603,37 +606,53 @@ export function createService({ store, mirror, config, onWrite, logger }) {
       // 全量渲染
       mirror.sync(reconcileHumanEdits(list));
 
-      // 成功：CAS/fence 绑定到本地 gen，旧 worker（gen 已过期）会被拦截
+      // 成功：CAS/fence 绑定到本地 gen，旧 worker（gen 已过期）会被拦截。
+      // 此步失败说明核心 clean 状态没写成功，向上层报失败（不再静默）。
       try {
         store.markMirrorCleanForGeneration(gen, now);
       } catch (stateError) {
         logger?.warn?.("syncMirror: markMirrorCleanForGeneration failed:", stateError);
+        return { success: false, error: stateError?.message ?? String(stateError) };
       }
-      // 逐 type 标记为 clean
+      // 逐 type 标记为 committed（peer blocker 4: per-type receipt）
       for (const type of coveredTypes) {
         try {
-          store.setTypeStatus(type, { dirty: false, applied_gen: gen, last_error: null });
+          store.setTypeStatus(type, { status: "committed", applied_gen: gen, last_error: null });
         } catch (stateError) {
-          logger?.warn?.(`syncMirror: setTypeStatus(${type}) clean failed:`, stateError);
+          logger?.warn?.(`syncMirror: setTypeStatus(${type}) committed failed:`, stateError);
         }
       }
+      return { success: true };
     } 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). 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.
+  function afterSync(label) {
+    const r = syncMirror();
+    if (!r?.success && !r?.deferred) {
+      logger?.warn?.(`${label}: mirror sync failed (will recover on restart):`, r?.error);
     }
   }
 
@@ -718,10 +737,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 +800,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,7 +826,7 @@ export function createService({ store, mirror, config, onWrite, logger }) {
           memory_id: id
         });
       }
-      syncMirror();
+      afterSync("write");
       notifyWrite();
       scheduleEmbed(updated);
       return updated;
@@ -835,19 +855,19 @@ export function createService({ store, mirror, config, onWrite, logger }) {
           memory_id: id
         });
       }
-      syncMirror();
+      afterSync("write");
       notifyWrite();
       scheduleEmbed(updated);
       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 —

package/lib/store.js

@@ -180,14 +180,19 @@ CREATE TABLE IF NOT EXISTS mirror_state (
   last_error TEXT,                   -- 最近失败原因
   last_attempt TEXT,                 -- 最近尝试时间（ISO）
   success_at TEXT,                   -- 最近成功时间（ISO）
-  generation INTEGER NOT NULL DEFAULT 0,         -- 期望的同步轮次（desired）
-  applied_generation INTEGER NOT NULL DEFAULT 0, -- 已成功应用的轮次
+  generation INTEGER NOT NULL DEFAULT 0 CHECK (generation >= 0 AND generation <= 9007199254740991),         -- 期望的同步轮次（desired）
+  applied_generation INTEGER NOT NULL DEFAULT 0 CHECK (applied_generation >= 0 AND applied_generation <= 9007199254740991), -- 已成功应用的轮次
   type_status TEXT                               -- JSON: 逐 type 状态 {type: {dirty, applied_gen, last_error}}
 );
 `;
 
 const TYPES = new Set(["preference", "project", "decision", "history", "summary"]);
 
+// Per-type mirror sync receipts (peer blocker 4): a type is either committed
+// (file written + fence applied), failed (last sync round errored for it), or
+// pending (still owed a write).
+const VALID_TYPE_STATUS = new Set(["committed", "failed", "pending"]);
+
 // Pure helpers: no shared module state.
 
 function sanitizePage(limit, offset, defaultLimit) {
@@ -387,6 +392,10 @@ function parseJsonArray(raw) {
 export function createStore(path) {
   const db = new DatabaseSync(path);
   db.exec("PRAGMA journal_mode = WAL;");
+  // Concurrent writers (peer probe: 8 independent processes) must wait for the
+  // write lock instead of failing immediately with SQLITE_BUSY — otherwise the
+  // atomic generation increment loses whole writes, not just increments.
+  db.exec("PRAGMA busy_timeout = 5000;");
   db.exec(SCHEMA);
 
   // Schema migrations for legacy databases (idempotent).
@@ -467,10 +476,17 @@ export function createStore(path) {
     const embedding = Array.isArray(memory.embedding) && memory.embedding.length
       ? JSON.stringify(memory.embedding)
       : null;
-    db.prepare(
-      `INSERT INTO memories (id, type, title, content, tags, importance, forgotten, source, embedding, created_at, updated_at)
-       VALUES (?, ?, ?, ?, ?, ?, 0, ?, ?, ?, ?)`
-    ).run(id, type, memory.title, memory.content, tags, importance, memory.source ?? null, embedding, now, now);
+    runAtomically(() => {
+      db.prepare(
+        `INSERT INTO memories (id, type, title, content, tags, importance, forgotten, source, embedding, created_at, updated_at)
+         VALUES (?, ?, ?, ?, ?, ?, 0, ?, ?, ?, ?)`
+      ).run(id, type, memory.title, memory.content, tags, importance, memory.source ?? null, embedding, now, now);
+      // desired generation bumped in the same transaction as the write: once
+      // this commits, generation > applied_generation, so a crash right after
+      // (before syncMirror) is caught by recoverMirror on restart (peer
+      // blocker 1). ROLLBACK on error rolls this back with the write.
+      incrementGeneration();
+    });
     return getById(id);
   }
 
@@ -486,24 +502,34 @@ export function createStore(path) {
     const embedding = patch.embedding !== undefined
       ? (Array.isArray(patch.embedding) && patch.embedding.length ? JSON.stringify(patch.embedding) : null)
       : existing.embedding ?? null;
-    db.prepare(
-      `UPDATE memories SET type=?, title=?, content=?, tags=?, importance=?, source=?, embedding=?, updated_at=? WHERE id=?`
-    ).run(
-      type,
-      patch.title ?? existing.title,
-      patch.content ?? existing.content,
-      JSON.stringify(patch.tags ?? existing.tags),
-      Number.isInteger(patch.importance) ? patch.importance : existing.importance,
-      patch.source !== undefined ? patch.source : (existing.source ?? null),
-      embedding,
-      now,
-      id
-    );
+    runAtomically(() => {
+      db.prepare(
+        `UPDATE memories SET type=?, title=?, content=?, tags=?, importance=?, source=?, embedding=?, updated_at=? WHERE id=?`
+      ).run(
+        type,
+        patch.title ?? existing.title,
+        patch.content ?? existing.content,
+        JSON.stringify(patch.tags ?? existing.tags),
+        Number.isInteger(patch.importance) ? patch.importance : existing.importance,
+        patch.source !== undefined ? patch.source : (existing.source ?? null),
+        embedding,
+        now,
+        id
+      );
+      // Desired generation bumped in the same transaction as the update (peer
+      // blocker 1: crash between write and sync must still be recoverable).
+      incrementGeneration();
+    });
     return getById(id);
   }
 
   function remove(id) {
-    db.prepare("DELETE FROM memories WHERE id = ?").run(id);
+    runAtomically(() => {
+      db.prepare("DELETE FROM memories WHERE id = ?").run(id);
+      // Mirror sync must reflect the deletion; bump desired generation so a
+      // crash between the delete and syncMirror leaves a recoverable debt.
+      incrementGeneration();
+    });
   }
 
   /**
@@ -542,18 +568,26 @@ export function createStore(path) {
       expectedUpdatedAt
     );
     if (result.changes === 0) return undefined; // CAS miss: a concurrent write won
+    // Only bump desired generation on a successful CAS — a miss writes nothing.
+    runAtomically(() => { incrementGeneration(); });
     return getById(id);
   }
 
   function setForget(id, forgotten) {
-    db.prepare("UPDATE memories SET forgotten = ?, updated_at = ? WHERE id = ?")
-      .run(forgotten === true || forgotten === 1 ? 1 : 0, nowIso(), id);
+    runAtomically(() => {
+      db.prepare("UPDATE memories SET forgotten = ?, updated_at = ? WHERE id = ?")
+        .run(forgotten === true || forgotten === 1 ? 1 : 0, nowIso(), id);
+      incrementGeneration();
+    });
     return getById(id);
   }
 
   function setArchived(id, archived) {
-    db.prepare("UPDATE memories SET archived = ?, updated_at = ? WHERE id = ?")
-      .run(archived ? 1 : 0, nowIso(), id);
+    runAtomically(() => {
+      db.prepare("UPDATE memories SET archived = ?, updated_at = ? WHERE id = ?")
+        .run(archived ? 1 : 0, nowIso(), id);
+      incrementGeneration();
+    });
     return getById(id);
   }
 
@@ -1189,7 +1223,10 @@ export function createStore(path) {
       if (key === "dirty") {
         value = value ? 1 : 0;
       } else if (key === "generation" || key === "applied_generation") {
-        value = Math.trunc(Number(value)) || 0;
+        value = Math.trunc(Number(value));
+        if (!Number.isFinite(value) || value < 0 || value > Number.MAX_SAFE_INTEGER) {
+          throw new RangeError(`mirror_state.${key} out of range: ${value}`);
+        }
       } else if (key === "type_status" && value != null && typeof value !== "string") {
         value = JSON.stringify(value);
       }
@@ -1220,12 +1257,15 @@ export function createStore(path) {
    * recent as this one may.
    */
   function markMirrorDirty(error, now) {
-    const current = getMirrorState();
+    // Bump the desired generation atomically first — the new debt must be bound
+    // to a fresh round so a stale worker cannot fence-clean it. Even if this
+    // write fails (peer blocker 2), generation still advanced, so recoverMirror
+    // sees generation > applied_generation and retries rather than false-clean.
+    incrementGeneration();
     return setMirrorState({
       dirty: 1,
       last_error: error,
-      last_attempt: now ?? nowIso(),
-      generation: (current.generation || 0) + 1
+      last_attempt: now ?? nowIso()
     });
   }
 
@@ -1262,13 +1302,23 @@ export function createStore(path) {
 
   /**
    * Record per-type mirror status (partial success bookkeeping). `status` is a
-   * partial patch {dirty?, applied_gen?, last_error?} merged into the existing
-   * entry for `type` (other types untouched). Returns the updated full state.
+   * patch {status: 'committed'|'failed'|'pending', applied_gen?, last_error?}
+   * replacing the entry for `type` (other types untouched). Standardizing on an
+   * explicit status gives per-type committed/failed/pending receipts — a type
+   * whose file was written while a sibling failed is recorded as such, not
+   * collapsed into a bulk "dirty" (peer blocker 4). Returns the updated state.
    */
   function setTypeStatus(type, status) {
+    if (!VALID_TYPE_STATUS.has(status?.status)) {
+      throw new TypeError(`setTypeStatus: status must be one of committed|failed|pending, got ${status?.status}`);
+    }
     const current = getMirrorState();
     const statuses = current.type_status || {};
-    statuses[type] = { ...(statuses[type] || {}), ...status };
+    statuses[type] = {
+      status: status.status,
+      ...(status.applied_gen !== undefined ? { applied_gen: status.applied_gen } : {}),
+      ...(status.last_error !== undefined ? { last_error: status.last_error } : {})
+    };
     return setMirrorState({ type_status: JSON.stringify(statuses) });
   }
 
@@ -1278,10 +1328,40 @@ export function createStore(path) {
     return current.type_status || {};
   }
 
-  /** Bump the desired generation (new sync round), returning the new state. */
+  /** Run fn atomically: when the connection is already inside a transaction
+   *  (service.transaction's BEGIN), just run it — the outer COMMIT covers us.
+   *  Otherwise wrap in BEGIN/COMMIT so a memory write and its desired-generation
+   *  bump commit together: a crash between them can never leave a mutated store
+   *  with generation == applied (audit peer blocker 1, "crash window"). */
+  function runAtomically(fn) {
+    if (db.isTransaction) return fn();
+    db.exec("BEGIN");
+    try {
+      const result = fn();
+      db.exec("COMMIT");
+      return result;
+    } catch (error) {
+      try { db.exec("ROLLBACK"); } catch { /* connection may be closed */ }
+      throw error;
+    }
+  }
+
+  /** Bump the desired generation atomically (SQLite single-statement increment,
+   *  no SELECT-then-UPSERT race: peer blocker 3 lost 10 of 91 concurrent
+   *  increments under an 8-process probe). Returns the new mirror state.
+   *  Guards the upper bound: generation must stay within MAX_SAFE_INTEGER so
+   *  reads never hit ERR_OUT_OF_RANGE (peer blocker 6). */
   function incrementGeneration() {
-    const current = getMirrorState();
-    return setMirrorState({ generation: (current.generation || 0) + 1 });
+    return runAtomically(() => {
+      // Ensure the singleton row exists before incrementing (UPDATE alone would
+      // match nothing on a fresh DB).
+      db.prepare("INSERT OR IGNORE INTO mirror_state (id) VALUES ('main')").run();
+      const row = db.prepare(
+        "UPDATE mirror_state SET generation = generation + 1 WHERE id = 'main' AND generation < ? RETURNING generation"
+      ).get(Number.MAX_SAFE_INTEGER);
+      if (!row) throw new RangeError("mirror_state.generation exceeded MAX_SAFE_INTEGER");
+      return getMirrorState();
+    });
   }
 
   return {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@modusensus/dsh-mneme",
   "description": "Cross-session memory plugin for DeepSeek Harness with autoDream consolidation: SQLite store, Markdown mirrors, 6 model tools, automatic injection, session summarization, user profile/rules, custom slash commands, vector (semantic) search, and a Web GUI panel",
-  "version": "0.3.7",
+  "version": "0.3.8",
   "license": "MIT",
   "type": "module",
   "main": "lib/index.js",

package/src/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;

package/src/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）。
@@ -603,37 +606,53 @@ export function createService({ store, mirror, config, onWrite, logger }) {
       // 全量渲染
       mirror.sync(reconcileHumanEdits(list));
 
-      // 成功：CAS/fence 绑定到本地 gen，旧 worker（gen 已过期）会被拦截
+      // 成功：CAS/fence 绑定到本地 gen，旧 worker（gen 已过期）会被拦截。
+      // 此步失败说明核心 clean 状态没写成功，向上层报失败（不再静默）。
       try {
         store.markMirrorCleanForGeneration(gen, now);
       } catch (stateError) {
         logger?.warn?.("syncMirror: markMirrorCleanForGeneration failed:", stateError);
+        return { success: false, error: stateError?.message ?? String(stateError) };
       }
-      // 逐 type 标记为 clean
+      // 逐 type 标记为 committed（peer blocker 4: per-type receipt）
       for (const type of coveredTypes) {
         try {
-          store.setTypeStatus(type, { dirty: false, applied_gen: gen, last_error: null });
+          store.setTypeStatus(type, { status: "committed", applied_gen: gen, last_error: null });
         } catch (stateError) {
-          logger?.warn?.(`syncMirror: setTypeStatus(${type}) clean failed:`, stateError);
+          logger?.warn?.(`syncMirror: setTypeStatus(${type}) committed failed:`, stateError);
         }
       }
+      return { success: true };
     } 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). 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.
+  function afterSync(label) {
+    const r = syncMirror();
+    if (!r?.success && !r?.deferred) {
+      logger?.warn?.(`${label}: mirror sync failed (will recover on restart):`, r?.error);
     }
   }
 
@@ -718,10 +737,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 +800,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,7 +826,7 @@ export function createService({ store, mirror, config, onWrite, logger }) {
           memory_id: id
         });
       }
-      syncMirror();
+      afterSync("write");
       notifyWrite();
       scheduleEmbed(updated);
       return updated;
@@ -835,19 +855,19 @@ export function createService({ store, mirror, config, onWrite, logger }) {
           memory_id: id
         });
       }
-      syncMirror();
+      afterSync("write");
       notifyWrite();
       scheduleEmbed(updated);
       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 —

package/src/store.js

@@ -180,14 +180,19 @@ CREATE TABLE IF NOT EXISTS mirror_state (
   last_error TEXT,                   -- 最近失败原因
   last_attempt TEXT,                 -- 最近尝试时间（ISO）
   success_at TEXT,                   -- 最近成功时间（ISO）
-  generation INTEGER NOT NULL DEFAULT 0,         -- 期望的同步轮次（desired）
-  applied_generation INTEGER NOT NULL DEFAULT 0, -- 已成功应用的轮次
+  generation INTEGER NOT NULL DEFAULT 0 CHECK (generation >= 0 AND generation <= 9007199254740991),         -- 期望的同步轮次（desired）
+  applied_generation INTEGER NOT NULL DEFAULT 0 CHECK (applied_generation >= 0 AND applied_generation <= 9007199254740991), -- 已成功应用的轮次
   type_status TEXT                               -- JSON: 逐 type 状态 {type: {dirty, applied_gen, last_error}}
 );
 `;
 
 const TYPES = new Set(["preference", "project", "decision", "history", "summary"]);
 
+// Per-type mirror sync receipts (peer blocker 4): a type is either committed
+// (file written + fence applied), failed (last sync round errored for it), or
+// pending (still owed a write).
+const VALID_TYPE_STATUS = new Set(["committed", "failed", "pending"]);
+
 // Pure helpers: no shared module state.
 
 function sanitizePage(limit, offset, defaultLimit) {
@@ -387,6 +392,10 @@ function parseJsonArray(raw) {
 export function createStore(path) {
   const db = new DatabaseSync(path);
   db.exec("PRAGMA journal_mode = WAL;");
+  // Concurrent writers (peer probe: 8 independent processes) must wait for the
+  // write lock instead of failing immediately with SQLITE_BUSY — otherwise the
+  // atomic generation increment loses whole writes, not just increments.
+  db.exec("PRAGMA busy_timeout = 5000;");
   db.exec(SCHEMA);
 
   // Schema migrations for legacy databases (idempotent).
@@ -467,10 +476,17 @@ export function createStore(path) {
     const embedding = Array.isArray(memory.embedding) && memory.embedding.length
       ? JSON.stringify(memory.embedding)
       : null;
-    db.prepare(
-      `INSERT INTO memories (id, type, title, content, tags, importance, forgotten, source, embedding, created_at, updated_at)
-       VALUES (?, ?, ?, ?, ?, ?, 0, ?, ?, ?, ?)`
-    ).run(id, type, memory.title, memory.content, tags, importance, memory.source ?? null, embedding, now, now);
+    runAtomically(() => {
+      db.prepare(
+        `INSERT INTO memories (id, type, title, content, tags, importance, forgotten, source, embedding, created_at, updated_at)
+         VALUES (?, ?, ?, ?, ?, ?, 0, ?, ?, ?, ?)`
+      ).run(id, type, memory.title, memory.content, tags, importance, memory.source ?? null, embedding, now, now);
+      // desired generation bumped in the same transaction as the write: once
+      // this commits, generation > applied_generation, so a crash right after
+      // (before syncMirror) is caught by recoverMirror on restart (peer
+      // blocker 1). ROLLBACK on error rolls this back with the write.
+      incrementGeneration();
+    });
     return getById(id);
   }
 
@@ -486,24 +502,34 @@ export function createStore(path) {
     const embedding = patch.embedding !== undefined
       ? (Array.isArray(patch.embedding) && patch.embedding.length ? JSON.stringify(patch.embedding) : null)
       : existing.embedding ?? null;
-    db.prepare(
-      `UPDATE memories SET type=?, title=?, content=?, tags=?, importance=?, source=?, embedding=?, updated_at=? WHERE id=?`
-    ).run(
-      type,
-      patch.title ?? existing.title,
-      patch.content ?? existing.content,
-      JSON.stringify(patch.tags ?? existing.tags),
-      Number.isInteger(patch.importance) ? patch.importance : existing.importance,
-      patch.source !== undefined ? patch.source : (existing.source ?? null),
-      embedding,
-      now,
-      id
-    );
+    runAtomically(() => {
+      db.prepare(
+        `UPDATE memories SET type=?, title=?, content=?, tags=?, importance=?, source=?, embedding=?, updated_at=? WHERE id=?`
+      ).run(
+        type,
+        patch.title ?? existing.title,
+        patch.content ?? existing.content,
+        JSON.stringify(patch.tags ?? existing.tags),
+        Number.isInteger(patch.importance) ? patch.importance : existing.importance,
+        patch.source !== undefined ? patch.source : (existing.source ?? null),
+        embedding,
+        now,
+        id
+      );
+      // Desired generation bumped in the same transaction as the update (peer
+      // blocker 1: crash between write and sync must still be recoverable).
+      incrementGeneration();
+    });
     return getById(id);
   }
 
   function remove(id) {
-    db.prepare("DELETE FROM memories WHERE id = ?").run(id);
+    runAtomically(() => {
+      db.prepare("DELETE FROM memories WHERE id = ?").run(id);
+      // Mirror sync must reflect the deletion; bump desired generation so a
+      // crash between the delete and syncMirror leaves a recoverable debt.
+      incrementGeneration();
+    });
   }
 
   /**
@@ -542,18 +568,26 @@ export function createStore(path) {
       expectedUpdatedAt
     );
     if (result.changes === 0) return undefined; // CAS miss: a concurrent write won
+    // Only bump desired generation on a successful CAS — a miss writes nothing.
+    runAtomically(() => { incrementGeneration(); });
     return getById(id);
   }
 
   function setForget(id, forgotten) {
-    db.prepare("UPDATE memories SET forgotten = ?, updated_at = ? WHERE id = ?")
-      .run(forgotten === true || forgotten === 1 ? 1 : 0, nowIso(), id);
+    runAtomically(() => {
+      db.prepare("UPDATE memories SET forgotten = ?, updated_at = ? WHERE id = ?")
+        .run(forgotten === true || forgotten === 1 ? 1 : 0, nowIso(), id);
+      incrementGeneration();
+    });
     return getById(id);
   }
 
   function setArchived(id, archived) {
-    db.prepare("UPDATE memories SET archived = ?, updated_at = ? WHERE id = ?")
-      .run(archived ? 1 : 0, nowIso(), id);
+    runAtomically(() => {
+      db.prepare("UPDATE memories SET archived = ?, updated_at = ? WHERE id = ?")
+        .run(archived ? 1 : 0, nowIso(), id);
+      incrementGeneration();
+    });
     return getById(id);
   }
 
@@ -1189,7 +1223,10 @@ export function createStore(path) {
       if (key === "dirty") {
         value = value ? 1 : 0;
       } else if (key === "generation" || key === "applied_generation") {
-        value = Math.trunc(Number(value)) || 0;
+        value = Math.trunc(Number(value));
+        if (!Number.isFinite(value) || value < 0 || value > Number.MAX_SAFE_INTEGER) {
+          throw new RangeError(`mirror_state.${key} out of range: ${value}`);
+        }
       } else if (key === "type_status" && value != null && typeof value !== "string") {
         value = JSON.stringify(value);
       }
@@ -1220,12 +1257,15 @@ export function createStore(path) {
    * recent as this one may.
    */
   function markMirrorDirty(error, now) {
-    const current = getMirrorState();
+    // Bump the desired generation atomically first — the new debt must be bound
+    // to a fresh round so a stale worker cannot fence-clean it. Even if this
+    // write fails (peer blocker 2), generation still advanced, so recoverMirror
+    // sees generation > applied_generation and retries rather than false-clean.
+    incrementGeneration();
     return setMirrorState({
       dirty: 1,
       last_error: error,
-      last_attempt: now ?? nowIso(),
-      generation: (current.generation || 0) + 1
+      last_attempt: now ?? nowIso()
     });
   }
 
@@ -1262,13 +1302,23 @@ export function createStore(path) {
 
   /**
    * Record per-type mirror status (partial success bookkeeping). `status` is a
-   * partial patch {dirty?, applied_gen?, last_error?} merged into the existing
-   * entry for `type` (other types untouched). Returns the updated full state.
+   * patch {status: 'committed'|'failed'|'pending', applied_gen?, last_error?}
+   * replacing the entry for `type` (other types untouched). Standardizing on an
+   * explicit status gives per-type committed/failed/pending receipts — a type
+   * whose file was written while a sibling failed is recorded as such, not
+   * collapsed into a bulk "dirty" (peer blocker 4). Returns the updated state.
    */
   function setTypeStatus(type, status) {
+    if (!VALID_TYPE_STATUS.has(status?.status)) {
+      throw new TypeError(`setTypeStatus: status must be one of committed|failed|pending, got ${status?.status}`);
+    }
     const current = getMirrorState();
     const statuses = current.type_status || {};
-    statuses[type] = { ...(statuses[type] || {}), ...status };
+    statuses[type] = {
+      status: status.status,
+      ...(status.applied_gen !== undefined ? { applied_gen: status.applied_gen } : {}),
+      ...(status.last_error !== undefined ? { last_error: status.last_error } : {})
+    };
     return setMirrorState({ type_status: JSON.stringify(statuses) });
   }
 
@@ -1278,10 +1328,40 @@ export function createStore(path) {
     return current.type_status || {};
   }
 
-  /** Bump the desired generation (new sync round), returning the new state. */
+  /** Run fn atomically: when the connection is already inside a transaction
+   *  (service.transaction's BEGIN), just run it — the outer COMMIT covers us.
+   *  Otherwise wrap in BEGIN/COMMIT so a memory write and its desired-generation
+   *  bump commit together: a crash between them can never leave a mutated store
+   *  with generation == applied (audit peer blocker 1, "crash window"). */
+  function runAtomically(fn) {
+    if (db.isTransaction) return fn();
+    db.exec("BEGIN");
+    try {
+      const result = fn();
+      db.exec("COMMIT");
+      return result;
+    } catch (error) {
+      try { db.exec("ROLLBACK"); } catch { /* connection may be closed */ }
+      throw error;
+    }
+  }
+
+  /** Bump the desired generation atomically (SQLite single-statement increment,
+   *  no SELECT-then-UPSERT race: peer blocker 3 lost 10 of 91 concurrent
+   *  increments under an 8-process probe). Returns the new mirror state.
+   *  Guards the upper bound: generation must stay within MAX_SAFE_INTEGER so
+   *  reads never hit ERR_OUT_OF_RANGE (peer blocker 6). */
   function incrementGeneration() {
-    const current = getMirrorState();
-    return setMirrorState({ generation: (current.generation || 0) + 1 });
+    return runAtomically(() => {
+      // Ensure the singleton row exists before incrementing (UPDATE alone would
+      // match nothing on a fresh DB).
+      db.prepare("INSERT OR IGNORE INTO mirror_state (id) VALUES ('main')").run();
+      const row = db.prepare(
+        "UPDATE mirror_state SET generation = generation + 1 WHERE id = 'main' AND generation < ? RETURNING generation"
+      ).get(Number.MAX_SAFE_INTEGER);
+      if (!row) throw new RangeError("mirror_state.generation exceeded MAX_SAFE_INTEGER");
+      return getMirrorState();
+    });
   }
 
   return {

package/test/mirror-generation.test.js

@@ -141,30 +141,33 @@ test("V0.3.6-C3: incrementGeneration 每次 +1，不动 dirty/applied", () => {
 
 // ── D. 逐 type 部分成功（store 层 setTypeStatus）──────────────────────────
 
-test("V0.3.6-D1: setTypeStatus 按 type 合并，partial patch 保留未传字段", () => {
+test("V0.3.6-D1: setTypeStatus 记录逐 type committed/failed/pending 回执（peer blocker 4）", () => {
   const { dir, store } = setup();
   try {
-    const s1 = store.setTypeStatus("project", { dirty: true, last_error: "e1" });
-    assert.equal(s1.type_status.project.dirty, true);
+    // 状态必填且必须合法
+    assert.throws(() => store.setTypeStatus("project", { applied_gen: 1 }), /status must be one of/, "缺 status 必须抛错");
+    assert.throws(() => store.setTypeStatus("project", { status: "bogus" }), /status must be one of/, "非法 status 必须抛错");
+
+    const s1 = store.setTypeStatus("project", { status: "failed", last_error: "e1" });
+    assert.equal(s1.type_status.project.status, "failed");
     assert.equal(s1.type_status.project.last_error, "e1");
 
-    const s2 = store.setTypeStatus("project", { applied_gen: 7 });
-    assert.equal(s2.type_status.project.applied_gen, 7, "partial 合并到同 type");
-    assert.equal(s2.type_status.project.dirty, true, "未传字段保留");
-    assert.equal(s2.type_status.project.last_error, "e1", "未传字段保留");
+    const s2 = store.setTypeStatus("project", { status: "committed", applied_gen: 7, last_error: null });
+    assert.equal(s2.type_status.project.status, "committed", "同 type 状态更新");
+    assert.equal(s2.type_status.project.applied_gen, 7);
 
-    const s3 = store.setTypeStatus("decision", { dirty: false, applied_gen: 7 });
-    assert.equal(s3.type_status.decision.applied_gen, 7, "另一 type 独立");
-    assert.equal(s3.type_status.project.dirty, true, "同 type 不受影响");
+    const s3 = store.setTypeStatus("decision", { status: "pending" });
+    assert.equal(s3.type_status.decision.status, "pending", "另一 type 独立");
+    assert.equal(s3.type_status.project.status, "committed", "同 type 不受影响");
 
     // getTypeStatus 返回同一解析后的 map
     assert.deepEqual(store.getTypeStatus(), {
-      project: { dirty: true, last_error: "e1", applied_gen: 7 },
-      decision: { dirty: false, applied_gen: 7 }
+      project: { status: "committed", applied_gen: 7, last_error: null },
+      decision: { status: "pending" }
     });
     // type_status 持久化为 JSON 文本
     const row = store.db.prepare("SELECT type_status FROM mirror_state WHERE id='main'").get();
-    assert.ok(JSON.parse(row.type_status).project.applied_gen === 7, "type_status 必须以 JSON 落库");
+    assert.ok(JSON.parse(row.type_status).project.status === "committed", "type_status 必须以 JSON 落库");
   } finally {
     store.close();
     rmSync(dir, { recursive: true, force: true });
@@ -253,7 +256,7 @@ test("V0.3.6-B1: markMirrorDirty 自身写失败——syncMirror 不抛、genera
 
 // ── D. 逐 type 部分成功（service 层 type_status 生命周期）─────────────────
 
-test("V0.3.6-D2: syncMirror 成功时逐 type 记录 clean（applied_gen=gen）", () => {
+test("V0.3.6-D2: syncMirror 成功时逐 type 记录 committed（applied_gen=gen）", () => {
   const { dir, store, mirror, service } = setup();
   try {
     const mock = makeSyncMock();
@@ -261,7 +264,7 @@ test("V0.3.6-D2: syncMirror 成功时逐 type 记录 clean（applied_gen=gen）"
     service.saveWithDedupe({ type: "project", title: "P", content: "x", importance: 3 });
     const ts = store.getTypeStatus();
     assert.ok(ts.project, "覆盖的 type 必须记录 type_status");
-    assert.equal(ts.project.dirty, false);
+    assert.equal(ts.project.status, "committed");
     assert.equal(ts.project.last_error, null);
     assert.equal(ts.project.applied_gen, store.getMirrorState().applied_generation,
       "type_status.applied_gen 与全局 applied 一致");
@@ -271,15 +274,15 @@ test("V0.3.6-D2: syncMirror 成功时逐 type 记录 clean（applied_gen=gen）"
   }
 });
 
-test("V0.3.6-D3: syncMirror 失败时逐 type 记录 dirty，recoverMirror 后追到最新 applied", () => {
+test("V0.3.6-D3: syncMirror 失败时逐 type 记录 failed，recoverMirror 后追到最新 applied", () => {
   const { dir, store, mirror, service } = setup();
   try {
     const mock = makeSyncMock();
     mirror.sync = mock.sync;
-    // 第一次成功建立 clean type_status
+    // 第一次成功建立 committed type_status
     mock.mode = "ok";
     service.saveWithDedupe({ type: "project", title: "P", content: "x", importance: 3 });
-    assert.equal(store.getTypeStatus().project.dirty, false);
+    assert.equal(store.getTypeStatus().project.status, "committed");
 
     // 模拟一次"债务轮次"：incrementGeneration 但未成功 applied（崩溃在 type_status 层面）
     store.incrementGeneration();
@@ -293,7 +296,7 @@ test("V0.3.6-D3: syncMirror 失败时逐 type 记录 dirty，recoverMirror 后
     const ts = store.getTypeStatus();
     assert.equal(ts.project.applied_gen, finalState.applied_generation,
       "type_status 必须追到最新 applied（部分成功债务表达并收敛）");
-    assert.equal(ts.project.dirty, false);
+    assert.equal(ts.project.status, "committed");
   } finally {
     store.close();
     rmSync(dir, { recursive: true, force: true });
@@ -454,8 +457,8 @@ test("V0.3.6-F1: 旧库（v0.3.5 5 列）打开自动 ALTER 加 3 列，不丢
     // 新方法在迁移后的库上正常工作
     const clean = store.markMirrorCleanForGeneration(0, "t");
     assert.equal(clean.dirty, false, "迁移库上 fence clean 正常工作");
-    store.setTypeStatus("project", { dirty: true, applied_gen: 0 });
-    assert.equal(store.getTypeStatus().project.dirty, true, "迁移库上 setTypeStatus 正常工作");
+    store.setTypeStatus("project", { status: "failed", applied_gen: 0 });
+    assert.equal(store.getTypeStatus().project.status, "failed", "迁移库上 setTypeStatus 正常工作");
     store.close();
   } finally {
     rmSync(dir, { recursive: true, force: true });

package/test/peer-blockers.test.js

@@ -0,0 +1,148 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { createStore } from "../src/store.js";
+import { createMirror } from "../src/mirror.js";
+import { createService } from "../src/service.js";
+
+const execFileP = promisify(execFile);
+const STORE_PATH = fileURLToPath(new URL("../src/store.js", import.meta.url));
+
+/**
+ * v0.3.8 回归测试（audit peer 6 项运行时阻断 → INSTALLATION_NOT_APPROVED）。
+ *
+ * 测试点：
+ *  A. 崩溃窗口（真实语义）：store.save 在业务事务内原子递增 desired generation，
+ *     崩溃在 COMMIT 后、syncMirror 前 → 重启 recoverMirror 仅凭
+ *     generation > applied_generation 捕获并收敛（peer blocker 1）
+ *  B. 业务写同事务原子性：INSERT 失败回滚时 generation 不得递增（peer blocker 1/3）
+ *  C. 多进程并发原子递增：8 进程 × 10 次不丢增量（peer blocker 3）
+ *  D. generation 上界/负数拒绝（peer blocker 6）
+ */
+
+function setup(dbPath) {
+  const dir = mkdtempSync(join(tmpdir(), "dsh-mneme-peer-"));
+  const mirrorDir = join(dir, "mirror");
+  const store = createStore(dbPath ?? ":memory:");
+  const mirror = createMirror(mirrorDir);
+  const warns = [];
+  const logger = { warn: (...a) => warns.push(a.join(" ")) };
+  const service = createService({ store, mirror, config: {}, logger });
+  return { dir, mirrorDir, store, mirror, service, warns };
+}
+
+test("peer-A: 崩溃窗口——save 后（generation 已递增）不 sync 直接关闭重开，recoverMirror 捕获并收敛", () => {
+  const dir = mkdtempSync(join(tmpdir(), "dsh-mneme-peer-"));
+  const dbPath = join(dir, "mneme.db");
+  const mirrorDir = join(dir, "mirror");
+  try {
+    const store = createStore(dbPath);
+    const mirror = createMirror(mirrorDir);
+    const service = createService({ store, mirror, config: {}, logger: { warn() {} } });
+    try {
+      // 业务写：store.save 在事务内递增 desired generation，但不触发 mirror 渲染
+      store.save({ type: "project", title: "P", content: "x", importance: 3 });
+      const afterSave = store.getMirrorState();
+      assert.ok(afterSave.generation > afterSave.applied_generation,
+        "save 后 generation > applied（COMMIT 完成，mirror 未同步=崩溃窗口）");
+    } finally {
+      // 模拟崩溃：不调 syncMirror，直接关库
+      store.close();
+    }
+
+    // 重启：重新打开同一 DB，recoverMirror 必须捕获债务并收敛
+    const store2 = createStore(dbPath);
+    const mirror2 = createMirror(mirrorDir);
+    const service2 = createService({ store: store2, mirror: mirror2, config: {}, logger: { warn() {} } });
+    try {
+      const result = service2.recoverMirror();
+      assert.equal(result.recovered, true, "崩溃窗口必须被 recover 捕获");
+      assert.equal(result.error, null);
+      const state = store2.getMirrorState();
+      assert.equal(state.dirty, false, "收敛后 dirty 清");
+      assert.ok(state.generation <= state.applied_generation, "收敛后无未应用债务");
+    } finally {
+      store2.close();
+    }
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("peer-B: 业务写同事务原子性——INSERT 失败回滚时 generation 不得递增", () => {
+  const { dir, store } = setup();
+  try {
+    store.save({ id: "dup", type: "project", title: "A", content: "x", importance: 3 });
+    const before = store.getMirrorState().generation;
+    assert.throws(
+      () => store.save({ id: "dup", type: "project", title: "B", content: "y", importance: 3 }),
+      /UNIQUE|constraint/i,
+      "重复主键 INSERT 必须抛错"
+    );
+    assert.equal(store.getMirrorState().generation, before,
+      "回滚后 generation 不递增（写与 desired generation 同事务，失败一起回滚）");
+  } finally {
+    store.close();
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("peer-C: 多进程并发原子递增——8 进程×10 次 incrementGeneration 不丢增量", async () => {
+  const dir = mkdtempSync(join(tmpdir(), "dsh-mneme-peer-"));
+  const dbPath = join(dir, "concurrent.db");
+  const N = 8;
+  const M = 10;
+  try {
+    // 子进程脚本：打开同一 DB 文件，原子递增 M 次
+    const worker = `
+      const { createStore } = require(process.argv[1]);
+      const store = createStore(process.argv[2]);
+      for (let i = 0; i < ${M}; i++) { store.incrementGeneration(); }
+      store.close();
+    `;
+    await Promise.all(
+      Array.from({ length: N }, () =>
+        execFileP(process.execPath, ["-e", worker, STORE_PATH, dbPath], { timeout: 30000 })
+      )
+    );
+    const store = createStore(dbPath);
+    try {
+      const state = store.getMirrorState();
+      assert.equal(state.generation, N * M,
+        `并发 ${N} 进程 × ${M} 次必须无丢失增量，得到 ${state.generation}`);
+    } finally {
+      store.close();
+    }
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("peer-D: generation 上界与负数拒绝", () => {
+  const { dir, store } = setup();
+  try {
+    // 负数拒绝
+    assert.throws(() => store.setMirrorState({ generation: -1 }), RangeError, "负数必须拒绝");
+    assert.throws(() => store.setMirrorState({ applied_generation: -5 }), RangeError, "负数 applied 必须拒绝");
+    // 超 MAX_SAFE_INTEGER 拒绝
+    assert.throws(
+      () => store.setMirrorState({ generation: Number.MAX_SAFE_INTEGER + 1 }),
+      RangeError,
+      "超出 MAX_SAFE_INTEGER 必须拒绝"
+    );
+    // 到上界后再 increment 必须抛错（读回不会 ERR_OUT_OF_RANGE）
+    store.setMirrorState({ generation: Number.MAX_SAFE_INTEGER });
+    assert.throws(() => store.incrementGeneration(), /exceeded MAX_SAFE_INTEGER/, "上界后再递增必须抛错");
+    // 正常递增仍工作
+    store.setMirrorState({ generation: 5 });
+    assert.equal(store.incrementGeneration().generation, 6, "正常递增不受影响");
+  } finally {
+    store.close();
+    rmSync(dir, { recursive: true, force: true });
+  }
+});