29-EFT.WP.TBN.Measurement v1.0 | Appendix A Interface Reference (I50 Full Set)

Home ／ Docs-Technical WhitePaper ／ 29-EFT.WP.TBN.Measurement v1.0

Appendix A Interface Reference (I50 Full Set)

• Objective: Enumerate and normalize every implementation binding I50-* in this volume—function prototypes, inputs/outputs, and invariants—so that the two forms (analytical/configuration vs observational/implementation) run in parallel; dimensional analysis is enforced; RefCond is traceable; window/bandwidth/units are aligned; and manifests are replayable.
• I. Overview & Conventions
• Numbering & Versioning
• Interfaces use unified IDs I50-xx. Semantic versioning (semver) is written into the manifest (see Appendix C).
• Breaking changes must bump the major version and ship both a diff/migration script and a replay-compatibility strategy.
• Two Forms in Parallel (mandatory)
• Any “evaluate/publish” interface must output both the analytical/configuration form and the observational/implementation form, and return delta_form_* with thresholds tol_*.
• Units / Dimensions (mandatory)
• Every numeric field declares unit(field) and dim(field) and must pass check_dim( y - f(x) ). Conversions between quantity↔linear (e.g., dB↔linear / rad↔cycle) are recorded in meta.scale.note.
• Explicit Measures
• Path/time/frequency/set integrals must be explicit: ( ∫_{gamma(ell)} · d ell ), ( ∫_{t∈W} · dt ), ( ∫_{f∈B} · df ), ( ∑_{k∈S} · ).
• Window/bandwidth fields are mandatory: window_fn, RBW, ENBW, W=[ts-Δt, ts].
• Error Semantics
• Unified error codes E50-xxx (see XVI). All functions return status ∈ {ok, error} with err / evidence_uri.
• II. Common Abstract Types
• 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}
• Invariants (global): two_forms_present = true; all check_dim(*) pass; RefCond.hash plus window/bandwidth and method parameters are traceable.
• III. Mathematical Baseline & Two-Form (Ch.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}
• Invariant: window/bandwidth/units aligned; TarrForms.delta_form ≤ tol_Tarr.
• IV. Front-Ends & Timebase (Ch.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}
• Invariant: unified time scale tau_mono; RBW/ENBW/window_fn persisted; inter-channel biases traceable.
• V. Phase & CFO Estimation (Ch.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 optional post-processing)
• 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}
• Invariant: CRLB/SNR/window length satisfied; method/params/window/bandwidth persisted.
• VI. Allan Family (Ch.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}
• Invariant: ν_eff and CI coverage ≥ 95%; deadtime/overlap conventions declared.
• VII. Link Delay & Jitter (Ch.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}
• Invariant: two-form and alignment gates satisfied; symmetry assumptions / anchor evidence URIs persisted.
• VIII. Path & Environmental Corrections (Ch.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}
• Invariant: source freshness/coverage tracked; phase/group mapping with ΔT_map and u(ΔT_map) persisted.
• IX. Instrument & Processing-Chain Metrology (Ch.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}
• Invariant: component/firmware/port topology hashes are traceable; evidence is replayable.
• X. Spectrum ↔ Time-Domain Consistency (Ch.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}
• Invariant: same window/bandwidth/units; modulation mapping constants, noise types, and decision thresholds persisted.
• XI. Analytics vs Measurement vs Anchor/Replay (Ch.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}
• Invariant: anchor/replay evidence URIs and script hashes recorded; windows/bandwidth/units aligned.
• XII. Uncertainty & Guardband (Ch.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}
• Invariant: GUM vs MC consistency ρ persisted; publish U/gB only after constraint projection.
• XIII. Contracts & Strategy Cards (Ch.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}
• Invariant: fail-closed is replayable; strategy-card actions and verification logs are complete.
• XIV. Runtime & Streaming, End-to-End (Ch.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}
• Invariant: schedule is monotone; cache keys include RefCond/hash and algo.hash; manifest signature chains verifiable; rollbacks are replayable.
• XV. Invariants & Common Preconditions (Summary)
• Two Forms: any interface touching T_arr returns TarrForms and asserts delta_form ≤ tol_Tarr.
• Same Window/Bandwidth/Units: spectral/statistical/time-domain measurements and comparisons must align on W/RBW/ENBW/window_fn/units.
• Traceability: RefCond.hash, model/script/firmware hashes and versions are mandatory; evidence URIs must be retrievable and verifiable.
• Dimensions: all return values carry unit/dim.
• Replay: key publishing interfaces also emit replay.core or a URI thereto.
• XVI. Error Codes & Semantics (E50-xxx)
• E50-001 InvalidDim — Units/dimensions mismatch (check_dim failed).
• E50-002 TwoFormMismatch — Two-form delta exceeds threshold (delta_form_* > tol_*).
• E50-003 InconsistentWindow/Bandwidth — W/RBW/ENBW/window_fn inconsistent.
• E50-004 StaleSource/LowCoverage — Sources expired or insufficient coverage.
• E50-005 ContractViolation — Any C50-* failed.
• E50-006 CRLB/SNR Guard Breach — Observation does not meet resolution or SNR lower bounds.
• E50-007 RaySolveFail/InterfaceInconsistent — Path/interface solve failed (if PathCorrection is referenced).
• E50-008 GUMvsMCMismatch — Consistency ρ out of tolerance.
• E50-009 ManifestInvalid/InvalidSignature — Manifest missing keys or signature verification failed.
• E50-010 SerializationError/DeserializationError.
• E50-011 NotTraceable — Missing hash/id/RefCond traceability info.
• XVII. Versioning & Compatibility
• Minor releases must not change existing parameter names/defaults; newly added fields must be optional and recorded in manifest.changelog.
• Canonicalization is required for signing/comparison (see Appendix C). Provide cross-version diff/migration scripts and a replay-compatibility strategy.
• XVIII. Cross-References
• Chapters: Ch.2–15 P/S/M/C define the semantics underlying this appendix’s interfaces.
• Manifests: Appendix C (manifest.tbn.*); Contracts: Appendix B; Metrics/Drift: Appendix D; Uncertainty: Appendix E.
• Companion Volumes: TimeBase/Sync (time sync), PathCorrection/Packets/PathRedshift (path/media/FSO/worldlines), Instrument (instrument metrology), Methods.Cleaning (cleaning & publishing conventions).
• Summary
• This appendix provides the complete I50-* prototypes, constraints, and error semantics: dual-form parity, dimensional compliance, RefCond traceability, aligned window/bandwidth/units, and mandatory manifests & replay.
• Together with chapter-level M50-* flows and Appendix C manifests, engineering teams can implement an end-to-end, reproducible, auditable, and rollback-capable TBN.Measurement pipeline—from acquisition to runtime publication.