18-EFT.WP.Methods.CrossStats v1.0 | Appendix A — Interface Reference (I30 Full Set)

Home ／ Docs-Technical WhitePaper ／ 18-EFT.WP.Methods.CrossStats v1.0

Appendix A — Interface Reference (I30 Full Set)

One-line objective: Consolidate the I30-* interfaces in this volume—their signatures, parameters, returns, and invariants—and define mapping conventions to DataSpec/Sea/Threads/Methods.Cleaning/Methods.Imaging.

I. General Rules & Conventions

1. Versioning & Naming
   • Interfaces follow the unified style I30-xx name(args) -> out, with sub-ranges by domain: 00–09 basics/alignment, 10–19 estimation & uncertainty, 20–29 drift/experimentation, 30–39 causality/calibration, 40–49 audit/compliance.
   • Semantic versioning major.minor.patch; minor/patch are backward compatible.
2. Inputs, Outputs & Units
   • Any physical field entering computation must declare unit(x) and dim(x); callers should pass check_dim(expr) beforehand (see Methods.Cleaning v1.0, Chapter 4).
   • Windowed statistics are always computed on tau_mono; publish on ts with offset/skew/J (see Methods.Cleaning v1.0, Chapter 5).
3. Streaming vs. Batch
   Batch interfaces return snapshot objects; streaming interfaces return an iterator or callback handle and include TraceID and signature.
4. Traceability & Signatures
   Carry TraceID, repro_hash, and signature consistently; outputs must be written into manifest.stats.* (keys per this volume’s Appendix C).
5. Invariants & General Contracts
   • sum(w_i)/N ≈ 1 (weight normalization).
   • alpha_spent ≤ alpha_budget (multiple/sequential control).
   • If T_arr is involved, record both formulations in parallel and assert delta_form ≤ tol_Tarr.
   • Failures map to severity ∈ {info, warn, error, fatal} with rollback strategies (see Chapter 14).

II. Common Types & Keys

• Data & weights: ds, schema, w: R^N.
• Models & posteriors: model, posterior, priors.
• Plans & reports: plan, cv_report, drift_report, ab_decision, audit_log.
• Policies & budgets: slo_policy, alpha_budget, alpha_spending.
• Manifest: manifest.stats with window.Delta_t, TraceID, contracts, results.

III. Function Catalog (At a Glance)

• Basics/Alignment: I30-01 time_align_for_stats
• Estimation & Uncertainty: I30-11 compute_weights, I30-13 fit_glm, I30-14 fit_bayes, I30-15 bootstrap_metric, I30-16 cross_validate
• Contracts & Manifests: I30-17 evaluate_stat_contracts, I30-18 emit_stats_manifest
• Drift/Experimentation: I30-21 detect_drift, I30-22 run_ab_test, I30-23 sequential_glrt, I30-24 track_alpha_spending, I30-25 latency_summary
• Causality/Calibration: I30-31 estimate_ate, I30-32 calibration_transfer, I30-33 calibration_report, I30-34 backtest_coverage
• Audit: I30-41 compute_slo_attainment, I30-42 audit_decision

IV. Interface Details

1. I30-01 time_align_for_stats(ds, sync_ref) -> ds'
   • Purpose: Align ds to tau_mono; compute and attach offset/skew/J; when relevant, record the two T_arr formulations and delta_form.
   • Params: ds, sync_ref ∈ {clock, beacon, event}.
   • Returns: ds' with fields tau_mono, timing.{offset,skew,J}, arrival.{form1,form2,delta_form}.
   • Invariants: non_decreasing(tau_mono); delta_form ≤ tol_Tarr.
   • Cross-ref: Methods.Cleaning v1.0, Chapters 5–6.
2. I30-11 compute_weights(ds, scheme) -> w
   • Purpose: Produce sampling/exposure weights; scheme ∈ {SRS, STRAT, CLUSTER, IPW}.
   • Returns: w and normalization summary W_norm = ( ∑ w_i ) / N.
   • Contracts: |W_norm - 1| ≤ tol_w; max(w)/min(w) ≤ cap_w.
   • Cross-ref: Chapter 3.
3. I30-13 fit_glm(ds, formula, family) -> model
   • Purpose: Fit a GLM and return coefficients and covariance.
   • Params: family ∈ {gaussian, binomial, poisson, gamma}.
   • Invariants: Score equations converge; Hessian is PSD or regularized.
   • Cross-ref: Chapter 4.
4. I30-14 fit_bayes(ds, model_spec, priors) -> posterior
   • Purpose: Bayesian fitting; return posterior samples and summaries.
   • Contracts: r_hat ≤ 1.1, effective sample size ESS ≥ ESS_min.
   • Cross-ref: Chapter 4.
5. I30-15 bootstrap_metric(fn, ds, B) -> {est, CI, dist}
   • Purpose: Bootstrap estimation of a metric and its interval.
   • Returns: est, CI = [q_low, q_high], optional dist samples.
   • Invariants: B ≥ B_min; with stratified sampling, resample within strata.
6. I30-16 cross_validate(model, ds, K, metric) -> cv_report
   • Purpose: K-fold cross-validation; report mean, variance, and variance decomposition.
   • Contracts: K ≥ 3; data leakage checks pass.
   • Cross-ref: Chapter 5.
7. I30-17 evaluate_stat_contracts(metrics, rules) -> report
   • Purpose: Execute C30-* contracts; emit per-item pass/fail with severity.
   • Invariants: Contract definitions and metric windows align (metrics.window == rules.window).
   • Cross-ref: Chapter 14 and Appendix B.
