12-EFT.WP.Methods.Repro v1.0 | 附录B 实现绑定与函数原型

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

附录B 实现绑定与函数原型

I. 范围与目标

• 本附录汇总实现绑定层 I30-* 原型、输入输出、幂等与重放语义、异常与处理，以及关键伪代码片段，保障跨章与跨域复现的一致性与可验证性。
• 所有函数签名、变量与公式均使用英文与纯文本表达；内联量以反引号包裹；涉及测度与积分按全卷统一口径声明；并发观测遵循《Core.Threads》之 TS.* 字段。

II. 术语与符号

• 环境与签名：EnvLock，hash(·)，fingerprint，anchor。
• 卡片与报告：PipelineCard，ParamCard，BenchReport，RepReport，MigPlan，CutoverReport，RollbackReport。
• 复现与度量：delta_rep，R_coef = 1 - delta_rep，delta_psd，gate.rep，eps_norm，eps_mass。
• 时基与谱：tau_mono，ts，alpha，beta，S_xx(f)，U_w，ENBW。

III. 设计原则与绑定约束

• 纯函数优先与显式副作用：除明示的持久化与签名外，函数应对同一输入与 EnvLock 产生稳定输出。
• 幂等域声明：为每一原型定义 idemp_key = hash( name || version || inputs || EnvLock )；在幂等域内重复调用返回同一 fingerprint 与 anchor。
• 时基对齐：涉及时间序列的处理先映射至公共 ts，遵循 ts = alpha + beta * tau_mono。
• 随机性控制：所有涉及采样或初始化的原型必须显式 seed 与 rng_family，并在 RepReport 中回填。
• 量纲与单位：在进入核心算子前执行 check_dim(expr)；谱口径需声明窗口、U_w 与 ENBW。

IV. 原型清单与参数

1. I30-1 freeze_environment(config:dict) -> EnvLock
   • 输入：config（OS、kernel、drivers、libs、compiler、cpu_id、gpu_id、flags、rng_family）。
   • 输出：EnvLock。
   • 幂等：以 config 规范化序列化为幂等域。
   • 异常：E_ENV_DRIFT。
   • 备注：EnvLock = hash( normalized(config) )。
2. I30-2 emit_pipeline_card(state:any) -> dict
   • 输入：state（DAG、io anchors、metrics、alerts）。
   • 输出：PipelineCard。
   • 幂等：以 state 与 EnvLock 绑定。
   • 异常：E_SCHEMA_MISMATCH。
3. I30-3 run_benchmark_suite(card:dict) -> BenchReport
   • 输入：PipelineCard（含数据与步骤绑定）。
   • 输出：BenchReport（用例结果、delta_psd、R_coef、score 局部分项）。
   • 幂等：以 card、EnvLock、seed 绑定。
   • 异常：E_DATA_MISMATCH，E_NONDETERMINISM。
4. I30-4 verify_reproduction(golden:any, candidate:any, metrics:dict) -> RepReport
   • 输入：golden，candidate，metrics（门限与权重）。
   • 输出：RepReport（delta_rep，R_coef，delta_psd，gate.rep）。
   • 幂等：以 golden 指纹、candidate 指纹与 metrics 绑定。
   • 异常：E_DATA_MISMATCH。
5. I30-5 snapshot_provenance(artifacts:list) -> dict
   • 输入：artifacts（文件、模型、卡片、报告）。
   • 输出：{fingerprint:list, anchor:str}。
   • 幂等：以工件内容与元信息绑定。
   • 异常：E_SCHEMA_MISMATCH。
6. I30-6 align_timebase(trace:any, reference:any) -> {alpha:float, beta:float, fit:dict}
   • 输入：trace（内部 tau_mono 序列），reference（外部 ts 序列）。
   • 输出：alpha，beta，fit（r_tb 与残差分解）。
   • 幂等：以输入序列与拟合口径绑定。
   • 异常：E_TIMEBASE_SKEW。
   • 备注：拟合模型为线性最小二乘或稳健回归，报告 r_tb = ( norm( ts - ( alpha + beta * tau_mono ) ) / norm( ts ) )。
7. I30-7 compare_psd(x:any, y:any, window:dict) -> {delta_psd:float, pass:bool}
   • 输入：x，y（对齐到同一 ts 的信号），window（w[n]、U_w、ENBW、带宽与重叠）。
   • 输出：delta_psd，pass。
   • 幂等：以数据指纹与窗口配置绑定。
   • 异常：E_SCHEMA_MISMATCH。
   • 备注：delta_psd = ( ∫ | S_xx(f) - S_yy(f) | df ) / ( ∫ S_xx(f) df )。
8. I30-8 collect_ts_metrics(run_id:str, fields:list) -> dict
   • 输入：run_id，fields ⊆ TS.*。
   • 输出：{ field -> series }。
   • 幂等：以 run_id 与时间窗口绑定。
   • 异常：E_DATA_MISMATCH。
