18-EFT.WP.Methods.CrossStats v1.0 | 附录A 接口参考（I30 全集）

目录 ／ 文档-技术白皮书 ／ 18-EFT.WP.Methods.CrossStats v1.0

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

一句话目标：汇总本卷 I30-* 接口的签名、参数、返回与不变量，并给出与 DataSpec/Sea/Threads/Methods.Cleaning/Methods.Imaging 的映射约定。

I. 总则与约定

1. 版本与命名
   • 接口统一命名 I30-xx name(args) -> out，以次级编号分域：00-09 基础/对齐，10-19 估计与不确定度，20-29 漂移/实验，30-39 因果/校准，40-49 审计/合规。
   • 语义化版本 major.minor.patch；minor/patch 后向兼容。
2. 输入输出与单位
   • 所有进入计算的物理字段必须声明 unit(x) 与 dim(x)，调用前应通过 check_dim(expr)（见《Methods.Cleaning v1.0》第4章）。
   • 窗口化统计一律在 tau_mono 上计算，对外以 ts 发布，附 offset/skew/J（见《Methods.Cleaning v1.0》第5章）。
3. 流式与批式
   批式接口返回快照对象；流式接口返回可迭代或回调句柄，并包含 TraceID 与 signature。
4. 追溯与签名
   统一携带 TraceID, repro_hash, signature；产出需写入 manifest.stats.*（键名见本卷附录C）。
5. 不变量与通用契约
   • sum(w_i)/N ≈ 1（加权归一）。
   • alpha_spent ≤ alpha_budget（多重/序贯）。
   • 若涉及 T_arr，必须并行记录两口径并断言 delta_form ≤ tol_Tarr。
   • 失败映射到 severity ∈ {info, warn, error, fatal} 与回退策略（见第14章）。

II. 公共类型与键

• 数据与权重：ds, schema, w: R^N。
• 模型与后验：model, posterior, priors。
• 计划与报告：plan, cv_report, drift_report, ab_decision, audit_log。
• 策略与预算：slo_policy, alpha_budget, alpha_spending。
• 清单：manifest.stats，含 window.Delta_t, TraceID, contracts, results.

III. 函数目录速览

• 基础/对齐：I30-01 time_align_for_stats
• 估计与不确定度：I30-11 compute_weights, I30-13 fit_glm, I30-14 fit_bayes, I30-15 bootstrap_metric, I30-16 cross_validate
• 契约与清单：I30-17 evaluate_stat_contracts, I30-18 emit_stats_manifest
• 漂移/实验：I30-21 detect_drift, I30-22 run_ab_test, I30-23 sequential_glrt, I30-24 track_alpha_spending, I30-25 latency_summary
• 因果/校准：I30-31 estimate_ate, I30-32 calibration_transfer, I30-33 calibration_report, I30-34 backtest_coverage
• 审计：I30-41 compute_slo_attainment, I30-42 audit_decision

IV. 接口详解

1. I30-01 time_align_for_stats(ds, sync_ref) -> ds'
   • 作用：将 ds 对齐到 tau_mono，计算并附带 offset/skew/J；必要时记录 T_arr 两口径与 delta_form。
   • 参数：ds, sync_ref ∈ {clock, beacon, event}。
   • 返回：ds'（新增 tau_mono, timing.{offset,skew,J}, arrival.{form1,form2,delta_form}）。
   • 不变量：non_decreasing(tau_mono)；delta_form ≤ tol_Tarr。
   • 交叉：见《Methods.Cleaning v1.0》第5、6章。
2. I30-11 compute_weights(ds, scheme) -> w
   • 作用：生成抽样/暴露权重。scheme ∈ {SRS, STRAT, CLUSTER, IPW}。
   • 返回：w 与归一摘要 W_norm = ( ∑ w_i ) / N。
   • 契约：|W_norm - 1| ≤ tol_w；max(w)/min(w) ≤ cap_w。
   • 交叉：第3章。
3. I30-13 fit_glm(ds, formula, family) -> model
   • 作用：拟合 GLM，返回系数与协方差。
   • 参数：family ∈ {gaussian, binomial, poisson, gamma}。
   • 不变量：得分方程收敛；Hessian 正定或给出正则项。
   • 交叉：第4章。
4. I30-14 fit_bayes(ds, model_spec, priors) -> posterior
   • 作用：贝叶斯拟合，返回后验样本与摘要。
   • 契约：r_hat ≤ 1.1，有效样本数 ESS ≥ ESS_min。
   • 交叉：第4章。
5. I30-15 bootstrap_metric(fn, ds, B) -> {est, CI, dist}
   • 作用：自助法估计指标与区间。
   • 返回：est, CI = [q_low, q_high], dist（可选样本）。
   • 不变量：B ≥ B_min；若分层抽样则遵循层内重采样。
6. I30-16 cross_validate(model, ds, K, metric) -> cv_report
   • 作用：K 折交叉验证；报告均值、方差与方差分解。
   • 契约：K ≥ 3；数据泄漏检测通过。
   • 交叉：第5章。
7. I30-17 evaluate_stat_contracts(metrics, rules) -> report
   • 作用：执行 C30-* 契约；输出逐项通过/失败与严重性。
   • 不变量：契约定义与度量窗口一致（metrics.window == rules.window）。
   • 交叉：第14章与附录B。
