@modusensus/dsh-mneme 0.3.7 → 0.3.9

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 AND generation = CAST(generation AS INTEGER)),         -- 期望的同步轮次（desired）
+  applied_generation INTEGER NOT NULL DEFAULT 0 CHECK (applied_generation >= 0 AND applied_generation <= 9007199254740991 AND applied_generation = CAST(applied_generation AS INTEGER)), -- 已成功应用的轮次
   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) {
@@ -386,6 +391,13 @@ function parseJsonArray(raw) {
 
 export function createStore(path) {
   const db = new DatabaseSync(path);
+  // Set busy_timeout BEFORE the journal-mode switch (audit peer: 8-process WAL
+  // init). Switching a fresh DB to WAL takes an exclusive lock; when several
+  // processes open the same path simultaneously, that lock can fail with
+  // SQLITE_BUSY before the timeout is armed. With the timeout installed first,
+  // the WAL transition (and every later write) blocks and retries instead of
+  // failing outright, so concurrent init converges to a stable 447/447.
+  db.exec("PRAGMA busy_timeout = 5000;");
   db.exec("PRAGMA journal_mode = WAL;");
   db.exec(SCHEMA);
 
@@ -417,6 +429,24 @@ export function createStore(path) {
     db.exec("ALTER TABLE mirror_state ADD COLUMN type_status TEXT");
   }
 
+  // Audit peer F: a legacy DB may hold a non-integer generation/applied_generation
+  // (pre-v0.3.9 the JS gate truncated with Math.trunc and SQLite's CHECK only
+  // enforced >= 0). Such a value is ambiguous — it cannot map to a real applied
+  // round — so surface it as a hard error on open instead of silently reading it
+  // as a coherent generation. Fail-closed: the operator must repair or reset the
+  // state row rather than continue with a lie.
+  for (const col of ["generation", "applied_generation"]) {
+    const bad = db.prepare(
+      `SELECT id FROM mirror_state WHERE ${col} IS NOT NULL AND ${col} != CAST(${col} AS INTEGER) LIMIT 1`
+    ).get();
+    if (bad) {
+      throw new RangeError(
+        `mirror_state.${col} holds a non-integer value (legacy dirty state); ` +
+        `repair or reset the row before opening this database`
+      );
+    }
+  }
+
   // Per-instance monotonic timestamp guard: consecutive writes within the same
   // millisecond must still produce strictly increasing timestamps (test asserts
   // updated_at != created_at). State lives in the store closure, not module scope.
@@ -467,10 +497,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 +523,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();
+    });
   }
 
   /**
@@ -526,34 +573,53 @@ export function createStore(path) {
     const embedding = patch.embedding !== undefined
       ? (Array.isArray(patch.embedding) && patch.embedding.length ? JSON.stringify(patch.embedding) : null)
       : existing.embedding ?? null;
-    const result = db.prepare(
-      `UPDATE memories SET type=?, title=?, content=?, tags=?, importance=?, source=?, embedding=?, updated_at=?
-       WHERE id=? AND updated_at=?`
-    ).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,
-      expectedUpdatedAt
-    );
-    if (result.changes === 0) return undefined; // CAS miss: a concurrent write won
+    // The CAS UPDATE and the desired-generation bump must commit together (audit
+    // peer A): if the UPDATE autocommits first and the process dies before the
+    // increment, the store is mutated while generation == applied_generation and
+    // dirty == false — recoverMirror sees no debt and the mirror stays stale.
+    // Wrapping both in one transaction means a CAS miss rolls back cleanly too
+    // (no write, no generation bump).
+    let applied = false;
+    runAtomically(() => {
+      const result = db.prepare(
+        `UPDATE memories SET type=?, title=?, content=?, tags=?, importance=?, source=?, embedding=?, updated_at=?
+         WHERE id=? AND updated_at=?`
+      ).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,
+        expectedUpdatedAt
+      );
+      if (result.changes === 0) return; // CAS miss: a concurrent write won
+      // Only bump desired generation on a successful CAS — a miss writes nothing.
+      incrementGeneration();
+      applied = true;
+    });
+    if (!applied) return undefined;
     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 +1255,17 @@ export function createStore(path) {
       if (key === "dirty") {
         value = value ? 1 : 0;
       } else if (key === "generation" || key === "applied_generation") {
-        value = Math.trunc(Number(value)) || 0;
+        // Fail-closed integer enforcement (audit peer F): never truncate. A
+        // fractional value like 1.5 previously passed the JS gate via
+        // Math.trunc while SQLite's CHECK (>= 0) silently accepted it too, so a
+        // dirty legacy row could carry a non-integer generation that reads as a
+        // coherent applied round. Reject non-integers outright — the caller must
+        // pass a whole number, and a stale dirty value stays visible instead of
+        // being "repaired" into a misleading clean integer.
+        value = Number(value);
+        if (!Number.isInteger(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 +1296,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 +1341,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 +1367,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",
+  "description": "Cross-session memory plugin for DeepSeek Harness with autoDream consolidation: SQLite store, Markdown mirrors, 7 model tools, automatic injection, session summarization, user profile/rules, custom slash commands, vector (semantic) search, and a Web GUI panel",
+  "version": "0.3.9",
   "license": "MIT",
   "type": "module",
   "main": "lib/index.js",

package/scripts/e2e-dsh.js

@@ -104,9 +104,11 @@ console.log(`记忆目录：${memDir}\n`);
 // 1. 装载检查
 console.log("【1】插件装载");
 const checks = [];
-checks.push(["注册 6 个模型工具", registeredTools.length === 6]);
+checks.push(["注册 7 个模型工具", registeredTools.length === 7]);
 checks.push(["注册 2 个注入上下文", injectContexts.length === 2 && injectContexts[0].name === "memory"]);
-checks.push(["注册 9 条 API 路由", apiRoutes.length === 9]);
+// 契约是 9 条 exact 路由；prefix fallback（/api/dsh-mneme → 404）是兜底，
+// 不计入路由数。
+checks.push(["注册 9 条 API 路由", apiRoutes.filter((r) => r.kind === "exact").length === 9]);
 for (const [label, ok] of checks) console.log(`  ${ok ? "✅" : "❌"} ${label}`);
 if (!checks.every(([, ok]) => ok)) { console.log("\n装载检查失败，中止。"); process.exit(1); }
 console.log(`  工具：${registeredTools.map((t) => t.name).join(", ")}\n`);

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;
@@ -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/src/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 };