add-coder 0.3.34 → 0.3.35

package/templates/core/scripts/mcp-server/shared/memory/domain/state-machine.ts

@@ -0,0 +1,90 @@
+/*
+ * Memory 生命周期状态机（Plan §5）
+ *
+ * CANDIDATE → PENDING → ACTIVE → STALE → SUPERSEDED → ARCHIVED
+ *     │          │         │        └──────────────→ ARCHIVED
+ *     └──────────┴─────────┴──────────────────────→ REJECTED
+ *
+ * 首版默认只允许人工或显式治理调用激活（approve 的强制校验在此表达）。
+ */
+import { MemoryError } from "./errors.js"
+
+export type MemoryStatus =
+  | "CANDIDATE" | "PENDING" | "ACTIVE" | "STALE"
+  | "SUPERSEDED" | "REJECTED" | "ARCHIVED"
+
+export type MemoryAction =
+  | "propose" | "submit_review" | "approve" | "reject"
+  | "mark_stale" | "supersede" | "archive" | "restore"
+
+interface Transition {
+  from: MemoryStatus[]
+  to: MemoryStatus
+}
+
+/** 迁移表：propose 是创建语义（无 from），其余均为状态到状态 */
+export const TRANSITIONS: Record<MemoryAction, Transition> = {
+  propose:       { from: [],                              to: "CANDIDATE" },
+  submit_review: { from: ["CANDIDATE"],                   to: "PENDING" },
+  approve:       { from: ["PENDING", "CANDIDATE"],        to: "ACTIVE" },
+  reject:        { from: ["CANDIDATE", "PENDING"],        to: "REJECTED" },
+  mark_stale:    { from: ["ACTIVE"],                      to: "STALE" },
+  supersede:     { from: ["ACTIVE", "STALE"],             to: "SUPERSEDED" },
+  archive:       { from: ["ACTIVE", "STALE", "SUPERSEDED"], to: "ARCHIVED" },
+  restore:       { from: ["ARCHIVED", "REJECTED"],        to: "CANDIDATE" },
+}
+
+/** approve / supersede 的不变量校验输入（DB 查询结果由调用方传入，领域层保持纯函数） */
+export interface TransitionContext {
+  evidenceCount?: number
+  approvedBy?: string | null
+  approvedAt?: Date | null
+  /** supersede 专用：新记忆 id 与 repository/scope 兼容性判定结果 */
+  supersededById?: string | null
+  supersessionCompatible?: boolean
+}
+
+export interface TransitionResult {
+  from: MemoryStatus
+  to: MemoryStatus
+  action: MemoryAction
+}
+
+/** 判定迁移是否合法；非法时抛 MemoryError（ERR_ILLEGAL_TRANSITION / ERR_EVIDENCE_REQUIRED / ...） */
+export function assertTransition(
+  current: MemoryStatus,
+  action: MemoryAction,
+  ctx: TransitionContext = {},
+): TransitionResult {
+  const t = TRANSITIONS[action]
+  if (action === "propose") {
+    // 创建语义：不与现有状态冲突（由调用方决定新建或合并）
+    return { from: current, to: t.to, action }
+  }
+  if (!t.from.includes(current)) {
+    throw new MemoryError("ERR_ILLEGAL_TRANSITION", `${current} --${action}--> ${t.to} 不允许（允许起点: ${t.from.join("/")}）`)
+  }
+  if (action === "approve") {
+    if (!ctx.evidenceCount || ctx.evidenceCount < 1) {
+      throw new MemoryError("ERR_EVIDENCE_REQUIRED")
+    }
+    if (!ctx.approvedBy) {
+      throw new MemoryError("ERR_APPROVAL_REQUIRED", "缺少 approvedBy")
+    }
+  }
+  if (action === "supersede") {
+    if (!ctx.supersededById) {
+      throw new MemoryError("ERR_SUPERSESSION_INVALID", "缺少 supersededById")
+    }
+    if (ctx.supersessionCompatible === false) {
+      throw new MemoryError("ERR_SUPERSESSION_INVALID", "新旧 Memory 的 repository/scope 不兼容")
+    }
+  }
+  return { from: current, to: t.to, action }
+}
+
+/** 默认召回允许的状态集合（Plan §7.1：默认排除 CANDIDATE/PENDING/REJECTED/ARCHIVED/SUPERSEDED/过期项） */
+export const DEFAULT_RECALL_STATUSES: readonly MemoryStatus[] = ["ACTIVE"]
+
+/** 显式诊断模式额外放行 STALE（带警告） */
+export const DIAGNOSTIC_RECALL_STATUSES: readonly MemoryStatus[] = ["ACTIVE", "STALE"]

