@modusensus/dsh-mneme 0.2.7 → 0.2.9

package/src/store.js

@@ -37,10 +37,27 @@ CREATE TABLE IF NOT EXISTS dream_runs (
   outcome        TEXT,                   -- JSON: { byId: {id: action} }
   applied        INTEGER NOT NULL DEFAULT 0,
   summary_stored INTEGER NOT NULL DEFAULT 0,
-  receipt        TEXT NOT NULL
+  receipt        TEXT NOT NULL,
+  policy_epoch   INTEGER NOT NULL DEFAULT 0  -- 裁决规则版本：规则升级后旧裁决降级为历史证据
 );
 CREATE INDEX IF NOT EXISTS idx_dream_runs_created ON dream_runs(created_at);
 
+-- recall_runs: recall-layer receipt. One row per retrieval scene — the query,
+-- mode, top-k, threshold and the exact candidate list (id/title/content/score/
+-- source) that was returned — so retrieval behavior can be audited and
+-- replayed after the fact. Sibling of the dream judgment-layer audit trail.
+CREATE TABLE IF NOT EXISTS recall_runs (
+  id          TEXT PRIMARY KEY,
+  query       TEXT NOT NULL,
+  mode        TEXT NOT NULL,
+  top_k       INTEGER,
+  threshold   REAL,
+  candidates  TEXT NOT NULL,   -- JSON: 召回候选数组（含 id/title/content/score/source）
+  created_at  TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_recall_runs_created ON recall_runs(created_at);
+CREATE INDEX IF NOT EXISTS idx_recall_runs_query ON recall_runs(query);
+
 -- failure_memories: records user corrections / reflection failures. Captures
 -- what a memory was (actual) vs what the user changed it to (expected)
 -- so later reflection passes can mine recurring correction patterns.
@@ -58,6 +75,49 @@ CREATE TABLE IF NOT EXISTS failure_memories (
 );
 CREATE INDEX IF NOT EXISTS idx_failure_memories_created ON failure_memories(created_at);
 CREATE INDEX IF NOT EXISTS idx_failure_memories_type ON failure_memories(failure_type);
+
+-- receipt_chain: per-record receipt chain. One row per mutable verdict
+-- (merge/conflict/update), carrying the input digest (the basis of the
+-- decision, content-addressed) and the idempotency check counters
+-- count_before → count_after. Replaying the same decision must reproduce the
+-- same result; a digest match with a divergent outcome pinpoints drift to the
+-- specific record/run. Sibling of the run-level dream audit trail.
+CREATE TABLE IF NOT EXISTS receipt_chain (
+  receipt_id   TEXT PRIMARY KEY,
+  run_id       TEXT NOT NULL,
+  record_id    TEXT NOT NULL,
+  kind         TEXT NOT NULL,         -- merge | conflict | update
+  input_digest TEXT NOT NULL,
+  winner_id    TEXT,
+  loser_id     TEXT,
+  keep_source  TEXT,
+  sources      TEXT,                  -- JSON: merge 全部参与 id 数组
+  verdict      TEXT NOT NULL,         -- live | revoked | historical
+  count_before INTEGER NOT NULL,
+  count_after  INTEGER NOT NULL,
+  policy_epoch INTEGER NOT NULL DEFAULT 0,
+  created_at   TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_receipt_chain_record ON receipt_chain(record_id);
+CREATE INDEX IF NOT EXISTS idx_receipt_chain_run ON receipt_chain(run_id);
+
+-- conflict_pending: conflicts parked for manual review (conflict freeze mode,
+-- opt-in via config.conflictFreezeEnabled). When enabled, the dream layer does
+-- NOT auto-adjudicate winner/loser — the conflicting pair is parked here until
+-- a human reviews it. resolveConflictPending stamps resolved_at (plus the chosen
+-- winner) so the review action stays auditable. Like the other audit tables this
+-- is bookkeeping: it never triggers write hooks.
+CREATE TABLE IF NOT EXISTS conflict_pending (
+  id              TEXT PRIMARY KEY,
+  run_id          TEXT,
+  memory_a        TEXT NOT NULL,
+  memory_b        TEXT NOT NULL,
+  reason          TEXT,
+  created_at      TEXT NOT NULL,
+  resolved_at     TEXT,
+  resolved_winner TEXT
+);
+CREATE INDEX IF NOT EXISTS idx_conflict_pending_unresolved ON conflict_pending(resolved_at);
 `;
 
 const TYPES = new Set(["preference", "project", "decision", "history", "summary"]);
@@ -116,10 +176,67 @@ function toDreamRun(row) {
     outcome: row.outcome ? JSON.parse(row.outcome) : undefined,
     applied: row.applied,
     summary_stored: row.summary_stored === 1,
-    receipt: row.receipt
+    receipt: row.receipt,
+    policy_epoch: row.policy_epoch ?? 0
+  };
+}
+
+function toReceipt(row) {
+  if (!row) return undefined;
+  return {
+    receipt_id: row.receipt_id,
+    run_id: row.run_id,
+    record_id: row.record_id,
+    kind: row.kind,
+    input_digest: row.input_digest,
+    winner_id: row.winner_id ?? undefined,
+    loser_id: row.loser_id ?? undefined,
+    keep_source: row.keep_source ?? undefined,
+    sources: parseJsonArray(row.sources),
+    verdict: row.verdict,
+    count_before: row.count_before,
+    count_after: row.count_after,
+    policy_epoch: row.policy_epoch ?? 0,
+    created_at: row.created_at
+  };
+}
+
+function toConflictPending(row) {
+  if (!row) return undefined;
+  return {
+    id: row.id,
+    run_id: row.run_id ?? undefined,
+    memory_a: row.memory_a,
+    memory_b: row.memory_b,
+    reason: row.reason ?? undefined,
+    created_at: row.created_at,
+    resolved_at: row.resolved_at ?? undefined,
+    resolved_winner: row.resolved_winner ?? undefined
+  };
+}
+
+function toRecallRun(row) {
+  if (!row) return undefined;
+  return {
+    id: row.id,
+    query: row.query,
+    mode: row.mode,
+    topK: row.top_k,
+    threshold: row.threshold,
+    candidates: parseJsonArray(row.candidates),
+    created_at: row.created_at
   };
 }
 
+function parseJsonArray(raw) {
+  try {
+    const arr = JSON.parse(raw);
+    return Array.isArray(arr) ? arr : [];
+  } catch {
+    return [];
+  }
+}
+
 export function createStore(path) {
   const db = new DatabaseSync(path);
   db.exec("PRAGMA journal_mode = WAL;");
@@ -134,6 +251,12 @@ export function createStore(path) {
     db.exec("ALTER TABLE memories ADD COLUMN embedding TEXT");
   }
 
+  // Legacy dream_runs without policy_epoch → backfill with the default epoch.
+  const dreamCols = db.prepare("PRAGMA table_info(dream_runs)").all().map((c) => c.name);
+  if (!dreamCols.includes("policy_epoch")) {
+    db.exec("ALTER TABLE dream_runs ADD COLUMN policy_epoch INTEGER NOT NULL DEFAULT 0");
+  }
+
   // 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.
@@ -398,16 +521,17 @@ export function createStore(path) {
   function saveDreamRun(run) {
     const id = run.id ?? randomUUID();
     const now = nowIso();
+    const policyEpoch = Number.isInteger(run.policy_epoch) ? run.policy_epoch : 0;
     db.prepare(
       `INSERT INTO dream_runs (id, created_at, status, error, provider, model, snapshot_hash,
-        input_count, input, decisions, outcome, applied, summary_stored, receipt)
-       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+        input_count, input, decisions, outcome, applied, summary_stored, receipt, policy_epoch)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
        ON CONFLICT(id) DO UPDATE SET
          created_at=excluded.created_at, status=excluded.status, error=excluded.error,
          provider=excluded.provider, model=excluded.model, snapshot_hash=excluded.snapshot_hash,
          input_count=excluded.input_count, input=excluded.input, decisions=excluded.decisions,
          outcome=excluded.outcome, applied=excluded.applied, summary_stored=excluded.summary_stored,
-         receipt=excluded.receipt`
+         receipt=excluded.receipt, policy_epoch=excluded.policy_epoch`
     ).run(
       id,
       run.created_at ?? now,
@@ -422,7 +546,8 @@ export function createStore(path) {
       run.outcome !== undefined ? JSON.stringify(run.outcome) : null,
       run.applied ?? 0,
       run.summary_stored ? 1 : 0,
-      run.receipt
+      run.receipt,
+      policyEpoch
     );
     return getDreamRun(id);
   }
