51-管线卡 Template v1.0 | 第6章 阶段定义与控制式（Stage Specs）

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

第6章 阶段定义与控制式（Stage Specs）

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

• 规定管线阶段（Stage）的输入/输出契约、控制式（Control Equations）、质量门（Gates）与错误语义/幂等/审计的统一口径，支撑可验证、可回放与可发布的阶段实现。
• 涉及路径量（到达时/相位）之阶段，正文显式 gamma(ell) 与测度 d ell，数据侧记录 delta_form ∈ {general, factored}；发布要求 p_dim = 1.0。

II. 前置条件与输入（Prerequisites & Inputs）

• 契约齐备：阶段输入/输出字段在 TARR 中有明确定义（字段/单位/量纲/取值域）。
• 参数与误差对齐：所依赖的参数已在“参数注册卡”注册并通过参数级 G1–G8；协方差/覆盖与“误差预算卡”一致。
• 引用与版本：采用“卷名 + 版本 + 锚点（P/S/M/I）”，锚点直指率 ≥ 90%。
• 时基与同步：满足第5章的 f_s、clock_state="locked"、|ts_start − calib.timestamp| ≤ τ_calib。

III. 阶段结构（Stage Structure）

• 标识：stage.id（全局唯一）、version (SemVer)、owner。
• 输入：inputs[]（字段路径，含单位/量纲），必要时给出形状/窗口/分区约束。
• 输出：outputs[]（生成的字段/工件），声明单位/量纲与精度。
• 控制式：control.form（括号化表达）、delta_form（路径型），必要时 assumptions[]（近轴/相干窗等）。
• 质量门：quality_gates[]（G1–G8），及阈值/停止准则映射。
• 错误语义：E_INPUT/E_DIM/E_GATE/E_SYNC/E_UQ/E_INTERNAL，含可补偿与不可补偿分类。
• 幂等与重试：idempotency_key、retry_policy{max_retries,backoff,deadline}、checkpoint。
• 审计：输出 audit.jsonl 事件（输入哈希、幂等键、重试计数、最终状态）。

IV. 控制式与规则（Control Equations & Rules）

1. 括号与优先级：任何含除号/积分/复合算符的表达必须加括号；ln/exp/conv 函数式书写。
2. 量纲闭合：控制式需通过 I70-dim_check；随附 check_dim_report.json；p_dim = 1.0 为发布前置。
3. 路径积分口径（两种等价）：
   • T_arr = ( 1 / c_ref ) * ( ∫ n_eff d ell )
   • T_arr = ( ∫ ( n_eff / c_ref ) d ell )
     相位：Phi = ( 2π / λ_ref ) * ( ∫ n_eff d ell )。
4. 对齐顺序：时间对齐 → 路径对齐（gamma_ell/d_ell/n_eff 同步）→ 相位对齐（参考窗）。
5. UQ 耦合：若阶段输出参与不确定度传播，提供 J=∂f/∂x|_{x̂} 与 Σ=Cov(x) 的来源（见误差预算卡 Ch.5/Ch.6）。

V. 质量门与停止（Gates & Stops）

• G1 Schema 完整：输入/输出字段存在性、类型与索引/窗口一致。
• G2 引用合规：见“引用与版本”，锚点直指率 ≥ 90%。
• G3 路径规范：gamma/measure/delta_form 齐备；len(path)≥2，Δell 合规。
• G4 量纲闭合：I70-dim_check 通过，p_dim = 1.0。
• G5 新鲜度：clock_state="locked"，|ts_start − calib.timestamp| ≤ τ_calib。
• G6 覆盖口径：不确定度区间与发布口径一致（k/alpha/quantile）。
• G7 协方差一致：cov_group/核参数与误差预算卡一致，Σ 正定。
• G8 唯一性：输出 record_id/checksum 不重复。
• 触发 S1–S5（量纲失败/新鲜度失效/路径缺失/协方差失配/引用不合规）即停止与回退。

VI. 错误语义与补偿（Errors & Compensation）

