12-EFT.WP.Methods.Repro v1.0 | 第13章 变更管理与版本策略

目录 ／ 文档-技术白皮书 ／ 12-EFT.WP.Methods.Repro v1.0

第13章 变更管理与版本策略

I. 范围与目标

• 建立从变更识别、影响评估、双跑比对、切换与回退到归档的完整策略，使任何版本演进在固定 EnvLock、数据 fingerprint、时基映射 ts = alpha + beta * tau_mono 与基准套口径下可度量、可回滚、可取证。
• 目标产出包括：MigPlan、DiffMatrix、CutoverReport、RollbackReport、CHANGELOG 与兼容旗标集；并与第8章评分与第12章验收门限联动，确保 delta_rep、delta_psd、r_tb、eps_mass 的风险在预算内。

II. 术语与符号

• version = MAJOR.MINOR.PATCH：语义化版本；channel ∈ {canary, stable, LTS}。
• compat flag：兼容旗标集合，如 flag.strict_nan、flag.psd_window_v2、flag.timebase_v2。
• W_mig：迁移窗口；T_dep：弃用生效时刻；T_grace：宽限期。
• budget = { b_rep , b_psd , b_tb , b_mass }：变更差异预算，对应 delta_rep、delta_psd、r_tb、eps_mass 的上限。
• anchor：回退锚点，定义 anchor = hash( EnvLock || PipelineCard || ParamCard || fingerprint )。
• DiffMatrix：双跑逐用例差异矩阵，含 delta_rep_i、delta_psd_i、r_tb_i、R_coef_i 与 perf_norm_i。

III. 公设与最小方程

• P31-50 兼容走廊公设
  在启用兼容旗标并限定 budget 下，新旧实现对外可观测行为差异满足
  Pr( delta_rep <= b_rep ∧ delta_psd <= b_psd ∧ r_tb <= b_tb ∧ eps_mass <= b_mass ) → 1 当样本与窗充分时。
• P31-51 回退可达公设
  任意 stable/LTS 发布必存在 anchor 与回退剧本，使 ( rollback_to( anchor ) ) 在有限步内恢复到通过门状态。
• S32-60 变更分级判据
  class(change) = MAJOR 若满足 schema_break ∨ api_break ∨ require_new_data ∨ require_new_EnvLock；
  class(change) = MINOR 若 default_param_change ∨ perf_shift ∨ feature_add 且无破坏性；
  否则 class(change) = PATCH。
• S32-61 双跑聚合差异
  Delta_agg = ( Σ ( w_i * delta_rep_i ) ) / ( Σ w_i )；
  PSD_agg = ( Σ ( w_i * delta_psd_i ) ) / ( Σ w_i )；
  TB_agg = ( Σ ( w_i * r_tb_i ) ) / ( Σ w_i )；
  通过条件：Delta_agg <= b_rep ∧ PSD_agg <= b_psd ∧ TB_agg <= b_tb。
• S32-62 升级守恒与回归公差
  score_new - score_old >= -tau_reg 且 lower( CI_score_new ) >= tau_score；tau_reg 由第12章设定。
• S32-63 弃用计划一致性
  对任一弃用项 d，应给出 ( T_dep - now ) >= T_grace 且在 W_mig 内提供旗标过渡 compat flag(d)。

IV. 数据与清单口径

• 变更条目最小字段
  version、channel、change_type ∈ {MAJOR, MINOR, PATCH}、compat flags、W_mig、T_dep/T_grace、budget、影响面（EnvLock、PipelineCard/ParamCard、数据模式、时基口径 alpha,beta、窗口 U_w/ENBW）与风险评估。
• 双跑证据包
  DiffMatrix 原始记录、用例权重 w_i、两口径 T_arr 与 delta_form、ScoreSummary(old,new)、audit chain 的 H_k 与 sig_k。
• 归档与可取证
  对每次切换产出 CutoverReport 与 RollbackPlan，以 hash(·) 与 fingerprint 固化并跨渠道复指。

V. 算法与实现绑定

• I30-25 plan_migration(change:dict, baseline:any, constraints:dict) -> MigPlan
  生成 budget、W_mig、compat flags、受影响清单与观测点 TS.*。
