19-EFT.WP.Methods.SynthData v1.0 | 附录A 接口参考（I40 全集）

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

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

I. 说明与适用范围

• 本附录汇总 I40-* 接口的签名、参数、返回与不变量，覆盖离线与流式两类合成数据流水线。
• 与其他卷的接口映射固定写法：“见《EFT.WP.Core.*》/《Methods.Cleaning》/《Methods.Imaging》/《Methods.CrossStats》… 第x章 S/P/M/I…”。

II. 统一约定与命名

• 接口编号：I40-kk，其中 kk 为两位或三位序号；破坏性变更需递增主版本。
• 时基口径：内部统一 tau_mono，对外发布 ts；到达时两口径并行记录 T_arr 与 delta_form。
• 量纲与单位：任何涉及物理量的参数/返回，必须显式声明 unit(x) 与 dim(x) 并通过 check_dim(expr)。
• 隐私会计：凡带差分隐私开关的接口，需上报 eps, delta，并接入全局 privacy_accountant。
• 幂等与可追溯：凡写入型接口须接受 TraceID 与 seed，保证 reproducible(seed) 与幂等重放。

III. 公共类型与字段

• SynthSpec：{schema_ref, fields[], constraints[], goals, eps_budget, seed}。
• Engine：{model, version, params, privacy, training_meta}。
• DS：数据集句柄或快照；包含 rid/pid, ts|tau_mono, m, q_score。
• ManifestSynth：{TraceID, seed, eps_total, metrics.*, contracts.*, signature}。
• ContractRule：{name, expr, tol, severity}。
• MetricReport：{W1, MMD, FID, KID, covg, utility_gap, u(metric)}。
• PrivacyReport：{eps_total, delta_total, MI_risk, attacks[]}。
• TimepathMeta：{T_arr_form1, T_arr_form2, delta_form, offset, skew, J}。

IV. 接口目录与签名

1. I40-31 design_synth_spec(schema, goals, constraints, eps_budget, seed) -> SynthSpec
   • 说明：依据模式与目标生成可执行合成规格。
   • 输入：schema，goals，constraints[]，eps_budget，seed。
   • 输出：SynthSpec。
   • 不变量：unique(fields.name)；eps_budget ≥ 0；check_dim(constraints) 全通过。
   • 错误：E.BAD_SCHEMA, E.CONSTRAINT_CONFLICT, E.BUDGET_INVALID。
   • 交叉引用：见《Core.DataSpec》模式注册接口。
2. I40-32 register_schema(SynthSpec) -> schema_ref
   • 说明：向注册表登记合成模式。
   • 不变量：hash_sha256(schema) = schema_ref；version 单调递增。
   • 交叉引用：见《Core.DataSpec》注册/校验流。
3. I40-33 validate_dataset(ds, schema_ref) -> report
   • 说明：按 schema_ref 校验 ds 的类型、可空、主外键与范围。
   • 不变量：unique(pk)；foreign_key 全通过或标注 severity。
4. I40-41 fit_engine(ds, model, priors_or_arch, privacy) -> Engine
   • 说明：训练统计/深度/仿真引擎。
   • 输入：model ∈ {copula, glm, rule, vae, gan, flow, diffusion, scm}；privacy = {eps, delta}|null。
   • 输出：Engine。
   • 不变量：training_meta.seed 已落盘；若启用 DP，则 eps ≥ 0, delta ∈ (0,1)。
   • 错误：E.TRAIN_DIVERGE, E.DP_CONFIG, E.INSUFFICIENT_DATA。
