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

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

第10章 实现绑定与 API 规范

I. 一句话目标

一句话目标：将本卷物理口径（Catalog/Seeds/Trajectory，Phi_T/grad_Phi_T，L_nu/LC，n_eff，分段与 Delta_T_sigma，两类 T_arr/Delta_T_arr）绑定为与模板 v0.1接口族一致的可复用 API，规范 I70-* 原型、数据对象、量纲校验、错误码、日志与复现，使跨团队实现一致、可审计、可重放。

II. 范围与非目标

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

III. 术语与符号最小集

1. 对象与状态：Catalog，Seeds，Trajectory；state = { M, R, J, a_bh, SFR, Z, … }。
2. 场与环境：T_fil(x,t)，Phi_T(x,t)=G(T_fil)，grad_Phi_T(x,t)；SeaProfile/Sigma_env。
3. 传播与口径：n_eff(x,t,f)（无量纲，且 n_eff ≥ 1），c_ref，gamma(ell)，d ell，端点 { ell_i }；
   • 常量外提：T_arr = (1/c_ref) * ( ∫ n_eff d ell )
   • 一般口径：T_arr = ( ∫ ( n_eff / c_ref ) d ell )
4. 能量一致与命名隔离：R_env + T_trans + A_sigma = 1；T_fil ≠ T_trans，n ≠ n_eff。

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

A. 目录/成因/演化（模板：I.Build.*）

• I70-1 build_early_object_catalog( params ) -> Catalog
  生成对象清单、类型、z_form/z_obs、环境引用与哈希。
• I70-2 seed_and_trigger( Phi_T, env, priors ) -> Seeds
  依据先验与环境字段采样 seed 并生成触发过程句柄（支持非齐次泊松）。
• I70-3 evolve_object_state( O, env, tgrid ) -> Trajectory
  数值推进 S70-7…S70-10，在事件时间应用 Trigger。

B. 辐射与传播（模板：I.Build.*，I.Arrival.*）

• I70-4 synthesize_spectrum( O, state, fgrid ) -> L_nu
• I70-5 couple_to_sea( O, SeaProfile, params ) -> EnvCoupled（可选，与 LayeredSea 对接）
• I70-6 predict_arrival_signature( n_eff, gamma, mode, c_ref ) -> { T_arr, Delta_T_arr }
  mode ∈ {constant, general}；分段与 Delta_T_sigma 在入口传入或在 n_eff 装配层处理。

C. 界面与能量（模板：I.Interface.*，I.RT.Estimate）

• detect_interfaces( gamma, Sigma_env or SeaProfile ) -> { ell_i, labels }
• interface_correction_sea( gamma, SeaProfile, params ) -> Delta_T_sigma（薄层可选）
• I70-7 estimate_energy_triplet( data, Sigma_env ) -> { R_env, T_trans, A_sigma }

D. 计量/一致性/不确定度（模板：I.Consistency.*，I.Uncertainty.*）

• check_dual_arrival_consistency( inputs ) -> eta_T
• consistency_thin_vs_thick_EO( inputs ) -> tau_report
• propagate_uncertainty_GUM( inputs ) -> u_c / propagate_uncertainty_MC( inputs, Nsamples, seed ) -> dist

E. 报告与日志（模板：I.Report.*）

• emit_measurement_report( contract, logs, artifacts ) -> Report
• log_artifacts_EO( meta, hashes, metrics ) -> Log

统一约束（所有入口）：量纲核查 check_dimension；验证 T_arr ≥ L_path / c_ref 与 R_env + T_trans + A_sigma = 1；命名隔离为必检项；分段端点 { ell_i } 显式入积，禁止跨界面插值。

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

• Contract：spec_version，coords_spec，units_spec，metric_spec，mode，tolerances:{eps_T,eta_T,eta_w,tau_switch}，hash(*)，SolverCfg，seed。
• Catalog：{ id, type, z_form, z_obs, env_ref, seed_ref }，hash(Catalog)。
• Seeds/Triggers：priors、样本与 seed_rng、触发事件集与时间戳、hash(Seeds)。
• Trajectory：时间序列 state(t) 与事件日志、hash(Trajectory)。
• Field：name ∈ {Phi_T, grad_Phi_T, n_eff}，storage ∈ {grid, trajectory}，coords_spec/units_spec。
• SeaProfile/Interfaces：层参数、Sigma_env 标签、{ ell_i } 公差、hash(SeaProfile)。
• Spectral/Obs：L_nu(f)，F_nu(f)，LC(t)，T_arr/Delta_T_arr 与不确定度。
• RTParams：R_env(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(L_nu) 与 dim(F_nu) 在契约中声明。
• 坐标/度规：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-EO-010 薄/厚层一致性失败或 Delta_T_sigma 与体积分差值超阈
  处理：返回错误对象保留中间日志与 seed；输出否证样本与回溯建议（口径、分段、SeaProfile、步长）。

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

• 确定性：核心流水线尽量纯函数；MC 记录 seed、采样策略与哈希。
• 并发：对象 × 频带 × 路径维度并行；层界局部窗口并行评估；避免共享可变状态。
• 复现：入口记录 hash(Catalog/Seeds/Trajectory/SeaProfile/Phi_T/n_eff/gamma/code)；报告含 SolverCfg 与 metric_spec 快照。

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

• 运行环境：时间戳、平台、库版本、spec_version、SolverCfg。
• 物理与几何：hash(Catalog/Seeds/Trajectory/SeaProfile/Phi_T/n_eff/gamma)，Sigma_env 标签与 { ell_i } 公差。
• 口径与阈值：mode，eps_T，eta_T，eta_c，eta_w，tau_switch，下界余量 T_arr − L_path/c_ref。
• 能量与差分：R_env/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. 目录→成因→演化→谱→传播（端到端）

• Catalog = build_early_object_catalog(params)
• Seeds = seed_and_trigger(Phi_T, env, priors)
• Trajectory = evolve_object_state(O, env, tgrid)
• L_nu = synthesize_spectrum(O, state, fgrid)
• T_arr, Delta_T_arr = predict_arrival_signature(n_eff, gamma, mode, c_ref)
• emit_measurement_report( … )（含 eta_T、tau_switch、能量一致与下界审计）

B. 界面与能量一致

• ell_i = detect_interfaces(gamma, Sigma_env or SeaProfile)
• T_arr = segment_integrals( n_eff, gamma, { ell_i }, mode ) [+ Delta_T_sigma]
• { R_env, T_trans, A_sigma } = estimate_energy_triplet(data, Sigma_env)
• log_artifacts_EO( … )

C. 不确定度与一致性

• u_c = propagate_uncertainty_GUM(inputs) / dist = propagate_uncertainty_MC(inputs, Nsamples, seed)
• eta_T = check_dual_arrival_consistency(inputs)
• tau_report = consistency_thin_vs_thick_EO(inputs)

XI. 交叉引用

• 《EFT.WP.Cosmo.EarlyObjects v1.0》：第3章（最小方程），第4章（seed/trigger），第5章（耦合与生长律），第6章（辐射与传播），第7章（计量），第9章（数值实现），第11章（验证），第12章（误差预算）。
• 模板 v0.1：接口族与 I/O 契约分层。
• 《EFT.WP.Cosmo.LayeredSea v1.0》：分段、匹配与一致性。
• 《EFT.WP.Propagation.TensionPotential v1.0》：两口径、差分、路径规范。
• 《EFT.WP.Core.*》：Equations/Metrology/Errors。

XII. 产出物

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