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

package/src/client/attribution/model.ts

@@ -1,17 +1,20 @@
 import { ZOMBIE_EDGE_DAYS } from '../../diagnosis/types.js'
 import {
-  PROBLEM_CLASSES, PROBLEM_CLASS_LABEL, problemClassIds, problemSubclassOf,
+  PROBLEM_CLASSES, PROBLEM_CLASS_LABEL, problemClassIds, problemClassOf, problemSubclassOf,
 } from '../../diagnosis/problem-classes.js'
 import type { ProblemClassId } from '../../diagnosis/problem-classes.js'
 import type {
+  AssetType,
   AttributionEdge, AttributionEdgeKind, AttributionGraphData, AttributionNode, AttributionNodeKind,
-  AttributionStats, FailureMode, NodeLayer,
+  AttributionStats, FailureReason, NodeLayer,
 } from '../../diagnosis/types.js'
 
 export { ZOMBIE_EDGE_DAYS, PROBLEM_CLASSES, PROBLEM_CLASS_LABEL, problemClassIds, problemSubclassOf }
 export type {
+  AssetType,
   AttributionEdge, AttributionGraphData, AttributionNode, AttributionNodeKind,
-  AttributionEdgeKind, AttributionStats, FailureMode, NodeLayer,
+  AttributionEdgeKind, AttributionStats, FailureReason, NodeLayer,
+  AttributionCase, CaseSection, CasePathStep,
 } from '../../diagnosis/types.js'
 export type { ProblemClassId, ProblemSubclassSpec } from '../../diagnosis/problem-classes.js'
 
@@ -30,10 +33,10 @@ export const LAYER_TONES: Record<NodeLayer, 'blue' | 'violet' | 'amber'> = {
 }
 
 /**
- * 失败模式 → 颜色。分类在图谱视图里是**着色**而不是分区，所以它只影响一眼扫过的
+ * 失败原因 → 颜色。分类在图谱视图里是**着色**而不是分区，所以它只影响一眼扫过的
  * 分组感，不影响节点位置 —— 位置由布局按边的方向决定。
  */
