05-EFT.WP.Core.Errors v1.0 | 附录A 错误码注册表模式

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

附录A 错误码注册表模式

I. 目的与范围

• 目的：给出跨卷统一的错误码注册表模式，规范 code、severity、domain、message、remediation 与追溯字段，以支撑 register_error_code、set_error_policy、normalize_error 的实现与校验。
• 适用范围：覆盖计量与误差两卷的在线/离线流程，包括 T_arr 两口径计算、校准/检定、稳健拟合、误差传播、数据质量与时序管线。

II. 命名与编码规范

1. 代码结构：code = "E.<DOMAIN>.<GROUP>.<KEY>[.NNN]"
   • <DOMAIN>：顶级域（如 METROLOGY、MEASUREMENT、NUMERICS、DATA_QUALITY、MODEL、PIPELINE、CALIBRATION、REFCOND、REPORT、IO、SECURITY）。
   • <GROUP>：二级分组（如 UNIT、TRACE、INTEGRATION、OUTLIER、FIT、TIME、LINEAR 等）。
   • <KEY>：具体故障键（全大写下划线，语义稳定）。
   • 可选序号 .NNN：同键下的细分情景（从 001 起）。
2. 正则约束：^E\.[A-Z][A-Z0-9_]*\.[A-Z][A-Z0-9_]*\.[A-Z][A-Z0-9_]*(\.[0-9]{3})?$。
3. 全局唯一：code 在全库唯一；同一 code 的 version 单调递增。
4. 语义稳定：message 模板可演进但不得改变根因/域/严重性语义。

III. 字段字典与必填项

1. 必填字段
   • code:str（全局唯一，见命名规范）
   • name:str（人类可读短标题，英文）
   • severity:str ∈ {INFO, WARN, ERROR, FATAL}
   • domain:str（与 <DOMAIN> 一致）
   • message:str（占位模板，变量形如 {{var}}）
   • remediation:str（首选动作，如 retry(policy={{pid}})、fallback(model={{mid}})、graceful_degradation(mode={{m}})、recalibrate(proc={{rid}})）
2. 推荐字段
   • see:list[str]（跨卷引用，形如 I50-4、I40-9、S88-1）
   • tags:list[str]（关键词，如 ["T_arr","gamma(ell)","n_eff","c_ref"]）
   • cause:str（直接原因）
   • effect:str（用户影响，含 SLI/SLO 触点）
   • detection:str（检测准则，如 |z| > 3.5、chi2/dof > t0）
   • context_schema:list[str]（最小上下文键名，见下节）
   • metrics:list[str]（记录的量化指标，如 ["chi2","r_bar_max","latency_ms","pass_rate"]）
   • policy_hint:str（策略提示，如 prefer_robust_loss=Huber）
3. 生命周期字段
   • version:str（语义化版本，如 1.0.0）
   • status:str ∈ {DRAFT, ACTIVE, DEPRECATED, RETIRED}
   • created_at:str、updated_at:str（ISO8601）
   • deprecates:list[str]、replaces:list[str]（兼容关系）

IV. 上下文最小键（追溯与再现）

• trace_id，span_id（链路追踪）
• inputs_hash（输入指纹）
• model_id，loss_kind（模型与稳健口径）
• gamma_spec，L_gamma，path_version（当涉及 gamma(ell)）
• c_ref_version，unit_policy（单位与参考常数版本）
• refcond_id（RefCond 标识）
• h，p_hat（步长与阶次）
• SLI_snapshot（触发时的指标切片）

V. 严重性与推荐动作映射

• INFO：记录与可观测性；默认 no-op，可附 telemetry_only=true。
• WARN：质量风险但可继续；默认 retry(policy={{pid}}) 或 switch_loss(kind=Huber)。
• ERROR：当前流程失败但可回退；默认 fallback(model={{mid}}) 或 graceful_degradation(mode=partial)。
• FATAL：不可恢复的系统或语义破坏；默认 abort 与 raise 并触发 recalibrate(proc={{rid}})。

VI. 规范化与校验规则

