21-EFT.WP.Metrology.Sync v1.0 | 附录A 接口参考（I60 全集）

目录 ／ 文档-技术白皮书 ／ 21-EFT.WP.Metrology.Sync v1.0

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

I. 使用说明与命名通则

1. 命名与编号
   • 接口统一编号 I60-xx；按功能域分组：拓扑与部署、时间戳链路、协议会话、伺服滤波、延迟与非对称、估计与稳定度、保持与回退、图同步优化、到达时计量、质量与面板、清单与审计。
   • 字段命名遵循《EFT.WP.Core.DataSpec v1.0》，跨卷引用固定写法：“见《…》第x章 S/P/M/I…”。
2. 计量与时基
   • 统计窗口在 tau_mono 上计算，对外以 ts 发布；随附 offset/skew/J。
   • 涉及到达时的接口必须并行给出两口径并记录 delta_form：
     T_arr = ( 1 / c_ref ) * ( ∫ n_eff d ell )，T_arr = ( ∫ ( n_eff / c_ref ) d ell )。
3. 契约与不变量（通用）
   • check_dim(expr) 必须通过；delta_form ≤ tol_Tarr；unique(TraceID)；idempotent(op, key)。
   • 失败返回标准错误（见本附录末尾“错误码与契约映射”）。

II. 公共类型与事件枚举

1. 公共类型
   • 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. 事件枚举
   EVT.GM_SWITCH, EVT.GNSS_LOSS, EVT.LOOP_UNLOCK, EVT.PDV_SPIKE, EVT.HOLDOVER_ENTER, EVT.HOLDOVER_EXIT。

III. 拓扑与部署（I60-1x）

1. I60-11 plan_topology(topo, roles, caps) -> plan_id
   • 输入：G=(V,E)、节点 role ∈ {GM, BC, OC}、时间戳能力 hw|sw|hybrid。
   • 输出：部署计划 plan_id 与约束摘要。
   • 不变量：unique(plan_id)；roles 与 caps 一致性校核通过。
2. I60-12 deploy_ptp_profile(profile: PTPProfile, plan_id) -> session_id
   • 输出：session_id。
   • 不变量：配置与设备能力兼容；BC 链路闭环可达。

IV. 时间戳链路（I60-2x）

1. I60-21 probe_timestamp_path(node, mode) -> LinkProp
   • 说明：测量 delay_ms, delay_sm, asym, PDV。
   • 不变量：asym = | delay_ms - delay_sm |；单位与量纲一致。
2. I60-22 set_timestamp_source(node, src) -> ack
   • 说明：配置 hw|sw|hybrid 时间戳源与 NIC 能力开关。
   • 不变量：切换无丢包或在维护窗内完成。

V. 协议会话与运行（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
   不变量：会话状态机一致；freq_lock_report.lock == true 方可进入相位/时间闭环。
4. I60-34 bmca_elect(plan_id, policy) -> gm_selected
   • 说明：执行 BMCA 主时钟选举。
   • 不变量：gm_selected 稳定在策略容忍抖动内。

VI. 伺服与滤波（I60-4x）

1. I60-41 servo_tune(nodes, params: ServoParams) -> applied
   • 说明：配置 PLL/FLL/PI/PII/Kalman 等伺服参数。
   • 不变量：loop_type 与设备实现匹配；闭环稳定判据满足 damping > 0。
2. I60-42 kalman_sync(stream, model_spec) -> state_series
   • 输出：state = {offset_hat, skew_hat, drift_hat, cov} 时间序列。
   • 不变量：协方差半正定；数值稳定。

VII. 延迟与非对称（I60-5x）

1. I60-51 estimate_asymmetry(samples, method) -> asym_est
   • method ∈ {cal_table, two_way, fiber_dispersion, WR-cal}。
   • 不变量：unit(asym)="s"，asym ≥ 0。
2. I60-52 compensate_path_asym(node, asym_est) -> ack
   不变量：补偿值持久化并可审计回滚。

VIII. 偏移/频偏/抖动估计（I60-6x）

1. I60-61 estimate_offset_skew(stream, window) -> {offset, skew, J_rms, J_pp}
   • 方程：skew = d ts_local / dt - d ts_ref / dt；J_rms = sqrt( mean_window( ( offset - mean(offset) )^2 ) )。
   • 不变量：窗口在 tau_mono；导出在 ts。
2. I60-62 robust_estimate(stream, loss_fn) -> stats
   • loss_fn ∈ {Huber, Tukey, L1}；输出对异常点鲁棒的估计。
   • 不变量：权重和归一；异常占比落盘。

IX. 噪声源与稳定度（Allan 家族，I60-7x）

