EVOLV/.agents/function-anchors/pumpingStation/ANCHOR-pumpingStation.md

# Pumping Station Function Anchor (Preparation Baseline)

## 0) Connection Map (At a Glance)
- **Node type**: `pumpingStation` (`nodes/pumpingStation/pumpingStation.js:1`, `nodes/pumpingStation/pumpingStation.html:15`)
- **Consumes parent/control topics**: `changemode`, `registerChild`, `calibratePredictedVolume`, `calibratePredictedLevel`, `q_in` (`nodes/pumpingStation/src/nodeClass.js:209`)
- **Publishes periodic outputs**:
  - Output `0`: process payload (`nodes/pumpingStation/src/nodeClass.js:197`)
  - Output `1`: influx payload (`nodes/pumpingStation/src/nodeClass.js:198`)
  - Output `2`: parent registration/control plumbing (`registerChild`) (`nodes/pumpingStation/src/nodeClass.js:114`)
- **Cross-node integrations (direct observed)**:
  - Registers `measurement` children and listens for `*.measured.<position>` events (`nodes/pumpingStation/src/specificClass.js:73`)
  - Registers `machine`, `machinegroup`, `pumpingstation` children and listens for predicted flow (`nodes/pumpingStation/src/specificClass.js:59`)
  - Commands child machines/stations/groups during control/safety transitions (`nodes/pumpingStation/src/specificClass.js:258`, `nodes/pumpingStation/src/specificClass.js:528`)
- **Admin/UI endpoints**:
  - `GET /pumpingStation/menu.js`
  - `GET /pumpingStation/configData.js` (`nodes/pumpingStation/pumpingStation.js:22`, `nodes/pumpingStation/pumpingStation.js:33`)

## 1) Unit Table (Initial Baseline)
| Signal/Field | Represents | Default Unit | Source of Truth | Produced By | Consumed By | Fallback/Degraded Behavior |
|---|---|---|---|---|---|---|
| `flow.measured.*` / `flow.predicted.*` | inflow/outflow streams | `m3/s` preferred | `nodes/pumpingStation/src/specificClass.js:24` | measurement/machine/machinegroup children | net-flow selection + predicted volume integration | falls back to level-rate estimate when unavailable (`nodes/pumpingStation/src/specificClass.js:458`) |
| `level.measured.*` / `level.predicted.*` | wet well level | `m` | `nodes/pumpingStation/src/specificClass.js:24` | measurement or pressure conversion path | control decisions + remaining-time estimate | if no level available, remaining time becomes null (`nodes/pumpingStation/src/specificClass.js:487`) |
| `volume.predicted.atequipment` | integrated basin volume | `m3` | `nodes/pumpingStation/src/specificClass.js:393` | tick-based integration | safety + status + output | if volume unreadable, station shuts down machines availability-first (`nodes/pumpingStation/src/specificClass.js:503`) |
| `volumePercent.*.atequipment` | normalized fill percentage | `%` | `nodes/pumpingStation/src/specificClass.js:424` | level/volume conversion | status + dashboards | not emitted until level/volume is known |
| `netFlowRate.*.atequipment` | selected net flow | measured unit or `m3/s` | `nodes/pumpingStation/src/specificClass.js:454` | `_selectBestNetFlow()` | status + remaining-time + safety | defaults to `0` with `steady` direction (`nodes/pumpingStation/src/specificClass.js:466`) |
| `timeleft` | estimated seconds to empty/full limit | `s` | `nodes/pumpingStation/src/specificClass.js:470` | `_computeRemainingTime()` | safety logic + output | null if insufficient data |

## 2) Class Identity
- **Runtime registration + endpoints**: `nodes/pumpingStation/pumpingStation.js`
- **Node-RED wrapper/routing**: `nodes/pumpingStation/src/nodeClass.js`
- **Domain/station logic**: `nodes/pumpingStation/src/specificClass.js`
- **Editor UI/defaults**: `nodes/pumpingStation/pumpingStation.html`
- **Default config schema/validation rules**: `nodes/generalFunctions/src/configs/pumpingStation.json`

## 3) Current Gaps To Resolve Before Declaring Anchor Complete
1. Topic/mode mismatch:
- UI default uses `controlMode: "none"` (`nodes/pumpingStation/pumpingStation.html:59`)
- runtime switch expects `manual` not `none` (`nodes/pumpingStation/src/specificClass.js:234`)
2. Position token mismatch risk:
- code mixes `atEquipment` and `atequipment` variants (`nodes/pumpingStation/src/nodeClass.js:122`, `nodes/pumpingStation/src/specificClass.js:103`)
3. Child softwareType mismatch risk:
- checks for `'pumpingstation'`/`'machinegroup'` lowercase (`nodes/pumpingStation/src/specificClass.js:61`, `nodes/pumpingStation/src/specificClass.js:63`)
- other configs generally use camelCase (`nodes/generalFunctions/src/configs/pumpingStation.json:48`)
4. Missing guards in input registration path:
- no null check after `RED.nodes.getNode` (`nodes/pumpingStation/src/nodeClass.js:217`)
5. Test baseline exists but is not yet full parity:
- basic/edge/integration scaffolding is present; additional safety/control math coverage is still pending.

## 4) Standardization Plan (Mirror RotatingMachine)
1. Create `ANCHOR-pumpingStation.html` with:
- always-visible topology map
- unit/signal catalog table
- control and safety flow diagram
- known invariants and risk list
2. Expand the current unit/integration/edge test suite under `nodes/pumpingStation/test/`:
- config defaults/overrides
- topic routing and child registration
- predicted volume integration and remaining-time math
- safety triggers and control actions
- regression for string casing mismatches and missing child node IDs
3. Add evidence companion doc:
- `EVIDENCE-pumpingStation-tests.md` with fail-before/pass-after references.
4. Keep this anchor and tests updated on every pumpingStation behavior change.

## 5) Acceptance Criteria For Completion
- Anchor markdown complete to template parity with rotatingMachine.
- Anchor HTML visualization added and aligned with actual contracts.
- Test suite runnable with `node --test nodes/pumpingStation/test/**/*.test.js`.
- Evidence file links each test file to anchored behavior.