29-EFT.WP.TBN.Measurement v1.0 | 附录A 接口参考（I50 全集）

目录 ／ 文档-技术白皮书 ／ 29-EFT.WP.TBN.Measurement v1.0

附录A 接口参考（I50 全集）

目标：枚举并规范本卷所有实现绑定 I50-* 的函数原型、输入/输出与不变量，确保两口径（解析/配置 vs 观测/实现）并行、量纲校核、RefCond 可追溯、同窗同带宽同单位与清单可回放。

I. 总述与约定

1. 编号与版本
   • 接口统一编号 I50-xx，语义化版本（semver）写入清单（见附录C）。
   • 破坏性变更须升主版，并提供 diff/迁移脚本 与回放兼容策略。
2. 两口径并行（强制）
   任一“评估/发布”接口需同时产出解析/配置口径与观测/实现口径结果，并返回差异 delta_form_* 与阈值 tol_*。
3. 单位/量纲（强制）
   所有数值字段声明 unit(field) 与 dim(field) 并通过 check_dim( y - f(x) )；对数量↔线性（dB↔linear / rad↔cycle）换算写入 meta.scale.note。
4. 测度显式
   • 路径/时间/频率/集合积分须显式：( ∫_{gamma(ell)} · d ell )、( ∫_{t∈W} · dt )、( ∫_{f∈B} · df )、( ∑_{k∈S} · )。
   • 窗/带宽字段必填：window_fn, RBW, ENBW, W=[ts-Δt,ts]。
5. 错误语义
   统一错误码 E50-xxx（见 XVI）；所有函数返回 status ∈ {ok,error} 与 err / evidence_uri。

II. 通用抽象类型

RefCond = {hash, sources:{ephemeris?,gravity?,iono?,trop?,nfield?,segments?,osc?},

frames, tz, Δt, Δx, coverage, valid_from, valid_to}

WindowSpec = {W:[t0,t1], H?, lateness?, watermark?, window_fn}

SpectrumSpec = {RBW, ENBW, band:[fL,fH], window_fn}

TarrForms = {form1, form2, delta_form, tol, unit:"s", dim:"[T]"}

EstCfg = {method∈{PLL,IQ,FFT,Hilbert}, params:{...}}

ManifestURI = {uri, signature, digest}

不变量（全局）：two_forms_present=true；check_dim(*) 通过；RefCond.hash、窗口/带宽与方法参数可追溯。

III. 数学基线与两口径（第2章，I50-2*）

• I50-21 estimate_spectra(raw, Fs, window_fn, RBW|ENBW) -> {S_phi, S_y, meta, status}
  meta：RBW/ENBW/window_fn, scale.note。
• I50-22 allan_stats(y_series, τ_set, overlap?, deadtime?) -> {sigma_y, ν_eff, U, meta, status}
• I50-23 twoform_latency(n_eff, gamma, c_ref) -> {TarrForms, status}
• I50-24 latency_breakdown(link_signals) -> {lat_prop, lat_ser, lat_sw, lat_q, lat_proc, meta, status}
• I50-25 assert_baseline_contracts(ds, rules) -> {report[], pass, status}
• I50-26 emit_baseline_manifest(results, policy) -> {ManifestURI, status}

不变量：同窗同带宽同单位；TarrForms.delta_form ≤ tol_Tarr。

IV. 采集前端与时基（第3章，I50-3*）

• I50-31 acquire_timing(frontends, refs, cfg) -> {raw:{samples,meta}, status}
• I50-32 characterize_jitter(raw, Fs, f_c) -> {t_j_rms, S_tj(f), meta, status}
• I50-33 correct_enbw(spectrum, window_fn) -> {Ŝ(f), ENBW, meta, status}
• I50-34 check_trigger_sync(trig, timestamps) -> {offset, skew, J_model, pass, status}
• I50-35 cross_channel_align(streams) -> {delay, phase, u, pass, status}
• I50-36 frontend_to_twoform_budget(meta) -> {u(delta_form|front-end), report, status}
• I50-37 emit_frontend_manifest(results, policy) -> {ManifestURI, status}

不变量：统一时标 tau_mono；RBW/ENBW/window_fn 落盘；跨通道偏置可追溯。

