31-EFT.WP.BH.TensionWall v1.0 | 第10章 实现绑定与 API 规范

目录 ／ 文档-技术白皮书 ／ 31-EFT.WP.BH.TensionWall v1.0

第10章 实现绑定与 API 规范

I. 一句话目标

一句话目标：将本卷物理口径（Phi_T，n_eff，Sigma_TW，Delta_T_sigma，两类到达时）绑定为可复用、可审计、可追溯的 API，规范数据类型、函数原型、契约对象与日志字段，确保跨项目一致性与工程落地。

II. 范围与非目标

• 覆盖内容：接口分层、数据类型、函数原型全集 I40-*、单位与量纲核查、错误码、并发与可复现、日志与审计、示例工作流。
• 非目标：不复述第3–9章的物理推导与数值细节；不提供装置级硬件设计。

III. 术语与符号最小集

• 场与势：T_fil(x,t)，Phi_T(x,t)，grad_Phi_T(x,t)。
• 壁与剖面：Sigma_TW，r_H，Delta_w，W(r)，Xi_TW(r)，TWProfile。
• 传播与速度：n_eff(x,t,f)，c_ref，c_loc = c_ref / n_eff。
• 路径与测度：gamma(ell)，d ell，分段 gamma_i，交点 { ell_i }。
• 口径与修正：T_arr = ( 1 / c_ref ) * ( ∫ n_eff d ell ) 或 T_arr = ( ∫ ( n_eff / c_ref ) d ell )，Delta_T_sigma。
• 能量三元组：R_TW，T_trans，A_sigma，R_TW + T_trans + A_sigma = 1。
• 约束：n_eff ≥ 1；严禁将 T_fil 与 T_trans 混用，n 与 n_eff 混用。

IV. 设计原则与契约（Contract）

1. 不变与可复现
   纯函数优先；输入不可变；所有随机过程可播种；输出与日志含哈希。
2. 量纲一致
   入口强制 check_dimension，保证 dim(T_arr) = [T]，dim(n_eff) = 1，dim(c_loc) = [L][T^-1]。
3. 规范与边界显式
   固定 Phi_T(x_ref,t_ref) = 0 与 boundary_config；Sigma_TW 与 { ell_i } 以显式字段落盘。
4. Contract 最小字段
   • id，spec_version
   • coords_spec，units_spec
   • mode ∈ {constant, general}
   • n_eff_dependencies（如 F(Phi_T, grad_Phi_T, rho, f)）
   • gauge:{x_ref,t_ref}，boundary_config
   • Sigma_TW_meta，hash(TWProfile)
   • tolerances:{eps_T, eta_T, eta_w, tau_switch}
   • guardband，uncertainty_method ∈ {GUM, MC, both}
   • hashes:{hash(Phi_T), hash(grad_Phi_T), hash(n_eff), hash(gamma), hash(code)}
   • seed，random_policy

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

• TWProfile：model，r_H/r_H(theta,phi)，Delta_w/Delta_w(theta,phi)，sigma_w，样条或系数，eta_w，派生句柄 Xi_TW(r)，Sigma_TW 隐式函数或网格近似。
• Path：path_id，gamma:[…]，Δell:[…]，可选 t_hat:[…]，interface_marks:[idx…]。
• Field：name ∈ {Phi_T, grad_Phi_T, n_eff}，storage ∈ {grid, trajectory}，坐标与单位说明。
• NeffParams：a0,a1,a2,b1,b1_sigma,c_m{…}，n_min=1，n_max。
• RTParams：R_TW(f)，T_trans(f)，A_sigma(f) 的带内曲线与夹持区间。
• SolverCfg：求积法、步长策略、阈值集合（tau_geom,tau_medium,tau_wall）、收敛准则、并行与缓存策略。
• Report/Log：指标、阈值、否证样本、哈希与环境元数据。

VI. 接口分层与函数原型（I 层全集，分组列举）

A. 构建与规范（I40-1…I40-6）

• build_tension_wall_profile( M_bh, a_bh, params ) -> TWProfile
• apply_TW_matching( Phi_T, TWProfile ) -> Phi_T_matched
• gradient( Phi_T ) -> grad_Phi_T
• estimate_neff_TW( Phi_T, grad_Phi_T, rho, f, TWProfile ) -> n_eff
• find_turning_points( gamma, TWProfile ) -> { ell_turn }
• declare_tw_contract( coords_spec, units_spec, gauge, boundary_config ) -> Contract

B. 路径、界面与分段（I40-7…I40-15）

• capture_path( raw_track, coord_spec ) -> { gamma[k], Δell[k], t_hat[k] }
• detect_TW_intersections( gamma, TWProfile ) -> { ell_i }
• compute_normals( Sigma_TW, at_points ) -> { n_vec }
• segment_integrals( n_eff, gamma, { ell_i }, mode ) -> { T_arr_i }
• interface_correction( gamma, Sigma_TW, params ) -> Delta_T_sigma
• reparameterize_by_arclength( gamma_raw ) -> gamma(ell)
• project_directionals( grad_Phi_T, t_hat, n_vec ) -> { dot_t, dot_n }
• arrival_time_with_TW( n_eff, gamma, Sigma_TW, mode, c_ref ) -> T_arr
• delta_arrival_TW( n_path_params, f1, f2, gamma, mode, c_ref ) -> ΔT_arr

