add-coder 0.3.33 → 0.3.35

package/templates/core/scripts/mcp-server/shared/memory/retrieval/fusion.ts

@@ -0,0 +1,43 @@
+/*
+ * RRF 融合（Plan §7.3）：RRF(d) = Σ 1 / (k + rank_i(d))
+ * 避免强行比较 PG、SQLite 和不同 FTS 实现的原始分值。
+ * k 可配置化（写入 Recall.rankingVersion 的配置快照）。
+ */
+import type { RankedId } from "./types.js"
+
+export const DEFAULT_RRF_K = 10
+
+/**
+ * 加权 RRF：score(d) = Σ_i w_i / (k + rank_i(d))
+ * 通道权重让「高精度通道」主导、低精度通道只做补充（Plan 轮 3 融合迭代）。
+ * weights 缺省为 1（退化为经典 RRF，保持向后兼容）。
+ */
+export function rrfFuse(
+  lists: RankedId[][],
+  k: number = DEFAULT_RRF_K,
+  weights?: readonly number[],
+): Map<string, number> {
+  const scores = new Map<string, number>()
+  lists.forEach((list, i) => {
+    const w = weights?.[i] ?? 1
+    if (w <= 0) return
+    for (const item of list) {
+      const prev = scores.get(item.memoryId) ?? 0
+      scores.set(item.memoryId, prev + w / (k + item.rank))
+    }
+  })
+  return scores
+}
+
+/** 便捷入口：融合后按分数降序返回有序 id 列表 */
+export function rrfRank(
+  lists: RankedId[][],
+  k: number = DEFAULT_RRF_K,
+  weights?: readonly number[],
+): RankedId[] {
+  const scores = rrfFuse(lists, k, weights)
+  return [...scores.entries()]
+    .map(([memoryId, score]) => ({ memoryId, rank: 0, score }))
+    .sort((a, b) => (b.score ?? 0) - (a.score ?? 0))
+    .map((r, i) => ({ ...r, rank: i + 1 }))
+}

package/templates/core/scripts/mcp-server/shared/memory/retrieval/pipeline.ts