8. I30-18 emit_stats_manifest(results, policy) -> manifest.stats
   • 作用：生成可审计清单，包含 TraceID, repro_hash, contracts, sign.
   • 契约：signature 可验证；与数据清单键对齐（见《Methods.Cleaning v1.0》附录C）。
9. I30-21 detect_drift(ref, cur, methods) -> drift_report
   • 作用：计算 W1, KL, psi, 分箱卡方等；标注 drift_level/drift_slope。
   • 契约：W1 ≤ W1_max ∧ KL ≤ KL_max ∧ psi ≤ psi_max 或触发告警。
   • 交叉：第7章。
10. I30-22 run_ab_test(stream, metric, alpha_spending) -> ab_decision
    • 作用：在线 A/B（或多臂）试验，支持 alpha_spending ∈ {OBF, Pocock, alpha-investing}。
    • 返回：decision ∈ {ship, rollback, continue}, alpha_spent, S_t 序列。
    • 不变量：alpha_spent ≤ alpha_budget；latency_ms_p99 ≤ SLO.latency_p99_max。
    • 交叉：第8章、附录D。
11. I30-23 sequential_glrt(stream, H0, H1, h) -> stop_time
    • 作用：序贯 GLRT，返回停序时刻与结论。
    • 契约：触发条件 tau = inf{ t : S_t ≥ h_upper or S_t ≤ h_lower }。
    • 交叉：第6章。
12. I30-24 track_alpha_spending(seq_tests) -> budget_state
    • 作用：跨一系列检验追踪 alpha 消耗。
    • 不变量：alpha_spent(t) 单调不减；溢出即 fatal。
13. I30-25 latency_summary(traces) -> {p50, p95, p99}
    • 作用：统计服务延迟分位。
    • 契约：p99 ≤ SLO.latency_p99_max；异常峰值需伴随 audit_log。
    • 交叉：第14章。
14. I30-31 estimate_ate(ds, method) -> {ATE, U, diag}
    • 作用：估计 ATE/ATT/CATE。method ∈ {PSM, IPW, DR, IV}。
    • 不变量：重叠性 min(ps(x)), min(1-ps(x)) ≥ eps；平衡性通过（标准化差值阈内）。
    • 交叉：第10章。
15. I30-32 calibration_transfer(src, dst, method) -> map
    • 作用：跨域校准迁移，method ∈ {Platt, Isotonic, BBQ}。
    • 不变量：map 单调；ECE_after ≤ ECE_before - delta_min。
    • 交叉：第9章。
16. I30-33 calibration_report(pred, obs, bins) -> {ECE, Brier, curves}
    • 作用：生成校准报告与等分位/等频分箱曲线。
    • 契约：bins ≥ 10 且每箱样本数 ≥ 下限。
    • 交叉：第4/9章。
17. I30-34 backtest_coverage(ds, plan) -> {coverage_rate, CI}
    • 作用：以历史窗口回测区间覆盖度。
    • 契约：coverage_rate ≥ SLO.coverage_min；不满足触发模型修订。
    • 交叉：第4/14章。
18. I30-41 compute_slo_attainment(metrics, slo) -> attainment
    • 作用：计算统计服务 SLO 达成度（覆盖度、FDR、latency 等）。
    • 不变量：窗口对齐 Delta_t；缺失以 m ∈ {0,1} 明示。
    • 交叉：第14章。
19. I30-42 audit_decision(trace, manifest) -> audit_log
    • 作用：汇总决策证据，落盘审计日志，绑定 signature。
    • 契约：audit_log.hash == repro_hash；可重放复现。
    • 交叉：第15章、附录C。

V. 交叉卷映射与依赖

• 与《EFT.WP.Core.DataSpec v1.0》
  字段注册与别名映射由 standardize_names 完成；接口假定 schema 合规。
• 与《EFT.WP.Core.Sea v1.0》
  流式输入需实现背压语义，尊重 chan/cap/q_len（详见《Core.Threads》）。
• 与《EFT.WP.Core.Threads v1.0》
  流式接口必须幂等且可重试；提供 resume_from(TraceID, offset)。
• 与《Methods.Cleaning v1.0》
  单位归一、量纲校核与时基对齐作为前置（第4、5章）；到达时两口径作为硬约束（第6章）。
• 与《Methods.Imaging v1.0》
  成像统计需声明辐射单位与标定口径（第4章），并在质量面板复用本卷 SLO。

VI. 错误码与处置（节选）

• E-I30-ARGS：参数非法；处置 error，拒绝执行。
• E-I30-DIM：量纲冲突；处置 error，建议调用 repair_units。
• E-I30-TIMEBASE：时基未对齐；处置 error，先执行 I30-01。
• E-I30-ALPHA：alpha_spent > alpha_budget；处置 fatal，终止试验。
• E-I30-DRIFT：漂移超阈；处置 warn/error，进入回退或锁定推广。
• E-I30-COVERAGE：覆盖度不达标；处置 error，阻断发布。
• E-I30-ARRIVAL：delta_form > tol_Tarr；处置 fatal，停止相关统计发布。

VII. 版本与兼容性指引

• I30-22 run_ab_test 自 1.1.0 起支持多臂；alpha_spending 新增 alpha-investing。
• I30-32 calibration_transfer 自 1.2.0 起支持 BBQ；旧版默认 Platt。
• 任何新增统计量必须在 emit_stats_manifest 中注册键路径，并在附录B 契约库添加对应 C30-* 模板。

小结