21-EFT.WP.Metrology.Sync v1.0 | Appendix A — Interface Reference (I60 Suite)

Home ／ Docs-Technical WhitePaper ／ 21-EFT.WP.Metrology.Sync v1.0

Appendix A — Interface Reference (I60 Suite)

Purpose: Define the full I60 interface set for the synchronization stack—signatures, parameter semantics, returns, errors, and invariants—so teams can assemble and audit systems consistently across the execution graph G=(V,E).

I. Usage Notes & Naming Conventions

1. Namespace & numbering
   • Interfaces are numbered I60-xx and grouped by function: topology & deployment, timestamp links, protocol sessions, servo filtering, delay & asymmetry, estimation & stability, holdover & failover, graph sync optimization, arrival metrology, quality & panels, manifests & audit.
   • Field names follow EFT.WP.Core.DataSpec v1.0; cross-volume references use the fixed pattern “see … Chapter x S/P/M/I…”.
2. Metrology & time base
   • Statistical windows are computed on tau_mono and published on ts, with offset/skew/J attached.
   • Any interface that involves arrival time must return both forms and record delta_form:
     T_arr = ( 1 / c_ref ) * ( ∫ n_eff d ell )，T_arr = ( ∫ ( n_eff / c_ref ) d ell )。
3. Contracts & generic invariants
   • check_dim(expr) must pass; delta_form ≤ tol_Tarr; unique(TraceID); idempotent(op, key).
   • Failures map to standardized errors (see Errors & Contract Mapping at the end of this appendix).

II. Common Types & Event Enumerations

1. Common types
   • TimeSample = { ts, tau_mono, offset, skew, J_rms, J_pp, meta }
   • LinkProp = { media, rate, delay_ms, delay_sm, asym, PDV }
   • ServoParams = { bw_hz, damping, loop_type, pll_order, fll_order }
   • PTPProfile = { profile_id, two_step, delay_mech, announce, sync, delayreq }
   • SLO = { metric, tol, window, pxx }
   • SLI = { metric, p50, p95, p99, mean, std }
2. Event enumeration
   EVT.GM_SWITCH, EVT.GNSS_LOSS, EVT.LOOP_UNLOCK, EVT.PDV_SPIKE, EVT.HOLDOVER_ENTER, EVT.HOLDOVER_EXIT.

III. Topology & Deployment (I60-1x)

1. I60-11 plan_topology(topo, roles, caps) -> plan_id
   • Input: G=(V,E), node role ∈ {GM, BC, OC}, timestamp capability hw|sw|hybrid.
   • Output: deployment plan plan_id and constraints summary.
   • Invariants: unique(plan_id); role–capability consistency checks pass.
2. I60-12 deploy_ptp_profile(profile: PTPProfile, plan_id) -> session_id
   • Output: session_id.
   • Invariants: configuration matches device capabilities; BC links are closed-loop reachable.

IV. Timestamp Links (I60-2x)

1. I60-21 probe_timestamp_path(node, mode) -> LinkProp
   • Description: measure delay_ms, delay_sm, asym, PDV.
   • Invariants: asym = | delay_ms - delay_sm |; units and dimensions are consistent.
2. I60-22 set_timestamp_source(node, src) -> ack
   • Description: configure hw|sw|hybrid timestamp source and NIC capabilities.
   • Invariants: switching causes no packet loss or occurs within a maintenance window.

V. Protocol Sessions & Runtime (I60-3x)

1. I60-31 start_ptp(session_id) -> ack
2. I60-32 start_synce(plan_id) -> freq_lock_report
3. I60-33 start_white_rabbit(plan_id) -> wr_session_id
   Invariants: state machines are consistent; freq_lock_report.lock == true before entering phase/time loops.
4. I60-34 bmca_elect(plan_id, policy) -> gm_selected
   • Description: run BMCA master election.
   • Invariants: gm_selected is stable within policy jitter tolerances.

VI. Servo & Filtering (I60-4x)

1. I60-41 servo_tune(nodes, params: ServoParams) -> applied
   • Description: configure PLL/FLL/PI/PII/Kalman parameters.
   • Invariants: loop_type matches device implementation; closed-loop stability holds (damping > 0).
2. I60-42 kalman_sync(stream, model_spec) -> state_series
   • Output: state = {offset_hat, skew_hat, drift_hat, cov} time series.
   • Invariants: covariance is positive semidefinite; numerically stable.

VII. Delay & Asymmetry (I60-5x)

1. I60-51 estimate_asymmetry(samples, method) -> asym_est
   • method ∈ {cal_table, two_way, fiber_dispersion, WR-cal}.
   • Invariants: unit(asym)="s", asym ≥ 0.
2. I60-52 compensate_path_asym(node, asym_est) -> ack
   Invariants: compensation is persisted and audit-roll-backable.

VIII. Offset / Skew / Jitter Estimation (I60-6x)

1. I60-61 estimate_offset_skew(stream, window) -> {offset, skew, J_rms, J_pp}
   • Equations: skew = d ts_local / dt - d ts_ref / dt；J_rms = sqrt( mean_window( ( offset - mean(offset) )^2 ) )。
   • Invariants: compute on tau_mono; publish on ts.