package/templates/core/scripts/mcp-server/shared/memory/embedding/index.ts

@@ -0,0 +1,117 @@
+/*
+ * Embedding 抽象与降级（Plan §8.1/§8.4，Spec §9）
+ *
+ * 提供者：none（默认，显式不可用）/ local-onnx / openai-compatible（Phase 5 轮 3）。
+ * Vector adapter：pgvector / sqlite-vec（retrieval/vector/），能力检测失败即降级。
+ * 契约：记忆系统任何环节不得因 embedding 缺失而阻塞 Gate（FTS-only 合法降级）。
+ */
+import { MemoryError } from "../domain/errors.js"
+import type { ComponentHealth, RankedId, RecallFilter } from "../retrieval/types.js"
+
+export interface EmbeddingProvider {
+  readonly id: string // "none" | "local-onnx" | "openai-compatible" | "custom"
+  readonly dimension: number
+  embed(texts: string[]): Promise<number[][]>
+  health(): Promise<ComponentHealth>
+}
+
+export interface VectorSearchAdapter {
+  search(vector: number[], filter: RecallFilter, limit: number): Promise<RankedId[]>
+  upsert(memoryId: string, vector: number[], model: string): Promise<void>
+  health(): Promise<ComponentHealth>
+}
+
+/** 首版唯一 provider：显式不可用。调用方据此走 FTS-only 并标注 degradedMode */
+export function createNoneEmbeddingProvider(): EmbeddingProvider {
+  return {
+    id: "none",
+    dimension: 0,
+    embed: (): Promise<number[][]> => Promise.reject(new MemoryError("ERR_EMBEDDING_DISABLED")),
+    health: (): Promise<ComponentHealth> =>
+      Promise.resolve({ component: "embedding", status: "disabled", detail: "EmbeddingProvider=none（首版定案，FTS-only）" }),
+  }
+}
+
+/** Vector adapter capability 存根：health 报告 unavailable，search/upsert 拒绝 */
+export function createUnavailableVectorAdapter(): VectorSearchAdapter {
+  return {
+    search: (): Promise<RankedId[]> =>
+      Promise.reject(new MemoryError("ERR_EMBEDDING_DISABLED", "VectorSearchAdapter 未配置（Phase 5 接入）")),
+    upsert: (): Promise<void> =>
+      Promise.reject(new MemoryError("ERR_EMBEDDING_DISABLED", "VectorSearchAdapter 未配置（Phase 5 接入）")),
+    health: (): Promise<ComponentHealth> =>
+      Promise.resolve({ component: "vector-search", status: "unavailable", detail: "向量索引未启用（Phase 5 接入 pgvector/sqlite-vec）" }),
+  }
+}
+
+/**
+ * 维度真源校验（Review R5 回流）：provider 上报维度必须与 DB 侧声明维度一致，否则拒写。
+ * declaredDim 来自 AddMemory.embeddingDim（写入路径的真源）。
+ */
+export function assertEmbeddingDimension(providerDim: number, declaredDim: number): void {
+  if (declaredDim <= 0) return // 未声明维度：首写，由 provider 值落库
+  if (providerDim !== declaredDim) {
+    throw new MemoryError(
+      "ERR_DIMENSION_MISMATCH",
+      `嵌入维度不一致：provider=${providerDim} vs 声明=${declaredDim}（拒绝写入，避免脏向量）`,
+    )
+  }
+}
+
+export type EmbeddingMode = "none" | "local-onnx" | "openai-compatible"
+
+export interface EmbeddingEnvConfig {
+  mode?: string
+  model?: string
+  dimension?: number
+  baseUrl?: string
+  apiKey?: string
+  cacheDir?: string
+  remoteHost?: string
+}
+
+/** 从环境变量解析提供者配置（纯函数，便于测试与文档化） */
+export function parseEmbeddingEnv(env: NodeJS.ProcessEnv = process.env): EmbeddingEnvConfig {
+  const mode = (env.ADD_MEMORY_EMBEDDING ?? "none").toLowerCase()
+  const dim = Number(env.ADD_MEMORY_EMBEDDING_DIM ?? "")
+  return {
+    mode,
+    model: env.ADD_MEMORY_EMBEDDING_MODEL,
+    dimension: Number.isFinite(dim) && dim > 0 ? Math.floor(dim) : undefined,
+    baseUrl: env.ADD_MEMORY_EMBEDDING_BASE_URL,
+    apiKey: env.ADD_MEMORY_EMBEDDING_API_KEY,
+    cacheDir: env.ADD_MEMORY_EMBEDDING_CACHE_DIR,
+    remoteHost: env.ADD_MEMORY_EMBEDDING_REMOTE_HOST,
+  }
+}
+
+/**
+ * 按配置装配提供者（默认 none → 行为与首版一致）。
+ * local-onnx / openai-compatible 走动态 import，未配置的路径不加载任何重依赖。
+ */
+export async function createEmbeddingProviderFromConfig(
+  config: EmbeddingEnvConfig = parseEmbeddingEnv(),
+): Promise<EmbeddingProvider> {
+  const mode = (config.mode ?? "none") as EmbeddingMode
+  if (mode === "local-onnx") {
+    const { createLocalOnnxEmbeddingProvider } = await import("./local-onnx.js")
+    return createLocalOnnxEmbeddingProvider({
+      model: config.model,
+      cacheDir: config.cacheDir,
+      remoteHost: config.remoteHost,
+    })
+  }
+  if (mode === "openai-compatible") {
+    if (!config.baseUrl) {
+      throw new MemoryError("ERR_EMBEDDING_DISABLED", "openai-compatible 需要 ADD_MEMORY_EMBEDDING_BASE_URL")
+    }
+    const { createOpenAiCompatibleEmbeddingProvider } = await import("./openai-compatible.js")
+    return createOpenAiCompatibleEmbeddingProvider({
+      baseUrl: config.baseUrl,
+      model: config.model ?? "text-embedding-3-small",
+      apiKey: config.apiKey,
+      dimension: config.dimension,
+    })
+  }
+  return createNoneEmbeddingProvider()
+}

