25-EFT.WP.STG.Dynamics v1.0 | 附录A 接口参考（I70 全集）

目录 ／ 文档-技术白皮书 ／ 25-EFT.WP.STG.Dynamics v1.0

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

一句话目标：汇总本卷实现绑定 I70-* 的完整接口原型、参数与不变量，确保跨团队、跨环境的可移植与可审计实现。

I. 通用约定与类型

1. 统一时间与哈希
   • tau_mono（单调时基）、ts（事件/观测时）、t_proc（处理时）；
   • graph.hash, L.hash, A.hash, H.hash, model.hash, policy.hash, manifest.hash。
2. 通用数据结构（伪类型）
   • Graph = {V: list[node], E: list[edge], attr: dict}
   • Op = {type, params, hash}（如 L/A/H/核 g(L)）
   • Signal = {TraceID, ts, y, unit, RefCond, meta}
   • WindowSpec = {type ∈ {tumbling, sliding, session}, Δt_win, Δt_slide, lateness_max}
   • Watermark = {wm: callable, state}
   • Contracts = {rules: dict, tol: dict}
   • Manifest = {keys: dict, artifacts: dict, signature}
3. 量纲与单位
   任一输入字段声明 unit(x), dim(x)；所有实现须显式调用 check_dim(y - f(x))。
4. 错误码（建议枚举）
   E_UNIT, E_DIM, E_HASH_MISMATCH, E_CONTRACT_BREACH, E_TIMEOUT, E_MEMORY, E_CONVERGENCE, E_VERSION.

II. 图与算子构建 I70-01x

1. I70-011 build_graph(sources, layers, policy) -> Graph
   • Args: sources（OSM/SCADA/PMU…）, layers（多源叠加策略）, policy（清洗/对齐）。
   • Returns: Graph（含 graph.hash）。
   • 不变量：|V|>0, |E|≥|V|-1, non_decreasing(tau_mono)。
2. I70-012 build_operators(graph, kind) -> {L, A, H}
   • Args: kind ⊆ {laplacian, adjacency, observation}。
   • Returns: 拉普拉斯 L、邻接 A、观测矩阵/算子 H。
   • 不变量：L 对称半正定；A≥0；hash 可追溯。
3. I70-013 estimate_refcond(ds) -> RefCond
   • 功能：从运行期元数据估计参考条件。
   • 不变量：RefCond 落盘；与单位一致。

III. 图核与滤波算子 I70-11x

1. I70-111 assemble_kernel(L, mode, hyper) -> Op
   • Args: mode ∈ {diff, wave, mix}, hyper = {τ, ω, α, order}。
   • Returns: 核 K（显式或近似，如切比雪夫）。
   • 不变量：谱半径可控；数值稳定区间已校核。
2. I70-112 graph_filter(x, K) -> x'
   • Args: 图信号 x，核/滤波器 K。
   • 不变量：check_dim(x'-x)=unit(x)；若 K 标称守恒则 sum(x')≈sum(x)。

IV. 动力学推进与物理约束 I70-21x

1. I70-211 propagate(x, u, K, Δt, noise=None) -> x_next
   • 模型：x_{k+1} = Φ_{Δt}(x_k, u_k; K)。
   • 不变量：Δt>0；刚性判别与步长自适应可选。
2. I70-212 enforce_physical(x, constraints) -> x_proj
   • 功能：守恒 B x = s、非负与范围投影。
   • 不变量：||B x_proj - s|| ≤ ε_cons。

V. 同化与滤波 I70-31x

• I70-311 filter_kf(y_stream, F, H, Q, R, x0, P0) -> {x̂, P}
• I70-312 filter_ukf(y_stream, f, h, Q, R, x0, P0, κ) -> {x̂, P}
• I70-313 filter_pf(y_stream, f, h, Q, R, Np, resample) -> {x̂, ESS}
  不变量：P ≽ 0；NIS/ESS 指标落盘；单位一致。

VI. 动力学识别与学习 I70-41x

• I70-411 identify_sindy(X, dXdt, Θ, λ) -> model.hash
• I70-412 identify_koopman(X, φ, rank) -> {K, φ}
• I70-413 train_pinn(data, loss, arch, hp) -> model.hash
• I70-414 fit_gnode(ds, graph, arch, hp) -> model.hash
  不变量：训练/验证分割记录；model.hash 可复现。

VII. 可控与可观 I70-51x

• I70-511 controllability_metrics(F, B) -> {rank, gramian}
• I70-512 observability_metrics(F, H) -> {rank, gramian}
• I70-513 place_sensors(graph, budget, criterion) -> S*
  不变量：量纲与谱半径审计；结果与 graph.hash 绑定。

VIII. 数值积分与事件 I70-61x

• I70-611 integrate_ode(f, x0, grid, solver, tol) -> x_path
  支持 solver ∈ {RK45, BDF, StrangSplit}，事件回调。
