05-EFT.WP.Core.Errors v1.0 | 第1章 错误体系与命名

目录 ／ 文档-技术白皮书 ／ 05-EFT.WP.Core.Errors v1.0

第1章 错误体系与命名

I. 章目与适用范围

• 本章定义错误域、严重性分级与编码方案，形成跨卷可追溯的错误词汇与注册规范，支撑 register_error_code、normalize_error、log_event、retry/fallback 等实现绑定。
• 适用范围覆盖观测、建模、数据、数值与运行期五类误差，并与《Core.Metrology》《Core.Parameters》《Core.Equations》在量纲、先验与方程层保持一致。

II. 错误域分类与边界

• MET（Metrology）：校准漂移、量纲不一致、参考条件缺失；与 check_dim(expr)、RefCond、U = k * u_c 强绑定。
• MOD（Model）：模型失配、先验冲突、等价约束破坏；与 r = y - f(x; theta)、prior(theta)、C_eq/C_ineq 相关。
• DAT（Data）：缺测、错误标注、离群与漂移；与 m ∈ {0,1}、mask_outlier ∈ {0,1}、drift_score 相关。
• NUM（Numerical）：舍入与截断、发散与溢出；与 u_round、O(h^p)、richardson_extrapolate 相关。
• OPS（Operations）：接口超时、资源枯竭、版本不兼容；与 traceability_chain、场景与版本治理相关。
• INT（Interop）：跨卷或跨服务互操作错误，如 unit 策略不一致、resolve_ref 失败、到达时两口径混用。
• 边界规则：错误域按主因归属；若同时触发，先归主因域，再以 see 链接次因域。

III. 严重性分级与动作矩阵

1. 级别集合：severity ∈ {info, warn, minor, major, critical}。
2. 影响维度：safety、scientific_validity、latency、availability、cost。
3. 动作矩阵（摘要）：
   • info：记录与可视化；无自动动作。
   • warn：记录、采样上报、建议性 retry。
   • minor：retry(policy) 一次，必要时 fallback。
   • major：强制 fallback(models, "weighted") 或 graceful_degradation；标记样本为 mask_outlier=1。
   • critical：立即切断路径、保全状态、触发告警与回滚；阻断不合规报告（如 check_dim 未过）。

IV. 公设 P71-1…P71-3（错误命名与严重性）

• 公设 P71-1（唯一性与稳定性）：每一错误以三元组 (domain, class, code) 唯一标识，文本 message 可演进但语义域与触发条件保持恒定。
• 公设 P71-2（量纲优先）：任何与物理量相关的错误优先落入 MET/INT 域，且必须提供 dim(lhs) 与 dim(rhs) 的比对证据；check_dim 不通过即为 critical。
• 公设 P71-3（动作与级别分离）：severity 表达影响，不编码修复动作；remediation 为策略建议，可随环境与策略库更新而变化，二者独立演进。

V. 编码方案与字段规范

1. 语法：E-<DOMAIN>-<CLASS>-<NNN>[@vMAJOR]
   • <DOMAIN> ∈ {MET, MOD, DAT, NUM, OPS, INT}。
   • <CLASS> 使用大写英文蛇形命名，如 DIMENSION, CALIB, PRIOR, MISSING, OUTLIER, ROUNDING, TIMEOUT。
   • <NNN> 为三位数字，域内递增；@vMAJOR 可选，用于兼容性断点声明。
2. 注册字段（与 register_error_code 对齐）：
   code、name（小写蛇形，如 dimension_mismatch）、severity、domain、message、remediation、see。
3. 规范要求：
   • message 仅含英文与可插值占位（如 {unit_from}->{unit_to}）；
   • 涉及到达时写全路径与测度：T_arr = ( ∫ ( n_eff / c_ref ) d ell )，并指明 gamma(ell) 与 d ell；
   • 禁止在 code 或 name 中使用中文、单位符号与空格。

