25-EFT.WP.STG.Dynamics v1.0 | Appendix A — Interface Reference (I70 Suite)

Home ／ Docs-Technical WhitePaper ／ 25-EFT.WP.STG.Dynamics v1.0

Appendix A — Interface Reference (I70 Suite)

One-Sentence Goal
Consolidate the complete set of I70- implementation bindings*, including prototypes, parameters, and invariants, to enable portable and auditable implementations across teams and environments.

I. Global Conventions & Types

1. Unified time & hashing
   • tau_mono (monotone time base), ts (event/observation time), t_proc (processing time).
   • graph.hash, L.hash, A.hash, H.hash, model.hash, policy.hash, manifest.hash.
2. Common data structures (pseudo-types)
   • Graph = { V: list[node], E: list[edge], attr: dict }
   • Op = { type, params, hash } (e.g., L / A / H / kernel 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. Dimensions & units
   Every input declares unit(x), dim(x); implementations must call check_dim( y − f(x) ).
4. Suggested error codes
   E_UNIT, E_DIM, E_HASH_MISMATCH, E_CONTRACT_BREACH, E_TIMEOUT, E_MEMORY, E_CONVERGENCE, E_VERSION.

II. Graph & Operator Construction I70-01x

1. I70-011 build_graph(sources, layers, policy) -> Graph
   • Args: heterogeneous sources (OSM/SCADA/PMU…), layers (fusion policy), policy (clean/align).
   • Returns: Graph with graph.hash.
   • Invariants: |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.
   • Invariants: L symmetric PSD; A ≥ 0; hashes traceable.
3. I70-013 estimate_refcond(ds) -> RefCond
   Role: infer runtime reference conditions; Invariant: persisted and unit-consistent.

III. Graph Kernels & Filters I70-11x

1. I70-111 assemble_kernel(L, mode, hyper) -> Op
   • Args: mode ∈ { diff, wave, mix }, hyper = { τ, ω, α, order }.
   • Returns: kernel K (explicit or approximated, e.g., Chebyshev).
   • Invariants: bounded spectral radius; stability region validated.
2. I70-112 graph_filter(x, K) -> x'
   Invariant: check_dim( x' − x ) = unit(x); if K is conservative, Σ x' ≈ Σ x.

IV. Dynamics & Physical Constraints I70-21x

• I70-211 propagate(x, u, K, Δt, noise=None) -> x_next
  Model: x_{k+1} = Φ_{Δt}(x_k, u_k; K). Invariant: Δt > 0; optional stiffness/stepsize adaptivity.
• I70-212 enforce_physical(x, constraints) -> x_proj
  Conservation B x = s, nonnegativity, box constraints; Invariant: || B x_proj − s || ≤ ε_cons.

V. Assimilation & Filtering 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 }
  Invariants: P ≽ 0; NIS/ESS persisted; unit coherence.

VI. Identification & Learning 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
  Invariants: train/val splits recorded; model.hash reproducible.

VII. Controllability & Observability 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*
  Invariants: dimension checks; spectral radius audited; results bound to graph.hash.

VIII. Numerical Integration & Events I70-61x

• I70-611 integrate_ode(f, x0, grid, solver, tol) -> x_path (solvers: RK45, BDF, StrangSplit; event callbacks)
• I70-612 event_handler(events, policy) -> actions
  Invariants: event sequence monotone in tau_mono; error budgets persisted.

IX. Causality & Intervention I70-71x

• I70-711 learn_invariant(ds_multi_env, graph, hp) -> inv_model
• I70-712 counterfactual(x, u_cf, model) -> x_cf
  Invariants: environment labels & intervention sets recorded; versions traceable.

X. Multiscale & Coarsening 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 }
  Invariants: spectral or conservation error bounds persisted.

XI. Filtering on Graphs I70-91x

• I70-911 build_H_from_sensors(S*, graph) -> H
• I70-912 fuse_multi_modal(y_list, policy) -> y_fused
  Invariants: sensor units/weights coherent; fusion traceable.

XII. Uncertainty & Guardbands 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
  Invariant: dual forms (LPU/MC) in parallel; record delta_form_unc.

XIII. Runtime & Streaming I70-14x (collected from Ch. 14)

XIV. Use-Case Wrappers I70-15x (echoing Ch. 15)

XV. Manifests & Publication I70-16x

• I70-161 build_manifest(keys, artifacts, policy) -> Manifest (keys include { 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
  Invariants: signature covers all fields; versions & policies aligned.

XVI. Contract Assertions 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 }
  Invariant: all assertions persisted to contracts.report.

XVII. Panels & Monitoring 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
  Invariants: privacy & minimal-necessary logging; time alignment verified.

XVIII. Versioning & Compatibility

• Semantic versioning I70-x.y.z: MAJOR breaking, MINOR backward-compatible additions, PATCH fixes.
• Deprecation: @deprecated_since, @remove_in; runtime warnings persisted.
• Compatibility matrix: graph.hash and model.hash are mandatory in manifests; mismatches → E_VERSION.

Summary
This appendix enumerates the complete I70- suite* and invariants spanning graph construction → operators → propagation → assimilation → identification → controllability/observability → integration → causality → multiscale → uncertainty → runtime → use cases → publication → contracts → panels.
Any implementation must: declare units & dimensions, run dual forms and record gaps, and persist RefCond / Hash / Manifest / Contracts—ensuring results are reproducible, auditable, and maintainable.

。