27-EFT.WP.Packets.Light v1.0 | 附录A 接口参考（I60 全集）

目录 ／ 文档-技术白皮书 ／ 27-EFT.WP.Packets.Light v1.0

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

目标：枚举并规范本卷所有实现绑定 I60-* 的函数原型、输入/输出与不变量，确保两口径（配置/解析 vs 测量/实现）并行、量纲校核、清单落盘与可审计回放。

I. 总述与约定

1. 命名与版本
   • 接口统一编号 I60-xx，语义化版本（semver）写入清单（见第15章）。
   • 任何破坏性变更需升主版本，并提供 diff/迁移脚本（见 XIV）。
2. 两口径并行（强制）
   所有“评估/发布”类接口需同时产出配置/解析口径与测量/实现口径结果，并返回两口径差 delta_form_*。
3. 量纲与单位（强制）
   任一进入方程字段必须声明 unit(field) 与 dim(field) 并通过 check_dim( y - f(x) )；对数量↔线性换算在结果元数据中注明。
4. 几何与测度显式
   路径积分 ( ∫_{gamma(ell)} · d ell )、频域 ( ∫_{f∈B} · d f )、时域 ( ∫_{t∈W} · d t ) 与事件/集合求和须显式域与测度。
5. 错误语义
   统一错误码 E60-xxx（见 XIII）；所有函数返回 status ∈ {ok,error} 与 err 字段；必要时返回 evidence_uri 以便审计。

II. 通用类型（抽象）

• GraphSpec = {segments:[{id, type∈{fiber,fso,device}, hash, len, params}], topo, timebase}
• FrameSpec = {T_epoch,T_f,T_slot,T_sym,T_guard,N_sym,N_gap,hash}
• RefCond = {tz, temp, press, humid, weather, cn2, samplerate, ts_from, ts_to, notes, hash}
• MediumModels = {n_eff(f,x), n_g(f), alpha(f), beta(ω), beta2, D_pmd}
• Label = {lambda, k_sub_set, s_set, B_eff, S_eff}
• PlanPower = {per_span:[], G_amp, tilt, evidence_uri}
• Metrics = {OSNR,EVM,BER,Q,P_rx,lat_*,Iso,XT,...}
• Uncertainty = {method∈{GUM,MC}, u:dict, U:dict, k, nu_eff}
• Manifest = {kind, semver, core:{…}, signature}

III. 路径与物理（第2章，I60-2）*

• I60-21 build_medium_models(segments, env:RefCond) -> {models:MediumModels, status, err}
  不变量：non_decreasing(ell)；check_dim(models.*)。
• I60-22 segment_integrals(gamma_seg, n_eff, c_ref) -> {T_form1, T_form2, delta_form, status}
  两口径：常量外提 vs 一般口径。
• I60-23 compute_group_delay(n_g, gamma) -> {T_g, status}
• I60-24 estimate_dispersion_broadening(beta2, L, pulse_spec) -> {sigma_out, status}
• I60-25 estimate_pmd_penalty(D_pmd, L) -> {tau_DGD, status}
• I60-26 link_osnr(devices, rbw, ref) -> {OSNR_lin_dB, status}
• I60-27 fso_scintillation(Cn2, geom, λ, D_rx) -> {sigma_X2, sigma_I2, G_ap, status}
• I60-28 nonlinear_check(P_tx, A_eff, gamma_nl, link) -> {phi_SPM, report, status}
• I60-29 emit_phys_manifest(results, policy) -> {uri, status}
  不变量：清单包含 gamma.hash, RefCond, T_arr_forms, OSNR, beta2/PMD 等（见第2章）。

IV. 成帧与时基（第3章，I60-3）*

• I60-31 design_frame(schema, timebase) -> {frame_spec:FrameSpec, status}
• I60-32 timestamp_from_indices(ids:{epoch,frame,slot,sym}, frame_spec) -> {t_hat_cnt, status}
• I60-33 estimate_timing(rx_stream, pilot, window) -> {t_hat_cont, offset, skew, J, status}
• I60-34 align_frames(rx_stream, frame_spec, pilot) -> {e_align, locks, diag, status}
• I60-35 guard_budget(residuals:{ΔCD,ΔPMD}, jitter:σ_J) -> {T_guard_min, status}
• I60-36 throughput(frame_spec, mod, fec, overhead) -> {R_net, status}
• I60-37 emit_frame_manifest(results, policy) -> {uri, status}
  不变量：delta_form_frame ≤ tol_frame；unit(T_*)="[T]"。