package/templates/core/scripts/mcp-server/shared/memory/embedding/local-onnx.ts

@@ -0,0 +1,105 @@
+/*
+ * 本地 ONNX 嵌入提供者（Plan §3.4 轮 3 Task 3.1 / Spec §6 §VectorCapability）
+ *
+ * 关键约束：
+ *  1. **可选依赖**：@huggingface/transformers 与模型权重都可能在目标机器缺失——加载失败
+ *     必须收敛为 ERR_EMBEDDING_DISABLED（调用方据此走 fts-only），绝不抛裸异常阻塞 Gate；
+ *  2. **维度以模型元数据为真源**：dimension 由首次推理的实际输出长度决定（不硬编码），
+ *     与 DB 侧 AddMemory.embeddingDim 不一致时由调用方拒绝写入（Review R5 回流）；
+ *  3. 惰性加载：不在模块顶层 import/下载模型，首次 embed 时才初始化。
+ */
+import { MemoryError } from "../domain/errors.js"
+import type { ComponentHealth } from "../retrieval/types.js"
+import type { EmbeddingProvider } from "./index.js"
+
+/** 默认模型：中文小模型（真源维度 512，与 Plan R5「维度真源」一致） */
+export const DEFAULT_LOCAL_ONNX_MODEL = "Xenova/bge-small-zh-v1.5"
+
+export interface LocalOnnxOptions {
+  model?: string
+  /** 显式缓存目录；缺省复用 HF_HUB_CACHE → HF_HOME/hub → ~/.cache/huggingface/hub */
+  cacheDir?: string
+  /** 镜像站（内网/受限网络） */
+  remoteHost?: string
+  /** 测试注入：直接给定 pipeline 工厂 */
+  loadPipeline?: (model: string) => Promise<(texts: string[]) => Promise<number[][]>>
+}
+
+export interface LocalOnnxProvider extends EmbeddingProvider {
+  /** 首次推理后可用；未初始化时为 0（调用方以 assertEmbeddingDimension 校验） */
+  readonly resolvedDimension: number
+}
+
+export function createLocalOnnxEmbeddingProvider(opts: LocalOnnxOptions = {}): LocalOnnxProvider {
+  const model = opts.model ?? DEFAULT_LOCAL_ONNX_MODEL
+  let embedFn: ((texts: string[]) => Promise<number[][]>) | null = null
+  let dimension = 0
+
+  async function ensureLoaded(): Promise<(texts: string[]) => Promise<number[][]>> {
+    if (embedFn) return embedFn
+    try {
+      if (opts.loadPipeline) {
+        embedFn = await opts.loadPipeline(model)
+      } else {
+        const { pipeline, env } = await import("@huggingface/transformers")
+        if (opts.cacheDir) env.cacheDir = opts.cacheDir
+        if (opts.remoteHost) env.remoteHost = opts.remoteHost
+        const extractor = await pipeline("feature-extraction", model)
+        embedFn = async (texts: string[]) => {
+          const result = await extractor(texts, { pooling: "mean", normalize: true })
+          const list = result.tolist() as number[][]
+          return list.length === texts.length ? list : [list as unknown as number[]]
+        }
+      }
+      return embedFn
+    } catch (error) {
+      throw new MemoryError(
+        "ERR_EMBEDDING_DISABLED",
+        `本地 ONNX 模型不可用（model=${model}）：${error instanceof Error ? error.message : String(error)}`,
+      )
+    }
+  }
+
+  return {
+    id: "local-onnx",
+    get dimension(): number {
+      return dimension
+    },
+    get resolvedDimension(): number {
+      return dimension
+    },
+    async embed(texts: string[]): Promise<number[][]> {
+      if (texts.length === 0) return []
+      const fn = await ensureLoaded()
+      let vectors: number[][]
+      try {
+        vectors = await fn(texts)
+      } catch (error) {
+        throw new MemoryError(
+          "ERR_EMBEDDING_DISABLED",
+          `本地 ONNX 推理失败（model=${model}）：${error instanceof Error ? error.message : String(error)}`,
+        )
+      }
+      const dim = vectors[0]?.length ?? 0
+      if (dim === 0) {
+        throw new MemoryError("ERR_EMBEDDING_DISABLED", `本地 ONNX 返回空向量（model=${model}）`)
+      }
+      // 维度真源：以模型实际输出为准；同一 provider 内必须自洽
+      if (dimension !== 0 && dimension !== dim) {
+        throw new MemoryError("ERR_DIMENSION_MISMATCH", `provider 维度漂移：${dimension} → ${dim}`)
+      }
+      dimension = dim
+      return vectors
+    },
+    health(): Promise<ComponentHealth> {
+      if (embedFn && dimension > 0) {
+        return Promise.resolve({ component: "embedding", status: "ok", detail: `local-onnx model=${model} dim=${dimension}` })
+      }
+      return Promise.resolve({
+        component: "embedding",
+        status: "degraded",
+        detail: `local-onnx 未初始化（model=${model}）；首次 embed 时加载，失败则降级 fts-only`,
+      })
+    },
+  }
+}

