21-EFT.WP.Metrology.Sync v1.0 | Appendix B — Contract Library & Runbooks (C60 Suite)

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

Appendix B — Contract Library & Runbooks (C60 Suite)

Purpose & Usage: This appendix defines the standard synchronization contracts C60-* and the operational runbooks. All assertions are evaluated on tau_mono, published on ts, and carry offset/skew/J with window Delta_t. Each contract is persisted as a triplet—computable assertion + threshold parameters + action plan—under manifest.sync.contracts.*. All formulas, symbols, and definitions are expressed in English plain text.

I. Assertion Grammar & Evaluation Rules

1. Unified symbols
   • Time error offset(t); frequency error skew(t) (unit s/s); jitter J_rms, J_pp; packet delay variation PDV; asymmetry asym.
   • Dual-form arrivals:
     T_arr_form1 = ( 1 / c_ref ) * ( ∫ n_eff d ell )
     T_arr_form2 = ( ∫ ( n_eff / c_ref ) d ell )
     delta_form = | T_arr_form1 - T_arr_form2 |.
2. Evaluation windows
   • eval(expr, window=Delta_t, quantile=q); default Delta_t=300 s, q ∈ {p50,p95,p99}.
   • When using weights, declare w(i) and publish n_eff = ( (∑ w)^2 ) / ( ∑ w^2 ).
3. Dimensions & units
   Run check_dim(expr) on every assertion; time in seconds; skew in s/s.
4. Results
   Ternary: pass / warn / fail. fail triggers the mapped runbook; warn accrues burn and enters observation.

II. Severity & Response Tiers

• S1 / critical: service lost or errors unbounded → immediate degrade/rollback.
• S2 / major: beyond SLO but controllable → retune and rate-limit.
• S3 / minor: transient excursions → observe & densify sampling.
• S4 / info: mild trends/environmental shift → log & notify.

III. Contract Groups & Parameter Dictionary

IV. C60 Contract Library

Link & Timestamp (Link/Stamp)

• C60-link-01 Packet Delay Variation ceiling
  PDV_p99 = eval(PDV, Delta_t, p99) ≤ tol_PDV → S2.
  Action: rate-limit or reroute; call I60-91.
• C60-stamp-02 Timestamp-source consistency
  source ∈ {hw, hybrid} for core paths → S2 on fail.
  Action: I60-22 switch and enter observation Delta_t_obs.
• C60-path-03 Asymmetry threshold
  asym ≤ tol_asym → S2 on fail.
  Action: I60-51/52 estimate & compensate; persist version.

Protocols & Sessions (PTP/NTP/SyncE/WR)

• C60-proto-11 Session stability
  flap_rate ≤ 1 / 10 min → S3 on fail.
  Action: revert to previous stable config.
• C60-bmca-12 GM jitter & switch rate
  bmca_switches_per_h ≤ max_bmca_switch_per_h → S2 on fail.
  Action: pin priorities or raise health thresholds; I60-34 re-elect.

Servo & Filtering

• C60-servo-21 Closed-loop stability
  damping > 0 ∧ bw_hz ∈ [bw_min, bw_max] → S1 on fail.
  Action: I60-41 auto-reduce bandwidth into the safe region.
• C60-servo-22 Lock time
  t_lock ≤ t_lock_max → S2 on fail.
  Action: raise PI integral or enable FLL pre-lock.

Error & Jitter (Offset/Skew/Jitter)

• C60-sync-31 Steady-state time error
  eval( |offset|, Delta_t, p99 ) ≤ tol_offset → S1 on fail.
  Action: degrade to frequency-lock or fallback path.
• C60-sync-32 Frequency cap
  eval( |skew|, Delta_t, p99 ) ≤ tol_skew → S2 on fail.
  Action: enable tempco compensation or auxiliary reference (SyncE).
• C60-sync-33 Jitter energy
  J_rms ≤ tol_J_rms ∧ J_pp ≤ 5 * tol_J_rms → S2 on fail.
  Action: heavier filtering or larger averaging windows.

Noise & Stability (Allan/Hadamard)

• C60-noise-41 ADEV envelope
  Adev(tau) ≤ Adev_spec(tau) for tau ∈ Tau_set → S3 on fail.
  Action: higher-grade source or reduced bandwidth.
• C60-noise-42 HDEV criterion
  Hdev(tau_large) ≤ Hdev_spec(tau_large) → S3.

Holdover & Failover

• C60-hold-51 Holdover capability
  t_holdover_1us ≥ min_holdover_1us → S2 on fail.
  Action: enable drift-model calibration and shorten maintenance cycles.
• C60-fail-52 Switchover latency
  tswitchover ≤ max_tswitchover → S1 on fail.
  Action: promote nearest BC to secondary GM; optimize links.