V. 调制/编码与检测（第4章，I60-4）*

• I60-41 modulate(bits, frame_spec, mod) -> {x(t), status}
• I60-42 pass_channel(x(t), H|h, impairments) -> {y(t), status}
• I60-43 demodulate(y(t), frame_spec, rx_cfg) -> {sym, LLR, EVM_meas, SNR_est, status}
• I60-44 map_osnr_to_snr(OSNR_lin, Rs, RBW) -> {SNR_lin, status}
• I60-45 predict_ber_from_snr(mod, SNR_lin) -> {BER_pred, status} / predict_evm_from_snr(SNR_lin) -> {EVM_pred, status}
• I60-46 measure_spectrum(x(t), RBW, B) -> {ACLR, OBB, OBW, status}
• I60-47 ofdm_metrics(x_cp, N_fft, N_cp) -> {PAPR, CP_ok, status}
• I60-48 fec_decode(LLR, FEC, R_c) -> {bits_hat, BER_postFEC, status}
• I60-49 compare_dual_forms(EVM_pred, EVM_meas, BER_pred, BER_meas) -> {delta_form_mod, status}
• I60-4A emit_mod_manifest(results, policy) -> {uri, status}
  不变量：掩膜/带宽与量纲一致；两口径差达标。

VI. 波长/子载/空间标签（第5章，I60-5）*

• I60-51 grid_define(kind∈{DWDM,FlexGrid}, spec) -> {Λ, status}
• I60-52 rsa_assign(req, net, Λ, K, S, policy) -> {label:Label, alloc, path, status}
• I60-53 power_equalize(path, H_link, targets) -> {plan_pwr:PlanPower, status}
• I60-54 spectral_metrics(trace, B_eff, RBW) -> {ACLR, OBB, Iso_ch, status}
• I60-55 sdm_metrics(probe, S_sel) -> {XT_pwr, κ_est, status}
• I60-56 spectral_efficiency(R_net, B_eff, S_eff) -> {SE, status}
• I60-57 compare_config_vs_meas(cfg_metrics, meas_metrics) -> {delta_form_label, status}
• I60-58 emit_label_manifest(results, policy) -> {uri, status}
  不变量：label 与设备/路径 hash 可追溯；保护带/隔离度达标。

VII. 传播损伤与补偿（第6章，I60-6）*

• I60-61 estimate_cd(y, X, grid) -> {D, beta2, fit_err, status}
• I60-62 compensate_cd_freq(X, D, L, window) -> {Xc, H_comp.hash, status}
• I60-63 equalize_cd_time(y, taps, method) -> {yc, h_eq.hash, status}
• I60-64 estimate_pmd(y, method) -> {R_hat, tau_DGD_hat, qual, status}
• I60-65 equalize_pmd_mimo(y, cfg) -> {yc, report, status}
• I60-66 dbp_ssfm(y, link, steps) -> {yc, complexity, status}
• I60-67 volterra_eq(y, order3_cfg) -> {yc, h1h3.hash, status}
• I60-68 compute_residuals(x, y, yc) -> {CD_res, PMD_res, NL_res, status}
• I60-69 compare_dual_comp(y_f, y_t) -> {delta_form_comp, status}
• I60-6A emit_comp_manifest(results, policy) -> {uri, status}
  不变量：两口径并行；残差与倾斜阈值达标。

VIII. 自由空间光（第7章，I60-7）*

• I60-71 fso_attenuation(weather, λ) -> {γ_atm_dB_per_km, status}
• I60-72 scintillation(Cn2, λ, L, D_rx) -> {σ_X2, σ_I2, G_ap, status}
• I60-73 pointing_loss(L, θ_div, D_rx, σ_θ, r_bias) -> {L_point_dB, status}
• I60-74 availability(stats, P_rx, P_th, model) -> {Avail, P_outage, status}
• I60-75 link_budget_fso(params) -> {A_atm, L_point, P_rx, OSNR, FM_dB, status}
• I60-76 compare_config_meas(cfg, meas) -> {delta_form_fso, status}
• I60-77 emit_fso_manifest(results, policy) -> {uri, status}
  不变量：天气/Cn2 源可追溯；两口径差达标。

IX. 到达时一致化（第8章，I60-8）*