V. 相位与频偏估计（第4章，I50-4*）

• I50-41 pll_estimate(iq, f_ref, cfg:{ω_n, ζ, B_L}) -> {phi, f_inst, y, crlb, meta, status}
• I50-42 hilbert_instantaneous(x, window_fn, B_smooth) -> {phi, f_inst, y, crlb, meta, status}
• I50-43 fft_cfo_estimate(x, window_fn, N_fft) -> {Δf_hat, var, meta, status} （含 Kay/Quinn-Macleod/Jacobsen 可选后处理）
• I50-44 spectra_from_y(y, window_fn, RBW, ENBW) -> {S_phi, S_y, sigma_y, meta, status}
• I50-45 assert_estimator_contracts(outputs, rules) -> {report[], pass, status}
• I50-46 emit_estimator_manifest(results, policy) -> {ManifestURI, status}

不变量：CRLB/SNR/窗长达标；方法/参数/窗/带宽落盘。

VI. Allan 家族（第5章，I50-5*）

• I50-51 allan_dev(y_series, τ_grid, overlap, deadtime) -> {sigma_y, ν_eff, U, meta, status}
• I50-52 mod_allan_dev(y_series, τ_grid, overlap) -> {mod_sigma_y, ν_eff, U, meta, status}
• I50-53 hadamard_dev(x_series, τ_grid) -> {HDEV, ν_eff, U, meta, status}
• I50-54 tdev_from_mdev(mod_sigma_y, τ_grid) -> {TDEV, meta, status}
• I50-55 allan_from_Sy(S_y, τ_grid, RBW, ENBW, window_fn) -> {sigma_y, meta, status}
• I50-56 fit_powerlaw_noise(sigma_y, τ_grid) -> {h_alpha, slopes, model_fit, status}
• I50-57 assert_allan_contracts(results, rules) -> {report[], pass, status}
• I50-58 emit_allan_manifest(results, policy) -> {ManifestURI, status}

不变量：ν_eff 与置信区间覆盖≥95%；死区/重叠口径声明。

VII. 链路时延与抖动（第6章，I50-6*）

• I50-61 measure_twtt(timestamps, cfg) -> {T_2way, T_1way, ΔT_asym, u, meta, status}
• I50-62 measure_oneway(stamps, sync) -> {T_1way, u, meta, status}
• I50-63 decompose_latency(traces, link_meta) -> {lat_total, lat_prop, lat_ser, lat_sw, lat_q, lat_proc, status}
• I50-64 jitter_spectrum(jitter_ts, RBW, ENBW) -> {S_t(f), σ_t, meta, status}
• I50-65 solve_asymmetry(peer|triangle|loop, evidences) -> {ΔT_asym, u, meta, status}
• I50-66 twoform_consistency(n_eff, gamma, c_ref) -> {TarrForms, status}
• I50-67 assert_delay_contracts(ds, rules) -> {report[], pass, status}
• I50-68 emit_delay_manifest(results, policy) -> {ManifestURI, status}

不变量：两口径与对齐门达标；对称性假设/锚定证据 URI 落盘。

VIII. 路径与环境修正绑定（第7章，I50-7*）

• I50-71 model_troposphere(met, elev, model) -> {ΔT_trop, meta, status}
• I50-72 model_ionosphere(TEC, f, mapping) -> {ΔT_iono, meta, status}
• I50-73 model_fiber(temp/press/hum, segments) -> {ΔT_fiber, meta, status}
• I50-74 estimate_multipath(obs, geom, method) -> {ΔT_mpath, MER, MP_res, tags, status}
• I50-75 compose_corr_env(parts) -> {ΔT_med, T_arr_star, TarrForms, status}
• I50-76 assert_corr_contracts(ds, rules) -> {report[], pass, status}
• I50-77 emit_corr_manifest(results, policy) -> {ManifestURI, status}

不变量：源新鲜度/覆盖；相/群映射与 ΔT_map 及 u(ΔT_map) 落盘。

IX. 仪器与处理链计量（第8章，I50-8*）

