---
name: evolv-process-hydraulics-mass-balance
description: Engineer process hydraulics and mass-balance consistency across EVOLV nodes. Use when validating flow/volume/level relationships, retention-time assumptions, split/merge behavior, and physically plausible cross-node transport dynamics.
---

# EVOLV Process Hydraulics Mass Balance

## Mission
Preserve physically coherent hydraulics and conservation behavior across interacting EVOLV process nodes.

## Harness Execution Contract
- Build a flow and accumulation map from current node contracts.
- Define invariants before edits:
  - no unplanned conservation breaks
  - split/merge behavior remains deterministic
  - retention/transport assumptions are explicit
- Validate with scenario-based balance checks.

## Scope
- `nodes/reactor/`
- `nodes/settler/`
- `nodes/pumpingStation/`
- `nodes/valve/`, `nodes/valveGroupControl/`

## Workflow
1. Identify control volumes and interfaces.
2. Map inflow/outflow/storage terms and units.
3. Validate steady-state and transient behavior under typical scenarios.
4. Check edge cases: zero flow, reverse flow, surge, overflow.
5. Confirm output contracts preserve balance observability.

## Standards
- Keep units and sign conventions explicit.
- Avoid hidden source/sink terms.
- Document retention-time and mixing assumptions.
- Preserve existing contracts unless migration is defined.

## Test Expectations
Cover:
- mass/volume conservation under nominal operation
- split/merge and bypass edge cases
- boundary condition behavior at zero/low/high flow
- numeric stability under long-run ticks

## Deliverables
Return:
- balance model and assumptions
- changed files/tests with scenario evidence
- unresolved hydraulic risks and required field checks

Decision interview triggers:
- changes to balance assumptions affecting KPI/compliance outputs
- compatibility-breaking payload/topic changes for flow/volume data
- startup behavior changes with overflow/dry-run implications