25-EFT.WP.STG.Dynamics v1.0 | Appendix B — Contract Library and Playbooks (C70 Suite)

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

Appendix B — Contract Library and Playbooks (C70 Suite)

One-Sentence Goal
Provide an executable library of C70- contracts* and associated playbooks to govern the full STG lifecycle—data → graph → operators → propagation → assimilation → uncertainty → runtime—ensuring cross-environment consistency and auditability.

I. Scope and Objects

• Objects: data ingestion & units, graph & operators, dynamics & stability, assimilation & filtering, physical consistency, uncertainty & guardbands, dual-form coherence, runtime SLO/SLI, versioning & security.
• Outputs: contracts.rules, contracts.report, manifest.stg.contracts, and playbook execution logs for remediation.
• Constraints: non_decreasing(tau_mono); check_dim( y − f(x) ) = 0; dual forms must run in parallel and gaps recorded.

II. Terms and Variables

• Key quantities: L, A, H, K, F, B, Q, R, x̂, P, u_c, g, nu_eff, α, delta_form_stream, delta_form_unc.
• Reference conditions: RefCond = { timezone, units, sensors, policy }.
• Time fields: ts (event time), tau_mono (monotone processing time), wm(t) (watermark).

III. Naming & Layers

1. Pattern: C70-{layer}{index}; layer prefixes:
   • 00 Data, 10 Graph/Operators, 20 Dynamics, 30 Assimilation, 40 Physics,
   • 50 Uncertainty, 60 Dual-forms, 70 Runtime, 80 Version & Security.
2. Assertion form: assert( metric ≤/≥ threshold ); declare unit(metric) and enforce check_dim(metric).

IV. Data & Units (Ingestion Layer)

• C70-0001 (Units & dimensions) — All inputs y, controls u, states x declare unit(*); must pass check_dim( y − H x ). Breach → reject ingest.
• C70-0002 (RefCond persistence) — Every batch carries RefCond and wm(t); missing → fill or reject.
• C70-0003 (Freshness & lateness) — Within-window late_rate ≤ tol_late; breach → trigger replay (Ch. 14).
• C70-0004 (Imputation labeling) — Any fill-in is tagged impute.tag ∈ { forward, model, median } and budgeted into u_model.

V. Graph & Operators (Structural Layer)

• C70-1001 (Connectivity) — |E| ≥ |V| − 1, giant-component coverage ≥ 0.95.
• C70-1002 (Laplacian bounds) — L symmetric PSD; λ_max(L) ≤ λ_cap (domain-configured).
• C70-1003 (Observation usability) — rank(H) ≥ r_min; sensor online rate ≥ 1 − miss_tol.
• C70-1004 (Kernel stability) — For K = g(L), spectral radius ρ(K) ≤ 1 + ε; approx-degree error ≤ ε_approx.

VI. Dynamics & Stability (Propagation Layer)

• C70-2001 (Step & stiffness) — Δt lies in stable region; if stiff > thr, switch solver ∈ { BDF, split }.
• C70-2002 (Energy/norm boundedness) — || x̂_{k+1} || ≤ γ || x̂_k || + b; rolling breaches → downgrade/reset.
• C70-2003 (Control safety) — u ∈ [ u_min, u_max ] (whitelist); out-of-bounds → clamp & alert.

VII. Assimilation & Filtering (Statistical Layer)

• C70-3001 (KF NIS) — NIS_p95 ∈ [ ν_low, ν_high ]; breach → tune Q/R or reset P0.
• C70-3002 (PF degeneracy) — ESS / Np ≥ ess_min; otherwise resample or increase Np.
• C70-3003 (Covariance PSD) — P ≽ 0 and cond(P) ≤ κ_max; failure → add εI to diagonal.
• C70-3004 (Residual coverage) — Pr( | y − H x̂ | ≤ g ) ≥ 1 − α; rolling coverage ≥ cov_min.

VIII. Physical Consistency (Conservation / Nonnegativity / Bounds)

• C70-4001 (Conservation) — || B x̂ − s ||_2 ≤ ε_cons; breach → project x̂ ← x̂ − B^{†}( B x̂ − s ).
• C70-4002 (Nonnegativity & ranges) — min(x̂) ≥ − ε_neg and x̂ ∈ [ l, u ]; breach → feasible-set projection.
• C70-4003 (Source–sink drift) — drift = ( Σ_in − Σ_out − s ) / scale ≤ ε_drift.

IX. Uncertainty & Guardbands (GUM / MC)

• C70-5001 (Composite uncertainty) — u_c^2 = J V_x J^T + u_num^2 + u_model^2; enforce check_dim(u_c) = "[X]".
• C70-5002 (Coverage) — Guardband g = k u_c; empirical coverage ≥ 1 − α − ε_cov.
• C70-5003 (Effective DoF) — nu_eff ≥ nu_min; otherwise increase samples or run MC in parallel.
• C70-5004 (Dual-form uncertainty gap) — delta_form_unc_p95 ≤ 0.2 • median(u_c).