• 模板变量完整性：message 中的 {{var}} 必由 context 提供同名键。
• 文本规范：message、name 使用英文与纯文本；禁止混入单位换算未声明的符号。
• 量纲一致：若 message 含量纲表达，须通过 check_dim（例如 y - f(x; theta)）。
• 关联一致：domain 必与 code 的 <DOMAIN> 匹配；severity 与 policy_hint 不冲突。
• 兼容性：ACTIVE→DEPRECATED 仅允许 remediation 强化，不得更改 code、domain、severity。

VII. 参考 JSON-Schema（概要）

1. type: object
2. required: [ "code","name","severity","domain","message","remediation" ]
3. properties:
   • code: string, pattern ^E\.[A-Z][A-Z0-9_]*\.[A-Z][A-Z0-9_]*\.[A-Z][A-Z0-9_]*(\.[0-9]{3})?$
   • severity: string, enum [ "INFO","WARN","ERROR","FATAL" ]
   • domain: string
   • name: string
   • message: string
   • remediation: string
   • see: array(string)
   • tags: array(string)
   • cause: string
   • effect: string
   • detection: string
   • context_schema: array(string)
   • metrics: array(string)
   • policy_hint: string
   • version: string
   • status: string, enum [ "DRAFT","ACTIVE","DEPRECATED","RETIRED" ]
   • created_at: string (date-time)
   • updated_at: string (date-time)
   • deprecates: array(string)
   • replaces: array(string)

VIII. 与实现绑定（I50- 对应）*

• register_error_code：按本模式校验并入库，返回 ERef；重复 code 拒绝。
• set_error_policy：按 domain 下发 severity→action 的默认映射，并可覆盖到具体 code。
• normalize_error：将原生异常/事件折叠为 { code, message(fmt), context, severity }，并补齐 trace_id、span_id、inputs_hash。

IX. 示例条目（跨域最小集）

• code=E.METROLOGY.UNIT.DIM_MISMATCH；name=Dimension mismatch；severity=ERROR；domain=METROLOGY；message=Expected dim(lhs)==dim(rhs) but got {{lhs}} vs {{rhs}}；remediation=abort and fix unit policy；see=[ "I40-2","S88-1" ]；tags=[ "check_dim" ]。
• code=E.MEASUREMENT.TRACE.MISSING_CHAIN；name=Traceability chain missing；severity=ERROR；domain=MEASUREMENT；message=Missing traceability_chain for {{code}}；remediation=attach_traceability(report={{rid}},chain={{cid}})；see=[ "I40-4","I50-6" ]。
• code=E.REFCOND.OUT_OF_RANGE；name=RefCond out of range；severity=WARN；domain=REFCOND；message=RefCond deviates: p={{p}},Temp={{Temp}},humidity={{humidity}}；remediation=apply corr_env and elevate u_env；see=[ "I40-3" ]；tags=[ "RefCond","corr_env" ]。
• code=E.NUMERICS.INTEGRATION.STEP_TOO_LARGE；name=Integration step too large；severity=WARN；domain=NUMERICS；message=h={{h}} exceeds bound; order={{order}}；remediation=retry(policy=refine_step)；see=[ "I50-5" ]；metrics=[ "h","p_hat" ]。
• code=E.NUMERICS.ROUNDING.CANCELLATION；name=Catastrophic cancellation；severity=ERROR；domain=NUMERICS；message=High cancellation risk; u_round={{u_round}}；remediation=fallback(model=KahanSum)；see=[ "I50-5" ]。
• code=E.DATA_QUALITY.OUTLIER.DETECTED；name=Outlier detected；severity=WARN；domain=DATA_QUALITY；message=Outliers ratio={{ratio}} via {{method}}；remediation=mask and refit；see=[ "I50-3","I50-2" ]；tags=[ "zscore","Hampel","RANSAC" ]。
• code=E.MODEL.FIT.NON_CONVERGENCE；name=Fit not converged；severity=ERROR；domain=MODEL；message=Solver failed; iter={{iter}}, tol={{tol}}；remediation=switch loss to Huber and retry；see=[ "I50-2" ]；metrics=[ "chi2","r_bar_max" ]。
• code=E.PIPELINE.TIMEOUT.P95_EXCEEDED；name=Latency p95 exceeded；severity=WARN；domain=PIPELINE；message=latency_p95={{p95}}ms > {{limit}}ms；remediation=graceful_degradation(mode=partial)；see=[ "I50-8","M8-3" ]。
• code=E.CALIBRATION.LINEAR.SLOPE_UNCERT_HIGH；name=Linear slope uncertainty high；severity=WARN；domain=CALIBRATION；message=u(a)={{ua}} exceeds {{limit}}；remediation=increase samples or robust loss；see=[ "M8-2" ]。
• code=E.REPORT.GUARD_BAND.MARGINAL；name=Guard band marginal；severity=INFO；domain=REPORT；message=Result within guard band; result={{x}}, U={{U}}, tol={{tol}}；remediation=record and monitor；see=[ "I40-6" ]。
• code=E.IO.READ.FAIL；name=I/O read failure；severity=ERROR；domain=IO；message=Failed to read {{uri}}; reason={{reason}}；remediation=retry(policy=io_backoff)；tags=[ "io","retry" ]。
• code=E.SECURITY.PERM.DENIED；name=Permission denied；severity=FATAL；domain=SECURITY；message=Access denied for {{actor}} to {{resource}}；remediation=abort and escalate；tags=[ "authz" ]。
• code=E.T_ARR.CONSISTENCY.DUAL_FORM_MISMATCH；name=T_arr dual-form mismatch；severity=ERROR；domain=MEASUREMENT；message=Two conventions disagree by {{delta}}s；remediation=enforce_arrival_time_convention() and re-run；see=[ "I40-9","S88-1" ]；tags=[ "T_arr","gamma(ell)","n_eff","c_ref" ]。