-export const FAILURE_MODE_STYLE: Record<FailureMode, { label: string; fill: string; stroke: string; text: string }> = {
+export const FAILURE_REASON_STYLE: Record<FailureReason, { label: string; fill: string; stroke: string; text: string }> = {
   'upstream-missing': { label: '上游未产出', fill: '#eef4ff', stroke: '#2563eb', text: '#1d4ed8' },
   'spec-change': { label: '口径变更', fill: '#f3f0ff', stroke: '#6b54cf', text: '#5b45be' },
   'data-processing': { label: '数据处理', fill: '#eafaf2', stroke: '#12875f', text: '#0f6b4d' },
@@ -78,23 +81,458 @@ export const NEUTRAL_STYLE = { fill: '#ffffff', stroke: '#d6dce6', text: '#74809
 export const NODE_KIND_LABEL: Record<AttributionNodeKind, string> = {
   symptom: '现象',
   hypothesis: '假设',
-  check: '检查',
-  'failure-mode': '失败模式',
+  check_point: '检查点',
+  failure_reason: '失败原因',
   asset: '资产',
   case: '案例',
   evidence: '证据',
   cause: '根因',
   unknown: '未归类',
 }
+/* ────────────────────────────────────────────────────────────────────────────
+ * 动线视角：五段泳道（0021 §7.7 / §4.6）
+ *
+ * 这一节是**纯数据**：段名、每段装什么、段内怎么排、段位坐标。
+ * 「画在画布上」与「画成 HTML 泳道带」都读同一份结果，两处不可能对不上 ——
+ * 这正是 §7.7「空段不隐藏」「断链」能被断言而不是被眼力的原因。
+ * ──────────────────────────────────────────────────────────────────────────── */
+
+/**
+ * 五个段位。
+ *
+ * 段名固定成这五个词，**不写「第一步 / 第二步」**（§7.5）：它们是数据的分段，
+ * 不是操作步骤；操作步骤在排查视图里，写成步骤会让「同一现象有 N 个假设」
+ * 读起来像「做错了要重来」。
+ *
+ * `note` 是**空段说明**：一段为空时画在段头右边的那句话。它必须与段的存在理由
+ * 对上 —— 曲线是「哪一段还没建」这张图最该显眼的信息（§7.7）。
+ */
+export type LaneId = 'symptom' | 'hypothesis' | 'check_point' | 'asset' | 'instance'
+
+export interface LaneSpec {
+  id: LaneId
+  /** 段号 ①②③④⑤。它是**顺序**，不是步骤编号。 */
+  ordinal: string
+  label: string
+  /** 这一段按什么排序 —— 写在段头右侧的读法。 */
+  orderHint: string
+  /** 空段时显示的一句话。 */
+  note: string
+  kinds: AttributionNodeKind[]
+  /** 实例层：随每次排查线性增长，因此默认折叠（§7.7 末段）。 */
+  instance: boolean
+}
+
+export const LANES: LaneSpec[] = [
+  {
+    id: 'symptom', ordinal: '①', label: '问题现象', orderHint: '按问题大类 → 子类',
+    note: '还没有现象：先登记一条异常现象', kinds: ['symptom'], instance: false,
+  },
+  {
+    id: 'hypothesis', ordinal: '②', label: '假设原因', orderHint: '按 prior ÷ 最低检查点成本',
+    note: '还没有假设：现象下面一条候选原因都没有', kinds: ['hypothesis'], instance: false,
+  },
+  {
+    id: 'check_point', ordinal: '③', label: '检查点', orderHint: '按 cost_minutes 升序',
+    note: '还没有检查点：有假设但走不下去，就是断链', kinds: ['check_point'], instance: false,
+  },
+  {
+    id: 'asset', ordinal: '④', label: '查询依据', orderHint: '经 queries 边 · 按类型',
+    note: '还没有查询依据：检查点没写 assets', kinds: ['asset'], instance: false,
+  },
+  {
+    id: 'instance', ordinal: '⑤', label: '实际查询与结果', orderHint: '按时间倒序 · 默认折叠',
+    note: '还没有实际查询：这些检查一次都没跑过',
+    kinds: ['evidence', 'cause', 'unknown'], instance: true,
+  },
+]
+
+const LANE_BY_KIND: Record<AttributionNodeKind, LaneId | undefined> = {
+  symptom: 'symptom',
+  hypothesis: 'hypothesis',
+  check_point: 'check_point',
+  asset: 'asset',
+  failure_reason: undefined,
+  case: undefined,
+  evidence: 'instance',
+  cause: 'instance',
+  unknown: 'instance',
+}
+
+/** 节点属于哪一段。`failure_reason` / `case` 不属于任何一段（见 LANES 的注释）。 */
+export function laneOf(node: AttributionNode): LaneId | undefined {
+  return LANE_BY_KIND[node.kind]
+}
+
+/**
+ * 动线布局里**没有段位**的节点种类。
+ *
+ * 从 `LANE_BY_KIND` 派生，不另写一份清单：漏一个的后果不是报错，而是画布上多一个
+ * **无处安放的孤儿节点** —— 它没有段位坐标，只能落在力导向的种子位置上，看起来像
+ * 「图里有个不该在这儿的东西」。这正是 `failure_reason` 之前的状态：5 个节点悬在
+ * 画布上，还带着 7 条 `categorized_as` 长边从②段横穿出去。
+ *
+ * 它们要说的信息**已经由假设节点的填充色承载**（§7.2「颜色 = 失败原因」），
+ * 所以动线视角不画它们不是丢信息，是去掉重复表达。关系视图照旧全画。
+ */
+export const OFF_LANE_KINDS: AttributionNodeKind[] = (Object.keys(LANE_BY_KIND) as AttributionNodeKind[])
+  .filter(kind => LANE_BY_KIND[kind] === undefined)
+
+/**
+ * 动线布局里**不画**的边。
+ *
+ * `indexed_from` 是「资产 → 假设」的**反向索引**，而动线的方向是
+ * 假设 → 检查点 → 查询依据。它指向反方向，会从④段一路横穿③段回到②段 ——
+ * 在这个布局里它只制造交叉，不承载动线。关系视图里保留（那里方向由力导向决定）。
+ */
+export const OFF_LANE_EDGE_KINDS: AttributionEdgeKind[] = ['indexed_from']
+
+/**
+ * 画布的作用域：按布局决定「哪些节点与边根本不进这张画布」。
+ *
+ * 把它做成一个函数而不是散在各处的 `if (layout === 'line')`，是为了让
+ * 「动线少画什么」只有一处答案 —— 否则它迟早会在三处各说各话，而表现是
+ * 「同一个节点在画布上有、在段头计数里没有」这类对不上的读数。
+ *
+ * 形参写 `'line' | 'force'` 而不是 `GraphLayout`：那个类型住在 `graph-options.ts`，
+ * 而它 import 这个文件 —— 反向 import 会成环。
+ */
+export function canvasScope(layout: 'line' | 'force'): { kinds: ReadonlySet<AttributionNodeKind>; edges: ReadonlySet<AttributionEdgeKind> } {
+  return layout === 'line'
+    ? { kinds: new Set(OFF_LANE_KINDS), edges: new Set(OFF_LANE_EDGE_KINDS) }
+    : { kinds: new Set<AttributionNodeKind>(), edges: new Set<AttributionEdgeKind>() }
+}
+
+/** 段 → 这一段的节点种类。四组切面用它表达「关掉检查点 = 第三段整段不画」。 */
+export const LANE_KINDS: Record<LaneId, AttributionNodeKind[]> = Object.fromEntries(
+  LANES.map(lane => [lane.id, lane.kinds]),
+) as Record<LaneId, AttributionNodeKind[]>
+
+/**
+ * 这一段的节点是否被画出。
+ *
+ * `kinds` 空集 = 不过滤（与其余切面同一条规则）。实例层还要过 `includeInstance`：
+ * ⑤ 段默认折叠，但被点亮的那条链例外（§7.7 末段），那条例外由 `chainIds` 承担。
+ */
+export function laneKindVisible(kinds: ReadonlySet<AttributionNodeKind>, lane: LaneSpec): boolean {
+  if (kinds.size === 0) return true
+  return lane.kinds.some(kind => kinds.has(kind))
+}
+
+/**
+ * 资产类型的固定顺序（表 / 指标 / 任务 / 链路）。
+ *
+ * 顺序按「排查时最常先想到的对象」排：先看表，再看指标口径，再看产出它的任务，
+ * 最后才是链路级的东西。缺省的类型排在最后 —— **不抖动**比排得对更重要，
+ * 同一份数据刷新之后顺序变了，图上就没有可依赖的空间记忆。
+ */
+export const ASSET_TYPE_ORDER: AssetType[] = ['table', 'metric', 'job', 'linkage']
+
+/** 资产类型的中文界面词。 */
+export const ASSET_TYPE_LABEL: Record<AssetType, string> = {
+  table: '表',
+  metric: '指标',
+  job: '任务',
+  linkage: '链路',
+}
+
+/** 「≤ 5 分钟」这条成本预设的界线。 */
+export const CHECK_COST_FAST_MINUTES = 5
+
+/** 成本预设：三档。`undefined` 表示某一档不参与。 */
+export interface CheckCostBand {
+  id: 'fast' | 'medium' | 'slow'
+  label: string
+  within: (minutes: number) => boolean
+}
+
+export const CHECK_COST_BANDS: CheckCostBand[] = [
+  { id: 'fast', label: `≤ ${CHECK_COST_FAST_MINUTES} 分钟`, within: m => m <= CHECK_COST_FAST_MINUTES },
+  { id: 'medium', label: `${CHECK_COST_FAST_MINUTES}–15 分钟`, within: m => m > CHECK_COST_FAST_MINUTES && m <= 15 },
+  { id: 'slow', label: '> 15 分钟', within: m => m > 15 },
+]
+
+/** 时间倒序用的时间戳：解析不了就当作 0（排在最后），绝不抛。 */
+export function timestampOf(node: AttributionNode): number {
+  const raw = node.at
+  if (!raw) return 0
+  const parsed = Date.parse(raw)
+  return Number.isNaN(parsed) ? 0 : parsed
+}
+
+/**
+ * 一段的头两行读数：`段名 + 这一段的节点数`。
+ *
+ * `total` 是**过滤前**的节点数：段头必须回答「这一段本来有多少、现在画了几个」，
+ * 只报画出来的那个数，切面一开就成了「这张图本来就这么小」。
+ */
+export interface LaneSegment {
+  lane: LaneSpec
+  /** 过滤后、落在这一段里的节点，已按 `orderHint` 排好。 */
+  nodes: AttributionNode[]
+  /** 过滤前的节点数。 */
+  total: number
+  /** 这一段在数据里本来就一条都没有（不是被切面关掉的，也不是被收起的）。 */
+  empty: boolean
+  /**
+   * 这一段里**没被画出来**的节点（`total - nodes` 的那一份，保持段内顺序）。
+   *
+   * 两种用途，都是「有，但这一屏不画」：
+   * - ① 段：`focusSymptomId` 之外的现象 —— 它们变成段头上的切换入口；
+   * - ④⑤ 段：收起时的那几个 —— 段头写「已收起 · N 个」。
+   *
+   * 与 `total` 分开是因为 `total` 只是个数字，而入口需要**知道是哪几个**。
+   */
+  hidden: AttributionNode[]
+  /**
+   * 这一段被**收起**：有数据，是「暂时不看」。
+   *
+   * 与 `empty` 是两件必须分开的事：收起是选择，空是缺失。把两者画成同一个样子，
+   * 段头就会在用户主动收起④段时写「还没有查询依据：检查点没写 assets」——
+   * 那是**在撒谎**，而且恰好抹掉了「哪一段还没建」这个最该显眼的读数（§7.7）。
+   */
+  collapsed: boolean
+}
+
+/**
+ * 段内排序键（升序）。
+ *
+ * 每条都对应 §7.7 表里的那一列，而且**只用卡片上能核对的字段**：
+ * 现象用问题大类 → 子类；假设用优先分（§4.4）取负；检查点用成本；
+ * 资产用类型；实例层用时间取负。
+ *
+ * `priorities` 是优先分表（见 `lanePriorityScores`）。**必须由调用方传入而不是
+ * 在这里现算** —— 优先分的定义点在 `candidatesOf`，如果这里再写一遍公式，
+ * 「排序」和「排查视图的候选排序」就有了两份实现，迟早会漂移。
+ */
+export function laneSortKey(node: AttributionNode, priorities: ReadonlyMap<string, number> = new Map()): number {
+  switch (node.kind) {
+    case 'symptom': {
+      // 先按问题大类，再按子类（§7.7 ① 段）。子类的顺序取它在大类里的定义顺序 ——
+      // 那是「看到异常之后的判断顺序」，不是字母序。
+      const owner = problemClassOf(node.problemSubclass)
+      const major = owner ? PROBLEM_CLASS_ORDER.indexOf(owner) : PROBLEM_CLASS_ORDER.length
+      const siblings = owner ? (PROBLEM_CLASSES.find(item => item.id === owner)?.subclasses ?? []) : []
+      const sub = siblings.findIndex(item => item.id === node.problemSubclass)
+      return major * 100 + (sub < 0 ? 99 : sub)
+    }
+    case 'hypothesis':
+      // 优先分越大越靠前 → 取负。空区拿不到分（表里没有它），记 0 排在这一段末尾。
+      return -(priorities.get(node.id) ?? 0)
+    case 'check_point':
+      return node.costMinutes ?? Number.MAX_SAFE_INTEGER
+    case 'asset': {
+      // 资产类型**由卡片声明**（`assets[]` 写成 `{ id, type }`），不由代码从 id 猜：
+      // 猜前缀会在有人给表起名 `t_xxx` 的那天静默失效，而失效的表现是「这一段排序
+      // 莫名其妙地变了」。没声明就退回 id 序 —— 两种都稳定、可复现。
+      const index = node.assetType ? ASSET_TYPE_ORDER.indexOf(node.assetType) : -1
+      return index < 0 ? ASSET_TYPE_ORDER.length : index
+    }
+    default:
+      // 实例层：按时间倒序 → 取负。
+      return -timestampOf(node)
+  }
+}
+
+/**
+ * 假设 id → 优先分（§4.4 的 `prior ÷ 最低检查点成本`）。
+ *
+ * **直接读 `candidatesOf`**：那是优先分唯一的实现，排查视图的候选排序也用它。
+ * 一条假设被多个现象指向时取其中**最高**的分 —— 它问的是「这条假设现在值不值得先查」，
+ * 而不是「哪个现象问的」。不在任何现象的候选集里的假设（今天没有这种数据，
+ * 但结构上允许）分记 0，排在这一段的末尾而不是消失。
+ */
+export function lanePriorityScores(data: AttributionGraphData): Map<string, number> {
+  const scores = new Map<string, number>()
+  for (const symptom of data.nodes) {
+    if (symptom.kind !== 'symptom') continue
+    for (const candidate of candidatesOf(data, symptom.id)) {
+      const best = scores.get(candidate.hypothesis.id)
+      if (best === undefined || candidate.score > best) scores.set(candidate.hypothesis.id, candidate.score)
+    }
+  }
+  return scores
+}
+
+/**
+ * 只留下「至少有一段要画它」的节点种类。
+ *
+ * 这是 §7.3「类型切面被三组吸收」的实现：按 `kind` 勾选与按动线段落收窄说的
+ * 是同一件事，同时存在只会让人犹豫点哪个 —— 所以 `kinds` 收窄的是**段**，
+ * 关闭一段 = 那一段的节点种类一起离开。
+ */
+export function narrowedToLanes(nodes: AttributionNode[], kinds: ReadonlySet<AttributionNodeKind>): AttributionNode[] {
+  if (kinds.size === 0) return nodes
+  const open = new Set<LaneId>()
+  for (const lane of LANES) if (laneKindVisible(kinds, lane)) open.add(lane.id)
+  // 不属于任何一段的节点（失败原因、案例）跟着**任意一段开着**就留下：
+  // 它们不是某一段的内容，而是挂在段上的标签与路径记录。
+  return nodes.filter(node => {
+    const lane = laneOf(node)
+    return lane === undefined ? open.size > 0 : open.has(lane)
+  })
+}
+
+/**
+ * 五段泳道的分段结果。
+ *
+ * 两条硬规则：
+ * 1. **空段不隐藏** —— 一条都没有的段照样返回，`empty: true`，段头写 note。
+ * 2. **实例层默认折叠** —— `includeInstance` 关掉时 ⑤ 段只留计数；`chainIds`
+ *    里被点亮的那条链上的实例节点例外（§7.7 末段）。
+ */
+export function laneSegments(data: AttributionGraphData, options: {
+  /** 是否展开实例层（⑤ 段）。 */
+  includeInstance?: boolean
+  /** 被点亮的那条链；其中的实例节点在折叠态下仍然画出来。 */
+  chainIds?: ReadonlySet<string>
+  /**
+   * 被用户收起的段。**有数据但不画**。
+   *
+   * 收起是**默认读法的一部分**，不是附加功能：面板只有 380px 宽，五段全铺时
+   * ④ 查询依据要占掉 5 个节点 + 11 条跨段边，而它是引用层的定位锚点（§0.1
+   * 「只作定位锚点」），不是动线上的决策对象。默认收起它，非空段从 4 段降到 3 段，
+   * 每段的节点能明显变大。
+   *
+   * 与 ⑤ 段的折叠是同一条规矩（§7.7 末段）：**被点亮的那条链上的节点例外**，
+   * 照样画出来 —— 用户点开一条链，就是在问「这条路到底走到哪」。
+   */
+  collapsedLanes?: ReadonlySet<LaneId>
+  /**
+   * ① 段**只画这一个现象**（动线视角的当前现象），其余现象进 `hidden` 变成切换入口。
+   *
+   * 为什么必须收窄：3 个现象共享 7 个假设（§4.5），于是 ①→② 之间有 14 条
+   * `may_be_caused_by`，而它们**互相交叉** —— 交叉的成因是「有三个起点」，不是
+   * 「哪条边不该画」。只留一个起点之后，那 7 条线从一个点扇出，彼此不再相交，
+   * 而画布上剩下的每一条边**都真实属于当前这个现象**（不是把别的现象的边藏起来
+   * 假装它不存在）。
+   *
+   * 代价说清楚：「三个现象共享同一批假设」这件事在动线视角里就看不到了，
+   * 它在关系视图里照旧。动线回答的是「这个现象的下一步」。
+   */
+  focusSymptomId?: string
+} = {}): LaneSegment[] {
+  const includeInstance = options.includeInstance ?? false
+  const chainIds = options.chainIds ?? new Set<string>()
+  const collapsedLanes = options.collapsedLanes ?? new Set<LaneId>()
+  const focusSymptomId = options.focusSymptomId
+  const priorities = lanePriorityScores(data)
+
+  return LANES.map(lane => {
+    const all = data.nodes.filter(node => laneOf(node) === lane.id)
+    /**
+     * **三态互斥**：空（没数据）/ 收起（有数据但不画）/ 展开。
+     *
+     * `all.length > 0 &&` 这一半不能省：⑤ 实例层默认就是「收起」的，而一个**空**的
+     * ⑤ 段也会因此被标成「收起」。段头的读数先看 `total === 0`，所以画出来是对的 ——
+     * 但模型层同时说「它是空的」和「它被收起了」，下一个读这两个字段的人就会踩坑。
+     */
+    const collapsed = all.length > 0 && (collapsedLanes.has(lane.id) || (lane.instance && !includeInstance))
+    // ① 段收窄到当前现象。**只在真的能指出那一个时收窄** —— `focusSymptomId` 指向一个
+    // 不存在的 id 时若照收窄，① 段会整段空掉，而段头写的是「还没有现象」：那是在撒谎。
+    const focused = lane.id === 'symptom' && focusSymptomId !== undefined && all.some(node => node.id === focusSymptomId)
+    const visible = collapsed
+      ? all.filter(node => chainIds.has(node.id))
+      : focused ? all.filter(node => node.id === focusSymptomId) : all
+    const ordered = visible.slice().sort((a, b) =>
+      laneSortKey(a, priorities) - laneSortKey(b, priorities) || a.id.localeCompare(b.id))
+    const drawn = new Set(ordered.map(node => node.id))
+    return {
+      lane, nodes: ordered, total: all.length, empty: all.length === 0, collapsed,
+      hidden: all.filter(node => !drawn.has(node.id)),
+    }
+  })
+}
+
+/**
+ * 段的分段结果 → 段位布局的入参。
+ *
+ * `laneLayoutOf` 只关心「哪一段、按什么顺序」，段名与计数是段头的事；两边用这一层
+ * 薄映射隔开，`graph-options.ts` 就不必 import 这个文件的段类型。
+ */
+export function laneBandsOf(segments: LaneSegment[]): Array<{ laneId: LaneId; nodes: AttributionNode[] }> {
+  return segments.map(segment => ({ laneId: segment.lane.id, nodes: segment.nodes }))
+}
+
+/**
+ * 一条被点亮的链：从选中的现象 / 假设出发，沿**有语义方向**的边往前走。
+ *
+ * 方向沿用 `PROBLEM_SCOPE_EDGES` 那份判断（产出性关系朝前、归属与索引朝后），
+ * 再加上实例层的四条执行边。之所以不能双向：双向会经由共享假设串回另外两个
+ * 现象，点一个现象就把整张图点亮 —— 那等于没有高亮。
+ *
+ * **从现象出发只走一跳。** 现象有 7 条候选假设（§4.5：三个现象共享同一批假设），
+ * 再往前就会经由每条假设铺开它们的检查点、资产与证据 —— 点 S1 会点亮 25/28 个节点。
+ * 那正是「点亮」要避免的结果。现象那一跳要回答的是「它有哪些候选原因」；
+ * 「这条假设往下怎么查」属于假设的链，点那个假设才展开（§7.4 第 9 条）。
+ *
+ * `refutes` 也算数：被否定的边同样是这条链走过的一段（§7.4 第 3 条）。
+ */
+export function chainOf(data: AttributionGraphData, startId: string): Set<string> {
+  const start = data.nodes.find(node => node.id === startId)
+  const chain = new Set<string>([startId])
+  let frontier = new Set<string>([startId])
+  // 链最长不会超过节点数；这个上界只是防止数据里出现环时死循环。
+  for (let step = 0; step < data.nodes.length; step += 1) {
+    const next = new Set<string>()
+    for (const edge of data.edges) {
+      const direction = CHAIN_EDGES[edge.kind]
+      if (direction === undefined) continue
+      // 现象出发只走一跳：第二跳起整张图都会被点亮（见函数头）。
+      if (start?.kind === 'symptom' && step >= 1) continue
+      const from = direction === 'forward' ? edge.source : edge.target
+      const to = direction === 'forward' ? edge.target : edge.source
+      if (frontier.has(from) && !chain.has(to)) next.add(to)
+    }
+    if (next.size === 0) break
+    for (const id of next) chain.add(id)
+    frontier = next
+  }
+  return chain
+}
+
+/** 点亮链允许走的边与方向。 */
+const CHAIN_EDGES: Partial<Record<AttributionEdgeKind, 'forward' | 'backward'>> = {
+  may_be_caused_by: 'forward',
+  verified_by: 'forward',
+  categorized_as: 'forward',
+  queries: 'forward',
+  produces: 'forward',
+  confirmed_as: 'forward',
+  // 证据 → 假设：由已跑过的证据找回它支持 / 否定的假设。方向朝前即可 ——
+  // 起点若是假设，`supports` 的箭头指向它，落在 `backward` 那一侧才是它的入边。
+  supports: 'backward',
+  refutes: 'backward',
+}
 
 /**
- * 会出现在「类型」筛选里的节点类型。
+ * 会不会被点亮：**只有从现象或假设出发**才点亮一条链。
  *
- * 只列**会被筛**的类型：证据 / 根因 / 案例是实例层的附属，默认就折叠着，
- * 把它们列进筛选器只会让用户点出一个空图。这份名单是模型事实（哪些类型值得筛），
- * 不是界面偏好，所以放在模型层 —— 界面层两个组件（工具条、筛选条）都要用它。
+ * 从资产或检查点出发也「有链」，但那回答的是「谁指向我」，与 §7.4 第 9 条
+ * 「下一步查什么」不是同一个问题。所以起点做限制，画布上点其它节点只切聚焦。
  */
-export const FILTERABLE_KINDS: AttributionNodeKind[] = ['symptom', 'hypothesis', 'check', 'asset', 'failure-mode']
+export function chainStartAllowed(node: AttributionNode | undefined): boolean {
+  return node?.kind === 'symptom' || node?.kind === 'hypothesis'
+}
+
+
+/**
+ * 会出现在**段切面**里的节点种类 = 会画在画布上的那几段。
+ *
+ * **不再是独立的一份名单。** v1.4 撤销了笼统的「类型切面」：节点可见性由它所属的
+ * 那一段承担（§7.3），所以这份名单由 `LANES` 派生 —— 加一段就自动多一类，
+ * 不会出现「段能画、切面里找不到」这种两处对不上的情况。
+ *
+ * **实例层（⑤ 段）不在这份名单里**：它默认就折叠着，列进切面只会让用户点出一个
+ * 空图（那份名单原来把这条写成了注释，现在由 `instance` 这一格承担）。
+ * 展开 ⑤ 段是右上的一个显式开关，不是切面。
+ *
+ * 顺序按动线：现象 → 假设 → 检查点 → 资产。失败原因与案例不在这份名单里，
+ * 它们不是某一段的内容（失败原因是假设的标签，案例是路径的记录）。
+ * 定义点排在 `LANES` 之后 —— 模块求值时它要读到 `LANES`。
+ */
+export const FILTERABLE_KINDS: AttributionNodeKind[] =
+  LANES.filter(lane => !lane.instance).flatMap(lane => lane.kinds)
 
 /**
  * 节点尺寸：假设节点按复用次数放大，其余按类型给固定宽高。
@@ -111,9 +549,9 @@ export function nodeBoxOf(node: AttributionNode): [number, number] {
     return [size, size]
   }
   if (node.kind === 'symptom') return [150, 44]
-  if (node.kind === 'check') return [156, 38]
+  if (node.kind === 'check_point') return [156, 38]
   if (node.kind === 'asset') return [132, 36]
-  if (node.kind === 'failure-mode') return [104, 30]
+  if (node.kind === 'failure_reason') return [104, 30]
   if (node.kind === 'case') return [184, 38]
   return [150, 36]
 }
@@ -125,10 +563,10 @@ export function nodeShapeOf(node: AttributionNode): 'circle' | 'rect' {
 
 /** 节点的取色：假设跟着失败模式走，其余走层色。 */
 export function nodeStyleOf(node: AttributionNode): { fill: string; stroke: string; text: string } {
-  if (node.failureMode) return FAILURE_MODE_STYLE[node.failureMode]
+  if (node.failureReason) return FAILURE_REASON_STYLE[node.failureReason]
   if (node.layer === 'reference') return { fill: '#eef4ff', stroke: '#9ec2ff', text: '#1d4ed8' }
   if (node.kind === 'symptom') return { fill: '#fff7ea', stroke: '#b96d14', text: '#96580f' }
-  if (node.kind === 'check') return { fill: '#f5f1ff', stroke: '#c9b8ff', text: '#5b45be' }
+  if (node.kind === 'check_point') return { fill: '#f5f1ff', stroke: '#c9b8ff', text: '#5b45be' }
   return NEUTRAL_STYLE
 }
 
@@ -186,6 +624,24 @@ export function visibleEdges(data: AttributionGraphData, nodes: AttributionNode[
   return data.edges.filter(edge => ids.has(edge.source) && ids.has(edge.target))
 }
 
+/* ────────────────────────────────────────────────────────────────────────────
+ * 动线视角：五段泳道（0021 §7.7 / §4.6）
+ *
+ * 这一节是**纯数据**：段名、每段装什么、段内怎么排、段位坐标。
+ * 「画在画布上」与「画成 HTML 泳道带」都读同一份结果，两处不可能对不上 ——
+ * 这正是 §7.7「空段不隐藏」「断链」能被断言而不是被眼力的原因。
+ * ──────────────────────────────────────────────────────────────────────────── */
+
+/**
+ * 五个段位。
+ *
+ * 段名固定成这五个词，**不写「第一步 / 第二步」**（§7.5）：它们是数据的分段，
+ * 不是操作步骤；操作步骤在排查视图里，写成步骤会让「同一现象有 N 个假设」
+ * 读起来像「做错了要重来」。
+ *
+ * `note` 是**空段说明**：一段为空时画在段头右边的那句话。它必须与段的存在理由
+ * 对上 —— 曲线是「哪一段还没建」这张图最该显眼的信息（§7.7）。
+ */
 /**
  * 以某个节点为中心取 N 跳邻域。
  *
@@ -234,6 +690,28 @@ export function degreeOf(data: AttributionGraphData, id: string): number {
 }
 
 /** 默认焦点：类型层里度数最高的假设。没有假设时退化为第一个节点。 */
+/**
+ * 打开这一栏时，**默认点亮哪条链**（§7.4 第 9 条：「路径高亮是默认读法，不是附加功能」）。
+ *
+ * 取①段**排好序之后的第一个现象** —— 就是扫视时先看到的那个。不取「候选最多的」：
+ * 那会让默认焦点随着别处新增一个假设而跳走，而空间记忆靠的正是「上次那个在哪儿」。
+ *
+ * 只挑**真的能点亮一条链**的现象（至少有一条 `may_be_caused_by` 从它出去）。点亮一个
+ * 孤立现象会让整张图暗下去而它什么都没连上 —— 那看起来像界面坏了，而不是
+ * 「这个现象还没建」，而后者才是真相。
+ */
+export function defaultChainStart(data: AttributionGraphData): string | undefined {
+  const hasCandidate = new Set(
+    data.edges.filter(edge => edge.kind === 'may_be_caused_by').map(edge => edge.source),
+  )
+  const priorities = lanePriorityScores(data)
+  const symptoms = data.nodes
+    .filter(node => node.kind === 'symptom' && hasCandidate.has(node.id))
+    // 与①段的段内排序**同一把尺**：这样「默认点亮的那个」就是段里最左边那个。
+    .sort((a, b) => laneSortKey(a, priorities) - laneSortKey(b, priorities) || a.id.localeCompare(b.id))
+  return symptoms[0]?.id
+}
+
 export function defaultFocusId(data: AttributionGraphData): string | undefined {
   const hypotheses = data.nodes.filter(node => node.kind === 'hypothesis')
   if (hypotheses.length === 0) return data.nodes[0]?.id
@@ -256,9 +734,13 @@ export interface AttributionCandidate {
 }
 
 /**
- * 近 30 天的同现象排查样本量，用作根因占比的分母。
+ * 根因占比的**示例分母**，取自 0021 §4.4 的示例表
+ * （12 / 6 / 4 / 3 / 1 / 5 / 2，合计 33 次已归类 + 8 次未归类 = 41）。
  *
- * 与 0021 §4.4 的示例表一致（12 / 6 / 4 / 3 / 1 / 5 / 2，合计 33 次已归类 + 8 次未归类）。
+ * ⚠️ **它不是这个知识库的真实样本量。** `prior` 属于卡片信封里的 `stats`（系统回填），
+ * 而回填还没实现 —— 于是界面上的「根因占比」今天是用这张示例表当分母算出来的。
+ * 界面必须如实说清这一点（`RunView` 的副标题就是这么写的）：产品的第一条品牌承诺是
+ * **不编造数字**，把一个示例分母渲染成「样本量 41 次（近 30 天）」正是那条承诺要拦的事。
  */
 export const SAMPLE_SIZE = 41
 
@@ -314,8 +796,15 @@ export function candidatesOf(data: AttributionGraphData, symptomId: string): Att
 /** 筛选条件。空集合 = 不按该维度过滤。 */
 export interface GraphFilter {
   query: string
+  /**
+   * 节点种类切面。
+   *
+   * **它就是动线段落的开关**（§7.3）：按 `kind` 勾选与按动线段落收窄说的是同一件事。
+   * 关闭「检查点」= 第三段整段不画，所以界面上一律用段名做标签（`LANES`），
+   * 不再并列一个笼统的「类型」切面。
+   */
   kinds: ReadonlySet<AttributionNodeKind>
-  failureModes: ReadonlySet<FailureMode>
+  failureReasons: ReadonlySet<FailureReason>
   /**
    * 问题大类。**它不是一条节点谓词，而是一个子图选择器。**
    *
@@ -325,6 +814,16 @@ export interface GraphFilter {
    * 其余条件再在这个范围里生效（见 `filterGraph`）。
    */
   problemClasses: ReadonlySet<ProblemClassId>
+  /**
+   * 问题子类。**在大类选中的范围之内**再收窄形态（§4.5 的两级切面）。
+   *
+   * 它**只作用于现象节点**：子类是现象的字段，原因侧没有这一格。与 `kinds` 不同，
+   * 它不是范围选择器 —— 命中现象之后邻居照旧由 `includeNeighbors` 带出来，
+   * 否则按子类筛会把「这个问题能查什么」一起筛掉。
+   */
+  problemSubclasses: ReadonlySet<string>
+  /** 只留空区：有假设、一条检查都没有。空区是读数，也是一个切面（§7.3 第 3 组）。 */
+  gapOnly: boolean
   /** 命中节点之外，是否把它们的 1 跳邻居也留下作为上下文。 */
   includeNeighbors: boolean
 }
@@ -332,11 +831,23 @@ export interface GraphFilter {
 export const EMPTY_FILTER: GraphFilter = {
   query: '',
   kinds: new Set(),
-  failureModes: new Set(),
+  failureReasons: new Set(),
   problemClasses: new Set(),
+  problemSubclasses: new Set(),
+  gapOnly: false,
   includeNeighbors: true,
 }
 
+/**
+ * 空图：一个知识库还没有任何排查知识时的取值。
+ *
+ * 存在的理由是**初始状态不能是示例**。这一栏原来用 `SEED_GRAPH` 当初始值，于是
+ * 「服务端还没答话」和「这个库有 34 个节点的排查知识」在界面上长得一模一样 ——
+ * 用户没法分辨自己看到的到底是自己的库还是内置样例。现在初始值是空的，
+ * 真数据由 `/diagnosis/graph` 填进来，示例只走「载入内置示例」那枚按钮。
+ */
+export const EMPTY_GRAPH: AttributionGraphData = { nodes: [], edges: [] }
+
 /**
  * 按问题筛时要走几跳。
  *
@@ -397,9 +908,9 @@ function matchesQuery(node: AttributionNode, query: string): boolean {
 /**
  * 图上的筛选。
  *
- * 只按「类型 / 失败模式 / 文本」三个维度过滤，**不新增一个「分类树」**：
- * 0021 §4.3 已经定了分类是切面，所以这里也做成切面 —— 它可以多选、可以为空、
- * 可以随时改回来看全图，而不像树的层级那样「选错就得往回退」。
+ * 按「问题大类（范围）/ 问题子类 / 段（节点种类）/ 失败原因 / 空区 / 文本」过滤，
+ * **不新增一个「分类树」**：0021 §4.3 已经定了分类是切面，所以这里也做成切面 ——
+ * 它可以多选、可以为空、可以随时改回来看全图，而不像树的层级那样「选错就得往回退」。
  *
  * `includeNeighbors` 默认开：只留命中节点会让图散成孤点，边的语义也一起丢了。
  * 留下来的是命中节点及其 1 跳邻居，边只在两端都留下时才保留。
@@ -408,9 +919,9 @@ export function filterGraph(data: AttributionGraphData, filter: GraphFilter): At
   const query = filter.query.trim().toLocaleLowerCase()
 
   // 第一步：问题大类先把**范围**收窄成「命中现象 2 跳以内」的子图。
-  // 顺序很重要 —— 先收范围再套文本/类型/失败模式，语义才是「在这类问题里找」，
+  // 顺序很重要 —— 先收范围再套文本/段/失败原因，语义才是「在这类问题里找」，
   // 而不是「在整张图里找同时满足所有条件的节点」（后者永远是空集）。
-  const inScope = filter.problemClasses.size === 0
+  let inScope = filter.problemClasses.size === 0
     ? data
     : problemScopeOf(
       data,
@@ -419,18 +930,36 @@ export function filterGraph(data: AttributionGraphData, filter: GraphFilter): At
         .map(node => node.id),
     )
 
-  const noFilter = query === '' && filter.kinds.size === 0 && filter.failureModes.size === 0
+  // 空区是**假设的谓词**，但它要连同「谁指向它、它在哪张表上」一起看 —— 只留一个孤零零的
+  // 假设圆等于把这张图上唯一能动手的线索（它缺什么）删掉了。所以它先算命中集，
+  // 再照常走邻居扩张。
+  const gapOnlyHits = filter.gapOnly
+    ? new Set(gapHypothesisIds(inScope))
+    : undefined
+  if (gapOnlyHits) {
+    const keep = filter.includeNeighbors ? neighborhoodIds(inScope, gapOnlyHits) : gapOnlyHits
+    inScope = {
+      nodes: inScope.nodes.filter(node => keep.has(node.id)),
+      edges: inScope.edges.filter(edge => keep.has(edge.source) && keep.has(edge.target)),
+    }
+  }
+
+  const noFilter = query === '' && filter.kinds.size === 0 && filter.failureReasons.size === 0
+    && filter.problemSubclasses.size === 0
   if (noFilter) return inScope
 
   const hits = new Set<string>()
   for (const node of inScope.nodes) {
     if (query !== '' && !matchesQuery(node, query)) continue
     if (filter.kinds.size > 0 && !filter.kinds.has(node.kind)) continue
-    if (filter.failureModes.size > 0) {
-      // 失败模式是假设的属性；失败模式节点本身也要能被选出来。
-      const isModeNode = node.kind === 'failure-mode'
-      if (!isModeNode && (node.failureMode === undefined || !filter.failureModes.has(node.failureMode))) continue
+    if (filter.failureReasons.size > 0) {
+      // 失败原因是假设的属性；失败原因节点本身也要能被选出来。
+      const isReasonNode = node.kind === 'failure_reason'
+      if (!isReasonNode && (node.failureReason === undefined || !filter.failureReasons.has(node.failureReason))) continue
     }
+    // 子类是现象的字段：它只收窄现象，原因侧的节点不受它影响 —— 作用对象不同（§7.3）。
+    if (filter.problemSubclasses.size > 0 && node.kind === 'symptom'
+      && (node.problemSubclass === undefined || !filter.problemSubclasses.has(node.problemSubclass))) continue
     hits.add(node.id)
   }