@@ -0,0 +1,285 @@
+/*
+ * Hybrid Recall 编排管线（Plan §7.1 十步流水线）
+ *
+ *  1. Repository/tenant 边界校验（调用方前置，此处防御性复核）
+ *  2. Lifecycle 过滤（默认仅 ACTIVE；诊断模式放行 STALE）
+ *  3. Scope 过滤与强约束匹配
+ *  4. FTS/BM25 候选生成（双后端 adapter）
+ *  5. Vector 候选生成（能力可用时；首版 none）
+ *  6. Reciprocal Rank Fusion
+ *  7. 治理重排
+ *  8. 冲突、重复和多样性处理
+ *  9. Token-budget 摘要与裁剪
+ * 10. 写入 AddMemoryRecall
+ */
+import { DEFAULT_RECALL_STATUSES, DIAGNOSTIC_RECALL_STATUSES, type MemoryStatus } from "../domain/state-machine.js"
+import { scopeApplies, type ScopeContext } from "../domain/scope.js"
+import { rrfFuse, DEFAULT_RRF_K } from "./fusion.js"
+import {
+  rerankOne,
+  DEFAULT_WEIGHTS,
+  RANKING_VERSION,
+  RANKING_VERSION_HYBRID,
+  RRF_SCORE_SCALE,
+  type RerankWeights,
+} from "./reranker.js"
+import { buildContext, estimateTokens } from "./context-builder.js"
+import { writeRecallAudit, type RecallAuditStore } from "./recall-writer.js"
+import type { LexicalSearchAdapter, RankedId, RecallFilter, RecalledMemory } from "./types.js"
+
+/** 向量通道默认权重与候选预算（Plan 轮 3 融合迭代：低精度通道不与词法等权） */
+export const DEFAULT_VECTOR_WEIGHT = 0.3
+export const DEFAULT_VECTOR_TOP_K = 5
+
+/** 管线需要的记忆行字段子集（与 AddMemoryRow 对齐） */
+export interface MemoryRowLike {
+  id: string
+  kind: string
+  status: string
+  topic: string
+  content: string
+  summary: string | null
+  scopeType: string
+  scopeValue: string
+  repositoryRef: string
+  importance: number
+  confidence: number
+  validUntil: Date | null
+  supersedes?: { id: string }[]
+}
+
+export interface RecallPipelineInput {
+  query: string
+  stage: string
+  repositoryRef: string
+  scopeCtx: ScopeContext
+  maxTokens: number
+  kinds?: string[]
+  limit?: number
+  consumerRef?: string
+  /** 诊断模式：放行 STALE（带警告标记），默认 false */
+  diagnostic?: boolean
+}
+
+export interface RecallPipelineDeps {
+  lexical: LexicalSearchAdapter[]
+  /** Vector 候选（可选；首版不传即 FTS-only） */
+  vector?: { search(query: string, filter: RecallFilter, limit: number): Promise<RankedId[]> } | null
+  /** 向量通道权重（RRF 加权；默认 DEFAULT_VECTOR_WEIGHT —— 低精度通道不与词法等权） */
+  vectorWeight?: number
+  /** 向量候选预算（默认 DEFAULT_VECTOR_TOP_K —— 不按总 limit 灌入，避免稀释词法信号） */
+  vectorTopK?: number
+  /** 补位模式阈值：仅当词法候选数 < 该值时启用向量通道（缺省=始终补充） */
+  vectorFallbackThreshold?: number
+  fetchByIds(ids: string[]): Promise<MemoryRowLike[]>
+  fetchEvidenceSourceRefs(memoryIds: string[]): Promise<Map<string, string[]>>
+  audit?: RecallAuditStore | null
+  weights?: RerankWeights
+  rrfK?: number
+  rankingVersion?: string
+  degradedMode?: string
+  now?: Date
+}
+
+export interface RecallPipelineResult {
+  items: RecalledMemory[]
+  recallId: string | null
+  degradedMode: string | null
+  /** 实际参与融合的候选通道（Spec §7 RecallResultMeta） */
+  fusedChannels: ("lexical" | "vector")[]
+  excluded: { memoryId: string; reason: string }[]
+  candidateCount: number
+  injectedTokens: number
+  latencyMs: number
+  rankingVersion: string
+}
+
+export async function recallPipeline(
+  input: RecallPipelineInput,
+  deps: RecallPipelineDeps,
+): Promise<RecallPipelineResult> {
+  const start = Date.now()
+  const now = deps.now ?? new Date()
+  const statuses: readonly MemoryStatus[] = input.diagnostic ? DIAGNOSTIC_RECALL_STATUSES : DEFAULT_RECALL_STATUSES
+  const limit = input.limit ?? 20
+
+  // Step 1（防御性复核）：repository 边界
+  if (input.scopeCtx.repository !== input.repositoryRef) {
+    throw new Error(`ERR_REPOSITORY_MISMATCH: scopeCtx.repository=${input.scopeCtx.repository} 与 repositoryRef 不一致`)
+  }
+
+  const filter: RecallFilter = {
+    repositoryRef: input.repositoryRef,
+    statuses,
+    scopeCtx: input.scopeCtx,
+    kinds: input.kinds,
+    now,
+  }
+
+  // Step 4/5：候选生成（FTS 多通道 + 可选 Vector）
+  const channelLists: RankedId[][] = []
+  let lexicalChannels = 0
+  for (const adapter of deps.lexical) {
+    const multi = adapter as LexicalSearchAdapter & {
+      searchChannels?(q: string, f: RecallFilter, l: number): Promise<RankedId[][]>
+    }
+    if (typeof multi.searchChannels === "function") {
+      const channels = await multi.searchChannels(input.query, filter, limit)
+      channelLists.push(...channels)
+      lexicalChannels += channels.length
+    } else {
+      channelLists.push(await adapter.search(input.query, filter, limit))
+      lexicalChannels += 1
+    }
+  }
+  let vectorUsed = false
+  const channelWeights: number[] = channelLists.map(() => 1) // 词法通道权重恒为 1
+  if (deps.vector) {
+    const lexicalCandidates = new Set(channelLists.flat().map((c) => c.memoryId)).size
+    const fallbackOnly = deps.vectorFallbackThreshold != null
+    const shouldUseVector = !fallbackOnly || lexicalCandidates < (deps.vectorFallbackThreshold as number)
+    try {
+      if (shouldUseVector) {
+        const vectorCandidates = await deps.vector.search(
+          input.query,
+          filter,
+          Math.min(deps.vectorTopK ?? DEFAULT_VECTOR_TOP_K, limit),
+        )
+        channelLists.push(vectorCandidates)
+        channelWeights.push(deps.vectorWeight ?? DEFAULT_VECTOR_WEIGHT)
+        vectorUsed = true
+      }
+    } catch {
+      // Vector 故障不阻塞 FTS（Plan §8.4）
+    }
+  }
+  const fusedChannels: ("lexical" | "vector")[] = [
+    ...(lexicalChannels > 0 ? (["lexical"] as const) : []),
+    ...(vectorUsed ? (["vector"] as const) : []),
+  ]
+  // rankingVersion：向量通道真正参与融合才记 v2；否则保持 v1（可被调用方显式覆盖）
+  const effectiveRankingVersion =
+    deps.rankingVersion ?? (vectorUsed ? RANKING_VERSION_HYBRID : RANKING_VERSION)
+
+  // Step 6：RRF 融合
+  const fused = rrfFuse(channelLists, deps.rrfK ?? DEFAULT_RRF_K, channelWeights)
+  const candidateIds = [...fused.keys()]
+  if (candidateIds.length === 0) {
+    const empty: RecallPipelineResult = {
+      items: [], recallId: null, degradedMode: deps.degradedMode ?? null,
+      fusedChannels,
+      excluded: [], candidateCount: 0, injectedTokens: 0,
+      latencyMs: Date.now() - start, rankingVersion: effectiveRankingVersion,
+    }
+    if (deps.audit) {
+      empty.recallId = await writeRecallAudit(deps.audit, {
+        repositoryRef: input.repositoryRef, query: input.query, stage: input.stage,
+        consumerRef: input.consumerRef, scopeContext: input.scopeCtx,
+        candidateIds: [], items: [], excluded: [],
+        rankingVersion: empty.rankingVersion, tokenBudget: input.maxTokens,
+        injectedTokens: 0, latencyMs: empty.latencyMs, degradedMode: empty.degradedMode ?? undefined,
+      })
+    }
+    return empty
+  }
+
+  // Step 2/3：取行 + lifecycle/scope 防御性复核（SQL 已过滤，此处兜底语义一致性）
+  const rows = await deps.fetchByIds(candidateIds)
+  const rowById = new Map(rows.map((r) => [r.id, r]))
+  const eligible = rows.filter((r) => {
+    if (r.repositoryRef !== input.repositoryRef) return false
+    if (!statuses.includes(r.status as MemoryStatus)) return false
+    if (r.validUntil && r.validUntil <= now) return false
+    return scopeApplies(
+      { type: r.scopeType as Parameters<typeof scopeApplies>[0]["type"], value: r.scopeValue },
+      input.scopeCtx,
+    )
+  })
+  const scopeExcluded = candidateIds
+    .filter((id) => rowById.has(id) && !eligible.some((r) => r.id === id))
+    .map((id) => ({ memoryId: id, reason: "lifecycle/scope/有效期过滤" }))
+
+  // Step 7/8：治理重排
+  const reranked = eligible.map((r) => ({
+    row: r,
+    rr: rerankOne({
+      memoryId: r.id,
+      // 相关性主导：RRF 放大到与治理 boost 可比量级（见 RRF_SCORE_SCALE 注释）
+      rrfScore: (fused.get(r.id) ?? 0) * RRF_SCORE_SCALE,
+      kind: r.kind,
+      status: r.status as MemoryStatus,
+      importance: r.importance,
+      confidence: r.confidence,
+      scopeType: r.scopeType,
+      scopeValue: r.scopeValue,
+    }, input.scopeCtx, deps.weights ?? DEFAULT_WEIGHTS),
+  }))
+
+  // Step 9：token 预算
+  const budgetItems = reranked.map(({ row, rr }) => ({
+    memoryId: row.id,
+    kind: row.kind,
+    finalScore: rr.finalScore,
+    tokens: estimateTokens(row.summary ?? row.content),
+    content: row.content,
+    sourceRefs: [] as string[],
+    _why: rr.whySelected,
+    _breakdown: rr.scoreBreakdown,
+  }))
+  const budget = buildContext(budgetItems, input.maxTokens)
+
+  const evidenceRefs = await deps.fetchEvidenceSourceRefs(budget.selected.map((s) => s.memoryId))
+  const items: RecalledMemory[] = budget.selected.map((s) => {
+    const row = rowById.get(s.memoryId)!
+    const extra = budgetItems.find((b) => b.memoryId === s.memoryId)!
+    return {
+      memoryId: s.memoryId,
+      kind: row.kind,
+      topic: row.topic,
+      content: row.content,
+      scope: { type: row.scopeType, value: row.scopeValue },
+      confidence: row.confidence,
+      importance: row.importance,
+      sourceRefs: evidenceRefs.get(s.memoryId) ?? s.sourceRefs,
+      whySelected: extra._why,
+      scoreBreakdown: extra._breakdown,
+      supersedes: (row.supersedes ?? []).map((x) => x.id),
+    }
+  })
+
+  const excluded = [...scopeExcluded, ...budget.excluded]
+  const latencyMs = Date.now() - start
+  const injectedTokens = budget.usedTokens
+
+  // Step 10：审计落库
+  let recallId: string | null = null
+  if (deps.audit) {
+    recallId = await writeRecallAudit(deps.audit, {
+      repositoryRef: input.repositoryRef,
+      query: input.query,
+      stage: input.stage,
+      consumerRef: input.consumerRef,
+      scopeContext: input.scopeCtx,
+      candidateIds,
+      items,
+      excluded,
+      rankingVersion: effectiveRankingVersion,
+      tokenBudget: input.maxTokens,
+      injectedTokens,
+      latencyMs,
+      degradedMode: deps.degradedMode,
+    })
+  }
+
+  return {
+    items,
+    recallId,
+    degradedMode: deps.degradedMode ?? null,
+    fusedChannels,
+    excluded,
+    candidateCount: candidateIds.length,
+    injectedTokens,
+    latencyMs,
+    rankingVersion: effectiveRankingVersion,
+  }
+}