package/templates/core/scripts/mcp-server/shared/memory/embedding/openai-compatible.ts

@@ -0,0 +1,87 @@
+/*
+ * OpenAI 兼容嵌入提供者（Plan §3.4 轮 3 Task 3.1）
+ *
+ * 适用于任意 /v1/embeddings 兼容端点（本地 vLLM / 自建网关 / 官方 API）。
+ * 契约同 local-onnx：维度以首次响应为准（配置项 dimension 仅作期望值校验），
+ * 任何失败收敛为 ERR_EMBEDDING_DISABLED，不阻塞 Gate。
+ */
+import { MemoryError } from "../domain/errors.js"
+import type { ComponentHealth } from "../retrieval/types.js"
+import type { EmbeddingProvider } from "./index.js"
+
+export interface OpenAiCompatibleOptions {
+  baseUrl: string
+  model: string
+  apiKey?: string
+  /** 期望维度（可选）：与首次响应不一致时报 ERR_DIMENSION_MISMATCH */
+  dimension?: number
+  timeoutMs?: number
+  /** 测试注入 */
+  fetchImpl?: typeof fetch
+}
+
+export function createOpenAiCompatibleEmbeddingProvider(
+  opts: OpenAiCompatibleOptions,
+): EmbeddingProvider {
+  const doFetch = opts.fetchImpl ?? fetch
+  const endpoint = `${opts.baseUrl.replace(/\/+$/, "")}/embeddings`
+  let dimension = opts.dimension ?? 0
+  let lastError: string | null = null
+
+  return {
+    id: "openai-compatible",
+    get dimension(): number {
+      return dimension
+    },
+    async embed(texts: string[]): Promise<number[][]> {
+      if (texts.length === 0) return []
+      const controller = new AbortController()
+      const timer = setTimeout(() => controller.abort(), opts.timeoutMs ?? 15_000)
+      let payload: { data?: { embedding?: number[] }[] }
+      try {
+        const res = await doFetch(endpoint, {
+          method: "POST",
+          headers: {
+            "content-type": "application/json",
+            ...(opts.apiKey ? { authorization: `Bearer ${opts.apiKey}` } : {}),
+          },
+          body: JSON.stringify({ model: opts.model, input: texts }),
+          signal: controller.signal,
+        })
+        if (!res.ok) {
+          throw new Error(`HTTP ${res.status}`)
+        }
+        payload = (await res.json()) as { data?: { embedding?: number[] }[] }
+      } catch (error) {
+        lastError = error instanceof Error ? error.message : String(error)
+        throw new MemoryError("ERR_EMBEDDING_DISABLED", `兼容端点调用失败（${endpoint}）：${lastError}`)
+      } finally {
+        clearTimeout(timer)
+      }
+
+      const vectors = (payload.data ?? []).map((d) => d.embedding ?? []).filter((v) => v.length > 0)
+      if (vectors.length === 0) {
+        throw new MemoryError("ERR_EMBEDDING_DISABLED", `兼容端点未返回向量（model=${opts.model}）`)
+      }
+      const dim = vectors[0].length
+      if (dimension !== 0 && dimension !== dim) {
+        throw new MemoryError("ERR_DIMENSION_MISMATCH", `期望维度 ${dimension}，实收 ${dim}`)
+      }
+      dimension = dim
+      lastError = null
+      return vectors
+    },
+    health(): Promise<ComponentHealth> {
+      if (dimension > 0) {
+        return Promise.resolve({ component: "embedding", status: "ok", detail: `openai-compatible model=${opts.model} dim=${dimension}` })
+      }
+      return Promise.resolve({
+        component: "embedding",
+        status: lastError ? "unavailable" : "degraded",
+        detail: lastError
+          ? `兼容端点不可用：${lastError}`
+          : `兼容端点未调用（model=${opts.model}，endpoint=${endpoint}）`,
+      })
+    },
+  }
+}