5. I40-42 update_engine(engine, patch) -> Engine'
   • 说明：小步更新参数或架构；记录 version 与 changelog。
   • 不变量：compat(Engine, Engine') = true 或强制新主版本。
6. I40-52 sample(engine, n, condition, seed) -> ds_syn
   • 说明：从引擎采样生成数据；支持条件化。
   • 输入：n > 0，condition|null，seed。
   • 输出：ds_syn。
   • 不变量：size(ds_syn) = n；reproducible(seed)；sum(weights)/n ≈ 1（如生成含权重）。
7. I40-61 enforce_constraints(ds_syn, rules) -> ds_syn'
   • 说明：执行唯一性、外键、范围、物理守恒等约束。
   • 不变量：unique(pk)；foreign_key；check_dim(expr)；冲突记录在 report.violations[]。
   • 错误：E.CONSTRAINT_VIOLATION（可配置为修复/隔离/失败）。
8. I40-62 align_timepath(ds_syn, ref) -> (ds_syn', TimepathMeta)
   • 说明：写入 T_arr 两口径、offset/skew/J 与 delta_form，并对齐 tau_mono → ts。
   • 不变量：delta_form ≤ tol_Tarr；non_decreasing(tau_mono)。
9. I40-71 compose_multimodal(syn_specs, coherence_rules) -> bundle
   • 说明：装配多模态子集并执行跨模态一致性校核。
   • 不变量：coherence(pass)=true；若失败，输出冲突图 G_conflict。
10. I40-81 balance_distribution(ref, syn, method) -> map
    • 说明：通过 reweight|mapping|domain_randomization 配平分布差异。
    • 输出：map（含 w(x) 或映射参数）。
    • 不变量：effective_n = ( (∑ w)^2 ) / ( ∑ w^2 ) ≥ n_min。
11. I40-91 measure_fidelity(real, syn, metrics) -> MetricReport
    • 说明：评估 W1|MMD|FID|KID|covg|downstream_metric。
    • 不变量：指标定义的核/带宽/特征口径落盘 metrics.spec。
12. I40-101 measure_privacy(real, syn, attacks, eps_delta) -> PrivacyReport
    • 说明：评估 MI/linkability/attribute 等风险；汇总 eps_total, delta_total。
    • 不变量：eps_total ≤ eps_budget；攻击集与会计口径落盘。
13. I40-111 watermark_and_provenance(ds_syn, scheme) -> (ds_syn', manifest_addendum)
    • 说明：嵌入水印与溯源标记；输出附加清单段。
    • 不变量：scheme ∈ {fragile, robust}；鲁棒性与误检率基准已记录。
14. I40-121 assert_synth_contract(ds_syn, rules) -> report
    • 说明：执行 C40-* 契约集合（保真/效用/隐私/时基/量纲）。
    • 不变量：所有 severity="blocker" 条目必须通过。
15. I40-131 freeze_release_synth(ds_syn, tag) -> ManifestSynth
    • 说明：冻结版本并生成可审计清单，签名发布。
    • 不变量：signature 有效；hash_sha256(blob) 与落盘一致。
16. I40-141 stream_synth(engine, qos, rate_limit, backpressure) -> stream_handle
    • 说明：建立流式生成服务，支持背压与限流。
    • 不变量：稳态 rho = lambda_in / mu_eff < 1；latency_ms_p99 ≤ qos.target。
17. I40-151 privacy_accountant(events) -> {eps_total, delta_total}
    • 说明：对训练/采样/查询等事件进行隐私预算会计。
    • 不变量：组合会计与高级会计口径一致；越界触发 policy.fuse。
18. I40-161 emit_runtime_manifest(stream_handle, window) -> manifest.runtime
    • 说明：按窗口导出运行期清单（SLO、漂移、预算与到达时）。
    • 字段：TS.sli.rho, latency_p99, drop_rate, eps_total, delta_form。
19. I40-171 detect_drift(ref, cur, metrics) -> drift_report
    • 说明：桥接漂移检测；{W1, KL, psi, pvals}。
    • 交叉引用：见《Methods.CrossStats》对应接口。
20. I40-181 run_ab_test(stream, metric, alpha_spending) -> decision
    • 说明：桥接在线实验；支持序贯 alpha 花费策略。
    • 交叉引用：见《Methods.CrossStats》第8章接口。
21. I40-191 emit_synth_manifest(results, policy) -> ManifestSynth
    • 说明：将离线评估/契约结果装配为发布清单（非冻结）。
    • 不变量：manifest.version 单调；与 freeze_release_synth 互斥或先于之。

V. 错误码与异常协议

1. 标准错误前缀 E.*
   • E.BAD_SCHEMA，E.CONSTRAINT_CONFLICT，E.BUDGET_INVALID。
   • E.TRAIN_DIVERGE，E.DP_CONFIG，E.INSUFFICIENT_DATA。
   • E.CONSTRAINT_VIOLATION，E.TIMEPATH_MISMATCH，E.DRIFT_EXCEEDED。
   • E.SLO_BREACH，E.PRIVACY_BREACH，E.SIGNATURE_INVALID。
2. 处理语义
   • 默认 severity ∈ {info, warn, block}；block 触发熔断或回退。
   • 所有异常需写入 manifest.logs.* 并绑定 TraceID。

VI. 合同映射与不变量

• 保真与效用：W1 ≤ W1_max，MMD ≤ mmd_max，FID|KID ≤ fid_max，utility_gap ≤ gap_max。
• 隐私：eps_total ≤ eps_budget，delta_total ≤ delta_budget。
• 时基与到达时：non_decreasing(tau_mono)，delta_form ≤ tol_Tarr。
• 量纲：check_dim(expr) 全通过。
• 流式：rho < 1，latency_ms_p99 ≤ target_p99，drop_rate ≤ tol_drop。

VII. 流式语义与背压协同

• 背压：stream_synth 必须公开 chan/cap/q_len；超阈触发 rate_limit 或 auto_batcher。
• 幂等：以 TraceID+seed 作为幂等键；重复请求不得生成差异样本。
• 冷启动：允许 warmup_batches，期间指标独立统计并标注 warmup=true。

VIII. 安全、隐私与审计

• 差分隐私：所有带 privacy 的训练与采样事件纳入 privacy_accountant，并将 eps_total 写入清单。
• 水印与溯源：对外发布前必须执行 watermark_and_provenance；提供检验子程序引用。
• 签名：freeze_release_synth 生成 signature，用于端到端追溯与防篡改。

IX. 交叉引用

• 模式与清单：见《EFT.WP.Core.DataSpec v1.0》模式注册与清单规范。
• 时间与到达时：见《Methods.Cleaning v1.0》时间轴与到达时章节。
• 成像口径：见《Methods.Imaging v1.0》计量、PSF/MTF、几何与 HDR 章节。
• 统计评估与实验：见《Methods.CrossStats v1.0》漂移、A/B 与 SLO 章节。

X. 示例调用序列（参考）

1. 离线发布
   design_synth_spec → register_schema → validate_dataset → fit_engine → sample → enforce_constraints → align_timepath → measure_fidelity/measure_privacy → assert_synth_contract → freeze_release_synth。
2. 流式运行
   fit_engine → stream_synth → privacy_accountant（持续）→ detect_drift（持续）→ emit_runtime_manifest（周期）→ 越界触发回退或熔断。