20-EFT.WP.Metrology.TimeBase v1.0 | Appendix A — Interface Reference (I50 Full Set)

Home ／ Docs-Technical WhitePaper ／ 20-EFT.WP.Metrology.TimeBase v1.0

Appendix A — Interface Reference (I50 Full Set)

One-line objective: Define the complete I50-* interface suite for time-base metrology and synchronization, including signatures, parameter semantics, returns, errors, and invariants—so that systems can be assembled and audited on an execution graph G=(V,E).

I. Conventions & Types

1. Unified vocabulary
   • Inline symbols use backticks: tau_mono, ts, offset, skew, J, adev/mdev/hdev, T_arr, delta_form, gamma(ell).
   • Dual-form arrival must always be recorded in parallel:
     T_arr = ( 1 / c_ref ) * ( ∫ n_eff d ell ) and T_arr = ( ∫ ( n_eff / c_ref ) d ell ); persist delta_form.
   • Units/dimensions must be checkable: unit(x), dim(x), check_dim(expr).
2. Returns & errors
   • All returns are records/structs with ok ∈ {0,1}, code, msg, TraceID.
   • Failures are non-mutating; every mutating interface must be idempotent with duplicate-ingest protection.
3. Time bases
   Estimation on tau_mono, publication on ts; include offset/skew/J and uncertainty U at publication.

II. Core Data Structures (Minimal Constraints)

• ClockSpec = { id, class ∈ {TCXO, OCXO, Rb, GNSS}, Allan = {sigma(τ)}, holdover, unit, dim }
• SyncConfig = { ptp, ntp, synce, servo, windows, tol_* }
• LatencyTrace = { hops[], t_in, t_out, phy, queuing, ts_adj }
• ArrivalPath = { gamma(ell), n_eff(ell), c_ref, L_gamma }
• TimeSeries<field> = { ts, tau_mono, value, u(value) }
• Manifest.time = { topology, sources, contracts, sli, slo, T_arr.*, signature }

III. Interface Catalog (by Function Group)

1. Basics & Registration — I50-1x
   • I50-11 register_topology(topology) -> {topology_id}
   • I50-12 register_clock(spec: ClockSpec) -> {clock_id}
   • I50-13 freeze_release_time(tag) -> manifest.time
   • I50-14 evaluate_slo(sli, targets) -> report.slo
2. Time-Base Mapping & Normalization — I50-2x
   • I50-21 map_to_tau(ds) -> ds'
   • I50-22 publish_ts(ds, policy) -> ds'
   • I50-23 standardize_time_fields(ds, registry) -> ds'
3. References & Clock Characterization — I50-3x
   • I50-31 qualify_clock(clock_id, data) -> {adev/mdev/hdev}
   • I50-32 read_clock_health(clock_id) -> health
   • I50-33 compute_holdover_budget(clock_id, horizon) -> budget
4. Timestamp Chain & Latency Budget — I50-4x
   • I50-41 stamp_chain_latency(trace: LatencyTrace) -> budget
   • I50-42 decompose_latency(trace) -> {phy, mac, stack, app}
   • I50-43 calibrate_timestamp_path(device) -> calib
   • I50-44 verify_timestamp_monotonicity(ds) -> report
5. Sync Protocols & Servos — I50-5x
   • I50-51 start_ptp_servo(cfg: SyncConfig) -> state
   • I50-52 evaluate_bmca(state) -> role
   • I50-53 configure_ntp(cfg) -> state
   • I50-54 start_synce_lock(cfg) -> state
   • I50-55 servo_kalman(stream, q_phase, q_freq) -> control
   • I50-56 servo_pid(stream, gains) -> control
   • I50-57 schedule_leap_smear(plan) -> status
6. Offset/Skew/Jitter Estimation & Robustification — I50-6x
   • I50-61 robust_offset(ds) -> {offset, skew, J}
   • I50-62 outlier_filter(ds, method) -> mask
   • I50-63 drift_detector(ds, windows) -> drift_report
   • I50-64 jitter_estimator(ds, windows) -> {J_p50,p95,p99}
7. Phase/Time Noise & Allan Family — I50-7x
   • I50-71 phase_noise_psd(ds, fs) -> S_phi(f)
   • I50-72 time_deviation(ds, taus) -> TDEV(τ)
   • I50-73 allan(ds, taus) -> {adev, mdev, hdev}
8. Buffering, Resampling & Time-Base Conversion — I50-8x
   • I50-81 align_timepath(ds, ref) -> ds'
   • I50-82 resample_timebase(ds, fs_out, policy) -> ds'
   • I50-83 buffer_strategy(qos) -> plan
9. Arrival-Time Metrology & Path Harmonization — I50-9x
   • I50-91 enforce_arrival_convention(path: ArrivalPath, c_ref) -> {T_arr, delta_form}
   • I50-92 assert_arrival_contract(T_arr, tol_Tarr) -> report
   • I50-93 record_path_length(path) -> {L_gamma}