2. I60-62 robust_estimate(stream, loss_fn) -> stats
   • loss_fn ∈ {Huber, Tukey, L1}; returns outlier-robust estimates.
   • Invariants: weights sum to normalized totals; outlier ratio is persisted.

IX. Noise Sources & Stability (Allan Family, I60-7x)

• I60-71 allan_deviation(freq_series, tau_set) -> {Adev(tau)}
• I60-72 hadamard_deviation(freq_series, tau_set) -> {Hdev(tau)}
  Invariants: tau_set is monotone; boundary truncation policy is fixed.

X. Holdover & Failover (I60-8x)

1. I60-81 holdover_assess(node, horizon) -> {t_holdover_x, drift}
   • Description: evaluate holdover duration at threshold x.
   • Invariants: drift consistent with historical stability model.
2. I60-82 failover_test(gm_pair, trigger, max_tswitchover) -> report
   Invariants: tswitchover ≤ max_tswitchover; EVT.GM_SWITCH is recorded correctly.

XI. Distributed Graph Sync & Topology Optimization (I60-9x)

1. I60-91 optimize_sync_graph(topo, weights, objective) -> topo'
   • objective ∈ {min_p99_offset, min_burn, max_availability}.
   • Invariants: topology remains connected; weights ≥ 0.
2. I60-92 place_boundary_clocks(topo, budget) -> placement
   Invariants: budget not exceeded; minimizes PDV on critical paths with reproducible strategy.

XII. Arrival Metrology & Path Consistency (I60-10x)

1. I60-101 calc_arrival_two_forms(path, n_eff, c_ref) -> {T_arr_form1, T_arr_form2, delta_form}
   • Equations:
     1. T_arr_form1 = ( 1 / c_ref ) * ( ∫ n_eff d ell )
     2. T_arr_form2 = ( ∫ ( n_eff / c_ref ) d ell )
     3. delta_form = | T_arr_form1 - T_arr_form2 |
   • Invariants: delta_form ≤ tol_Tarr; gamma(ell) and measure d ell are explicit.
2. I60-102 enforce_arrival_convention(ds) -> ds'
   • Description: standardize datasets to persist both forms and delta_form.
   • Invariants: original time semantics are not altered.

XIII. Quality, SLOs & Dashboards (I60-11x)

1. I60-111 compute_sync_sli(stream|samples, window, qset) -> SLI[]
   • Description: quantiles for sync_error, skew, J_rms/J_pp, PDV, asym.
   • Invariants: qset ⊆ {p50,p90,p95,p99}; window coverage ≥ threshold.
2. I60-112 evaluate_slo(sli, rules) -> {pass, violations, bad_time, E_budget, burn_rate, q_score_sync}
   Invariants: E_budget = ∑ duration(violations); burn_rate = bad_time / window_total.
3. I60-113 emit_dashboard(spec, series) -> panel_id
   Invariants: panel_id is unique; replay source replay_uri is persisted.

XIV. Manifests & Audit (I60-12x)

1. I60-121 export_sli_manifest(ctx, sli, slo) -> manifest.sync.sli
   • Contents: TraceID, Delta_t, metrics.*, contracts.*, signature, config_hash.
   • Invariants: hash_sha256(blob) and signature verify successfully.
2. I60-122 audit_trail(query) -> events[]
   • Description: return sequence of EVT.* and configuration changes.
   • Invariants: event timeline is strictly monotone (non_decreasing(ts)).

XV. Typical Call Chains & Invariant Checks

1. Deploy & measure (example)
   • plan_topology → deploy_ptp_profile → start_ptp
   • probe_timestamp_path → estimate_asymmetry → compensate_path_asym
   • servo_tune → run_sync_probe (see Chapter 15) → compute_sync_sli → evaluate_slo
   • calc_arrival_two_forms → export_sli_manifest
2. Global invariants
   check_dim(all outputs); delta_form ≤ tol_Tarr; sum(weights)/N ≈ 1 (when weighting is used); unique(plan_id, session_id, panel_id).

XVI. Error Codes & Contract Mapping (Summary)

• E.BAD_DIMENSION: dimensional check failed → trigger C60-dim-01 rollback.
• E.DELTA_FORM_EXCEEDS: delta_form > tol_Tarr → C60-arr-02 blocks release.
• E.LOOP_UNSTABLE: servo instability → C60-servo-03 adjust bw_hz/damping.
• E.PDV_EXCESS: PDV above threshold → C60-link-04 rate-limit & path swap.
• E.GM_SWITCH_FREQ: GM switching too frequent → C60-bmca-05 inspect BMCA policy & reference health.
• E.SLO_VIOLATION: SLO unmet → C60-slo-06 degrade or move to rollback manifest.

XVII. Compatibility & Versioning

• Semantic versioning: I60.major.minor.patch. Breaking changes must be listed in Appendix F: Change Log with migration steps.
• Historical compatibility: retain deprecated_since with replacement guidance.

XVIII. Cross-References

• Dual-form arrivals: EFT.WP.Metrology.TimeBase v1.0 Chapter 9 and Methods.Cleaning v1.0 Chapters 6/10.
• Quality & SLOs: Methods.CrossStats v1.0 Chapter 14.
• Noise & stability: this volume Chapter 9 and TimeBase Chapter 7.