Graph Sync & Topology

• C60-topo-61 Cascade depth
  bc_layers ≤ bc_layers_max → S2 on fail.
  Action: I60-92 re-place boundary clocks.
• C60-topo-62 Path redundancy
  path_redundancy ≥ R_min → S2 on fail.

Arrival & Path Consistency

• C60-arr-71 Dual-form delta
  delta_form ≤ tol_Tarr → S1 on fail.
  Action: block release; I60-101/102 recompute & persist.
• C60-path-72 Path monotonicity
  non_decreasing(ell) → S2 on fail.

Quality, SLO & Panels

• C60-slo-81 SLI coverage
  coverage(window) ≥ 0.95 → S2 on fail.
  Action: backfill or relax statistical confidence.
• C60-slo-82 Error budget
  burn_rate = bad_time / window_total ≤ burn_max → S2/S1 per ratio.
• C60-slo-83 Release gate
  contract_ok ∧ manifest_signed == true → S1 on fail.

Boundary & Anomalies (Virtualization / GNSS / Spoofing)

• C60-edge-91 VM jitter bound
  J_rms_vm ≤ tol_vm → S3 on fail.
  Action: pin vCPU / isolate IRQs; enable HW timestamp passthrough.
• C60-gnss-92 GNSS quality & spoofing
  DOP ≤ DOP_max ∧ spoof_score ≤ spoof_max → S1 on fail.
  Action: enter holdover and switch to terrestrial references.

Audit & Provenance

• C60-audit-01 Event monotonicity
  non_decreasing(ts_event[]) → S2 on fail.
  Action: rebuild index and complete gaps.
• C60-audit-02 Signature & hash
  verify(signature, hash_sha256(blob)) == true → S1 on fail.

V. Runbooks (Strategy Cards)

1. S60-01 PDV Spike (trigger: C60-link-01 fail)
   I60-21 re-probe → 2. inspect congestion/queuing → 3. temporarily reduce sync rate → 4. I60-91 reweight & reroute → 5. observe Delta_t_obs=900 s, refresh panels.
2. S60-02 GM Switch Thrash (trigger: C60-bmca-12 fail)
   Lock candidate set → raise health thresholds → pin priority (short freeze) → I60-34 re-elect → log EVT.GM_SWITCH.
3. S60-03 Offset Drift (trigger: C60-sync-31 warn/fail)
   I60-61 decompose offset/skew → I60-41 reduce bandwidth + enable feed-forward → if persistent, fall back to frequency lock and notify upstream.
4. S60-04 Asymmetry Detected (trigger: C60-path-03 fail)
   I60-51 estimate asym → I60-52 online compensate → persist compensation version & rollback point.
5. S60-05 GNSS Loss/Spoof (trigger: C60-gnss-92 or EVT.GNSS_LOSS)
   Enter holdover → switch to network refs (SyncE/PTP) → enable anti-spoof cross-checks → gradual re-lock on recovery.
6. S60-06 Holdover Entry (trigger: upstream failure)
   Publish t_holdover_x forecast → tighten SLOs & alert → warm standby GM.
7. S60-07 PTP Flapping (trigger: C60-proto-11 fail)
   Roll back peer negotiation → lower announce rate → check L2 loops & storm control.
8. S60-08 VM Jitter Blow-up (trigger: C60-edge-91 fail)
   Pin vCPU / isolate interrupts → enable HW timestamp passthrough → evaluate migration to bare metal.
9. S60-09 Leap Event
   Freeze BMCA → verify step/smear plan sequentially → widen statistics and grant short-term SLO exemptions.
10. S60-10 Audit Failure (trigger: C60-audit-02 fail)
    Block release → re-sign and recompute hash → generate and archive audit report.

VI. Contract → Interface → Manifest Mapping

• Example: C60-arr-71 → I60-101/102 → manifest.sync.contracts.arr.delta_form.
• Example: C60-sync-31 → I60-61/41 → manifest.sync.metrics.offset.* and manifest.sync.slo.*.
• Example: C60-link-01 → I60-21/91 → manifest.sync.link.pdv.*.

VII. Release Gate & Rollback Order

• Release criterion: pass = check_dim ∧ all_required(C60-*) ∧ contract_ok ∧ manifest_signed.
• Rollback sequence: parameter rollback → path reselection → cascade-depth reduction → role switch/degrade → pause publication.

VIII. Versioning & Compatibility

IX. Cross-References

• Time base & arrivals: EFT.WP.Metrology.TimeBase v1.0 Chapter 9 & appendix.
• Cleaning & release gates: Methods.Cleaning v1.0 Chapter 10.
• Statistics & SLOs: Methods.CrossStats v1.0 Chapter 14.