10. Distributed Graph Sync & Failover — I50-10x
    • I50-101 graph_sync(plan) -> status
    • I50-102 failover_policy(state) -> action
    • I50-103 bmc_telemetry(state) -> metrics
11. Dashboards, Alerts & Audit — I50-11x
    • I50-111 emit_dashboard(sli) -> dashboard
    • I50-112 raise_alarm(event, severity) -> ack
    • I50-113 audit_log(entry) -> ok

IV. Selected Interface Details & Invariants (High-Frequency APIs)

1. I50-51 start_ptp_servo(cfg) -> state
   • Inputs: cfg.ptp.{domain, two_step, profile, intervals}, cfg.servo, tol_*.
   • Outputs: state = {role, lock, offset/skew/J (live), bmca_state}.
   • Invariants:
     1. role ∈ {GM, BC, OC, SLAVE} consistent with BMCA.
     2. slew_rate ≤ cfg.servo.max_slew (default 50 ns/s).
     3. On source switch, emit source_switch and write audit_log.
2. I50-61 robust_offset(ds) -> {offset, skew, J}
   • Estimation: median-of-means for location, Theil–Sen for slope, quantiles for J.
   • Invariants: non_decreasing(tau_mono); return includes uncertainty U.
3. I50-73 allan(ds, taus) -> {adev, mdev, hdev}
   • Constraints: taus increasing; on short windows, auto-fallback or code="SHORT_WINDOW".
   • Invariants: adev(τ) ≥ 0; sanity checks on monotone log–log segments.
4. I50-41 stamp_chain_latency(trace) -> budget
   • Behavior: decompose phy/queue/stack/app; return budget = {mean, p95, p99}.
   • Invariants: budget.mean ≥ 0; p99 ≥ p95 ≥ mean.
5. I50-91 enforce_arrival_convention(path, c_ref)
   • Behavior: compute and persist the two forms with delta_form:
     T_arr = ( 1 / c_ref ) * ( ∫ n_eff d ell ) and T_arr = ( ∫ ( n_eff / c_ref ) d ell )。
   • Invariant: delta_form ≤ tol_Tarr; on failure return ok=0 with a diagnostic report.
6. I50-14 evaluate_slo(sli, targets) -> report.slo
   • Behavior: burn_rate_W = bad_time_W / ( (1 - SLO_target) * W ); tiered outcomes warn/major/critical.
   • Invariants: windowed stats computed on tau_mono; publication on ts.
7. I50-101 graph_sync(plan) -> status
   • Inputs: plan = { graph G=(V,E), roles, priorities, holdover_budget }.
   • Behavior: compute a minimal “reference tree”; evaluate offset/skew and holdover per edge/node.
   • Invariants: unique GM exists; mismatches trigger failover_policy.

V. Parameter & Field Semantics (Unified Rules)

• Time & frequency: offset [s], skew [ppm|ppb], J [s], tau [s], adev/mdev/hdev [s].
• Confidence & uncertainty: U = k * u_c, default k = 2; each returned field pairs U(field) with u(field).
• Thresholds & contracts: tol_offset, tol_skew, tol_J, tol_Tarr must be explicit in SyncConfig.

VI. Events & Audit Fields (Aligned with Ch. 13/14)

• Events: source_switch, holdover_enter/exit, leap_event, smear_active, failover, bmca_change.
• Audit record:
  audit_log = { ts, tau_mono, event, role_before/after, sli_snapshot, signature }.

VII. Cross-Volume Mapping & Dependencies

• EFT.WP.Core.DataSpec v1.0: field naming, PK/index, unit/dimension checks via check_dim.
• EFT.WP.Core.Threads v1.0: encapsulate I50-* nodes on thr/chan, honoring backpressure & idempotence.
• Methods.Cleaning v1.0 / Methods.Imaging v1.0: I50-81/I50-91 align T_arr with image/sensor paths; record missing/masks m ∈ {0,1} and q_score.

VIII. Typical Assembly Sequence (Reference)

• register_topology → register_clock
• calibrate_timestamp_path → stamp_chain_latency
• start_synce_lock → start_ptp_servo → evaluate_bmca
• robust_offset → allan → time_deviation
• align_timepath → enforce_arrival_convention → assert_arrival_contract
• emit_dashboard → evaluate_slo → freeze_release_time

IX. Invariant Summary (Global Constraints for All Interfaces)

• id/TraceID uniqueness; all mutating calls are idempotent.
• non_decreasing(tau_mono); no publishing interface may violate monotonicity.
• ( ∑ weights ) / N ≈ 1 where weighted estimates are used.
• check_dim(all) = pass; delta_form ≤ tol_Tarr; signature_valid = true.