12-EFT.WP.Methods.Repro v1.0 | 第7章 管线卡与参数卡

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

第7章 管线卡与参数卡

I. 范围与目标

1. 本章定义 PipelineCard 与 ParamCard 的统一口径，用于打包环境锁定 EnvLock、数据依赖、算子图、随机源策略 rng_family/seed/stream_id、时基对齐参数 alpha,beta 与门限 gate.rep，支撑跨站点、跨时间的复现与审计。
2. 目标包括：
   • 给出两类卡片的最小必填字段与可选扩展集，覆盖版本、签名、清单与量纲约束。
   • 规定卡片生成、校核、签名、发布的流程 Mx-39 → Mx-41，与异常与回退策略。
   • 对接实现绑定 I30-*：发卡、校验、差分、签名与物化运行的原型与契约。

II. 术语与符号

• PipelineCard：描述一次可复现运行所需的工件清单与调度意图的卡片对象。
• ParamCard：描述算法/模型/实验的参数集合与量纲约束的卡片对象。
• schema.version：卡片模式版本，遵循语义化版本。
• artifact：具名工件，含 uri 与 hash(·)，支持内容寻址。
• fingerprint：跨字段摘要指纹，供审计轨与对照。
• EnvLock：见第5章，环境与依赖锁定的摘要对象。
• alpha,beta：时基映射参数，ts = alpha + beta * tau_mono。
• rng_family, seed, stream_id：随机源策略（见第6章）。
• gate.rep：复现通过门；delta_rep 与 R_coef 作为核心指标。
• 冲突名强制：T_fil 与 T_trans 不可混用；n 与 n_eff 严格区分；到达时两口径需并行报告 delta_form。

III. 公设与最小方程

1. P31-13 卡即契约公设
   在给定 PipelineCard 与匹配的 ParamCard、且 EnvLock 生效的前提下，运行输出满足同分布一致性，度量以 delta_rep、R_coef 与谱一致性检验约束。
2. P31-14 量纲一致公设
   任一参数 p_i 若声明单位与量纲，发布前必须通过 check_dim( p_i ) 与单位校核，禁止无量纲对数非法用法（如 ln( length )）。
3. S32-17 复现门与评分合成
   • delta_rep = ( norm( y_new - y_ref ) / max( norm( y_ref ), eps_floor ) )
   • R_coef = 1 - delta_rep
   • score = w1 * R_coef + w2 * ( 1 - delta_psd ) + w3 * pass( gate.rep )，权重 w1 + w2 + w3 = 1。
4. S32-18 卡片差分影响度
   设两卡差分集合 D = { d_j }，每项影响系数 impact_j ∈ [0,1]，则
   risk_index = ( ∑_j w_j * impact_j ) / ( ∑_j w_j )，用于回归优先级与回退决策。
5. S32-19 到达时两口径约束（如卡片声明 T_arr）
   并行计算
   T_arr = ( 1 / c_ref ) * ( ∫ n_eff d ell ) 与 T_arr = ( ∫ ( n_eff / c_ref ) d ell )，并发布 delta_form 与路径 gamma(ell)、测度 d ell。

IV. 数据与清单口径

1. PipelineCard 最小必填字段
   • 身份与版本
     card.id，schema.version，created.ts，author，fingerprint。
   • 环境与时基
     env_lock_ref（指向 EnvLock），timebase = { alpha, beta, r_tb, window }。
   • 随机源策略
     rng = { rng_family, seed, H.name, H.version, stream_id_schema }。
   • 数据与工件
     inputs = [ { name, uri, hash, role, window } ]；references = [ { name, uri, hash } ]。
   • 执行图与调度
     graph = { nodes:[ { id, op, version, container, entrypoint } ], edges:[ (u,v) ] }；constraints = { hb, bp, resources, affinity }；与《Core.Threads》之 TS.* 对齐。
   • 门限与告警
     gates = { gate.rep, tau_tb, tau_jitter, tau_psd, tau_var }；alerts = { on_fail: [action] }。
   • 到达时（可选）
     arrival = { paths:[ gamma(ell) ], c_ref, media, report_delta_form:bool }。
2. PipelineCard 可选字段
   release.channel ∈ { canary, stable, LTS }；audit = { reviewers, signature }；notes；labels。
3. ParamCard 最小必填字段
   • 身份与版本
     param.id，schema.version，scope（如 op_scope 或模块名），created.ts，author。
   • 参数集合
     params = [ { name, value, unit, dim, bounds, frozen:bool } ]；其中 dim 为量纲表达（如 M^1 L^-1 T^-2）。
   • 约束与依赖
     constraints = { check_dim:bool, monotone:[name], categorical:[name], coupled:[ (a,b, law) ] }。
   • 标定来源
     calib = { dataset_ref, method, uncertainty, fit.ts }。
   • 签名与指纹
     fingerprint，signature（可后续补签）。
4. ParamCard 可选字段
   priors = { name: distribution, hyperparams }；transform = { name: function }；release.notes。
