dsh-data-domain-knowledge 0.1.0-alpha.2 → 0.1.0-alpha.4

package/src/diagnosis/cards.ts

@@ -1,8 +1,9 @@
-import { DIAGNOSIS_ENTITIES, type DiagnosisEntityType } from './schema.js'
-import type { AttributionCase } from './seed.js'
+import { DIAGNOSIS_ENTITIES, LEGACY_BLOCK_FIELDS, LEGACY_ENTITY_TYPES, type DiagnosisEntityType } from './schema.js'
 import type {
+  AssetType,
+  AttributionCase,
   AttributionEdge, AttributionEdgeKind, AttributionGraphData, AttributionNode, AttributionNodeKind,
-  FailureMode,
+  FailureReason,
 } from './types.js'
 
 /**
@@ -10,13 +11,12 @@ import type {
  *
  * ## 为什么这一层必须存在
  *
- * 在它之前，智能归因的图只有一条来源：`seed.ts` 里的 TypeScript 字面量，被
- * `DiagnosisStore.ensure()` 直接写成 `05_diagnosis/*.jsonl`。那意味着**排查思路从来没有
- * 进过 wiki**：它不在 `01_source_truth` 里、不是 `02_wiki` 的卡片、编译器连
- * `diagnosis/hypothesis` 这个 entity_type 都不认 —— 于是它既不会被 wikiNote 化，
+ * 在它之前，智能归因的图只有一条来源：`seed.ts` 里的 TypeScript 字面量。那意味着
+ * **排查思路从来没有进过 wiki**：它不在 `01_source_raw` 里、不是 `02_wiki` 的卡片、
+ * 编译器连 `diagnosis/hypothesis` 这个 entity_type 都不认 —— 于是它既不会被 wikiNote 化，
  * 也不会进向量索引，**召回永远召不到它**。而「遇到类似问题先召回」正是这个产品的主张。
  *
- * 这一层把图变成卡片的**投影**：卡片是手写的（人写、Agent 写、从 SourceRaw 编译而来），
+ * 这一层把图变成卡片的**投影**：卡片是手写的（人写、Agent 提议后由人确认），
  * 图是算出来的。§4「存图、显树」讲的是同一件事 —— 存的是知识，图是它的一种读法。
  *
  * ## 卡片三段式与「谁由卡片定义」的边界
@@ -31,10 +31,10 @@ import type {
  *
  * | 图上的东西 | 谁定义 | 为什么 |
  * | --- | --- | --- |
- * | symptom / hypothesis / check / failure-mode / case 节点 | **卡片** | 这五类是人写的知识（§6.4） |
+ * | symptom / hypothesis / check_point / failure_reason / case 节点 | **卡片** | 这五类是人确认过的知识（§6.4） |
  * | asset 节点 | 引用反推 | 它随数据目录同步，不手写；卡片里只留 id |
- * | 现象→假设 / 假设→检查 / 假设→失败模式 / 资产→假设 / 案例→现象 边 | **卡片** | 都是卡片字段的确定性投影 |
- * | evidence / cause 节点，produces / supports / refutes / confirmed_as 边 | **一次排查** | 它们是一次执行的结果，不是知识；由排查自动写入（§6.4） |
+ * | 现象→假设 / 假设→检查点 / 假设→失败原因 / 检查点→资产 / 资产→假设 / 案例→现象 边 | **卡片** | 都是卡片字段的确定性投影 |
+ * | evidence / cause 节点，produces / supports / refutes / confirmed_as 边 | **一次排查** | 它们是一次执行的结果，不是知识；由 `01_source_raw/agent_diagnosis_case/` 那条 SourceRaw 读时解析出来 |
  *
  * 最后一行不是妥协，是分层：把「上次查到什么」写进卡片，等于让一份可复用的知识
  * 绑死在一次具体的执行上。
@@ -80,14 +80,15 @@ const CARD_LAYOUT: Record<DiagnosisEntityType, { block: string[]; summaryFrom: s
     summaryFrom: 'observable',
   },
   'diagnosis/hypothesis': {
-    block: ['discriminator', 'not_when', 'failure_mode', 'verified_by', 'assets', 'reuse_count', 'stale'],
+    block: ['discriminator', 'not_when', 'failure_reason', 'verified_by', 'assets', 'reuse_count', 'stale'],
     summaryFrom: 'summary',
   },
-  'diagnosis/check': {
-    block: ['cost_minutes', 'automation', 'verdict_true', 'verdict_false', 'stale'],
+  'diagnosis/check-point': {
+    // `assets` 是 v1.3 新增的**查询依据**：它承载「检查点 → 资产」这条 `queries` 边。
+    block: ['cost_minutes', 'automation', 'verdict_true', 'verdict_false', 'runbook', 'side_effect', 'assets', 'stale'],
     summaryFrom: 'summary',
   },
-  'diagnosis/failure-mode': {
+  'diagnosis/failure-reason': {
     block: ['code', 'label', 'boundary'],
     summaryFrom: 'summary',
   },
@@ -107,7 +108,7 @@ export const CARD_NODE_KINDS: AttributionNodeKind[] = DIAGNOSIS_ENTITIES.map(spe
 
 /** 卡片能定义的边：全部是卡片字段的确定性投影。 */
 export const CARD_EDGE_KINDS: AttributionEdgeKind[] = [
-  'may_be_caused_by', 'verified_by', 'categorized_as', 'indexed_from', 'instance_of',
+  'may_be_caused_by', 'verified_by', 'categorized_as', 'queries', 'indexed_from', 'instance_of',
 ]
 
 /** 一次排查写下的边。它们不属于任何卡片，见文件头的边界表。 */
