32-EFT.WP.Cosmo.LayeredSea v1.0 | 第10章 实现绑定与 API 规范

目录 ／ 文档-技术白皮书 ／ 32-EFT.WP.Cosmo.LayeredSea v1.0

第10章 实现绑定与 API 规范

I. 一句话目标

一句话目标：把本卷物理口径（SeaProfile，Phi_T/grad_Phi_T，n_eff，层界分段与 Delta_T_sigma，两类 T_arr）绑定为模板 v0.1 接口族一致的可复用 API，规范数据类型、函数原型 I60-*、量纲校验、错误码、日志与复现，使跨项目实现一致、可审计、可重放。

II. 范围与非目标

• 覆盖：接口分层与函数原型（对齐模板接口族并给出 I60-* 建议实现）、数据对象最小字段、参数校验与量纲口径、错误码与异常、并发与可复现、日志与审计、示例工作流与发布口径。
• 非目标：不复述第3–9章的方程与数值细节；不提供装置级硬件实现。

III. 术语与符号最小集

• 层与剖面：SeaProfile，W_k(chi)，Xi_k(chi)，Delta_k，Sigma_sea。
• 场与传播：T_fil(x,t)，Phi_T(x,t)，grad_Phi_T(x,t)，n_eff(x,t,f)。
• 路径与测度：gamma(ell)，d ell，{ ell_i }，分段 gamma_i。
• 口径与修正：T_arr = ( 1 / c_ref ) * ( ∫ n_eff d ell ) 或 T_arr = ( ∫ ( n_eff / c_ref ) d ell )；Delta_T_sigma。
• 能量与事件：R_sea，T_trans，A_sigma（R_sea + T_trans + A_sigma = 1）。
• 命名隔离与约束：T_fil ≠ T_trans；n ≠ n_eff；n_eff ≥ 1。

IV. 接口分层与函数原型（与模板 v0.1接口族对齐，建议 I60-* 实现）

A. 构建与规范（模板：I.Build.*，I.Interface.ApplyMatching）

1. I60-1 build_layered_sea_profile( params ) -> SeaProfile
   • params：层族、chi_k/Delta_k/sigma_k，可选角向系数 a_{lm}^{(k)}，阈值 eta_w,tau_sea。
   • 出参：SeaProfile，含 Sigma_sea 隐式函数/网格与 hash(SeaProfile)。
2. I60-2 apply_sea_matching( Phi_T, SeaProfile ) -> Phi_T_matched
   作用：设定层侧限；与第8章匹配类型一致。
3. gradient( Phi_T ) -> grad_Phi_T（模板同名）

B. 折射率装配（模板：I.Build.Neff）

1. I60-3 estimate_neff_sea( Phi_T, grad_Phi_T, rho, f, SeaProfile ) -> n_eff
   语义：实现 n_eff = F( … ) + H_sea( {W_k, Xi_k}, f )；强制n_eff ∈ [1,n_max] 夹持并记录触发率。

C. 路径、分段与修正（模板：I.Path.*）

• I60-4 detect_sea_intersections( gamma, SeaProfile ) -> { ell_i, layer_id }
• segment_integrals( n_eff, gamma, { ell_i }, mode ) -> { T_arr_i }
• I60-5 interface_correction_sea( gamma, SeaProfile, params ) -> Delta_T_sigma（薄层可选）

D. 到达时与差分（模板：I.Arrival.*）

• I60-6 arrival_time_in_sea( n_eff, gamma, mode, c_ref ) -> T_arr
• I60-7 delta_arrival_in_sea( n_path_params, f1, f2, gamma, mode, c_ref ) -> Delta_T_arr

E. 能量三元组与一致性（模板：I.RT.Estimate，I.Consistency.*）

• I60-8 estimate_RT_sea( data, SeaProfile ) -> R_sea, T_trans, A_sigma
• check_dual_arrival_consistency( inputs ) -> eta_T
• consistency_thin_vs_thick_LS( inputs ) -> tau_report

F. 计量、不确定度与报告（模板：I.Uncertainty.*，I.Report.*）

• propagate_uncertainty_GUM( inputs ) -> u_c / propagate_uncertainty_MC( inputs, Nsamples, seed ) -> dist(T_arr)
• emit_measurement_report( contract, logs, artifacts ) -> Report
• log_artifacts_LS( meta, hashes, metrics ) -> Log

统一约束（全部入口）：执行量纲核查 check_dimension；验证 T_arr ≥ L_path / c_ref 与 R_sea + T_trans + A_sigma = 1；命名隔离为必检项。

V. 数据结构与类型（最小定义）

• Contract：spec_version，coords_spec，units_spec，metric_spec，mode ∈ {constant,general}，tolerances:{eps_T,eta_T,eta_w,tau_switch}，hash(*)。
• SeaProfile：model_k，chi_k，Delta_k，sigma_k，可选 a_{lm}^{(k)}；派生 Sigma_sea 隐式函数/网格与 hash(SeaProfile)。
• Path：path_id，gamma:[…]，Δell:[…]，可选 t_hat:[…]，interface_marks:[idx…]。
• Field：name ∈ {Phi_T, grad_Phi_T, n_eff}，storage ∈ {grid, trajectory}，coords_spec/units_spec。
• NeffParams：a0,a1,a2，可选 u0_k,u1_k,b1,b1_n,c_m，n_min=1,n_max。
• RTParams：R_sea(f), T_trans(f), A_sigma(f) 的带内曲线与夹持区间。
• Report/Log：指标、阈值、否证样本、哈希与环境元数据。

