20-EFT.WP.Metrology.TimeBase v1.0 | 附录A 接口参考（I50 全集）

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

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

一句话目标：给出本卷“时基计量与同步”的接口全集 I50-*，包含签名、参数语义、返回、错误与不变量，便于在 G=(V,E) 执行图中装配与审计。

I. 约定与类型

1. 统一口径
   • 内联符号用反引号：tau_mono, ts, offset, skew, J, adev/mdev/hdev, T_arr, delta_form, gamma(ell)。
   • 到达时两口径必须并行记录：T_arr = ( 1 / c_ref ) * ( ∫ n_eff d ell ) 与 T_arr = ( ∫ ( n_eff / c_ref ) d ell )；并落盘 delta_form。
   • 单位/量纲必须可校核：unit(x), dim(x), check_dim(expr)。
2. 返回与错误
   • 返回统一为记录集或结构体，含 ok ∈ {0,1}, code, msg, TraceID。
   • 失败不改变外部状态；所有变更型接口需具备幂等性与重复入库保护。
3. 时基
   内部估计在 tau_mono，对外发布 ts；发布时附 offset/skew/J 与不确定度字段 U。

II. 核心数据结构（最小约束）

• 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. 接口目录（按功能分组）

1. 基础与注册 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. 时基映射与标准化 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. 参考与时钟表征 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. 时间戳链路与延迟预算 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. 同步协议与伺服 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. 偏移/频偏/抖动估计与鲁棒化 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. 相位/时间噪声与 Allan 家族 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. 缓冲、重采样与时基转换 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. 到达时计量与路径一致化 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. 分布式图同步与故障切换 I50-10x
    • I50-101 graph_sync(plan) -> status
    • I50-102 failover_policy(state) -> action
    • I50-103 bmc_telemetry(state) -> metrics
11. 面板、告警与审计 I50-11x
    • I50-111 emit_dashboard(sli) -> dashboard
    • I50-112 raise_alarm(event, severity) -> ack
    • I50-113 audit_log(entry) -> ok

IV. 详细说明与不变量（节选，高频接口）

1. I50-51 start_ptp_servo(cfg) -> state
   • 输入：cfg.ptp.{domain, two_step, profile, intervals}, cfg.servo, tol_*。
   • 输出：state = {role, lock, offset/skew/J (live), bmca_state}。
   • 不变量
     1. role ∈ {GM, BC, OC, SLAVE} 与 BMCA 一致。
     2. slew_rate ≤ cfg.servo.max_slew，默认 50 ns/s。
     3. 切源时生成事件 source_switch 并进入 audit_log。
2. I50-61 robust_offset(ds) -> {offset, skew, J}
   • 估计：位置用 median-of-means，斜率用 Theil–Sen，抖动 J 用窗口分位。
   • 不变量：non_decreasing(tau_mono)；U 随结果输出。
3. I50-73 allan(ds, taus) -> {adev, mdev, hdev}
   • 约束：taus 为增序；边界窗口不足自动回退或报告 code="SHORT_WINDOW"。
   • 不变量：adev(τ) ≥ 0；对数坐标下单调段合理性校核。
4. I50-41 stamp_chain_latency(trace) -> budget
   • 分解 phy、queue、stack、app；返回 budget = {mean, p95, p99}。
   • 不变量：budget.mean ≥ 0；p99 ≥ p95 ≥ mean。
5. I50-91 enforce_arrival_convention(path, c_ref)
   • 计算并落盘两口径与 delta_form：
     T_arr = ( 1 / c_ref ) * ( ∫ n_eff d ell ) 与 T_arr = ( ∫ ( n_eff / c_ref ) d ell )。
   • 不变量：delta_form ≤ tol_Tarr（契约失败则返回 ok=0 与报告）。
6. I50-14 evaluate_slo(sli, targets) -> report.slo
   • 计算 burn_rate_W = bad_time_W / ( (1 - SLO_target) * W )；输出分层 warn/major/critical。
   • 不变量：窗口化统计在 tau_mono 上完成；对外以 ts 发布。
7. I50-101 graph_sync(plan) -> status
   • 输入：plan = {graph G=(V,E), roles, priorities, holdover_budget}。
   • 行为：计算最小生成“参考树”，在边/节点上评估 offset/skew 与 holdover。
   • 不变量：存在唯一 GM；失配触发 failover_policy。

V. 参数与字段语义（统一规则）

• 时间与频率
  offset [s], skew [ppm|ppb], J [s], tau [s], adev/mdev/hdev [s]。
• 置信与不确定度
  U = k * u_c，k 默认 2；接口返回中的 U(field) 与 u(field) 成对出现。
• 阈值与契约
  tol_offset, tol_skew, tol_J, tol_Tarr 必须在 SyncConfig 中明示。

VI. 事件与审计字段（与第13/14章对齐）

• 事件键
  source_switch, holdover_enter/exit, leap_event, smear_active, failover, bmca_change。
• 审计记录
  audit_log = { ts, tau_mono, event, role_before/after, sli_snapshot, signature }。

VII. 跨卷映射与依赖

• 与《EFT.WP.Core.DataSpec v1.0》
  字段命名、pk/idx、单位与量纲校核 check_dim。
• 与《EFT.WP.Core.Threads v1.0》
  在 thr/chan 上封装 I50-* 节点，遵循背压与幂等。
• 与《Methods.Cleaning v1.0》与《Methods.Imaging v1.0》
  I50-81/I50-91 对齐 T_arr 与图像/传感路径；缺失与掩码记录 m ∈ {0,1}、q_score。

VIII. 典型装配序列（参考）

• 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. 不变量汇总（所有接口统一约束）

• id/TraceID 唯一；变更接口幂等。
• non_decreasing(tau_mono)；任何发布型接口不得破坏单调性。
• sum(weights)/N ≈ 1（如用到加权估计）。
• check_dim(all) = pass；到达时 delta_form ≤ tol_Tarr；signature_valid = true。