• I30-26 run_dual_track(plan:dict) -> DiffMatrix
  以固定 EnvLock、seed、alpha,beta 并行运行旧/新实现，产出逐用例差异与性能计量。
• I30-27 evaluate_compat(diff:any, thresholds:dict) -> {pass:bool, report:any}
  实现 S32-61/62，返回是否通过与差异分解。
• I30-28 execute_cutover(plan:dict, mode:str) -> CutoverReport
  mode ∈ {shadow, canary, blue-green, all-at-once}；联动告警与回退锚点登记。
• I30-29 rollback_to(anchor:any) -> RollbackReport
  执行回退并验证 gate.rep、tau_psd、tau_tb 恢复达标。

VI. 计量流程与运行图

1. Mx-35 classify-and-scope
   • 标注 change_type 与影响面（环境、数据、算法、度量）；
   • 设定 budget 与 compat flags；
   • 生成 MigPlan 与观察矩阵（对齐 TS.* 指标）。
2. Mx-36 dual-run-and-compare
   • 调用 I30-26 产出 DiffMatrix；
   • 计算 Delta_agg/PSD_agg/TB_agg 与 delta_form；
   • 触发 I30-27，形成通过/否决与整改建议。
3. Mx-37 decide-and-cutover
   • 若 evaluate_compat.pass = true 且 score_new 达标，则选择切换模式执行 I30-28；
   • 若部分用例超预算，但通过兼容旗标可屏蔽，进入 shadow 或 canary 扩样；
   • 若失败，进入回退与修复循环（I30-29）。
4. Mx-38 deprecate-and-archive
   • 公布 T_dep/T_grace 与迁移指南；
   • 在第9章审计轨登记 H_k，归档 CutoverReport、RollbackPlan 与 CHANGELOG；
   • 更新基线与基准套映射。

VII. 验证与测试矩阵

1. 分级验证
   • MAJOR：强制全量双跑，budget 取保守上限；需通过 S32-61/62 且 delta_form 纳分不超设定。
   • MINOR：抽样双跑，关键用例全量；允许 perf_norm 正向波动但需给出 CI_score 保障。
   • PATCH：最小回归集 + 审计轨一致性校验。
2. 边界场景
   • 数据模式演进：执行可逆迁移算子 Migrate(schema_v_old -> schema_v_new)，验证幂等与回退性；
   • 时基口径变更：重新拟合 alpha,beta，报告 r_tb 与其对 score 的边际影响；
   • 窗口与谱口径切换：U_w/ENBW 改动引发的 delta_psd 敏感性分析。
3. 告警与门限联动
   • 硬门：Delta_agg <= b_rep、PSD_agg <= b_psd、TB_agg <= b_tb、eps_mass <= b_mass；
   • 软门：lower( CI_score_new ) >= tau_score、score_new - score_old >= -tau_reg。

VIII. 交叉引用与依赖

IX. 风险、限制与开放问题

• 风险
  兼容旗标长期滞留导致口径分裂；EnvLock 局部松动造成隐性 E_ENV_DRIFT；聚合权重不当引发 Simpson 偏差；供应商驱动更新引入 E_NONDETERMINISM。
• 限制
  线性预算对强非线性链路不敏感；小样本迁移下 CI_score 近似偏差；跨域 c_ref、n_eff 估计差异可能放大 delta_form。
• 开放问题
  自适应预算调度与风险加权；跨站点联合双跑的分布同等性检验；弃用策略与 W_mig 的最优分配。

X. 交付件与版本管理

1. 交付件
   • MigPlan（budget/W_mig/T_dep/T_grace/compat flags/anchor）；
   • DiffMatrix 与 ScoreSummary(old,new)；
   • CutoverReport、RollbackReport 与审计链 H_k/sig_k；
   • CHANGELOG：逐版本差异、影响面、旗标、窗口与门限变更；
   • 迁移指南与回退剧本。
2. 版本策略
   • 触发 MAJOR 的事件需新建 LTS 分支并冻结旧 LTS 的安全修复窗口；
   • MINOR 进入 canary → stable 发布列车，W_mig 内保持双跑；
   • PATCH 可直接 stable 推送，但必须更新 CHANGELOG 与 anchor；
   • 所有版本以 hash(·) 与 fingerprint 固化，支持长期可取证与一键回退。