5. 入湖与追溯要求
   两卡均需记录 hash(·)、fingerprint 与外链 uri；任何更新形成新 schema.version 与新 fingerprint，旧版只读不可变。

V. 算法与实现绑定

1. I30-2 emit_pipeline_card(state:any) -> dict
   • 汇总 EnvLock、图 G=(V,E)、rng、timebase 与 gates。
   • 计算 fingerprint = hash( fields_ordered ) 并附加。
   • 返回 PipelineCard，并写入审计日志。
2. I30-11 emit_param_card(source:any, scope:str) -> dict
   • 从 source 抽取参数与单位、量纲 dim。
   • 执行 check_dim( p_i ) 与边界校验，失败抛出 E_DIMENSION_MISMATCH。
   • 生成 ParamCard 与 fingerprint。
3. I30-12 validate_card(card:dict) -> LintReport
   • 校验必填集、冲突名、两口径声明一致性。
   • 交叉校核：rng 与第6章策略一致；timebase 与第6章 r_tb 门限。
   • 产出 failures、warnings、pass:bool。
4. I30-13 diff_cards(card_a:dict, card_b:dict) -> ImpactReport
   • 逐域比较，生成差分集合 D。
   • 依据 S32-18 估计 risk_index，并产出回归建议。
5. I30-14 sign_and_publish_card(card:dict, key_ref:any) -> {uri:str, signature:any}
   • 对 fingerprint 与关键域签名。
   • 发布到受控仓库，返回 uri 与 signature。
6. I30-15 materialize_pipeline(card:dict, mode:str) -> RunPlan
   • 解析 graph 与 constraints，绑定资源与亲和性。
   • 输出可执行 RunPlan，含 TS.* 观测点与告警编排。
7. 典型异常
   E_SCHEMA_MISMATCH，E_ENV_DRIFT，E_TIMEBASE_SKEW，E_NONDETERMINISM，E_DATA_MISMATCH，E_BOUNDS_VIOLATION。

VI. 计量流程与运行图

1. Mx-39 card-emit-lint-sign
   • emit_pipeline_card → validate_card。
   • 通过后 sign_and_publish_card；失败触发 alerts.on_fail。
2. Mx-40 param-freeze-verify
   • emit_param_card → validate_card（量纲、边界、耦合）。
   • 双跑对照，要求 delta_rep <= gate.rep 与 delta_psd <= tau_psd，否则回退。
3. Mx-41 plan-materialize-run
   • materialize_pipeline 生成 RunPlan，绑定 TS.* 观测。
   • 按 release.channel 执行 canary → stable 的分层发布。

VII. 验证与测试矩阵

1. 架构一致性
   • 删除任一必填字段应导致 validate_card.pass = false。
   • 冲突名与两口径声明不一致应触发硬失败。
2. 量纲与单位
   • 人工注入维度错误，check_dim 必捕获并报 E_DIMENSION_MISMATCH。
   • 对 log/exp/ln 自变量进行无量纲性检查。
3. 随机性与时基
   • 卡片 rng 与第6章策略不一致触发告警。
   • r_tb > tau_tb 触发 E_TIMEBASE_SKEW 并阻断发布。
4. 差分与回归
   • diff_cards 的 risk_index 与实际 delta_rep 相关性需达成设定阈值（如皮尔逊系数 ≥ 0.7）。
   • 高风险差分需强制进入 canary 通道并增加样本量。

VIII. 交叉引用与依赖

• 第5章 EnvLock；第6章 alpha,beta、rng_family/seed 与 S_tt(f)；第8章 评分函数与门限；第12章 验收与发布流程。
• 《Core.Threads》：TS.* 指标、hb、bp 与执行图约束。
• 《Core.DataSpec》：模式版本、清单字段与入湖策略。
• 《Core.Metrology》：谱估计 S_xx(f)、U_w、ENBW 与不确定度口径。

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

• 风险
  隐式默认参数未入 ParamCard，导致影子配置；容器入口脚本覆盖卡片字段；外部数据二次解析破坏 hash(·) 的可验证性。
• 限制
  某些硬件特性（如 denorm、原子序）无法完全在卡片层表达，仍需结合 EnvLock 细节。
• 开放问题
  risk_index 的跨域标定与自适应权重学习；ParamCard 的层级继承与冲突合并策略；到达时两口径在多介质组合路径上的规范化表达。

X. 交付件与版本管理

1. 产出件
   pipeline.card.json，param.card.json，impact.report.json，run.plan.json，签名包与 fingerprint 索引。
2. 版本与通道
   • schema.version 采用 MAJOR.MINOR.PATCH；MAJOR 变更需提供迁移脚本与双跑对照。
   • 发布遵循 canary → stable → LTS；任一门限失败回退至上一个稳定版本并触发 Mx-40 复核。
3. 审计与归档
   卡片与签名、清单与评分报告一并入湖，留存 created.ts、release.channel、reviewers 与 signature；对声明 T_arr 的卡片强制发布 delta_form 与路径 gamma(ell)、测度 d ell 清单。