package/templates/core/scripts/mcp-server/shared/memory/retrieval/query-terms.ts

@@ -0,0 +1,31 @@
+/*
+ * 查询词项抽取（双后端 LIKE/bigram 通道共用）
+ *
+ * 背景：trigram 分词器（PG pg_trgm / SQLite FTS5 trigram）是子串语义，
+ * 对释义查询（如 "新端口怎么申请" vs 内容 "新增端口"）召回不足。
+ * 本模块把查询分解为「拉丁词 + CJK 二元组」词项，供 LIKE 重叠通道计分。
+ */
+import { normalizeContent } from "../domain/dedup.js"
+
+const MAX_TERMS = 24
+
+/** 拉丁/数字词（≥2 字符）+ CJK 连续段的滑动二元组 */
+export function extractQueryTerms(query: string): string[] {
+  const norm = normalizeContent(query)
+  const terms: string[] = []
+  const seen = new Set<string>()
+  const push = (t: string) => {
+    if (!seen.has(t) && terms.length < MAX_TERMS) { seen.add(t); terms.push(t) }
+  }
+
+  // 拉丁词
+  for (const m of norm.matchAll(/[a-z0-9_]{2,}/g)) push(m[0])
+
+  // CJK 连续段 → 滑动二元组（单字段保留单字）
+  for (const seg of norm.matchAll(/[㐀-鿿぀-ヿ]+/g)) {
+    const s = seg[0]
+    if (s.length === 1) { push(s); continue }
+    for (let i = 0; i < s.length - 1; i++) push(s.slice(i, i + 2))
+  }
+  return terms
+}