C. 标定、反演与一致性（I40-16…I40-28）

• calibrate_c_ref( gamma_ref, T_arr_ref, n_eff_ref, mode ) -> c_ref
• estimate_RT_TW( data, TWProfile ) -> R_TW, T_trans, A_sigma
• fit_TW_profile( observations, Phi_T, grad_Phi_T, prior, model_spec ) -> theta_hat, Cov
• check_dual_arrival_consistency( inputs ) -> eta_T
• check_dimension( expr ) -> DimReport
• propagate_uncertainty_GUM( inputs ) -> u_c
• propagate_uncertainty_MC( inputs, Nsamples, seed ) -> dist(T_arr)
• consistency_thin_vs_thick_TW( inputs ) -> tau_report
• rt_estimator_TW( data ) -> RTParams
• emit_measurement_report( contract, logs, artifacts ) -> Report
• log_tw_propagation( meta, hashes, metrics ) -> Log
• log_TW_interface( meta, hashes, metrics ) -> Log

D. 建模、基准与审计（I40-29…I40-46）

• build_solver_config_TW( params ) -> SolverCfg
• solve_phi_grid_TW( T_fil, params_G, TWProfile ) -> Phi_T, grad_Phi_T
• estimate_neff_TW( … ) -> n_eff（同上，允许批量频带）
• simulate_multipath_TW( n_eff, gamma, TWProfile, mode ) -> { T_arr_m, w_m }
• benchmark_suite_TW( runlist ) -> Summary
• convergence_scan( problem, cfg_list ) -> Report
• log_artifacts_TW( meta, hashes, metrics ) -> Log
• ensure_units_and_coords( contract, objects… ) -> DimReport

约束（所有 I40- 入口通用）*

• 强制量纲核查与单位一致；检查 n_eff ∈ [1, n_max]；分段端点显式纳入；能量一致 R_TW + T_trans + A_sigma = 1 为必检项。

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

• 单位核查：长度 m，时间 s，速度 m·s^-1，频率 Hz；离散路径 Δell[k] 与 c_ref 单位一致。
• 量纲绑定：dim(c_ref)=[L][T^-1]，dim(n_eff)=1，dim(d ell)=[L]，dim(T_arr)=[T]。
• 夹持规则：n_eff ∈ [1, n_max]，触发率入日志；触发过高需回溯建模与数据质量。
• 选择口径：记录 mode ∈ {constant, general}、eta_c 与选择理由；一般口径需给出 c_ref(x,t,f) 的估计与不确定度。

VIII. 错误码与异常（最小集）

• 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-TW-010：薄厚壁一致性失败或 Delta_T_sigma 与体积分差值超阈
  处理：返回错误对象并保留中间日志与 seed；输出否证样本与回溯建议。

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

• 确定性：核心流水线纯函数化；MC 唯一影响随机路径，需记录 seed 与采样策略。
• 并发：频带、路径与局部壁窗口均可并行；避免共享可变状态；缓存以只读句柄传递。
• 复现：所有入口记录 hash(Phi_T), hash(grad_Phi_T), hash(n_eff), hash(gamma), hash(code)；报告含 SolverCfg 快照与坐标/单位契约。

X. 安全、完整性与命名隔离

• 完整性：接口不依赖外部网络；输入输出严格校验与哈希签名可选启用。
• 命名隔离：T_trans 仅指界面透射系数，不得与张力或其他量混用；n 与 n_eff 严格区分。
• 数据最小化：日志仅记录必要元数据，避免泄露敏感路径与系统信息。

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

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

XII. 示例工作流（可直接落地）

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

1. Phi_T = apply_TW_matching( fix_gauge( build_phi_t(T_fil, params_G ), x_ref, t_ref ), TWProfile )
2. grad_Phi_T = gradient( Phi_T )
3. n_eff = estimate_neff_TW( Phi_T, grad_Phi_T, rho, f_grid, TWProfile )
4. 对每条路径：{ ell_i } = detect_TW_intersections( gamma, TWProfile )
   • T_arr = segment_integrals( n_eff, gamma, { ell_i }, mode )
   • 若薄壁：T_arr += interface_correction( gamma, Sigma_TW, params )
5. log_tw_propagation( … )，emit_measurement_report( … )

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

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

C. 多频带差分隔离 path term

• n_common, n_path_params = decompose_n_eff( n_eff, f_grid )（若采用）
• ΔT_arr = delta_arrival_TW( n_path_params, f1, f2, gamma, mode, c_ref )
• 对比观测差分并更新 NeffParams 或 TWProfile

D. 薄壁与厚壁一致性

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

XIII. 交叉引用

• 《EFT.WP.BH.TensionWall v1.0》第3章（最小方程与结构模型），第4章（几何与坐标），第5章（壁的构建与参数化），第6章（壁附近传播口径），第7章（计量与可观测量设计），第8章（界面匹配），第9章（建模方法与数值实现），第11章（验证与对标），第12章（误差预算）。
• 《EFT.WP.Propagation.TensionPotential v1.0》I 层通用接口与日志规范。
• 《EFT.WP.Core.Equations v1.1》S06-；《EFT.WP.Core.Metrology v1.0》M05-，M10-；《EFT.WP.Core.Errors v1.0》M20-。

XIV. 产出物

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