• I60-81 eval_tarr_forms(n_eff, c_ref, gamma) -> {T_form1, T_form2, delta_form, status}
• I60-82 corr_env_T(parts, RefCond, sensors) -> {ΔT_geom, ΔT_med, status}
• I60-83 fuse_timebases(t_cnt, t_cont, T_form2, weights) -> {T_arr_star, status}
• I60-84 estimate_sync(rx_ts, tx_ts) -> {offset, skew, J, status}
• I60-85 check_guard_and_jitter(frame_spec, J, residuals) -> {report, status}
• I60-86 assert_tarr_contracts(records, rules) -> {report, pass, status}
• I60-87 emit_tarr_manifest(results, policy) -> {uri, status}
  不变量：T_arr 与 T_arr* 量纲一致；delta_form ≤ tol_Tarr。

X. 交换与路由（第9章，I60-9）*

• I60-91 ksp_paths(topology, src, dst, k, metric) -> {π_1…π_k, status}
• I60-92 rsa_assign(req, resources, policy) -> {label, path, feas, cost, status}
• I60-93 xbar_program(path, label, devices) -> {Xbar, T_reconf, status}
• I60-94 ocs_blocking(A, m) -> {P_block, status}
• I60-95 ops_contention(λ_pkt, μ, P_out, N_in, FDL, WC) -> {P_contention, lat_q, status}
• I60-96 power_equalize(dev_chain, targets) -> {plan_pwr, status}
• I60-97 measure_swrt(telem) -> {P_block_meas, P_cont_meas, lat_sw_meas, Iso_meas, FM_dB_meas, status}
• I60-98 compare_config_meas(cfg, meas) -> {delta_form_swrt, status}
• I60-99 emit_swrt_manifest(results, policy) -> {uri, status}
  不变量：保护带/隔离与功率计划不被破坏；两口径并行。

XI. 排队与守恒（第10章，I60-10）*

• I60-101 queue_model({λ, E[L], C, K}) -> {lat_q, P_block, status}
• I60-102 ops_fdlsched({λ, μ, P_out, N_in, FDL, WC}) -> {P_contention, μ_eff, lat_q, status}
• I60-103 netcal_bound(arrival:{σ,ρ}, service:{R,T0}) -> {D_max, B_max, status}
• I60-104 shaper_delay(token_bucket:{r,σ}, C) -> {W_shaper, status}
• I60-105 compose_latency(links[]) -> {lat_total_{mean,p95}, status}
• I60-106 guard_budget(jitter, residuals:{ΔCD,ΔPMD}) -> {T_guard_min, status}
• I60-107 measure_latency(ts_stream) -> {lat_prop, lat_ser, lat_sw, lat_q, lat_proc, lat_total, status}
• I60-108 compare_dual_queue(config, meas) -> {delta_form_queue, status}
• I60-109 emit_queue_manifest(results, policy) -> {uri, status}
  不变量：两口径差与守恒门达标。

XII. 计量与遥测（第11章，I60-11）*

• I60-111 measure_osa(trace, B, RBW) -> {OSNR_meas_lin, P_sig, P_noise, meta, status}
• I60-112 measure_power(monitor) -> {P_tx, P_rx, IL_meas, status}
• I60-113 measure_constellation(iq, frame_spec, eq_cfg) -> {sym, EVM_meas, BER_meas, SNR_est, Q_factor, status}
• I60-114 predict_from_osnr(mod, OSNR_lin, Rs, RBW_ref) -> {SNR_pred, EVM_pred, BER_pred, status}
• I60-115 compare_dual_meas(pred, meas, weights) -> {delta_form_meas, status}
• I60-116 propagate_uncertainty(cal, RBW, noise_stats) -> {u_OSNR, u_EVM, u_P, status}
• I60-117 emit_meas_manifest(results, policy) -> {uri, status}
  不变量：掩膜/带宽一致；校准有效且可追溯。

XIII. 多径与安全（第12/13章，I60-12, I60-13）**