package/templates/core/scripts/mcp-server/shared/memory/retrieval/recall-writer.ts

@@ -0,0 +1,87 @@
+/*
+ * Recall 审计写入（Plan §4.3/§7.1-10：每次召回记录候选、评分、选择，可重放）
+ */
+import type { RecalledMemory } from "./types.js"
+
+export interface RecallAuditRecord {
+  repositoryRef: string
+  query: string
+  stage: string
+  consumerRef?: string
+  scopeContext: unknown
+  candidateIds: string[]
+  items: RecalledMemory[]
+  excluded: { memoryId: string; reason: string }[]
+  rankingVersion: string
+  tokenBudget: number
+  injectedTokens: number
+  latencyMs: number
+  degradedMode?: string
+}
+
+export interface RecallAuditStore {
+  createRecall(data: {
+    repositoryRef: string
+    query: string
+    stage: string
+    consumerRef: string | null
+    scopeContext: unknown
+    candidateIds: unknown
+    selectedIds: unknown
+    scoreBreakdown: unknown
+    exclusionReasons: unknown
+    rankingVersion: string
+    tokenBudget: number
+    injectedTokens: number
+    latencyMs: number
+    degradedMode: string | null
+  }): Promise<{ id: string }>
+  createRecallItem(data: {
+    recallId: string
+    memoryId: string
+    selected: boolean
+    rank: number | null
+  }): Promise<unknown>
+}
+
+/** 落库一次召回（Recall + 每候选一条 RecallItem），返回 recallId */
+export async function writeRecallAudit(
+  store: RecallAuditStore,
+  rec: RecallAuditRecord,
+): Promise<string> {
+  const selectedIds = rec.items.map((i) => i.memoryId)
+  const scoreBreakdown: Record<string, Record<string, number>> = {}
+  for (const item of rec.items) scoreBreakdown[item.memoryId] = item.scoreBreakdown
+
+  const recall = await store.createRecall({
+    repositoryRef: rec.repositoryRef,
+    query: rec.query,
+    stage: rec.stage,
+    consumerRef: rec.consumerRef ?? null,
+    scopeContext: rec.scopeContext,
+    candidateIds: rec.candidateIds,
+    selectedIds,
+    scoreBreakdown,
+    exclusionReasons: rec.excluded,
+    rankingVersion: rec.rankingVersion,
+    tokenBudget: rec.tokenBudget,
+    injectedTokens: rec.injectedTokens,
+    latencyMs: rec.latencyMs,
+    degradedMode: rec.degradedMode ?? null,
+  })
+
+  // 候选全集 = 选中 + 被排除（重放完整性）
+  const selectedSet = new Set(selectedIds)
+  const rankOf = new Map(selectedIds.map((id, i) => [id, i + 1]))
+  const excludedReason = new Map(rec.excluded.map((e) => [e.memoryId, e.reason]))
+  for (const id of rec.candidateIds) {
+    await store.createRecallItem({
+      recallId: recall.id,
+      memoryId: id,
+      selected: selectedSet.has(id),
+      rank: rankOf.get(id) ?? null,
+    })
+    void excludedReason.get(id) // reason 已落 Recall.exclusionReasons（JSON），Item 层不重复
+  }
+  return recall.id
+}