@@ -150,8 +151,8 @@ export function serializeCard(card: DiagnosisCard): string {
 export function parseCard(source: string): DiagnosisCard | undefined {
   // 复用运行时的 front matter 解析（同一个 yaml 子集），不另写一套。
   const parsed = parseFrontmatter(source)
-  const entityType = String(parsed.frontmatter.entity_type ?? '')
-  if (!isEntityType(entityType)) return undefined
+  const entityType = normalizeEntityType(String(parsed.frontmatter.entity_type ?? ''))
+  if (!entityType) return undefined
   const entityId = String(parsed.frontmatter.entity_id ?? '').trim()
   if (!entityId) return undefined
 
@@ -160,7 +161,7 @@ export function parseCard(source: string): DiagnosisCard | undefined {
   if (match) {
     try {
       const value = JSON.parse(match[1])
-      if (value && typeof value === 'object' && !Array.isArray(value)) block = value as Record<string, unknown>
+      if (value && typeof value === 'object' && !Array.isArray(value)) block = normalizeBlock(value as Record<string, unknown>)
     } catch { /* 块坏了不静默降级成空对象：留空之后由三层校验的「格式层」报缺字段。 */ }
   }
   const body = match ? parsed.content.replace(match[0], '') : parsed.content
@@ -180,6 +181,22 @@ export function parseCard(source: string): DiagnosisCard | undefined {
   }
 }
 
+/** 改名之前的 `entity_type` 按别名认，而不是判为未知类型然后静默丢掉这张卡片。 */
+export function normalizeEntityType(value: string): DiagnosisEntityType | undefined {
+  const mapped = LEGACY_ENTITY_TYPES[value] ?? value
+  return DIAGNOSIS_ENTITIES.some(spec => spec.entityType === mapped) ? mapped as DiagnosisEntityType : undefined
+}
+
+/** 结构化块里的旧字段名（`failure_mode`）搬到新名字上。 */
+function normalizeBlock(block: Record<string, unknown>): Record<string, unknown> {
+  const next: Record<string, unknown> = { ...block }
+  for (const [from, to] of Object.entries(LEGACY_BLOCK_FIELDS)) {
+    if (next[to] === undefined && next[from] !== undefined) next[to] = next[from]
+    delete next[from]
+  }
+  return next
+}
+
 /**
  * 只解析 front matter 与正文。
  *
@@ -224,20 +241,21 @@ function splitSections(body: string): DiagnosisCardSection[] {
   return sections.filter(section => section.body !== '')
 }
 
-function isEntityType(value: string): value is DiagnosisEntityType {
-  return DIAGNOSIS_ENTITIES.some(spec => spec.entityType === value)
-}
-
 /* ─────────────────────────────────────────────── 图 → 卡片 ── */
 
 /**
  * 类型层与案例 → 卡片。
  *
- * `asset` / `evidence` / `cause` 节点**不产出卡片**：它们不是手写的知识（§6.4）。
- * 被假设引用的资产会在反序列化时按 id 补一个最小节点回来。
+ * `asset` / `evidence` / `cause` 节点**不产出卡片**：它们不是手确认过的知识（§6.4）。
+ * 被引用的资产会在反序列化时按 id 补一个最小节点回来。
  */
 export function graphToCards(graph: AttributionGraphData, cases: AttributionCase[] = []): DiagnosisCard[] {
   const cards: DiagnosisCard[] = []
+  /** 资产 id → 卡片声明过的种类。它写在**引用它的那张卡片**上，不写在资产节点自己身上。 */
+  const assetTypeById = new Map<string, AssetType>()
+  for (const node of graph.nodes) {
+    if (node.kind === 'asset' && node.assetType) assetTypeById.set(node.id, node.assetType)
+  }
 
   for (const node of graph.nodes) {
     // 案例节点只是图上的**桩**：它的正文与有序路径住在 `cases` 里（§6.4）。图上的桩不单独成卡，
@@ -264,18 +282,25 @@ export function graphToCards(graph: AttributionGraphData, cases: AttributionCase
     } else if (node.kind === 'hypothesis') {
       block.discriminator = node.discriminator ?? ''
       block.not_when = node.notWhen ?? ''
-      block.failure_mode = node.failureMode ?? null
+      block.failure_reason = node.failureReason ?? null
       block.verified_by = graph.edges.filter(edge => edge.kind === 'verified_by' && edge.source === node.id).map(edge => edge.target)
-      block.assets = graph.edges.filter(edge => edge.kind === 'indexed_from' && edge.target === node.id).map(edge => edge.source)
+      block.assets = graph.edges
+        .filter(edge => edge.kind === 'indexed_from' && edge.target === node.id)
+        .map(edge => assetEntryOf(edge.source, assetTypeById))
       block.reuse_count = node.reuseCount ?? 0
       if (node.stale !== undefined) block.stale = node.stale
-    } else if (node.kind === 'check') {
+    } else if (node.kind === 'check_point') {
       block.cost_minutes = node.costMinutes ?? null
       block.automation = node.automation ?? null
       block.verdict_true = node.verdictTrue ?? ''
       block.verdict_false = node.verdictFalse ?? ''
+      // 检查点 → 资产：`queries` 边。它和假设上的 `assets`（`indexed_from`）是两条边，
+      // 两端与回答的问题都不同，所以各读各的，不共用一份。
+      block.assets = graph.edges
+        .filter(edge => edge.kind === 'queries' && edge.source === node.id)
+        .map(edge => assetEntryOf(edge.target, assetTypeById))
       if (node.stale !== undefined) block.stale = node.stale
-    } else if (node.kind === 'failure-mode') {
+    } else if (node.kind === 'failure_reason') {
       block.code = node.code ?? null
       block.label = node.title
       block.boundary = ''
@@ -328,9 +353,9 @@ export interface CompiledDiagnosis {
 /**
  * 卡片 → 图。
  *
- * 只产出「卡片定义得了」的那部分（类型层 + 引用层的资产 + 案例，以及五种卡片边）；
- * `evidence` / `cause` 与四条执行边由一次排查写入，不在这里合成 —— 否则一次执行的结果
- * 会被伪装成可复用的知识。
+ * 只产出「卡片定义得了」的那部分（类型层 + 引用层的资产 + 案例，以及六种卡片边）；
+ * `evidence` / `cause` 与四条执行边由一次排查写入（`agent_diagnosis_case` 的 SourceRaw），
+ * 不在这里合成 —— 否则一次执行的结果会被伪装成可复用的知识。
  */
 export function cardsToGraph(cards: DiagnosisCard[]): CompiledDiagnosis {
   const nodes: AttributionNode[] = []
@@ -343,16 +368,25 @@ export function cardsToGraph(cards: DiagnosisCard[]): CompiledDiagnosis {
     seen.add(card.entityId)
   }
 
-  /** 资产节点按引用反推：引用层随数据目录同步，卡片里只留 id。 */
+  /**
+   * 资产节点按引用反推：引用层随数据目录同步，卡片里只留 id。
+   *
+   * `assets[]` 的每一项可以是 `"dwd_ord_di"`，也可以是 `{ id, type }` —— 后者顺带声明
+   * 资产的种类，它只影响「查询依据」那一段怎么分组（§7.7 ④），不改变边的两端。
+   */
   const assetIds = new Set<string>()
-  const modeIdByCode = new Map<FailureMode, string>()
+  const assetTypes = new Map<string, AssetType>()
+  const reasonIdByCode = new Map<FailureReason, string>()
 
   for (const card of cards) {
-    if (card.entityType === 'diagnosis/failure-mode' && typeof card.block.code === 'string') {
-      modeIdByCode.set(card.block.code as FailureMode, card.entityId)
+    if (card.entityType === 'diagnosis/failure-reason' && typeof card.block.code === 'string') {
+      reasonIdByCode.set(card.block.code as FailureReason, card.entityId)
     }
-    if (card.entityType === 'diagnosis/hypothesis' && Array.isArray(card.block.assets)) {
-      for (const id of card.block.assets) assetIds.add(String(id))
+    if (card.entityType === 'diagnosis/hypothesis' || card.entityType === 'diagnosis/check-point') {
+      for (const ref of assetRefsOf(card.block.assets)) {
+        assetIds.add(ref.id)
+        if (ref.type) assetTypes.set(ref.id, ref.type)
+      }
     }
   }
 
@@ -393,8 +427,8 @@ export function cardsToGraph(cards: DiagnosisCard[]): CompiledDiagnosis {
       if (discriminator) node.discriminator = discriminator
       const notWhen = stringOf(card.block.not_when)
       if (notWhen) node.notWhen = notWhen
-      const failureMode = stringOf(card.block.failure_mode)
-      if (failureMode) node.failureMode = failureMode as FailureMode
+      const failureReason = stringOf(card.block.failure_reason)
+      if (failureReason) node.failureReason = failureReason as FailureReason
       const reuse = numberOf(card.block.reuse_count)
       if (reuse !== undefined) node.reuseCount = reuse
       if (typeof card.block.stale === 'boolean') node.stale = card.block.stale
@@ -402,15 +436,15 @@ export function cardsToGraph(cards: DiagnosisCard[]): CompiledDiagnosis {
       for (const [index, target] of listOf(card.block.verified_by).entries()) {
         edges.push({ id: `e-${card.entityId.toLowerCase()}-${String(target).toLowerCase()}-${index}`, source: card.entityId, target: String(target), kind: 'verified_by' })
       }
-      for (const [index, asset] of listOf(card.block.assets).entries()) {
-        edges.push({ id: `e-${String(asset).toLowerCase()}-${card.entityId.toLowerCase()}-${index}`, source: String(asset), target: card.entityId, kind: 'indexed_from' })
+      for (const [index, asset] of assetRefsOf(card.block.assets).entries()) {
+        edges.push({ id: `e-${asset.id.toLowerCase()}-${card.entityId.toLowerCase()}-${index}`, source: asset.id, target: card.entityId, kind: 'indexed_from' })
       }
-      if (failureMode) {
-        const modeNode = modeIdByCode.get(failureMode as FailureMode)
-        if (modeNode) edges.push({ id: `e-${card.entityId.toLowerCase()}-${modeNode.toLowerCase()}`, source: card.entityId, target: modeNode, kind: 'categorized_as' })
-        else problems.push(`${card.entityId} 的 failure_mode=${failureMode} 找不到对应的失败模式卡片 —— categorized_as 边无从建立`)
+      if (failureReason) {
+        const reasonNode = reasonIdByCode.get(failureReason as FailureReason)
+        if (reasonNode) edges.push({ id: `e-${card.entityId.toLowerCase()}-${reasonNode.toLowerCase()}`, source: card.entityId, target: reasonNode, kind: 'categorized_as' })
+        else problems.push(`${card.entityId} 的 failure_reason=${failureReason} 找不到对应的失败原因卡片 —— categorized_as 边无从建立`)
       }
-    } else if (card.entityType === 'diagnosis/check') {
+    } else if (card.entityType === 'diagnosis/check-point') {
       const cost = numberOf(card.block.cost_minutes)
       if (cost !== undefined) node.costMinutes = cost
       const automation = stringOf(card.block.automation)
@@ -419,10 +453,18 @@ export function cardsToGraph(cards: DiagnosisCard[]): CompiledDiagnosis {
       if (verdictTrue) node.verdictTrue = verdictTrue
       const verdictFalse = stringOf(card.block.verdict_false)
       if (verdictFalse) node.verdictFalse = verdictFalse
+      const assets = assetRefsOf(card.block.assets).map(ref => ref.id)
+      if (assets.length > 0) node.assets = assets
       if (typeof card.block.stale === 'boolean') node.stale = card.block.stale
-    } else if (card.entityType === 'diagnosis/failure-mode') {
+
+      // 检查点 → 资产（`queries`）：这条检查要去查哪些对象。与假设上的
+      // `indexed_from`（这条假设落在哪个对象上）是两条边，方向和语义都不同。
+      for (const [index, asset] of assets.entries()) {
+        edges.push({ id: `e-${card.entityId.toLowerCase()}-${asset.toLowerCase()}-q${index}`, source: card.entityId, target: asset, kind: 'queries' })
+      }
+    } else if (card.entityType === 'diagnosis/failure-reason') {
       const code = stringOf(card.block.code)
-      if (code) node.code = code as FailureMode
+      if (code) node.code = code as FailureReason
     } else if (card.entityType === 'diagnosis/case') {
       const symptom = stringOf(card.block.symptom)
       if (!symptom) problems.push(`${card.entityId} 没有 symptom —— 案例必须从一个现象进入`)
@@ -447,7 +489,8 @@ export function cardsToGraph(cards: DiagnosisCard[]): CompiledDiagnosis {
 
   for (const id of assetIds) {
     if (nodes.some(node => node.id === id)) continue
-    nodes.push({ id, kind: 'asset', layer: 'reference', title: id })
+    const assetType = assetTypes.get(id)
+    nodes.push({ id, kind: 'asset', layer: 'reference', title: id, ...(assetType ? { assetType } : {}) })
   }
 
   // 引用完整性：卡片引用了不存在的卡片时，必须报出来（否则图上会出现悬空边，
@@ -461,6 +504,33 @@ export function cardsToGraph(cards: DiagnosisCard[]): CompiledDiagnosis {
   return { graph: { nodes, edges }, cases, problems }
 }
 
+/**
+ * `assets[]` 的一项 → `{ id, type? }`。
+ *
+ * 两种写法都认：`"dwd_ord_di"`（只留 id，资产随数据目录同步）与
+ * `{ id: "dwd_ord_di", type: "table" }`（顺带声明种类，供「查询依据」那一段分组）。
+ * 认不出来的项直接丢掉 —— 造一个 id 是 `[object Object]` 的资产节点，比少一条边难解释。
+ */
+function assetRefsOf(value: unknown): Array<{ id: string; type?: AssetType }> {
+  return listOf(value).flatMap((entry): Array<{ id: string; type?: AssetType }> => {
+    if (typeof entry === 'string') return entry.trim() ? [{ id: entry.trim() }] : []
+    if (entry && typeof entry === 'object') {
+      const record = entry as { id?: unknown; type?: unknown }
+      const id = stringOf(record.id)
+      if (!id) return []
+      const type = stringOf(record.type) as AssetType | undefined
+      return [{ id, ...(type ? { type } : {}) }]
+    }
+    return []
+  })
+}
+
+/** 写回卡片时用同一条规则：声明过种类就写成对象，否则保持一行一个 id 的短写法。 */
+function assetEntryOf(id: string, types: Map<string, AssetType>): string | { id: string; type: AssetType } {
+  const type = types.get(id)
+  return type ? { id, type } : id
+}
+
 function stringOf(value: unknown): string | undefined {
   return typeof value === 'string' && value.trim() !== '' ? value : undefined
 }

package/src/diagnosis/run.ts

@@ -0,0 +1,251 @@
+import type {
+  AttributionEdge, AttributionGraphData, AttributionNode, CasePathStep, DiagnosisRunEvidence, DiagnosisRunRecord,
+} from './types.js'
+import type { DiagnosisCard } from './cards.js'
+
+/**
+ * 一次排查的记录 —— `01_source_raw/agent_diagnosis_case/` 那条 SourceRaw 的编解码。
+ *
+ * ## 为什么它是一条 SourceRaw，而不是一个自造的 jsonl
+ *
+ * 排查产物要能被 `query_source_truth` 读到、被卡片引用、被 SourceRaw 已有的治理覆盖
+ * （分类、版本、检索），就得是一条 SourceRaw。自造一个 jsonl 格式，等于在知识库旁边
+ * 再养一套只读不进链路的数据 —— 这也是 0021 §0.3 撤销 `05_diagnosis/` 的直接原因。
+ *
+ * ## 它与案例卡片的区别
+ *
+ * | | 谁写 | 性质 |
+ * | --- | --- | --- |
+ * | 这条 SourceRaw（`agent_diagnosis_case`） | **Agent**，每次排查结束自动写 | 跑出来的**过程记录** |
+ * | 案例卡片（`diagnosis/case`） | Agent 提议 → **人确认** | 归纳出来的**结论** |
+ *
+ * 同一件事可以有两条记录，它们不是重复：一个回答「当时怎么走的」，一个回答「结论是什么」。
+ * 而案例卡片必须经人确认 —— 它落在类型层收敛的那一侧，见 0021 §6.1。
+ *
+ * ## 三段式
+ *
+ * 与卡片同构：正文小节给人读、` ```json diagnosis-run ` 块给机器读。序和枚举一进散文，
+ * 归并算法就再也读不到它了。
+ */
+
+/** 机器可读块的围栏标记。与卡片的 `json diagnosis` 分开，两种块不会互相误读。 */
+const RUN_FENCE = 'json diagnosis-run'
+
+/** 证据节点的标题取自 `result`；太长就截断，完整值仍在节点上。 */
+const EVIDENCE_TITLE_CHARS = 60
+
+export interface DiagnosisRunFile {
+  record: DiagnosisRunRecord
+  /** 正文小节（人读的部分）。由记录派生，不手写第二份。 */
+  sections: Array<{ heading: string; body: string }>
+}
+
+/**
+ * 一次排查的记录 → SourceRaw 正文。
+ *
+ * 正文按「现象 / 走过的路径 / 结论」三段组织：那是人打开这条来源时想看的三件事，
+ * 而机器要读的一切都在下面的块里。
+ */
+export function renderRunSource(record: DiagnosisRunRecord): string {
+  const path = record.path.length > 0
+    ? record.path.map(step => `- \`${step.label}\` ${step.note}${step.refuted ? '（否定）' : ''}`).join('\n')
+    : '（这次没有记录路径）'
+  const evidence = record.evidence.length > 0
+    ? record.evidence.map(item => `- \`${item.id}\` 跑 \`${item.checkPointId}\`：${item.result} —— ${verdictWord(item.verdict)}${item.why ? `，因为${item.why}` : ''}`).join('\n')
+    : '（这次没有产出证据）'
+  const conclusion = record.rootCause
+    ? [`**根因**：${record.rootCause.text}`, record.rootCause.fixAction ? `**修复**：${record.rootCause.fixAction}` : ''].filter(Boolean).join('\n\n')
+    : '（这次没有确认根因）'
+  const misleading = record.misleading && record.misleading.length > 0
+    ? `\n\n## 误导段\n\n${record.misleading.map(item => `- ${item.label}：浪费 ${item.wastedMinutes} 分钟。${item.why}`).join('\n')}`
+    : ''
+
+  return [
+    '## 现象',
+    '',
+    `入口现象 \`${record.symptomId}\`，开始于 ${record.startedAt}，总耗时 ${record.durationMinutes} 分钟。`,
+    '',
+    '## 走过的路径',
+    '',
+    path,
+    '',
+    '## 每个检查点的产出',
+    '',
+    evidence,
+    '',
+    '## 结论',
+    '',
+    conclusion,
+    misleading,
+    '',
+    '```' + RUN_FENCE,
+    JSON.stringify(record, null, 2),
+    '```',
+    '',
+  ].join('\n')
+}
+
+function verdictWord(verdict: DiagnosisRunEvidence['verdict']): string {
+  if (verdict === 'supports') return '支持'
+  if (verdict === 'refutes') return '否定'
+  return '给不出结论'
+}
+
+/** SourceRaw 正文 → 记录。块坏了或缺 runId 时返回 undefined（调用方如实报问题，不猜）。 */
+export function parseRunSource(content: string): DiagnosisRunRecord | undefined {
+  const match = content.match(new RegExp('```' + RUN_FENCE + '\\s*\\n([\\s\\S]*?)```'))
+  if (!match) return undefined
+  let value: unknown
+  try { value = JSON.parse(match[1]) } catch { return undefined }
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return undefined
+  const record = value as Partial<DiagnosisRunRecord>
+  if (typeof record.runId !== 'string' || !record.runId.trim()) return undefined
+  if (typeof record.symptomId !== 'string' || !record.symptomId.trim()) return undefined
+  return {
+    runId: record.runId,
+    symptomId: record.symptomId,
+    startedAt: typeof record.startedAt === 'string' ? record.startedAt : '',
+    durationMinutes: typeof record.durationMinutes === 'number' ? record.durationMinutes : 0,
+    path: Array.isArray(record.path) ? record.path as CasePathStep[] : [],
+    evidence: Array.isArray(record.evidence) ? record.evidence.filter(isEvidence) : [],
+    ...(record.rootCause && typeof record.rootCause === 'object' ? { rootCause: record.rootCause } : {}),
+    ...(Array.isArray(record.misleading) ? { misleading: record.misleading } : {}),
+  }
+}
+
+function isEvidence(value: unknown): value is DiagnosisRunEvidence {
+  if (!value || typeof value !== 'object') return false
+  const item = value as Partial<DiagnosisRunEvidence>
+  return typeof item.id === 'string' && typeof item.checkPointId === 'string'
+    && (item.verdict === 'supports' || item.verdict === 'refutes' || item.verdict === 'inconclusive')
+}
+
+/** 根因节点 id：记录里给了就用它，没给就按假设 id 生成一个稳定的。 */
+export function causeIdOf(record: DiagnosisRunRecord): string | undefined {
+  if (!record.rootCause) return undefined
+  return record.rootCause.id?.trim() || `C-${record.rootCause.hypothesisId}`
+}
+
+/**
+ * 记录 → 实例层节点与四条执行边。
+ *
+ * **它只产出执行产物**：`evidence` / `cause` 节点与 `produces` / `supports` / `refutes` /
+ * `confirmed_as`。类型层（现象、假设、检查点、失败原因）永远来自卡片 —— 把两者混在一起，
+ * 一次执行的结果就会被伪装成可复用的知识（§6.7 的边界表）。
+ */
+export function runToGraph(record: DiagnosisRunRecord): { nodes: AttributionNode[]; edges: AttributionEdge[]; problems: string[] } {
+  const nodes: AttributionNode[] = []
+  const edges: AttributionEdge[] = []
+  const problems: string[] = []
+  const seen = new Set<string>()
+
+  for (const item of record.evidence) {
+    if (seen.has(item.id)) problems.push(`证据 ${item.id} 在这次排查里出现了两次 —— 同一份产出只能有一个 id`)
+    seen.add(item.id)
+    const result = item.result ?? ''
+    nodes.push({
+      id: item.id,
+      kind: 'evidence',
+      layer: 'instance',
+      title: result.length > EVIDENCE_TITLE_CHARS ? `${result.slice(0, EVIDENCE_TITLE_CHARS)}…` : result || item.id,
+      summary: item.why,
+      query: item.query,
+      result,
+      verdict: item.verdict,
+      why: item.why,
+      at: item.at,
+      by: item.by,
+      ...(item.rawRef ? { rawRef: item.rawRef } : {}),
+    })
+    edges.push({ id: `run-${record.runId}-${item.checkPointId}-${item.id}`, source: item.checkPointId, target: item.id, kind: 'produces' })
+    // 给不出结论的证据**不挂支持 / 否定边**：它不是「弱支持」，它是没有结论。
+    // 把它挂成 supports 会让最贵的教训（便宜检查给不出结论）从模型里消失。
+    if (item.verdict !== 'inconclusive' && item.hypothesisId) {
+      edges.push({
+        id: `run-${record.runId}-${item.id}-${item.hypothesisId}`,
+        source: item.id,
+        target: item.hypothesisId,
+        kind: item.verdict === 'supports' ? 'supports' : 'refutes',
+      })
+    }
+  }
+
+  const causeId = causeIdOf(record)
+  if (record.rootCause && causeId) {
+    nodes.push({
+      id: causeId,
+      kind: 'cause',
+      layer: 'instance',
+      title: record.rootCause.text,
+      ...(record.rootCause.fixAction ? { summary: record.rootCause.fixAction } : {}),
+      ...(record.rootCause.confirmedAt ? { at: record.rootCause.confirmedAt } : {}),
+    })
+    edges.push({ id: `run-${record.runId}-${record.rootCause.hypothesisId}-${causeId}`, source: record.rootCause.hypothesisId, target: causeId, kind: 'confirmed_as' })
+  }
+
+  return { nodes, edges, problems }
+}
+
+/**
+ * 引用完整性：一次排查里的每个 id 都必须在图上真实存在。
+ *
+ * 缺了这条，一条写错 id 的诊断日志会在图上留下悬空的执行边 —— 而
+ * `validateDiagnosis` 只在读图之后才看得到，那时已经分不清是卡片错了还是日志错了。
+ *
+ * `knownIds` 要**同时包含卡片那部分与这次排查自己产出的那部分**：路径里的 `E1` / `C1`
+ * 正是这次排查自己写下的，只拿卡片图去比会把它们全判成悬空。
+ */
+export function runReferenceProblems(record: DiagnosisRunRecord, knownIds: ReadonlySet<string>): string[] {
+  const ids = knownIds
+  const problems: string[] = []
+  if (!ids.has(record.symptomId)) problems.push(`诊断日志 ${record.runId} 的入口现象 ${record.symptomId} 不存在`)
+  for (const item of record.evidence) {
+    if (!ids.has(item.checkPointId)) problems.push(`诊断日志 ${record.runId} 的证据 ${item.id} 指向不存在的检查点 ${item.checkPointId}`)
+    if (item.hypothesisId && !ids.has(item.hypothesisId)) problems.push(`诊断日志 ${record.runId} 的证据 ${item.id} 指向不存在的假设 ${item.hypothesisId}`)
+  }
+  if (record.rootCause && !ids.has(record.rootCause.hypothesisId)) {
+    problems.push(`诊断日志 ${record.runId} 的根因指向不存在的假设 ${record.rootCause.hypothesisId}`)
+  }
+  for (const step of record.path) {
+    if (!ids.has(step.nodeId)) problems.push(`诊断日志 ${record.runId} 的路径节点 ${step.nodeId} 不存在`)
+  }
+  return problems
+}
+
+/**
+ * 把一次排查归纳成一张**案例卡片**（还只是提议，要人确认才生效）。
+ *
+ * 归纳这一步是「过程记录 → 可复用知识」的那一跳，也是唯一需要人看的一跳：
+ * 路径里哪几步其实是误导、根因一句话怎么写，都是判断题。
+ */
+/**
+ * 一次排查的案例卡片草案（0044 前叫 `caseProposalOf`）。
+ *
+ * 改名是因为它产出的东西**直接落卡**，不再是一条提议：名字里留着 `Proposal` 会让下一个
+ * 读的人继续在两个时代之间猜。函数体一行没动 —— 它本来就是「从一条排查记录编出一张案例卡」。
+ */
+export function caseCardOf(record: DiagnosisRunRecord, symptomTitle: string): DiagnosisCard {
+  const rootCause = record.rootCause?.text ?? '（这次没有确认根因）'
+  const firstMisleading = record.misleading?.[0]
+  return {
+    entityId: `CASE-${record.runId}`,
+    entityType: 'diagnosis/case',
+    title: symptomTitle,
+    status: 'unreviewed',
+    sourceRefs: [],
+    sections: [
+      { heading: '现象', body: `入口现象 \`${record.symptomId}\`（${symptomTitle}），开始于 ${record.startedAt}。` },
+      { heading: '影响面', body: '（待补：这次影响到了谁、范围多大）' },
+      { heading: '排查过程', body: record.path.map(step => `- \`${step.label}\` ${step.note}${step.refuted ? '（否定）' : ''}`).join('\n') || '（没有记录路径）' },
+      { heading: '根因', body: rootCause },
+      { heading: '修复与防复发', body: record.rootCause?.fixAction ?? '（待补：修复动作与防复发措施）' },
+    ],
+    block: {
+      symptom: record.symptomId,
+      path: record.path,
+      duration_minutes: record.durationMinutes,
+      ...(firstMisleading ? { misleading: firstMisleading } : {}),
+      root_cause: rootCause,
+    },
+  }
+}