79afe11da8
Some checks failed
CI / lint-and-test (push) Has been cancelled
Four decisions recorded under .agents/decisions/ per project convention (DECISION-YYYYMMDD-slug.md) to close the loop on today's pumpingStation refactor + eval + docs work: - wiki-in-code-repo — why docs+diagrams+code now live in one package - 5-threshold-naming — old/new field mapping + breaking-change rationale - mode-tier-template — Tier 1/2/3 classification for mode pages - eval-harness — why eval/ exists alongside test/ Also bumps nodes/pumpingStation to 66fd3fe (eval harness + Tier 2/3 template pages). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
55 lines
3.3 KiB
Markdown
55 lines
3.3 KiB
Markdown
# 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.
|