• I70-612 event_handler(events, policy) -> actions
  不变量：事件序列按 tau_mono 单调；误差预算落盘。

IX. 因果与干预 I70-71x

• I70-711 learn_invariant(ds_multi_env, graph, hp) -> inv_model
• I70-712 counterfactual(x, u_cf, model) -> x_cf
  不变量：环境标签与干预集记录；版本可追溯。

X. 多尺度与粗化 I70-81x

• I70-811 coarsen_graph(graph, k, preserve) -> graph'
  preserve ∈ {spectrum, cuts, flows}。
• I70-812 lift_restrict(x, P_down, P_up) -> {x_coarse, x_fine}
  不变量：谱偏差界或守恒误差界落盘。

XI. 同化与滤波（图版） I70-91x

• I70-911 build_H_from_sensors(S*, graph) -> H
• I70-912 fuse_multi_modal(y_list, policy) -> y_fused
  不变量：传感器单位与权重合规；融合可追溯。

XII. 不确定度与 guardband I70-13x

• I70-131 propagate_uncertainty(J, Vx, U_num, U_model) -> {u_c, U}
• I70-132 mc_uncertainty(sim, N, seeds) -> stats
• I70-133 compute_guardband(u_c, k, nu_eff, α) -> g
  不变量：两口径并行（LPU/MC）并记录 delta_form_unc。

XIII. 运行时与流式 I70-14x（第14章已部分定义，这里汇总）

• I70-141 build_window_op(type, Δt_win, Δt_slide, φ) -> WOP
• I70-142 update_watermark(stream_meta) -> wm(t)
• I70-143 reduce_window(WOP, batch) -> R_W, meta
• I70-144 cache_getput(key, val, policy, ttl) -> {val', hit}
• I70-145 rate_limit(token_bucket, now) -> permit
• I70-146 handle_backpressure(q, λ, μ, policy) -> action
• I70-147 panel_update(metrics) -> snapshot_id
• I70-148 hot_swap_model(model_new) -> ok
• I70-149 replay_gap_fill(range, source) -> patches
• I70-14A assert_runtime_contracts(state, rules) -> report
• I70-14B emit_runtime_manifest(results, policy) -> manifest.stg.runtime
  不变量：wm(t) 单调；幂等键 {TraceID, seq, ts}。

XIV. 用例封装 I70-15x（第15章已定义，这里复述要点）

• I70-151 build_case(domain, layers) -> {graph, L, A, H, meta}
• I70-152 assemble_kernel(L, mode, hyper) -> K
• I70-153 simulate_or_forecast(x0, K, B, u, steps) -> x_path
• I70-154 filter_online(y_stream, model, Q, R) -> {x̂_series, P_series}
• I70-155 enforce_physical(x, constraints) -> x_proj
• I70-156 eval_contracts(outputs, rules) -> report
• I70-157 emit_case_manifest(results, policy) -> manifest.stg.case
  不变量：units/RefCond 落盘；P ≽ 0；hash(*) 一致。

XV. Manifest 与发布 I70-16x

• I70-161 build_manifest(keys, artifacts, policy) -> Manifest
  keys ⊇ {TraceID, graph.hash, L/A/H.hash, model.hash, RefCond, units}。
• I70-162 sign_manifest(manifest, key_id) -> manifest.signature
• I70-163 verify_manifest(manifest, keyring) -> ok
  不变量：签名覆盖全量字段；版本与策略一致。

XVI. 契约断言 I70-17x

• I70-171 assert_dim_units(obj) -> report
• I70-172 assert_two_form(ds_evt, ds_proc, tol) -> {delta_form_stream, pass}
• I70-173 assert_coverage(residuals, α) -> {rate, pass}
• I70-174 assert_slo(runtime_metrics, slo) -> {breaches}
  不变量：所有断言落盘 contracts.report。

XVII. 面板与监控 I70-18x

• I70-181 render_panel(state, layout) -> snapshot_id
• I70-182 export_metrics(series, sink) -> ok
• I70-183 annotate_incident(event, context) -> ticket_id
  不变量：隐私与最小必要记录；时间对齐已校核。

XVIII. 版本与兼容

• 语义化版本：I70-x.y.z；MAJOR 破坏性、MINOR 向后兼容新增、PATCH 修复。
• 弃用策略：@deprecated_since, @remove_in；运行时告警落盘。
• 兼容矩阵：graph.hash 与 model.hash 必须在 manifest 标注；不兼容直接拒绝执行并返回 E_VERSION。

小结

• 本附录提供 I70-* 全集与不变量，覆盖图构建—算子—推进—同化—识别—可控可观—积分—因果—多尺度—不确定度—运行时—用例—发布—契约—面板的端到端接口。
• 任何实现必须：声明单位与量纲、双口径并行并记录差异、落盘 RefCond/Hash/Manifest/Contracts，以确保结果可复现、可审计与可维护。