13-EFT.WP.Methods.SimStack v1.0 | 附录A 接口参考与原型

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

附录A 接口参考与原型

I. 范围与目标

• 本附录汇总 I60-* 接口的原型、输入输出、异常枚举、幂等与一致性契约，覆盖连续核、离散编织、耦合与推进、时间基准与校准、数据与清单、调度与资源、误差预算与基准、复现实验与发布。
• 所有符号与公式采取英文与纯文本表达，单位与量纲校核须调用 check_dim(expr)；并发语义、TS.* 指标与 hb/bp 口径对齐《第3章》《第7章》。

II. 公共约定与通用类型

1. 通用标识与时间
   • ts（发布时钟），tau_mono（单调内部时基），ts = alpha + beta * tau_mono。
   • 路径与测度：gamma(ell)，d ell。
2. 到达时两口径
   • T_arr = ( 1 / c_ref ) * ( ∫ n_eff d ell )
   • T_arr = ( ∫ ( n_eff / c_ref ) d ell )
   • 并行计算并发布差异 delta_form。
3. 通用数据类型（文本规范）
   • CouplingRef，PipeRef，EnvLock，PipeCard，ParamCard，CalReport，StepReport，BenchmarkReport，Attest。
   • 结果字段常用键：TS.*，eps_norm，eps_mass，cfl，stable，sha256。
4. 异常与返回错误（可枚举字符串）
   E_DIM_MISMATCH，E_INVALID_UNITS，E_PATH_UNSPECIFIED，E_TIMEBASE_UNLOCKED，E_CFL_UNSTABLE，E_CONSERVATION_FAIL，E_RESOURCE_EXHAUSTED，E_DEADLINE，E_BACKPRESSURE，E_SCHEMA_MISMATCH，E_STORAGE_IO，E_IDEMPOTENCY，E_RETRYABLE，E_NONRETRYABLE。
5. 幂等与一致性
   标注 idempotent=true 的接口须在请求重复时返回同一 Ref 或相同副作用；跨线程通信遵循 hb 语义与去重键 msg.dedup_key。

III. I60-1 couple_fields —— 连续与离散的耦合

1. 原型
   I60-1 couple_fields(sim_state:any, continuous_kernels:list, discrete_nets:list, opts:dict) -> CouplingRef
2. 输入
   • continuous_kernels = [{id, kind, units, domain, bc}]
   • discrete_nets = [{id, graph=G=(V,E), io, semantics}]
   • opts = {interfaces, units.map, path.gamma.list, c_ref, timebase={alpha,beta}}
3. 输出
   CouplingRef，含边界映射、单位映射、路径清单。
4. 异常
   E_SCHEMA_MISMATCH，E_INVALID_UNITS，E_PATH_UNSPECIFIED。
5. 契约
   幂等；建立后 units.map 与 path.gamma.list 不可变更（见口径不可变性）。

IV. I60-2 exchange_packets —— 边界交换

• 原型
  I60-2 exchange_packets(coupling:CouplingRef, t_now:float) -> int
• 输入
  t_now 以 tau_mono 计；消息载荷遵守 at-least-once + idempotent 语义。
• 输出
  成功交换的事件/波包计数。
• 异常
  E_BACKPRESSURE，E_DEADLINE。
• 契约
  消息带 dedup_key；跨线程 hb 顺序保留。

V. I60-3 advance_dt —— 时间推进

• 原型
  I60-3 advance_dt(sim_state:any, dt:float, controller:dict) -> StepReport
• 输入
  controller = {cfl_max, err_tol, scheme, retry, clamp}。
• 输出
  StepReport = {dt_in, dt_out, stable:bool, cfl, eps_norm, eps_mass, TS.*}。
• 异常
  E_CFL_UNSTABLE，E_CONSERVATION_FAIL。
• 契约
  发布守恒残差 eps_mass 与归一误差 eps_norm；stable=false 时回退与重试策略由 controller.retry 指定。

VI. I60-4 calibrate_arrival_time —— 到达时校准

• 原型
  I60-4 calibrate_arrival_time(trace:any, paths:list, c_ref:float, medium:any) -> CalReport
• 输出
  CalReport = {T_arr.general, T_arr.factorized, delta_form, path.gamma.list, timebase={alpha,beta}}。
• 契约
  显式路径与测度；发布两口径并行结果及 delta_form。