package/templates/core/scripts/mcp-server/shared/memory/jobs/consolidation.ts

@@ -0,0 +1,226 @@
+/*
+ * Consolidation 异步任务（Spec §10，Plan §9.2 Post-Handoff 行）
+ *
+ * 职责（全部 fail-open 隔离：单步失败不影响他步，错误入报告）：
+ *  1. drainEvidenceQueue —— 采证队列落库
+ *  2. 重复检测 —— 同 repositoryRef+contentHash 多行 → 报告（不自动合并，人审）
+ *  3. 冲突队列 —— CANDIDATE/PENDING 与 ACTIVE 高相似 → 报告（不自动激活，Plan §3）
+ *  4. 指标候选 —— AddMetricSnapshot 连续异常 streak 命中 → 创建 CANDIDATE（幂等）
+ *  5. Handoff Digest —— HANDOFF Evidence → HANDOFF_DIGEST Candidate（幂等，绝不直接 ACTIVE）
+ *  6. 刷新 L1 快照 —— 供 session-start Hook 注入
+ */
+import type {
+  AddMemoryEvidenceRow,
+  AddMemoryEvidenceLinkRow,
+  AddMemoryRow,
+  AddMetricSnapshotRow,
+  TableDelegate,
+} from "../../db-types.js"
+import { detectConflicts, type Conflict } from "../domain/conflicts.js"
+import { contentHash } from "../domain/dedup.js"
+import { detectAnomalyStreak, type MetricPoint } from "../domain/metric-candidate.js"
+import { buildHandoffDigest } from "../domain/handoff-digest.js"
+import { drainEvidenceQueue, type DrainResult } from "./evidence-collector.js"
+import { refreshL1Snapshot, type SnapshotDeps, type SnapshotResult } from "./snapshot.js"
+
+export interface ConsolidationDeps extends SnapshotDeps {
+  memoryDb: TableDelegate<AddMemoryRow>
+  evidenceDb: Pick<TableDelegate<AddMemoryEvidenceRow>, "upsert" | "findMany">
+  linkDb: Pick<TableDelegate<AddMemoryEvidenceLinkRow>, "findFirst" | "create">
+  metricDb: TableDelegate<AddMetricSnapshotRow>
+}
+
+export interface ConsolidationReport {
+  drain: DrainResult
+  duplicates: { contentHash: string; ids: string[] }[]
+  conflictQueue: { candidateId: string; topic: string; conflicts: Conflict[] }[]
+  metricCandidatesCreated: string[]
+  handoffDigestsCreated: string[]
+  snapshot: SnapshotResult | null
+  errors: string[]
+}
+
+export async function runConsolidation(deps: ConsolidationDeps): Promise<ConsolidationReport> {
+  const report: ConsolidationReport = {
+    drain: { processed: 0, skipped: 0, errors: [], newOffset: 0 },
+    duplicates: [],
+    conflictQueue: [],
+    metricCandidatesCreated: [],
+    handoffDigestsCreated: [],
+    snapshot: null,
+    errors: [],
+  }
+
+  // 1. 采证队列落库
+  try {
+    report.drain = await drainEvidenceQueue(deps)
+  } catch (e) {
+    report.errors.push(`drain: ${e instanceof Error ? e.message : String(e)}`)
+  }
+
+  // 2/3. 重复检测 + 冲突队列（共享一次全量读取）
+  try {
+    const rows = await deps.memoryDb.findMany({
+      where: { repositoryRef: deps.repositoryRef, status: { notIn: ["REJECTED", "ARCHIVED"] } },
+      take: 500,
+    })
+    const byHash = new Map<string, string[]>()
+    for (const r of rows) {
+      const arr = byHash.get(r.contentHash) ?? []
+      arr.push(r.id)
+      byHash.set(r.contentHash, arr)
+    }
+    for (const [hash, ids] of byHash) {
+      if (ids.length > 1) report.duplicates.push({ contentHash: hash, ids })
+    }
+    const actives = rows.filter((r) => r.status === "ACTIVE")
+    for (const c of rows.filter((r) => r.status === "CANDIDATE" || r.status === "PENDING")) {
+      const conflicts = detectConflicts(c, actives)
+      if (conflicts.length > 0) report.conflictQueue.push({ candidateId: c.id, topic: c.topic, conflicts })
+    }
+  } catch (e) {
+    report.errors.push(`dedup/conflicts: ${e instanceof Error ? e.message : String(e)}`)
+  }
+
+  // 4. 指标候选（Plan §10：连续异常 streak 才生成，内容必须是可验证结论）
+  try {
+    const metrics = await deps.metricDb.findMany({
+      where: { repositoryRef: deps.repositoryRef },
+      orderBy: { measuredAt: "asc" },
+      take: 500,
+    })
+    const byType = new Map<string, MetricPoint[]>()
+    for (const m of metrics) {
+      const arr = byType.get(m.metricType) ?? []
+      arr.push({
+        repositoryRef: m.repositoryRef,
+        metricType: m.metricType,
+        value: m.value,
+        baseline: m.baseline,
+        planKeyword: m.planKeyword,
+        measuredAt: m.measuredAt,
+        sourceRef: m.sourceRef,
+      })
+      byType.set(m.metricType, arr)
+    }
+    for (const points of byType.values()) {
+      const proposal = detectAnomalyStreak(points)
+      if (!proposal) continue
+      const hash = contentHash(proposal.content)
+      const existing = await deps.memoryDb.findFirst({
+        where: {
+          repositoryRef: deps.repositoryRef,
+          contentHash: hash,
+          scopeType: "REPOSITORY",
+          scopeValue: deps.repositoryRef,
+          status: { notIn: ["REJECTED", "ARCHIVED"] },
+        },
+      })
+      if (existing) continue // 幂等：已提过同结论
+      const created = await deps.memoryDb.create({
+        data: {
+          kind: "PATTERN",
+          topic: proposal.topic,
+          content: proposal.content,
+          scopeType: "REPOSITORY",
+          scopeValue: deps.repositoryRef,
+          repositoryRef: deps.repositoryRef,
+          contentHash: hash,
+          createdBy: "memory-jobs:consolidation",
+        },
+      })
+      for (const ref of proposal.evidenceSourceRefs) {
+        const ev = await deps.evidenceDb.upsert({
+          where: {
+            repositoryRef_sourceType_sourceRef_contentHash: {
+              repositoryRef: deps.repositoryRef, sourceType: "DPS_GATE", sourceRef: ref, contentHash: contentHash(ref),
+            },
+          },
+          create: {
+            repositoryRef: deps.repositoryRef, sourceType: "DPS_GATE", sourceRef: ref,
+            excerpt: ref.slice(0, 500), contentHash: contentHash(ref),
+          },
+          update: {},
+        })
+        const linked = await deps.linkDb.findFirst({ where: { memoryId: created.id, evidenceId: ev.id } })
+        if (!linked) await deps.linkDb.create({ data: { memoryId: created.id, evidenceId: ev.id } })
+      }
+      report.metricCandidatesCreated.push(created.id)
+    }
+  } catch (e) {
+    report.errors.push(`metric-candidates: ${e instanceof Error ? e.message : String(e)}`)
+  }
+
+  // 5. Handoff Digest（Plan §3.1 轮 2）：HANDOFF Evidence → HANDOFF_DIGEST Candidate
+  //    幂等去重靠 dedupKey 派生的 contentHash；绝不直接置 ACTIVE（只产 CANDIDATE）
+  try {
+    const handoffEvidence = await deps.evidenceDb.findMany({
+      where: { repositoryRef: deps.repositoryRef, sourceType: "HANDOFF" },
+      orderBy: { occurredAt: "asc" },
+      take: 200,
+    })
+    for (const ev of handoffEvidence) {
+      const proposal = buildHandoffDigest(
+        { handoffRef: ev.sourceRef, excerpt: ev.excerpt, planKeyword: ev.planKeyword },
+        { repositoryRef: deps.repositoryRef },
+      )
+      const existing = await deps.memoryDb.findFirst({
+        where: {
+          repositoryRef: deps.repositoryRef,
+          contentHash: proposal.contentHash,
+          scopeType: proposal.scopeType,
+          scopeValue: proposal.scopeValue,
+          status: { notIn: ["REJECTED", "ARCHIVED"] },
+        },
+      })
+      if (existing) {
+        // 幂等：同一交接 evidence 的摘要已入队过 → 仅补齐证据关联
+        const linkedAlready = await deps.linkDb.findFirst({
+          where: { memoryId: existing.id, evidenceId: ev.id },
+        })
+        if (!linkedAlready) {
+          await deps.linkDb.create({
+            data: { memoryId: existing.id, evidenceId: ev.id },
+          })
+        }
+        continue
+      }
+      const created = await deps.memoryDb.create({
+        data: {
+          kind: proposal.kind,
+          status: "CANDIDATE", // 绝不直接 ACTIVE
+          topic: proposal.topic,
+          content: proposal.content,
+          scopeType: proposal.scopeType,
+          scopeValue: proposal.scopeValue,
+          repositoryRef: deps.repositoryRef,
+          contentHash: proposal.contentHash,
+          importance: 0.6,
+          confidence: 0.5,
+          createdBy: "memory-jobs:consolidation",
+          metadata: { ...proposal.metadata, dedupKey: proposal.dedupKey, evidenceId: ev.id },
+        },
+      })
+      const linked = await deps.linkDb.findFirst({
+        where: { memoryId: created.id, evidenceId: ev.id },
+      })
+      if (!linked) {
+        await deps.linkDb.create({
+          data: { memoryId: created.id, evidenceId: ev.id },
+        })
+      }
+      report.handoffDigestsCreated.push(created.id)
+    }
+  } catch (e) {
+    report.errors.push(`handoff-digest: ${e instanceof Error ? e.message : String(e)}`)
+  }
+
+  // 6. 刷新 L1 快照
+  try {
+    report.snapshot = await refreshL1Snapshot(deps)
+  } catch (e) {
+    report.errors.push(`snapshot: ${e instanceof Error ? e.message : String(e)}`)
+  }
+
+  return report
+}