03-EFT.WP.Core.Parameters v1.0 | 第8章 治理、版本与复用

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

第8章 治理、版本与复用

I. 章节目标与范围

• 建立参数资产的治理框架：版本语义、场景管理、别名策略、冻结/解冻、兼容性与回归基线。
• 定义最小流程 Mx-4，对接实现接口 I30 9/11/12，保障跨卷一致复用与可追溯。
• 强化冲突规避：T_fil 与 T_trans、n 与 n_eff 严格区分；路径相关量必须显式 gamma(ell) 与 d ell。

II. 治理对象与角色

1. 治理对象
   • 参数注册表：由 register_param 建立的规范条目（字段含 code/unit/role/bounds/prior/transform 等）。
   • 场景与基线：通过 create_scenario/activate_scenario 管理的参数集与其回归基线。
   • 复用关系：add_alias/tie_params/derive_param/freeze/thaw 形成的依赖网。
2. 典型角色（职责口径）
   • 维护者：批准 MAJOR 变更与冻结策略。
   • 提交者：新增条目与别名，提交场景差异。
   • 审核者：执行回归与兼容性检查，签发版本标签。

III. 版本语义与编号（治理公设 P81-1…P81-3）

1. P81-1 语义化版本
   • 版本写作 MAJOR.MINOR.PATCH，由 bump_version(semver) 执行。
   • PATCH：不改变语义与接口，仅修正 prior 超参数、默认值或文档；code/unit/bounds/transform 不变。
   • MINOR：后向兼容的增强，如新增参数（有默认与先验）、放宽 bounds、新增 alias；已有 YAML 不需修改即可解析并得到同值。
   • MAJOR：任一破坏性修改（重命名 code、更改 unit、修改 transform 族或缩放、收紧 bounds 使既有值非法、改变物理语义）。
2. P81-2 兼容性定义
   给定旧集 X_old 与新集 X_new，若 export_params("yaml") 的旧文档在新版本 import_params 下可无告警解析，且 compare_param_sets(X_old, X_new, ["L2","Corr"]) 返回 L2 ≤ ε_L2、Corr ≥ 1-ε_corr，则判定后向兼容。
3. P81-3 不可见改动
   任意影响 check_dim(expr) 结论的改动均视为 MAJOR，即使数值未变。

IV. 场景管理与继承（最小流程 Mx-4A）

• 新建：SRef = create_scenario(name, base=None|base_name)，从 base 复制参数集。
• 激活：activate_scenario(name)，后续操作均作用于活动场景。
• 叠加与解析（S81-1）
  设层次 base → scenario → local，有效值定义为
  value_eff(code) def= select( local, scenario, base )（自右向左覆盖，空缺则继承）。
• 差异与审计：diff_scenarios(a,b) 输出字段级差异与依赖影响。
• 基线冻结：导出 export_params("yaml") 建立回归基线工件，并标注 version/scene/hash.

V. 别名、规范化与重定向（最小方程 S81-2）

1. 规范化管线
   token → normalize_param(token) → canonical code
2. 约束与冲突
   • 同一 alias 不得映射至多个 canonical。
   • alias 不得与任意 code 重名。
3. 迁移建议
   仅在 MINOR/MAJOR 版本引入 alias，并在导出时始终回写 canonical，保证工件稳定。

VI. 冻结/解冻与共享（治理公设 P81-4…P81-5）

• P81-4 冻结语义
  执行 freeze(code) 后，set_bounds/set_prior/set_transform/derive_param/tie_params 均被禁止对该 code 生效；解冻须显式 thaw(code) 并记录审计线。
• P81-5 共享与绑定
  共享关系须显式：theta_a = theta_b 或 theta_a def= g(theta_b)（由 tie_params/derive_param 建立）。任何隐式共享视为违规。

VII. 兼容性矩阵与变更控制（最小流程 Mx-4B）

