27-EFT.WP.Packets.Light v1.0 | Appendix A — Interface Reference (I60 Suite)

Home ／ Docs-Technical WhitePaper ／ 27-EFT.WP.Packets.Light v1.0

Appendix A — Interface Reference (I60 Suite)

Goal: Enumerate and standardize the full set of I60-* implementation bindings—function prototypes, inputs/outputs, and invariants—so that dual-form execution (configured/analytic vs measured/realized), dimensional checks, manifest persistence, and auditable replay are consistently satisfied across this volume.

I. Overview & Conventions

1. Naming & versioning
   • Interfaces are numbered I60-xx. Semantic versions (semver) are recorded in manifests (see Chapter 15).
   • Any breaking change requires a major version bump and a diff/migration script (see §XVI).
2. Dual-form execution (mandatory)
   Every evaluation/publish interface must produce both the configured/analytic form and the measured/realized form, and return the dual-form gap delta_form_*.
3. Dimensions & units (mandatory)
   Any field that enters equations must declare unit(field) and dim(field) and pass check_dim( y − f(x) ). Log↔linear conversions must be noted in result metadata.
4. Explicit geometry & measures
   Path integrals ( ∫_{gamma(ell)} • d ell ), frequency-domain integrals ( ∫_{f∈B} • d f ), time-domain integrals ( ∫_{t∈W} • d t ), and event/set summations must declare domains and measures explicitly.
5. Error semantics
   Unified error codes E60-xxx (see §XV). All functions return status ∈ { ok, error } and an err field; when relevant, return evidence_uri for audit.

II. Common Types (abstract)

• 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. Path & Physics (Chapter 2, I60-2*)

• I60-21 build_medium_models(segments, env:RefCond) -> { models:MediumModels, status, err }
  Invariant: non_decreasing(ell); check_dim(models.*).
• I60-22 segment_integrals(gamma_seg, n_eff, c_ref) -> { T_form1, T_form2, delta_form, status }
  Two forms: constant-factored vs general.
• 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 }
  Invariant: manifest includes gamma.hash, RefCond, T_arr_forms, OSNR, beta2/PMD (see Ch. 2).

IV. Framing & Timebase (Chapter 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 }
  Invariant: delta_form_frame ≤ tol_frame; unit(T_*) = "[T]".

V. Modulation/Coding & Detection (Chapter 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 }
  Invariant: mask/bandwidth and dimensions consistent; dual-form gap within limits.

VI. Wavelength / Subcarriers / Space Labels (Chapter 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 }
  Invariant: label and device/path hashes traceable; guard/isolation thresholds satisfied.

VII. Propagation Impairments & Compensation (Chapter 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 }
  Invariant: dual forms in parallel; residual and tilt thresholds met.

VIII. Free-Space Optics (Chapter 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 }
  Invariant: weather/Cn2 sources traceable; dual-form gap within limits.

IX. Arrival-Time Harmonization (Chapter 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 }
  Invariant: T_arr and T_arr* share dimensions; delta_form ≤ tol_Tarr.

X. Switching & Routing (Chapter 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 }
  Invariant: guard/isolation and power plans preserved; dual-form execution.

XI. Queueing & Conservation (Chapter 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 }
  Invariant: dual-form gap and conservation gates satisfied.

XII. Metrology & Telemetry (Chapter 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 }
  Invariant: mask/bandwidth consistent; calibration valid and traceable.

XIII. Multipath & Security (Chs. 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 }
  Invariant: evidence URIs bound to segments/devices; minimum-visibility principle.

XIV. Runtime & End-to-End (Chs. 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 }
  Invariant: signature chain intact; dual forms end-to-end; rollback is replayable.

XV. Error Codes & Semantics (E60-xxx)

• E60-001 InvalidDim: unit/dimension mismatch (check_dim failure).
• E60-002 TwoFormMismatch: dual-form gap exceeds threshold (delta_form_* > tol_*).
• E60-003 UnstableKernel / GuardBreach: conservation or stability/protection gate failure.
• E60-004 ManifestIncomplete / InvalidSignature: missing manifest keys or invalid signature.
• E60-005 ContractViolation: any C60-* not satisfied.
• E60-006 CalExpired / DataStale: calibration expired or data freshness insufficient.
• E60-007 ResourceExceeded / Backpressure: resource or backpressure quota exceeded.
• E60-008 Serialization / DeserializationError.
• E60-009 NotTraceable: missing hash / id / RefCond provenance.

XVI. Versioning & Compatibility

• Minor releases must not change existing parameter names/defaults; new fields must be optional and noted in the manifest changelog.
• Provide a stable canonicalize(manifest) serialization for signing/diff; supply cross-version diff/migration scripts.

XVII. Cross-References

1. The P / S / M / C rules of Chapters 2–15 are the semantic ground truth for these interfaces.
2. Companion volumes:
   • EFT.WP.Metrology.PathCorrection v1.0 (two-form & path correction)
   • EFT.WP.Metrology.TimeBase v1.0 and …Sync v1.0 (timebase/synchronization)
   • EFT.WP.Metrology.Instrument v1.0 (metrology/calibration)

Summary

• This appendix delivers the complete I60-* interface suite, constraints, and error semantics: dual-form parallelism, dimensional audit, manifest persistence, and replayable evidence are mandatory for all implementations.
• In concert with each chapter’s P/S/M/C, engineering teams can realize an end-to-end, reproducible, and rollback-capable Packets.Light pipeline—from physical modeling to runtime release.