12-EFT.WP.Methods.Repro v1.0 | 第2章 术语、边界与对象模型

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

第2章 术语、边界与对象模型

I. 范围与目标

1. 本章统一本卷使用的术语体系，确立环境/数据/算法/度量四层对象模型（Env/Data/Algo/Metrics），并给出层间接口边界与最小清单。
2. 目标包括：
   • 定义复现相关核心量与冲突名，确保跨卷口径一致。
   • 以对象模型阐明输入输出、不可变性与追溯关系，给出最小字段集。
   • 指定层间契约与合规门，支撑 gate.rep 的自动化校验与发布。

II. 术语与符号

1. 复现分层与等级
   • reproducible：同站点、同 EnvLock、同 seed，输出满足 delta_rep 门限。
   • replicable：跨站点或轻度环境差异，满足统计与谱一致性门。
   • portable：跨硬件/OS/加速器，接口稳定，门限不变。
2. 对象与标识
   • EnvLock：环境锁定快照（OS、kernel、driver、accel、libs、compiler 等）。
   • PipelineCard：管线卡，描述执行图、版本与依赖。
   • ParamCard：参数卡，描述可调参数与约束（单位、量纲、域）。
   • oid = hash(bytes(obj))：对象标识；fingerprint 为代码+参数+环境的聚合指纹。
   • 结果哈希组合：fp = hash( bytes(code) || bytes(params) || bytes(env) )。
3. 时基与随机性
   • tau_mono 内部单调时基；ts 发布时基；映射 ts = alpha + beta * tau_mono。
   • seed 随机种；rng_family、rng_device 随机源族与设备标识。
4. 复现度量与门
   • delta_rep = ( norm( y_new - y_ref ) / max( norm( y_ref ), eps_floor ) )
   • R_coef = 1 - delta_rep；eps_floor > 0。
   • 谱一致性：var( x ) ≈ ( ∫ S_xx(f) df )，报告窗口能量 U_w 与 ENBW。
   • 通过门集合 gate.rep = {tau_rep, tau_psd, tau_tb, ...}。
5. 路径与到达时（跨卷约束）
   • 路径与测度：gamma(ell)，d ell。
   • 两口径并行：T_arr = ( 1 / c_ref ) * ( ∫ n_eff d ell ) 与 T_arr = ( ∫ ( n_eff / c_ref ) d ell )；差异 delta_form 必报告。
6. 冲突名强制
   T_fil 仅指张力；T_trans 仅指透射系数；n 与 n_eff 严格区分。

III. 公设与最小方程

• P31-1 确定性重放公设
  固定 EnvLock 与 seed 时，同一管线对同一输入产生同分布输出；若全确定，则 hash(outputs) 相等。
• P31-2 接口不变性公设
  层间接口签名在语义上稳定；版本升级应保持输入输出集合与量纲不变或提供显式迁移。
• P31-3 不可变性与追溯公设
  入湖对象以内容寻址 oid = hash(bytes(obj))；任何修改均生成新 oid 与新 fingerprint。
• S32-1 结果差异与复现系数
  delta_rep = ( norm( y_new - y_ref ) / max( norm( y_ref ), eps_floor ) )，R_coef = 1 - delta_rep。
• S32-2 时基映射
  ts = alpha + beta * tau_mono；alpha, beta 由标定获得，窗口内稳定。
• S32-3 指纹合成
  fp = hash( bytes(code) || bytes(params) || bytes(env) || bytes(inputs.meta) )，用于等价性快速判定与审计。

IV. 数据与清单口径

1. 最小字段（跨层通用）
   • 标识：project_id，dataset_id，schema.version，submit_ts，oid，fingerprint
   • 时基：alpha，beta，tau_mono_origin，ts_origin
   • 随机性：seed，rng_family，rng_device
   • 窗口：window = [t0, t1]，fs，window_fn，U_w，ENBW
   • 路径：若涉及路径积分，给出 gamma(ell) 参数化与支集、测度 d ell
   • 指标：delta_rep，R_coef，tau_rep，tau_psd，pass（bool）
2. 单位与量纲
   发布前执行 check_dim(expr)；所有字段单位显式声明；无量纲量包括 delta_rep，R_coef，alpha，beta。