• I60-71 allan_deviation(freq_series, tau_set) -> {Adev(tau)}
• I60-72 hadamard_deviation(freq_series, tau_set) -> {Hdev(tau)}
  不变量：tau_set 单调；边界截断规则固定。

X. 保持与回退（I60-8x）

1. I60-81 holdover_assess(node, horizon) -> {t_holdover_x, drift}
   • 说明：评估 holdover 在阈值 x 下的持续时间。
   • 不变量：drift 与历史稳定度模型一致。
2. I60-82 failover_test(gm_pair, trigger, max_tswitchover) -> report
   不变量：tswitchover ≤ max_tswitchover；事件 EVT.GM_SWITCH 正确记录。

XI. 分布式图同步与拓扑优化（I60-9x）

1. I60-91 optimize_sync_graph(topo, weights, objective) -> topo'
   • objective ∈ {min_p99_offset, min_burn, max_availability}。
   • 不变量：拓扑连通；weights ≥ 0。
2. I60-92 place_boundary_clocks(topo, budget) -> placement
   不变量：预算不超限；关键路径 PDV 最小化策略可复算。

XII. 到达时计量与路径一致化（I60-10x）

1. I60-101 calc_arrival_two_forms(path, n_eff, c_ref) -> {T_arr_form1, T_arr_form2, delta_form}
   • 方程：
     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 |
   • 不变量：delta_form ≤ tol_Tarr；gamma(ell) 与测度 d ell 明确。
2. I60-102 enforce_arrival_convention(ds) -> ds'
   • 说明：为数据集统一落盘两口径与 delta_form。
   • 不变量：不改变原始时间语义。

XIII. 质量、SLO 与面板（I60-11x）

1. I60-111 compute_sync_sli(stream|samples, window, qset) -> SLI[]
   • 说明：计算 sync_error, skew, J_rms/J_pp, PDV, asym 的分位指标。
   • 不变量：qset ⊆ {p50,p90,p95,p99}；窗口覆盖率 ≥ 阈值。
2. I60-112 evaluate_slo(sli, rules) -> {pass, violations, bad_time, E_budget, burn_rate, q_score_sync}
   不变量：E_budget = ∑ duration(violations)；burn_rate = bad_time / window_total。
3. I60-113 emit_dashboard(spec, series) -> panel_id
   不变量：panel_id 唯一；可复算数据源 replay_uri 落盘。

XIV. 清单与审计（I60-12x）

1. I60-121 export_sli_manifest(ctx, sli, slo) -> manifest.sync.sli
   • 内容：TraceID, Delta_t, metrics.*, contracts.*, signature, config_hash。
   • 不变量：hash_sha256(blob) 与 signature 验证通过。
2. I60-122 audit_trail(query) -> events[]
   • 说明：返回 EVT.* 序列与配置变更轨迹。
   • 不变量：事件时间线严格单调（non_decreasing(ts)）。

XV. 典型调用串与不变量检查

1. 部署与测量（简例）
   • plan_topology → deploy_ptp_profile → start_ptp。
   • probe_timestamp_path → estimate_asymmetry → compensate_path_asym。
   • servo_tune → run_sync_probe（见第15章）→ compute_sync_sli → evaluate_slo。
   • calc_arrival_two_forms → export_sli_manifest。
2. 贯穿不变量
   check_dim(all outputs)；delta_form ≤ tol_Tarr；sum(weights)/N ≈ 1（若用权重）；unique(plan_id, session_id, panel_id)。

XVI. 错误码与契约映射（摘要）

• E.BAD_DIMENSION：量纲校核失败 → 触发 C60-dim-01 回退。
• E.DELTA_FORM_EXCEEDS：delta_form > tol_Tarr → C60-arr-02 拒绝发布。
• E.LOOP_UNSTABLE：伺服不稳定 → C60-servo-03 调整 bw_hz/damping。
• E.PDV_EXCESS：PDV 超阈 → C60-link-04 限流与路径置换。
• E.GM_SWITCH_FREQ：主时钟切换过于频繁 → C60-bmca-05 检查 BMCA 策略与参考健康。
• E.SLO_VIOLATION：SLO 未达 → C60-slo-06 进入降级或回退清单。

XVII. 兼容性与版本

• 接口采用语义化版本 I60.major.minor.patch；破坏性变更需在《附录F 变更记录》声明并给出迁移步骤。
• 历史兼容层须保留 deprecated_since 与替代建议字段。

XVIII. 交叉引用

• 到达时两口径：见《EFT.WP.Metrology.TimeBase v1.0》第9章与《Methods.Cleaning v1.0》第6/10章。
• 质量与 SLO：见《Methods.CrossStats v1.0》第14章。
• 噪声与稳定度：见本卷第9章、TimeBase 第7章。