51-管线卡 Template v1.0 | 第7章 状态、幂等与容错（事务/重试/回放）

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

第7章 状态、幂等与容错（事务/重试/回放）

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

• 统一状态机（State）、幂等（Idempotency）与容错（事务/重试/回放）的建模与校验口径，确保阶段在失败/抖动/重复触发下的可恢复性与可审计性。
• 涉及路径量（到达时/相位）之阶段，正文显式 gamma(ell) 与测度 d ell，数据侧记录 delta_form ∈ {general, factored}；发布要求 p_dim = 1.0。

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

• 契约齐备：入/出站 Schema 与 TARR 对齐，单位/量纲明确并通过 I70-dim_check。
• 同步与时基：满足第5章 clock_state="locked"、|ts_start − calib.timestamp| ≤ τ_calib。
• 引用与版本：采用“卷名 + 版本 + 锚点（P/S/M/I）”，锚点直指率 ≥ 90%。
• 路径一致：len(gamma_ell)=len(d_ell)=len(n_eff)≥2，Δell 合规；缺失即拒收。

III. 状态机（State Machine）

1. 状态集合：state ∈ {pending, running, succeeded, failed, rolled_back}。
2. 基本转移：
   • pending → running：依赖阶段 succeeded 且通过 G1–G3。
   • running → succeeded：阶段 G1–G8 全部通过。
   • running → failed：触发 S1–S5 任一（量纲失败/新鲜度失效/路径缺失/协方差失配/引用不合规）。
   • failed → rolled_back：存在检查点或补偿策略且审计完备。
3. 不可变式：转移不得破坏上游工件一致性；回滚需与检查点一致并可重放。

IV. 事务边界与错误语义（Transactions & Errors）

1. 事务边界：输入读取→计算→输出写入为一次原子提交；外部副作用需可补偿。
2. 错误分类：
   • E_INPUT（契约/类型/窗口错误）
   • E_DIM（量纲失败）
   • E_GATE（质量门未过）
   • E_SYNC（失锁/偏置超阈）
   • E_UQ（协方差非 PD/覆盖不一致）
   • E_INTERNAL（实现内部异常）
3. 处置策略：可补偿错误优先回滚并重试；不可补偿错误标注 failed 并进入人工复核。

V. 幂等（Idempotency）

• 幂等键：idempotency_key = f(run_id, partition, window, …)；同键多次触发输出不变。
• Exactly-Once vs At-Least-Once：默认 At-Least-Once；声明 Exactly-Once 时，需提供去重证据与幂等写（主键/合并写）。
• 输入快照：持久化输入哈希 input_hashes[]，确保重试/回放的决定性。
• 副作用隔离：外部调用（API/DB）须具幂等语义或补偿记录（补偿日志/撤销消息）。

VI. 重试（Retry Strategy）

• 策略字段：retry_policy = { max_retries, backoff ∈ {const, exp, jitter}, deadline }。
• 不变量：重试不改变 idempotency_key 与输入快照；超出 deadline 直接标记 failed。
• 退避建议：exp + jitter，保护上游与共享资源；记录重试计数与间隔。
• 与门配合：对 E_GATE 可按阈值切分降级支路；对 E_DIM 禁止盲目重试，需修正后再触发。

VII. 回放与检查点（Replay & Checkpoint）

• 检查点：在关键阶段启用 checkpoint: true，保存最小充分状态与输出摘要。
• 回放约束：按 DAG 拓扑倒序回放；若存在副作用，先执行补偿后回放；回放期间仍须通过 G1–G8。
• 一致性：回放结果（输出哈希/主键集合）须与原执行一致；差异进入 rolled_back 并上报。

VIII. 路径阶段的专属约束（Path-Aware Requirements）

• 必备输入：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 )。
• 对齐顺序：时间对齐 → 路径对齐（gamma_ell/d_ell/n_eff 同步）→ 相位对齐（参考窗）。

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

• G1 Schema 完整｜G2 引用合规｜G3 路径规范｜G4 量纲闭合｜G5 新鲜度｜G6 覆盖口径｜G7 协方差一致｜G8 唯一性。
• 触发 S1–S5（量纲失败/新鲜度失效/路径缺失/协方差失配/引用不合规）即停止与回退，必要时进入 [Restricted]。

X. 机读配置（Machine-Readable Configs）
A. 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" }

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

idempotency_key: "run_id+partition+window"

B. replay_plan.yaml

version: "1.0.0"

replay:

enabled: true

order: "reverse_topology"

require_checkpoint: true

compensate_before_replay: true

verify:

hash: true

primary_keys: true

alerts:

on_divergence: ["page_ops","open_ticket"]

C. 审计事件 audit.jsonl（示例行）

{
  "ts": "2025-09-24T16:10:00Z",
  "stage_id": "stage-30-arrival",
  "event": "retry",
  "idempotency_key": "run42+p010+win001",
  "attempt": 2,
  "backoff_ms": 800,
  "input_hashes": [ "sha256:..." ],
  "state": "running",
  "user": "scheduler",
  "checksum": "sha256:..."
}

XI. 校验与监控（Validation & Monitoring）

• /validate：返回阶段当前状态、门通过率、stops_triggered 与重试/回放统计；量纲闭合以 check_dim_report.json 为准。
• 在线指标：Latency_P50/P95、Throughput、retry_count、replay_count、idempotency_conflicts、σ_y(τ)、δt_abs、Q_res、p_dim。
• 告警：状态抖动、重试风暴、非 PD 协方差、路径不同步、失锁与门越界；支持抑制与升级策略。

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

• 反例：重试改变 idempotency_key → 修正：固定键并保留输入快照。
• 反例：T_arr = ∫ n_eff / c_ref d ell（缺括号）→ 修正：T_arr = ( ∫ ( n_eff / c_ref ) d ell )。
• 反例：clock_state!="locked" 仍写入 → 修正：拒收或回退并标注 [Restricted]。
• 反例：无检查点就回放 → 修正：补充检查点与补偿；或仅允许只读试算。

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

PTN_EXPORT/

configs/

state_machine.yaml

replay_plan.yaml

reports/

check_dim_report.json

validate_report.json

audit.jsonl

figs/

state_transitions.svg

retry_replay_timeline.pdf

report_manifest.yaml

SIGNATURE.asc

XIV. 交叉引用（Cross-References）

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

XV. 执行勾选清单（Checklist）

• 状态机定义完备，转移条件可机读；retry_policy、idempotency_key、checkpoint 已配置。
• 事务边界明确；外部副作用可补偿或具幂等写；审计事件完整。
• 路径阶段显式 gamma/measure/delta_form；Δell 与 f_s 约束满足；相位对齐在参考窗内进行。
• I70-dim_check 通过、p_dim = 1.0；clock_state="locked"、τ_calib 合规。
• /validate 通过 G1–G8；触发 S1–S5 时有明确回退与告警；发布包签名与校验和完备；引用锚点直指率 ≥ 90%。