dsh-data-domain-knowledge 0.1.0-alpha.1

package/src/runtime.ts

@@ -0,0 +1,3069 @@
+import { createHash } from 'node:crypto'
+import { spawn, type ChildProcessWithoutNullStreams } from 'node:child_process'
+import { existsSync } from 'node:fs'
+import { appendFile, mkdir, readFile, readdir, rename, rm, rmdir, stat, unlink, writeFile } from 'node:fs/promises'
+import { basename, dirname, extname, isAbsolute, join, relative, resolve, sep } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import {
+  buildSourceTypeCatalog, defaultSourceTypes, DEFAULT_KNOWLEDGE_CONFIG, deriveSourceExt,
+  FALLBACK_EMBEDDING_MODEL, FALLBACK_RERANK_MODEL, legacyResourceHome, SOURCE_TYPE_ID_PATTERN,
+  LOCAL_EMBEDDING_MODEL_DIR, LOCAL_RERANK_MODEL_DIR,
+  type CardSchemaIssue, type ContextGraph, type ContextItem, type DocumentVersion, type Envelope,
+  type KnowledgeAssetRef, type KnowledgeCard, type KnowledgeConfig, type KnowledgeDocument,
+  type KnowledgeDocumentDetail, type KnowledgeError, type KnowledgeStatus, type KnowledgeUnit,
+  type RecallDiagnostics, type RecallEvidence, type RecallHit, type RecallMode, type RecallResult, type RecallRoute, type RecallRouteDiagnostic, type RebuildReport,
+  type RerankResult, type RuntimeKnowledgeConfig, type SchemaType, type SearchHit, type SourceRaw, type SourceRawRead, type SourceType,
+  type SourceTypeCatalog, type SourceTypeDef, type WikiCardVersion, type WikiNote,
+  type WikiSchemaMode, type WikiTypeCatalog, type WikiTypeDef,
+} from './types.js'
+import { defaultWikiTypes, validateCardAgainstType, WIKI_TYPE_RULES } from './wiki-types.js'
+import { buildAliasIndex, candidateEntityId, extractCandidates, normalizeCandidates, RELATES_TO, type NormalizedCandidates } from './extract.js'
+import { extractWithModel, type ModelCall } from './extract-model.js'
+import { FTS_FILE, FtsIndex, loadSqlite, segment } from './fts.js'
+import { applyRerank, applyThreshold, evidenceExcerpts, graphBoost, matchOf, noteIndexText, rrfFuse, selectContext, tokenSet, type RouteRanking } from './recall-rank.js'
+import { legacyKnowledgeRoot } from './layout.js'
+import { envelopeFailure, envelopeSuccess } from 'dsh-data-contracts/envelope'
+import type { LineageContext, LineageRef } from 'dsh-data-contracts/refs'
+
+// 05_diagnosis 是派生层（智能归因图谱）：内容可由 02_wiki + 03_compiled 重建，
+// 和 03_compiled 同性质，所以给独立编号段而不是塞进源头目录。
+//
+// `00_schema` 在 0030 被撤掉了：它从建出来那天起就是一个**空目录**。分类注册表
+// 与 Wiki 类型注册表一直住在 `<agentRoot>/resource/knowledge-bases.json`（那是
+// 配置，跟着根路径走，见 `knowledge-bases.ts`），而这个段里没有一行代码写过东西。
+// 「磁盘上有一个文件夹」本身是一种承诺，承诺了却空着就是误导。
+const LAYOUT = ['01_source_truth', '02_wiki', '03_compiled', '05_diagnosis'] as const
+/**
+ * SourceRaw 段。段内**按来源分类再分一层**：`<段>/<source_type>/<docSlug>.md`。
+ *
+ * 平铺在真实使用里会先变成垃圾场：几十份来源混在一层，`ls` 读不出「我的指标口径在
+ * 哪」。而分类本来就是每份来源的必备元数据（frontmatter 的 `source_type`），把它
+ * 提到目录名上，是让「按分类找东西」在文件系统层面直接成立 —— 不依赖界面。
+ *
+ * 读路径不依赖这个层级：`sourceIndex()` 递归扫全段建 slug → path 索引，所以旧
+ * 平铺布局与迁移中间态都照常可读（见 `migrateSourceTruthLayout`）。
+ */
+const SOURCE_TRUTH = '01_source_truth'
+/** Wiki 段；段内按 `entity_type` 分目录（与 SourceRaw 的分类分层同一个思路）。 */
+const WIKI = '02_wiki'
+const STATUS: KnowledgeStatus[] = ['unreviewed', 'draft', 'reviewed', 'active', 'deprecated', 'problem']
+const SAFE_ID = /^[a-zA-Z0-9._:-]{1,160}$/
+const VECTOR_MANIFEST = 'vector-manifest.json'
+const VECTOR_BINARY = 'vectors.binary'
+const VECTOR_INT8 = 'vectors.int8'
+const VECTOR_QUANTIZATION = 'binary+hamming+int8' as const
+/**
+ * 编码实现的指纹（0031）。
+ *
+ * 它与 `provider` / `model` 是**两件事**：同一个模型、同一份权重，换了「怎么调它」就足以
+ * 让已有向量全部作废 —— 0031 正是这种情况：修复前 WeMM 走 SentenceTransformers 包装路径，
+ * 对任何输入返回同一个向量；改成官方 processor 路径之后，同样的模型名会产出完全不同的向量。
+ *
+ * 没有它就会踩这个坑（实测）：`rebuild all` 看到 44 条 note 的 contentHash 一个都没变，
+ * 于是把**旧的退化向量**原样复制过来，修复等于没发生 —— 而且构建还报 `reused: 44`，
+ * 读起来像「一切正常，没什么要重算的」。
+ *
+ * 所以：**改编码路径时必须一起改这个值**。
+ */
+const ENCODER_FINGERPRINT = 'wemm-official-processor-v1'
+/** Stage 2 output consumed by stage 3 recall. */
+const WIKI_NOTES = 'wiki_notes.json'
+/** Pre-0014 artifact name; kept readable so an upgrade does not force a rebuild. */
+const LEGACY_UNITS = 'knowledge_units.json'
+/**
+ * SourceRaw version snapshots live under `04_memory/source-versions/<docSlug>/`.
+ * One file per historical revision, named `<compactIso>-<contentHash8>.md` and
+ * holding the *original markdown file bytes* so a rollback is byte-faithful.
+ */
+const SOURCE_VERSIONS = 'source-versions'
+/**
+ * Wiki card version snapshots live under
+ * `04_memory/card-versions/<entityType>/<entityId>/`.
+ *
+ * The SourceRaw layer has had version history since 0018; the wiki layer — the
+ * thing an Agent actually recalls and the thing a compile run rewrites — had
+ * none until 0025. Two layers, one versioning model: same directory shape, same
+ * `<compactIso>-<hash8>.md` naming, same append-only rule, so "回滚本身也可回滚"
+ * holds on both sides without a second mechanism to learn.
+ */
+const CARD_VERSIONS = 'card-versions'
+/**
+ * Pass 0 抽出的**关系**（0029）。
+ *
+ * 0025 起抽取是增量的：指纹没变的来源一次都不抽。但抽出来的关系原来只活在**本次
+ * 运行的内存里**（`ExtractionOutcome.relations`），没有任何持久化 —— 于是任何一次
+ * 全量重编（所有来源都被指纹跳过 → 关系为空）都会把图上**已经连上的 `relates_to`
+ * 边全部抹掉**，而报告写 `relationsExtracted=0 / dropped=0`，读起来像「本来就没有
+ * 关系」。实跑复现：`rebuild(wiki)` 得到 1 条 relates_to，紧接着 `rebuild(all)` 之后
+ * 归零且再也回不来。
+ *
+ * 所以关系按来源落一份产物：重编时**跳过的来源从这里读回它自己的关系**，新抽的
+ * 覆盖进去。它是派生数据（可由 SourceRaw 重算），所以放在 `03_compiled/`；删掉它
+ * 只会让下一次重建把关系重新抽一遍。
+ */
+const EXTRACTED_RELATIONS = 'extracted_relations.json'
+/** Sections shorter than this stay in a single note; longer cards split by heading. */
+const NOTE_SPLIT_MIN_CHARS = 800
+/**
+ * 边类型 → 查询里可能用来指代它的词。
+ *
+ * 图召回早就支持「按关系类型命中」，但它只认英文写法：`supported_by` 要写成
+ * "supported by" 才命中，而中文提问不会这么写。Pass 0 新增的 `relates_to` 同理。
+ * 两种边都补上中文同义词，这条召回路径才不是只对英文有效。
+ */
+const RELATION_QUERY_WORDS: Record<string, string> = {
+  supported_by: 'supported by source 来源 出处 依据 支撑',
+  [RELATES_TO]: 'relates to related 相关 关联 关系 有关',
+}
+/**
+ * 融合与阈值的常数（0031）。
+ *
+ * `RRF_K` 与两路权重直接采用 WeKnora 的出厂值（k=60，向量 0.7 / 关键词 0.3）——
+ * 「不从零调参」比「我们自己的猜测」更可辩护，但两边的语料与模型不同，仍要按评测校准。
+ */
+const RRF_K = 60
+const RRF_WEIGHTS = { fts: 0.3, vector: 0.7, graph: 0.2 } as const
+/** 图谱只是 boost，不是路：它的权重只作用在**已经在候选池里**的条目上（见 `graphBoost`）。 */
+const GRAPH_BOOST_WEIGHT = RRF_WEIGHTS.graph
+/**
+ * 编码器健康门的判据：两段无关文本的余弦必须低于它。
+ *
+ * 0.99 不是一个「调出来的」阈值，而是一条分界线：真正编码不同文本的模型不会给出
+ * 0.99+ 的余弦，而 0030 那个坏掉的路径给的是 1.000000。
+ */
+const ENCODER_SELF_SIMILARITY_MAX = 0.99
+/**
+ * 关键词路的**查询词覆盖率下限**（0031）。
+ *
+ * 为什么除了阈值还需要它：关键词的分是按本次最高分归一化的，所以「整批都弱」时最弱的
+ * 那条也会被归一成 1.0 并轻松过 `keywordThreshold` —— 相对阈值挡得住弱命中，挡不住
+ * 「只有弱命中」。实测：`完全无关的词汇zzz` 只蹭到一个「的」，归一化后照样过 0.3。
+ *
+ * 覆盖率是**绝对**的：命中里出现的查询词占查询全部词的比例。只蹭到一个高频单字 = 覆盖
+ * 率极低，直接淘汰；真正相关的段落会同时命中若干双字词，覆盖率自然上去。它是结构性
+ * 守卫（像「图谱不能制造候选」一样），不是需要用户调的分 —— 所以它是常数，不是设置项。
+ */
+const MIN_QUERY_COVERAGE = 0.25
+/** 每条命中最多带几段证据原文。 */
+const EVIDENCE_PER_HIT = 3
+/** 同一张 wiki 最多几条进上下文：否则 5 条上下文可能全是同一张卡的不同小节。 */
+const CONTEXT_PER_WIKI_CAP = 2
+const BIT_COUNTS = Array.from({ length: 256 }, (_, value) => {
+  let count = 0
+  for (let bit = value; bit !== 0; bit &= bit - 1) count += 1
+  return count
+})
+
+interface VectorItem {
+  unitId: string
+  contentHash: string
+}
+
+interface VectorManifest {
+  version: number
+  createdAt: string
+  provider: KnowledgeConfig['embeddingProvider']
+  model: string
+  /**
+   * 编码实现的指纹（0031）。旧清单没有这个字段 → 视为不兼容，于是修复编码器之后
+   * 一定触发一次真正的重编码，而不是把旧向量按 contentHash 复用回来。
+   */
+  encoder?: string
+  device: string
+  dimension: number
+  quantization: typeof VECTOR_QUANTIZATION
+  itemCount: number
+  items: VectorItem[]
+}
+
+interface LoadedVectorIndex {
+  manifest: VectorManifest
+  binary: Buffer
+  int8: Buffer
+}
+
+interface EmbeddingInput {
+  text: string
+  image?: string
+}
+
+interface EmbeddingBuildResult {
+  status: 'ready' | 'unavailable' | 'skipped'
+  count: number
+  reused: number
+  dimension?: number
+  device?: string
+  error?: string
+}
+
+/**
+ * Pass 0（候选抽取 + 归一）一次运行的结果。
+ *
+ * 计数器在这里是**累加**出来的，不是事后算的：每个数都对应上面一次真实的
+ * `writeCard` 调用或一次指纹比较。关系先收集、等图装配时才知道能不能连上，
+ * 所以 `relationsExtracted` / `relationsDropped` 不在这里，而在 `applyExtractedRelations`。
+ */
+interface ExtractionOutcome {
+  extractionHashes: Record<string, string>
+  candidatesExtracted: number
+  candidatesRejected: number
+  cardsCreated: number
+  cardsMerged: number
+  sourcesExtracted: number
+  sourcesSkipped: number
+  relations: Array<{ fromKey: string; toKey: string; relation: string; sourceId: string }>
+  /**
+   * 按来源分组的关系。`relations` 是它的扁平视图（喂给 `applyExtractedRelations`），
+   * 这一份是**要落盘的形态** —— 跳过的来源下次重建靠它把关系读回来。
+   */
+  relationsBySource: Record<string, Array<{ fromKey: string; toKey: string; relation: string; sourceId: string }>>
+  warnings: string[]
+}
+
+/**
+ * Both helpers delegate to the shared envelope constructors: the five-key shape
+ * and the "warnings ⇒ partial" rule live in `dsh-data-contracts`,
+ * so a knowledge response and a workbook response cannot disagree about status,
+ * and neither can forget `error: null` on the happy path.
+ */
+export function success<T>(data: T, warnings: string[] = []): Envelope<T> { return envelopeSuccess<T, KnowledgeError>(data, warnings) }
+export function failure<T>(data: T, code: string, message: string, retryable = true, suggestion?: string): Envelope<T> {
+  const error: KnowledgeError = { code, message, retryable, ...(suggestion ? { suggestion } : {}) }
+  return envelopeFailure<T, KnowledgeError>(data, error)
+}
+
+function slug(value: string): string {
+  const normalized = value.trim().replace(/[^\p{L}\p{N}._-]+/gu, '-').replace(/^-+|-+$/g, '')
+  return normalized.slice(0, 120) || `item-${Date.now().toString(36)}`
+}
+
+function hash(value: string): string { return createHash('sha256').update(value).digest('hex').slice(0, 24) }
+
+/** The content hash used for `KnowledgeDocument.contentHash` and version ids. */
+function contentHashOf(content: string): string { return hash(content) }
+
+/**
+ * 把这次新抽到的正文**追加**进已有卡片的正文。
+ *
+ * 这是「wiki 编译第二条链路」的落点：实体已经在 wiki 里 → 在原卡片上追加；不在 →
+ * 新建一张。追加而不是覆盖，是因为覆盖会把别的来源贡献的内容删掉；而**丢弃**
+ * （第一版的行为）更糟 —— 来源改写了，卡片却永远停在第一次抽取的样子。
+ *
+ * 已经在正文里出现过的那一段不再追加：同一份来源重建、或同一段被两个候选命中时，
+ * 卡片不该越编译越长。判重按整段文本，所以它是幂等的。
+ */
+function appendExtracted(existing: string, additions: string[]): string {
+  let content = existing
+  for (const addition of additions) {
+    const body = addition.trim()
+    if (!body || content.includes(body)) continue
+    content = content ? `${content}\n\n${body}` : body
+  }
+  return content
+}
+
+/**
+ * `2026-01-02T03:04:05.123Z` → `20260102T030405123Z`. Millisecond precision keeps
+ * two overwrites inside the same second from colliding on the same version id.
+ */
+function compactIso(date: Date): string { return date.toISOString().replace(/[-:]/g, '').replace(/\.(\d{3})Z$/, '$1Z') }
+
+/**
+ * Inverse of `compactIso`. Version ids embed the timestamp, so a snapshot's age
+ * is readable from its filename alone — no stat() per row, and the ordering
+ * `cardVersionIds` already does by name is chronological as a side effect.
+ * It lives next to `compactIso` so the two formats cannot drift apart.
+ */
+function expandCompactIso(value: string): string {
+  const match = /^(\d{4})(\d{2})(\d{2})T(\d{2})(\d{2})(\d{2})(\d{3})Z$/.exec(value)
+  return match ? `${match[1]}-${match[2]}-${match[3]}T${match[4]}:${match[5]}:${match[6]}.${match[7]}Z` : ''
+}
+
+function plainRecord(value: unknown): Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value) ? value as Record<string, unknown> : {}
+}
+
+/**
+ * Declared source format of a document. Prefers a real extension from
+ * `metadata.source_path`; otherwise the upstream `source_format` label
+ * (`markdown` / `office` / …); otherwise `markdown`, the store's default shape.
+ */
+function sourceFormatOf(metadata: Record<string, unknown>): string {
+  const sourcePath = typeof metadata.source_path === 'string' ? metadata.source_path.trim() : ''
+  if (sourcePath) {
+    const base = sourcePath.split(/[\\/]/).pop() ?? ''
+    const dot = base.lastIndexOf('.')
+    if (dot > 0 && dot < base.length - 1) return base.slice(dot + 1).toLowerCase()
+  }
+  const format = typeof metadata.source_format === 'string' ? metadata.source_format.trim().toLowerCase() : ''
+  return format || 'markdown'
+}
+
+/** Failure payload for a document lookup that could not produce a detail. */
+function emptyDocumentDetail(docId: string): KnowledgeDocumentDetail {
+  return {
+    docId, title: docId, sourceType: '', sourceTypeKnown: false, sourceFormat: '', parser: '', externalId: '', contentHash: '',
+    bytes: 0, assetCount: 0, createdAt: '', updatedAt: '', versionCount: 0,
+    relativePath: '', ext: '', content: '', frontmatter: {}, assets: [],
+  }
+}
+
+function generatedId(prefix: string): string { return `${prefix}_${hash(`${Date.now()}:${Math.random()}`)}` }
+
+function parseLineage(value: unknown): LineageContext | undefined {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return undefined
+  const record = value as Record<string, unknown>
+  const lineage: LineageContext = {}
+  for (const key of ['sessionId', 'turnId', 'intentId', 'taskId', 'subtaskId', 'parentSubtaskId', 'runId', 'traceId', 'domain'] as const) {
+    if (typeof record[key] === 'string' && record[key].trim()) lineage[key] = record[key].trim().slice(0, 160)
+  }
+  return Object.keys(lineage).length > 0 ? lineage : undefined
+}
+
+function withRun(lineage: LineageContext | undefined, prefix: string): LineageContext | undefined {
+  if (lineage === undefined) return undefined
+  return { ...lineage, runId: lineage.runId ?? generatedId(prefix) }
+}
+
+function parseProvenance(value: unknown): LineageRef[] | undefined {
+  if (!Array.isArray(value)) return undefined
+  const result = value.map(item => {
+    const lineage = parseLineage(item)
+    if (!lineage) return undefined
+    const record = item as Record<string, unknown>
+    return { ...lineage, ...(typeof record.role === 'string' ? { role: record.role as LineageRef['role'] } : {}), ...(typeof record.refType === 'string' ? { refType: record.refType } : {}), ...(typeof record.refId === 'string' ? { refId: record.refId } : {}) }
+  }).filter((item): item is LineageRef => item !== undefined)
+  return result.length > 0 ? result : undefined
+}
+function yamlValue(value: string): unknown {
+  const text = value.trim()
+  if (text === 'true') return true
+  if (text === 'false') return false
+  if (text === 'null') return null
+  if (/^-?\d+(\.\d+)?$/.test(text)) return Number(text)
+  if ((text.startsWith('[') && text.endsWith(']')) || (text.startsWith('{') && text.endsWith('}'))) {
+    try { return JSON.parse(text) } catch { /* keep string */ }
+  }
+  return text.replace(/^['"]|['"]$/g, '')
+}
+
+export function parseMarkdown(source: string): { frontmatter: Record<string, unknown>; content: string } {
+  if (!source.startsWith('---')) return { frontmatter: {}, content: source.trim() }
+  const end = source.indexOf('\n---', 3)
+  if (end < 0) return { frontmatter: {}, content: source.trim() }
+  const header = source.slice(3, end).replace(/^\n/, '')
+  const frontmatter: Record<string, unknown> = {}
+  for (const line of header.split(/\r?\n/)) {
+    const separator = line.indexOf(':')
+    if (separator <= 0) continue
+    const key = line.slice(0, separator).trim()
+    frontmatter[key] = yamlValue(line.slice(separator + 1))
+  }
+  return { frontmatter, content: source.slice(end + 4).trim() }
+}
+
+function markdown(frontmatter: Record<string, unknown>, content: string): string {
+  const lines = Object.entries(frontmatter).map(([key, value]) => `${key}: ${typeof value === 'string' ? value : JSON.stringify(value)}`)
+  return `---\n${lines.join('\n')}\n---\n\n${content.trim()}\n`
+}
+
+async function writeTextAtomic(path: string, content: string): Promise<void> {
+  // 原子写需要一个与目标同目录的临时文件，所以目标目录必须先存在。0030 起
+  // SourceRaw 落在 `<段>/<source_type>/` 下，而 `ensureLayout` 只建段目录 —— 少了
+  // 这一行，第一次写某一种分类就会 ENOENT（实测）。
+  await mkdir(dirname(path), { recursive: true })
+  const temporary = `${path}.${process.pid}.${Date.now().toString(36)}.tmp`
+  try {
+    await writeFile(temporary, content, 'utf8')
+    await rename(temporary, path)
+  } finally {
+    await unlinkIfExists(temporary)
+  }
+}
+
+async function writeBufferAtomic(path: string, content: Buffer): Promise<void> {
+  const temporary = `${path}.${process.pid}.${Date.now().toString(36)}.tmp`
+  try {
+    await writeFile(temporary, content)
+    await rename(temporary, path)
+  } finally {
+    await unlinkIfExists(temporary)
+  }
+}
+
+async function unlinkIfExists(path: string): Promise<void> {
+  try {
+    const { unlink } = await import('node:fs/promises')
+    await unlink(path)
+  } catch { /* rename already consumed the temp file */ }
+}
+
+async function filesUnder(root: string): Promise<string[]> {
+  try {
+    const entries = await readdir(root, { withFileTypes: true })
+    const result: string[] = []
+    for (const entry of entries) {
+      const path = join(root, entry.name)
+      if (entry.isDirectory()) result.push(...await filesUnder(path))
+      else if (entry.isFile() && extname(entry.name).toLowerCase() === '.md') result.push(path)
+    }
+    return result
+  } catch { return [] }
+}
+
+async function fileCount(root: string): Promise<number> {
+  try {
+    const entries = await readdir(root, { withFileTypes: true })
+    let count = 0
+    for (const entry of entries) count += entry.isDirectory() ? await fileCount(join(root, entry.name)) : entry.isFile() ? 1 : 0
+    return count
+  } catch { return 0 }
+}
+
+function tokens(text: string): string[] { return text.toLocaleLowerCase().split(/[^\p{L}\p{N}_-]+/u).filter(token => token.length > 1) }
+
+/**
+ * Stage 2: turn one wiki card into recall notes.
+ *
+ * Short cards stay a single note whose content is the historical
+ * `summary + content` payload, so existing recall results and qrels keep
+ * working. Long cards that carry `##`/`###` sections split on those headings
+ * and the summary rides along with the first section.
+ */
+export function splitWikiNotes(card: Pick<KnowledgeCard, 'summary' | 'content'>): Array<{ heading?: string; content: string }> {
+  const summary = card.summary?.trim()
+  const body = card.content.trim()
+  const combined = [summary, body].filter(Boolean).join('\n\n')
+  if (body.length <= NOTE_SPLIT_MIN_CHARS) return [{ content: combined }]
+  const sections = body.split(/\n(?=#{2,4}\s+\S)/).map(section => section.trim()).filter(Boolean)
+  // Keep a top-level preamble (`# title` and intro text) with the first
+  // section instead of emitting a contentless note for it.
+  const preamble = sections[0] !== undefined && !/^#{2,4}\s+\S/.test(sections[0]) ? sections.shift() : undefined
+  if (sections.length < 2) return [{ content: combined }]
+  return sections.map((section, index) => {
+    const heading = section.match(/^#{2,4}\s+(.+)$/m)?.[1]?.trim()
+    const content = [index === 0 ? summary : undefined, index === 0 ? preamble : undefined, section].filter(Boolean).join('\n\n')
+    return { ...(heading ? { heading } : {}), content }
+  })
+}
+
+function markdownImageRefs(content: string): string[] {
+  const refs: string[] = []
+  const pattern = /!\[[^\]]*\]\(\s*(?:<([^>]+)>|([^\s)]+))/g
+  for (const match of content.matchAll(pattern)) {
+    const raw = (match[1] ?? match[2] ?? '').trim()
+    if (!raw || raw.startsWith('data:') || /^https?:\/\//i.test(raw) || raw.startsWith('#')) continue
+    try { refs.push(decodeURIComponent(raw)) } catch { /* malformed image URL; keep the markdown searchable as text */ }
+  }
+  return [...new Set(refs)]
+}
+
+function markdownImagePaths(content: string, baseDir: string): string[] {
+  return markdownImageRefs(content).map(value => isAbsolute(value) ? resolve(value) : resolve(baseDir, value))
+}
+
+async function imageFingerprints(paths: string[]): Promise<string[]> {
+  const result: string[] = []
+  for (const path of paths) {
+    try {
+      const details = await stat(path)
+      result.push(`${path}:${details.size}:${details.mtimeMs}`)
+    } catch {
+      result.push(`${path}:missing`)
+    }
+  }
+  return result
+}
+
+function binaryVector(vector: number[], dimension: number): Buffer {
+  const bytes = Buffer.alloc(Math.ceil(dimension / 8))
+  for (let index = 0; index < dimension; index += 1) if ((vector[index] ?? 0) >= 0) bytes[index >> 3] |= 1 << (index & 7)
+  return bytes
+}
+
+function int8Vector(vector: number[], dimension: number): Buffer {
+  const bytes = Buffer.alloc(dimension)
+  for (let index = 0; index < dimension; index += 1) {
+    const value = Math.max(-127, Math.min(127, Math.round((vector[index] ?? 0) * 127)))
+    bytes.writeInt8(value, index)
+  }
+  return bytes
+}
+
+function signedByte(value: number): number { return value > 127 ? value - 256 : value }
+
+function normaliseVectors(raw: unknown, dimension: number): number[][] {
+  if (!Array.isArray(raw)) throw new Error('EMBEDDING_RESPONSE_INVALID')
+  const vectors = raw.map(item => {
+    if (!Array.isArray(item) || item.length < dimension) throw new Error(`EMBEDDING_DIMENSION_INVALID: expected ${dimension}`)
+    const vector = item.slice(0, dimension).map(Number)
+    if (vector.some(value => !Number.isFinite(value))) throw new Error('EMBEDDING_VALUE_INVALID')
+    const norm = Math.sqrt(vector.reduce((sum, value) => sum + value * value, 0)) || 1
+    return vector.map(value => value / norm)
+  })
+  return vectors
+}
+
+interface PendingWorkerRequest {
+  resolve: (value: any) => void
+  reject: (reason: unknown) => void
+  timer: ReturnType<typeof setTimeout>
+}
+
+/** Keep the WeMM process/model alive across rebuilds and search requests. */
+class JsonLineWorker {
+  private child: ChildProcessWithoutNullStreams | undefined
+  private buffer = ''
+  private pending: PendingWorkerRequest[] = []
+
+  /**
+   * `label` names the subsystem in every failure code this worker can produce.
+   *
+   * The class is generic (`embedding_worker.py` serves both stage 2/3 embedding
+   * and stage 4 rerank), but its codes were hard-coded `EMBEDDING_*`. A rerank
+   * that timed out therefore reported `EMBEDDING_TIMEOUT` — pointing the operator
+   * at a subsystem that was working, while the reranker was the one that never
+   * loaded (measured 2026-09-22).
+   */
+  constructor(private readonly command: string, private readonly args: string[], private readonly cwd: string, private readonly env: NodeJS.ProcessEnv, private readonly label = 'EMBEDDING') {}
+
+  private start(): void {
+    const child = spawn(this.command, this.args, { cwd: this.cwd, env: this.env, stdio: ['pipe', 'pipe', 'pipe'] })
+    this.child = child
+    child.stdout.setEncoding('utf8')
+    child.stderr.resume()
+    child.stdout.on('data', chunk => {
+      this.buffer += String(chunk)
+      const lines = this.buffer.split(/\r?\n/)
+      this.buffer = lines.pop() ?? ''
+      for (const line of lines) {
+        if (!line.trim()) continue
+        let result: any
+        try { result = JSON.parse(line) } catch { continue }
+        const request = this.pending.shift()
+        if (!request) continue
+        clearTimeout(request.timer)
+        if (!result?.ok) request.reject(new Error(String(result?.error ?? `${this.label}_WORKER_ERROR`)))
+        else request.resolve(result)
+      }
+    })
+    child.once('error', error => this.fail(error))
+    child.once('close', code => {
+      if (this.child !== child) return
+      this.child = undefined
+      this.fail(new Error(`${this.label}_WORKER_EXIT_${code ?? 'unknown'}`))
+    })
+  }
+
+  private fail(reason: unknown): void {
+    const child = this.child
+    this.child = undefined
+    if (child && !child.killed) child.kill('SIGTERM')
+    const requests = this.pending.splice(0)
+    for (const request of requests) {
+      clearTimeout(request.timer)
+      request.reject(reason)
+    }
+  }
+
+  request(payload: unknown, timeoutMs: number): Promise<any> {
+    if (!this.child) this.start()
+    return new Promise((resolveWorker, rejectWorker) => {
+      const request = { resolve: resolveWorker, reject: rejectWorker, timer: undefined as unknown as ReturnType<typeof setTimeout> }
+      request.timer = setTimeout(() => {
+        const index = this.pending.indexOf(request)
+        if (index >= 0) this.pending.splice(index, 1)
+        const timeout = new Error(`${this.label}_TIMEOUT`)
+        this.fail(timeout)
+        rejectWorker(timeout)
+      }, timeoutMs)
+      this.pending.push(request)
+      try {
+        this.child!.stdin.write(`${JSON.stringify(payload)}\n`)
+      } catch (error) {
+        const index = this.pending.indexOf(request)
+        if (index >= 0) this.pending.splice(index, 1)
+        clearTimeout(request.timer)
+        rejectWorker(error)
+      }
+    })
+  }
+
+  close(): void { this.fail(new Error(`${this.label}_WORKER_CLOSED`)) }
+}
+
+/**
+ * 来源分类注册表的读取入口。
+ *
+ * 做成 provider 而不是构造时快照：`KnowledgeBases` 缓存的是 runtime 而不是
+ * 注册表，用户在设置里改完分类必须**立刻**对 `add_source` 生效（0013 规范
+ * 第 5 节「新增后必须立刻对 Agent 可见」）。
+ */
+export type SourceTypeProvider = () => SourceTypeDef[]
+
+/** Wiki 卡片类型注册表的读取入口（0024）：类型定义 + schema 生效方式。 */
+export interface WikiSchemaSnapshot {
+  types: WikiTypeDef[]
+  mode: WikiSchemaMode
+}
+export type WikiSchemaProvider = () => WikiSchemaSnapshot
+
+/**
+ * 解析三个「家当」路径（0029）。
+ *
+ * 优先级：**配置里显式写的值**（由构造函数处理）> `<agentRoot>/resource/…`（存在时）
+ * > 旧家当目录 `~/.tita-data-agent/…`（存在时）> 兜底（`python3` / HF 模型名）。
+ *
+ * 旧目录留在链上，是为了让「还没搬家当」与「已经搬完」两种状态都能跑；搬家当这件事
+ * 本身不改变行为，只改变文件在哪。
+ *
+ * `modelId` 把本地模型的**身份**与它的位置解耦：两个已知位置都归一到
+ * `local:<模型目录名>`，所以把模型从旧目录搬进根路径**不会**让向量清单判成
+ * 「配置不匹配」—— 否则一次搬家会让整个索引作废、触发一次全量重编码。
+ */
+function resolveResources(resourceRoot: string | undefined): {
+  python: string
+  embeddingModel: string
+  rerankModel: string
+  modelId: (path: string) => string
+} {
+  const home = legacyResourceHome()
+  const root = resourceRoot ? resolve(resourceRoot) : undefined
+  const firstExisting = (candidates: Array<string | undefined>, fallback: string): string => {
+    for (const candidate of candidates) if (candidate && existsSync(candidate)) return candidate
+    return fallback
+  }
+  const python = firstExisting([
+    root ? join(root, 'python', 'bin', 'python') : undefined,
+    join(home, 'embedding-venv', 'bin', 'python'),
+  ], 'python3')
+  const embeddingModel = firstExisting([
+    root ? join(root, 'models', LOCAL_EMBEDDING_MODEL_DIR) : undefined,
+    join(home, 'models', LOCAL_EMBEDDING_MODEL_DIR),
+  ], FALLBACK_EMBEDDING_MODEL)
+  const rerankModel = firstExisting([
+    root ? join(root, 'models', LOCAL_RERANK_MODEL_DIR) : undefined,
+    join(home, 'models', LOCAL_RERANK_MODEL_DIR),
+  ], FALLBACK_RERANK_MODEL)
+  const modelId = (path: string): string => {
+    for (const base of [root, home]) {
+      if (!base || !path.startsWith(`${base}${sep}`)) continue
+      // `models/<目录名>` 与 `embedding-venv/...` 都去掉容器那一层，两个位置归一。
+      return `local:${relative(base, path).replace(/^models[\\/]/, '')}`
+    }
+    return path
+  }
+  return { python, embeddingModel, rerankModel, modelId }
+}
+
+export interface KnowledgeRuntimeOptions {
+  /** 注册表来源；省略时用出厂内置分类。 */
+  sourceTypes?: SourceTypeProvider
+  /** Wiki 卡片类型来源；省略时用出厂 11 个类型 + `report` 模式。 */
+  wikiSchema?: WikiSchemaProvider
+  /**
+   * 0029：家当目录（`<agentRoot>/resource`）。
+   *
+   * 配置里那三个路径字段（`python` / `embeddingModel` / `rerankModel`）为空时，
+   * 它们从这里解析。省略时退回旧的 `TITA_DATA_AGENT_HOME` —— 独立运行时与单元
+   * 测试不必先造一个根路径。
+   */
+  resourceRoot?: string
+  /**
+   * 0032：这个知识库的记忆段（`<agentRoot>/memory/<知识库 id>`）。
+   *
+   * 版本快照、反馈与访问审计写到这里，**不再写进知识树**。省略时退回
+   * `<rootDir>/04_memory` —— 独立运行时与单元测试不必先造一个根路径，迁移期间
+   * 「还没搬」的知识库也照常能读写。
+   */
+  memoryRoot?: string
+  /**
+   * #3b：模型调用接缝。
+   *
+   * 运行时自己**不认识** `ctx.llm` —— 那是插件层的事。把调用以函数形式注进来，
+   * 运行时才能在 `rebuild` 里用模型做实体抽取与归并（`extract-model.ts`），
+   * 而单元测试可以塞一个假模型进去，不必真的跑一次推理。
+   *
+   * 省略 = 退回纯规则抽取（Pass 0）。那条链路本来就不依赖模型，这条接缝的存在
+   * 不能让「没有模型就跑不动」成为新的前提。
+   */
+  modelCall?: ModelCall
+}
+
+export class KnowledgeRuntime {
+  /** 当前生效的配置。volatile 改动会就地合并进来（见 `updateConfig`），所以它不是只读的。 */
+  config: RuntimeKnowledgeConfig
+  readonly rootDir: string
+  /**
+   * 来源分类注册表的来源（0013）。省略时用出厂内置分类——独立 runtime 与单元
+   * 测试是这个形态；`KnowledgeBases` 会注入「按库读取」的 provider，于是每个
+   * 知识库有自己的注册表，自定义分类立刻对 Agent 可见，不需要重启。
+   */
+  private readonly sourceTypeProvider?: SourceTypeProvider
+  /** Wiki 卡片类型注册表的来源（0024）；省略时用出厂 11 个类型 + `report` 模式。 */
+  private readonly wikiSchemaProvider?: WikiSchemaProvider
+  /**
+   * Id of the knowledge base this runtime serves. `KnowledgeBases` sets it when
+   * it creates/caches a runtime; asset URLs are built from it. Standalone
+   * runtimes keep the default so `/knowledge/assets/default/<rel>` still works.
+   */
+  baseId = 'default'
+  private cards: KnowledgeCard[] = []
+  private units: KnowledgeUnit[] = []
+  private graph: { nodes: Array<Record<string, unknown>>; edges: Array<Record<string, unknown>> } = { nodes: [], edges: [] }
+  /**
+   * `docSlug → 绝对路径` 的 SourceRaw 索引（0030）。
+   *
+   * 有了它，文档 id 不需要携带来源分类也能定位文件 —— `add_source` 允许调用方自
+   * 己给 `source_id`，那串 id 里没有类型信息；而目录层级里有。索引递归覆盖整段，
+   * 所以旧平铺布局、新分类布局、以及两者并存的迁移中间态都能解析。
+   * 写入与删除后必须失效（见 `addSource` / `deleteDocument`）。
+   */
+  private sourceIndex: Map<string, string> | undefined
+  /** 段内布局整理是否已经跑过（每个 runtime 一次）。 */
+  private segmentsOrganized = false
+  private vectorIndex: LoadedVectorIndex | null = null
+  private vectorError: string | undefined
+  private embeddingWorker: JsonLineWorker | null = null
+  /** Separate process so a rerank model failure cannot take embeddings down. */
+  private rerankWorker: JsonLineWorker | null = null
+  /** Cache the first rerank failure; do not respawn a doomed model per recall. */
+  private rerankUnavailable: string | undefined
+  /** 解析后的 Python 解释器路径（配置为空时从家当目录解析）。 */
+  private pythonPath: string
+  /** 解析后的嵌入模型：本地目录或 HF 模型名。 */
+  private embeddingModelPath: string
+  /** 解析后的重排模型。 */
+  private rerankModelPath: string
+  /**
+   * 向量清单里记的**模型身份**。
+   *
+   * 本地模型记 `resource:<相对路径>`，不记绝对路径 —— 否则把根路径搬一次，
+   * 清单里的模型名就对不上，整个向量索引被判成「配置不匹配」而作废，用户会莫名
+   * 收到一次全量重编码。清单该记「是哪一个模型」，不是「它在哪」。
+   */
+  private readonly embeddingModelId: string
+  /**
+   * 这个知识库的记忆段（0032）。
+   *
+   * 它可以**在知识树之外**（正常情况就是 `<agentRoot>/memory/<库 id>`），所以
+   * 不能再走 `safePath` —— 那个守卫的契约是「不许跑出 rootDir」。这里另起一个
+   * `memoryPath`，守卫换成「不许跑出 memoryDir」。
+   */
+  private readonly memoryDir: string
+  /** #3b 的模型调用接缝；undefined = 退回纯规则抽取。 */
+  private readonly modelCall: ModelCall | undefined
+
+  constructor(rootDir: string, config: Partial<RuntimeKnowledgeConfig> = {}, options: KnowledgeRuntimeOptions = {}) {
+    this.rootDir = resolve(rootDir)
+    // `config` 里没有路径字段：这个运行时的位置就是 `this.rootDir`，配置只带
+    // 「怎么算」的参数（embedding / rerank / topK…）。这样就不存在「配置说 A、
+    // 运行时实际在 B」这种两处说法。
+    this.config = { ...DEFAULT_KNOWLEDGE_CONFIG, ...config }
+    this.sourceTypeProvider = options.sourceTypes
+    this.wikiSchemaProvider = options.wikiSchema
+    this.memoryDir = options.memoryRoot ? resolve(options.memoryRoot) : join(this.rootDir, '04_memory')
+    this.modelCall = options.modelCall
+    const resources = resolveResources(options.resourceRoot)
+    this.pythonPath = config.python?.trim() || resources.python
+    this.embeddingModelPath = config.embeddingModel?.trim() || resources.embeddingModel
+    this.rerankModelPath = config.rerankModel?.trim() || resources.rerankModel
+    this.embeddingModelId = resources.modelId(this.embeddingModelPath)
+  }
+
+  /**
+   * 就地应用一份新的运行时配置（0.1.7 的 volatile 改动走这条路）。
+   *
+   * 宿主改 volatile 字段时**不会重载插件**（`Entry._commitVolatile()` 只调
+   * `updateVolatile()` 就地改引用，再发一个 `loader/volatile-update`），所以「设置存下了
+   * 但没有生效」必须由这里兜住 —— 只标 volatile 不应用，就是假设置。
+   *
+   * 大部分字段是**每次调用现读** `this.config` 的（`recall` 读 `recallTopK`、
+   * `sourceTruth` 读 `allowSourceTruth`……），合并进去就生效。但有几类是**建好就缓存**
+   * 的，配置换了却还用旧的，那正是「看起来改了其实没改」：
+   *
+   * - 两个模型进程：解释器或模型路径变了，旧进程跑的还是旧模型；
+   * - 向量索引：维度或模型变了，旧向量与新查询不在同一个空间里，比出来的分没有意义。
+   *
+   * @param patch - 要合并进来的配置片段。
+   */
+  updateConfig(patch: Partial<RuntimeKnowledgeConfig>): void {
+    const previous = this.config
+    this.config = { ...previous, ...patch }
+
+    const modelChanged =
+      previous.embeddingProvider !== this.config.embeddingProvider ||
+      previous.embeddingModel !== this.config.embeddingModel ||
+      previous.embeddingDimension !== this.config.embeddingDimension ||
+      previous.embeddingDevice !== this.config.embeddingDevice ||
+      previous.python !== this.config.python
+    const rerankChanged =
+      previous.rerankProvider !== this.config.rerankProvider ||
+      previous.rerankModel !== this.config.rerankModel ||
+      previous.python !== this.config.python
+
+    if (modelChanged) {
+      this.embeddingWorker?.close()
+      this.embeddingWorker = null
+      // 旧索引建在旧模型/旧维度下，留着它只会给出没有意义的相似度。
+      this.vectorIndex = null
+      this.vectorError = undefined
+    }
+    if (rerankChanged) {
+      this.rerankWorker?.close()
+      this.rerankWorker = null
+      this.rerankUnavailable = undefined
+    }
+    if (patch.python !== undefined) this.pythonPath = patch.python.trim() || this.pythonPath
+    if (patch.embeddingModel !== undefined) this.embeddingModelPath = patch.embeddingModel.trim() || this.embeddingModelPath
+    if (patch.rerankModel !== undefined) this.rerankModelPath = patch.rerankModel.trim() || this.rerankModelPath
+  }
+
+  // ------------------------------------------------- Wiki 卡片类型注册表（0024）
+
+  /** 当前生效的卡片 schema：类型定义 + 生效方式。 */
+  wikiSchema(): WikiSchemaSnapshot {
+    return this.wikiSchemaProvider?.() ?? { types: defaultWikiTypes(), mode: 'report' }
+  }
+
+  /**
+   * Agent 与设置面板共用的类型目录：注册表 + 生效方式 + 内置只读判定规则 +
+   * 现有卡片的三层校验结果（`report` 模式下这是"待补"清单）。
+   */
+  async wikiTypeCatalog(): Promise<Envelope<WikiTypeCatalog>> {
+    const schema = this.wikiSchema()
+    const issues = await this.lintCards()
+    return success({
+      types: schema.types,
+      mode: schema.mode,
+      rules: WIKI_TYPE_RULES,
+      issues: issues.slice(0, 50),
+      issueCount: issues.length,
+    })
+  }
+
+  /** 对已落库的卡片跑三层校验。不写盘，只报告。 */
+  async lintCards(): Promise<Array<CardSchemaIssue & { entityId: string; entityType: string }>> {
+    const schema = this.wikiSchema()
+    const byId = new Map(schema.types.map(def => [def.id, def]))
+    const result: Array<CardSchemaIssue & { entityId: string; entityType: string }> = []
+    for (const card of await this.loadCards()) {
+      const type = byId.get(card.entityType)
+      if (!type) continue
+      for (const issue of validateCardAgainstType(type, card)) {
+        result.push({ ...issue, entityId: card.entityId, entityType: card.entityType })
+      }
+    }
+    return result
+  }
+
+  /**
+   * `write_knowledge_card` 的类型闸门 + 三层校验。
+   *
+   * 返回 `{ type, issues }` 或一个失败信封。是否因 issues 拒绝写入由 `mode` 决定：
+   * `strict` 直接拒绝，`report` 把问题写进卡片并回报——存量卡片因此不会被升级挡在门外。
+   */
+  private cardSchemaGate(input: { entityType: string; title: string; content: string; sourceRefs: string[]; metadata: Record<string, unknown>; owner?: string; summary?: string }):
+  { type: WikiTypeDef; issues: CardSchemaIssue[] } | { error: KnowledgeError } {
+    const schema = this.wikiSchema()
+    const type = schema.types.find(def => def.id === input.entityType)
+    if (!type) {
+      return {
+        error: {
+          code: 'SCHEMA_TYPE_INVALID',
+          message: `未知卡片类型: ${input.entityType}`,
+          retryable: false,
+          suggestion: `先在「知识库设置 → Wiki 类型」里登记它，或调 list_wiki_types 查看可用类型。可用类型: ${schema.types.map(def => def.id).join(' / ')}`,
+        },
+      }
+    }
+    if (!type.enabled) {
+      return {
+        error: {
+          code: 'WIKI_TYPE_DISABLED',
+          message: `卡片类型已停用: ${input.entityType}`,
+          retryable: false,
+          suggestion: '在「知识库设置 → Wiki 类型」里重新启用它，或换一个类型。',
+        },
+      }
+    }
+    return { type, issues: validateCardAgainstType(type, input) }
+  }
+
+  // ------------------------------------------------- 来源分类注册表（0013）
+
+  /** 当前生效的来源分类注册表（含计算字段 `sourceCount`）。 */
+  sourceTypes(): SourceTypeDef[] {
+    return this.sourceTypeProvider?.() ?? defaultSourceTypes()
+  }
+
+  /** Agent 与设置面板共用的分类目录：注册表 + 内置只读判定提示词。 */
+  sourceTypeCatalog(): Envelope<SourceTypeCatalog> {
+    return success(buildSourceTypeCatalog(this.sourceTypes()))
+  }
+
+  /**
+   * `add_source` 的分类闸门。
+   *
+   * 三态区分得很清楚，因为它们的修法完全不同：
+   * - 未知分类 → `SOURCE_TYPE_UNKNOWN`（去注册表里加，或改用一个已存在的 id）；
+   * - 已停用 → `SOURCE_TYPE_DISABLED`（去设置里重新启用，或换一个分类）；
+   * - 兜底分类被停用 → 不可能，`document` 由注册表守卫保证始终启用。
+   */
+  private sourceTypeGate(sourceType: string): KnowledgeError | null {
+    const defs = this.sourceTypes()
+    const def = defs.find(item => item.id === sourceType)
+    if (!def) {
+      return {
+        code: 'SOURCE_TYPE_UNKNOWN',
+        message: `未知来源分类: ${sourceType}`,
+        retryable: false,
+        suggestion: `先调 list_source_types 查看该知识库的分类注册表。可用分类: ${defs.map(item => item.id).join(' / ')}`,
+      }
+    }
+    if (!def.enabled) {
+      return {
+        code: 'SOURCE_TYPE_DISABLED',
+        message: `来源分类已停用: ${sourceType}`,
+        retryable: false,
+        suggestion: '在「知识库设置 → 来源类型」里重新启用它，或改用另一个分类。',
+      }
+    }
+    return null
+  }
+
+  directory(name: typeof LAYOUT[number]): string { return join(this.rootDir, name) }
+  async ensureLayout(): Promise<void> {
+    await Promise.all(LAYOUT.map(name => mkdir(this.directory(name), { recursive: true })))
+    // 记忆段在知识树**外面**（0032），所以要单独建。它与 LAYOUT 一起建的理由相同：
+    // 「目录结构」本身是承诺，用户第一次打开面板就该在磁盘上看到它。
+    await mkdir(this.memoryDir, { recursive: true })
+    // 一次性的段内布局整理（0030）。放在 `ensureLayout` 里而不是构造时：构造发生在
+    // 设置解析的回调链上，那里做 FS 扫描会把启动拖住；而 `ensureLayout` 已经是所有
+    // 写入与统计的入口。实例级标志保证每个 runtime 只扫一次。
+    if (!this.segmentsOrganized) {
+      this.segmentsOrganized = true
+      await this.migrateSourceTruthLayout()
+      await this.dropLegacySchemaSegment()
+    }
+  }
+
+  /**
+   * 0030：把平铺的 `<段>/*.md` 搬进 `<段>/<source_type>/*.md`。
+   *
+   * 三条纪律与 `migrate.ts` 一致：**只动直接躺在段目录下的 `.md`**（已经在子目录里的
+   * 不碰，所以可重入）、**读不出合法 `source_type` 的就留在原地**（宁可少搬，不可搬错
+   * ——分类只是元数据，搬错目录会让人按分类找不到东西）、**失败不回滚也不报错**（
+   * `loadSources` 两种布局都能读，搬不动不影响正确性）。
+   */
+  private async migrateSourceTruthLayout(): Promise<void> {
+    const root = this.directory(SOURCE_TRUTH)
+    let entries
+    try { entries = await readdir(root, { withFileTypes: true }) } catch { return }
+    for (const entry of entries) {
+      if (!entry.isFile() || extname(entry.name).toLowerCase() !== '.md') continue
+      const from = join(root, entry.name)
+      let sourceType = ''
+      try {
+        sourceType = String(parseMarkdown(await readFile(from, 'utf8')).frontmatter.source_type ?? '')
+      } catch { continue }
+      if (!SOURCE_TYPE_ID_PATTERN.test(sourceType)) continue
+      const target = join(root, sourceType, entry.name)
+      try {
+        await mkdir(dirname(target), { recursive: true })
+        await rename(from, target)
+      } catch { /* 搬不动就留在原地：读取不依赖目录层级 */ }
+    }
+    // 目录变了，索引必须重建。
+    this.sourceIndex = undefined
+  }
+
+  /**
+   * 0030：删掉已经被撤掉的 `00_schema` 段。
+   *
+   * **只在它确实是空的时候删。** 这个段从来没被写过东西，但如果用户的目录里恰好
+   * 有人放了文件，那就不属于「没用的空文件夹」了 —— 那种情况下留着并让人自己判断，
+   * 比替他们删掉安全。
+   */
+  private async dropLegacySchemaSegment(): Promise<void> {
+    const path = this.safePath('00_schema')
+    try {
+      const entries = await readdir(path)
+      if (entries.length > 0) return
+      // `rmdir`，不是 `rm`：它在目录非空时会失败，这正好是我们要的保证 —— 万一在
+      // readdir 与删除之间有人放了东西进来，失败比删掉别人的文件安全。
+      // （`rm` 不带 `recursive` 对目录直接抛 EISDIR，什么也不会发生，看着像删了。）
+      await rmdir(path)
+    } catch { /* 不存在、非空、或删不掉都不是错误 */ }
+  }
+
+  private async loadVectorIndex(): Promise<LoadedVectorIndex | null> {
+    if (this.vectorIndex) return this.vectorIndex
+    try {
+      const manifest = JSON.parse(await readFile(this.safePath('03_compiled', VECTOR_MANIFEST), 'utf8')) as VectorManifest
+      if (manifest.quantization !== VECTOR_QUANTIZATION || !Number.isInteger(manifest.dimension) || !Array.isArray(manifest.items)) return null
+      // 编码实现换了 → 盘上这份索引不是「同一个东西」，当作不存在（于是 recall 会如实降级，
+      // 而不是拿一份用别的编码器算出来的向量去排序）。
+      if (manifest.encoder !== ENCODER_FINGERPRINT) return null
+      const binary = await readFile(this.safePath('03_compiled', VECTOR_BINARY))
+      const int8 = await readFile(this.safePath('03_compiled', VECTOR_INT8))
+      const binaryWidth = Math.ceil(manifest.dimension / 8)
+      if (manifest.itemCount !== manifest.items.length || binary.length !== manifest.itemCount * binaryWidth || int8.length !== manifest.itemCount * manifest.dimension) return null
+      this.vectorIndex = { manifest, binary, int8 }
+      return this.vectorIndex
+    } catch {
+      return null
+    }
+  }
+
+  private vectorWorkerPath(): string {
+    return process.env.DSH_EMBEDDING_WORKER || resolve(dirname(fileURLToPath(import.meta.url)), '../../src/python/embedding_worker.py')
+  }
+
+  private async encodeWithOllama(inputs: EmbeddingInput[]): Promise<{ vectors: number[][]; device: string }> {
+    const base = this.config.embeddingBaseUrl.replace(/\/$/, '')
+    const controller = new AbortController()
+    const timer = setTimeout(() => controller.abort(), this.config.embeddingTimeoutMs)
+    try {
+      const body = JSON.stringify({ model: this.embeddingModelPath, input: inputs.map(item => item.text) })
+      const response = await fetch(`${base}/api/embed`, { method: 'POST', headers: { 'content-type': 'application/json' }, body, signal: controller.signal })
+      if (response.status === 404) {
+        // Older Ollama releases expose only the single-prompt endpoint. Do
+        // not silently return one vector for a batch; that used to corrupt
+        // row-to-vector alignment during a rebuild.
+        const legacy: unknown[] = []
+        for (const input of inputs) {
+          const itemResponse = await fetch(`${base}/api/embeddings`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ model: this.embeddingModelPath, prompt: input.text }), signal: controller.signal })
+          if (!itemResponse.ok) throw new Error(`OLLAMA_HTTP_${itemResponse.status}`)
+          const itemPayload = await itemResponse.json() as { embedding?: unknown }
+          if (!Array.isArray(itemPayload.embedding)) throw new Error('OLLAMA_EMBEDDING_RESPONSE_INVALID')
+          legacy.push(itemPayload.embedding)
+        }
+        return { vectors: normaliseVectors(legacy, this.config.embeddingDimension), device: 'ollama' }
+      }
+      if (!response.ok) throw new Error(`OLLAMA_HTTP_${response.status}`)
+      const payload = await response.json() as { embeddings?: unknown; embedding?: unknown }
+      const raw = Array.isArray(payload.embeddings) ? payload.embeddings : payload.embedding ? [payload.embedding] : []
+      return { vectors: normaliseVectors(raw, this.config.embeddingDimension), device: 'ollama' }
+    } finally {
+      clearTimeout(timer)
+    }
+  }
+
+  private async encodeEmbeddings(inputs: EmbeddingInput[]): Promise<{ vectors: number[][]; device: string }> {
+    if (this.config.embeddingProvider === 'none') throw new Error('EMBEDDING_DISABLED')
+    // Keep each JSON response bounded for large stores. The WeMM process is
+    // persistent, so chunking does not reload the 1.8GB model between chunks.
+    const chunkSize = Math.max(1, this.config.embeddingBatchSize * 64)
+    const vectors: number[][] = []
+    let device = this.config.embeddingProvider === 'ollama' ? 'ollama' : this.config.embeddingDevice
+    for (let start = 0; start < inputs.length; start += chunkSize) {
+      const chunk = inputs.slice(start, start + chunkSize)
+      if (this.config.embeddingProvider === 'ollama') {
+        const result = await this.encodeWithOllama(chunk)
+        vectors.push(...result.vectors)
+        device = result.device
+        continue
+      }
+      if (!this.embeddingWorker) this.embeddingWorker = this.spawnWorker()
+      const result = await this.embeddingWorker.request({
+        model: this.embeddingModelPath,
+        device: this.config.embeddingDevice,
+        dimension: this.config.embeddingDimension,
+        batchSize: this.config.embeddingBatchSize,
+        inputs: chunk,
+      }, this.config.embeddingTimeoutMs)
+      vectors.push(...normaliseVectors(result.vectors, this.config.embeddingDimension))
+      device = String(result.device ?? this.config.embeddingDevice)
+    }
+    return { vectors, device }
+  }
+
+  close(): void {
+    this.embeddingWorker?.close()
+    this.embeddingWorker = null
+    this.rerankWorker?.close()
+    this.rerankWorker = null
+  }
+
+  /** Both the encoder and the reranker speak the same JSONL worker protocol. */
+  private spawnWorker(label = 'EMBEDDING'): JsonLineWorker {
+    return new JsonLineWorker(this.pythonPath, [this.vectorWorkerPath()], this.rootDir, process.env, label)
+  }
+
+  private async vectorInputs(units: KnowledgeUnit[]): Promise<Array<{ unit: KnowledgeUnit; input: EmbeddingInput; contentHash: string }>> {
+    const result: Array<{ unit: KnowledgeUnit; input: EmbeddingInput; contentHash: string }> = []
+    for (const unit of units) {
+      const imagePaths = unit.imagePaths ?? []
+      const fingerprints = await imageFingerprints(imagePaths)
+      const text = `${unit.title}\n\n${unit.content}`.slice(0, 120_000)
+      const input: EmbeddingInput = { text, ...(imagePaths[0] ? { image: imagePaths[0] } : {}) }
+      result.push({ unit, input, contentHash: hash(JSON.stringify({ unitId: unit.unitId, text, sourceRefs: unit.sourceRefs, images: fingerprints })) })
+    }
+    return result
+  }
+
+  /** 关键词索引的最近一次失败原因；`undefined` = 上次构建成功。 */
+  private ftsError: string | undefined
+
+  /**
+   * 关键词索引（0031）：FTS5 + BM25，见 `fts.ts`。
+   *
+   * 与向量索引的区别是它**不依赖模型**，所以 `only: 'wiki'` 也重建它 —— 卡片改了、
+   * 关键词索引不跟着改，就会出现「按旧词表召回」。`node:sqlite` 不可用时如实返回
+   * `unavailable`（诊断里会写明），而不是退回 0030 那套对中文无效的计数打分。
+   */
+  private async buildFtsIndex(units: KnowledgeUnit[], sources: SourceRaw[] = []): Promise<'ready' | 'unavailable'> {
+    const byId = new Map(sources.map(source => [source.sourceId, source.title]))
+    const sqlite = await loadSqlite()
+    if (!sqlite) {
+      this.ftsError = '当前 Node 没有 node:sqlite（需要 22.5+）'
+      return 'unavailable'
+    }
+    // 索引的不只是正文，还有这条 note 的**溯源身份**：它引用的 sourceId 与那些来源的标题。
+    //
+    // 这不是锦上添花，而是「图谱降为 boost」之后的必要补偿：boost 只能给已有候选加权，
+    // 不能制造候选，所以「只提到某份来源、没提到任何卡片正文」的查询会一条都召不回
+    // （0031 实测：查 `ledger` 命中 source 节点，但 0 命中）。把溯源身份放进关键词索引，
+    // 「这份台账派生出了哪些结论」就回到关键词路回答 —— 那本来就是词面问题，不是图问题。
+    const titleOf = (sourceId: string): string | undefined => byId.get(sourceId)
+    try {
+      await FtsIndex.build(
+        this.safePath('03_compiled', FTS_FILE),
+        units.map(unit => ({
+          unitId: unit.unitId,
+          title: unit.title,
+          content: noteIndexText({ title: unit.title, content: unit.content, sourceRefs: unit.sourceRefs }, titleOf),
+        })),
+        sqlite.DatabaseSync,
+      )
+      this.ftsError = undefined
+      return 'ready'
+    } catch (cause) {
+      this.ftsError = cause instanceof Error ? cause.message : String(cause)
+      return 'unavailable'
+    }
+  }
+
+  private async buildVectorIndex(units: KnowledgeUnit[], version: number): Promise<EmbeddingBuildResult> {
+    if (this.config.embeddingProvider === 'none') return { status: 'skipped', count: 0, reused: 0 }
+    if (this.config.embeddingDimension % 8 !== 0) return { status: 'unavailable', count: 0, reused: 0, error: 'embeddingDimension 必须是 8 的倍数，才能进行 binary quantization' }
+    const inputs = await this.vectorInputs(units)
+    if (inputs.length === 0) return { status: 'ready', count: 0, reused: 0, dimension: this.config.embeddingDimension, device: 'none' }
+
+    const previous = await this.loadVectorIndex()
+    const compatiblePrevious = previous && previous.manifest.dimension === this.config.embeddingDimension && previous.manifest.provider === this.config.embeddingProvider && previous.manifest.model === this.embeddingModelId && previous.manifest.encoder === ENCODER_FINGERPRINT ? previous : null
+    const previousById = new Map((compatiblePrevious?.manifest.items ?? []).map((item, index) => [item.unitId, { item, index }]))
+    const binaryWidth = Math.ceil(this.config.embeddingDimension / 8)
+    const binary = Buffer.alloc(inputs.length * binaryWidth)
+    const int8 = Buffer.alloc(inputs.length * this.config.embeddingDimension)
+    const pending: typeof inputs = []
+    let reused = 0
+    for (let index = 0; index < inputs.length; index += 1) {
+      const current = inputs[index]!
+      const old = previousById.get(current.unit.unitId)
+      if (old && old.item.contentHash === current.contentHash && compatiblePrevious && old.index < compatiblePrevious.manifest.itemCount) {
+        compatiblePrevious.binary.copy(binary, index * binaryWidth, old.index * binaryWidth, (old.index + 1) * binaryWidth)
+        compatiblePrevious.int8.copy(int8, index * this.config.embeddingDimension, old.index * this.config.embeddingDimension, (old.index + 1) * this.config.embeddingDimension)
+        reused += 1
+      } else pending.push(current)
+    }
+
+    let device = compatiblePrevious?.manifest.device ?? 'cache'
+    try {
+      if (pending.length > 0) {
+        const encoded = await this.encodeEmbeddings(pending.map(item => item.input))
+        if (encoded.vectors.length !== pending.length) throw new Error(`EMBEDDING_COUNT_INVALID: expected ${pending.length}, got ${encoded.vectors.length}`)
+        device = encoded.device
+        const pendingRows = new Map(pending.map((item, index) => [item.unit.unitId, index]))
+        for (let index = 0; index < inputs.length; index += 1) {
+          const row = pendingRows.get(inputs[index]!.unit.unitId)
+          if (row === undefined) continue
+          const vector = encoded.vectors[row]!
+          binaryVector(vector, this.config.embeddingDimension).copy(binary, index * binaryWidth)
+          int8Vector(vector, this.config.embeddingDimension).copy(int8, index * this.config.embeddingDimension)
+        }
+      }
+      /**
+       * 索引多样性断言（0031 的 P0）。
+       *
+       * 编码器坏掉时，44 条 note 会产出**同一份向量**（0030 实测 44 行里 39 行逐字节
+       * 相同），而构建照样报 `ready`、界面照样显示「三路都在跑」。这种索引比没有索引
+       * 更坏：它让排序退化成 `unitId` 字典序，却看起来一切正常。
+       *
+       * 所以写盘之前先数一遍不同的向量。宁可报 unavailable 并把原因写进编码器健康状态，
+       * 也不留下一份骗人的索引。
+       */
+      const dimension = this.config.embeddingDimension
+      const distinct = new Set<string>()
+      for (let row = 0; row < inputs.length; row += 1) distinct.add(int8.subarray(row * dimension, (row + 1) * dimension).toString('base64'))
+      if (inputs.length >= 4 && distinct.size < Math.max(2, Math.ceil(inputs.length / 2))) {
+        this.encoderHealth = { ok: false, reason: `编码器退化：${inputs.length} 条 note 只产出 ${distinct.size} 个不同向量` }
+        throw new Error(`EMBEDDING_INDEX_DEGENERATE: ${inputs.length} 条只产出 ${distinct.size} 个不同向量`)
+      }
+      const manifest: VectorManifest = { version, createdAt: new Date().toISOString(), provider: this.config.embeddingProvider, model: this.embeddingModelId, encoder: ENCODER_FINGERPRINT, device, dimension: this.config.embeddingDimension, quantization: VECTOR_QUANTIZATION, itemCount: inputs.length, items: inputs.map(item => ({ unitId: item.unit.unitId, contentHash: item.contentHash })) }
+      await writeBufferAtomic(this.safePath('03_compiled', VECTOR_BINARY), binary)
+      await writeBufferAtomic(this.safePath('03_compiled', VECTOR_INT8), int8)
+      await writeTextAtomic(this.safePath('03_compiled', VECTOR_MANIFEST), JSON.stringify(manifest, null, 2))
+      this.vectorIndex = { manifest, binary, int8 }
+      this.vectorError = undefined
+      return { status: 'ready', count: inputs.length, reused, dimension: this.config.embeddingDimension, device }
+    } catch (cause) {
+      const error = cause instanceof Error ? cause.message : String(cause)
+      this.vectorError = error
+      return { status: 'unavailable', count: compatiblePrevious?.manifest.itemCount ?? 0, reused, dimension: this.config.embeddingDimension, error }
+    }
+  }
+
+  private async loadCompiledState(): Promise<void> {
+    // Stage 2 writes wiki_notes.json; a store compiled before 0014 only has
+    // knowledge_units.json, which stays readable until the next rebuild.
+    for (const artifact of [WIKI_NOTES, LEGACY_UNITS]) {
+      try {
+        const notes = JSON.parse(await readFile(this.safePath('03_compiled', artifact), 'utf8'))
+        if (Array.isArray(notes) && notes.length > 0) { this.units = notes as KnowledgeUnit[]; break }
+      } catch { /* the first build has not happened yet */ }
+    }
+    try {
+      const graph = JSON.parse(await readFile(this.safePath('03_compiled', 'knowledge_graph.json'), 'utf8'))
+      if (graph && Array.isArray(graph.nodes) && Array.isArray(graph.edges)) this.graph = graph as typeof this.graph
+    } catch { /* the first build has not happened yet */ }
+  }
+
+  private safePath(...parts: string[]): string {
+    const path = resolve(this.rootDir, ...parts)
+    const root = this.rootDir.endsWith(sep) ? this.rootDir : `${this.rootDir}${sep}`
+    if (path !== this.rootDir && !path.startsWith(root)) throw new Error('PATH_OUTSIDE_KNOWLEDGE_ROOT')
+    return path
+  }
+
+  /**
+   * 记忆段里的一个路径（0032）。
+   *
+   * 与 `safePath` 同一套守卫，边界换成 `memoryDir` —— 记忆段现在住在知识树
+   * **外面**（`<agentRoot>/memory/<库 id>`），拿 `safePath` 拼会直接抛
+   * `PATH_OUTSIDE_KNOWLEDGE_ROOT`。两个守卫各自成立，不合并成一个「允许两个根」的
+   * 宽松版本：那样一旦哪个根算错，路径就会悄悄写到别人的目录里去。
+   */
+  private memoryPath(...parts: string[]): string {
+    const path = resolve(this.memoryDir, ...parts)
+    const root = this.memoryDir.endsWith(sep) ? this.memoryDir : `${this.memoryDir}${sep}`
+    if (path !== this.memoryDir && !path.startsWith(root)) throw new Error('PATH_OUTSIDE_MEMORY_ROOT')
+    return path
+  }
+
+  /** 记忆段的真实位置（面板与诊断要显示它，而不是让人以为还在知识树里）。 */
+  get memoryRoot(): string { return this.memoryDir }
+
+  async stats(): Promise<Record<string, unknown>> {
+    await this.ensureLayout()
+    const counts = await Promise.all(LAYOUT.map(item => fileCount(this.directory(item))))
+    if (this.cards.length === 0) this.cards = await this.loadCards()
+    if (this.units.length === 0 && this.graph.nodes.length === 0) await this.loadCompiledState()
+    let buildManifest: {
+      version?: number
+      builtAt?: string
+      cardHashes?: Record<string, string>
+      embedding?: { status?: string; reused?: number; count?: number }
+      compileRunId?: string
+      lastBuild?: {
+        only?: string; incremental?: boolean; skipped?: boolean
+        cardsReused?: number; cardsRecompiled?: number; cardsAdded?: number; cardsRemoved?: number
+        notesReused?: number; notesRecompiled?: number
+        // Pass 0 的计数：面板据此显示「这一轮抽了几个候选、建了几张卡」。
+        candidatesExtracted?: number; candidatesRejected?: number
+        cardsCreated?: number; cardsMerged?: number
+        relationsExtracted?: number; relationsDropped?: number
+        sourcesExtracted?: number; sourcesSkipped?: number
+      }
+    } = {}
+    try {
+      buildManifest = JSON.parse(await readFile(this.safePath('03_compiled', 'build-manifest.json'), 'utf8')) as typeof buildManifest
+    } catch { /* the first build has not happened yet */ }
+    const vector = await this.loadVectorIndex()
+    // 卡片版本快照数：界面要能说清「wiki 也有历史」，而不只是 SourceRaw 有。
+    const cardVersionCount = await fileCount(this.memoryPath(CARD_VERSIONS))
+    const layout = Object.fromEntries(LAYOUT.map((item, index) => [item, counts[index] ?? 0]))
+    return {
+      rootDir: this.rootDir,
+      layout,
+      /** 0032：记忆段的真实位置与落盘文件数。它不在 `layout` 里了 —— 那一段
+       *  已经不是知识树的一段，混进去会让「知识树有哪几段」这个问题的答案漂移。 */
+      memoryRoot: this.memoryDir,
+      memoryFiles: await fileCount(this.memoryDir),
+      /**
+       * 按**段名**取，不按位置取。这里原先是 `counts[1]`，而它之所以曾经是对的，
+       * 只是因为 `LAYOUT[1]` 恰好是 `01_source_truth` —— 0030 撤掉 `00_schema`
+       * 之后同一条表达式就静默变成了「wiki 卡片数」，界面上的来源数直接归零。
+       * 布局的索引是实现的偶然，段名才是契约。
+       */
+      sourceCount: layout[SOURCE_TRUTH] ?? 0,
+      cards: this.cards.length,
+      units: this.units.length,
+      notes: this.units.length,
+      graphNodes: this.graph.nodes.length,
+      graphEdges: this.graph.edges.length,
+      buildVersion: Number(buildManifest.version ?? 0),
+      builtAt: buildManifest.builtAt,
+      trackedCards: Object.keys(buildManifest.cardHashes ?? {}).length,
+      cardVersions: cardVersionCount,
+      lastBuild: buildManifest.lastBuild ?? null,
+      lastCompileRunId: buildManifest.compileRunId,
+      recallTopK: this.config.recallTopK,
+      recallMode: this.config.recallMode,
+      contextTopN: this.config.contextTopN,
+      rerankProvider: this.config.rerankProvider,
+      rerankModel: this.rerankModelPath,
+      embeddingProvider: this.config.embeddingProvider,
+      embeddingModel: this.embeddingModelPath,
+      embeddingDevice: this.config.embeddingDevice,
+      embeddingDimension: vector?.manifest.dimension ?? this.config.embeddingDimension,
+      vectorCount: vector?.manifest.itemCount ?? 0,
+      vectorQuantization: vector?.manifest.quantization ?? VECTOR_QUANTIZATION,
+      searchBackend: vector && vector.manifest.itemCount > 0 ? 'hybrid' : 'fts',
+      embeddingStatus: vector ? 'ready' : this.config.embeddingProvider === 'none' ? 'disabled' : 'unavailable',
+      embeddingError: this.vectorError,
+    }
+  }
+
+  async addSource(input: { sourceType: SourceType; title?: string; content: string; externalId?: string; metadata?: Record<string, unknown>; sourceId?: string; lineage?: LineageContext }): Promise<Envelope<{ sourceId: string; path: string; lineage?: LineageContext }>> {
+    if (!this.config.allowSourceTruth) return failure({ sourceId: '', path: '' }, 'SOURCE_TRUTH_DISABLED', '当前配置禁止写入 SourceTruth', false)
+    // 分类闸门走注册表（0013），不再是硬编码枚举：自定义分类建完即可用。
+    const gate = this.sourceTypeGate(input.sourceType)
+    if (gate) return failure({ sourceId: '', path: '' }, gate.code, gate.message, gate.retryable, gate.suggestion)
+    if (typeof input.content !== 'string' || input.content.trim().length === 0) return failure({ sourceId: '', path: '' }, 'CONTENT_REQUIRED', 'content 不能为空', true)
+    /**
+     * 这里**没有**长度上限（0029 撤掉了 `maxSourceBytes`）。
+     *
+     * 它曾经是 4,000,000 字符的硬上限，而那个设置在 0029 已经从设置面板撤走 —— 于是
+     * 它变成一个**用户改不了、也不知道存在**的闸门：长文档被拒，报的还是「去调大设置里
+     * 那个你已经找不到的字段」。
+     *
+     * 真正的边界在别处，而且各自都有名有姓：转换内核的 `maxInputBytes` 管入口大小，
+     * 嵌入按 `embeddingBatchSize` 分批、并把交给模型的文本切到模型上下文长度。在存储
+     * 这层再留一个谁也不认识的字符数，只会让「这份文档为什么进不来」变成查不到答案的
+     * 问题。留下的只有「不能是空串」那一条 —— 那是语义，不是配额。
+     */
+    await this.ensureLayout()
+    const sourceId = input.sourceId?.trim() || `${input.sourceType}:${hash(input.externalId ?? input.content)}`
+    if (!SAFE_ID.test(sourceId)) return failure({ sourceId: '', path: '' }, 'SOURCE_ID_INVALID', 'source_id 含有非法字符', false)
+    const path = this.sourcePath(sourceId, input.sourceType)
+    /**
+     * 这一份文档**可能已经以另一个分类存在**。0030 起分类是目录名，所以
+     * 「改一个来源的分类」不再是原地覆盖，而是换目录 —— 必须先解析它现在落在哪，
+     * 否则会有两个后果：版本快照比对的是一份不存在的新文件（历史被静默丢掉），
+     * 而旧目录里那份留下来变成孤儿（统计成两个来源、分类永远删不掉）。
+     */
+    const previousPath = await this.sourcePathOf(sourceId)
+    let createdAt = new Date().toISOString()
+    // Version history: before overwriting an existing document whose *body*
+    // changed, snapshot the previous file bytes under
+    // `04_memory/source-versions/<docSlug>/`. The comparison is on the body
+    // only, so re-writing identical content (a common idempotent re-ingest)
+    // does not manufacture a version. Because `revertDocument` calls
+    // `addSource`, a rollback snapshots the pre-rollback head too: history is
+    // append-only and a rollback is itself reversible.
+    let previousRaw: string | undefined
+    if (previousPath !== undefined) { try { previousRaw = await readFile(previousPath, 'utf8') } catch { /* vanished */ } }
+    if (previousRaw !== undefined) {
+      const previous = parseMarkdown(previousRaw)
+      createdAt = String(previous.frontmatter.created_at ?? createdAt)
+      if (previous.content.trim() !== input.content.trim()) {
+        await this.snapshotSource(sourceId, previousRaw, previous.content)
+      }
+    }
+    const record: SourceRaw = { sourceId, sourceType: input.sourceType, title: input.title?.trim() || sourceId, content: input.content, ...(input.externalId ? { externalId: input.externalId } : {}), metadata: input.metadata ?? {}, ...(input.lineage ? { lineage: input.lineage } : {}), createdAt, updatedAt: new Date().toISOString() }
+    await writeTextAtomic(path, markdown({ source_id: sourceId, source_type: input.sourceType, title: record.title, created_at: record.createdAt, updated_at: record.updatedAt, external_id: input.externalId ?? '', metadata: record.metadata, ...(record.lineage ? { lineage: record.lineage } : {}) }, record.content))
+    // 换了分类的那一次：新文件已经落好，旧目录里那份才删 —— 顺序反过来的话，写入
+    // 失败就同时丢了旧的那一份。
+    if (previousPath !== undefined && previousPath !== path) {
+      try { await unlink(previousPath) } catch { /* already moved or removed */ }
+    }
+    this.sourceIndex?.set(slug(sourceId), path)
+    // 证据片段取自 SourceRaw 正文，写入后那份缓存必须失效（否则上下文会引用旧原文）。
+    this.sourceCorpusCache = undefined
+    return success({ sourceId, path, ...(record.lineage ? { lineage: record.lineage } : {}) })
+  }
+
+  /** Directory holding one document's version snapshots. */
+  private versionDir(sourceId: string): string { return this.memoryPath(SOURCE_VERSIONS, slug(sourceId)) }
+
+  /** Write the previous file bytes as one immutable version snapshot. */
+  private async snapshotSource(sourceId: string, raw: string, body: string): Promise<string> {
+    const dir = this.versionDir(sourceId)
+    await mkdir(dir, { recursive: true })
+    const versionId = `${compactIso(new Date())}-${contentHashOf(body).slice(0, 8)}`
+    const path = join(dir, `${versionId}.md`)
+    if (!existsSync(path)) await writeTextAtomic(path, raw)
+    return versionId
+  }
+
+  /** Snapshot file basenames (without `.md`) for one document. */
+  private async versionIds(sourceId: string): Promise<string[]> {
+    try {
+      const entries = await readdir(this.versionDir(sourceId), { withFileTypes: true })
+      return entries.filter(entry => entry.isFile() && entry.name.endsWith('.md')).map(entry => basename(entry.name, '.md')).sort().reverse()
+    } catch { return [] }
+  }
+
+  async loadSources(): Promise<SourceRaw[]> {
+    const result: SourceRaw[] = []
+    for (const path of await filesUnder(this.directory(SOURCE_TRUTH))) {
+      const parsed = parseMarkdown(await readFile(path, 'utf8'))
+      const sourceId = String(parsed.frontmatter.source_id ?? basename(path, '.md'))
+      const sourceType = String(parsed.frontmatter.source_type ?? 'document') as SourceType
+      // 0013：未知分类**不再静默丢弃**。分类只是元数据，内容仍然可召回；
+      // 丢掉文档才是真正的数据损失。未知分类在列表里以「未知分类」呈现。
+      result.push({ sourceId, sourceType, title: String(parsed.frontmatter.title ?? sourceId), content: parsed.content, externalId: typeof parsed.frontmatter.external_id === 'string' && parsed.frontmatter.external_id ? parsed.frontmatter.external_id : undefined, metadata: typeof parsed.frontmatter.metadata === 'object' && parsed.frontmatter.metadata ? parsed.frontmatter.metadata as Record<string, unknown> : {}, ...(parseLineage(parsed.frontmatter.lineage) ? { lineage: parseLineage(parsed.frontmatter.lineage) } : {}), createdAt: String(parsed.frontmatter.created_at ?? ''), updatedAt: String(parsed.frontmatter.updated_at ?? '') })
+    }
+    return result
+  }
+
+  // ------------------------------------------------- 文档（SourceRaw）列表 / 详情
+
+  /**
+   * Absolute path a SourceRaw document is written to.
+   *
+   * 0030：段内按来源分类分目录。`sourceType` 在调用点已经过了注册表闸门
+   * （`addSource` 的 `sourceTypeGate`），所以它一定匹配 `SOURCE_TYPE_ID_PATTERN`，
+   * 不会引入路径穿越。
+   */
+  private sourcePath(sourceId: string, sourceType: string): string {
+    return this.safePath(SOURCE_TRUTH, sourceType, `${slug(sourceId)}.md`)
+  }
+
+  /** 递归扫 SourceRaw 段，建 `docSlug → path` 索引；两种布局都覆盖。 */
+  private async sourceIndexMap(): Promise<Map<string, string>> {
+    if (this.sourceIndex) return this.sourceIndex
+    const index = new Map<string, string>()
+    for (const path of await filesUnder(this.directory(SOURCE_TRUTH))) index.set(basename(path, '.md'), path)
+    this.sourceIndex = index
+    return index
+  }
+
+  /** 已知文档 id 的落盘位置；不存在时 `undefined`（调用方各自决定怎么报错）。 */
+  private async sourcePathOf(docId: string): Promise<string | undefined> {
+    return (await this.sourceIndexMap()).get(slug(docId))
+  }
+
+  /**
+   * Assets a document really has on disk.
+   *
+   * Preferred source of truth is `metadata.assets` (knowledge-root-relative
+   * paths written by `convert/ingest.ts`). Documents written by hand fall back
+   * to parsing local markdown image links. A link is resolved **knowledge-root
+   * first, then relative to the document's own directory**: the convert ingest
+   * seam re-bases assets to `_assets/<bucket>/<name>` (root-relative), while
+   * hand-written docs typically use a sibling path. Only existing files are
+   * returned, so `assetCount` is never an over-count.
+   */
+  private async assetsOf(path: string, content: string, metadata: Record<string, unknown>): Promise<KnowledgeAssetRef[]> {
+    const refs = new Set<string>()
+    if (Array.isArray(metadata.assets)) for (const item of metadata.assets) if (typeof item === 'string' && item.trim()) refs.add(item.trim())
+    for (const ref of markdownImageRefs(content)) refs.add(ref)
+    const root = this.rootDir
+    const insideRoot = (value: string): boolean => value === root || value.startsWith(root.endsWith(sep) ? root : `${root}${sep}`)
+    const assets: KnowledgeAssetRef[] = []
+    const seen = new Set<string>()
+    for (const ref of refs) {
+      const candidates = isAbsolute(ref) ? [resolve(ref)] : [resolve(root, ref), resolve(dirname(path), ref)]
+      for (const absolute of candidates) {
+        if (!insideRoot(absolute)) continue
+        let details
+        try { details = await stat(absolute) } catch { continue }
+        if (!details.isFile()) continue
+        const rel = relative(root, absolute).split(sep).join('/')
+        if (seen.has(rel)) break
+        seen.add(rel)
+        const encoded = rel.split('/').map(segment => encodeURIComponent(segment)).join('/')
+        assets.push({ rel, bytes: details.size, url: `/knowledge/assets/${encodeURIComponent(this.baseId)}/${encoded}` })
+        break
+      }
+    }
+    return assets.sort((left, right) => left.rel.localeCompare(right.rel))
+  }
+
+  /** Parse one on-disk SourceRaw file into the detail projection. */
+  private async readDocumentFile(path: string): Promise<KnowledgeDocumentDetail | undefined> {
+    let raw: string
+    try { raw = await readFile(path, 'utf8') } catch { return undefined }
+    const parsed = parseMarkdown(raw)
+    const sourceId = String(parsed.frontmatter.source_id ?? basename(path, '.md'))
+    const sourceType = String(parsed.frontmatter.source_type ?? 'document')
+    // 未知分类照样投影出来（0013）；前端按 sourceTypeKnown 渲染「未知分类」徽标。
+    const sourceTypeKnown = this.sourceTypes().some(def => def.id === sourceType)
+    const metadata = plainRecord(parsed.frontmatter.metadata)
+    const ext = deriveSourceExt(metadata)
+    const assets = await this.assetsOf(path, parsed.content, metadata)
+    const lineage = parseLineage(parsed.frontmatter.lineage)
+    return {
+      docId: sourceId,
+      title: String(parsed.frontmatter.title ?? sourceId),
+      sourceType,
+      sourceTypeKnown,
+      sourceFormat: sourceFormatOf(metadata),
+      /**
+       * `parser` 说的是**谁解析了这份文档**，不是「它本该被谁解析」。
+       *
+       * 0029 之前这里回退到 `engineForExt(ext)` —— 按扩展名查一张表，猜一个引擎名。
+       * 那是在**编造一个没有发生过的事实**：直接写进来的 SourceRaw（`add_source`、
+       * 浏览器直读文本）根本没有解析器，而猜出来的 `anydoc` 会让人以为它经过了转换
+       * 内核。现在如实写 `direct`：没有解析器。
+       *
+       * 经转换内核进来的文档由 `convert/ingest.ts` 写 `metadata.parser`
+       * （如 `anydoc@1/pdf`），那才是真话。
+       */
+      parser: typeof metadata.parser === 'string' && metadata.parser.trim() ? metadata.parser.trim() : 'direct',
+      externalId: typeof parsed.frontmatter.external_id === 'string' ? parsed.frontmatter.external_id : '',
+      contentHash: contentHashOf(parsed.content),
+      bytes: Buffer.byteLength(raw, 'utf8'),
+      assetCount: assets.length,
+      createdAt: String(parsed.frontmatter.created_at ?? ''),
+      updatedAt: String(parsed.frontmatter.updated_at ?? ''),
+      versionCount: (await this.versionIds(sourceId)).length + 1,
+      relativePath: relative(this.rootDir, path).split(sep).join('/'),
+      ext,
+      content: parsed.content,
+      frontmatter: parsed.frontmatter,
+      assets,
+      ...(lineage ? { lineage: lineage as Record<string, string> } : {}),
+    }
+  }
+
+  /** 文档列表（新→旧），正文/资产明细留在详情接口里。 */
+  async listDocuments(): Promise<KnowledgeDocument[]> {
+    const documents: KnowledgeDocument[] = []
+    for (const path of await filesUnder(this.directory(SOURCE_TRUTH))) {
+      const detail = await this.readDocumentFile(path)
+      if (!detail) continue
+      documents.push({
+        docId: detail.docId, title: detail.title, sourceType: detail.sourceType, sourceTypeKnown: detail.sourceTypeKnown,
+        sourceFormat: detail.sourceFormat,
+        parser: detail.parser, externalId: detail.externalId, contentHash: detail.contentHash, bytes: detail.bytes,
+        assetCount: detail.assetCount, createdAt: detail.createdAt, updatedAt: detail.updatedAt,
+        versionCount: detail.versionCount, relativePath: detail.relativePath, ext: detail.ext,
+      })
+    }
+    return documents.sort((left, right) => right.updatedAt.localeCompare(left.updatedAt) || left.docId.localeCompare(right.docId))
+  }
+
+  /** 文档详情：正文、frontmatter、资产与 lineage。 */
+  async readDocument(docId: string): Promise<KnowledgeDocumentDetail | undefined> {
+    const path = await this.sourcePathOf(docId)
+    return path ? this.readDocumentFile(path) : undefined
+  }
+
+  /**
+   * 版本历史，新→旧。
+   *
+   * 第一条永远是当前 head（`isCurrent: true`，`versionId` 形如
+   * `current-<hash8>`），其后是 `04_memory/source-versions/<docSlug>/` 里的
+   * 历史快照。快照保存的是**被覆盖前的原文件字节**，因此回滚是字节级的。
+   */
+  async listVersions(docId: string): Promise<DocumentVersion[]> {
+    const path = await this.sourcePathOf(docId)
+    if (!path) return []
+    let raw: string
+    try { raw = await readFile(path, 'utf8') } catch { return [] }
+    const head = parseMarkdown(raw)
+    const headHash = contentHashOf(head.content)
+    const versions: DocumentVersion[] = [{
+      versionId: `current-${headHash.slice(0, 8)}`,
+      createdAt: String(head.frontmatter.updated_at ?? ''),
+      contentHash: headHash,
+      bytes: Buffer.byteLength(raw, 'utf8'),
+      sourceFormat: sourceFormatOf(plainRecord(head.frontmatter.metadata)),
+      label: '当前版本',
+      isCurrent: true,
+    }]
+    for (const versionId of await this.versionIds(docId)) {
+      try {
+        const snapshotRaw = await readFile(join(this.versionDir(docId), `${versionId}.md`), 'utf8')
+        const parsed = parseMarkdown(snapshotRaw)
+        const createdAt = String(parsed.frontmatter.updated_at ?? '')
+        versions.push({
+          versionId,
+          createdAt,
+          contentHash: contentHashOf(parsed.content),
+          bytes: Buffer.byteLength(snapshotRaw, 'utf8'),
+          sourceFormat: sourceFormatOf(plainRecord(parsed.frontmatter.metadata)),
+          label: `历史版本 · ${createdAt || versionId}`,
+          isCurrent: false,
+        })
+      } catch { /* snapshot vanished between readdir and read */ }
+    }
+    return versions
+  }
+
+  /**
+   * 回滚到某个历史版本。
+   *
+   * 语义：用快照内容重新调用 `addSource`。因为 `addSource` 在覆盖前会把当前
+   * head 再快照一次，所以**回滚本身也可回滚**，历史只增不减。
+   * `current-<hash8>` 指向当前 head，属于 no-op，直接返回当前详情。
+   */
+  async revertDocument(docId: string, versionId: string): Promise<Envelope<KnowledgeDocumentDetail>> {
+    const path = await this.sourcePathOf(docId)
+    if (path === undefined) return failure(emptyDocumentDetail(docId), 'DOCUMENT_NOT_FOUND', `文档不存在: ${docId}`, true)
+    const head = await this.readDocumentFile(path)
+    if (!head) return failure(emptyDocumentDetail(docId), 'DOCUMENT_NOT_FOUND', `文档不存在: ${docId}`, true)
+    const target = typeof versionId === 'string' ? versionId.trim() : ''
+    if (!target) return failure(head, 'VERSION_ID_REQUIRED', 'versionId 不能为空', false, '用 list_versions / GET /knowledge/documents/:docId/versions 先取版本列表。')
+    if (target.startsWith('current-')) return success(head)
+    const snapshotPath = join(this.versionDir(docId), `${basename(target)}.md`)
+    if (!existsSync(snapshotPath)) return failure(head, 'VERSION_NOT_FOUND', `版本不存在: ${target}`, true)
+    const parsed = parseMarkdown(await readFile(snapshotPath, 'utf8'))
+    const restored = await this.addSource({
+      sourceType: (String(parsed.frontmatter.source_type ?? 'document')) as SourceType,
+      title: typeof parsed.frontmatter.title === 'string' ? parsed.frontmatter.title : undefined,
+      content: parsed.content,
+      externalId: typeof parsed.frontmatter.external_id === 'string' && parsed.frontmatter.external_id ? parsed.frontmatter.external_id : undefined,
+      metadata: plainRecord(parsed.frontmatter.metadata),
+      sourceId: docId,
+      lineage: parseLineage(parsed.frontmatter.lineage),
+    })
+    if (!restored.ok) return failure(head, restored.error?.code ?? 'REVERT_FAILED', restored.error?.message ?? '回滚写入失败', restored.error?.retryable ?? false, restored.error?.suggestion)
+    const document = await this.readDocumentFile(path)
+    if (!document) return failure(head, 'DOCUMENT_NOT_FOUND', `回滚后文档不可读: ${docId}`, true)
+    await this.audit('source_truth.revert', { docId, versionId: target })
+    return success(document)
+  }
+
+  /** 删除文档本体与其版本历史（重新写入同一 sourceId 会从头开始记版本）。 */
+  async deleteDocument(docId: string): Promise<Envelope<{ deleted: true }>> {
+    const path = await this.sourcePathOf(docId)
+    if (path === undefined) return failure({ deleted: true }, 'DOCUMENT_NOT_FOUND', `文档不存在: ${docId}`, true)
+    await unlink(path)
+    this.sourceIndex?.delete(slug(docId))
+    this.sourceCorpusCache = undefined
+    await rm(this.versionDir(docId), { recursive: true, force: true })
+    await this.audit('source_truth.delete', { docId })
+    return success({ deleted: true })
+  }
+
+  async writeCard(input: { entityType: SchemaType; entityId: string; title: string; content: string; sourceRefs: string[]; status?: KnowledgeStatus; summary?: string; /**
+   * 负责人。它属于 0021 §6.4 的卡片信封（智能归因的五类卡片里 `check.owner` 是必填 ——
+   * 「这一步该找谁」和成本、判定阈值一样是执行信息）；其余 entity_type 不使用它。
+   */
+  owner?: string; metadata?: Record<string, unknown>; lineage?: LineageContext; provenance?: LineageRef[] }): Promise<Envelope<{ entityId: string; path: string; lineage?: LineageContext }>> {
+    if (!SAFE_ID.test(input.entityId)) return failure({ entityId: input.entityId, path: '' }, 'ENTITY_ID_INVALID', 'entity_id 必须是稳定且安全的标识符', false)
+    if (!input.title?.trim() || !input.content?.trim()) return failure({ entityId: input.entityId, path: '' }, 'CARD_CONTENT_REQUIRED', 'title 和 content 不能为空', true)
+    if (!Array.isArray(input.sourceRefs) || input.sourceRefs.length === 0) return failure({ entityId: input.entityId, path: '' }, 'SOURCE_REFS_REQUIRED', '知识卡片必须引用 SourceTruth', false)
+    const sourceIds = new Set((await this.loadSources()).map(source => source.sourceId))
+    const missingRefs = input.sourceRefs.filter(sourceRef => !sourceIds.has(sourceRef))
+    if (missingRefs.length > 0) return failure({ entityId: input.entityId, path: '' }, 'SOURCE_REF_NOT_FOUND', `source_refs 引用不存在: ${missingRefs.join(', ')}`, false, '先调用 add_source 写入对应的 SourceTruth')
+    const status = input.status ?? 'unreviewed'
+    if (!STATUS.includes(status)) return failure({ entityId: input.entityId, path: '' }, 'STATUS_INVALID', 'status 不合法', false)
+    // 0024：类型闸门 + 三层校验（format / reference / semantic）。
+    const gate = this.cardSchemaGate({
+      entityType: input.entityType, title: input.title.trim(), content: input.content,
+      sourceRefs: input.sourceRefs, metadata: input.metadata ?? {}, ...(input.owner ? { owner: input.owner } : {}), ...(input.summary ? { summary: input.summary } : {}),
+    })
+    if ('error' in gate) return failure({ entityId: input.entityId, path: '' }, gate.error.code, gate.error.message, gate.error.retryable, gate.error.suggestion)
+    const { issues } = gate
+    const warnings = issues.map(issue => `${issue.level}: ${issue.message}`)
+    if (issues.length > 0 && this.wikiSchema().mode === 'strict') {
+      return failure(
+        { entityId: input.entityId, path: '' },
+        'CARD_SCHEMA_INVALID',
+        `卡片不符合「${gate.type.label}」的 schema：${issues.map(issue => issue.message).join('；')}`,
+        false,
+        '补齐必填小节 / 字段后重试；或在「知识库设置 → Wiki 类型」里把生效方式改为 report（只标记不拦截）。',
+      )
+    }
+    await this.ensureLayout()
+    const path = this.safePath(WIKI, input.entityType, `${slug(input.entityId)}.md`)
+    await mkdir(dirname(path), { recursive: true })
+    const updatedAt = new Date().toISOString()
+    // 卡片和 SourceRaw 一样先快照旧版本再覆盖。判据是**正文**：只改 status 或
+    // provenance（setStatus 就是这么写的）不会凭空造出一个"内容版本"，否则
+    // 「审核一次 = 多一个版本」，版本列表会被状态流转灌满。
+    let createdAt = updatedAt
+    let previousRaw: string | undefined
+    try { previousRaw = await readFile(path, 'utf8') } catch { /* 首次写入这张卡片 */ }
+    if (previousRaw !== undefined) {
+      const previous = parseMarkdown(previousRaw)
+      createdAt = String(previous.frontmatter.created_at ?? createdAt)
+      if (previous.content.trim() !== input.content.trim()) {
+        await this.snapshotCard(input.entityType, input.entityId, previousRaw, previous.content)
+      }
+    }
+    const provenance = [...(input.provenance ?? []), ...(input.lineage ? [{ ...input.lineage, role: 'created' as const, refType: 'knowledge_card', refId: input.entityId }] : [])]
+    // report 模式：把问题留在卡片上，界面据此显示"待补"，而不是静默通过。
+    const metadata = { ...(input.metadata ?? {}), ...(issues.length > 0 ? { schema_issues: issues } : {}) }
+    await writeTextAtomic(path, markdown({ entity_id: input.entityId, entity_type: input.entityType, title: input.title.trim(), status, summary: input.summary ?? '', ...(input.owner ? { owner: input.owner } : {}), source_refs: input.sourceRefs, created_at: createdAt, updated_at: updatedAt, metadata, ...(provenance.length > 0 ? { provenance } : {}) }, input.content))
+    return success({ entityId: input.entityId, path, ...(input.lineage ? { lineage: input.lineage } : {}) }, warnings)
+  }
+
+  /** Directory holding one wiki card's version snapshots. */
+  private cardVersionDir(entityType: SchemaType, entityId: string): string {
+    return this.memoryPath(CARD_VERSIONS, slug(entityType), slug(entityId))
+  }
+
+  /** Write the previous card file bytes as one immutable version snapshot. */
+  private async snapshotCard(entityType: SchemaType, entityId: string, raw: string, body: string): Promise<string> {
+    const dir = this.cardVersionDir(entityType, entityId)
+    await mkdir(dir, { recursive: true })
+    const versionId = `${compactIso(new Date())}-${contentHashOf(body).slice(0, 8)}`
+    const path = join(dir, `${versionId}.md`)
+    if (!existsSync(path)) await writeTextAtomic(path, raw)
+    return versionId
+  }
+
+  /** Snapshot basenames (without `.md`) for one card, newest first. */
+  private async cardVersionIds(entityType: SchemaType, entityId: string): Promise<string[]> {
+    try {
+      const entries = await readdir(this.cardVersionDir(entityType, entityId), { withFileTypes: true })
+      return entries.filter(entry => entry.isFile() && entry.name.endsWith('.md')).map(entry => basename(entry.name, '.md')).sort().reverse()
+    } catch { return [] }
+  }
+
+  /** Resolve one card by id, optionally constrained to a type (ids are unique per type). */
+  async readCard(entityId: string, entityType?: SchemaType): Promise<KnowledgeCard | undefined> {
+    const cards = await this.loadCards()
+    return cards.find(card => card.entityId === entityId && (entityType === undefined || card.entityType === entityType))
+  }
+
+  /**
+   * Version list for one card: the newest snapshot reported as current *plus* the
+   * live head. The head is not itself a snapshot — it is the file on disk — but a
+   * version list that omits what you are looking at is unreadable.
+   */
+  async listCardVersions(entityId: string, entityType?: SchemaType): Promise<WikiCardVersion[]> {
+    const card = await this.readCard(entityId, entityType)
+    if (!card) return []
+    const ids = await this.cardVersionIds(card.entityType, entityId)
+    const versions: WikiCardVersion[] = []
+    for (const versionId of ids) {
+      try {
+        const raw = await readFile(join(this.cardVersionDir(card.entityType, entityId), `${versionId}.md`), 'utf8')
+        const parsed = parseMarkdown(raw)
+        versions.push({
+          versionId,
+          // `<compactIso>` is `YYYYMMDDThhmmssSSSZ`; expand it back to a real ISO
+          // string so the panel formats it like every other timestamp.
+          createdAt: expandCompactIso(versionId.slice(0, versionId.lastIndexOf('-'))) || card.updatedAt,
+          contentHash: contentHashOf(parsed.content),
+          bytes: Buffer.byteLength(raw, 'utf8'),
+          title: String(parsed.frontmatter.title ?? entityId),
+          status: String(parsed.frontmatter.status ?? 'draft'),
+          label: `V${ids.length - versions.length + 1} · ${String(parsed.frontmatter.title ?? entityId)}`,
+          isCurrent: false,
+        })
+      } catch { /* 快照在 readdir 与 read 之间消失了 */ }
+    }
+    versions.unshift({
+      versionId: 'head',
+      createdAt: card.updatedAt || new Date().toISOString(),
+      contentHash: contentHashOf(card.content),
+      bytes: Buffer.byteLength(card.content, 'utf8'),
+      title: card.title,
+      status: card.status,
+      label: `当前 · ${card.title}`,
+      isCurrent: true,
+    })
+    return versions
+  }
+
+  /** 回滚一张卡片到历史快照；写入走 writeCard，所以**回滚前的当前版本也会被快照**。 */
+  async revertCard(entityId: string, versionId: string, entityType?: SchemaType): Promise<Envelope<KnowledgeCard>> {
+    const card = await this.readCard(entityId, entityType)
+    if (!card) return failure({} as KnowledgeCard, 'CARD_NOT_FOUND', `知识卡片不存在: ${entityId}`, true)
+    const target = versionId.replace(/\.md$/, '')
+    // 「当前版本」先判：它没有快照文件，先查文件会得到「版本不存在」，那是在
+    // 用错误的原因回答一个合理的请求。
+    if (String(target) === 'head') return failure(card, 'VERSION_IS_HEAD', '当前版本不能作为回滚目标', false, '从版本列表里选一个历史快照。')
+    const snapshotPath = join(this.cardVersionDir(card.entityType, entityId), `${target}.md`)
+    if (!existsSync(snapshotPath)) return failure(card, 'VERSION_NOT_FOUND', `版本不存在: ${target}`, true)
+    const parsed = parseMarkdown(await readFile(snapshotPath, 'utf8'))
+    const refs = Array.isArray(parsed.frontmatter.source_refs) ? parsed.frontmatter.source_refs.map(String) : card.sourceRefs
+    const status = STATUS.includes(String(parsed.frontmatter.status) as KnowledgeStatus) ? String(parsed.frontmatter.status) as KnowledgeStatus : card.status
+    const restored = await this.writeCard({
+      entityType: card.entityType,
+      entityId,
+      title: String(parsed.frontmatter.title ?? card.title),
+      content: parsed.content,
+      sourceRefs: refs,
+      status,
+      summary: typeof parsed.frontmatter.summary === 'string' ? parsed.frontmatter.summary : card.summary,
+      metadata: typeof parsed.frontmatter.metadata === 'object' && parsed.frontmatter.metadata ? parsed.frontmatter.metadata as Record<string, unknown> : card.metadata,
+    })
+    if (!restored.ok) return failure(card, restored.error?.code ?? 'REVERT_FAILED', restored.error?.message ?? '回滚写入失败', restored.error?.retryable ?? false, restored.error?.suggestion)
+    const next = await this.readCard(entityId, card.entityType)
+    if (!next) return failure(card, 'CARD_NOT_FOUND', `回滚后卡片不可读: ${entityId}`, true)
+    await this.audit('wiki.revert', { entityId, entityType: card.entityType, versionId: target })
+    return success(next)
+  }
+
+  async loadCards(): Promise<KnowledgeCard[]> {
+    const result: KnowledgeCard[] = []
+    for (const path of await filesUnder(this.directory(WIKI))) {
+      const parsed = parseMarkdown(await readFile(path, 'utf8'))
+      const entityId = String(parsed.frontmatter.entity_id ?? basename(path, '.md'))
+      const entityType = String(parsed.frontmatter.entity_type ?? relative(this.directory(WIKI), dirname(path)).split(sep)[0]) as SchemaType
+      // 0024：未知类型**不再静默丢弃**。类型只是元数据，丢掉卡片才是真正的数据损失；
+      // 未知类型在界面上显示成「未登记类型」，由人决定是补登记还是改卡片。
+      const refs = Array.isArray(parsed.frontmatter.source_refs) ? parsed.frontmatter.source_refs.map(String) : []
+      result.push({ entityId, entityType, title: String(parsed.frontmatter.title ?? entityId), status: STATUS.includes(String(parsed.frontmatter.status) as KnowledgeStatus) ? String(parsed.frontmatter.status) as KnowledgeStatus : 'draft', summary: typeof parsed.frontmatter.summary === 'string' ? parsed.frontmatter.summary : undefined, content: parsed.content, sourceRefs: refs, ...(parseProvenance(parsed.frontmatter.provenance) ? { provenance: parseProvenance(parsed.frontmatter.provenance) } : {}), metadata: typeof parsed.frontmatter.metadata === 'object' && parsed.frontmatter.metadata ? parsed.frontmatter.metadata as Record<string, unknown> : {}, updatedAt: String(parsed.frontmatter.updated_at ?? ''), imagePaths: markdownImagePaths(parsed.content, dirname(path)) })
+    }
+    return result
+  }
+
+  async setStatus(entityId: string, status: KnowledgeStatus, problemNote?: string, lineage?: LineageContext): Promise<Envelope<{ entityId: string; status: KnowledgeStatus; lineage?: LineageContext }>> {
+    if (!SAFE_ID.test(entityId) || !STATUS.includes(status)) return failure({ entityId, status }, 'STATUS_INPUT_INVALID', 'entity_id 或 status 不合法', false)
+    const cards = await this.loadCards()
+    const card = cards.find(item => item.entityId === entityId)
+    if (!card) return failure({ entityId, status }, 'CARD_NOT_FOUND', '知识卡片不存在', true)
+    if (status === 'problem' && !problemNote?.trim()) return failure({ entityId, status }, 'PROBLEM_NOTE_REQUIRED', 'status=problem 时必须提供 problem_note', false)
+    if (card.status === 'problem' && status === 'reviewed') return failure({ entityId, status }, 'STATUS_TRANSITION_INVALID', 'problem 不能直接恢复为 reviewed，请先改为 unreviewed', false)
+    const eventLineage = withRun(lineage, 'knowledge-status')
+    const provenance = [...(card.provenance ?? []), ...(eventLineage ? [{ ...eventLineage, role: 'executed' as const, refType: 'knowledge_status', refId: entityId }] : [])]
+    await this.writeCard({ ...card, status, sourceRefs: card.sourceRefs, provenance, metadata: { ...card.metadata, ...(problemNote?.trim() ? { problem_note: problemNote.trim() } : {}) } })
+    return success({ entityId, status, ...(eventLineage ? { lineage: eventLineage } : {}) })
+  }
+
+  /**
+   * Stage 2: compile wiki cards into wikiNotes.
+   *
+   * A note is the unit stage 3 recalls and stage 4 reranks. Every note keeps a
+   * `wikiId` pointer so recall can always resolve the authoritative wiki card,
+   * and the first note of a wiki keeps the historical `<type>:<id>` unitId.
+   *
+   * Split per card (not per corpus) so the incremental rebuild can recompile one
+   * card's notes while keeping every other card's `unitId`s — and therefore their
+   * vectors — exactly as they were.
+   */
+  private compileNotes(cards: KnowledgeCard[], sourceTypes: Map<string, SourceType>): WikiNote[] {
+    return cards.flatMap(card => this.compileCardNotes(card, sourceTypes))
+  }
+
+  private compileCardNotes(card: KnowledgeCard, sourceTypes: Map<string, SourceType>): WikiNote[] {
+    if (card.status === 'problem') return []
+    const notes: WikiNote[] = []
+    const sourceTypesFor = card.sourceRefs.flatMap(ref => { const sourceType = sourceTypes.get(ref); return sourceType ? [sourceType] : [] })
+    for (const [index, chunk] of splitWikiNotes(card).entries()) {
+      const baseId = `${card.entityType}:${card.entityId}`
+      const unitId = index === 0 ? baseId : `${baseId}#${index}`
+      notes.push({
+        unitId,
+        noteId: unitId,
+        entityId: card.entityId,
+        wikiId: card.entityId,
+        entityType: card.entityType,
+        title: chunk.heading ? `${card.title} · ${chunk.heading}` : card.title,
+        ...(chunk.heading ? { heading: chunk.heading } : {}),
+        content: chunk.content,
+        sourceRefs: card.sourceRefs,
+        sourceTypes: sourceTypesFor,
+        ...(card.provenance ? { provenance: card.provenance } : {}),
+        status: card.status,
+        ...(card.imagePaths?.length ? { imagePaths: card.imagePaths } : {}),
+      })
+    }
+    return notes
+  }
+
+  /** 1-hop neighbourhood of a set of wiki cards inside the compiled graph. */
+  private oneHopGraph(keys: Set<string>, includeProblem: boolean): ContextGraph {
+    const visible = (node: Record<string, unknown>) => includeProblem || node.status !== 'problem'
+    const edges = this.graph.edges.filter(edge => keys.has(String(edge.from)) || keys.has(String(edge.to))).slice(0, 50)
+    const ids = new Set(keys)
+    for (const edge of edges) { ids.add(String(edge.from)); ids.add(String(edge.to)) }
+    const nodes = this.graph.nodes
+      .filter(visible)
+      .filter(node => ids.has(`${node.type}:${node.id}`))
+      .slice(0, 50)
+    return { nodes, edges }
+  }
+
+  /**
+   * Stage 4: BERT cross-encoder rerank over the recalled wikiNotes.
+   *
+   * Mirrors the embedding path: a missing model or worker degrades to the
+   * fused score order with an explicit warning instead of faking a score.
+   *
+   * 0031 的两处改动：
+   * 1. **作用在候选池上**，不再是已经截断到 `recallTopK` 的那 10 条 —— 否则重排只能
+   *    换顺序，救不回被融合排到窗口外的那一条（0014 点名的「分层只做了一半」）。
+   * 2. **带阈值**：低于 `threshold` 的一律丢弃，并报出丢了几条。「弃答」主要靠它 ——
+   *    cross-encoder 的分是**跨查询可比**的，而关键词/向量的阈值做不到这一点。
+   *
+   * `threshold` 与 WeKnora 同刻度（**原始 logit**，默认 0.2）；worker 用
+   * `predict_raw` 保证这一点（`predict` 默认会套 sigmoid），`rerankScore` 是
+   * sigmoid 之后的展示值，两者单调等价，排序不受影响。刻度换算集中在
+   * `applyRerank`（纯函数，有测试），这里不再自己乘除。
+   */
+  private async rerankNotes(query: string, hits: RecallHit[], threshold: number): Promise<{ hits: RecallHit[]; result: RerankResult; warning?: string }> {
+    const provider = this.config.rerankProvider
+    if (provider === 'none') return { hits, result: { status: 'skipped', provider, threshold } }
+    if (hits.length < 2) return { hits, result: { status: 'skipped', provider, model: this.rerankModelPath, scored: hits.length, threshold } }
+    if (this.rerankUnavailable) return { hits, result: { status: 'unavailable', provider, model: this.rerankModelPath, error: this.rerankUnavailable, threshold }, warning: `重排不可用，已按融合分数排序：${this.rerankUnavailable}` }
+    try {
+      if (!this.rerankWorker) this.rerankWorker = this.spawnWorker('RERANK')
+      const response = await this.rerankWorker.request({
+        task: 'rerank',
+        model: this.rerankModelPath,
+        device: this.config.embeddingDevice,
+        query,
+        documents: hits.map(hit => `${hit.title}\n\n${hit.content}`.slice(0, 8000)),
+      }, this.config.rerankTimeoutMs)
+      const raw: number[] = Array.isArray(response?.scores) ? (response.scores as unknown[]).map(Number) : []
+      const outcome = applyRerank(raw, hits, threshold)
+      const vocabSize = Number(response?.vocabSize)
+      return {
+        hits: outcome.kept,
+        result: {
+          status: 'ready', provider, model: this.rerankModelPath,
+          scored: outcome.kept.length, threshold, dropped: outcome.dropped,
+          topLogit: outcome.topLogit,
+          ...(Number.isFinite(vocabSize) && vocabSize > 0 ? { vocabSize } : {}),
+        },
+      }
+    } catch (cause) {
+      const error = cause instanceof Error ? cause.message : String(cause)
+      // Drop the worker (a timeout already killed it) and remember the failure
+      // so a later recall does not respawn a doomed model every time.
+      this.rerankWorker?.close()
+      this.rerankWorker = null
+      this.rerankUnavailable = error
+      return { hits, result: { status: 'unavailable', provider, model: this.rerankModelPath, error, threshold }, warning: `重排不可用，已按融合分数排序：${error}` }
+    }
+  }
+
+  /**
+   * Fingerprint of everything a wikiNote is compiled *from*.
+   *
+   * Deliberately excludes the fields that are cheap to refresh on a reused note
+   * (`provenance`, `imagePaths`, `metadata`) and includes the ones that change
+   * what the note says (`title`, `status`, `content`, `sourceRefs`). A card whose
+   * fingerprint is unchanged produces byte-identical notes, so reusing them is
+   * not a shortcut — it is the same answer without the churn.
+   */
+  private cardHashOf(card: KnowledgeCard): string {
+    return contentHashOf(JSON.stringify({ title: card.title, status: card.status, content: card.content, sourceRefs: card.sourceRefs }))
+  }
+
+  /** Previous `wiki_notes.json` (or the pre-0014 mirror), without touching `this.units`. */
+  private async readNotesArtifact(): Promise<WikiNote[]> {
+    for (const artifact of [WIKI_NOTES, LEGACY_UNITS]) {
+      try {
+        const notes = JSON.parse(await readFile(this.safePath('03_compiled', artifact), 'utf8'))
+        if (Array.isArray(notes) && notes.length > 0) return notes as WikiNote[]
+      } catch { /* the first build has not happened yet */ }
+    }
+    return []
+  }
+
+  // ------------------------------------------------- Pass 0 · 候选抽取 + 归一
+
+  /**
+   * 来源的抽取指纹。
+   *
+   * 三项缺一不可：
+   * - **正文**：文档本身变了，抽出来的东西自然要重算；
+   * - **声明式候选**：它们只写在 `metadata` 里（`SourceRaw` 只投影这一块），
+   *   正文不变而声明变了是常见操作，不带上它就会漏抽；
+   * - **启用的类型注册表**：用户新登记一个 wiki 类型后，同一份文档的判型结论会变。
+   *   不把注册表算进指纹，「来源没变就永远不重抽」会把新类型永远锁在门外。
+   */
+  private extractionFingerprint(source: SourceRaw, registryHash: string): string {
+    const declared = ['candidates', 'entities', 'concepts', 'relations']
+      .map(key => plainRecord(source.metadata)[key] ?? null)
+    return contentHashOf(JSON.stringify({
+      sourceId: source.sourceId,
+      content: contentHashOf(source.content),
+      updatedAt: source.updatedAt,
+      declared: contentHashOf(JSON.stringify(declared)),
+      registry: registryHash,
+    }))
+  }
+
+  /** 一次 Pass 0 的真实结果：计数器 + 待装配的关系 + 来源指纹。 */
+  private emptyExtractionOutcome(extractionHashes: Record<string, string>): ExtractionOutcome {
+    return {
+      extractionHashes,
+      candidatesExtracted: 0, candidatesRejected: 0, cardsCreated: 0, cardsMerged: 0,
+      sourcesExtracted: 0, sourcesSkipped: 0, relations: [], relationsBySource: {}, warnings: [],
+    }
+  }
+
+  /**
+   * Pass 0：对指纹变了的来源做候选抽取 + 归一，并把结果落成 wiki 卡片。
+   *
+   * 三条硬约束：
+   * 1. **增量**：指纹没变的来源一次都不抽（这是 0025 增量承诺的一部分）；
+   * 2. **不重写没变的卡片**：合并只追加 `source_refs`，正文不动，所以不会凭空造
+   *    版本快照（`snapshotCard` 只认正文变化）；
+   * 3. **fail-soft**：一个候选被闸门拒绝、甚至一份来源整个抛错，都只记一笔，
+   *    绝不带走整次重建 —— 重建失败比少一张卡片严重得多。
+   */
+  private async runExtractionStage(sources: SourceRaw[], previousHashes: Record<string, string>): Promise<ExtractionOutcome> {
+    const schema = this.wikiSchema()
+    const enabledTypes = schema.types.filter(def => def.enabled)
+    const registryHash = contentHashOf(JSON.stringify(enabledTypes.map(def => ({ id: def.id, description: def.description, examples: def.examples }))))
+    const outcome = this.emptyExtractionOutcome({})
+    /**
+     * 上一轮落下的关系产物。**跳过的来源从这里读回自己的关系** —— 没有这一步，
+     * 一次全量重编就会把图上所有 `relates_to` 边抹掉（见 `EXTRACTED_RELATIONS`）。
+     */
+    const persisted = await this.readExtractedRelations()
+    // 计数器与产物不能由 readdir 的顺序决定，所以先按 sourceId 排序。
+    const ordered = [...sources].sort((left, right) => left.sourceId.localeCompare(right.sourceId))
+    let cards = await this.loadCards()
+    for (const source of ordered) {
+      const fingerprint = this.extractionFingerprint(source, registryHash)
+      outcome.extractionHashes[source.sourceId] = fingerprint
+      if (previousHashes[source.sourceId] === fingerprint) {
+        outcome.sourcesSkipped += 1
+        const kept = persisted[source.sourceId] ?? []
+        if (kept.length > 0) {
+          outcome.relationsBySource[source.sourceId] = kept
+          outcome.relations.push(...kept)
+        }
+        continue
+      }
+      outcome.sourcesExtracted += 1
+      try {
+        cards = await this.extractFromSource(source, cards, enabledTypes, outcome)
+      } catch (cause) {
+        outcome.warnings.push(`来源 ${source.sourceId} 的候选抽取失败，已跳过该来源：${cause instanceof Error ? cause.message : String(cause)}`)
+      }
+    }
+    // 只留这一轮真实存在的来源：删掉的文档不该在图上留下幽灵关系。
+    const alive = new Set(ordered.map(source => source.sourceId))
+    const next: Record<string, ExtractionOutcome['relations']> = {}
+    for (const [sourceId, relations] of Object.entries(outcome.relationsBySource)) {
+      if (alive.has(sourceId)) next[sourceId] = relations
+    }
+    outcome.relationsBySource = next
+    await this.writeExtractedRelations(next)
+    return outcome
+  }
+
+  /** 读回关系产物。文件不在或读不动都当「没有」，不抛。 */
+  private async readExtractedRelations(): Promise<Record<string, ExtractionOutcome['relations']>> {
+    try {
+      const raw = await readFile(this.safePath('03_compiled', EXTRACTED_RELATIONS), 'utf8')
+      const parsed = JSON.parse(raw) as { bySource?: unknown }
+      const bySource = plainRecord(parsed.bySource)
+      const result: Record<string, ExtractionOutcome['relations']> = {}
+      for (const [sourceId, value] of Object.entries(bySource)) {
+        if (!Array.isArray(value)) continue
+        const relations = value.flatMap(entry => {
+          const item = plainRecord(entry)
+          const fromKey = typeof item.fromKey === 'string' ? item.fromKey : ''
+          const toKey = typeof item.toKey === 'string' ? item.toKey : ''
+          const relation = typeof item.relation === 'string' ? item.relation : ''
+          if (!fromKey || !toKey || !relation) return []
+          return [{ fromKey, toKey, relation, sourceId }]
+        })
+        if (relations.length > 0) result[sourceId] = relations
+      }
+      return result
+    } catch { return {} }
+  }
+
+  /** 落盘关系产物。失败只记一笔：它不该带走整次重建。 */
+  private async writeExtractedRelations(bySource: Record<string, ExtractionOutcome['relations']>): Promise<void> {
+    try {
+      await writeTextAtomic(this.safePath('03_compiled', EXTRACTED_RELATIONS), `${JSON.stringify({ version: 1, bySource }, null, 2)}\n`)
+    } catch { /* 写不进去就当这一轮没有产物，下一次重建会重新抽 */ }
+  }
+
+  /** 一份来源的抽取结果：新建候选卡片、把证据来源并进已有卡片、收集关系候选。 */
+  private async extractFromSource(source: SourceRaw, cards: KnowledgeCard[], enabledTypes: WikiTypeDef[], outcome: ExtractionOutcome): Promise<KnowledgeCard[]> {
+    /**
+     * #3b：**模型先抽实体，规则补关系。**
+     *
+     * 规则抽取把「小节标题」当实体身份，实测下来的后果是同一件东西横跨两份文档就
+     * 变成两张卡片（`新建 2 / 并入 0`）—— 追加分支永远不触发。所以实体这一层交给
+     * 模型（它能判断「毛利率变动及其驱动因素」与「毛利率（口径补充）」是同一个东西）。
+     *
+     * 但仍然**照跑一遍规则抽取**，理由有两个：关系候选只有规则会抽（模型这一层不产
+     * 关系），而且模型不可用时它就是那条降级路径。两者不是二选一。
+     */
+    const ruleCandidates = extractCandidates(source, enabledTypes)
+    outcome.candidatesExtracted += ruleCandidates.length
+    const ruleNormalized = normalizeCandidates(ruleCandidates, buildAliasIndex(cards))
+
+    let normalized: NormalizedCandidates = ruleNormalized
+    if (this.modelCall && this.config.extractWithModel) {
+      const modelled = await extractWithModel({ source, wikiTypes: enabledTypes, existing: cards, call: this.modelCall })
+      for (const warning of modelled.warnings) outcome.warnings.push(warning)
+      // 模型一条实体都没给（或者不可用）时，完整退回规则结果，而不是丢掉整轮抽取。
+      if (modelled.fresh.length > 0 || modelled.merges.length > 0) {
+        normalized = { fresh: modelled.fresh, merges: modelled.merges, relations: ruleNormalized.relations }
+      }
+    }
+    const candidates = normalized.fresh
+    if (candidates.length === 0 && normalized.merges.length === 0) return cards
+    const next = [...cards]
+
+    // 先建后并：同一轮里新建的卡片也可能被别名指回，先建才能让后面的合并找得到对象。
+    for (const candidate of normalized.fresh) {
+      /**
+       * 候选**必须带正文**才落卡。
+       *
+       * 0029 实跑发现：这里原来在候选没有正文时拿 `type.template` 顶上，于是
+       * `[[链接]]` 指到、但还没人写过的实体（那时链接候选确实没有正文）会落成一张
+       * **正文是模板**的卡片，而模板里的「（必填：写什么）」会被编进 wikiNotes、
+       * 被召回、被塞进模型的上下文包 —— 管线写出了一张它自己的校验器判为不合格的
+       * 卡片。链接候选现在会带上它所在小节的正文（`extract.ts`），所以这条回退基本
+       * 不会被走到；真走到了就**不落卡**，并如实计数：没有正文 = 没有可说的。
+       */
+      const body = candidate.body?.trim() ?? ''
+      if (!body) {
+        outcome.candidatesRejected += 1
+        outcome.warnings.push(`候选「${candidate.name}」没有任何正文（只在别处被提到，所在小节也没取到），不落卡`)
+        continue
+      }
+      // 重复的写法都进 aliases：判重认的是名字，不是卡片 id（中文名会退化成哈希 id）。
+      const aliases = [...new Set([candidate.name, ...(candidate.aliases ?? [])].map(value => value.trim()).filter(Boolean))]
+      const metadata: Record<string, unknown> = {
+        extraction: 'pass0',
+        candidate_kind: candidate.kind,
+        confidence: candidate.confidence,
+        evidence: {
+          sourceId: candidate.evidence.sourceId,
+          ...(candidate.evidence.heading ? { heading: candidate.evidence.heading } : {}),
+        },
+        ...(aliases.length > 0 ? { aliases } : {}),
+      }
+      const written = await this.writeCard({
+        entityType: candidate.type,
+        entityId: candidateEntityId(candidate.name),
+        title: candidate.name,
+        content: body,
+        sourceRefs: [candidate.evidence.sourceId],
+        status: 'unreviewed',
+        metadata,
+      })
+      if (!written.ok) {
+        outcome.candidatesRejected += 1
+        outcome.warnings.push(`候选「${candidate.name}」未写入（${written.error?.code ?? 'UNKNOWN'}）：${written.error?.message ?? ''}`)
+        continue
+      }
+      outcome.cardsCreated += 1
+      next.push({
+        entityId: written.data.entityId,
+        entityType: candidate.type,
+        title: candidate.name,
+        status: 'unreviewed',
+        content: body,
+        sourceRefs: [candidate.evidence.sourceId],
+        metadata,
+        updatedAt: '',
+      })
+    }
+
+    // 归一：命中的候选把证据来源并进已有卡片。同一张卡片在这一轮里的多次命中合并且只写一次。
+    const targets = new Map<string, { card: KnowledgeCard; keys: string[]; sourceId: string; bodies: string[] }>()
+    for (const merge of normalized.merges) {
+      const card = next.find(item => item.entityId === merge.entityId && item.entityType === merge.entityType)
+      if (!card) continue
+      // 「只在没有的时候追加」：来源已在 source_refs 里就什么都不做 —— 空写也会
+      // 刷新 updated_at，并让「并入了多少张卡」这个计数变成谎话。
+      if (card.sourceRefs.includes(merge.sourceId)) continue
+      const id = `${merge.entityType}:${merge.entityId}`
+      const entry = targets.get(id)
+      if (entry) {
+        if (!entry.keys.includes(merge.key)) entry.keys.push(merge.key)
+        entry.bodies.push(merge.body)
+      } else targets.set(id, { card, keys: [merge.key], sourceId: merge.sourceId, bodies: [merge.body] })
+    }
+    for (const { card, keys, sourceId, bodies } of targets.values()) {
+      const history = Array.isArray(card.metadata.extraction_merges) ? card.metadata.extraction_merges : []
+      // 只留最近 20 条：这是「这张卡被哪些来源判重命中过」的可见痕迹，不是审计日志。
+      const extraction_merges = [...history, { sourceId, keys, at: new Date().toISOString() }].slice(-20)
+      // **追加**而不是覆盖，也不是丢弃：实体已存在时，这次新抽到的正文并进原卡片，
+      // 于是知识是累积的，来源改写了也不会停在旧版本上。
+      const content = appendExtracted(card.content, bodies)
+      const written = await this.writeCard({
+        ...card,
+        content,
+        sourceRefs: [...card.sourceRefs, sourceId],
+        metadata: { ...card.metadata, extraction_merges },
+      })
+      if (!written.ok) {
+        outcome.candidatesRejected += 1
+        outcome.warnings.push(`候选并入卡片「${card.entityId}」失败（${written.error?.code ?? 'UNKNOWN'}）：${written.error?.message ?? ''}`)
+        continue
+      }
+      outcome.cardsMerged += 1
+      // 让后面的来源看到已经追加过的正文与 source_refs，避免重复写入。
+      const index = next.findIndex(item => item.entityId === card.entityId && item.entityType === card.entityType)
+      if (index >= 0) next[index] = { ...card, content, sourceRefs: [...card.sourceRefs, sourceId], metadata: { ...card.metadata, extraction_merges } }
+    }
+
+    outcome.relations.push(...normalized.relations)
+    // 按来源存一份：跳过的来源下次重建要靠它把关系读回来（见 EXTRACTED_RELATIONS）。
+    outcome.relationsBySource[source.sourceId] = [
+      ...(outcome.relationsBySource[source.sourceId] ?? []),
+      ...normalized.relations,
+    ]
+    return next
+  }
+
+  /**
+   * 把关系候选装配成 wiki↔wiki 的边。
+   *
+   * 只有两端都解析到**已存在的 wiki 节点**时才加边，其余丢弃并计数：凭空造一个
+   * 节点会给图上留一个点不开的孤立点，比没有这条边更难解释。自环同理丢弃。
+   * `supported_by`（卡片 → 来源）完全不受影响，它是另一套边。
+   */
+  private applyExtractedRelations(
+    nodeMap: Map<string, Record<string, unknown>>,
+    edges: Array<Record<string, unknown>>,
+    relations: Array<{ fromKey: string; toKey: string; relation: string }>,
+  ): { extracted: number; dropped: number } {
+    const seen = new Set(edges.map(edge => `${String(edge.from)}|${String(edge.to)}|${String(edge.type)}`))
+    let extracted = 0
+    let dropped = 0
+    for (const relation of relations) {
+      const from = relation.fromKey
+      const to = relation.toKey
+      const type = relation.relation || 'relates_to'
+      if (!from || !to || from === to || !nodeMap.has(from) || !nodeMap.has(to)) { dropped += 1; continue }
+      const key = `${from}|${to}|${type}`
+      // 多份来源声明同一条关系是很常见的；它已经连上了，不重复加边，但也不算丢弃。
+      if (!seen.has(key)) { seen.add(key); edges.push({ from, to, type }) }
+      extracted += 1
+    }
+    return { extracted, dropped }
+  }
+
+  async rebuild(only: 'all' | 'schema' | 'wiki' | 'embeddings' = 'all', lineage?: LineageContext, options: { extract?: boolean } = {}): Promise<Envelope<RebuildReport>> {
+    await this.ensureLayout()
+    const startedAt = new Date().toISOString()
+    this.cards = await this.loadCards()
+    const sources = await this.loadSources()
+    const sourceTypes = new Map(sources.map(source => [source.sourceId, source.sourceType]))
+
+    // ------------------------------------------------ previous build state
+    let previousManifest: { version?: number; builtAt?: string; cardHashes?: Record<string, string>; extractionHashes?: Record<string, string>; embedding?: unknown } = {}
+    try {
+      previousManifest = JSON.parse(await readFile(this.safePath('03_compiled', 'build-manifest.json'), 'utf8')) as typeof previousManifest
+    } catch { /* first build */ }
+    const previousVersion = Number(previousManifest.version ?? 0)
+    const previousHashes = previousManifest.cardHashes ?? {}
+    const previousExtractionHashes = previousManifest.extractionHashes ?? {}
+
+    // ------------------------------------------------ Pass 0 · 候选抽取 + 归一
+    /**
+     * Pass 0 只在会走 stage 2 的重建里跑：`embeddings` 是纯向量重编码，不碰 wiki 层。
+     * 关掉时走一条显式的空路径而不是省略——报告里的八个计数必须始终是「真的 0」，
+     * 不能靠缺字段表达，否则读的人分不清「关掉了」和「这一步没有实现」。
+     */
+    const extractEnabled = only !== 'embeddings' && (options.extract ?? this.config.extractCandidates)
+    const extraction = extractEnabled
+      ? await this.runExtractionStage(sources, previousExtractionHashes)
+      : this.emptyExtractionOutcome(previousExtractionHashes)
+    // 抽取刚落过盘：stage 2 必须看到新的卡片清单，否则这一轮建的卡片要等下一次
+    // 重建才进 wikiNotes，用户点了编译却召不回刚抽出来的东西。
+    if (extraction.cardsCreated > 0 || extraction.cardsMerged > 0) this.cards = await this.loadCards()
+    const extractionCounts = {
+      candidatesExtracted: extraction.candidatesExtracted,
+      candidatesRejected: extraction.candidatesRejected,
+      cardsCreated: extraction.cardsCreated,
+      cardsMerged: extraction.cardsMerged,
+      sourcesExtracted: extraction.sourcesExtracted,
+      sourcesSkipped: extraction.sourcesSkipped,
+    }
+    const warnings: string[] = [...extraction.warnings]
+    let relationsExtracted = 0
+    let relationsDropped = 0
+
+    // ------------------------------------------------ stage 2 · compile notes
+    let cardsReused = 0
+    let cardsRecompiled = 0
+    let cardsAdded = 0
+    let notesReused = 0
+    let notesRecompiled = 0
+    const cardHashes: Record<string, string> = {}
+    /**
+     * 复用与「跳过」只发生在**增量编译（`wiki`）**上。
+     *
+     * `all` 是用户点「全量重编」时明确要求的「从头来一遍」：它照样重切所有 wikiNotes、
+     * 照样升版本（向量层的 `contentHash` 复用仍然生效，所以不会真的重编码一遍）。
+     * 把 `all` 也做成「没变就跳过」会让这个按钮变成第二个增量编译，用户就失去了
+     * 那个「我怀疑产物不对，强制重来一次」的手段。
+     */
+    const incremental = only === 'wiki'
+    if (only === 'embeddings') {
+      if (this.units.length === 0) await this.loadCompiledState()
+    } else {
+      const previousNotes = incremental ? await this.readNotesArtifact() : []
+      const previousByWiki = new Map<string, WikiNote[]>()
+      for (const note of previousNotes) {
+        const key = `${note.entityType}:${note.entityId}`
+        const bucket = previousByWiki.get(key)
+        if (bucket) bucket.push(note)
+        else previousByWiki.set(key, [note])
+      }
+      const notes: WikiNote[] = []
+      for (const card of this.cards) {
+        const key = `${card.entityType}:${card.entityId}`
+        const fingerprint = this.cardHashOf(card)
+        cardHashes[key] = fingerprint
+        if (!previousHashes[key]) cardsAdded += 1
+        const kept = incremental && previousHashes[key] === fingerprint ? previousByWiki.get(key) : undefined
+        if (kept && kept.length > 0) {
+          // Reuse the notes verbatim, but refresh the two derived fields that can
+          // change *without* the card changing: a SourceRaw's business type and
+          // the card's provenance chain. Keeping a stale `sourceTypes` would make
+          // a source_type-filtered recall silently miss this card.
+          const sourceTypesFor = card.sourceRefs.flatMap(ref => { const sourceType = sourceTypes.get(ref); return sourceType ? [sourceType] : [] })
+          notes.push(...kept.map(note => ({
+            ...note,
+            sourceTypes: sourceTypesFor,
+            ...(card.provenance ? { provenance: card.provenance } : {}),
+          })))
+          cardsReused += 1
+          notesReused += kept.length
+        } else {
+          const fresh = this.compileCardNotes(card, sourceTypes)
+          notes.push(...fresh)
+          cardsRecompiled += 1
+          notesRecompiled += fresh.length
+        }
+      }
+      this.units = notes
+      const currentKeys = new Set(Object.keys(cardHashes))
+      const cardsRemoved = Object.keys(previousHashes).filter(key => !currentKeys.has(key)).length
+
+      // A wiki rebuild over an unchanged corpus is a no-op, not a new version:
+      // bumping the version there would invalidate the vector cache and every
+      // qrels pointing at it for nothing. `all` never takes this path (see
+      // `incremental` above).
+      const corpusChanged = !incremental || previousVersion === 0 || cardsRecompiled > 0 || cardsRemoved > 0
+      if (!corpusChanged) {
+        const compileRunId = `rebuild_${hash(`${startedAt}:${this.cards.length}`)}`
+        const report: RebuildReport = {
+          runId: compileRunId, compileRunId, version: previousVersion, only,
+          cards: this.cards.length, units: this.units.length, notes: this.units.length,
+          graphNodes: this.graph.nodes.length, graphEdges: this.graph.edges.length,
+          embedding: 'skipped',
+          cardsReused, cardsRecompiled: 0, cardsAdded: 0, cardsRemoved: 0,
+          notesReused, notesRecompiled: 0,
+          incremental: true, skipped: true,
+          ...extractionCounts,
+          // 这一轮没有重装图，所以没有一条边是「这次连上的」或「这次丢掉的」。
+          // 报 0 而不是把图里已有的边算进来：那会把历史成果记到这次空操作头上。
+          relationsExtracted: 0, relationsDropped: 0,
+          ...(lineage ? { lineage } : {}), startedAt, finishedAt: new Date().toISOString(),
+        }
+        // 跳过一次也要落盘 lastBuild：否则界面显示的是「上一次真正重建」的增量数字，
+        // 用户刚点了编译却看到上次的统计，会以为按钮没生效。version 不变，所以
+        // 这个写入既不改索引也不让向量缓存失效。extractionHashes 必须跟着更新：
+        // 来源变了但没抽出卡片时，不落新指纹会让下一次又把它重抽一遍。
+        await writeTextAtomic(this.safePath('03_compiled', 'build-manifest.json'), JSON.stringify({ version: previousVersion, builtAt: previousManifest.builtAt, sourceCount: sources.length, cardCount: this.cards.length, noteCount: this.units.length, cardHashes, extractionHashes: extraction.extractionHashes, embedding: previousManifest.embedding, compileRunId, lastBuild: { only, incremental: true, skipped: true, cardsReused, cardsRecompiled: 0, cardsAdded: 0, cardsRemoved: 0, notesReused, notesRecompiled: 0, ...extractionCounts, relationsExtracted: 0, relationsDropped: 0 }, ...(lineage ? { lineage } : {}) }, null, 2))
+        return success(report, ['知识库没有变化：已复用全部 wikiNotes，未生成新的索引版本。', ...extraction.warnings])
+      }
+
+      const nodeMap = new Map<string, Record<string, unknown>>()
+      const edges: Array<Record<string, unknown>> = []
+      for (const card of this.cards) {
+        nodeMap.set(`${card.entityType}:${card.entityId}`, { id: card.entityId, type: card.entityType, title: card.title, status: card.status })
+        for (const sourceRef of card.sourceRefs) {
+          nodeMap.set(`source:${sourceRef}`, { id: sourceRef, type: 'source', title: sourceRef })
+          edges.push({ from: `${card.entityType}:${card.entityId}`, to: `source:${sourceRef}`, type: 'supported_by' })
+        }
+      }
+      // Pass 0 抽出的关系在这里才成为边：两端都要落在真实存在的 wiki 节点上。
+      const relationStats = this.applyExtractedRelations(nodeMap, edges, extraction.relations)
+      relationsExtracted = relationStats.extracted
+      relationsDropped = relationStats.dropped
+      this.graph = { nodes: [...nodeMap.values()], edges }
+      const removedCount = cardsRemoved
+      const version = previousVersion + 1
+      const builtAt = new Date().toISOString()
+      await writeTextAtomic(this.safePath('03_compiled', WIKI_NOTES), JSON.stringify(this.units, null, 2))
+      // Compatibility mirror for tooling that predates wiki_notes.json.
+      await writeTextAtomic(this.safePath('03_compiled', LEGACY_UNITS), JSON.stringify(this.units, null, 2))
+      await writeTextAtomic(this.safePath('03_compiled', 'knowledge_graph.json'), JSON.stringify(this.graph, null, 2))
+      // 关键词索引跟着 notes 一起落盘（0031）：它的输入就是 notes，两者必须同时有效，
+      // 否则会出现「卡片改了、关键词路还按旧词表召回」。它不依赖编码器，所以 wiki-only
+      // 重建也要重建它 —— 而向量是 stage 3，仍然只在 `embeddings`/`all` 时重算。
+      const ftsResult = await this.buildFtsIndex(this.units, sources)
+      // `only: 'wiki'` stops at the notes + graph: vectors are stage 3 and get
+      // rebuilt on demand (`embeddings`/`all`), so a wiki edit does not pay for a
+      // re-encode of the whole corpus.
+      const embeddingResult = only === 'all' ? await this.buildVectorIndex(this.units, version) : { status: 'skipped' as const, count: 0, reused: 0 }
+      const compileRunId = `rebuild_${hash(`${startedAt}:${this.cards.length}`)}`
+      await writeTextAtomic(this.safePath('03_compiled', 'build-manifest.json'), JSON.stringify({ version, builtAt, sourceCount: sources.length, cardCount: this.cards.length, noteCount: this.units.length, cardHashes, extractionHashes: extraction.extractionHashes, embedding: embeddingResult, fts: ftsResult, compileRunId, lastBuild: { only, incremental: cardsReused > 0, skipped: false, cardsReused, cardsRecompiled, cardsAdded, cardsRemoved: removedCount, notesReused, notesRecompiled, ...extractionCounts, relationsExtracted, relationsDropped }, ...(lineage ? { lineage } : {}) }, null, 2))
+      const report: RebuildReport = {
+        runId: compileRunId, compileRunId, version, only,
+        cards: this.cards.length, units: this.units.length, notes: this.units.length,
+        graphNodes: this.graph.nodes.length, graphEdges: this.graph.edges.length,
+        embedding: embeddingResult.status, embeddingItems: embeddingResult.count, embeddingReused: embeddingResult.reused,
+        embeddingDimension: embeddingResult.dimension,
+        vectorQuantization: embeddingResult.status === 'ready' ? VECTOR_QUANTIZATION : undefined,
+        embeddingError: embeddingResult.error,
+        fts: ftsResult,
+        cardsReused, cardsRecompiled, cardsAdded, cardsRemoved: removedCount,
+        notesReused, notesRecompiled,
+        incremental: cardsReused > 0 || notesReused > 0,
+        skipped: false,
+        ...extractionCounts, relationsExtracted, relationsDropped,
+        ...(lineage ? { lineage } : {}), startedAt, finishedAt: new Date().toISOString(),
+      }
+      if (embeddingResult.status === 'unavailable') warnings.push(`embedding 不可用，已保留 FTS fallback：${embeddingResult.error ?? 'unknown error'}`)
+      return success(report, warnings)
+    }
+
+    // ------------------------------------------------ embeddings-only rebuild
+    if (this.units.length === 0 && this.graph.nodes.length === 0) {
+      await this.loadCompiledState()
+    }
+    const version = previousVersion + 1
+    const embeddingResult = await this.buildVectorIndex(this.units, version)
+    const compileRunId = `rebuild_${hash(`${startedAt}:${this.cards.length}`)}`
+    await writeTextAtomic(this.safePath('03_compiled', 'build-manifest.json'), JSON.stringify({ version, builtAt: new Date().toISOString(), sourceCount: sources.length, cardCount: this.cards.length, noteCount: this.units.length, cardHashes, extractionHashes: extraction.extractionHashes, embedding: embeddingResult, compileRunId, lastBuild: { only, incremental: embeddingResult.reused > 0, skipped: false, notesReused: embeddingResult.reused, notesRecompiled: Math.max(0, embeddingResult.count - embeddingResult.reused), ...extractionCounts, relationsExtracted: 0, relationsDropped: 0 }, ...(lineage ? { lineage } : {}) }, null, 2))
+    const report: RebuildReport = {
+      runId: compileRunId, compileRunId, version, only,
+      cards: this.cards.length, units: this.units.length, notes: this.units.length,
+      graphNodes: this.graph.nodes.length, graphEdges: this.graph.edges.length,
+      embedding: embeddingResult.status, embeddingItems: embeddingResult.count, embeddingReused: embeddingResult.reused,
+      embeddingDimension: embeddingResult.dimension,
+      vectorQuantization: embeddingResult.status === 'ready' ? VECTOR_QUANTIZATION : undefined,
+      embeddingError: embeddingResult.error,
+      incremental: embeddingResult.reused > 0, skipped: false,
+      // `embeddings` 不跑 Pass 0，所以这些计数是真的 0，不是省略。
+      ...extractionCounts, relationsExtracted: 0, relationsDropped: 0,
+      ...(lineage ? { lineage } : {}), startedAt, finishedAt: new Date().toISOString(),
+    }
+    if (embeddingResult.status === 'unavailable') warnings.push(`embedding 不可用，已保留 FTS fallback：${embeddingResult.error ?? 'unknown error'}`)
+    return success(report, warnings)
+  }
+
+  /**
+   * The staged read path:
+   *   3) recall — multi-route (keyword + vector + knowledge graph) recall over
+   *      wikiNotes, bounded by `recallTopK`, then resolve each hit's wiki and
+   *      its 1-hop graph;
+   *   4) rerank — BERT cross-encoder, then expand only `contextTopN` notes
+   *      into the context pack handed to the model.
+   */
+  // ------------------------------------------------------------- 召回（0031）
+
+  /**
+   * 编码器健康门（0031 的 P0）。
+   *
+   * 0030 的真实故障：WeMM 经 `SentenceTransformer.encode` 对**任何输入返回同一个向量**
+   * （实测四段无关文本两两 `cos = 1.000000`），而整条链路照样上报
+   * `routes: ["fts","vector","graph"]` —— 谎报「三路都在跑」。索引里 44 行有 39 行逐字节
+   * 相同，排序退化成 `unitId` 字典序，而界面上看不出任何异常。
+   *
+   * 所以「能不能用」不能靠「跑没跑」来判断，要**实测**：编码两段无关文本，要求余弦远小于 1。
+   * 不通过就关掉向量路并如实说明 —— 一条会撒谎的路比没有这条路更坏。
+   *
+   * 代价：第一次用到向量路时要起一次 worker（模型常驻之后就是一次往返）。这个代价是
+   * 必要的，而且它和「第一次召回本来就要加载模型」重叠。
+   */
+  private encoderHealth: { ok: boolean; reason?: string } | undefined
+
+  private async checkEncoder(): Promise<{ ok: boolean; reason?: string }> {
+    if (this.encoderHealth) return this.encoderHealth
+    if (this.config.embeddingProvider === 'none') {
+      this.encoderHealth = { ok: false, reason: '嵌入已关闭（embeddingProvider = none）' }
+      return this.encoderHealth
+    }
+    try {
+      const probes = [
+        '召回链路自检：指标口径与计算公式。',
+        'Sanity probe: an entirely unrelated sentence about cooking pasta.',
+      ]
+      const encoded = await this.encodeEmbeddings(probes.map(text => ({ text })))
+      const left = encoded.vectors[0]
+      const right = encoded.vectors[1]
+      if (!left || !right || left.length !== right.length || left.length === 0) throw new Error('ENCODER_PROBE_SHAPE_INVALID')
+      let dot = 0
+      let leftNorm = 0
+      let rightNorm = 0
+      for (let index = 0; index < left.length; index += 1) {
+        dot += left[index]! * right[index]!
+        leftNorm += left[index]! * left[index]!
+        rightNorm += right[index]! * right[index]!
+      }
+      const cosine = dot / (Math.sqrt(leftNorm) * Math.sqrt(rightNorm) || 1)
+      if (!Number.isFinite(cosine) || cosine > ENCODER_SELF_SIMILARITY_MAX) {
+        this.encoderHealth = { ok: false, reason: `编码器对两段无关文本给出同一个向量（cos = ${cosine.toFixed(4)}），向量路已停用` }
+        return this.encoderHealth
+      }
+      this.encoderHealth = { ok: true }
+      return this.encoderHealth
+    } catch (cause) {
+      this.encoderHealth = { ok: false, reason: `编码器自检失败：${cause instanceof Error ? cause.message : String(cause)}` }
+      return this.encoderHealth
+    }
+  }
+
+  /** 关键词路：FTS5 + BM25（0031）。索引不在时如实降级，不退回旧的计数打分。 */
+  private async ftsRoute(query: string, eligible: WikiNote[], pool: number, threshold: number, titleOf: (sourceId: string) => string | undefined): Promise<{ ranking: RouteRanking[]; diagnostic: RecallRouteDiagnostic }> {
+    const eligibleIds = new Set(eligible.map(note => note.unitId))
+    const sqlite = await loadSqlite()
+    if (!sqlite) return { ranking: [], diagnostic: { route: 'fts', status: 'degraded', reason: '当前 Node 没有 node:sqlite（需要 22.5+），关键词路已降级' } }
+    const index = await FtsIndex.open(this.safePath('03_compiled', FTS_FILE), sqlite.DatabaseSync)
+    if (!index) return { ranking: [], diagnostic: { route: 'fts', status: 'degraded', reason: `关键词索引不存在（03_compiled/${FTS_FILE}），先编译一次` } }
+    try {
+      const found = index.search(query, pool).filter(hit => eligibleIds.has(hit.unitId))
+      /**
+       * 覆盖率门槛（见 `MIN_QUERY_COVERAGE`）：只蹭到一两个高频单字的命中在这里淘汰，
+       * 于是「整批都弱」也能弃答 —— 这是相对阈值做不到的那一半。
+       *
+       * **分母只数多字词**（中文双字词与 ASCII 词），不数单个汉字。单个汉字在中文里
+       * 从来不是证据：`的` 到处都是，而 `GMV 怎么算` 这种问句里 怎/么/算 都是噪声。
+       * 把它们算进分母会同时犯两种错 —— 实测：
+       * - 全算 → `GMV 怎么算` 的分母塞进 5 个噪声词，只剩 1 个真命中，覆盖率 0.17，
+       *   正确答案被丢掉；
+       * 只算「命中过任何文档」的词 → `完全无关的词汇zzz` 只剩 `的`，覆盖率 1.0，
+       *   该弃答的反而过了。
+       *
+       * 只数多字词同时修好两边：`GMV 怎么算` → 分母 {gmv, 怎么, 么算}，命中 gmv = 0.33 过线；
+       * `完全无关的词汇zzz` → 分母是 6 个双字词，一个都不命中 = 0 淘汰。
+       */
+      const coverageTerms = [...new Set(segment(query))].filter(term => term.length > 1)
+      if (coverageTerms.length === 0) {
+        // 单字查询（如 `表`）是刻意收窄的问法，没有「多字词覆盖率」可言：不拦它，
+        // 交给阈值。这里如实返回空排名之外的结果需要另走一条路，所以直接用全部命中。
+        const ranking = found.map(hit => ({ unitId: hit.unitId, score: hit.score }))
+        const { kept, dropped, topScore } = applyThreshold(ranking, threshold)
+        return {
+          ranking: kept,
+          diagnostic: {
+            route: 'fts', status: 'ran', candidates: ranking.length, kept: kept.length, topScore, threshold,
+            ...(dropped > 0 ? { reason: `${dropped} 条低于关键词阈值 ${threshold} 被丢弃` } : {}),
+          },
+        }
+      }
+      const notesById = new Map(eligible.map(note => [note.unitId, note]))
+      const scored = found.map(hit => {
+        const note = notesById.get(hit.unitId)
+        const noteTokens = note ? tokenSet(noteIndexText(note, titleOf)) : new Set<string>()
+        let matched = 0
+        for (const term of coverageTerms) if (noteTokens.has(term)) matched += 1
+        return { unitId: hit.unitId, score: hit.score, coverage: matched / coverageTerms.length }
+      })
+      const covered = scored.filter(hit => hit.coverage >= MIN_QUERY_COVERAGE)
+      const ranking = covered.map(hit => ({ unitId: hit.unitId, score: hit.score }))
+      const { kept, dropped, topScore } = applyThreshold(ranking, threshold)
+      const lowCoverage = scored.length - covered.length
+      const reasons: string[] = []
+      if (lowCoverage > 0) reasons.push(`${lowCoverage} 条查询词覆盖率低于 ${MIN_QUERY_COVERAGE} 被丢弃`)
+      if (dropped > 0) reasons.push(`${dropped} 条低于关键词阈值 ${threshold} 被丢弃`)
+      return {
+        ranking: kept,
+        diagnostic: {
+          route: 'fts', status: 'ran', candidates: ranking.length, kept: kept.length, topScore, threshold,
+          ...(reasons.length > 0 ? { reason: reasons.join('；') } : {}),
+        },
+      }
+    } finally {
+      index.close()
+    }
+  }
+
+  /**
+   * 向量路：健康门 → 编码一次 → 原始余弦 → 阈值。
+   *
+   * 分数**不再**做 `(cosine + 1) / 2` 的映射：那个映射把余弦压进 0..1 之后，`0.15` 这样的
+   * 阈值就完全失去意义（余弦 0 会被映射成 0.5，轻松过线）。原始余弦是绝对量，可以直接
+   * 用来判「这段内容和问题到底像不像」—— 弃答主要靠它和重排阈值。
+   */
+  private async vectorRoute(query: string, eligibleIds: Set<string>, pool: number, threshold: number): Promise<{ ranking: RouteRanking[]; diagnostic: RecallRouteDiagnostic; health: { ok: boolean; reason?: string } }> {
+    const health = await this.checkEncoder()
+    if (!health.ok) return { ranking: [], diagnostic: { route: 'vector', status: 'degraded', reason: health.reason }, health }
+    try {
+      const scores = await this.vectorRecall(query, eligibleIds, pool)
+      const ranking = [...scores.entries()].map(([unitId, score]) => ({ unitId, score })).sort((left, right) => right.score - left.score || left.unitId.localeCompare(right.unitId))
+      const { kept, dropped, topScore } = applyThreshold(ranking, threshold)
+      return {
+        ranking: kept,
+        health,
+        diagnostic: {
+          route: 'vector', status: 'ran', candidates: ranking.length, kept: kept.length, topScore, threshold,
+          ...(dropped > 0 ? { reason: `${dropped} 条低于向量阈值 ${threshold} 被丢弃` } : {}),
+        },
+      }
+    } catch (cause) {
+      const error = cause instanceof Error ? cause.message : String(cause)
+      this.vectorError = error
+      return { ranking: [], diagnostic: { route: 'vector', status: 'degraded', reason: `向量召回不可用：${error}` }, health }
+    }
+  }
+
+  /**
+   * 图谱的**名次表**（不是一路分数，见 `graphBoost`）。
+   *
+   * 匹配逻辑与 0030 相同（词面匹配节点 title / id 与关系词，命中节点带出 1 跳邻居并衰减），
+   * 但返回值只用于给**已经在候选池里**的条目加权 —— 它自己不能制造候选。
+   */
+  private graphBoostRanking(query: string, eligible: WikiNote[], includeProblems: boolean): RouteRanking[] {
+    if (this.graph.nodes.length === 0) return []
+    const queryTokens = segment(query)
+    if (queryTokens.length === 0) return []
+    const byNodeKey = new Map<string, number>()
+    const boost = (key: string, score: number): void => { byNodeKey.set(key, Math.max(byNodeKey.get(key) ?? 0, score)) }
+    const visible = (node: Record<string, unknown>): boolean => includeProblems || node.status !== 'problem'
+    const nodeKey = (node: Record<string, unknown>): string => `${String(node.type)}:${String(node.id)}`
+
+    for (const node of this.graph.nodes) {
+      if (!visible(node)) continue
+      const title = String(node.title ?? '').toLocaleLowerCase()
+      const id = String(node.id ?? '').toLocaleLowerCase()
+      let score = 0
+      for (const token of queryTokens) {
+        if (title.includes(token)) score += 3
+        else if (id.includes(token)) score += 2
+      }
+      if (score > 0) boost(nodeKey(node), score)
+    }
+    for (const edge of this.graph.edges) {
+      const type = String(edge.type ?? '')
+      const relation = (RELATION_QUERY_WORDS[type] ?? type.toLocaleLowerCase().replace(/_/g, ' ')).toLocaleLowerCase()
+      let score = 0
+      for (const token of queryTokens) if (relation.includes(token)) score += 1
+      if (score > 0) { boost(String(edge.from), score); boost(String(edge.to), score) }
+    }
+    if (byNodeKey.size === 0) return []
+    const expanded = new Map<string, number>(byNodeKey)
+    for (const [key, score] of byNodeKey) {
+      for (const edge of this.graph.edges) {
+        const from = String(edge.from)
+        const to = String(edge.to)
+        if (from === key) expanded.set(to, Math.max(expanded.get(to) ?? 0, score * 0.5))
+        else if (to === key) expanded.set(from, Math.max(expanded.get(from) ?? 0, score * 0.5))
+      }
+    }
+    const byWiki = new Map<string, number>()
+    for (const note of eligible) {
+      const score = expanded.get(`${note.entityType}:${note.wikiId}`)
+      if (score === undefined) continue
+      // 一张 wiki 只留它最好的一节：分节片段不该各自再占一个名次。
+      byWiki.set(note.wikiId, Math.max(byWiki.get(note.wikiId) ?? 0, score))
+    }
+    const primary = new Map(eligible.map(note => [note.wikiId, note.unitId]))
+    return [...byWiki.entries()]
+      .map(([wikiId, score]) => ({ unitId: primary.get(wikiId) ?? '', score }))
+      .filter(item => item.unitId !== '')
+      .sort((left, right) => right.score - left.score || left.unitId.localeCompare(right.unitId))
+  }
+
+  /** SourceRaw 正文，按 sourceId 索引；证据片段从这里取。写入后失效。 */
+  private sourceCorpusCache: Map<string, { title: string; content: string }> | undefined
+
+  private async sourceCorpus(): Promise<Map<string, { title: string; content: string }>> {
+    if (this.sourceCorpusCache) return this.sourceCorpusCache
+    const corpus = new Map<string, { title: string; content: string }>()
+    for (const source of await this.loadSources()) corpus.set(source.sourceId, { title: source.title, content: source.content })
+    this.sourceCorpusCache = corpus
+    return corpus
+  }
+
+  /**
+   * 给命中挂上**证据片段**（0031）。
+   *
+   * `sourceRefs` 只说了「这条结论出自哪几份 SourceRaw」，而模型要核对一个数字时需要的
+   * 是**那一段原文**。这里把它解析出来放进上下文，于是「每个数字都能指回它的口径定义与
+   * 原始文档」在上下文层面成立，而不是靠模型自觉再调一次工具。
+   */
+  private async attachEvidence(hits: RecallHit[], queryTerms: string[], corpus: Map<string, { title: string; content: string }>): Promise<void> {
+    if (hits.length === 0 || queryTerms.length === 0) return
+    for (const hit of hits) {
+      const evidence: RecallEvidence[] = []
+      for (const ref of hit.sourceRefs) {
+        const source = corpus.get(ref)
+        if (!source) continue
+        evidence.push(...evidenceExcerpts(ref, source.title, source.content, queryTerms))
+      }
+      if (evidence.length > 0) {
+        hit.evidence = evidence
+          .sort((left, right) => right.coverage - left.coverage || left.sourceId.localeCompare(right.sourceId))
+          .slice(0, EVIDENCE_PER_HIT)
+      }
+    }
+  }
+
+  async recall(
+    query: string,
+    limit?: number,
+    sourceTypes: string[] = [],
+    includeProblems = false,
+    mode?: RecallMode,
+    lineage?: LineageContext,
+    options: { contextTopN?: number; rerank?: boolean } = {},
+  ): Promise<Envelope<RecallResult>> {
+    const recallId = generatedId('recall')
+    const recallMode = mode ?? this.config.recallMode
+    const recallTopK = limit ?? this.config.recallTopK
+    const requestedTopN = options.contextTopN ?? this.config.contextTopN
+    const contextTopN = Math.min(requestedTopN, Number.isInteger(recallTopK) && recallTopK > 0 ? recallTopK : requestedTopN)
+    /**
+     * 候选池：融合与重排都在它上面做，`recallTopK` 只决定最终给模型几条。
+     *
+     * 0014 早就点明「`limit` 同时承担候选数与最终上下文数」是缺陷：重排作用在已经截断的
+     * 列表上，只能换顺序，救不回被融合排到窗口外的那一条。所以两者彻底分开，而候选池
+     * 默认 50（与 WeKnora 的 `EmbeddingTopK` 同量级）。
+     */
+    const candidatePool = Math.max(recallTopK, Math.min(200, Number.isInteger(this.config.recallCandidatePool) && this.config.recallCandidatePool > 0 ? this.config.recallCandidatePool : 50))
+    const emptyDiagnostics = (reason?: string): RecallDiagnostics => ({
+      routes: [], fusion: { method: 'rrf', k: RRF_K, weights: RRF_WEIGHTS }, graphBoost: { applied: 0, weight: GRAPH_BOOST_WEIGHT },
+      abstention: 'relative-only', ...(reason ? { reason } : {}),
+    })
+    const empty = (): RecallResult => ({
+      hits: [], context: [], wiki: [], graph: { nodes: [], edges: [] }, backend: 'fts', routes: [], recallMode,
+      rerank: { status: 'skipped', provider: this.config.rerankProvider },
+      recallTopK: Number.isInteger(recallTopK) ? recallTopK : this.config.recallTopK,
+      candidatePool, contextTopN: Number.isInteger(contextTopN) ? contextTopN : this.config.contextTopN,
+      insufficientEvidence: true, diagnostics: emptyDiagnostics(), recallId,
+    })
+    if (!query?.trim()) return failure(empty(), 'QUERY_REQUIRED', 'query 不能为空', true)
+    if (!Number.isInteger(recallTopK) || recallTopK < 1 || recallTopK > 50) return failure(empty(), 'LIMIT_INVALID', '召回 top_k 必须是 1 到 50 的整数', false)
+    if (!Number.isInteger(requestedTopN) || requestedTopN < 1 || (options.contextTopN !== undefined && requestedTopN > recallTopK)) return failure(empty(), 'CONTEXT_TOP_N_INVALID', `上下文 top_n 必须是 1 到 ${recallTopK} 的整数`, false)
+    if (this.units.length === 0) {
+      await this.loadCompiledState()
+      if (this.units.length === 0) await this.rebuild('all', lineage)
+    }
+    const eventLineage = withRun(lineage, 'recall')
+    const indexVersion = (await this.loadVectorIndex())?.manifest.version
+    let compileRunId: string | undefined
+    try {
+      const manifest = JSON.parse(await readFile(this.safePath('03_compiled', 'build-manifest.json'), 'utf8')) as { compileRunId?: unknown }
+      if (typeof manifest.compileRunId === 'string' && manifest.compileRunId.trim()) compileRunId = manifest.compileRunId
+    } catch { /* the first build has not happened yet */ }
+
+    const wanted = new Set(sourceTypes.filter(Boolean))
+    const eligible = this.units.filter(unit => includeProblems || unit.status !== 'problem').filter(unit => wanted.size === 0 || unit.sourceTypes.some(sourceType => wanted.has(sourceType)))
+    const eligibleIds = new Set(eligible.map(unit => unit.unitId))
+    const queryTerms = [...new Set(segment(query))]
+    const warnings: string[] = []
+    // 一份 SourceRaw 语料，两处要用：关键词路的**查询词覆盖率**必须对着「建索引时那份
+    // 文本」算（含来源标题），而证据片段要对着来源正文取。按 runtime 缓存，写入后失效。
+    const corpus = await this.sourceCorpus()
+    const titleOf = (sourceId: string): string | undefined => corpus.get(sourceId)?.title
+
+    // --- R1 · 候选生成（每一路各自超采、各自过阈值）------------------------
+    // 图谱不再是「第三路」：它不能制造候选，只在 R2 里给已有候选加权（见 `graphBoost`）。
+    // 所以 `mode: 'graph'` 与 `hybrid` 同义 —— 一个「只靠图谱」的召回在设计上不成立。
+    const useFts = recallMode !== 'vector'
+    const useVector = recallMode !== 'fts'
+    const useGraphBoost = recallMode === 'hybrid' || recallMode === 'graph'
+
+    const ftsOutcome = useFts
+      ? await this.ftsRoute(query, eligible, candidatePool, this.config.keywordThreshold, titleOf)
+      : { ranking: [] as RouteRanking[], diagnostic: { route: 'fts' as const, status: 'skipped' as const, reason: '当前模式未启用关键词路' } }
+    const vectorOutcome = useVector
+      ? await this.vectorRoute(query, eligibleIds, candidatePool, this.config.vectorThreshold)
+      : { ranking: [] as RouteRanking[], diagnostic: { route: 'vector' as const, status: 'skipped' as const, reason: '当前模式未启用向量路' }, health: { ok: false, reason: '当前模式未启用向量路' } }
+    const graphRanking = useGraphBoost ? this.graphBoostRanking(query, eligible, includeProblems) : []
+
+    if (ftsOutcome.diagnostic.status === 'degraded' && ftsOutcome.diagnostic.reason) warnings.push(ftsOutcome.diagnostic.reason)
+    if (vectorOutcome.diagnostic.status === 'degraded' && vectorOutcome.diagnostic.reason) warnings.push(vectorOutcome.diagnostic.reason)
+
+    // --- R2 · 名次级融合（RRF）+ 图谱 boost ---------------------------------
+    const fused = rrfFuse({ fts: ftsOutcome.ranking, vector: vectorOutcome.ranking }, { k: RRF_K, weights: RRF_WEIGHTS })
+    const boosted = graphBoost(fused, graphRanking, { k: RRF_K, weights: RRF_WEIGHTS })
+
+    const unitById = new Map(eligible.map(unit => [unit.unitId, unit]))
+    let hits: RecallHit[] = boosted.hits
+      .filter(hit => unitById.has(hit.unitId))
+      .map(hit => ({ ...unitById.get(hit.unitId)!, score: hit.score, match: matchOf(hit.ranks), ranks: hit.ranks }))
+
+    // --- R3 · 对**候选池**重排，再过阈值 ------------------------------------
+    let rerank: RerankResult
+    if (options.rerank === false || this.config.rerankProvider === 'none') {
+      rerank = { status: 'skipped', provider: this.config.rerankProvider }
+      hits = hits.slice(0, recallTopK)
+    } else {
+      const reranked = await this.rerankNotes(query, hits, this.config.rerankThreshold)
+      hits = reranked.hits.slice(0, recallTopK)
+      rerank = reranked.result
+      if (reranked.warning) warnings.push(reranked.warning)
+    }
+
+    // --- R4 · 证据片段 -----------------------------------------------------
+    await this.attachEvidence(hits, queryTerms, corpus)
+
+    // --- R5 · 弃答 ---------------------------------------------------------
+    // 一路都没过阈值 = 这个知识库里没有能回答这个问题的东西。与其凑满 topN 让模型编，
+    // 不如明确说「没有」：这是产品诚实性的一部分，也是 eval 里「不应召回」样本的落点。
+    const insufficientEvidence = hits.length === 0
+    const ranRoutes = ([ftsOutcome, vectorOutcome] as const).filter(outcome => outcome.diagnostic.status === 'ran').map(outcome => outcome.diagnostic.route)
+    const backend = ranRoutes.includes('vector') ? (ranRoutes.includes('fts') ? 'hybrid' : 'vector') : 'fts'
+    /**
+     * 弃答的**判据强度**要如实标注 —— 说「没有」的时候，读者有权知道凭什么。
+     *
+     * 三种情况差别很大：重排阈值与向量余弦都是绝对判据；而只剩相对阈值时，它挡得住弱命中、
+     * 挡不住「整批都弱」。
+     *
+     * 归因顺序也修过一次。原来只看「重排跑没跑」就报 `rerank-threshold`，是**过度声称**：
+     * 当时实测 `dropped` 恒为 0、logit 挤在 0.68–0.73 —— 那不是「重排很保守」，而是
+     * 分词器词表是空的（见 `RERANK_TOKENIZER_DEGENERATE`），模型在给 `<unk>` 排序。
+     * 现在重排真的会丢东西，所以判据可以按「谁真的丢了」来归因，而不是按「谁跑过」。
+     */
+    const vectorDropped = (vectorOutcome.diagnostic.candidates ?? 0) > 0 && (vectorOutcome.diagnostic.kept ?? 0) < (vectorOutcome.diagnostic.candidates ?? 0)
+    const rerankDropped = rerank.status === 'ready' && (rerank.dropped ?? 0) > 0
+    const abstention: RecallDiagnostics['abstention'] = !insufficientEvidence
+      ? 'not-needed'
+      : rerankDropped ? 'rerank-threshold'
+        : vectorDropped ? 'vector-threshold'
+          : 'relative-only'
+    const diagnostics: RecallDiagnostics = {
+      routes: [ftsOutcome.diagnostic, vectorOutcome.diagnostic],
+      fusion: { method: 'rrf', k: RRF_K, weights: RRF_WEIGHTS },
+      graphBoost: { applied: boosted.applied, weight: GRAPH_BOOST_WEIGHT },
+      abstention,
+      encoder: vectorOutcome.health,
+      ...(insufficientEvidence ? {
+        reason: rerankDropped
+          ? `没有内容达到重排阈值 ${this.config.rerankThreshold}（候选 ${fused.length} 条，全部被丢弃；最高 logit ${(rerank.topLogit ?? 0).toFixed(2)}）`
+          : `没有内容达到召回阈值（关键词 ${this.config.keywordThreshold} / 向量余弦 ${this.config.vectorThreshold}）`,
+      } : {}),
+    }
+
+    // --- 组装：片段 → 整篇 → 证据 -------------------------------------------
+    const cards = this.cards.length > 0 ? this.cards : await this.loadCards()
+    const cardByKey = new Map(cards.map(card => [`${card.entityType}:${card.entityId}`, card]))
+    const wikiKey = (note: Pick<RecallHit, 'entityType' | 'entityId'>) => `${note.entityType}:${note.entityId}`
+    const wiki = [...new Set(hits.map(wikiKey))].map(key => cardByKey.get(key)).filter((card): card is KnowledgeCard => card !== undefined)
+    const graph = this.oneHopGraph(new Set(hits.map(wikiKey)), includeProblems)
+    // 上下文条目的选择**不是**简单切片：每张 wiki 封顶 + MMR 去冗余，否则 5 条上下文
+    // 可能全是同一张卡的不同小节（一屏塞满、信息量为 1）。
+    const contextHits = selectContext(hits, {
+      relevance: hit => hit.rerankScore ?? hit.score,
+      tokens: hit => tokenSet(`${hit.title}\n${hit.content}`),
+      wikiKey: hit => hit.entityId,
+      limit: contextTopN,
+      perWikiCap: CONTEXT_PER_WIKI_CAP,
+    })
+    const context: ContextItem[] = contextHits.map(note => ({
+      note,
+      wiki: cardByKey.get(wikiKey(note)) ?? null,
+      graph: this.oneHopGraph(new Set([wikiKey(note)]), includeProblems),
+      ...(note.evidence ? { evidence: note.evidence } : {}),
+    }))
+
+    const data: RecallResult = {
+      hits, context, wiki, graph, backend, routes: ranRoutes, recallMode, rerank, recallTopK, candidatePool, contextTopN,
+      insufficientEvidence, diagnostics, recallId,
+      ...(indexVersion === undefined ? {} : { indexVersion }),
+      ...(compileRunId === undefined ? {} : { compileRunId }),
+      ...(eventLineage ? { lineage: eventLineage } : {}),
+    }
+    await this.audit('knowledge.recall', {
+      query: query.slice(0, 4000), count: hits.length, context: context.length, backend, routes: ranRoutes,
+      rerank: rerank.status, rerankThreshold: this.config.rerankThreshold, candidatePool,
+      ...(rerank.dropped === undefined ? {} : { rerankDropped: rerank.dropped }),
+      ...(rerank.topLogit === undefined ? {} : { rerankTopLogit: Number(rerank.topLogit.toFixed(4)) }),
+      ...(rerank.vocabSize === undefined ? {} : { rerankVocabSize: rerank.vocabSize }),
+      insufficientEvidence, routesDetail: diagnostics.routes,
+      ...(indexVersion === undefined ? {} : { indexVersion }), ...(compileRunId === undefined ? {} : { compileRunId }),
+      ...(eventLineage ? { lineage: eventLineage } : {}),
+    })
+    return success(data, warnings)
+  }
+
+  /**
+   * 向量路的原始余弦（0031 修了两个数）。
+   *
+   * 1. **分母**：向量在入库与查询时都已归一（实测 `|v| = 0.9992`），量化是 `round(v × 127)`，
+   *    所以 `Σ q_i·s_i ≈ 127²·cos`，正确分母是 `127²`。0030 写的是 `127² × dimension`，
+   *    多除了一个 1024 —— 任何余弦都被压进 ±0.001，再经 `(cos+1)/2` 之后所有候选都落在
+   *    0.5 附近，**排序完全没有区分度**（实测：某行自相似度算出来是 0.000975，应为 1.0）。
+   * 2. **量纲**：返回**原始余弦**，不再做 `(cos+1)/2` 的映射 —— 那个映射让 `0.15` 这类阈值
+   *    失去意义（余弦 0 → 0.5，轻松过线）。原始余弦是绝对量，可以直接用于弃答。
+   */
+  private async vectorRecall(query: string, eligibleIds: Set<string>, candidateLimit: number): Promise<Map<string, number>> {
+    const index = await this.loadVectorIndex()
+    if (!index || index.manifest.itemCount === 0) throw new Error('VECTOR_INDEX_NOT_READY')
+    if (index.manifest.provider !== this.config.embeddingProvider || index.manifest.model !== this.embeddingModelId || index.manifest.dimension !== this.config.embeddingDimension) throw new Error('VECTOR_INDEX_CONFIG_MISMATCH')
+    const encoded = await this.encodeEmbeddings([{ text: query }])
+    const queryBinary = binaryVector(encoded.vectors[0]!, index.manifest.dimension)
+    const queryInt8 = int8Vector(encoded.vectors[0]!, index.manifest.dimension)
+    const binaryWidth = Math.ceil(index.manifest.dimension / 8)
+    const candidates: Array<{ row: number; distance: number }> = []
+    for (let row = 0; row < index.manifest.itemCount; row += 1) {
+      const item = index.manifest.items[row]
+      if (!item || !eligibleIds.has(item.unitId)) continue
+      let distance = 0
+      const offset = row * binaryWidth
+      for (let byte = 0; byte < binaryWidth; byte += 1) distance += BIT_COUNTS[queryBinary[byte]! ^ index.binary[offset + byte]!]!
+      if (candidates.length < candidateLimit || distance < candidates[candidates.length - 1]!.distance) {
+        candidates.push({ row, distance })
+        candidates.sort((left, right) => left.distance - right.distance || left.row - right.row)
+        if (candidates.length > candidateLimit) candidates.pop()
+      }
+    }
+    const scores = new Map<string, number>()
+    for (const candidate of candidates) {
+      const item = index.manifest.items[candidate.row]!
+      const offset = candidate.row * index.manifest.dimension
+      let dot = 0
+      for (let dimension = 0; dimension < index.manifest.dimension; dimension += 1) dot += signedByte(queryInt8[dimension]!) * signedByte(index.int8[offset + dimension]!)
+      scores.set(item.unitId, Math.max(-1, Math.min(1, dot / (127 * 127))))
+    }
+    return scores
+  }
+
+  /**
+   * 解析后的三个「家当」路径（0029）。
+   *
+   * 设置面板用它显示「自动」到底指向哪里：配置里那三个字段空着就是「跟着根路径
+   * 走」，但用户要看到的是**真实路径**，否则「自动」等于没说。
+   */
+  resourcePaths(): { python: string; embeddingModel: string; rerankModel: string; embeddingModelId: string } {
+    return {
+      python: this.pythonPath,
+      embeddingModel: this.embeddingModelPath,
+      rerankModel: this.rerankModelPath,
+      embeddingModelId: this.embeddingModelId,
+    }
+  }
+
+  async embeddingHealth(): Promise<Envelope<Record<string, unknown>>> {
+    const index = await this.loadVectorIndex()
+    return success({
+      provider: this.config.embeddingProvider,
+      model: this.embeddingModelPath,
+      configuredDevice: this.config.embeddingDevice,
+      dimension: this.config.embeddingDimension,
+      batchSize: this.config.embeddingBatchSize,
+      worker: this.config.embeddingProvider === 'wemm-python' ? this.vectorWorkerPath() : undefined,
+      vectorIndex: index ? { ready: true, version: index.manifest.version, itemCount: index.manifest.itemCount, dimension: index.manifest.dimension, device: index.manifest.device, quantization: index.manifest.quantization } : { ready: false, itemCount: 0 },
+      lastError: this.vectorError,
+    })
+  }
+
+  /**
+   * Stage 5（旁路）：读 SourceRaw 原文，**带配额**。
+   *
+   * 配额是「top `max_chars` 字符」（默认与上限都是 40000），而且是**跨多条来源共享**的，
+   * 所以一份长文档很可能只回来开头。这件事必须**说出来**，不能靠调用方自己猜：
+   *
+   * - 每条带上 `path`（磁盘绝对路径）与 `totalChars`；
+   * - 信封上带 `truncated`。
+   *
+   * 看到 `truncated: true` 或 `returnedChars < totalChars`，就该去读那个文件 —— 这条
+   * 路径是知识库里的真实文件，读它与读这里的内容是同一份数据，而且没有配额。这样
+   * 「一次读不完」就不再等于「读不到」，也不会出现「以为拿到全文、其实只有前 4 万字符」。
+   */
+  async sourceTruth(query: string, sourceTypes: string[] = [], limit = 20, maxChars = 40000, lineage?: LineageContext): Promise<Envelope<{ sources: SourceRawRead[]; sourceReadId: string; maxChars: number; returnedChars: number; truncated: boolean; lineage?: LineageContext }>> {
+    const sourceReadId = generatedId('source-read')
+    const empty = { sources: [] as SourceRawRead[], sourceReadId, maxChars, returnedChars: 0, truncated: false }
+    if (!this.config.allowSourceTruth) return failure(empty, 'SOURCE_TRUTH_DISABLED', '当前配置禁止访问 SourceTruth', false)
+    if (limit < 1 || limit > 20 || maxChars < 1 || maxChars > 40000) return failure(empty, 'SOURCE_LIMIT_INVALID', 'limit 最大 20，max_chars 最大 40000；需要更多就按返回的 path 直接读文件', false)
+    const wanted = new Set(sourceTypes.filter(Boolean))
+    const queryTokens = tokens(query)
+    const sources = (await this.loadSources()).filter(item => wanted.size === 0 || wanted.has(item.sourceType)).filter(item => !queryTokens.length || queryTokens.some(token => `${item.title}\n${item.content}`.toLocaleLowerCase().includes(token))).slice(0, limit)
+    // 一次把索引取出来（它整段只扫一遍），避免每条来源各扫一次目录。
+    const index = await this.sourceIndexMap()
+    let used = 0
+    let truncated = false
+    const bounded: SourceRawRead[] = []
+    for (const source of sources) {
+      const remaining = Math.max(0, maxChars - used)
+      const content = source.content.slice(0, remaining)
+      if (content.length < source.content.length) truncated = true
+      used += content.length
+      // 配额用尽后剩下的来源直接丢掉（它们只会有空 content），而不是返回一堆空壳。
+      if (content.length === 0 && sources.length > 0) continue
+      bounded.push({
+        ...source,
+        content,
+        // 索引命中不了时退回按 id + 分类算出来的路径：那条路径**就是**写入时用的，
+        // 所以它仍然指向真实文件（索引缺失只可能是并发写入还没失效缓存）。
+        path: index.get(slug(source.sourceId)) ?? this.sourcePath(source.sourceId, source.sourceType),
+        returnedChars: content.length,
+        totalChars: source.content.length,
+      })
+    }
+    const eventLineage = withRun(lineage, 'source-read')
+    await this.audit('source_truth.read', { query: query.slice(0, 4000), count: bounded.length, sourceReadId, ...(eventLineage ? { lineage: eventLineage } : {}) })
+    return success({ sources: bounded, sourceReadId, maxChars, returnedChars: used, truncated, ...(eventLineage ? { lineage: eventLineage } : {}) })
+  }
+
+  async graphQuery(action: 'entity' | 'neighbors' | 'path' | 'list' | 'types', entityId?: string, entityType?: string, depth = 1, options: { fromId?: string; toId?: string; status?: string; includeProblem?: boolean; limit?: number } = {}, lineage?: LineageContext): Promise<Envelope<Record<string, unknown>>> {
+    const eventLineage = withRun(lineage, 'graph-query')
+    if (this.units.length === 0) await this.rebuild('all', eventLineage)
+    const attachLineage = (data: Record<string, unknown>): Record<string, unknown> => eventLineage ? { ...data, lineage: eventLineage } : data
+    if (depth < 1 || depth > 3) return failure({}, 'DEPTH_INVALID', 'depth 必须在 1 到 3 之间', false)
+    const limit = options.limit ?? 50
+    if (!Number.isInteger(limit) || limit < 1 || limit > 50) return failure({}, 'LIMIT_INVALID', 'limit 必须在 1 到 50 之间', false)
+    if (action === 'types') return success(attachLineage({ types: this.wikiSchema().types.filter(def => def.enabled).map(def => def.id), relationTypes: ['supported_by', RELATES_TO] }))
+
+    const includeProblem = options.includeProblem === true
+    const visible = (node: Record<string, unknown>) => includeProblem || node.status !== 'problem'
+    const allNodes = this.graph.nodes
+      .filter(visible)
+      .filter(node => !options.status || node.status === options.status)
+    const nodes = allNodes.filter(node => !entityType || node.type === entityType)
+    const edges = this.graph.edges.filter(edge => allNodes.some(node => `${node.type}:${node.id}` === String(edge.from)) && allNodes.some(node => `${node.type}:${node.id}` === String(edge.to)))
+    if (action === 'list') return success(attachLineage({ nodes: nodes.slice(0, limit), edges: edges.slice(0, limit) }))
+
+    const nodeKey = (rawId: string | undefined, rawType?: string): string | undefined => {
+      if (!rawId) return undefined
+      if (rawId.includes(':')) return rawId
+      if (rawType) return `${rawType}:${rawId}`
+      const match = allNodes.find(node => node.id === rawId)
+      return match ? `${match.type}:${match.id}` : undefined
+    }
+    const fromKey = nodeKey(options.fromId ?? (action === 'path' ? entityId : undefined), entityType)
+    const toKey = nodeKey(options.toId)
+    if (action === 'path') {
+      if (!fromKey || !toKey) return failure({}, 'PATH_ENDPOINTS_REQUIRED', 'path 需要 from_id 和 to_id（也可用 entity_id 作为 from_id）', true)
+      const queue: Array<{ key: string; path: string[] }> = [{ key: fromKey, path: [fromKey] }]
+      const visited = new Set([fromKey])
+      let found: string[] | undefined
+      while (queue.length > 0 && found === undefined) {
+        const current = queue.shift()!
+        if (current.key === toKey) { found = current.path; break }
+        if (current.path.length - 1 >= depth) continue
+        const nextKeys = edges.flatMap(edge => {
+          const from = String(edge.from); const to = String(edge.to)
+          return from === current.key ? [to] : to === current.key ? [from] : []
+        })
+        for (const next of nextKeys) if (!visited.has(next)) { visited.add(next); queue.push({ key: next, path: [...current.path, next] }) }
+      }
+      if (!found) return success(attachLineage({ path: [], nodes: [], edges: [] }))
+      return success(attachLineage({ path: found, nodes: allNodes.filter(node => found!.includes(`${node.type}:${node.id}`)), edges: edges.filter(edge => found!.includes(String(edge.from)) && found!.includes(String(edge.to))) }))
+    }
+
+    const id = nodeKey(entityId, entityType)
+    if (!id) return failure({}, 'ENTITY_REQUIRED', '该 graph action 需要 entity_id', true)
+    if (action === 'entity') return success(attachLineage({ nodes: nodes.filter(node => `${node.type}:${node.id}` === id).slice(0, limit) }))
+    if (action === 'neighbors') {
+      const ids = new Set([id])
+      for (let index = 0; index < depth; index++) for (const edge of edges) {
+        if (ids.has(String(edge.from))) ids.add(String(edge.to))
+        if (ids.has(String(edge.to))) ids.add(String(edge.from))
+      }
+      return success(attachLineage({ nodes: allNodes.filter(node => ids.has(`${node.type}:${node.id}`)).slice(0, limit), edges: edges.filter(edge => ids.has(String(edge.from)) || ids.has(String(edge.to))).slice(0, limit) }))
+    }
+    return failure({}, 'ACTION_INVALID', `不支持的 graph action: ${action}`, false)
+  }
+
+  async recordFeedback(input: { feedbackId?: string; unitId?: string; rating: number; comment?: string; sessionKey?: string; lineage?: LineageContext }): Promise<Envelope<{ feedbackId: string; lineage?: LineageContext }>> {
+    if (!Number.isInteger(input.rating) || input.rating < 1 || input.rating > 5) return failure({ feedbackId: '' }, 'RATING_INVALID', 'rating 必须为 1 到 5 的整数', false)
+    const feedbackId = input.feedbackId?.trim() || `feedback_${hash(`${Date.now()}:${input.unitId ?? ''}:${input.rating}`)}`
+    await this.ensureLayout()
+    const eventLineage = withRun(input.lineage, 'feedback')
+    await appendFile(this.memoryPath('feedback.ndjson'), `${JSON.stringify({ feedbackId, ...input, ...(eventLineage ? { lineage: eventLineage } : {}), createdAt: new Date().toISOString() })}\n`, 'utf8')
+    return success({ feedbackId, ...(eventLineage ? { lineage: eventLineage } : {}) })
+  }
+
+  async audit(action: string, metadata: Record<string, unknown>): Promise<void> {
+    await this.ensureLayout()
+    await appendFile(this.memoryPath('access-audit.ndjson'), `${JSON.stringify({ action, metadata, at: new Date().toISOString() })}\n`, 'utf8')
+  }
+}
+
+/**
+ * @deprecated 0029：知识树的根不再是「一个路径」，而是
+ * `<agentRoot>/domain_knowledge/<知识库 id>`。这里保留旧名字只为让外部调用点
+ * （注册表的默认库、测试）有个可迁移的入口；新代码一律用 `layout.ts` 的
+ * `knowledgeBaseRoot()`。它返回的是**旧布局**的位置，也就是迁移的来源。
+ */
+export function defaultKnowledgeRoot(): string {
+  return legacyKnowledgeRoot()
+}
+