recallnest 2.3.0 → 2.5.4

package/src/capture-engine.ts

@@ -1,7 +1,7 @@
 import type { Embedder } from "./embedder.js";
 import { detectLang, tokenizeFts } from "./language-hook.js";
 import { generateAnchor } from "./anchor-generator.js";
-import { incrementWriteCount } from "./activity-counter.js";
+import { extractErrorSignatures } from "./error-signature.js";
 import { verifyWrite } from "./write-verifier.js";
 // batchInternalDedup is available in ingest.ts for large-batch scenarios;
 // persistMemoryBatch relies on per-item conflict detection (A-2) instead.
@@ -56,7 +56,7 @@ import {
 import { matchPreference, applyPreferenceMatch } from "./preference-matcher.js";
 import type { LLMClient } from "./llm-client.js";
 import type { KGExtractor } from "./kg-extractor.js";
-import { scanForPII } from "./pii-detector.js";
+import { scanForPII, redactSecrets } from "./pii-detector.js";
 import type { AuditLogger } from "./audit-log.js";
 import { checkAdmission, type ScopeRateLimiter, type AdmissionConfig } from "./admission-control.js";
 import { tagNarrativeIfEnabled } from "./narrative-tagger.js";
@@ -699,6 +699,17 @@ function buildCaseMemoryMetadata(
       tools: input.tools,
     },
   };