8. I30-18 emit_stats_manifest(results, policy) -> manifest.stats
   • Purpose: Generate an auditable manifest with TraceID, repro_hash, contracts, and sign.
   • Contracts: signature verifiable; key alignment with data manifests (see Methods.Cleaning v1.0, Appendix C).
9. I30-21 detect_drift(ref, cur, methods) -> drift_report
   • Purpose: Compute W1, KL, psi, binned chi-square, etc.; label drift_level/drift_slope.
   • Contracts: W1 ≤ W1_max ∧ KL ≤ KL_max ∧ psi ≤ psi_max, otherwise alert.
   • Cross-ref: Chapter 7.
10. I30-22 run_ab_test(stream, metric, alpha_spending) -> ab_decision
    • Purpose: Online A/B (or multi-arm) experimentation with alpha_spending ∈ {OBF, Pocock, alpha-investing}.
    • Returns: decision ∈ {ship, rollback, continue}, alpha_spent, sequence S_t.
    • Invariants: alpha_spent ≤ alpha_budget; latency_ms_p99 ≤ SLO.latency_p99_max.
    • Cross-ref: Chapter 8, Appendix D.
11. I30-23 sequential_glrt(stream, H0, H1, h) -> stop_time
    • Purpose: Sequential GLRT; return stopping time and conclusion.
    • Contracts: Trigger rule tau = inf{ t : S_t ≥ h_upper or S_t ≤ h_lower }.
    • Cross-ref: Chapter 6.
12. I30-24 track_alpha_spending(seq_tests) -> budget_state
    • Purpose: Track alpha consumption across a sequence of tests.
    • Invariants: alpha_spent(t) is non-decreasing; overflow ⇒ fatal.
13. I30-25 latency_summary(traces) -> {p50, p95, p99}
    • Purpose: Latency quantiles for statistical services.
    • Contracts: p99 ≤ SLO.latency_p99_max; anomalous spikes must attach an audit_log.
    • Cross-ref: Chapter 14.
14. I30-31 estimate_ate(ds, method) -> {ATE, U, diag}
    • Purpose: Estimate ATE/ATT/CATE; method ∈ {PSM, IPW, DR, IV}.
    • Invariants: Overlap min(ps(x)), min(1-ps(x)) ≥ eps; balance passes (standardized differences within thresholds).
    • Cross-ref: Chapter 10.
15. I30-32 calibration_transfer(src, dst, method) -> map
    • Purpose: Cross-domain calibration transfer; method ∈ {Platt, Isotonic, BBQ}.
    • Invariants: Mapping is monotone; ECE_after ≤ ECE_before - delta_min.
    • Cross-ref: Chapter 9.
16. I30-33 calibration_report(pred, obs, bins) -> {ECE, Brier, curves}
    • Purpose: Produce a calibration report with equal-quantile/equal-frequency binning curves.
    • Contracts: bins ≥ 10 and per-bin sample counts ≥ minimum.
    • Cross-ref: Chapters 4 and 9.
17. I30-34 backtest_coverage(ds, plan) -> {coverage_rate, CI}
    • Purpose: Backtest interval coverage over historical windows.
    • Contracts: coverage_rate ≥ SLO.coverage_min; otherwise trigger model revision.
    • Cross-ref: Chapters 4 and 14.
18. I30-41 compute_slo_attainment(metrics, slo) -> attainment
    • Purpose: Compute SLO attainment for statistical services (coverage, FDR, latency, etc.).
    • Invariants: Window alignment on Delta_t; missingness flagged via m ∈ {0,1}.
    • Cross-ref: Chapter 14.
19. I30-42 audit_decision(trace, manifest) -> audit_log
    • Purpose: Consolidate decision evidence; persist an audit log bound to signature.
    • Contracts: audit_log.hash == repro_hash; must be replayable for full reproduction.
    • Cross-ref: Chapter 15, Appendix C.

V. Cross-Volume Mappings & Dependencies

• With EFT.WP.Core.DataSpec v1.0
  Field registration and aliasing are handled by standardize_names; interfaces assume schema compliance.
• With EFT.WP.Core.Sea v1.0
  Streaming inputs must implement backpressure semantics and respect chan/cap/q_len (see Core.Threads).
• With EFT.WP.Core.Threads v1.0
  Streaming interfaces must be idempotent and retryable; provide resume_from(TraceID, offset).
• With Methods.Cleaning v1.0
  Unit normalization, dimensional checks, and time-base alignment are prerequisites (Chapters 4–5); the dual T_arr formulations are hard constraints (Chapter 6).
• With Methods.Imaging v1.0
  Imaging statistics must declare radiometric units and calibration gauges (Chapter 4) and reuse this volume’s SLOs in the quality panel.

VI. Error Codes & Remedies (Excerpt)

• E-I30-ARGS: invalid parameters; action = error, refuse execution.
• E-I30-DIM: dimensional conflict; action = error, advise repair_units.
• E-I30-TIMEBASE: time-base not aligned; action = error, run I30-01 first.
• E-I30-ALPHA: alpha_spent > alpha_budget; action = fatal, terminate the experiment.
• E-I30-DRIFT: drift beyond thresholds; action = warn/error, enter rollback or lock promotion.
• E-I30-COVERAGE: coverage below target; action = error, block publication.
• E-I30-ARRIVAL: delta_form > tol_Tarr; action = fatal, halt related statistical releases.

VII. Versioning & Compatibility Guidance

• I30-22 run_ab_test supports multi-arm since 1.1.0; alpha_spending adds alpha-investing.
• I30-32 calibration_transfer supports BBQ since 1.2.0; older versions default to Platt.
• Any newly added statistic must register its key path in emit_stats_manifest and add a corresponding C30-* template in Appendix B (contract library).

Summary