• I50-81 loopback_delay(stamps|correl, cfg) -> {τ_loop, ΔT_inst_plus_proc, ΔT_asym?, u, meta, status}
• I50-82 peer_delays(pairs:{τ_AB,τ_BA}, cfg) -> {T_1way, ΔT_asym, u, meta, status}
• I50-83 triangle_delays(pairs:{τ_AB,τ_BC,τ_CA}, cfg) -> {ΔT_asym, u, meta, status}
• I50-84 inst_decompose(total, priors) -> {components:{frontend,codec,fpga,serdes,filter,connector,buffer,stack}, u, meta, status}
• I50-85 jitter_psd(traces, RBW, ENBW) -> {S_t(f), σ_t, meta, status}
• I50-86 inst_to_twoform_consistency(n_eff, gamma, c_ref) -> {TarrForms, status}
• I50-87 assert_inst_contracts(ds, rules) -> {report[], pass, status}
• I50-88 emit_inst_manifest(results, policy) -> {ManifestURI, status}

不变量：组件/固件/端口拓扑 hash 可追溯；证据可回放。

X. 频谱与时域一致（第9章，I50-9*）

• I50-91 spectrum_to_jitter(S_phi|S_y, f_c, RBW, ENBW, band) -> {σ_φ, σ_t, S_t(f), meta, status}
• I50-92 jitter_to_eye(σ_t, T_sym, margin_ISI, k_β) -> {t_open, t_jit_margin, meta, status}
• I50-93 jitter_to_evm(σ_t, f_c, κ_mod) -> {EVM_pred, SNR_j, meta, status}
• I50-94 evm_consistency(EVM_pred, EVM_meas, method) -> {resid_evm, pass, status}
• I50-95 assert_consistency_contracts(ds, rules) -> {report[], pass, status}
• I50-96 emit_consistency_manifest(results, policy) -> {ManifestURI, status}

不变量：同窗/同带宽/同单位；调制映射常数、噪声型与判决阈值落盘。

XI. 解析 vs 观测 vs 锚/回放（第10章, I50-10*）

• I50-101 align_pred_meas(pred, meas) -> {aligned, meta, status}
• I50-102 residuals(pred, meas) -> {resid_*, u(resid), pass, status}
• I50-103 apply_anchor(meas, anchor) -> {meas_cal, params, u, status}
• I50-104 build_replay_core(pred, meas, RefCond, scripts) -> {replay.core, status}
• I50-105 assert_anchor_contracts(ds, rules) -> {report[], pass, status}
• I50-106 emit_anchor_manifest(results, policy) -> {ManifestURI, status}

不变量：锚/回放证据 URI 与脚本哈希；同窗同带宽同单位。

XII. 不确定度与 guardband（第11章, I50-11*）

