recallnest 2.6.1 → 3.0.1

package/src/mcp-server.ts

@@ -9,7 +9,7 @@
  * Tool tiers:
  * - core: Always exposed (7 tools)
  * - advanced: Exposed by default, includes core (30 tools)
- * - full: All tools including governance (43 tools)
+ * - full: All tools including governance (44 tools)
  *
  * Control: RECALLNEST_MCP_TIER=core|advanced|full
  */
@@ -79,6 +79,7 @@ const TOOL_TIERS: Record<string, ToolTier> = {
   distill_session: "advanced",
   scan_skill_promotions: "governance",
   promote_scan: "governance",
+  promote_synthesis: "governance",
   manage_alias: "governance",
   forget_memory: "advanced",
 

package/src/mcp-tools-advanced.ts

@@ -633,10 +633,11 @@ registerTool(
   "dream",
   "Run a full memory consolidation cycle (Orient, Gather, Consolidate, Prune). Side effect: may archive low-value entries and generate insight memories. Use when memory count is high and you need periodic maintenance.",
   {
-    scope: z.string().min(1).max(160).optional().describe("Scope to consolidate, e.g. 'project:myapp'. Omit to consolidate across all scopes"),
+    scope: z.string().min(1).max(160).optional().describe("Scope to consolidate, e.g. 'project:myapp'. Matched exactly by default — a scope name is treated as itself, not as a prefix family. Omit to consolidate across all scopes"),
     force: z.boolean().default(false).describe("Set to true to force consolidation even if recent write count is below the automatic threshold"),
+    familyMatch: z.boolean().default(false).describe("Set to true to also consolidate child scopes sharing this prefix (e.g. 'memory' would additionally pull in 'memory:pivot'). Off by default: merging sibling scopes into one clustering round mixes unrelated material."),
   },
-  async ({ scope, force }) => {
+  async ({ scope, force, familyMatch }) => {
     const resolvedScope = scope || "project:default";
     const components = getComponents();
     const result = await runDream({
@@ -646,6 +647,10 @@ registerTool(
       scope: resolvedScope,
       force,
       kgStore: getKGStore(),
+      // MCP 调用方给的都是具体 scope 名，family 语义在这里是意外面：
+      // `dream({scope: "memory"})` 会连 `memory:pivot` 一起卷进去（2026-08-16 实测）。
+      // 默认改精确是**行为变更**，要 family 得显式要。
+      scopeMatch: familyMatch ? "family" : "exact",
     });
     return {
       content: [{ type: "text" as const, text: formatDreamResult(result) }],

package/src/mcp-tools-core.ts

@@ -13,6 +13,7 @@ import { buildSessionCheckpointResult } from "./session-engine.js";
 import { formatCheckpointSaved, formatCheckpointSummary, formatResumeContext } from "./session-output.js";
 import { matchesTemporalConstraint, type TemporalConstraint } from "./temporal-parser.js";
 import { buildManagedCheckpointObservation, buildManagedResumeObservation } from "./workflow-observation-managed.js";
+import { PROCESS_READER_ID, recentRecallHits } from "./recall-ledger.js";
 import { buildWorkflowObservationRecord } from "./workflow-observation-engine.js";
 import type { ToolRegistryDeps } from "./mcp-tool-deps.js";
 import type { RetrievalResult } from "./retriever.js";
@@ -65,7 +66,16 @@ export function registerCoreTools(deps: ToolRegistryDeps): void {
 
   async function saveManagedObservation(observation: Parameters<typeof buildWorkflowObservationRecord>[0]): Promise<void> {
     try {
-      const record = buildWorkflowObservationRecord(observation);
+      // P0 join key：managed observation 是最该带它的一类——`resume_context` 本身
+      // 就是「读了一批记忆」的动作，它的成败与那批记忆直接相关。
+      // （api-server 那份同名函数刻意不加：HTTP server 一个进程服务多个客户端，
+      //  「一进程 ≈ 一会话」的前提在那里不成立，加了只会 join 出假配对。）
+      const recalledIds = recentRecallHits();
+      const record = buildWorkflowObservationRecord({
+        readerId: PROCESS_READER_ID,
+        ...(recalledIds.length > 0 ? { recalledIds } : {}),
+        ...(observation as Record<string, unknown>),
+      });
       await workflowObservationStore.save(record);
     } catch (error) {
       console.error("[RecallNest MCP] Failed to persist managed workflow observation:", error);

package/src/mcp-tools-governance.ts

@@ -8,13 +8,20 @@ import { formatConflictAudit, formatConflictClusters, formatConflictEscalation,
 import { ConflictStatusSchema } from "./conflict-schema.js";
 import { ConsolidationEngine, formatConsolidationResult } from "./consolidation-engine.js";
 import { archiveDirtyBriefAsset, listDirtyBriefAssets } from "./memory-assets.js";
-import { scanMemoryPromotions, buildPromoteScanDeps, formatPromoteScanResult } from "./memory-promotion.js";
+import {
+  scanMemoryPromotions,
+  scanSynthesisPromotions,
+  buildPromoteScanDeps,
+  formatPromoteScanResult,
+  formatSynthesisPromoteResult,
+} from "./memory-promotion.js";
 import { aliasMapFilePath, expandQuery, explainUserAliases, listUserAliases, removeUserAlias, upsertUserAlias } from "./query-expander.js";
 import { recordSkillOutcome } from "./skill-engine.js";
 import { scanForPromotions, formatPromotionResult } from "./skill-promotion.js";
 import { buildWorkflowEvidence, buildWorkflowObservationRecord, inspectWorkflowDashboard, inspectWorkflowHealth } from "./workflow-observation-engine.js";
 import { formatWorkflowEvidencePack, formatWorkflowHealthDashboard, formatWorkflowHealthReport, formatWorkflowObservationSaved } from "./workflow-observation-output.js";
 import { WorkflowObservationOutcomeSchema } from "./workflow-observation-schema.js";
+import { PROCESS_READER_ID, recentRecallHits } from "./recall-ledger.js";
 import type { ToolRegistryDeps } from "./mcp-tool-deps.js";
 import { withLock } from "./distill-lock.js";
 
@@ -36,8 +43,14 @@ registerTool(
     tools: z.array(z.string().min(1).max(60)).max(6).default([]).describe("Optional tools involved"),
     skillId: z.string().min(1).max(128).optional().describe("Optional skill id to bump. When present and outcome is success, the skill's successCount increments; otherwise failureCount increments. Missing/corrupt skills are skipped silently (does not block observation write)."),
     idempotencyKey: z.string().min(1).max(160).optional().describe("Optional stable request key; repeated saves with the same key replace the prior observation"),
+    recalledIds: z.array(z.string().min(1).max(128)).max(64).optional().describe("Optional memory ids this task actually used. Omit to auto-fill from what this session retrieved in the last 30 minutes — that auto-fill is what makes (memory, outcome) value back-propagation possible."),
   },
-  async ({ workflowId, outcome, summary, scope, source, signal, task, tags, tools, skillId, idempotencyKey }) => {
+  async ({ workflowId, outcome, summary, scope, source, signal, task, tags, tools, skillId, idempotencyKey, recalledIds }) => {
+    // P0 join key：不传就用本进程的检索账本自动补。这一步是价值回溯的前提——
+    // 少了它，库里就只剩「有结果没参与者」和「有参与者没结果」两堆对不上的数据。
+    const resolvedRecalledIds = recalledIds && recalledIds.length > 0
+      ? recalledIds
+      : recentRecallHits();
     const record = buildWorkflowObservationRecord({
       workflowId,
       outcome,
@@ -50,6 +63,8 @@ registerTool(
       tools,
       skillId,
       idempotencyKey,
+      readerId: PROCESS_READER_ID,
+      ...(resolvedRecalledIds.length > 0 ? { recalledIds: resolvedRecalledIds } : {}),
     });
     const stored = await workflowObservationStore.save(record);
 
@@ -332,6 +347,7 @@ registerTool(
         getById: store.getById.bind(store),
         vectorSearch: store.vectorSearch.bind(store),
         update: async () => null, // no-op in dry-run
+        patchMetadataBatch: async () => 0, // no-op in dry-run（3a 批量写通道，2026-08-14）
       };
       const engine = new ConsolidationEngine(readOnlyStore, { clusterThreshold, mergeThreshold, maxEntriesPerRun: maxEntries }, getKGStore());
       const result = await engine.run(scope);
@@ -377,11 +393,13 @@ registerTool(
   {
     scope: z.string().min(1).max(160).describe("Project scope to scan for promotion candidates"),
     minOccurrences: z.number().min(2).max(20).default(3).describe("Minimum similar cases to trigger a promotion suggestion"),
+    minDistinctSources: z.number().min(1).max(10).default(2).describe("How many DIFFERENT sources (episodes) a cluster must span. Counting similar entries is not the same as counting distinct experiences — the same pothole hit three times is one experience, not a rule. Set 1 to disable this check. Abstains (never rejects) when the entries carry no source pointer."),
   },
-  async ({ scope, minOccurrences }) => {
+  async ({ scope, minOccurrences, minDistinctSources }) => {
     const { store } = getComponents();
     const result = await scanForPromotions(store, scope, {
       minCaseOccurrences: minOccurrences,
+      minDistinctSources,
     });
 
     return {
@@ -472,4 +490,28 @@ registerTool(
     };
   },
 );
+
+registerTool(
+  "promote_synthesis",
+  "Scan dream-synthesized conclusions (cluster insights and cross-memory patterns, which are written on the evidence layer and therefore excluded from stable memory) and promote the well-supported ones into a durable copy. Eligibility comes from the conclusion's own validated evidence set, not from repetition. Default dry-run (no writes); when dryRun=false it writes durable entries through the same promote path as promote_memory, so canonicalKey dedup makes re-runs a revision rather than a duplicate. The synthesized row itself is never modified.",
+  {
+    scope: z.string().min(1).max(160).describe("Scope to scan, e.g. memory"),
+    dryRun: z.boolean().default(true).describe("When true (default), only report candidates without writing"),
+    minDistinctEvidence: z.number().int().min(2).max(20).default(2).describe("Min distinct, still-active evidence memories behind the conclusion"),
+    minImportance: z.number().min(0).max(1).default(0.6).describe("Min importance of the synthesized conclusion itself"),
+  },
+  async ({ scope, dryRun, minDistinctEvidence, minImportance }) => {
+    const { store, embedder } = getComponents();
+    const kgExtractor = getKGExtractor();
+    const deps = buildPromoteScanDeps({ store, embedder, conflictStore, kgExtractor });
+    const result = await scanSynthesisPromotions(deps, scope, { dryRun, minDistinctEvidence, minImportance });
+
+    return {
+      content: [{
+        type: "text" as const,
+        text: formatSynthesisPromoteResult(result),
+      }],
+    };
+  },
+);
 }

package/src/memory-evolution.ts

@@ -115,6 +115,22 @@ export function patchEvolution(
   return JSON.stringify(parsed);
 }
 
+/**
+ * patchEvolution 的对象版：给 patchMetadataBatch 的 patchFn 用（那条通道进出都是
+ * 已解析的 metadata 对象，不该为了复用字符串版而反复 stringify/parse）。
+ * 就地修改并返回同一对象，语义与 patchEvolution 一致（浅合并 evolution 子对象）。
+ */
+export function patchEvolutionOnMeta(
+  meta: Record<string, unknown>,
+  patch: Partial<EvolutionMetadata>,
+): Record<string, unknown> {
+  const existing = meta.evolution !== null && typeof meta.evolution === "object" && !Array.isArray(meta.evolution)
+    ? (meta.evolution as Partial<EvolutionMetadata>)
+    : undefined;
+  meta.evolution = { ...existing, ...patch };
+  return meta;
+}
+
 // ---------------------------------------------------------------------------
 // Predicates
 // ---------------------------------------------------------------------------

package/src/memory-output.ts

@@ -1,3 +1,4 @@
+import { formatAgeLabel } from "./age-label.js";
 import type { MemoryEntry } from "./store.js";
 import type { RetrievalResult } from "./retriever.js";
 import type { RetrievalProfileName } from "./retrieval-profiles.js";
@@ -41,6 +42,7 @@ export interface DistilledEvidence {
   source: string;
   scope: string;
   date: string;
+  age: string;
   retrievalPath: string;
   snippet: string;
 }
@@ -82,6 +84,37 @@ function getTierLabel(result: RetrievalResult): string {
   return String(meta.tier || "peripheral");
 }
 
+/**
+ * 所在 session 里有用户贴图时，多给一行提示。
+ *
+ * 图本体不在库里，正文里通常也没有对图的描述——这一行是唯一能让读到这条
+ * 记忆的人意识到「这附近还有图没看」的信号。判断值不值得看，回 Deja 按
+ * session 读原文。
+ *
+ * ⚠️ 这是 **session 级**标记，不是「本条记忆有图」：同一个 session 切出来
+ * 的每条记忆都带同一个数，图未必跟眼前这条有关。粒度换覆盖，明知而为——
+ * 图所在的那一轮常因正文太短根本没进库，只有盖到同 session 的其他轮次上
+ * 才可能被搜到。
+ *
+ * 无图时返回 null，调用方据此不输出这一行——不给无图记忆添噪音。
+ */
+function formatSessionImages(result: RetrievalResult): string | null {
+  const meta = parseMetadata(result.entry);
+  const own = typeof meta.sessionImages === "number" ? meta.sessionImages : 0;
+  const tool = typeof meta.sessionToolImages === "number" ? meta.sessionToolImages : 0;
+  if (own <= 0 && tool <= 0) return null;
+
+  // 两类分开报，因为它们答的是不同的问题：找「我发过的那张截图」看前者，
+  // 回溯「我当时生成的图 / 那个页面当时的样子」看后者。
+  // 措辞用英文，与同一块里的 prov / fresh 行保持一致（这个输出面是英文的）。
+  const parts: string[] = [];
+  if (own > 0) parts.push(`${own} user-pasted`);
+  if (tool > 0) parts.push(`${tool} agent-made`);
+  const sess = typeof meta.sessionId === "string" ? meta.sessionId.slice(0, 8) : "?";
+
+  return `${parts.join(", ")} in this session · read sess=${sess}`;
+}
+
 function getProvenanceSummary(result: RetrievalResult): string {
   const provenance = extractMemoryProvenance({
     scope: result.entry.scope,
@@ -332,6 +365,7 @@ function buildSearchRow(index: number, query: string, result: RetrievalResult):
     getTierLabel(result).padEnd(10),
     getSourceLabel(result).padEnd(7),
     getDateLabel(result.entry.timestamp),
+    formatAgeLabel(result.entry.timestamp).padEnd(5),
     getRetrievalPath(result).padEnd(20),
     getFileLabel(result),
     cleanSnippet(pickBestSnippet(query, result.entry.text), 120),
@@ -374,14 +408,16 @@ export function formatFullResults(
     `Profile : ${context.profile}`,
     `Hits    : ${results.length}`,
     "",
-    "#  ID       Score Category     Tier       Source  Date       Retrieval Path       File / Snippet",
-    "-- -------- ----- ------------ ---------- ------- ---------- -------------------- --------------",
+    "#  ID       Score Category     Tier       Source  Date       Age   Retrieval Path       File / Snippet",
+    "-- -------- ----- ------------ ---------- ------- ---------- ----- -------------------- --------------",
   ];
 
   for (let i = 0; i < results.length; i++) {
     const row = buildSearchRow(i, context.query, results[i]);
-    lines.push(`${row[0]} ${row[1]} ${row[2]} ${row[3]} ${row[4]} ${row[5]} ${row[6]} ${row[7]} ${row[8]} | ${row[9]}`);
+    lines.push(`${row[0]} ${row[1]} ${row[2]} ${row[3]} ${row[4]} ${row[5]} ${row[6]} ${row[7]} ${row[8]} ${row[9]} | ${row[10]}`);
     lines.push(`   prov : ${getProvenanceSummary(results[i])}`);
+    const imgs = formatSessionImages(results[i]);
+    if (imgs) lines.push(`   imgs : ${imgs}`);
     // Full mode: append metadata details
     const meta = parseMetadata(results[i].entry);
     const evolution = typeof meta.evolutionStatus === "string" ? meta.evolutionStatus : "-";
@@ -424,14 +460,16 @@ export function formatSearchResults(
     `Profile : ${context.profile}`,
     `Hits    : ${results.length}`,
     "",
-    "#  ID       Score Category     Tier       Source  Date       Retrieval Path       File / Snippet",
-    "-- -------- ----- ------------ ---------- ------- ---------- -------------------- --------------",
+    "#  ID       Score Category     Tier       Source  Date       Age   Retrieval Path       File / Snippet",
+    "-- -------- ----- ------------ ---------- ------- ---------- ----- -------------------- --------------",
   ];
 
   for (let i = 0; i < results.length; i++) {
     const row = buildSearchRow(i, context.query, results[i]);
-    lines.push(`${row[0]} ${row[1]} ${row[2]} ${row[3]} ${row[4]} ${row[5]} ${row[6]} ${row[7]} ${row[8]} | ${row[9]}`);
+    lines.push(`${row[0]} ${row[1]} ${row[2]} ${row[3]} ${row[4]} ${row[5]} ${row[6]} ${row[7]} ${row[8]} ${row[9]} | ${row[10]}`);
     lines.push(`   prov : ${getProvenanceSummary(results[i])}`);
+    const imgs = formatSessionImages(results[i]);
+    if (imgs) lines.push(`   imgs : ${imgs}`);
     // Freshness: only shown for memories that declared dependsOn (opt-in, cheap check).
     const fresh = evaluateEntryFreshness(results[i].entry.metadata, freshnessCache);
     if (fresh) lines.push(`   fresh: ${fresh}`);
@@ -529,7 +567,7 @@ export function formatExplainResults(
     const session = getSessionLabel(result);
     const why = buildWhyMatched(context.query, result);
 
-    lines.push(`${i + 1}. ${result.entry.id.slice(0, 8)} | ${score} | ${getSourceLabel(result)} | ${getDateLabel(result.entry.timestamp)}`);
+    lines.push(`${i + 1}. ${result.entry.id.slice(0, 8)} | ${score} | ${getSourceLabel(result)} | ${getDateLabel(result.entry.timestamp)} (${formatAgeLabel(result.entry.timestamp)})`);
     lines.push(`   category: ${getCategoryLabel(result)}`);
     lines.push(`   tier    : ${getTierLabel(result)}`);
     lines.push(`   path    : ${retrieval}`);
@@ -592,6 +630,7 @@ export function summarizeResults(
       source: getSourceLabel(result),
       scope: result.entry.scope,
       date: getDateLabel(result.entry.timestamp),
+      age: formatAgeLabel(result.entry.timestamp),
       retrievalPath: getRetrievalPath(result),
       snippet: pickBestSnippet(context.query, normalizeRecallText(result)),
     });
@@ -654,7 +693,7 @@ export function distillResults(
 
   lines.push("", "Evidence");
   summary.evidence.forEach((item, index) => {
-    lines.push(`${index + 1}. ${item.source} | ${item.date} | ${item.retrievalPath} | ${item.snippet}`);
+    lines.push(`${index + 1}. ${item.source} | ${item.date} (${item.age}) | ${item.retrievalPath} | ${item.snippet}`);
   });
 
   lines.push("", "Reusable Memory Candidates");

package/src/memory-promotion.ts

@@ -244,3 +244,283 @@ export function formatPromoteScanResult(result: PromoteScanResult): string {
   }
   return lines.join("\n");
 }
+
+// ---------------------------------------------------------------------------
+// Synthesis promotion: evidence → durable for dream-synthesized conclusions
+// ---------------------------------------------------------------------------
+
+/**
+ * The layering this implements is "evidence retained → current projection → eligible for
+ * recall → ranked result". `scanMemoryPromotions` above covers one road into the durable
+ * layer: transcript-downgraded facts that recur often enough to be worth keeping. This
+ * covers the other one, which had no road at all.
+ *
+ * `buildDerivedBoundary` (consolidation-engine) stamps every dream-synthesized insight and
+ * cross-memory pattern as `layer: "evidence"`, deliberately — a model re-reading its own
+ * memories is a lead to its sources, not authority over them. But
+ * `shouldUseStableMemoryResult` refuses anything on the evidence layer, so the consequence
+ * was absolute: **a synthesized conclusion could never take part in stable memory, no
+ * matter how well supported it was.** The synthesis contract added in `efdb043` made those
+ * conclusions checkable (a verdict may abstain, and evidence ids are validated against the
+ * cluster) without giving them anywhere to go.
+ *
+ * ## Why the gate is not the one above
+ *
+ * The recurrence gate — "the same fact showed up in N separate places" — is the wrong
+ * question to ask a synthesis. A synthesis is *already* a cross-entry aggregate; demanding
+ * that the dream produce the same conclusion three times would be counting one thing three
+ * ways. What it carries instead is its own support set, so that is what gets checked:
+ * enough distinct sources, still live, under a contract version that validated them.
+ *
+ * ## What promotion does and does not touch
+ *
+ * The synthesis row is never modified — archive-first, and the evidence has to stay
+ * readable as evidence. Promotion writes a *separate* durable entry through the same
+ * `promoteMemory` path everything else uses, so it inherits canonicalKey dedup (re-running
+ * revises rather than duplicating), secret redaction, and `promotedFrom` provenance
+ * pointing back at the synthesis. The durable copy is what later recall can lean on.
+ */
+
+/** Synthesis contract version required before a derived row is eligible. */
+export const MIN_PROMOTABLE_CONTRACT_VERSION = 2;
+
+export interface SynthesisPromoteScanConfig {
+  /** Min distinct, still-live evidence memories behind the conclusion (default 2). */
+  minDistinctEvidence: number;
+  /** Min importance of the synthesis itself (default 0.6). */
+  minImportance: number;
+  /** Max derived rows fetched from the store (default 2000). */
+  listLimit: number;
+  /** When true (default), report candidates without writing anything. */
+  dryRun: boolean;
+}
+
+export const DEFAULT_SYNTHESIS_PROMOTE_CONFIG: SynthesisPromoteScanConfig = {
+  minDistinctEvidence: 2,
+  minImportance: 0.6,
+  listLimit: 2000,
+  dryRun: true,
+};
+
+/** Why an otherwise-derived row was not promoted. Reported, never silent. */
+export type SynthesisSkipReason =
+  | "pre_contract"
+  | "already_promoted"
+  | "evidence_unresolvable"
+  | "too_few_distinct_evidence"
+  | "below_importance";
+
+export interface SynthesisPromoteCandidate {
+  seedId: string;
+  seedText: string;
+  /** Durable category the conclusion is promoted into (from boundary.originalCategory). */
+  category: DurableMemoryCategory;
+  contractVersion: number;
+  /** Distinct evidence ids that are still active in the store. */
+  evidenceIds: string[];
+  importance: number;
+  /** Filled after a real promotion; null in dryRun mode. */
+  promoted: StoredPromotedMemoryRecord | null;
+}
+
+export interface SynthesisPromoteScanResult {
+  candidates: SynthesisPromoteCandidate[];
+  /** Derived rows examined (carrying a distillation boundary), before gating. */
+  scannedSyntheses: number;
+  /** Per-reason counts for everything examined and rejected. */
+  skipped: Record<SynthesisSkipReason, number>;
+  promoted: number;
+  dryRun: boolean;
+}
+
+export interface SynthesisPromoteScanDeps {
+  store: Pick<MemoryStore, "list"> & {
+    getById?(id: string): Promise<MemoryEntry | null>;
+    get?(id: string): Promise<MemoryEntry | null>;
+  };
+  promote: PromoteFn;
+}
+
+function readContractVersion(metadata?: string): number | null {
+  const parsed = parseMetadataObject(metadata);
+  const raw = parsed?.synthesis_contract;
+  return typeof raw === "number" && Number.isFinite(raw) ? raw : null;
+}
+
+/** Ids the model itself named as support, deduplicated and order-preserved. */
+function readEvidenceIds(metadata?: string): string[] | null {
+  const parsed = parseMetadataObject(metadata);
+  const raw = parsed?.evidenceMemories;
+  if (!Array.isArray(raw)) return null;
+  const ids = raw.filter((id): id is string => typeof id === "string" && id.trim().length > 0);
+  return [...new Set(ids)];
+}
+
+/** A dream-synthesized derivative — evidence layer written by the distillation path. */
+function isSynthesisRow(entry: MemoryEntry): boolean {
+  const boundary = extractBoundaryMetadata(entry.metadata);
+  return boundary?.layer === "evidence" && boundary.authority === "distillation";
+}
+
+async function loadEntry(
+  deps: SynthesisPromoteScanDeps,
+  id: string,
+): Promise<MemoryEntry | null> {
+  if (deps.store.getById) return deps.store.getById(id);
+  if (deps.store.get) return deps.store.get(id);
+  return null;
+}
+
+/**
+ * Find synthesized conclusions whose own support set justifies a durable copy.
+ *
+ * Abstains rather than guesses: a row whose evidence ids cannot be resolved at all is
+ * counted under `evidence_unresolvable` and left alone. That mirrors the abstention path
+ * in `scanForPromotions`' cross-source check — when the provenance needed for the judgement
+ * is missing, not judging is the correct answer, not judging leniently.
+ */
+export async function scanSynthesisPromotions(
+  deps: SynthesisPromoteScanDeps,
+  scope: string,
+  config?: Partial<SynthesisPromoteScanConfig>,
+): Promise<SynthesisPromoteScanResult> {
+  const cfg: SynthesisPromoteScanConfig = { ...DEFAULT_SYNTHESIS_PROMOTE_CONFIG, ...config };
+
+  const result: SynthesisPromoteScanResult = {
+    candidates: [],
+    scannedSyntheses: 0,
+    skipped: {
+      pre_contract: 0,
+      already_promoted: 0,
+      evidence_unresolvable: 0,
+      too_few_distinct_evidence: 0,
+      below_importance: 0,
+    },
+    promoted: 0,
+    dryRun: cfg.dryRun,
+  };
+
+  // Synthesized insights take the cluster's majority category, so this cannot be narrowed
+  // to one category the way the downgraded-evidence scan is.
+  const rows = await deps.store.list([scope], undefined, cfg.listLimit, 0);
+  const syntheses = rows.filter((e) => isActiveMemory(e.metadata) && isSynthesisRow(e));
+  result.scannedSyntheses = syntheses.length;
+
+  for (const entry of syntheses) {
+    const contractVersion = readContractVersion(entry.metadata);
+    // Derivatives written before the synthesis contract were never validated — the whole
+    // point of the version stamp is that "which code produced this" stops being a guess.
+    if (contractVersion === null || contractVersion < MIN_PROMOTABLE_CONTRACT_VERSION) {
+      result.skipped.pre_contract += 1;
+      continue;
+    }
+
+    if (hasPromotedToMarker(entry.metadata)) {
+      result.skipped.already_promoted += 1;
+      continue;
+    }
+
+    const declared = readEvidenceIds(entry.metadata);
+    if (declared === null || declared.length === 0) {
+      result.skipped.evidence_unresolvable += 1;
+      continue;
+    }
+
+    // Evidence that has since been superseded or archived no longer supports anything.
+    const resolved: string[] = [];
+    let lookupFailed = false;
+    for (const id of declared) {
+      const source = await loadEntry(deps, id);
+      if (source === null) {
+        lookupFailed = true;
+        continue;
+      }
+      if (isActiveMemory(source.metadata)) resolved.push(id);
+    }
+
+    // Cannot see any of the support: abstain instead of promoting on an unchecked claim.
+    if (resolved.length === 0 && lookupFailed) {
+      result.skipped.evidence_unresolvable += 1;
+      continue;
+    }
+
+    if (resolved.length < cfg.minDistinctEvidence) {
+      result.skipped.too_few_distinct_evidence += 1;
+      continue;
+    }
+
+    if ((entry.importance ?? 0) < cfg.minImportance) {
+      result.skipped.below_importance += 1;
+      continue;
+    }
+
+    const boundary = extractBoundaryMetadata(entry.metadata);
+    const category = (boundary?.originalCategory ?? "events") as DurableMemoryCategory;
+
+    const candidate: SynthesisPromoteCandidate = {
+      seedId: entry.id,
+      seedText: entry.text,
+      category,
+      contractVersion,
+      evidenceIds: resolved,
+      importance: entry.importance,
+      promoted: null,
+    };
+
+    if (!cfg.dryRun) {
+      candidate.promoted = await deps.promote({
+        memoryId: entry.id,
+        category,
+        scope,
+        importance: entry.importance,
+      });
+      result.promoted += 1;
+    }
+
+    result.candidates.push(candidate);
+  }
+
+  return result;
+}
+
+export function formatSynthesisPromoteResult(result: SynthesisPromoteScanResult): string {
+  const skippedTotal = Object.values(result.skipped).reduce((a, b) => a + b, 0);
+  const lines = [
+    `Synthesis promote-scan: ${result.scannedSyntheses} synthesized conclusion(s) examined, ${skippedTotal} skipped.`,
+  ];
+
+  // Always print the rejection breakdown: a scan that promotes nothing should still say
+  // why, or "nothing found" and "everything filtered" look the same from outside.
+  const reasons = (Object.entries(result.skipped) as Array<[SynthesisSkipReason, number]>)
+    .filter(([, n]) => n > 0)
+    .map(([reason, n]) => `${reason}=${n}`);
+  if (reasons.length > 0) lines.push(`Skipped: ${reasons.join(", ")}`);
+
+  if (result.candidates.length === 0) {
+    lines.push("No promotion candidates found.");
+    return lines.join("\n");
+  }
+
+  lines.push(
+    result.dryRun
+      ? `Found ${result.candidates.length} candidate(s) (dry-run, nothing written):\n`
+      : `Promoted ${result.promoted} of ${result.candidates.length} candidate(s):\n`,
+  );
+
+  for (const [i, c] of result.candidates.entries()) {
+    lines.push(`### ${i + 1}. [${c.category}] ${c.seedText.split("\n")[0].slice(0, 80)}`);
+    lines.push(
+      `Evidence: ${c.evidenceIds.length} distinct (${c.evidenceIds.map((id) => id.slice(0, 8)).join(", ")})`,
+    );
+    lines.push(`Contract: v${c.contractVersion} | importance: ${c.importance.toFixed(2)} | seed: ${c.seedId.slice(0, 8)}`);
+    if (c.promoted) {
+      lines.push(
+        c.promoted.disposition === "conflict" && c.promoted.conflictId
+          ? `-> conflict ${c.promoted.conflictId.slice(0, 8)} (manual review)`
+          : `-> durable ${c.promoted.id.slice(0, 8)} (${c.promoted.disposition}, key ${c.promoted.canonicalKey})`,
+      );
+    }
+    lines.push("");
+  }
+  return lines.join("\n");
+}

package/src/memory-store-port.ts

@@ -1,4 +1,5 @@
 import type { MemoryEntry, MemorySearchResult } from "./store.js";
+import type { ScopeMatchMode } from "./scope-policy.js";
 
 export interface MemoryStoreStats {
   totalCount: number;
@@ -18,8 +19,16 @@ export type MemoryStoreUpdate = {
 };
 
 export interface MemoryStorePort {
-  stats(scopeFilter?: string[]): Promise<MemoryStoreStats>;
-  list(scopeFilter?: string[], category?: string, limit?: number, offset?: number): Promise<MemoryEntry[]>;
+  /** scopeMatch 见 scope-policy.ts 的 ScopeMatchMode：缺省 "family"（历史行为，
+   *  无冒号 scope 按前缀），"exact" 由调用方在"我给的是一个具体 scope 名"时显式声明。 */
+  stats(scopeFilter?: string[], scopeMatch?: ScopeMatchMode): Promise<MemoryStoreStats>;
+  list(
+    scopeFilter?: string[],
+    category?: string,
+    limit?: number,
+    offset?: number,
+    scopeMatch?: ScopeMatchMode,
+  ): Promise<MemoryEntry[]>;
   /** 按 id 批量取真实向量。list()/listPage() 为性能恒返回 vector:[]（假空数组），
    *  任何要做相似度/聚类的消费者必须用这个回填——promote_scan 与 dream 3b 都栽过同一坑。 */
   getVectors(ids: string[]): Promise<Map<string, number[]>>;
@@ -42,5 +51,25 @@ export interface MemoryStorePort {
     patchFn: (meta: Record<string, unknown>, entry: MemoryEntry) => Record<string, unknown>,
     scopeFilter?: string[],
   ): Promise<MemoryEntry | null>;
-  vectorSearch(vector: number[], limit?: number, minScore?: number, scopeFilter?: string[]): Promise<MemorySearchResult[]>;
+  /** metadata 批量读改写：单锁单 commit 写一批行（≤200/批）。patchFn 在锁内以库中
+   *  最新行为底座、按数组序依次应用（同批闭包可传递决策）。单条失败跳过不炸整批，
+   *  返回成功写入数。dream 3a/3b/auto-gc 的写放大治理入口（2026-08-14）。 */
+  patchMetadataBatch(
+    patches: Array<{
+      id: string;
+      patchFn: (meta: Record<string, unknown>, entry: MemoryEntry) => Record<string, unknown>;
+    }>,
+    scopeFilter?: string[],
+  ): Promise<number>;
+  /** Remove version-group metadata from groups with only one surviving member.
+   *  Implementations should take one membership snapshot and apply repairs under
+   *  the same write lock so concurrent group creation cannot invalidate the plan. */
+  repairSingletonVersionGroups(): Promise<number>;
+  vectorSearch(
+    vector: number[],
+    limit?: number,
+    minScore?: number,
+    scopeFilter?: string[],
+    scopeMatch?: ScopeMatchMode,
+  ): Promise<MemorySearchResult[]>;
 }