SWMM Agent Engine — run · diff · diagnose · explain · certify

The premise, which is a forecast and not a measurement: by 2030 most SWMM runs will be started by an agent, not by a person clicking Run, and neither SWMM5 nor SWMM6 has a first-class interface for that. This app is that interface as a working prototype: five pinned WASM artifacts behind six core verbs, four discovery verbs and a batch verb, every call returning structured JSON, every result carrying a provenance record — and a harness that decides whether an agent is allowed to say "SWMM6 matches SWMM5". The version number is the target year, not a release date.

What an agent gets back

Never a .rpt to parse. Every verb returns:

Continuity — runoff / routing / quality error, already banded (C0–C3).
Instability signature — C0-N2-F1-T0: continuity band, non-convergence band, flow-turn band, timestep-collapse stage.
Timestep-collapse stage — 0 fixed, 1 mild, 2 transient, 3 sustained, 4 at the floor.
Expected-difference class — IDENTICAL, ROUNDOFF, WITHIN_TOLERANCE, NEAR_MISS, KNOWN_ENGINE_DIVERGENCE, OBSERVED_UNRESOLVED, PHYSICS_OPTION_CHANGE, UNEXPLAINED.
Provenance — engine artifact SHA-256 (of the bytes that executed), model SHA-256, [OPTIONS] as parsed, tolerance profile, harness version, expected-difference file hash.

Why this is obvious for this workshop

The tiered harness and the expected-difference file are the test suite that keeps the agent honest. certify runs the gate ladder and issues a certificate (sha256 digest for integrity, session HMAC for authenticity) — or withholds it. An agent cannot claim agreement without one, and verify_certificate rejects anything altered or withheld.
The instability explainers become the diagnose and explain verbs: bands, stages, named findings, and for each finding what / why / ordered fixes with the option to change.
BatchSWMMRunner already has six execution modes and a tolerance comparison; this is the stable contract on the outside — the Contract tab is the tools/list an MCP client would see.

The verb set

swmm.run

model + engine → structured result, diagnosis, provenance. Fresh engine instance per run; artifact hash verified before a byte executes.

swmm.diagnose

signature + class + findings from the engine's own report blocks. What the engine did not report is listed, never assumed zero.

swmm.explain

each finding → what, why, fixes in order (option, value, rationale), reference. The teaching content, callable.

swmm.diff

two runs on a tolerance profile → class, worst metric, continuity delta, option differences, physics-option flag.

swmm.certify

8-gate ladder + expected-difference file → CERTIFIED / WITHHELD / REFUSED, with a SHA-256 digest (integrity) and a session HMAC (this carrier issued it). An agent can recompute a digest; it cannot produce this session's MAC — and neither is proof of origin to a third party, which needs a service holding a private key

swmm.verify_certificate

recompute the digest; refuse altered, withheld or foreign-harness certificates.

Engine roster (all pinned, all hash-checked)

id	artifact	API	status

alpha.3 is alpha.2, bit for bit, on this corpus. swmm6-alpha3 is the LocalSWMM main-branch build (engine ec280d2c, v6.0.0-alpha.3-3, a pthreads build whose thread pool this carrier stubs; 1D only). On all 12 bundled models its .out results block hashes identically to the alpha.2 handle build — same extran6 near miss, same extran9 period count, same Example1 divergence. The banner changed; the numbers did not.

alpha.4 fixes Example1. swmm6-alpha4 is Bob's own wasm6 build from BatchSWMMRunner (HydroCouple swmm6_rel @137e65e4, 2026-09-10, emcc 3.1.51, BUILD_INFO and link map committed) — the first build carrying the water-quality/transport code. On EPA Example1 it is WITHIN_TOLERANCE against SWMM5 (worst 0.43%) where alpha.2/alpha.3 diverge (ED-3, now scoped to those versions); quality continuity +4.09% remains as ED-6. Against alpha.2 it differs at roundoff only on the hydraulic models (ED-7). The "Reported Max Depth" column defect (ED-5) persists.

One of the five is deliberately defective. swmm6-cli-alpha2 is the small LocalSWMM CLI build of alpha.2; measured here on 2026-09-19, it mis-applies hour-based [TIMESERIES] inflows (extran1 external inflow 4.4 vs 33.5 acre-ft). It stays in the roster so you can watch certify refuse it — the whole point of a harness is what it will not sign.

Measured, not assumed

Every number this app quotes about the bundled models was produced by these same five artifacts running in Node on 2026-09-19 (752 parser and verb gates green). When you run a bundled model here, the response carries a fixture check: the browser result must reproduce the Node result — same continuity, same non-convergence, same .out results-block hash. If it does not, the transport is the bug, and the response says so.

Engines

Fetched from the pinned URL (jsDelivr/raw fallback), SHA-256 compared to the manifest before evaluation. A mismatch refuses the load and says so.

Model

Bundled classic models (12)

or drop / choose a .inp file

Call

engine

tolerance profile

Demos

Narrated on the right: five engines verified → agreement certified on extran6 → three tamper attempts refused → alpha.3 shown bit-identical to alpha.2, alpha.4 at roundoff → the defective build withheld (ED-4) → Example1 withheld on alpha.2 (ED-3) and certified on alpha.4 → extran9 time-grid divergence licensed (ED-1) → refusals before running → worker cancel and rerun. Pause, step, or stop at any point; every number in the narration is read from the live response.

Agree: extran6 → run on both → diagnose → explain → diff → certify. Refuse: extran1 → SWMM5 and the defective CLI build → certify → WITHHELD with ED-4 matched.

Request (JSON-RPC as an MCP client would send it)

{ "method": "tools/call", "params": { "name": "swmm.run", "arguments": {} } }

Response

— send a call —

Transcript

Tolerance profiles

profile	rel	abs flow (flow units)	abs depth (ft or m)	abs velocity / flooding	continuity max %	near-miss ×

Bands

Cold self-test no engine, no network

Runs the analysis layer on bundled report excerpts and synthetic certificates in this tab, in under a second: parse → diagnose → explain, the parse-failure and banner-only paths, unknown-profile refusal, advisory non-matching, and digest/signature tampering. A visible slice of the Node suite a reader can reproduce offline.

Stdio transport (Python stub)

The same contract over stdio for Claude Desktop / Claude Code. It wraps the existing swmm5_mcp_server.py engine call; remember the fd-1 writecon redirect around every engine call.

tools/list

Guided demo · not started

Scorecard

Runs after the demo finishes or is stopped.

Chapters and steps

Entries

id	class	licenses	trigger	note	evidence	what this does not show

Drafts live in memory for this session; export the file to keep them. The file hash in every certificate changes when the file changes, so a certificate always names the file that licensed it.

Corpus fixtures (Node, 2026-09-19)

model	SWMM5 5.2.2 cont % · nonconv % · signature · results-block hash	alpha.2 handle	alpha.3 (main)	alpha.4 (wasm6)	CLI alpha.2 (defective)	vs SWMM5 at cross_engine

Calls

#	time	verb	model sha	engine(s)	result	chain

Certificates issued or withheld

digest	verdict	class	profile	model	A	B	gates