• I50-111 build_sensitivity(models, gamma, RefCond) -> {J_z, J_T, meta, status}
• I50-112 propagate_gum(J, V_ξ, constraints) -> {u_c, nu_eff, U, status}
• I50-113 propagate_mc(sampler, N, α, η, constraints) -> {stats, U, ρ, status}
• I50-114 compose_twoform_uncert(T_form1, T_form2, cov) -> {u(delta_form), status}
• I50-115 map_uncert_phase_group(n_phi, n_g, band, z_phi_series) -> {u(ΔT_map), method, status}
• I50-116 design_guardband(metrics_u, drift_score, policy) -> {gb, gb', actions, status}
• I50-117 assert_uncert_contracts(u_report, rules) -> {report[], pass, status}
• I50-118 emit_uncert_manifest(results, policy) -> {ManifestURI, status}

不变量：GUM/MC 一致性 ρ 落盘；约束投影后再发布 U/gB。

XIII. 契约与策略卡（第12章, I50-12*）

• I50-121 evaluate_quality(ds, rules) -> {metrics.Q, report[], pass, status}
• I50-122 evaluate_integrity(ds, rules) -> {metrics.Int, report[], pass, status}
• I50-123 evaluate_security(ds, rules) -> {metrics.Sec, report[], pass, status}
• I50-124 plan_guardband(metrics, u, risk) -> {gb_updates, policy, status}
• I50-125 run_strategy_cards(cards, context) -> {actions[], verify, status}
• I50-126 assert_tbn_contracts(reports, rules) -> {pass, summary, status}
• I50-127 emit_contract_manifest(results, policy) -> {ManifestURI, status}

不变量：Fail-Closed 可回放；策略卡动作与验证记录完整。

XIV. 运行时与流式、端到端（第13–15章, I50-13*, I50-15*）

• I50-131 plan_stream_windows(W, H, lateness, watermark) -> {schedule, status}
• I50-132 query_or_compute(cache, K_cache, fn) -> {value, hit, stale, status}
• I50-133 measure_runtime(stream) -> {latency, drop_rate, ρ, cpu_pct, mem_pct, watermark_lag, status}
• I50-134 compare_dual_runtime(cfg_metrics, meas_metrics) -> {delta_form_rt_T, ΔT_obs_p95, resid_Sy_p95, status}
• I50-135 apply_fallback(mode, ctx) -> {actions[], status}
• I50-136 snapshot_panel(metrics, resources, U) -> {panel.uri, snapshot.hash, status}
• I50-137 emit_runtime_manifest(results, policy) -> {ManifestURI, status}
• I50-151 build_usecase(profile) -> {graph, sources.hashes, RefCond, thresholds, status}
• I50-152 run_pipeline(profile, inputs) -> {manifests[], panels[], kpis, status}
• I50-153 validate_end2end(manifests, kpis, rules) -> {report, pass, status}
• I50-154 publish_end2end(manifests, report) -> {ManifestURI, status}
• I50-155 rollback_end2end(manifest_uri, reason) -> {status}

不变量：schedule 单调；缓存键含 RefCond/hash 与 algo.hash；清单签名链可验；回退可回放。

XV. 不变量与公共前置条件（汇总）

• 两口径：凡涉 T_arr 的接口均返回 TarrForms 并断言 delta_form ≤ tol_Tarr。
• 同窗/同带宽/同单位：谱/统计/时域量测与比较必须对齐 W/RBW/ENBW/window_fn/units。
• 追溯：RefCond.hash、模型/脚本/固件 hash 与版本必填；证据 URI 可复取与验签。
• 量纲：所有返回值附 unit/dim。
• 回放：关键发布接口同时产出 replay.core 或引用其 URI。

XVI. 错误码与语义（E50-xxx）

• E50-001 InvalidDim：量纲/单位不匹配（check_dim 失败）。
• E50-002 TwoFormMismatch：两口径差超阈（delta_form_* > tol_*）。
• E50-003 InconsistentWindow/Bandwidth：W/RBW/ENBW/window_fn 不一致。
• E50-004 StaleSource/LowCoverage：来源过期或覆盖不足。
• E50-005 ContractViolation：任一 C50-* 未通过。
• E50-006 CRLB/SNR Guard Breach：观测不满足分辨率或 SNR 下界。
• E50-007 RaySolveFail/InterfaceInconsistent：路径/接口求解失败（若引用 PathCorrection）。
• E50-008 GUMvsMCMismatch：ρ 超容忍区间。
• E50-009 ManifestInvalid/InvalidSignature：清单缺键或验签失败。
• E50-010 SerializationError/DeserializationError。
• E50-011 NotTraceable：缺失 hash/id/RefCond 追溯信息。

XVII. 版本与兼容

• 次版本升级不得改变已存在参数名/默认值；新增字段须可选并记录于 manifest.changelog。
• **规范化（canonicalize）**用于签名/对比（见附录C）；跨版本提供 diff/迁移脚本 与回放兼容策略。

XVIII. 交叉引用

• 章节：第2–15章 P/S/M/C 为本附录接口语义基础。
• 清单：附录C（manifest.tbn.*）；契约：附录B；指标/漂移：附录D；不确定度：附录E。
• 配套卷：TimeBase/Sync（对时）、PathCorrection/Packets/PathRedshift（路径/介质/FSO/世界线）、Instrument（设备计量）、Methods.Cleaning（清洗与发布约定）。

小结

• 本附录给出 I50-* 全集的原型/约束/错误语义：两口径并行、量纲合规、RefCond 可追溯、同窗同带宽同单位、清单与回放是所有实现的刚性要求；
• 结合各章 M50-* 流程与附录C 清单，工程团队可据此实现从采集到运行发布的端到端、可复现、可审计、可回退的 TBN.Measurement 管线。