+  // A1: error-signature 指纹（读写对称，P3-A 检索复用同一抽取器）。
+  // 在 build metadata 前算好作为 extra 写入，不 post-write update（Codex 验证要求）。
+  const errorSignature = extractErrorSignatures({
+    problem: input.problem,
+    context: input.context,
+    outcome: input.outcome,
+    solutionSteps: input.solutionSteps,
+  });
+  if (errorSignature.length > 0) cmExtra.error_signature = errorSignature;
+  // A1: break-loop 五维（可选，向后兼容；不提供则普通 case）。
+  if (input.debugFraming) cmExtra.debugFraming = input.debugFraming;
   const anchor = generateAnchor(input.title + ": " + input.problem, cmExtra);
   if (anchor) cmExtra.anchor = anchor;
   return buildStructuredMetadata({
@@ -746,7 +757,16 @@ export async function persistMemory(
   deps: PersistMemoryDeps,
   rawInput: unknown,
 ): Promise<StoredMemoryRecord> {
-  const input = StoreMemoryInputSchema.parse(rawInput);
+  let input = StoreMemoryInputSchema.parse(rawInput);
+
+  // F-3b: Scan THEN redact, before the text reaches any external surface —
+  // LLM summary/importance calls, embedding API, storage, audit log, KG.
+  // Scan first so the piiWarning below still reflects what the raw text held.
+  const piiScan = scanForPII(input.text);
+  const redaction = redactSecrets(input.text);
+  if (redaction.redacted > 0) {
+    input = { ...input, text: redaction.text };
+  }
 
   // F3: Extract temporal validity params before Zod strips them
   const rawObj = rawInput as Record<string, unknown> | null;
@@ -801,6 +821,18 @@ export async function persistMemory(
     deps.admissionConfig,
   );
   if (admission.verdict === "rejected") {
+    // Gemini #26523 lesson: rejected writes must stay queryable after the fact,
+    // not just echo back to the caller — otherwise they become invisible noise.
+    try {
+      deps.auditLogger?.log({
+        operation: "reject",
+        scope: admissionScope,
+        actor: input.source,
+        details: `${admission.reason ?? "unknown"}: ${input.text.slice(0, 100)}`,
+      });
+    } catch {
+      // Audit must never block memory writes
+    }
     return {
       id: `rejected-${Date.now()}`,
       text: input.text,
@@ -812,6 +844,7 @@ export async function persistMemory(
       resolvedScope: admissionScope,
       storedAt: new Date().toISOString(),
       disposition: "rejected" as const,
+      ...(admission.reason ? { rejectionReason: admission.reason } : {}),
     };
   }
 
@@ -937,15 +970,16 @@ export async function persistMemory(
   }
 
   // F-3: PII detection — inject warning into metadata if PII found.
-  // Non-blocking: PII does not prevent the write.
+  // Non-blocking: PII does not prevent the write. Uses the pre-redaction scan
+  // from the top of persistMemory (scanning here would see scrubbed text).
   let metadata = buildStoreMemoryMetadata(input, canonicalKey);
-  const piiResult = scanForPII(input.text);
-  if (piiResult.hasPII) {
+  if (piiScan.hasPII) {
     const parsed: Record<string, unknown> = JSON.parse(metadata);
     parsed.piiWarning = {
-      summary: piiResult.summary,
-      detections: piiResult.detections.length,
-      severity: piiResult.detections.some(d => d.severity === "high") ? "high" : "medium",
+      summary: piiScan.summary,
+      detections: piiScan.detections.length,
+      severity: piiScan.detections.some(d => d.severity === "high") ? "high" : "medium",
+      ...(redaction.redacted > 0 ? { redacted: redaction.redacted } : {}),
     };
     metadata = JSON.stringify(parsed);
   }
@@ -1031,14 +1065,9 @@ export async function persistMemory(
     // Audit must never block memory writes
   }
 
-  // HP-3: Activity counter — track non-dedup writes for distill trigger
-  if (disposition !== "deduped") {
-    try {
-      incrementWriteCount();
-    } catch {
-      // Activity tracking must never block memory writes
-    }
-  }
+  // HP-3 activity counter moved to the store layer (store/upsert/storeBatch count per
+  // scope): that is the necessary chokepoint for every write source (capture/ingest/
+  // store_memory/consolidation), and per-scope counts drive per-scope dream activation.
 
   // HP-2: Post-write verification — async, non-blocking
   if (disposition !== "deduped" && deps.store.get) {
@@ -1063,7 +1092,7 @@ export async function persistMemory(
     input.category !== "preferences" &&
     inferImplicitUsageSlot(input.text)
   ) {
-    const prefCanonicalKey = buildDefaultCanonicalKey("preferences", input.text);
+    const prefCanonicalKey = buildDefaultCanonicalKey({ category: "preferences", text: input.text });
     const prefSlot = inferImplicitUsageSlot(input.text);
     const prefMetadata = buildStructuredMetadata({
       source: input.source,
@@ -1098,7 +1127,8 @@ export async function persistWorkflowPattern(
   const input = WorkflowPatternInputSchema.parse(rawInput);
   const resolvedScope = resolveScope(input);
   const tags = mergeTags(input.tags, ["workflow", "pattern"]);
-  const text = buildWorkflowPatternText(input);
+  // F-3b: scrub before embedding/storage (this path bypasses persistMemory)
+  const text = redactSecrets(buildWorkflowPatternText(input)).text;
   const vector = await deps.embedder.embedPassage(text);
   const language = detectLang(text);
   const fts_text = tokenizeFts(text, language);
@@ -1142,7 +1172,8 @@ export async function persistCaseMemory(
   const input = CaseMemoryInputSchema.parse(rawInput);
   const resolvedScope = resolveScope(input);
   const tags = mergeTags(input.tags, ["case", "solution"]);
-  const text = buildCaseMemoryText(input);
+  // F-3b: scrub before embedding/storage (this path bypasses persistMemory)
+  const text = redactSecrets(buildCaseMemoryText(input)).text;
   const vector = await deps.embedder.embedPassage(text);
   const language = detectLang(text);
   const fts_text = tokenizeFts(text, language);
@@ -1202,7 +1233,9 @@ export async function promoteMemory(
   }
 
   const category = inferPromotedCategory(input, sourceEntry);
-  const text = input.text || sourceEntry.text;
+  // F-3b: scrub caller-supplied text AND legacy stored text (pre-redaction
+  // era entries may still hold secrets; promotion is a natural wash point)
+  const text = redactSecrets(input.text || sourceEntry.text).text;
   const canonicalKey = resolveCanonicalKey({
     category,
     text,

package/src/cli.ts

@@ -11,7 +11,7 @@
 
 import { Command } from "commander";
 import { existsSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
-import { join, resolve } from "node:path";
+import { basename, dirname, join, resolve } from "node:path";
 import { homedir } from "node:os";
 
 import { metaDir } from "./compat.js";
@@ -21,6 +21,8 @@ import { distillResults, formatExplainResults, formatSearchResults, selectBriefS
 import { archiveDirtyBriefAsset, assetSummaryLine, buildBriefAsset, buildPinAsset, getExportsDir, listDirtyBriefAssets, listMemoryAssets, listPinAssets, pinSummaryLine, saveBriefAsset, savePinAsset, writeExportArtifact } from "./memory-assets.js";
 import { indexAsset, indexPinnedAsset } from "./asset-sync.js";
 import { createComponents, createStoreOnly, expandHome, loadConfig, loadDotEnv, type LocalMemoryConfig } from "./runtime-config.js";
+import { KGStore } from "./kg-store.js";
+import { isKGModeEnabled } from "./kg-extractor.js";
 import {
   formatDedupReasonSummary,
   getDedupSkipRate,
@@ -34,6 +36,9 @@ import {
 } from "./ingest.js";
 import { runDoctor, formatDoctorResults } from "./doctor.js";
 import { persistCaseMemory, persistMemory, persistWorkflowPattern } from "./capture-engine.js";
+import { scanMemoryPromotions, buildPromoteScanDeps, formatPromoteScanResult } from "./memory-promotion.js";
+import { runDream, formatDreamResult, DEFAULT_DREAM_CONFIG } from "./dream-pipeline.js";
+import { listScopesAboveThreshold } from "./activity-counter.js";
 import {
   CaseMemoryInputSchema,
   type CaseMemoryInput,
@@ -47,6 +52,7 @@ import { ConflictStatusSchema } from "./conflict-schema.js";
 import { resolveConflictCandidate } from "./conflict-engine.js";
 import { escalateConflicts } from "./conflict-escalation.js";
 import { ConflictCandidateStore } from "./conflict-store.js";
+import { createAuditLogger } from "./audit-log.js";
 import { formatConflictAudit, formatConflictAuditMarkdown, formatConflictClusters, formatConflictEscalation, formatConflictList, formatConflictRecord, formatConflictResolution } from "./conflict-output.js";
 import { CONFLICT_ATTENTION_LEVELS, parseConflictAttention, summarizeConflictLifecycle } from "./conflict-lifecycle.js";
 import { buildConflictAuditSummary, clusterConflicts, summarizeConflictAdvice } from "./conflict-advisor.js";
@@ -63,49 +69,66 @@ import {
 } from "./workflow-observation-scope-review.js";
 import { collectScopeInventory, formatScopeInventoryReport } from "./scope-inventory.js";
 import { buildRetrievalContext, resolveScopeSelection } from "./scope-policy.js";
+import { createScopeSuggester } from "./scope-suggester.js";
 
 /**
- * Auto-detect Claude Code transcript directory.
- * Scans ~/.claude/projects/ for subdirectories containing .jsonl files.
+ * Auto-detect Claude Code transcript directories.
+ * Scans ~/.claude/projects/ for ALL subdirectories containing .jsonl files.
+ *
+ * CC 按 cwd 编码 project 子目录，凡是不在 ~ 下跑的会话（Codex spawn 的子进程 / cd 到 repo 跑 /
+ * bridge 临时工作目录）会落到 ~/.claude/projects/-XXX/ 别的子目录。旧版只挑 jsonl 最多的根
+ * 目录返回，导致 28+ 个子目录全失声。修复：返回所有有 jsonl 的子目录，调用方循环 ingest。
  */
-function detectCCPath(): string | null {
+function detectCCPath(): string[] {
   const projectsDir = join(homedir(), ".claude", "projects");
-  if (!existsSync(projectsDir)) return null;
+  if (!existsSync(projectsDir)) return [];
   try {
-    const dirs = readdirSync(projectsDir, { withFileTypes: true })
+    return readdirSync(projectsDir, { withFileTypes: true })
       .filter(d => d.isDirectory())
-      .map(d => join(projectsDir, d.name));
-    // Pick the directory with most .jsonl files
-    let best = "";
-    let bestCount = 0;
-    for (const dir of dirs) {
-      const jsonlCount = readdirSync(dir).filter(f => f.endsWith(".jsonl")).length;
-      if (jsonlCount > bestCount) {
-        bestCount = jsonlCount;
-        best = dir;
-      }
-    }
-    return best || null;
+      .map(d => join(projectsDir, d.name))
+      .filter(dir => {
+        try { return readdirSync(dir).some(f => f.endsWith(".jsonl")); }
+        catch { return false; }
+      });
   } catch {
-    return null;
+    return [];
+  }
+}
+
+/**
+ * Pick the CC project subdirectory with the most jsonl files (heuristic: user's primary cwd).
+ * Used by memory source which still expects a single directory.
+ */
+function pickPrimaryCCPath(detected: string[]): string {
+  let best = detected[0];
+  let bestCount = 0;
+  for (const dir of detected) {
+    try {
+      const c = readdirSync(dir).filter(f => f.endsWith(".jsonl")).length;
+      if (c > bestCount) { bestCount = c; best = dir; }
+    } catch { /* skip */ }
   }
+  return best;
 }
 
 /**
  * Resolve "auto" paths in config to actual directories.
+ *
+ * Note: cc 分支只返回第一个 detect 到的目录（fallback），ingest 入口已改为直接调
+ * detectCCPath() 拿全量子目录循环处理。这里保留是为兼容潜在的其它调用方。
  */
 function resolveSourcePath(source: string, key: string): string {
   if (source !== "auto") return expandHome(source);
 
   if (key === "cc") {
     const detected = detectCCPath();
-    if (!detected) throw new Error("Could not auto-detect Claude Code transcript path. Set sources.cc.path in config.json.");
-    return detected;
+    if (detected.length === 0) throw new Error("Could not auto-detect Claude Code transcript path. Set sources.cc.path in config.json.");
+    return pickPrimaryCCPath(detected);
   }
   if (key === "memory") {
-    const ccPath = detectCCPath();
-    if (!ccPath) throw new Error("Could not auto-detect memory path. Set sources.memory.path in config.json.");
-    return join(ccPath, "memory");
+    const detected = detectCCPath();
+    if (detected.length === 0) throw new Error("Could not auto-detect memory path. Set sources.memory.path in config.json.");
+    return join(pickPrimaryCCPath(detected), "memory");
   }
   throw new Error(`Cannot auto-detect path for source "${key}". Set it manually in config.json.`);
 }
@@ -147,7 +170,7 @@ async function runRetrievalView(
   },
 ) {
   const config = loadConfig();
-  const { retriever, profile } = createComponents(config, options.profile);
+  const { retriever, profile, store } = createComponents(config, options.profile);
 
   const limit = parseLimitOption(options.limit, 5, 1, 20);
 
@@ -206,6 +229,17 @@ async function runRetrievalView(
       : formatSearchResults(results, context);
 
   console.log(rendered);
+
+  // P1-A: 显式 scope 0 命中 → 相近 scope 提示打到 stderr(不污染 stdout)
+  if (results.length === 0 && options.scope) {
+    try {
+      const suggest = createScopeSuggester(async () => (await store.stats()).scopeCounts);
+      const suggestions = (await suggest(options.scope)).filter(s => s !== options.scope);
+      if (suggestions.length > 0) {
+        console.error(`⚠️ scope '${options.scope}' 命中 0 条,相近 scope: [${suggestions.join(", ")}]`);
+      }
+    } catch { /* best-effort */ }
+  }
 }
 
 function parseLimitOption(value: string | undefined, fallback: number, min = 1, max = 50): number {
@@ -644,6 +678,28 @@ program
     ].join("\n"));
   });
 
+program
+  .command("promote-scan")
+  .description("扫描 transcript 降级的 profile/preferences evidence，聚类高频高 importance 项晋升回 durable")
+  .requiredOption("--scope <scope>", "要扫描的 scope，如 cc:project:recallnest")
+  .option("--apply", "执行晋升；默认 dry-run 只预览")
+  .option("--min-occurrences <n>", "聚类最小成员数（默认 3）", "3")
+  .option("--min-importance <n>", "聚类最小平均 importance（默认 0.6）", "0.6")
+  .action(async (options) => {
+    const config = loadConfig();
+    const { store, embedder } = createComponents(config);
+    const conflictStore = new ConflictCandidateStore();
+    const deps = buildPromoteScanDeps({ store, embedder, conflictStore });
+    const minOccurrences = Number(options.minOccurrences);
+    const minImportance = Number(options.minImportance);
+    const result = await scanMemoryPromotions(deps, options.scope, {
+      dryRun: !options.apply,
+      ...(Number.isFinite(minOccurrences) ? { minOccurrences } : {}),
+      ...(Number.isFinite(minImportance) ? { minImportance } : {}),
+    });
+    console.log(formatPromoteScanResult(result));
+  });
+
 program
   .command("export <query>")
   .description("导出检索与蒸馏结果到 markdown/json")
@@ -1054,7 +1110,7 @@ program
         continue;
       }
 
-      const record = await persistWorkflowPattern({ store, embedder, conflictStore }, input);
+      const record = await persistWorkflowPattern({ store, embedder, conflictStore, auditLogger: createAuditLogger() }, input);
       existingKeys.add(key);
       stored.push({ title: record.title, id: record.id, scope: record.resolvedScope });
     }
@@ -1130,7 +1186,7 @@ program
         continue;
       }
 
-      const record = await persistCaseMemory({ store, embedder, conflictStore }, input);
+      const record = await persistCaseMemory({ store, embedder, conflictStore, auditLogger: createAuditLogger() }, input);
       existingKeys.add(key);
       stored.push({ title: record.title, id: record.id, scope: record.resolvedScope });
     }
@@ -1208,7 +1264,7 @@ program
         continue;
       }
 
-      const record = await persistMemory({ store, embedder, conflictStore }, input);
+      const record = await persistMemory({ store, embedder, conflictStore, auditLogger: createAuditLogger() }, input);
       existingKeys.add(storeMemoryIdentity({
         category: input.category,
         scope: record.resolvedScope,
@@ -1345,8 +1401,10 @@ program
     console.log(`  ✅ ${config.embedding.model} (${testResult.dimensions}d)`);
 
     // LLM status — respect --no-llm flag
-    const effectiveLlm = options.noLlm ? null : llm;
-    if (options.noLlm) {
+    // commander 把 --no-llm 解析成 options.llm=false（不产生 options.noLlm），对齐 --no-dedup 的取反键写法
+    const noLlm = options.llm === false;
+    const effectiveLlm = noLlm ? null : llm;
+    if (noLlm) {
       console.log("  ⚠️  LLM: 已通过 --no-llm 禁用，原始对话将跳过不存入");
     } else if (llm) {
       const llmTest = await llm.test();
@@ -1376,15 +1434,23 @@ program
     const ingestOpts = { limit, verbose, noDedup, llm: effectiveLlm, recentHours };
 
     // CC Transcripts
+    // CC 按 cwd 编码 project 子目录，所有有 jsonl 的子目录都要 ingest（不只是 jsonl 最多的那个）
     if (source === "all" || source === "cc") {
       console.log("📝 导入 Claude Code 对话...");
       const ccSource = config.sources.cc;
       if (ccSource) {
-        const ccPath = resolveSourcePath(ccSource.path, "cc");
-        const r = await ingestCCTranscripts(store, embedder, ccPath, ingestOpts);
-        results.push(r);
-        console.log(`  ✅ CC: ${formatIngestSummary(r)}`);
-        maybeWarnHighCCDedupRate(r);
+        const ccPaths = ccSource.path === "auto"
+          ? detectCCPath()
+          : [expandHome(ccSource.path)];
+        if (ccPaths.length === 0) {
+          throw new Error("Could not auto-detect Claude Code transcript path. Set sources.cc.path in config.json.");
+        }
+        for (const ccPath of ccPaths) {
+          const r = await ingestCCTranscripts(store, embedder, ccPath, ingestOpts);
+          results.push(r);
+          console.log(`  ✅ CC [${basename(ccPath)}]: ${formatIngestSummary(r)}`);
+          maybeWarnHighCCDedupRate(r);
+        }
       }
     }
 
@@ -1403,7 +1469,7 @@ program
         limit,
         verbose,
         noDedup,
-        llm,
+        llm: effectiveLlm,
         recentHours,
       });
       results.push(r);
@@ -1436,7 +1502,7 @@ program
         const r = await ingestMarkdownFiles(store, embedder, memPath, "memory", {
           verbose,
           noDedup,
-          llm,
+          llm: effectiveLlm,
           recentHours,
         });
         results.push(r);
@@ -1502,6 +1568,70 @@ program
     console.log();
   });
 
+// ─── dream ───────────────────────────────────────────────────────────────────
+// P3 调度化入口:launchd 经 scripts/dream-consolidation.sh 调用本命令,
+// 输出 [[DREAM_STATUS]] ok|skip|blocked 标记供脚本判定(同 weekly-distill 的
+// [[DISTILL_STATUS]] 模式)。dream 是 auto-gc / usageStatus 快照 / consolidation
+// 的唯一生产触发点——没有它们整条维护链就是死代码(2026-06-11 临床重审实锤)。
+
+program
+  .command("dream")
+  .description("运行 dream 离线整固管线 (Orient/Gather/Consolidate/Prune)")
+  .option("--scope <scope>", "目标 scope(前缀或精确)", "cc")
+  .option("--auto", "扫描 activity-counter 中写计数达标的所有 scope，逐个跑 dream（单 scope 失败不阻断其他）")
+  .option("--force", "跳过 min-writes 门槛强制运行")
+  .action(async (options: { scope: string; auto?: boolean; force?: boolean }) => {
+    const config = loadConfig();
+    const { store, embedder, llm } = createComponents(config);
+    // Same activity-stats file the store writes per-scope counts to (beside the LanceDB dir).
+    const activityStatsPath = join(dirname(store.dbPath), "activity-stats.json");
+    // KG evidence for triple-overlap merging — same gate as the MCP server
+    const kgStore = isKGModeEnabled() ? new KGStore({ dbPath: store.dbPath }) : null;
+
+    if (options.auto) {
+      const scopes = listScopesAboveThreshold(DEFAULT_DREAM_CONFIG.minWritesForDream, { statsPath: activityStatsPath });
+      if (scopes.length === 0) {
+        console.log("dream --auto: 无达标 scope（写计数均低于门槛）");
+        console.log("[[DREAM_STATUS]] skip");
+        process.exit(0);
+      }
+      console.log(`dream --auto: ${scopes.length} 个达标 scope → ${scopes.join(", ")}`);
+      let anyFailed = false;
+      for (const scope of scopes) {
+        try {
+          const result = await runDream({ store, llm, embedder, scope, force: Boolean(options.force), activityStatsPath, kgStore });
+          console.log(`[scope=${scope}] ${formatDreamResult(result)}`);
+        } catch (err) {
+          anyFailed = true;
+          // 单 scope 失败不阻断其他 scope
+          console.error(`[scope=${scope}] dream failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+      }
+      console.log(anyFailed ? "[[DREAM_STATUS]] blocked" : "[[DREAM_STATUS]] ok");
+      process.exit(anyFailed ? 1 : 0);
+    }
+
+    try {
+      const result = await runDream({
+        store,
+        llm,
+        embedder,
+        scope: options.scope,
+        force: Boolean(options.force),
+        activityStatsPath,
+        kgStore,
+      });
+
+      console.log(formatDreamResult(result));
+      console.log(result.ran ? "[[DREAM_STATUS]] ok" : "[[DREAM_STATUS]] skip");
+      process.exit(0);
+    } catch (err) {
+      console.error(`dream failed: ${err instanceof Error ? err.message : String(err)}`);
+      console.log("[[DREAM_STATUS]] blocked");
+      process.exit(1);
+    }
+  });
+
 // ─── stats ───────────────────────────────────────────────────────────────────
 
 program
@@ -1723,6 +1853,7 @@ program
   .option("--task <task>", "相关任务")
   .option("--tags <tags>", "逗号分隔 tags")
   .option("--tools <tools>", "逗号分隔 tools")
+  .option("--idempotency-key <key>", "同一请求重试时用于替换旧 observation 的稳定键")
   .option("--json", "输出 JSON")
   .action(async (workflowId, summary, options) => {
     const store = new WorkflowObservationStore();
@@ -1736,6 +1867,7 @@ program
       task: options.task,
       tags: splitCsvOption(options.tags),
       tools: splitCsvOption(options.tools),
+      idempotencyKey: options.idempotencyKey,
     });
     const stored = await store.save(record);
     if (options.json) {

package/src/confidence-tracker.ts

@@ -261,50 +261,68 @@ export function buildContradictPatch(
 // Convenience wrappers (for callers who DO have a store)
 // ---------------------------------------------------------------------------
 
+/** 单写通道端口：读改写经 store.patchMetadata per-id 队列，防并发覆盖。 */
+type ConfidenceStorePort = {
+  patchMetadata(
+    id: string,
+    patchFn: (meta: Record<string, unknown>, entry: MemoryEntry) => Record<string, unknown>,
+    scopeFilter?: string[],
+  ): Promise<MemoryEntry | null>;
+};
+
+function applyConfidencePatch(
+  store: ConfidenceStorePort,
+  entryId: string,
+  scope: string,
+  build: (entry: MemoryEntry) => ConfidencePatch | null,
+): Promise<ConfidenceUpdate | null> {
+  let update: ConfidenceUpdate | null = null;
+  return store
+    .patchMetadata(
+      entryId,
+      (meta, entry) => {
+        const patch = build(entry);
+        if (!patch) return meta;
+        update = patch.update;
+        return patch.metadata;
+      },
+      [scope],
+    )
+    .then(result => (result === null ? null : update));
+}
+
 /**
  * Confirm a memory and write back to store. Convenience wrapper.
  */
 export async function confirmMemory(
-  store: { getById(id: string): Promise<MemoryEntry | null>; update(id: string, data: { metadata: string }, scopes: string[]): Promise<void> },
+  store: ConfidenceStorePort,
   entryId: string,
   scope: string,
 ): Promise<ConfidenceUpdate | null> {
-  const entry = await store.getById(entryId);
-  const patch = buildConfirmPatch(entry);
-  if (!patch) return null;
-  await store.update(entryId, { metadata: JSON.stringify(patch.metadata) }, [scope]);
-  return patch.update;
+  return applyConfidencePatch(store, entryId, scope, entry => buildConfirmPatch(entry));
 }
 
 /**
  * Correct a memory and write back to store. Convenience wrapper.
  */
 export async function correctMemory(
-  store: { getById(id: string): Promise<MemoryEntry | null>; update(id: string, data: { metadata: string }, scopes: string[]): Promise<void> },
+  store: ConfidenceStorePort,
   entryId: string,
   scope: string,
   correctedById?: string,
 ): Promise<ConfidenceUpdate | null> {
-  const entry = await store.getById(entryId);
-  const patch = buildCorrectPatch(entry, correctedById);
-  if (!patch) return null;
-  await store.update(entryId, { metadata: JSON.stringify(patch.metadata) }, [scope]);
-  return patch.update;
+  return applyConfidencePatch(store, entryId, scope, entry => buildCorrectPatch(entry, correctedById));
 }
 
 /**
  * Contradict a memory and write back to store. Convenience wrapper.
  */
 export async function contradictMemory(
-  store: { getById(id: string): Promise<MemoryEntry | null>; update(id: string, data: { metadata: string }, scopes: string[]): Promise<void> },
+  store: ConfidenceStorePort,
   entryId: string,
   scope: string,
 ): Promise<ConfidenceUpdate | null> {
-  const entry = await store.getById(entryId);
-  const patch = buildContradictPatch(entry);
-  if (!patch) return null;
-  await store.update(entryId, { metadata: JSON.stringify(patch.metadata) }, [scope]);
-  return patch.update;
+  return applyConfidencePatch(store, entryId, scope, entry => buildContradictPatch(entry));
 }
 
 // ---------------------------------------------------------------------------