• 变更提案：以差异清单描述 code/unit/bounds/prior/transform 的拟改动与影响面。
• 量纲审查：对受影响表达式运行 check_dim(expr)；涉及路径项一律使用 ( n_eff / c_ref ) * d ell 并显式 gamma(ell)。
• 回归基线：compare_param_sets(X_old, X_new)，判定阈值 ε_L2, ε_corr 由场景定义。
• 影响扩散：若影响 S20-*（到达时）或 S40-*（张度场），用 compute_jacobian 取 ∂ g / ∂ theta 做一阶评估并在需要时触发采样传播（见第7章）。
• 版本签发：依据 P81-1 判级并 bump_version；生成发行说明与变更记录（附录B）。

VIII. 导入、导出与回归基线（最小方程 S81-3）

• 导出工件规范（YAML 字段最小集）
  code, name, role, unit, default, bounds{lb,ub}, prior{family,hyper{...}}, transform{name,args}, version, scene, depends, status
• 回归命名
  基线命名 RB-Param-<scene>-v<MAJOR.MINOR>；推荐随 MINOR 更新。
• 基线比对（通过 compare_param_sets）
  通过条件：L2 ≤ ε_L2 且 Corr ≥ 1-ε_corr；否则标为“可能破坏”，需 MAJOR 或补充迁移脚本。

IX. 复用与跨卷绑定（最小流程 Mx-4C）

• 绑定识别：列出与目标方程 Sxx-* 的耦合参数，如到达时需要 c_ref、n_eff，并声明路径 gamma(ell) 与 d ell。
• 一致性校验：调用 check_dim 与第7章线性化式验证 ( n_eff / c_ref ) * d ell 的无量纲性。
• 推导与派生：如需无量纲参数，使用 derive_param("bar_n_eff", "n_eff / n_eff_ref", ["n_eff","n_eff_ref"])，并在导出时保留依赖。
• 变更联动：任一被绑定参数发生 MAJOR 变更时，触发对应方程卷的兼容性评审与回归。

X. 审计与可追溯

• 审计记录建议包含：操作人、时间、scene、变更字段、旧→新、理由、关联 issue、回归结果、版本标签。
• 工件完整性：导出时建议计算 sha256 摘要并附带到元数据字段 hash（文本保存，不涉实现）。

XI. 标准治理流水线 Mx-4（端到端）

• 立项与基线：create_scenario → export_params 建立 RB-Param-<scene>-vX.Y。
• 变更实现：新增/修改参数或关系（register_param/add_alias/tie_params/derive_param），必要时 freeze/thaw。
• 校验三件套：validate_param_set、check_dim(expr)、compare_param_sets。
• 兼容性决策：依据 P81-1 判定 PATCH/MINOR/MAJOR，编制迁移与别名表。
• 版本签发与归档：bump_version，生成发行说明与审计记录，更新回归基线。
• 跨卷同步：在《Core.Equations》《Core.Terms》处登记引用更新与到达时用例验证。

XII. 误用与冲突清单

• 在冻结状态下隐式改动 bounds/prior/transform。
• 以 alias 写入工件或在工件内混用 alias 与 canonical。
• 更改 unit 或缩放而仍标注为 MINOR/PATCH。
• 在到达时链路中误用 n 替代 n_eff，或写作 ∫ n d ell / c（缺括号且路径未声明）。
• 导出缺失 prior.hyper 或缺失 bounds，导致可行集 Theta 不可判定。

XIII. 输出锚点与引用

• 治理公设：P81-1（语义化版本）、P81-2（兼容性定义）、P81-3（量纲变更即 MAJOR）、P81-4（冻结语义）、P81-5（显式共享）。
• 最小方程：S81-2（别名规范化）、S81-3（导出工件最小字段）、S81-1（场景叠加解析）。
• 标准流程：Mx-4A/B/C（场景管理、变更控制、跨卷绑定）。
• 实现接口：I30 9/11/12 与 compare_param_sets、check_dim、compute_jacobian、export_params/import_params。