VII. I60-5 emit_metrics —— 运行指标

• 原型
  I60-5 emit_metrics(sim_state:any) -> dict
• 输出
  TS.* 指标（延迟、抖动、吞吐、bp、hb 违例计数等）与最新守恒统计。

VIII. I60-6 freeze_env —— 环境锁定

• 原型
  I60-6 freeze_env(env_spec:dict) -> EnvLock
• 输出
  EnvLock = {oci_digest, deps.lock, sys.meta, compiler.flags, H_env=sha256(...)}。
• 异常
  E_MISSING_HW_CAP。
• 契约
  幂等；用于 CL2/CL3 级复现（见第11章）。

IX. I60-7 generate_pipeline_card —— 管线卡生成

• 原型
  I60-7 generate_pipeline_card(sim_state:any, fit:any, opts:dict) -> PipeCard
• 输出
  PipeCard = {graph=G, stage.io, H.id, units.*, timebase, paths.gamma.list, c_ref, TS.probes}。
• 契约
  必须通过 check_dim(expr) 与口径校核。

X. I60-8 materialize_pipeline —— 管线实例化

• 原型
  I60-8 materialize_pipeline(PipeCard, ParamCard, EnvLock) -> PipeRef
• 输出
  PipeRef 与放置计划。
• 异常
  E_SCHEMA_MISMATCH，E_TIMEBASE_UNLOCKED。
• 契约
  幂等；版本不匹配时拒绝实例化。

XI. I60-9 run_with_attestation —— 带佐证运行

• 原型
  I60-9 run_with_attestation(PipeRef, seeds:list) -> Attest
• 输出
  Attest = {run.id, H_env, sha256(artifacts), r.stats, J, delta_form, TS.*}。
• 契约
  记录 ts 与 tau_mono 事件时间；消息链路可追溯。

XII. I60-10 verify_repro —— 复现校验

1. 原型
   I60-10 verify_repro(artifact:any, gates:dict) -> Verdict
2. 输出
   • Verdict = {class=CL0|CL1|CL2|CL3, Score, details}。
   • 判据参见 S62-80。

XIII. I60-11 export_repro_pack —— 复现包导出

• 原型
  I60-11 export_repro_pack(PipeCard, ParamCard, EnvLock, Attest) -> ReproPack
• 输出
  ReproPack 与审计索引条目。

XIV. I60-20 manifest_emit —— 清单落盘

1. 原型
   I60-20 manifest_emit(objects:list, schema:str, opts:dict) -> str
2. 输入
   • objects 包含 PipeCard/ParamCard/CalReport/StepReport/BenchmarkReport。
   • opts = {namespace, version, checksum="sha256"}。
3. 输出
   返回清单对象的内容寻址 cid。
4. 异常
   E_SCHEMA_MISMATCH，E_STORAGE_IO。
5. 契约
   所有数值字段单位显式；窗口与 U_w/ENBW 必填（若含谱量）。

XV. I60-21 dataset_write —— 数据写入

• 原型
  I60-21 dataset_write(stream:any, window:dict, manifest:str) -> int
• 输入
  window = {t0, t1, dt, path.gamma.id}。
• 输出
  写入记录数。
• 契约
  写后返回 sha256 与对齐状态；保证幂等写。

XVI. I60-30 plan_schedule —— 计划与就绪集

• 原型
  I60-30 plan_schedule(G:(V,E), cost:dict, quota:dict, policy:dict) -> dict
• 输入
  cost = {w(v), c(e)}，quota = {cpu, mem, io}，policy = {placement, affinity, bp}。
• 输出
  放置与优先级计划、估计 T_make(G) 与 crit(G)。
• 异常
  E_RESOURCE_EXHAUSTED。
• 契约
  与《第7章》代价模型一致；发布 TS.* 目标与告警阈值。

XVII. I60-31 set_backpressure —— 背压与限流

• 原型
  I60-31 set_backpressure(PipeRef, bp:dict) -> dict
• 输入
  bp = {queue.max, rate.limit, drop.policy, retry}。
• 输出
  生效配置回显与当前 bp 指标。
• 异常
  E_BACKPRESSURE（超限或策略冲突）。
• 契约
  更改为事务化，期间保持 hb 语义不破坏。

XVIII. I60-60 fit_step —— 拟合单步

• 原型
  I60-60 fit_step(sim_out:any, obs:any, H:any, pri:any, opts:dict) -> dict