X. Dual-Form Coherence (Event vs Processing Time)

• C70-6001 (Statistical dual-form) — delta_form_unc_p95 ≤ tol_unc.
• C70-6002 (Temporal dual-form) — delta_form_stream_p95 ≤ tol_stream.
• C70-6003 (Panel alignment) — | ts − tau_mono | ≤ ε_sync; breach → replay gap-fill.

XI. Runtime SLO/SLI & Resources

• C70-7001 (Latency SLO) — latency_p95 ≤ B_mod; p99 ≤ B_hard.
• C70-7002 (Drops & backpressure) — drop_rate ≤ 0.1%; if backpressure persists > T_bp, degrade.
• C70-7003 (Cache hit) — cache_hit ≥ 80% (if enabled); else tune ttl/size/policy.
• C70-7004 (Replay coverage) — replay_gap_covered ≥ 99.5%.
• C70-7005 (Panel health) — key metrics refresh interval ≤ Δt_panel_max; breach → health-check & alert.

XII. Versioning & Security

• C70-8001 (Hash coherence) — graph.hash / L.hash / model.hash / policy.hash must match the running instance; otherwise reject.
• C70-8002 (Semantic versioning) — I70-x.y.z incompatibilities require explicit migration; otherwise reject.
• C70-8003 (Audit & signatures) — manifest.signature must verify; failure → read-only degrade.

XIII. Contract DSL (Minimal Executable Snippet)

rule_id: C70-3001

title: KF NIS consistency

metric: NIS_p95

unit: "1"

assert: "NIS_p95 >= ν_low && NIS_p95 <= ν_high"

window: { type: sliding, Δt_win: "30m", Δt_slide: "5m" }

on_breach:

- action: tune_QR

params: { scale_Q: 1.5, scale_R: 0.8, cap: [Q_max, R_min] }

- action: reset_filter_if_persist

params: { duration: "15m" }

persist:

keys: [TraceID, graph.hash, L.hash, model.hash, RefCond]

XIV. Playbooks (Remediation Library)

1. S-01: NIS too high (underfitting observation)
   • Trigger: C70-3001 above ν_high for k consecutive windows.
   • Steps: (1) tune Q↑ / R↓; (2) validate H and units; (3) if still high → reset x0, P0 and switch to robust filtering (Huber / χ-clipping).
   • Record: contracts.report.actions = ["tune_QR","reset","robust_mode"].
2. S-02: ESS degradation — Trigger: ESS/Np < ess_min; Steps: systematic resampling → adaptive Np↑ → jitter regularization → if compute-bound switch to UKF.
3. S-03: Conservation breach — Trigger C70-4001; Steps: project x̂ ← x̂ − B^{†}( B x̂ − s ); locate faulty sources/sinks; freeze anomalous subgraph if needed.
4. S-04: Stiffness/divergence — Trigger C70-2001/2002; Steps: switch solver = BDF / StrangSplit; shorten Δt; spectrally clip kernels ρ(K) ← min(ρ, 1 − ε).
5. S-05: Coverage shortfall (guardband) — Trigger C70-5002; Steps: re-estimate u_model & J; increase k or adjust distributional assumptions; if skewed → switch to quantile bands.
6. S-06: Dual-form inconsistency — Trigger C70-6001/6002; Steps: align ts / tau_mono; unify window weights; equalize integrator steps; retain root-cause traces.
7. S-07: SLO breach — Triggers C70-7001..7005; Steps: rate-limit & spill, cache bypass, degrade model (lower-order kernels / sparse H); backfill after recovery.

XV. Generation & Publication

• Generate: assert_runtime_contracts(state, rules) -> report (I70-14A) and summarize via eval_contracts (I70-156).
• Publish: emit_runtime_manifest(results, policy) -> manifest.stg.runtime and emit_case_manifest(...) (I70-14B / I70-157).
• Persist: contracts.rules, contracts.report, violations.*, actions.*, signature.

XVI. Cross-References

• Numerical integration & stability: Ch. 9 (stiffness criteria, splitting & events).
• Assimilation & filtering: Ch. 12 (KF/UKF/PF metrics & implementations).
• Uncertainty & guardbands: Ch. 13 (u_c, g, nu_eff, α).
• Runtime & streaming: Ch. 14 (windows, watermarks, caches & fallbacks).
• Use cases & panels: Ch. 15 (threshold examples in traffic/power/water).

Summary
This appendix provides the complete C70- contract suite* and executable playbooks, spanning structural → statistical → physical → runtime assertions and remedies.
Every contract must declare units/dimensions, threshold provenance, and windowing strategy; breach actions and audit logs must be written to manifest.stg.contracts to sustain reproducible, regulatable, and evolvable STG systems.