3. 跨卷字段映射与口径继承
   • 与《Core.DataSpec》：字段前缀建议 DS.*；标注 schema.version 与演进策略。
   • 与《Core.Threads》：运行观测使用 TS.* 指标（hb、bp、makespan 等）。
   • 与《Core.Metrology》：谱口径字段 MET.psd.*`，含窗口、泄漏与校准系数。
   • 涉及到达时与介质的字段从《Core.Sea》《Core.Density》继承：c_ref，n_eff，路径 gamma(ell)。

V. 算法与实现绑定

1. 对象层接口（契约要点）
   • Env → Algo
     1. 输入：EnvLock
     2. 契约：声明确定性域与非确定性算子清单；暴露 rng_family 与加速器后端。
   • Algo → Data
     1. 输入：PipelineCard，ParamCard，inputs
     2. 契约：纯函数假设在 EnvLock 下成立；输出以 oid 内容寻址。
   • Data → Metrics
     1. 输入：数据清单与窗口口径
     2. 契约：谱估计与统计量需报告 U_w，ENBW 与偏差修正口径。
   • Metrics → Gate
     1. 输入：delta_rep，R_coef，谱指标
     2. 契约：对 gate.rep 做布尔决策并生成审计条目。
2. 参考原型（与附录B一致）
   • I30-1 freeze_environment(config:dict) -> EnvLock
   • I30-2 emit_pipeline_card(state:any) -> dict
   • I30-3 run_benchmark_suite(card:dict) -> BenchReport
   • I30-4 verify_reproduction(golden:any, candidate:any, metrics:dict) -> RepReport
   • I30-6 align_timebase(trace:any, reference:any) -> {alpha:float, beta:float, fit:dict}
3. 幂等与异常
   • 幂等：重复调用应产出相同 oid 或显式 no-op。
   • 异常：E_ENV_DRIFT，E_DATA_MISMATCH，E_TIMEBASE_SKEW，E_NONDETERMINISM，E_SEED_INVALID，E_SCHEMA_MISMATCH。

VI. 计量流程与运行图

1. Mx-31 环境冻结与登记
   • 采集硬件/OS/驱动/库版本生成 EnvLock。
   • 记录 rng_family、seed 策略与加速器后端。
2. Mx-32 接口与口径检查
   • 校验 PipelineCard 与 ParamCard 的单位与量纲。
   • 若含路径积分，登记 gamma(ell) 与 d ell。
3. Mx-33 时基与谱标定
   • 对齐 alpha, beta；验证 ts = alpha + beta * tau_mono。
   • 谱口径按《Core.Metrology》执行窗口与泄漏修正。
4. Mx-34 复现门评估
   • 计算 delta_rep，R_coef 与谱一致性。
   • 生成 RepReport 并打入审计轨。

VII. 验证与测试矩阵

1. 最小必测
   • 接口稳定性：版本跃迁后 PipelineCard 与 ParamCard 语义不变。
   • 确定性回归：固定 EnvLock 与 seed，期望 delta_rep = 0（确定性管线）。
   • 谱一致性：| var(x) - ( ∫ S_xx(f) df ) | <= tau_psd。
2. 边界与极端
   • 浮点精度切换（float32 ↔ float64）
   • 线程归约顺序与 GPU 后端切换
   • 采样漂移、缺包与窗口错配
3. 通过门与置信
   tau_rep、tau_psd、tau_tb 由项目级配置；按《Core.Errors》给出功效与显著性。

VIII. 交叉引用与依赖

• 《Core.DataSpec》：清单与模式演进、内容寻址规范。
• 《Core.Threads》：TS.* 指标、hb、bp、限流与回退。
• 《Core.Metrology》：S_xx(f)、U_w、ENBW 的计量与偏差修正。
• 《Core.Sea》《Core.Density》：时间基准、介质与参考速度 c_ref；路径 gamma(ell) 与测度 d ell。
• 《Core.Equations》《Core.DrawingKinetics》：若涉及 T_arr，两口径并行与 delta_form 报告口径。

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

• 非确定性源（线程调度、GPU 内核、原子序）难以完全屏蔽，需以统计门兜底并在清单中标注。
• 指纹 fp 无法证明语义等价，仅提供高概率一致性指示；仍需 delta_rep 与谱门验证。
• 长期环境漂移（微码、编译器）可能破坏 EnvLock 可重建性，需 LTS 二进制与再构建剧本。
• 开放问题：跨加速器的数值等价标准、混合精度预算在 gate.rep 中的分配。

X. 交付件与版本管理

1. 产出件
   • 术语与对象模型说明（本章）
   • 层间接口规范与最小字段清单
   • 校验脚本与门限配置样例（用于 gate.rep）
2. 版本策略
   • 按语义化版本管理接口与清单；任何破坏性变更必须附迁移剧本。
   • 双跑比对：版本跃迁前后并行运行，计算 delta_rep、R_coef 与谱差；不通过即回退。
   • 审计轨：为每次发布生成 fingerprint、oid、门限与判定记录。