51-管线卡 Template v1.0 | 第3章 体系结构与计算图（DAG/状态机）

目录 ／ 文档-技术白皮书 ／ 51-管线卡 Template v1.0

第3章 体系结构与计算图（DAG/状态机）

I. 目的与范围（Purpose & Scope）

• 给出管线的体系结构与计算图（DAG(V,E)）及其状态机的统一口径，覆盖拓扑约束、阶段边界、事务与幂等、检查点与回放、Exactly-Once/At-Least-Once 语义与合规模块。
• 涉及路径量（到达时/相位）之阶段，正文显式 gamma(ell) 与测度 d ell，数据侧记录 delta_form ∈ {general, factored}；发布要求 p_dim = 1.0。

II. 定义与对象（Definitions & Objects）

• Pipeline：由阶段与有向边构成的处理流。
• DAG(V,E)：阶段集合 V 与依赖边集合 E 构成的有向无环图。
• Stage：最小可执行单元，具输入/输出契约与质量门。
• Operator：阶段内部可并行算子。
• Artifact：阶段产物（表/文件/报告/图）。
• ctx：执行上下文（参数、环境、idempotency_key、追踪标识）。
• State Machine：state ∈ {pending, running, succeeded, failed, rolled_back} 与转移集合 T。

III. 计算图建模（DAG Modeling）

• 无环性：DAG 必须无环；禁止隐式依赖（所有边须显式声明）。
• 边语义：(u → v) ∈ E 表示 v 的输入工件完整可用且满足 v 的前置门；若需旁路/可选输入，使用条件边 cond(u→v)。
• 并行与分支：分支节点以复制语义传播工件；汇合节点以对齐语义（同分区/同窗口）聚合。
• 幂等与幂等域：每条路径以 idempotency_key = f(run_id, partition, window, …) 去重，保证重复触发时输出一致。
• 检查点与回放：阶段 v 可声明检查点；回放应满足拓扑倒序与幂等约束，不得破坏上游工件一致性。
• 契约对齐：每条边两端的 Schema（字段/单位/量纲）须一致或可被显式映射；不允许隐式单位换算。

IV. 状态机与转移（State Machine & Transitions）

1. 基本转移：pending → running → {succeeded | failed}；succeeded/failed → rolled_back 仅限具检查点或补偿策略的阶段。
2. 转移条件：
   • pending→running：前置阶段 succeeded 且通过 G1–G3。
   • running→succeeded：阶段质量门 G1–G8 全部通过。
   • running→failed：触发 S1–S5（量纲失败/新鲜度失效/路径缺失/协方差失配/引用不合规）之一。
   • failed→rolled_back：存在补偿/回滚动作且审计记录完备。
3. 重试策略：retry_policy = {max_retries, backoff, deadline}；重试不应改变 idempotency_key 与输入快照。
4. Exactly-Once/At-Least-Once：默认 At-Least-Once；若声明 Exactly-Once，需提供去重与输出幂等证据（主键/幂等写）。

V. 路径阶段的专属要求（Path-Aware Stages）

• 输入需包含并显式：gamma(ell)、d ell、n_eff(ell)、c_ref、（相位类）λ_ref；数据侧记录 delta_form。
• 统一口径（两种等价）：
  T_arr = ( 1 / c_ref ) * ( ∫ n_eff d ell )；T_arr = ( ∫ ( n_eff / c_ref ) d ell )；
  相位：Phi = ( 2π / λ_ref ) * ( ∫ n_eff d ell )。
• 采样一致性：len(gamma_ell)=len(d_ell)=len(n_eff)≥2；Δell ≤ ( c_ref / f_s ) / max(n_eff)。

VI. 一致性与不变式（Consistency Invariants）