• 输出
  {theta.new, loss, grad, cov, TS.*}。
• 契约
  口径对齐：H、单位与时间基须与《第10章》一致。

XIX. I60-65 run_fit_loop —— 拟合回路

• 原型
  I60-65 run_fit_loop(PipeRef, obs:any, H:any, controller:dict) -> FitArtifact
• 输出
  FitArtifact = {theta*, loss_curve, cov, gates}。
• 契约
  记录 Mx-65 运行轨迹；若失败，提供可复现实验入口。

XX. I60-70 compute_error_budget —— 误差预算

• 原型
  I60-70 compute_error_budget(terms:list, rules:dict) -> dict
• 输入
  terms = [{name, mean, var, units}]，rules = {composition, gates}。
• 输出
  {budget, dominant_terms, gate_pass}。
• 契约
  与《第8章》门限与合成规则一致。

XXI. I60-71 check_conservation —— 守恒校核

• 原型
  I60-71 check_conservation(flow:any, rho:any, window:dict) -> dict
• 输出
  {eps_mass, eps_norm, TS.*}。
• 异常
  E_CONSERVATION_FAIL（越过质量门）。

XXII. I60-90 run_benchmark —— 基准运行

• 原型
  I60-90 run_benchmark(PipeRef, suite:list, opts:dict) -> BenchmarkReport
• 输出
  BenchmarkReport = {cases, correctness, stability, SLO, throughput, Score}。
• 契约
  报告字段与《第9章》一致；发布 ReproPack 关联键。

XXIII. I60-91 report_benchmark —— 基准发布

• 原型
  I60-91 report_benchmark(BenchmarkReport, targets:list) -> dict
• 输出
  发布结果与审计链接。
• 异常
  E_STORAGE_IO，E_SCHEMA_MISMATCH。

XXIV. 工具函数（约定实现）

• check_dim(expr) -> bool：单位与量纲校核；失败抛出 E_INVALID_UNITS 或 E_DIM_MISMATCH。
• check_ts_alignment(alpha:float, beta:float) -> bool：校验 ts = alpha + beta * tau_mono。
• window_spec(t0,t1,dt) -> dict：时间窗口规范化。
• spec_path(gamma:list) -> list：路径参数化与支集声明。

XXV. 典型调用序列（伪代码）

1. 启动与耦合
   • PipeRef = I60-8.materialize_pipeline(PipeCard, ParamCard, EnvLock)
   • PipeCard = I60-7.generate_pipeline_card(sim_state, fit, opts)
   • CouplingRef = I60-1.couple_fields(sim_state, kernels, nets, opts)
   • EnvLock = I60-6.freeze_env(env_spec)
2. 时间推进与校准
   • I60-5.emit_metrics(sim_state)
   • 循环 I60-3.advance_dt(...) 并定期 I60-2.exchange_packets(...)
   • CalReport = I60-4.calibrate_arrival_time(trace, paths, c_ref, medium)
3. 守恒与发布
   • I60-91.report_benchmark(BenchmarkReport, targets)
   • ReproPack = I60-11.export_repro_pack(PipeCard, ParamCard, EnvLock, Attest)
   • Attest = I60-9.run_with_attestation(PipeRef, seeds)
   • BenchmarkReport = I60-90.run_benchmark(PipeRef, suite, opts)
   • I60-71.check_conservation(...)

XXVI. 版本与兼容性

1. 版本语义
   • 主版本递增：口径或单位变化、T_arr 两口径定义调整、时间基映射变化。
   • 次版本：参数与默认策略变化但口径不变。
   • 修订号：缺陷修复与非功能性优化。
2. 兼容策略
   I60-* 新增可选参数保持向后兼容；删除或语义改变仅在主版本进行，并提供迁移脚本的 cid。

XXVII. 本附录新增术语与符号（记忆）

• 接口与工件：I60-1..I60-5, I60-6..I60-11, I60-20, I60-21, I60-30, I60-31, I60-60, I60-65, I60-70, I60-71, I60-90, I60-91。
• 报告与卡片：PipeCard，ParamCard，EnvLock，CalReport，StepReport，BenchmarkReport，Attest，ReproPack。
• 关键量与口径：TS.*，eps_norm，eps_mass，cfl，delta_form，H_env，gamma(ell)，T_arr 两口径，U_w，ENBW。