X. 维护与治理流程

1. 版本与状态
   • 新增以 DRAFT 进入，完成联调与回归后切换 ACTIVE。
   • 若存在覆盖条目，以 DEPRECATED 指向新 code；冻结旧条目，仅允许加强 remediation 与 see。
   • 迁移完成后标记为 RETIRED，保留只读以保证历史报告可解析。
2. 变更准入
   • 任何 severity 变化需通过跨卷评审，并更新 set_error_policy。
   • 涉及 message 模板变量新增，必须同步扩展 context_schema 并更新生成端。
   • 回归保障：以 compare_reports(a,b, metrics=["mean","U","pass_rate"]) 验证影响不超基线阈值。

XI. 快速校验清单（注册前自检）

• code 格式与唯一性通过；domain 与 <DOMAIN> 一致。
• severity 已映射默认动作；remediation 语法可被执行引擎解析。
• message 中全部 {{var}} 在 context_schema 内；占位符与键名大小写一致。
• 若涉及计量表达（如 T_arr、check_dim），已在样例数据上通过校验与两口径一致性（|delta| ≤ eps_policy）。
• 关联文献的 see 可解析到本卷或配套白皮书的有效锚点。

XII. 与计量卷的关键锚点对齐

• 锚点清单：c_ref、gamma(ell)、d ell、L_gamma、n_eff(x,t)、T_arr。
• 报告要求：凡触达上述锚点的错误码，必须携带 gamma_spec、L_gamma、c_ref_version、refcond_id，并在 tags 中包含相应锚点名。

XIII. 输出物与落地

1. 输出物
   • 标准模式文件（建议导出为 yaml 与 json 双格式），可由 export_units("yaml")、export_refcond("yaml") 的同一流水线发布。
   • 示例库（≥ 20 条建议在实现阶段扩充），与 set_error_policy 的默认策略包一同交付。
2. 落地步骤
   • 以本模式批量注册核心条目（优先 METROLOGY、MEASUREMENT、NUMERICS、DATA_QUALITY）。
   • 在集成环境启用 normalize_error，统一日志与报告侧格式。
   • 将错误码与 SLI/SLO 门控联动，触发 retry/fallback/graceful_degradation 的自动化策略链。