@modusensus/dsh-mneme 0.2.6 → 0.2.8

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-258%20passed-success)](https://github.com/modusensus/dsh-mneme)
+[![tests](https://img.shields.io/badge/tests-263%20passed-success)](https://github.com/modusensus/dsh-mneme)
 
 > 给 DeepSeek Harness 的跨会话记忆插件：让 Agent 记住你、记住项目、自动整理记忆。**Mneme**（Μνήμη）——希腊记忆女神 Mnemosyne 之名，掌管记忆与梦境，正如 autoDream 在后台巩固记忆。
 
@@ -225,7 +225,7 @@ src/
 lib/
 ├── client.js         # Web 面板（手写 ModuleLoader bundle）
 └── *.js              # src 的同步分发产物
-test/                 # 258 个 node:test 测试（含审计与三轴线压测不变量）
+test/                 # 263 个 node:test 测试（含审计与三轴线压测不变量）
 scripts/              # e2e-dsh.js 端到端演示 · stress-dsh.js 三轴线压测 · sync-lib.js 同步
 ```
 
@@ -234,7 +234,7 @@ scripts/              # e2e-dsh.js 端到端演示 · stress-dsh.js 三轴线压
 ```bash
 cd dsh-mneme
 npm install        # 安装 peer 依赖（以 devDependencies 形式，用于本地测试）
-npm test           # 运行 258 个测试
+npm test           # 运行 263 个测试
 npm run stress     # 三轴线压测：长会话检索 / 冲突仲裁 / 多 Agent 并发（离线 mock LLM）
 npm run sync       # 把 src/ 同步到 lib/（发布时由 prepack 钩子自动执行）
 ```

package/lib/config.js

@@ -13,6 +13,10 @@ export const Config = z.object({
   dreamProvider: z.string(),
   dreamModel: z.string(),
   dreamMaxTokens: z.natural().min(256).max(32768).default(4096),
+  // Rule version for dream adjudication: when this bumps, older dream_runs
+  // degrade to historical evidence (their receipts no longer drive live
+  // decisions). Default 0 = no versioning in use yet.
+  policyEpoch: z.natural().min(0).max(1000000).default(0),
 
   // --- API protection ------------------------------------------------------
   // Optional shared token for the plugin's HTTP API. Empty (default) keeps

package/lib/dream/decisions.js

@@ -244,7 +244,7 @@ function applyMerge(d, service, snapshot) {
   });
   return {
     applied: 1,
-    committed: { action: "merge", ids: d.ids, keepSource: d.keepSource, title: d.title, content: d.content, importance: d.importance }
+    committed: { action: "merge", ids: d.ids, keepSource: d.keepSource, title: d.title, content: d.content, importance: d.importance, count_before: d.ids.length, count_after: 1 }
   };
 }
 
@@ -266,7 +266,7 @@ function applyConflict(d, service, snapshot) {
     });
     service.setArchived(d.loser, true);
   });
-  return { applied: 1, committed: { action: "conflict", winner: d.winner, loser: d.loser } };
+  return { applied: 1, committed: { action: "conflict", winner: d.winner, loser: d.loser, count_before: 2, count_after: 1 } };
 }
 
 function applyUpdate(d, service, snapshot) {
@@ -288,5 +288,5 @@ function applyUpdate(d, service, snapshot) {
       importance: d.importance ?? cur.importance
     });
   });
-  return { applied: 1, committed: { action: "update", ids: [id], title: d.title, content: d.content, importance: d.importance } };
+  return { applied: 1, committed: { action: "update", ids: [id], title: d.title, content: d.content, importance: d.importance, count_before: 1, count_after: 1 } };
 }

package/lib/dream.js

@@ -68,7 +68,7 @@ export function parseReceipt(receipt) {
   // reconcile = decisions validated but one or more did not commit (CAS
   // conflict / transaction rollback) — the store diverges from the decision
   // list and the run must be reconciled, never reported as a fake ok.
-  if (!runId || !/^(ok|failed|reconcile)$/.test(status)) return undefined;
+  if (!runId || !/^(ok|noop|degraded|reconcile|failed)$/.test(status)) return undefined;
   const count = Number(inputCount);
   const appliedN = Number(applied);
   if (!Number.isInteger(count) || !Number.isInteger(appliedN)) return undefined;
@@ -100,6 +100,78 @@ export function buildOutcome(decisions) {
   return { byId };
 }
 
+/**
+ * Content-addressed digest of the memories a verdict was decided against
+ * (id + title + content + importance), sorted by id so identical inputs always
+ * hash the same. This is the per-record "判定依据" fingerprint: a receipt whose
+ * digest cannot be reproduced from the involved memories is a bare claim, and a
+ * digest match with a divergent outcome pinpoints drift to the exact record.
+ */
+export function hashDecisionInput(memories) {
+  const canon = (memories ?? [])
+    .map((m) => [m.id, m.title, m.content, m.importance])
+    .sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0))
+    .map((p) => p.map((x) => String(x ?? "")).join("
"))
+    .join("");
+  return createHash("sha256").update(canon).digest("hex");
+}
+
+/**
+ * Build the per-record receipts for a run's actually-committed mutable verdicts
+ * (merge/conflict/update) — one row per verdict in the receipt_chain. Inputs
+ * are drawn from the run snapshot (what the LLM actually arbitrated against),
+ * and the idempotency counters count_before → count_after come from the
+ * committed sub-step, so replaying the same decision must reproduce the same
+ * numbers. verdict starts "live"; a later policy_epoch upgrade will batch-mark
+ * older verdicts "historical" (a receipt_chain rewrite driven by the store's
+ * getLatestPolicyEpoch — out of scope for this pass), while "revoked" is
+ * reserved for verdicts later overturned by an explicit human decision.
+ */
+function buildRecordReceipts({ runId, committed, snapshot, policyEpoch }) {
+  const at = (id) => snapshot?.get?.(id);
+  const receipts = [];
+  for (const c of committed ?? []) {
+    const base = {
+      run_id: runId,
+      verdict: "live",
+      count_before: c.count_before,
+      count_after: c.count_after,
+      policy_epoch: policyEpoch,
+      created_at: new Date().toISOString()
+    };
+    if (c.action === "merge") {
+      receipts.push({
+        ...base,
+        receipt_id: randomUUID(),
+        record_id: c.keepSource,
+        kind: "merge",
+        input_digest: hashDecisionInput((c.ids ?? []).map(at).filter(Boolean)),
+        keep_source: c.keepSource,
+        sources: c.ids
+      });
+    } else if (c.action === "conflict") {
+      receipts.push({
+        ...base,
+        receipt_id: randomUUID(),
+        record_id: c.winner,
+        kind: "conflict",
+        input_digest: hashDecisionInput([at(c.winner), at(c.loser)].filter(Boolean)),
+        winner_id: c.winner,
+        loser_id: c.loser
+      });
+    } else if (c.action === "update") {
+      receipts.push({
+        ...base,
+        receipt_id: randomUUID(),
+        record_id: c.ids[0],
+        kind: "update",
+        input_digest: hashDecisionInput([at(c.ids[0])].filter(Boolean))
+      });
+    }
+  }
+  return receipts;
+}
+
 /**
  * Consume an LLM stream and return the accumulated text. Direct text-delta
  * accumulation covers both the real protocol ({type:"text-delta", index, text})
@@ -286,9 +358,11 @@ export function createDreamScheduler({ onRun, thresholdCount = 10, thresholdChar
     // replayable too.
     const finish = (result) => {
       // status is derived from what actually committed: ok only when the full
-      // decision list landed; reconcile when decisions were validated but some
-      // did not commit (CAS conflict / rollback); failed on any LLM/validation
-      // error. No fake "ok" for a partial commit.
+      // decision list landed (or a summary was refreshed); noop when nothing
+      // changed; degraded when real changes landed without a summary;
+      // reconcile when decisions were validated but some did not commit (CAS
+      // conflict / rollback); failed on any LLM/validation error. No fake "ok"
+      // for an empty or partial run.
       const status = result.status ?? (result.ok ? "ok" : "failed");
       const applied = result.applied ?? 0;
       const summaryStored = result.summary ?? false;
@@ -302,6 +376,10 @@ export function createDreamScheduler({ onRun, thresholdCount = 10, thresholdChar
           model: route?.model,
           snapshot_hash: snapshotHash,
           input_count: snapshot.size,
+          // 裁决规则版本号：config.policyEpoch（默认 0）。规则升级后该行保留
+          // 当时的 epoch，旧裁决据此降级为历史证据（store 层 getLatestPolicyEpoch
+          // 只负责读取当前生效版本，写入由这里完成）。
+          policy_epoch: config.policyEpoch ?? 0,
           // Full input snapshot (canonical fields) so the exact arbitration
           // input can be rebuilt offline from the audit row alone — the
           // digest + decisions + outcome triple makes silent errors locatable
@@ -418,6 +496,19 @@ export function createDreamScheduler({ onRun, thresholdCount = 10, thresholdChar
     // a target changed during the LLM call is skipped and reported as a
     // conflict instead of being overwritten (item ①).
     const { applied, conflicts, failures, committed } = applyDecisions(decisions, service, logger, snapshot);
+    // Per-record receipt chain: one row per actually-committed merge/conflict/
+    // update verdict, stamped with the decision-basis digest + idempotency
+    // counters (count_before → count_after). Written here, before the run audit
+    // row, so the verdict trail always precedes the run trail it belongs to.
+    // Bookkeeping: a write failure is logged and swallowed — it must never
+    // block the consolidation flow.
+    try {
+      for (const r of buildRecordReceipts({ runId, committed, snapshot, policyEpoch: config.policyEpoch ?? 0 })) {
+        service.saveReceipt(r);
+      }
+    } catch (error) {
+      logger?.warn?.(`dsh-mneme dream: failed to write per-record receipt: ${String(error)}`);
+    }
     // Attach the pre-update snapshot to the audit copy of each update decision
     // so the recorded row shows the before/after delta, not just the target.
     const auditDecisions = decisions.map((d) =>
@@ -432,6 +523,11 @@ export function createDreamScheduler({ onRun, thresholdCount = 10, thresholdChar
     const outcome = { ...buildOutcome(committed), conflicts, failures };
     // Decisions validated but not fully committed → reconcile (not ok).
     const partial = conflicts.length > 0 || failures.length > 0;
+    // No decision landed (all-keep, or every decision skipped as an idempotent
+    // replay) → nothing substantive changed. Distinct from a success: such a
+    // run must never be reported as ok, or the audit claims work that never
+    // happened and the scheduler refreshes the baseline on a false positive.
+    const noChange = applied === 0 && committed.every((c) => c.action === "keep");
 
     // Keep the vector index consistent with the post-dream store state.
     if (semantic?.embedder && semantic?.vectorIndex) {
@@ -476,9 +572,30 @@ export function createDreamScheduler({ onRun, thresholdCount = 10, thresholdChar
         } catch { /* best-effort */ }
       }
     }
+    // Honest status assignment (never a fake ok):
+    //   reconcile — some decisions validated but did not commit (CAS/rollback).
+    //   noop      — nothing changed and no summary persisted: truly an empty
+    //               run. ok:false keeps the scheduler from moving the baseline.
+    //   ok        — either real changes landed, or a fresh summary was stored
+    //               (all-keep + summary is a substantive summary refresh).
+    //   degraded  — real consolidation landed but the summary came back empty/
+    //               missing: the store was absorbed (ok for the baseline) but
+    //               the run did not produce its full output (marked, not faked).
+    let status;
+    let okResult;
+    if (partial) {
+      status = "reconcile";
+      okResult = false;
+    } else if (noChange) {
+      status = summaryStored ? "ok" : "noop";
+      okResult = summaryStored;
+    } else {
+      status = summaryStored ? "ok" : "degraded";
+      okResult = true;
+    }
     return finish({
-      ok: !partial,
-      status: partial ? "reconcile" : "ok",
+      ok: okResult,
+      status,
       applied,
       decisions: auditDecisions,
       outcome,

package/lib/index.js

@@ -44,6 +44,23 @@ export const apply = (ctx, config) => {
   const mirror = createMirror(memoryDir);
   const service = createService({ store, mirror, config: cfg });
 
+  // Recall-layer receipt: when searchMemories runs with recordRecall=true, the
+  // retrieval scene (query/mode/topK/threshold + candidates) is persisted to
+  // recall_runs for audit/replay — the sibling of the dream_runs judgment trail.
+  // Best-effort: a failed recall write must never break the search.
+  service.setRecallRecorder((recall) => {
+    try {
+      store.saveRecallRun({
+        query: recall.query,
+        mode: recall.mode,
+        topK: recall.topK,
+        threshold: recall.threshold ?? null,
+        candidates: recall.candidates ?? [],
+        created_at: recall.createdAt
+      });
+    } catch { /* non-fatal: recall recording is bookkeeping */ }
+  });
+
   // User-configurable settings (profile, rules) and custom commands share the
   // same SQLite file but live in dedicated tables, isolated from memories.
   const settings = createSettings(store.db);

package/lib/service.js

@@ -16,6 +16,13 @@ export function createService({ store, mirror, config, onWrite }) {
   let vectorIndex = null;
   let reranker = null;
 
+  // Optional recall recorder, installed via setRecallRecorder after creation.
+  // When searchMemories is called with recordRecall=true it receives the
+  // actual merged recall scene (candidates + scores + source + threshold) so
+  // the retrieval layer can be audited/replayed — the sibling of the dream
+  // judgment-layer audit trail (dream_runs).
+  let recallRecorder = null;
+
   // Transaction nesting depth. Inside service.transaction the per-mutation side
   // effects (mirror render, write notify, re-embed) are deferred so a ROLLBACK
   // never leaves the mirror file diverged from the database; transaction()
@@ -43,7 +50,7 @@ export function createService({ store, mirror, config, onWrite }) {
       const out = [];
       for (const s of scored) {
         const c = byId.get(s.id);
-        if (c) { out.push({ ...c, score: s.score }); if (out.length >= topK) break; }
+        if (c) { out.push({ ...c, score: s.score, source: "rerank" }); if (out.length >= topK) break; }
       }
       return out.length ? out : candidates.slice(0, topK);
     } catch {
@@ -78,15 +85,16 @@ export function createService({ store, mirror, config, onWrite }) {
     return base * (0.5 + (row.importance ?? 3) / 10);
   }
 
-  async function searchMemories(query, { mode = "auto", topK = 20, threshold, useRerank = true } = {}) {
+  async function searchMemories(query, { mode = "auto", topK = 20, threshold, useRerank = true, recordRecall = false } = {}) {
     const q = String(query ?? "").trim();
     if (!q) return [];
     const lim = topK > 0 ? topK : 20;
 
     // Keyword results, decorated with a score so they can be weight-blended
-    // with vector results and reported uniformly.
+    // with vector results and reported uniformly. source tracks where each
+    // candidate came from for the recall layer receipt.
     const rawKeyword = store.search(q, { limit: lim });
-    const keyword = rawKeyword.map((m) => ({ ...m, score: scoreKeyword(m, q) }));
+    const keyword = rawKeyword.map((m) => ({ ...m, score: scoreKeyword(m, q), source: "keyword" }));
     const wantVector = mode === "vector" || mode === "hybrid" || (mode === "auto" && !!embedder);
     let vector = [];
     if (wantVector && embedder) {
@@ -100,7 +108,7 @@ export function createService({ store, mirror, config, onWrite }) {
           const hits = vectorIndex
             ? vectorIndex.search(qv, { limit: lim * 2, threshold: threshold ?? 0 })
             : store.searchVector(qv, { limit: lim * 2, threshold: threshold ?? 0 });
-          vector = hits.map((m) => ({ ...m, vector: true }));
+          vector = hits.map((m) => ({ ...m, vector: true, source: "vector" }));
         }
       } catch { /* vector unavailable: keep keyword results */ }
     }
@@ -147,10 +155,34 @@ export function createService({ store, mirror, config, onWrite }) {
     }
 
     merged = merged.slice(0, lim);
-    if (useRerank && reranker && merged.length) {
-      return rerankCandidates(q, merged, lim);
+    const result = useRerank && reranker && merged.length
+      ? await rerankCandidates(q, merged, lim)
+      : merged;
+
+    // Recall layer receipt: with recordRecall on, hand the actual merged
+    // candidate list (id/title/content/score/source) to the injected recorder
+    // before returning, making the retrieval scene replayable — the sibling of
+    // the dream judgment-layer audit trail. Recorder failures must never break
+    // the search itself.
+    if (recordRecall && recallRecorder) {
+      try {
+        recallRecorder({
+          query: q,
+          mode,
+          topK: lim,
+          threshold: threshold ?? null,
+          candidates: result.map((m) => ({
+            id: m.id,
+            title: m.title,
+            content: m.content,
+            score: m.score ?? null,
+            source: m.source ?? "keyword"
+          })),
+          createdAt: new Date().toISOString()
+        });
+      } catch { /* recall receipt is best effort */ }
     }
-    return merged;
+    return result;
   }
 
   /**
@@ -355,6 +387,7 @@ export function createService({ store, mirror, config, onWrite }) {
     setEmbedder(emb) { embedder = emb; },
     setVectorIndex(vi) { vectorIndex = vi; },
     setReranker(rn) { reranker = rn; },
+    setRecallRecorder(fn) { recallRecorder = fn; },
     searchMemories,
     // passthroughs used by tools and api layers; mutations keep the mirror in sync
     search: (q, o) => store.search(q, o),
@@ -441,6 +474,11 @@ export function createService({ store, mirror, config, onWrite }) {
     // dream scheduler that just recorded the run.
     saveDreamRun: (run) => store.saveDreamRun(run),
     getDreamRun: (id) => store.getDreamRun(id),
-    listDreamRuns: (opts) => store.listDreamRuns(opts)
+    listDreamRuns: (opts) => store.listDreamRuns(opts),
+    // Per-record receipt chain (same bookkeeping semantics as saveDreamRun: an
+    // audit write, never a write-hook-triggering memory mutation).
+    saveReceipt: (r) => store.saveReceipt(r),
+    getReceipt: (id) => store.getReceipt(id),
+    listReceipts: (opts) => store.listReceipts(opts)
   };
 }