9. I30-9 publish_release(anchor:str, channel:str, policy:dict) -> dict
   • 输入：anchor（EnvLock || PipelineCard || ParamCard 的联合哈希），channel ∈ {canary, stable, LTS}，policy（门限与监控）。
   • 输出：{release_id:str, sig_k:bytes}。
   • 幂等：以 anchor 与 channel 绑定。
   • 异常：E_ENV_DRIFT。
10. I30-10 plan_migration(diff:dict) -> MigPlan
    • 输入：diff（PipelineCard/ParamCard 差异矩阵）。
    • 输出：MigPlan（W_mig，T_dep，T_grace，回退锚点）。
    • 幂等：以 diff 指纹绑定。
    • 异常：E_SCHEMA_MISMATCH。
11. I30-11 execute_cutover(plan:MigPlan) -> CutoverReport
    • 输入：MigPlan。
    • 输出：CutoverReport（双跑比对、score 变化、TS.* 冲击）。
    • 幂等：以 plan 与窗口绑定。
    • 异常：E_ENV_DRIFT，E_TIMEBASE_SKEW。
12. I30-12 rollback(anchor:str, reason:str) -> RollbackReport
    • 输入：anchor，reason。
    • 输出：RollbackReport（恢复点、影响面、ScoreSummary(old,new)）。
    • 幂等：以 anchor 与 reason 绑定。
    • 异常：E_DATA_MISMATCH。

V. 幂等与重放（统一契约）

1. 幂等键：idemp_key = hash( name || version || inputs || EnvLock )；对任意 I30-*，若 idemp_key 相同，则
   • fingerprint(outputs_new) = fingerprint(outputs_old)；
   • 允许生成时间戳差异但不影响 fingerprint（时间戳不入指纹域）。
2. 随机性：涉及采样的原型必须接受 seed；若未显式提供，拒绝执行并返回 E_SEED_INVALID。
3. 时间基准：带时间的输入先执行 I30-6 获得 alpha,beta，将内部 tau_mono 映射到公共 ts，再进行谱与评分计算。

VI. 计量与可观测性接口

1. 必报 TS.* 字段
   • TS.latency.{p50,p95,p99}，TS.thrpt，TS.error_rate，TS.cpu，TS.mem，TS.gpu.util（若适用），TS.hb。
   • 对 I30-3/4/7 追加 TS.psd.band_energy，对 I30-6 追加 TS.timebase.r_tb。
2. 采样与聚合窗口
   统一以外部 ts 切片；窗口长度、步长与对齐策略在 PipelineCard 中声明。

VII. 异常枚举与处理

1. 核心异常
   • E_ENV_DRIFT：环境与 EnvLock 不一致。
   • E_DATA_MISMATCH：输入数据或模式不符合 PipelineCard/ParamCard。
   • E_TIMEBASE_SKEW：时基失配，r_tb 超门限。
   • E_NONDETERMINISM：非确定性迹象，复算输出 fingerprint 不一致。
   • E_SEED_INVALID：未提供 seed 或超出合法域。
   • E_SCHEMA_MISMATCH：结构或字段不匹配。
2. 处理策略（最小集）
   记录 H_k/sig_k 与触发 anchor；回填 TS.* 与差异摘要；若为运行期异常，触发 I30-12 rollback 并附 ScoreSummary(old,new)。

VIII. 参考片段（伪代码与状态机）

1. I30-6 align_timebase 计算流程
   • 接收 trace.tau_mono 与 reference.ts，执行缺失与异常值处理。
   • 构造线性模型 ts ≈ alpha + beta * tau_mono，采用稳健回归求解 alpha,beta。
   • 计算 r_tb = ( norm( ts - ( alpha + beta * tau_mono ) ) / norm( ts ) )；若超阈，返回 E_TIMEBASE_SKEW。
   • 输出 {alpha,beta,fit:{r_tb,residuals}} 并记录 TS.timebase.r_tb。
2. I30-3 run_benchmark_suite 状态机
   • INIT：校核 EnvLock 与 PipelineCard。
   • PREP：映射时基至公共 ts，锁定 seed 与 rng_family。
   • EXEC：逐用例运行，收集 TS.* 与中间产物 fingerprint。
   • ANALYZE：计算 delta_rep、delta_psd、分项 score。
   • DECIDE：与门限比对，设置 gate.rep。
   • FINAL：生成 BenchReport，提交审计签名 sig_k。

IX. 交叉引用与依赖

X. 版本管理与编号策略

• I30-* 为稳定编号空间；新增原型递增编号且保持后向兼容；破坏性参数变更提升 MAJOR；返回字段扩展为 MINOR；文档勘误为 PATCH。
• 每次变更更新 PipelineCard、ParamCard、CHANGELOG 与 anchor，并在审计链登记 H_k/sig_k。