VI. 参数校验与单位/量纲

• 量纲绑定：dim(T_arr)=[T]，dim(c_ref)=[L][T^-1]，dim(d ell)=[L]，dim(n_eff)=1，dim(Delta_T_sigma)=[T]，dim(Xi_k)=[L^-1]。
• 坐标/度规：metric_spec 必填并给出 chi → d ell 映射；入口统一 coords_spec/units_spec。
• 夹持与可行域：n_eff ∈ [1,n_max] 强制；越界直接拒收并登记否证样本。
• 两口径：记录 mode 与选择理由；一般口径需提供 c_ref(x,t,f) 模型与不确定度。

VII. 错误码与异常（与模板错误族对齐）

• E-DIM-001 量纲不一致或单位缺失
• E-GAUGE-002 规范未固定或冲突
• E-NEFF-003 n_eff < 1 或分解失败
• E-PATH-004 路径离散非法或与测度不一致
• E-INTF-005 界面匹配失败或参数越界
• E-QAD-006 求积分段不收敛或 eps_T 未满足
• E-CREF-007 c_ref 标定不可解或不稳定
• E-CONSIST-008 两口径一致性失败（eta_T 超阈）
• E-LS-010 薄/厚层一致性失败或 Delta_T_sigma 与体积分差值超阈
  处理：返回错误对象并保留中间日志与 seed；输出否证样本与回溯建议（口径、分段、SeaProfile、步长）。

VIII. 并发、确定性与可复现

• 确定性：核心流水线尽量纯函数化；MC 需记录 seed 与采样策略。
• 并发：频带与路径可并行；层界局部窗口并行评估；避免共享可变状态。
• 复现：入口记录 hash(SeaProfile), hash(grad_Phi_T), hash(n_eff), hash(gamma), hash(code)；报告含 SolverCfg 与 metric_spec 快照。

IX. 日志与审计（最小字段）

• 运行与环境：时间戳、平台、库版本、spec_version、SolverCfg。
• 物理与几何：hash(SeaProfile), hash(grad_Phi_T), hash(n_eff), hash(gamma)，Sigma_sea 标签与 { ell_i } 公差。
• 口径与阈值：mode，eps_T，eta_T，eta_c，eta_w，tau_switch，下界余量 T_arr − L_path/c_ref。
• 能量与差分：R_sea/T_trans/A_sigma 余量，Delta_T_sigma 触发统计，Delta_T_arr 线性区与带外泄漏比。
• 不确定度与复现：u_stat,u_sys,u_c，k，seed，coords_spec/units_spec/metric_spec，哈希与否证样本清单。

X. 示例工作流（对齐模板接口族）

A. 网格法：从 SeaProfile 到 T_arr(f)

• Phi_T = build_phi_t( T_fil, params_G ) → fix_gauge → apply_sea_matching( Phi_T, SeaProfile )
• grad_Phi_T = gradient( Phi_T )
• n_eff = estimate_neff_sea( Phi_T, grad_Phi_T, rho, f_grid, SeaProfile )
• 每条路径：{ ell_i } = detect_sea_intersections( gamma, SeaProfile )；
  T_arr = segment_integrals( n_eff, gamma, { ell_i }, mode )；若薄层：T_arr += interface_correction_sea( … )
• log_artifacts_LS( … )，emit_measurement_report( … )

B. 参照速度标定与两口径一致性

• c_ref = calibrate_c_ref( gamma_ref, T_arr_ref, n_eff_ref, mode )
• eta_T = check_dual_arrival_consistency( inputs )（阈值内为合格）

C. 多频带差分隔离 path term

• n_common, n_path_params（若需要分解）
• Delta_T_arr = delta_arrival_in_sea( n_path_params, f1, f2, gamma, mode, c_ref )
• 与 Delta_T_arr_obs 对比，更新 NeffParams/SeaProfile

D. 薄/厚层一致性

• 在 eta_w 邻域双算 T_arr^{thin}+Delta_T_sigma 与 T_arr^{thick}
• tau_report = consistency_thin_vs_thick_LS( inputs )（未超阈即通过）

XI. 交叉引用

• 《EFT.WP.Cosmo.LayeredSea v1.0》：第3章（最小方程与层化表述），第4章（几何与坐标），第5章（层结构与参数化），第6章（传播与到达时），第8章（界面匹配），第9章（建模与数值实现），第11章（验证），第12章（误差预算）。
• 模板 v0.1：接口族与 I/O 契约分层。
• 《EFT.WP.Propagation.TensionPotential v1.0》：两口径与差分流程。
• 《EFT.WP.Core.Equations v1.1 / Metrology v1.0 / Errors v1.0》：符号、计量与错误族。

XII. 产出物

• API 参考清单：I60-* 原型、入参/出参、单位与量纲要求、错误码语义（对齐模板 v0.1）。
• 契约模板：Contract/SeaProfile/Path/Field/NeffParams/RTParams/Report 字段规范。
• 审计与复现实例包：示例工作流 A/B/C/D 的日志、哈希与重放清单。