# DECISION-20260422-pumpingstation-5-threshold-naming

## Context
- Task/request: Re-draw the pumpingStation basin model and rename the configuration fields so they match the conceptual model used in the wiki.
- Impacted files/contracts:
  - `generalFunctions/src/configs/pumpingStation.json` (schema keys)
  - `nodes/pumpingStation/src/specificClass.js` (internal state + comments)
  - `nodes/pumpingStation/src/nodeClass.js` (config ingestion mapping)
  - `nodes/pumpingStation/pumpingStation.html` (editor field IDs + labels)
  - `nodes/pumpingStation/test/*` (test fixtures)
  - `examples/pumpingstation-3pumps-dashboard/{build_flow.py, flow.json, README.md}`
  - saved production flows that reference the old field names (breaking change)
- Why a decision is required now: The old names (`stopLevel`, `maxFlowLevel`, `minFlowLevel`, `heightInlet/Outlet/Overflow`) conflated geometry with control thresholds and had a redundant field (`minFlowLevel` always had to equal `startLevel`).

## Options
1. Keep old names; just document them better
- Benefits: Zero breaking change.
- Risks: Naming keeps confusing new contributors; docs continue drifting from code.

2. Adopt the 5-threshold naming from the wiki basin diagram (selected)
- Benefits: Clear semantic split — two safety thresholds (`dryRunLevel`, `overflowLevel`), three control thresholds (`minLevel`, `startLevel`, `maxLevel`) — plus three physical pipe heights (`inflowLevel`, `outflowLevel`, basin `height`). Drops the redundant `minFlowLevel`. Matches the diagram in the functional description.
- Risks: Breaking change for saved flows; node editor fields must be re-entered.
- Rollout notes: RnD/trial node — no compat shim. Breaking change documented in commit bodies and wiki.

## Decision
- Selected option: Option 2.
- Decision owner: User
- Date: 2026-04-22
- Rationale: The names should reflect the model. The diagram came first; the code should match the diagram, not the other way around. Compat posture is "controlled" (per DECISION-20260216) — breaking changes are permitted with migration notes.

## Mapping
| Old | New |
|---|---|
| `heightInlet` | `inflowLevel` |
| `heightOutlet` | `outflowLevel` |
| `heightOverflow` | `overflowLevel` |
| `stopLevel` | `minLevel` |
| `maxFlowLevel` | `maxLevel` |
| `minFlowLevel` | removed (collapsed into `startLevel`) |
| `minVolIn/Out` (internal) | `minVolAtInflow/Outflow` |
| `maxVolOverflow` (internal) | `maxVolAtOverflow` |

## Consequences
- Compatibility impact: Existing flows break; editor fields must be re-entered.
- Safety/security impact: Safety thresholds (`dryRunLevel`, `overflowLevel`) now have first-class names — guardrail validation can reason about them explicitly.
- Data/operations impact: InfluxDB payload field names change (`maxVolOverflow` → `maxVolAtOverflow` etc.). Downstream Grafana dashboards referencing the old names must update.

## Implementation Notes
- Required code/doc updates: Done in commits pumpingStation@a218945, generalFunctions@4252292, EVOLV@b885f29.
- Validation evidence required: Unit tests (`node --test test/basic/*.test.js`) pass; `grep -r` confirms zero residual old names in pumpingStation/ + generalFunctions/pumpingStation.json + examples/.

## Rollback / Migration
- Rollback strategy: revert the three commits; the renames are isolated.
- Migration/deprecation plan: None — RnD node, breaking change is acceptable.