VI. 流程 M71-1：错误归一与处置

• 捕获：在模型/管线/接口边界捕获异常或规则触发的违例。
• 归一：使用 normalize_error(err) 映射到标准字段与 code。
• 判级：根据上下文与 set_error_policy(domain, policy) 计算 severity。
• 记录：调用 log_event(code, level, context)，附 traceability_chain。
• 决策：依据动作矩阵选择 retry/fallback/graceful_degradation。
• 报告：在计量/科学输出中标注影响（如提高 U、降低 confidence、打 mask_outlier）。
• 回归：纳入回归基线与阈值自适应更新（drift_score 监测）。

VII. 典型编码清单（节选）

• E-MET-DIM-001 name:dimension_mismatch severity:critical message:dim(lhs)!=dim(rhs) remediation:fix_unit_or_expr; run check_dim see:I40 2。
• E-MET-CALIB-002 name:calibration_expired severity:major message:RefCond/CMC out-of-date remediation:recalibrate; recompute U = k*u_c see:I40 5。
• E-INT-ARR-003 name:arrival_time_convention_mixed severity:major message:mixed conventions for T_arr remediation:enforce single convention see:enforce_arrival_time_convention。
• E-MOD-PRIOR-004 name:prior_incompatible_bounds severity:major message:prior support outside [lb,ub] remediation:align prior with bounds see:I30 3。
• E-MOD-CONSTR-005 name:constraint_violation_eq severity:major message:C_eq(theta)!=0 remediation:project_to_feasible see:I30 2。
• E-DAT-MISS-006 name:missing_values_detected severity:minor message:m=1 fraction exceeds threshold remediation:impute_or_drop。
• E-DAT-OUTLIER-007 name:outlier_excess severity:major message:|z|>t0 or MAD rule remediation:mask_and_refit see:I50 3。
• E-NUM-ROUND-008 name:catastrophic_cancellation severity:major message:loss of significance remediation:rescale_or_kahan。
• E-NUM-DIVERGE-009 name:solver_divergence severity:major message:no convergence within tol remediation:adjust_step_or_precond。
• E-OPS-TIMEOUT-010 name:rpc_timeout severity:minor message:downstream exceeded SLA remediation:retry(policy)。
• E-OPS-VERSION-011 name:scenario_incompatible severity:major message:scenario diff incompatible remediation:migrate_or_pin see:diff_scenarios。
• E-INT-UNIT-012 name:unit_policy_mismatch severity:major message:convert() policy conflict remediation:bind_to_equation(unit_policy)。

VIII. 示例：到达时错误命名的一致性

1. 若在路径积分中混用两口径或未声明路径与测度，即触发：
   • E-INT-ARR-003（混用口径）；
   • E-MET-DIM-001（量纲校验失败，当 ( n_eff / c_ref ) * d ell 未无量纲化时）。
2. 残差口径：对到达时观测 y = T_arr_meas 与模型 f(x; theta)，残差定义 r def= y - f(x; theta)，量纲与单位须等同；check_dim( y - f(x; theta) ) 不通过即 critical。

IX. 兼容性与版本治理

• 版本断点以 @vMAJOR 标注，仅在语义或触发条件发生破坏性变化时提升主版本；次级文案或修复不改变 code。
• 与场景管理协同：当 create_scenario/activate_scenario 切换后，错误策略由 set_error_policy 载入场景定制版本；回归使用 compare_reports(..., ["mean","U","pass_rate"]) 监测质量滑坡。

X. 本章小结与输出物

• 输出：错误域词汇、严重性动作矩阵、公设 P71-1…P71-3、E-<DOMAIN>-<CLASS>-<NNN> 编码语法、流程 M71-1、典型注册清单。
• 进入下一章前，请以项目实际错误清单批量调用 register_error_code，并在拟合与评估流程中接入 compute_residual、loss_rho、psi_weight 与 zscore_detect/hampel_filter。