From 79afe11da8998e4613bcd4c8a034112a2454a9d1 Mon Sep 17 00:00:00 2001 From: znetsixe Date: Wed, 22 Apr 2026 16:50:00 +0200 Subject: [PATCH] Log pumpingStation architectural decisions; bump submodule pointers MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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) --- ...60422-pumpingstation-5-threshold-naming.md | 54 +++++++++++++++++++ ...ON-20260422-pumpingstation-eval-harness.md | 53 ++++++++++++++++++ ...60422-pumpingstation-mode-tier-template.md | 46 ++++++++++++++++ ...260422-pumpingstation-wiki-in-code-repo.md | 41 ++++++++++++++ nodes/pumpingStation | 2 +- 5 files changed, 195 insertions(+), 1 deletion(-) create mode 100644 .agents/decisions/DECISION-20260422-pumpingstation-5-threshold-naming.md create mode 100644 .agents/decisions/DECISION-20260422-pumpingstation-eval-harness.md create mode 100644 .agents/decisions/DECISION-20260422-pumpingstation-mode-tier-template.md create mode 100644 .agents/decisions/DECISION-20260422-pumpingstation-wiki-in-code-repo.md diff --git a/.agents/decisions/DECISION-20260422-pumpingstation-5-threshold-naming.md b/.agents/decisions/DECISION-20260422-pumpingstation-5-threshold-naming.md new file mode 100644 index 0000000..769e737 --- /dev/null +++ b/.agents/decisions/DECISION-20260422-pumpingstation-5-threshold-naming.md @@ -0,0 +1,54 @@ +# 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. diff --git a/.agents/decisions/DECISION-20260422-pumpingstation-eval-harness.md b/.agents/decisions/DECISION-20260422-pumpingstation-eval-harness.md new file mode 100644 index 0000000..d41670b --- /dev/null +++ b/.agents/decisions/DECISION-20260422-pumpingstation-eval-harness.md @@ -0,0 +1,53 @@ +# DECISION-20260422-pumpingstation-eval-harness + +## Context +- Task/request: Provide a way to fluctuate inputs to the pumpingStation and observe the system's response over time, in a readable form suitable for post-hoc analysis (operator review, Grafana, or ad-hoc debugging). +- Impacted files/contracts: `nodes/pumpingStation/eval/*`, `test/basic/*`. +- Why a decision is required now: Unit tests (`node --test`) verify individual functions in isolation. They can't ergonomically show "what does the level look like over 20 minutes of storm surge". That's a different artefact. + +## Options +1. Extend unit tests to cover scenarios +- Benefits: Single testing surface. +- Risks: Unit tests are assertion-heavy and slow to read; scenario output (tables, events) gets lost in TAP. + +2. Separate `eval/` folder with a scenario runner (selected) +- Benefits: Scenarios read as narratives ("steady state", "storm surge", "safety dry-run"); output is human-friendly (ASCII table + events + expectation checks); JSONL per-tick log enables Grafana streaming or offline analysis. +- Risks: Second test surface to maintain. + +3. Real-time Node-RED deployment + observe +- Benefits: Closest to production. +- Risks: Slow, requires infrastructure, irreproducible. + +## Decision +- Selected option: Option 2. +- Decision owner: User +- Date: 2026-04-22 +- Rationale: Unit tests answer "is this function correct?"; evals answer "how does the system behave under this input profile?". Two distinct questions — two distinct tools. The split also matches the .claude/rules/testing.md 3-tier convention (basic/integration/edge) which is for asserted behaviours, not scenario replay. + +## Architecture + +``` +test/ + basic/ integration/ edge/ — node:test + assertions +eval/ + run.js — scenario driver + scenarios/*.js — each exports { name, config, setup, inputs(t,ps), expectations } + formatters/table.js — ASCII summary + logs/*.jsonl — one-line-per-tick output + README.md — usage + how to pipe into Grafana +``` + +Driver monkey-patches `Date.now()` so the volume integrator sees 1 second per tick regardless of wall-clock. Every tick records a state snapshot (level, volume, direction, netFlow, flowSource, demand, mode, safetyActive) to JSONL for streaming. + +## Consequences +- Compatibility impact: None. +- Safety/security impact: None — read-only simulation. +- Data/operations impact: Running `node eval/run.js --all` produces artefacts that can be checked into CI for regression (e.g. "did the storm scenario's max level rise compared to last release?"). The JSONL format is friendly to InfluxDB/Grafana for interactive review. + +## Implementation Notes +- Required code/doc updates: Driver + three starter scenarios (`levelbased-steady`, `levelbased-storm`, `safety-dry-run-trip`) + README in `eval/`. +- Validation evidence required: `node eval/run.js --all` exits 0; manual inspection of JSONL confirms per-tick records make physical sense. + +## Rollback / Migration +- Rollback strategy: Delete `eval/`. Unit tests continue to work. +- Migration/deprecation plan: N/A. diff --git a/.agents/decisions/DECISION-20260422-pumpingstation-mode-tier-template.md b/.agents/decisions/DECISION-20260422-pumpingstation-mode-tier-template.md new file mode 100644 index 0000000..ac41ed2 --- /dev/null +++ b/.agents/decisions/DECISION-20260422-pumpingstation-mode-tier-template.md @@ -0,0 +1,46 @@ +# DECISION-20260422-pumpingstation-mode-tier-template + +## Context +- Task/request: Document each pumpingStation control mode uniformly so operators can compare them and contributors can add new ones from a template. +- Impacted files/contracts: `wiki/modes/*.md`, `wiki/diagrams/modes/*.drawio.svg`. +- Why a decision is required now: The initial `levelbased.md` used a 2D `demand-vs-level` transfer-function plot. That plot form works for static memoryless control but misleads for modes whose curve shape changes at runtime (e.g. `powerBased`) or where there is no curve at all (`mpc`). We need one template that stretches to cover all cases. + +## Options +1. One template, transfer-function only +- Benefits: Uniformity. +- Risks: Silently misleading for Tier-2/Tier-3 modes where the "curve" is not well-defined. + +2. Per-mode ad-hoc diagrams +- Benefits: Each mode gets the best visual for itself. +- Risks: No common vocabulary — comparing modes becomes harder. + +3. Three-tier template (selected) +- Benefits: Classifies every mode into one of three buckets, each with a dedicated diagram type. Still one template — only the diagram section branches. +- Risks: Some modes don't fit cleanly; will need judgement. + +## Tier definitions + +| Tier | Control surface | Example modes | Diagrams | +|---|---|---|---| +| 1 | Static: `demand = f(x)` memoryless | `levelbased`, `manual` | Single-curve transfer function | +| 2 | Parameterised: shape fixed, curve moves with `θ(t)` | `flowbased` (PID), `pressureBased`, `percentageBased`, `powerBased` | Transfer function + parameter-overlay / family-of-curves | +| 3 | Optimisation / horizon: no fixed curve | `hybrid-optimal`, `mpc`, weather-aware | Block diagram of signal flow + scenario time-series | + +## Decision +- Selected option: Option 3 — three-tier classification with diagram type per tier. +- Decision owner: User +- Date: 2026-04-22 +- Rationale: Keeps the mode pages comparable (same six sections) while being honest about what's actually drawable. Tier-3 modes get scenario-based analysis (via the `eval/` harness) instead of a fictitious static curve. + +## Consequences +- Compatibility impact: None — this is doc-level. +- Safety/security impact: None. +- Data/operations impact: New modes get a template to follow; reviews have a shared vocabulary. + +## Implementation Notes +- Required code/doc updates: `wiki/modes/README.md` lists the tiers and template; `wiki/modes/{flowbased, powerbased, mpc}.md` are worked templates covering Tier 2 (×2) and Tier 3 (×1) respectively. +- Validation evidence required: A reviewer reading a mode page can identify which tier it is within 10 seconds without scrolling. + +## Rollback / Migration +- Rollback strategy: Delete `wiki/modes/`; revert the table in `wiki/README.md`. +- Migration/deprecation plan: N/A — adding a tier later (e.g. Tier 4 — RL-based) is trivially additive. diff --git a/.agents/decisions/DECISION-20260422-pumpingstation-wiki-in-code-repo.md b/.agents/decisions/DECISION-20260422-pumpingstation-wiki-in-code-repo.md new file mode 100644 index 0000000..b027d15 --- /dev/null +++ b/.agents/decisions/DECISION-20260422-pumpingstation-wiki-in-code-repo.md @@ -0,0 +1,41 @@ +# DECISION-20260422-pumpingstation-wiki-in-code-repo + +## Context +- Task/request: Document pumpingStation functional behaviour (basin model, control modes, safety). Initial draft went into the Gitea wiki repo (`pumpingStation.wiki.git`). +- Impacted files/contracts: location of all pumpingStation documentation; how docs, diagrams, and code stay in sync; wiki UI vs repo browsing UX. +- Why a decision is required now: Wiki repo + code repo diverge silently. When `specificClass.js` renames a field, nothing forces the wiki to follow. User preference is "single package" — clone once, edit together, review together. + +## Options +1. Keep docs in `pumpingStation.wiki.git` (Gitea's native wiki) +- Benefits: Gitea wiki UI (Pages dropdown, `?edit=1`, dedicated URL). +- Risks: Two separate repos; code and doc drift silently. +- Rollout notes: Status quo as of 2026-04-22. + +2. Move docs + diagrams into `pumpingStation.git/wiki/` (selected) +- Benefits: Single package — `git clone pumpingStation` gets code + docs + diagrams. Atomic commits can change code + doc + diagram together. Diagrams version-lock with the class they describe. +- Risks: Lose the Gitea wiki Pages dropdown. Browsing is via the repo tree. +- Rollout notes: Shrink the `.wiki.git` to a pointer at the new location. + +3. Hybrid — diagrams only in code repo, Markdown pages in `.wiki.git` +- Benefits: Keep Gitea wiki UI. +- Risks: Image URLs break silently on rename; still two repos to sync. +- Rollout notes: Not pursued. + +## Decision +- Selected option: Option 2 — everything under `pumpingStation/wiki/`. +- Decision owner: User (r.de.ren@brabantsedelta.nl) +- Date: 2026-04-22 +- Rationale: Single package > Gitea wiki UI convenience. Review-as-one-PR pattern is worth more than the Pages dropdown. `wiki/README.md` acts as the index instead. + +## Consequences +- Compatibility impact: Anyone bookmarking `RnD/pumpingStation/wiki/Functional-Description` lands on a one-line pointer. Breaking but low-impact. +- Safety/security impact: None. +- Data/operations impact: Future contributors must know to edit `wiki/` inside the code repo, not the wiki repo. Pointer page on the Gitea wiki explains. + +## Implementation Notes +- Required code/doc updates: `pumpingStation/wiki/{functional-description.md, README.md, modes/, diagrams/}` populated; `.wiki.git` Home shrunk. +- Validation evidence required: Raw Gitea URLs resolve; `https://gitea.wbd-rd.nl/RnD/pumpingStation/src/branch/main/wiki/` browses cleanly. + +## Rollback / Migration +- Rollback strategy: Reverse — copy `pumpingStation/wiki/*.md` back into `.wiki.git`, update `.wiki.git` Home to point at itself. +- Migration/deprecation plan: The pointer page stays indefinitely. diff --git a/nodes/pumpingStation b/nodes/pumpingStation index a218945..66fd3fe 160000 --- a/nodes/pumpingStation +++ b/nodes/pumpingStation @@ -1 +1 @@ -Subproject commit a2189457f6515a42db50bdc8f55c0da20d45b675 +Subproject commit 66fd3feff8ac4877642ba4b9d553ff7c8251b043