@@ -440,6 +565,136 @@ export function createStore(path) {
     return rows.map(toDreamRun);
   }
 
+  /**
+   * Latest ruling-rule version seen on the audit trail. policy_epoch is a config
+   * value stamped onto each run by the caller; reading the newest row's epoch
+   * gives the current effective version, falling back to 0 (default) when the
+   * trail is empty. Rules upgrades leave older runs with their original epoch,
+   * so those decisions can be demoted to historical evidence.
+   */
+  function getLatestPolicyEpoch() {
+    const row = db.prepare(
+      "SELECT policy_epoch FROM dream_runs ORDER BY created_at DESC, id LIMIT 1"
+    ).get();
+    return row ? (row.policy_epoch ?? 0) : 0;
+  }
+
+  // --- per-record receipt chain --------------------------------------------
+
+  /**
+   * Persist one per-record receipt (a single merge/conflict/update verdict).
+   * The run-level dream audit trail answers "did this run happen and with what
+   * input"; the receipt chain drills down to each mutable verdict, carrying the
+   * input digest (decision basis) plus count_before → count_after idempotency
+   * checkpoints so replay drift can be located to the exact record/run. Like
+   * the dream trail this is bookkeeping: it never triggers write hooks. Writes
+   * are idempotent on receipt id (replay overwrites, never duplicates).
+   */
+  function saveReceipt(run) {
+    const id = run.receipt_id ?? randomUUID();
+    const now = nowIso();
+    const policyEpoch = Number.isInteger(run.policy_epoch) ? run.policy_epoch : 0;
+    db.prepare(
+      `INSERT INTO receipt_chain (receipt_id, run_id, record_id, kind, input_digest,
+        winner_id, loser_id, keep_source, sources, verdict, count_before, count_after,
+        policy_epoch, created_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+       ON CONFLICT(receipt_id) DO UPDATE SET
+         run_id=excluded.run_id, record_id=excluded.record_id, kind=excluded.kind,
+         input_digest=excluded.input_digest, winner_id=excluded.winner_id,
+         loser_id=excluded.loser_id, keep_source=excluded.keep_source,
+         sources=excluded.sources, verdict=excluded.verdict,
+         count_before=excluded.count_before, count_after=excluded.count_after,
+         policy_epoch=excluded.policy_epoch, created_at=excluded.created_at`
+    ).run(
+      id,
+      run.run_id,
+      run.record_id,
+      run.kind,
+      run.input_digest,
+      run.winner_id ?? null,
+      run.loser_id ?? null,
+      run.keep_source ?? null,
+      JSON.stringify(run.sources ?? []),
+      run.verdict,
+      run.count_before,
+      run.count_after,
+      policyEpoch,
+      run.created_at ?? now
+    );
+    return getReceipt(id);
+  }
+
+  function getReceipt(id) {
+    const row = db.prepare("SELECT * FROM receipt_chain WHERE receipt_id = ?").get(id);
+    return toReceipt(row);
+  }
+
+  function listReceipts({ limit = 50, offset = 0, run_id } = {}) {
+    const { limit: lim, offset: off } = sanitizePage(limit, offset, 50);
+    const clauses = [];
+    const params = [];
+    if (run_id) {
+      clauses.push("run_id = ?");
+      params.push(run_id);
+    }
+    const where = clauses.length ? `WHERE ${clauses.join(" AND ")}` : "";
+    const rows = db.prepare(
+      `SELECT * FROM receipt_chain ${where} ORDER BY created_at DESC, receipt_id LIMIT ? OFFSET ?`
+    ).all(...params, lim, off);
+    return rows.map(toReceipt);
+  }
+
+  // --- recall-layer audit trail -------------------------------------------
+
+  /**
+   * Persist one recall run (the retrieval scene: query/mode/top-k/threshold +
+   * the exact candidate list handed to the caller). Like the dream audit trail
+   * this is bookkeeping, so it never triggers write hooks — a notify here would
+   * loop back into search itself. Writes are idempotent on run id (replay
+   * overwrites, never duplicates), matching saveDreamRun.
+   */
+  function saveRecallRun(run) {
+    const id = run.id ?? randomUUID();
+    db.prepare(
+      `INSERT INTO recall_runs (id, query, mode, top_k, threshold, candidates, created_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?)
+       ON CONFLICT(id) DO UPDATE SET
+         query=excluded.query, mode=excluded.mode, top_k=excluded.top_k,
+         threshold=excluded.threshold, candidates=excluded.candidates,
+         created_at=excluded.created_at`
+    ).run(
+      id,
+      run.query,
+      run.mode,
+      run.topK ?? null,
+      run.threshold ?? null,
+      JSON.stringify(run.candidates ?? []),
+      run.created_at ?? nowIso()
+    );
+    return getRecallRun(id);
+  }
+
+  function getRecallRun(id) {
+    const row = db.prepare("SELECT * FROM recall_runs WHERE id = ?").get(id);
+    return toRecallRun(row);
+  }
+
+  function listRecallRuns({ limit = 50, offset = 0, query } = {}) {
+    const { limit: lim, offset: off } = sanitizePage(limit, offset, 50);
+    const clauses = [];
+    const params = [];
+    if (query) {
+      clauses.push("query LIKE ? ESCAPE '\\'");
+      params.push(`%${escapeLike(String(query))}%`);
+    }
+    const where = clauses.length ? `WHERE ${clauses.join(" AND ")}` : "";
+    const rows = db.prepare(
+      `SELECT * FROM recall_runs ${where} ORDER BY created_at DESC, id LIMIT ? OFFSET ?`
+    ).all(...params, lim, off);
+    return rows.map(toRecallRun);
+  }
+
   // --- failure memories ----------------------------------------------------
 
   /**
@@ -479,6 +734,66 @@ export function createStore(path) {
     return db.prepare("DELETE FROM failure_memories WHERE created_at < ?").run(before).changes;
   }
 
+  // --- conflict freeze: pending manual review ------------------------------
+
+  /**
+   * Park a detected conflict for human review (conflict freeze mode). The pair
+   * order is normalized (sorted by id) so the same two memories are only ever
+   * pending once — a re-detection in a later dream run is a no-op, never a
+   * duplicate queue entry. Returns the pending row (freshly inserted, or the
+   * existing unresolved row when the pair is already pending).
+   */
+  function saveConflictPending({ run_id, memory_a, memory_b, reason }) {
+    const [a, b] = [memory_a, memory_b].sort();
+    const existing = db.prepare(
+      "SELECT * FROM conflict_pending WHERE memory_a = ? AND memory_b = ? AND resolved_at IS NULL LIMIT 1"
+    ).get(a, b);
+    if (existing) return toConflictPending(existing);
+    const id = randomUUID();
+    const now = nowIso();
+    db.prepare(
+      `INSERT INTO conflict_pending (id, run_id, memory_a, memory_b, reason, created_at)
+       VALUES (?, ?, ?, ?, ?, ?)`
+    ).run(id, run_id ?? null, a, b, reason ?? null, now);
+    return toConflictPending(db.prepare("SELECT * FROM conflict_pending WHERE id = ?").get(id));
+  }
+
+  /**
+   * List pending conflicts, newest first. Unresolved rows only by default;
+   * pass includeResolved to include resolved ones (audit view).
+   */
+  function listConflictPending({ limit = 50, offset = 0, includeResolved = false } = {}) {
+    const { limit: lim, offset: off } = sanitizePage(limit, offset, 50);
+    const clauses = [];
+    const params = [];
+    if (!includeResolved) clauses.push("resolved_at IS NULL");
+    const where = clauses.length ? `WHERE ${clauses.join(" AND ")}` : "";
+    const rows = db.prepare(
+      `SELECT * FROM conflict_pending ${where} ORDER BY created_at DESC, id LIMIT ? OFFSET ?`
+    ).all(...params, lim, off);
+    return rows.map(toConflictPending);
+  }
+
+  /**
+   * Mark a pending conflict as reviewed. winner (optional) records which side
+   * the human chose, keeping the resolution auditable. Returns the updated row,
+   * or undefined for an unknown id.
+   */
+  function resolveConflictPending(id, { winner } = {}) {
+    const row = db.prepare("SELECT * FROM conflict_pending WHERE id = ?").get(id);
+    if (!row) return undefined;
+    db.prepare("UPDATE conflict_pending SET resolved_at = ?, resolved_winner = ? WHERE id = ?")
+      .run(nowIso(), winner ?? null, id);
+    return toConflictPending(db.prepare("SELECT * FROM conflict_pending WHERE id = ?").get(id));
+  }
+
+  /** Number of unresolved (awaiting review) pending conflicts. */
+  function countConflictPending() {
+    return db.prepare(
+      "SELECT count(*) AS c FROM conflict_pending WHERE resolved_at IS NULL"
+    ).get().c;
+  }
+
   function getFailureStats({ since } = {}) {
     const clause = since ? "WHERE created_at >= ?" : "";
     const params = since ? [since] : [];
@@ -510,10 +825,21 @@ export function createStore(path) {
     saveDreamRun,
     getDreamRun,
     listDreamRuns,
+    getLatestPolicyEpoch,
+    saveReceipt,
+    getReceipt,
+    listReceipts,
+    saveRecallRun,
+    getRecallRun,
+    listRecallRuns,
     saveFailure,
     listFailures,
     getFailureStats,
     deleteOldFailures,
+    saveConflictPending,
+    listConflictPending,
+    resolveConflictPending,
+    countConflictPending,
     close() {
       db.close();
     }

package/test/audit.test.js

@@ -6,6 +6,7 @@ import { join } from "node:path";
 import {
   createDreamScheduler,
   hashSnapshot,
+  hashDecisionInput,
   buildReceipt,
   parseReceipt,
   buildOutcome
@@ -104,6 +105,97 @@ test("successful runDream writes an audit row with receipt, decisions and outcom
   store.close();
 });
 
+// ---------------------------------------------------------------- per-record receipt chain
+
+test("hashDecisionInput is deterministic, order-independent and content-addressed", () => {
+  const mk = (id, title, content = "c") => ({ id, title, content, importance: 3 });
+  const a = mk("a", "t1");
+  const b = mk("b", "t2");
+  assert.equal(hashDecisionInput([a, b]), hashDecisionInput([b, a]), "order independent");
+  assert.equal(hashDecisionInput([a, b]), hashDecisionInput([{ ...a }, { ...b }]), "clone independent");
+  assert.notEqual(hashDecisionInput([a, b]), hashDecisionInput([a, { ...b, content: "changed" }]), "content change flips digest");
+  assert.match(hashDecisionInput([]), /^[0-9a-f]{64}$/, "empty input hashes stably");
+});
+
+test("runDream writes one per-record receipt per committed merge/conflict/update", async () => {
+  const { store, service, dream } = setup();
+  const { memory: a } = service.saveWithDedupe({ type: "project", title: "插件", content: "旧", importance: 3 });
+  const { memory: b } = service.saveWithDedupe({ type: "project", title: "插件2", content: "新细节", importance: 4 });
+  const { memory: w } = service.saveWithDedupe({ type: "decision", title: "截止", content: "8月20日", importance: 4 });
+  const { memory: l } = service.saveWithDedupe({ type: "decision", title: "截止旧", content: "8月15日", importance: 4 });
+  const { memory: u } = service.saveWithDedupe({ type: "preference", title: "语言", content: "喜欢 Python" });
+  const ctx = mockCtx({
+    onConsolidation: () => JSON.stringify([
+      { action: "merge", ids: [a.id, b.id], keepSource: b.id, title: "插件总览", content: "合并内容", importance: 4 },
+      { action: "conflict", winner: w.id, loser: l.id, reason: "更新" },
+      { action: "update", ids: [u.id], content: "喜欢 Rust" }
+    ])
+  });
+  // Backdate the update target so the update age guard (minAgeHours) sees a
+  // settled record rather than a sub-second-old one — store.nowIso() can drift
+  // a few ms ahead of the wall clock when seeds land in the same millisecond.
+  store.db.prepare("UPDATE memories SET created_at = ? WHERE id = ?")
+    .run(new Date(Date.now() - 3600000).toISOString(), u.id);
+  const result = await dream.runDream(ctx, service, { reflectionUpdateMinAgeHours: 0, policyEpoch: 3 });
+  assert.equal(result.status, "ok");
+
+  const receipts = store.listReceipts({ run_id: result.runId });
+  assert.equal(receipts.length, 3, "one receipt per mutable verdict, none for keep/archive");
+
+  const byKind = Object.fromEntries(receipts.map((r) => [r.kind, r]));
+  assert.deepEqual(Object.keys(byKind).sort(), ["conflict", "merge", "update"]);
+
+  const merge = byKind.merge;
+  assert.equal(merge.run_id, result.runId);
+  assert.equal(merge.record_id, b.id, "merge receipt keyed on keepSource");
+  assert.equal(merge.keep_source, b.id);
+  assert.deepEqual(merge.sources, [a.id, b.id], "merge sources = full id array");
+  assert.equal(merge.count_before, 2);
+  assert.equal(merge.count_after, 1);
+  assert.equal(merge.verdict, "live");
+  assert.equal(merge.policy_epoch, 3, "policy epoch stamped from config");
+  assert.equal(merge.input_digest, hashDecisionInput([a, b]), "digest over the pre-apply basis memories");
+  assert.match(merge.created_at, /^2\d{3}-/, "created_at is an ISO timestamp");
+
+  const conflict = byKind.conflict;
+  assert.equal(conflict.record_id, w.id, "conflict receipt keyed on winner");
+  assert.equal(conflict.winner_id, w.id);
+  assert.equal(conflict.loser_id, l.id);
+  assert.equal(conflict.keep_source, undefined, "no keep_source on a conflict");
+  assert.equal(conflict.count_before, 2);
+  assert.equal(conflict.count_after, 1);
+  assert.equal(conflict.input_digest, hashDecisionInput([w, l]), "digest over winner+loser");
+
+  const update = byKind.update;
+  assert.equal(update.record_id, u.id);
+  assert.equal(update.winner_id, undefined, "no winner/loser on an update");
+  assert.equal(update.count_before, 1);
+  assert.equal(update.count_after, 1);
+  assert.equal(update.input_digest, hashDecisionInput([u]), "digest over the pre-update target");
+  store.close();
+});
+
+test("a throwing per-record receipt writer never breaks the run (bookkeeping fails safe)", async () => {
+  const { store, service, dream } = setup();
+  const { memory: a } = service.saveWithDedupe({ type: "project", title: "甲", content: "A", importance: 3 });
+  const { memory: b } = service.saveWithDedupe({ type: "project", title: "乙", content: "B", importance: 4 });
+  service.saveReceipt = () => { throw new Error("receipt store boom"); };
+  const ctx = mockCtx({
+    onConsolidation: () => JSON.stringify([
+      { action: "merge", ids: [a.id, b.id], keepSource: b.id, title: "甲乙", content: "合并", importance: 4 }
+    ])
+  });
+  const result = await dream.runDream(ctx, service, {});
+  assert.equal(result.ok, true, "consolidation unaffected by receipt failure");
+  assert.equal(result.applied, 1);
+  const run = store.listDreamRuns()[0];
+  assert.equal(run.status, "ok", "audit row still written");
+  assert.equal(store.getById(b.id).title, "甲乙", "merge still applied");
+  assert.equal(store.getById(a.id).archived, true, "merge source still archived");
+  assert.equal(store.listReceipts().length, 0, "no receipts persisted");
+  store.close();
+});
+
 test("failed runDream records status failed with the error", async () => {
   const { store, service, dream } = setup();
   service.saveWithDedupe({ type: "preference", title: "语言", content: "中文" });