Prepare reactor, diffuser, and settler updates for mainline merge

.agents/decisions/DECISION-20260323-reactor-four-zone-staged-aeration-demo.md

@@ -0,0 +1,43 @@
+## Context
+
+The single demo bioreactor did not reflect the intended EVOLV biological treatment concept. The owner requested:
+
+- four reactor zones in series
+- staged aeration based on effluent NH4
+- local visualization per zone for NH4, NO3, O2, and other relevant state variables
+- improved PFR numerical stability by increasing reactor resolution
+
+The localhost deployment also needed to remain usable for E2E debugging with Node-RED, InfluxDB, and Grafana.
+
+## Options Considered
+
+1. Keep one large PFR and add more internal profile visualization only.
+2. Split the biology into four explicit reactor zones in the flow and control aeration at zone level.
+3. Replace the PFR demo with a simpler CSTR train for faster visual response.
+
+## Decision
+
+Choose option 2.
+
+The demo flow now uses four explicit PFR zones in series with:
+
+- equal-zone sizing (`4 x 500 m3`, total `2000 m3`)
+- explicit `Fluent` forwarding between zones
+- common clocking for all zones
+- external `OTR` control instead of fixed `kla`
+- staged NH4-based aeration escalation with 30-minute hold logic
+- per-zone telemetry to InfluxDB and Node-RED dashboard charts
+
+For runtime stability on localhost, the demo uses a higher spatial resolution with moderate compute load rather than the earlier single-reactor setup.
+
+## Consequences
+
+- The flow is easier to reason about operationally because each aeration zone is explicit.
+- Zone-level telemetry is available for dashboarding and debugging.
+- PFR outlet response remains residence-time dependent, so zone outlet composition will not change instantly after startup or inflow changes.
+- Grafana datasource query round-trip remains valid, but dashboard auto-generation still needs separate follow-up if strict dashboard creation is required in E2E checks.
+
+## Rollback / Migration Notes
+
+- Rolling back to the earlier demo means restoring the single `demo_reactor` topology in `docker/demo-flow.json`.
+- Existing E2E checks and dashboards should prefer the explicit zone measurements (`reactor_demo_reactor_z1` ... `reactor_demo_reactor_z4`) going forward.