package/templates/core/scripts/mcp-server/shared/memory/retrieval/reranker.ts

@@ -0,0 +1,116 @@
+/*
+ * 治理重排（Plan §7.3）
+ *
+ * finalScore = rrfScore
+ *   + scopeBoost + kindBoost + importanceBoost + confidenceBoost + mandatoryConstraintBoost
+ *   - stalePenalty - conflictPenalty - redundancyPenalty
+ *
+ * 权重与 rankingVersion 配置化；首版默认权重经评测校准，未评测前不作为不可变产品规则。
+ */
+import { scopeRank, type ScopeContext } from "../domain/scope.js"
+import type { MemoryStatus } from "../domain/state-machine.js"
+
+export const RANKING_VERSION = "memory-rank-v1"
+/** hybrid（lexical + vector 双通道）排序版本：Plan §3.4 轮 3「rankingVersion v2」 */
+export const RANKING_VERSION_HYBRID = "memory-rank-v2"
+
+/**
+ * RRF 分数放大系数（Plan 轮 3 融合迭代）。
+ *
+ * 问题：RRF 单通道差值约 1/61−1/80 ≈ 0.004，而治理 boost 量级为 0.1–0.5 —— boost 完全主导排序，
+ * 相关性（RRF）只起微调作用，表现为「重要度高的无关记忆排在相关记忆之前」。
+ * 处理：把 RRF 分数放大到与 boost 可比的量级（×100），使**相关性主导、治理项做同分位微调**。
+ * 该系数进入 rankingVersion 快照（权重变更即版本变更）。
+ */
+export const RRF_SCORE_SCALE = 1000
+
+export interface RerankWeights {
+  scopeBoost: number
+  kindBoost: Record<string, number>
+  importanceBoost: number
+  confidenceBoost: number
+  mandatoryConstraintBoost: number
+  stalePenalty: number
+  conflictPenalty: number
+  redundancyPenalty: number
+}
+
+/** 默认权重（v1）：强约束信号最强，stale/冲突/冗余显著惩罚 */
+export const DEFAULT_WEIGHTS: RerankWeights = {
+  scopeBoost: 0.15, // × (scopeRank/7)
+  kindBoost: { CONSTRAINT: 0.25, DECISION: 0.15, FAILURE: 0.1, PITFALL: 0.1, CONVENTION: 0.05 },
+  importanceBoost: 0.2, // × importance
+  confidenceBoost: 0.1, // × confidence
+  mandatoryConstraintBoost: 0.5, // 适用 scope 内的 ACTIVE CONSTRAINT
+  stalePenalty: 0.3,
+  conflictPenalty: 0.2,
+  redundancyPenalty: 0.1,
+}
+
+export interface RerankInput {
+  memoryId: string
+  rrfScore: number
+  kind: string
+  status: MemoryStatus
+  importance: number
+  confidence: number
+  scopeType: string
+  scopeValue: string
+  /** 与已选高分项近重复（由 context-builder 阶段标记，重排阶段先打罚分） */
+  redundant?: boolean
+  /** 与其他候选项存在未决冲突 */
+  conflicted?: boolean
+}
+
+export interface RerankResult {
+  memoryId: string
+  finalScore: number
+  scoreBreakdown: Record<string, number>
+  whySelected: string[]
+}
+
+export function rerankOne(
+  input: RerankInput,
+  scopeCtx: ScopeContext,
+  weights: RerankWeights = DEFAULT_WEIGHTS,
+): RerankResult {
+  const rank = scopeRank(input.scopeType as Parameters<typeof scopeRank>[0]) / 7
+  const scopeBoost = weights.scopeBoost * rank
+  const kindBoost = weights.kindBoost[input.kind] ?? 0
+  const importanceBoost = weights.importanceBoost * input.importance
+  const confidenceBoost = weights.confidenceBoost * input.confidence
+  const mandatory =
+    input.kind === "CONSTRAINT" && input.status === "ACTIVE" ? weights.mandatoryConstraintBoost : 0
+  const stalePenalty = input.status === "STALE" ? weights.stalePenalty : 0
+  const conflictPenalty = input.conflicted ? weights.conflictPenalty : 0
+  const redundancyPenalty = input.redundant ? weights.redundancyPenalty : 0
+
+  const finalScore =
+    input.rrfScore + scopeBoost + kindBoost + importanceBoost + confidenceBoost + mandatory
+    - stalePenalty - conflictPenalty - redundancyPenalty
+
+  const why: string[] = [`rrf=${input.rrfScore.toFixed(4)}`]
+  if (scopeBoost > 0) why.push(`scopeBoost(${input.scopeType}:${input.scopeValue})`)
+  if (kindBoost > 0) why.push(`kindBoost(${input.kind})`)
+  if (mandatory > 0) why.push("mandatoryConstraint")
+  if (stalePenalty > 0) why.push("stalePenalty（诊断模式）")
+  if (conflictPenalty > 0) why.push("conflictPenalty")
+  if (redundancyPenalty > 0) why.push("redundancyPenalty")
+
+  return {
+    memoryId: input.memoryId,
+    finalScore,
+    scoreBreakdown: {
+      rrfScore: input.rrfScore,
+      scopeBoost,
+      kindBoost,
+      importanceBoost,
+      confidenceBoost,
+      mandatoryConstraintBoost: mandatory,
+      stalePenalty: -stalePenalty,
+      conflictPenalty: -conflictPenalty,
+      redundancyPenalty: -redundancyPenalty,
+    },
+    whySelected: why,
+  }
+}

