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>
3.3 KiB
3.3 KiB
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 (minFlowLevelalways had to equalstartLevel).
Options
- Keep old names; just document them better
- Benefits: Zero breaking change.
- Risks: Naming keeps confusing new contributors; docs continue drifting from code.
- 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, basinheight). Drops the redundantminFlowLevel. 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→maxVolAtOverflowetc.). 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 -rconfirms 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.