• E_INPUT：缺字段/类型错/窗口不一致 → 修复入站契约或拒收。
• E_DIM：量纲失败 → 停止、回滚检查点。
• E_GATE：质量门未过 → 按门映射阈值分流或降级。
• E_SYNC：失锁/偏置超阈 → 切回退（PTP/NTP），必要时标注 [Restricted]。
• E_UQ：协方差非 PD/覆盖不一致 → 切稳健代理或拒收。
• E_INTERNAL：实现内部异常 → 重试或报警。

VII. 幂等、重试与回放（Idempotency, Retry & Replay）

• 幂等键：idempotency_key = f(run_id, partition, window, …)；重复触发不得改变输出。
• 重试：指数退避/截止时间，保留输入快照与幂等键。
• 回放：有检查点的阶段允许拓扑倒序回放，不得破坏上游工件一致性。

VIII. 监控与指标（Monitoring & KPIs）

• 核心指标：Latency_P50/P95、Throughput、ρ、Q_res、p_dim、σ_y(τ)、ε_flux（路径类）。
• 告警：门越界/失锁/PD 失败/路径不同步/幂等冲突；支持抑制窗口与升级策略。

IX. 机读示例（Machine-Readable Examples）
A. 阶段规格 stage.yaml

version: "1.0.0"

stage:

id: "stage-30-arrival"

owner: "ptn.core"

inputs:

- "path.gamma_ell" # m

- "path.d_ell" # m

- "medium.n_eff_profile" # 1

- "ref.c_ref" # m/s

outputs:

- "obs.T_arr" # s

control:

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

delta_form: "general"

assumptions: ["paraxial","coherence_window"]

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

error_map:

E_INPUT: "reject_or_fix_contract"

E_DIM: "rollback_checkpoint"

E_GATE: "branch_or_degrade"

E_SYNC: "fallback_ptp_ntp"

E_UQ: "robust_surrogate_or_reject"

E_INTERNAL:"retry_then_alert"

idempotency_key: "run_id+partition+window"

retry_policy: { max_retries: 3, backoff: "exp", deadline: "10m" }

checkpoint: true

see:

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

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

B. 控制式—相位阶段 stage-40-phase.yaml

version: "1.0.0"

stage:

id: "stage-40-phase"

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

outputs: ["obs.Phi"]

control:

form: "Phi = ( 2π / lambda_ref ) * ∫ n_eff d ell"

delta_form: "factored"

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

see:

- "EFT.WP.Core.Equations v1.1:S21-2"

C. 验证报告 validate_report.json

{
  "stage_id": "stage-30-arrival",
  "gates": {
    "G1": true,
    "G2": 0.94,
    "G3": true,
    "G4": true,
    "G5": true,
    "G6": true,
    "G7": true,
    "G8": true
  },
  "stops_triggered": [  ]
}

X. 反例与修正（Anti-Patterns & Fixes）

• 反例：T_arr = ∫ n_eff / c_ref d ell（缺括号）→ 修正：T_arr = ( ∫ ( n_eff / c_ref ) d ell )。
• 反例：未声明 delta_form 或缺 d ell → 修正：补齐并与 n_eff 对齐。
• 反例：未做 I70-dim_check 即发布 → 修正：校核并附 check_dim_report.json，确保 p_dim = 1.0。

XI. 发布与目录结构（Release & Layout）

PTN_EXPORT/

stages/

stage-30-arrival.yaml

stage-40-phase.yaml

reports/

check_dim_report.json

validate_report.json

audit.jsonl

figs/

stage_dag.svg

path_alignment.pdf

report_manifest.yaml

SIGNATURE.asc

XII. 交叉引用（Cross-References）

• 体系结构与计算图：见第3章；入站契约：见第4章；时基/同步/缓冲：见第5章；质量门与监控：见第9章；UQ 耦合与闭环：见第10章。
• 参数/误差/协议模板：参考Parameter/ Error/ Experimental Protocol 对应章节。

XIII. 执行勾选清单（Checklist）

• 阶段 inputs/outputs 与 TARR 对齐，单位与量纲清晰。
• 控制式括号化、I70-dim_check 通过、p_dim = 1.0；路径型记录 delta_form。
• 质量门 G1–G8 与阈值映射明确；E_* 错误语义与补偿策略可执行。
• 幂等键、重试与检查点已配置；审计事件与输入哈希完整。
• /validate 报告通过；发布包含阶段规格、校核与审计制品，引用锚点直指率 ≥ 90%。