package/templates/core/scripts/mcp-server/shared/memory/retrieval/types.ts

@@ -0,0 +1,52 @@
+/*
+ * 检索管线公共类型（Plan §7/§8.1）
+ */
+import type { MemoryStatus } from "../domain/state-machine.js"
+import type { ScopeContext } from "../domain/scope.js"
+
+export interface RankedId {
+  memoryId: string
+  rank: number
+  score?: number
+}
+
+export interface RecallFilter {
+  repositoryRef: string
+  statuses: readonly MemoryStatus[]
+  scopeCtx: ScopeContext
+  kinds?: string[]
+  /** validUntil 过滤基准时刻 */
+  now: Date
+}
+
+export interface ComponentHealth {
+  component: string
+  status: "ok" | "degraded" | "unavailable" | "disabled"
+  detail?: string
+}
+
+export interface LexicalSearchAdapter {
+  readonly id: string
+  search(query: string, filter: RecallFilter, limit: number): Promise<RankedId[]>
+  health(): Promise<ComponentHealth>
+}
+
+/** 最小原生 SQL 查询接口：PG/SQLite adapter 与测试桩共用（生产由 prisma.$queryRawUnsafe 适配） */
+export interface RawQuerier {
+  query<T = Record<string, unknown>>(sql: string, params: unknown[]): Promise<T[]>
+}
+
+/** recall_memory 返回项（Plan §6.2：必须结构化，不依赖模型从自由文本推断） */
+export interface RecalledMemory {
+  memoryId: string
+  kind: string
+  topic: string
+  content: string
+  scope: { type: string; value: string }
+  confidence: number
+  importance: number
+  sourceRefs: string[]
+  whySelected: string[]
+  scoreBreakdown: Record<string, number>
+  supersedes: string[]
+}