• I60-121 otdr_estimate(trace, alpha) -> {events:[{z_k,R_hat_k}], slope_err, h_hat, status}
• I60-122 corr_channel(x,y, window) -> {τ_hat[], â[], h_hat, status}
• I60-123 sparse_mp_estimate(x,y, grid, λ) -> {â, τ_hat, h_hat, status}
• I60-124 multipath_cancel(x, y, τ_hat, â, cfg) -> {y_clean, status}
• I60-125 notch_smooth(H, bands) -> {H_smooth, meta, status}
• I60-126 eval_mpath_residual(x, y, y_clean, H0, B) -> {MER, MP_res, status}
• I60-127 compare_dual_mpath(pred, meas, weights) -> {delta_form_mpath, status}
• I60-128 emit_mpath_manifest(results, policy) -> {uri, status}
• I60-131 compute_energy_balance(x,y,plan) -> {E_balance, status}
• I60-132 spectral_anomaly(Y, Y_ref, B, RBW) -> {D_spec, ACLR, OBB, status}
• I60-133 polarization_anomaly(S, S_ref) -> {Pol_anom, status}
• I60-134 timing_integrity(T_arr_star, t_hat_cont, T_sym) -> {Timing_anom, status}
• I60-135 quality_consistency(EVM_pred, EVM_meas, BER_pred, BER_meas) -> {ΔQ, status}
• I60-136 fuse_security_score(z, coeff) -> {Score, status}
• I60-137 compare_dual_sec(cfg_metrics, meas_metrics, weights) -> {delta_form_sec, status}
• I60-138 act_security_policy(Score, rules) -> {actions[], status}
• I60-139 emit_sec_manifest(results, policy) -> {uri, status}
  不变量：证据 URI 与段/设备绑定；最小可见原则。

XIV. 运行时与端到端（第14/15章，I60-14, I60-15）**

• I60-141 plan_stream_windows(W, H, lateness, watermark) -> {schedule, status}
• I60-142 query_or_compute(cache, K_cache, fn) -> {value, hit, stale, status}
• I60-143 enforce_rate(token_bucket:{r,B}, now) -> {permit, state, status}
• I60-144 measure_runtime(stream) -> {latency, drop_rate, ρ, cpu_pct, mem_pct, gpu_util, watermark_lag, status}
• I60-145 compare_dual_runtime(cfg_metrics, meas_metrics) -> {delta_form_rt, status}
• I60-146 apply_fallback(mode, ctx) -> {actions[], status}
• I60-147 snapshot_panel(metrics, resources, U) -> {panel_uri, snapshot_hash, status}
• I60-148 emit_runtime_manifest(results, policy) -> {uri, status}
• I60-151 build_usecase(profile) -> {graph, segments, devices, frame_spec, thresholds, status}
• I60-152 run_pipeline(profile, inputs) -> {manifests[], panels[], kpis, status}
• I60-153 validate_end2end(manifests, kpis, rules) -> {report, pass, status}
• I60-154 publish_end2end(manifests, report) -> {uri, status}
• I60-155 rollback_end2end(manifest_uri, reason) -> {status}
  不变量：签名链完整；两口径贯通；回退可回放。

XV. 错误码与语义（E60-xxx）

• E60-001 InvalidDim：量纲/单位不匹配（check_dim 失败）。
• E60-002 TwoFormMismatch：两口径差超阈（delta_form_* > tol_*）。
• E60-003 UnstableKernel/GuardBreach：守恒或稳定/保护门失败。
• E60-004 ManifestIncomplete/InvalidSignature：清单缺键或签名无效。
• E60-005 ContractViolation：任一 C60-* 未通过。
• E60-006 CalExpired/DataStale：校准过期或数据新鲜度不足。
• E60-007 ResourceExceeded/Backpressure：资源或背压超配额。
• E60-008 Serialization/DeserializationError。
• E60-009 NotTraceable：缺失 hash/id/RefCond 追溯信息。

XVI. 版本与兼容

• 次版本升级不得改变已存在参数名/默认值；新增字段必须可选并在清单 changelog 记录。
• 提供 canonicalize(manifest) 的稳定序列化用于签名/对比；跨版本提供 diff/迁移脚本。

XVII. 交叉引用

1. 第2–15章各节的 P/S/M/C 规则是本附录接口的语义基础；
2. 相关配套卷：
   • 《EFT.WP.Metrology.PathCorrection v1.0》（两口径与路径修正）
   • 《EFT.WP.Metrology.TimeBase v1.0》《…Sync v1.0》（时基/同步）
   • 《EFT.WP.Metrology.Instrument v1.0》（计量/校准）

小结

• 本附录给出 I60-* 的全量接口原型、约束与错误语义：两口径并行、量纲校核、清单落盘与可审计回放是所有实现的一致要求；
• 结合各章 P/S/M/C，工程团队可据此实现从物理建模到运行发布的端到端、可复现、可回退的 Packets.Light 管线。