• Schema 不变式：沿边传递的工件必须满足目标阶段输入契约，单位/量纲闭合（p_dim = 1.0）。
• 副作用隔离：阶段外部副作用须可补偿/幂等；禁止在失败后留下不可回滚状态。
• 资源与时基：clock_state="locked"、|ts_start − calib.timestamp| ≤ τ_calib；抖动与漂移在阈值内（σ_y(τ) 目标）。
• 协方差一致：cov_group 与核参数与误差预算卡一致；Σ 正定。

VII. 机读制品（Machine-Readable Artifacts）
A. pipeline_graph.json（结构）

{

"version": "1.0.0",

"nodes": [

{"id":"ingest"},

{"id":"calibrate"},

{"id":"arrival","checkpoint":true,"retry_policy":{"max_retries":3,"backoff":"exp","deadline":"10m"}}

],

"edges": [

{"from":"ingest","to":"calibrate"},

{"from":"calibrate","to":"arrival","cond":"schema_ok && gates_ok"}

],

"idempotency_key":"run_id+partition"

}

B. state_machine.yaml（转移与门）

version: "1.0.0"

states: [pending, running, succeeded, failed, rolled_back]

transitions:

- { from: pending, to: running, when: "deps_succeeded && G1..G3" }

- { from: running, to: succeeded, when: "G1..G8 && !S1..S5" }

- { from: running, to: failed, when: "any(S1..S5)" }

- { from: failed, to: rolled_back, when: "has_checkpoint && do_compensate" }

gates: ["G1","G2","G3","G4","G5","G6","G7","G8"]

stops: ["S1","S2","S3","S4","S5"]

C. stage.yaml（阶段规格，节选）

version: "1.0.0"

stage:

id: "stage-30-arrival"

inputs: ["path.gamma_ell","path.d_ell","medium.n_eff_profile","ref.c_ref"]

outputs: ["obs.T_arr"]

control:

form: "T_arr = ∫ ( n_eff / c_ref ) d ell"

delta_form: "general"

quality_gates: ["G1","G3","G4","G6"]

see:

- "EFT.WP.Core.Equations v1.1:S20-1"

- "EFT.WP.Core.Metrology v1.0:check_dim"

VIII. 校验与质量门（Validation & Gates）

• 管线级 G1–G8：Schema 完整、引用合规、路径规范、量纲闭合、新鲜度、覆盖口径、协方差一致、唯一性；触发 S1–S5 阻断执行与发布。
• /validate 应返回每节点与全局门的通过率与停机原因；维度闭合以 check_dim_report.json 为准。

IX. 监控与告警（Monitoring & Alerts）

• 指标：Latency_P50/P95、Throughput、ρ、Q_res、p_dim、σ_y(τ)、ε_flux。
• 告警：状态转移失败、正定性失败、门越界、回放频繁、幂等冲突；支持静默窗口与抑制规则。
• 可观测性：每阶段输出 audit.jsonl 事件，含 idempotency_key、输入哈希、重试计数与最终状态。

X. 发布与引用（Release & References）

• 制品：pipeline_graph.json、state_machine.yaml、各阶段 stage.yaml、check_dim_report.json、audit.jsonl、图表与 report_manifest.yaml；图表双份导出（PDF/SVG 与 PNG）。
• 引用固定格式：见《<卷名> vX.Y》<章节> <锚点>，优先 P/S/M/I，禁止外链与别名。

XI. 执行勾选清单（Checklist）

• DAG(V,E) 无环；条件边明确且可机读；幂等键定义清晰。
• 状态机 pending→running→{succeeded|failed}→rolled_back 转移条件可验证；重试与补偿策略已配置。
• 路径阶段显式 gamma(ell)、d ell；delta_form 已记录；Δell 与 f_s 约束满足。
• I70-dim_check 通过，p_dim = 1.0；clock_state="locked"、τ_calib 合规；Σ 正定。
• /validate 通过 G1–G8，无 S1–S5；see[]/references[] 合规且锚点直指率 ≥ 90%。
• 发布包包含计算图/状态机/阶段规格、维度报告与审计；签名与校验和完备。