levelBased ramp + engagement:
- Ramp foot is now max(startLevel, holdLevel) — was max(startLevel,
inflowLevel). inflowLevel is basin geometry, not a control setpoint;
the implicit hold zone it created was causing pumps to "start at
inflowLevel" instead of startLevel.
- New optional `holdLevel` config (defaults to startLevel = no hold band).
When raised, pumps engage at startLevel and hold at 0 % = MGC flow.min
across [startLevel, holdLevel], then ramp 0..100 % to maxLevel.
- Engagement decided in run() (not in `_applyMachineGroupLevelControl`):
rising-edge hysteresis arming gates a clean turnOff early-return.
Once armed, the helper always forwards setDemand(pct, '%') — 0 %
legitimately means "engaged at min flow", no more soft-turnOff at
the boundary.
- Disengagement paths (minLevel hard-stop, stopLevel falling-edge,
pre-arming idle) now all clear the shifted-ramp hysteresis state too.
- Threshold validator drops the startLevel ≤ inflowLevel rule; adds
startLevel ≤ holdLevel < maxLevel (only checked when holdLevel is
explicitly set, so default-null doesn't false-flag).
MGC unit math:
- Replace direct group.handleInput(percent) with group.setDemand(pct, '%')
in _applyMachineGroupLevelControl. The percent → m³/s resolution now
lives in MGC.setDemand (committed separately in the MGC submodule).
FlowAggregator variant picking:
- New _pickFlowSum() helper mirrors selectBestNetFlow's variant
precedence (measured first, then predicted) and resolves each side
independently. Realistic mixed case — real measured upstream sensor +
predicted pump outflow — now feeds the predicted-volume integrator.
Was reading only `flow.predicted.*` so a real upstream sensor
(which writes `flow.measured.*`) never moved the level.
Editor:
- New `holdLevel` and `deadZoneKeepAlivePercent` defaults + side-panel
input rows in the levelbased mode preview.
- Add the missing `ps-mode-line-holdLevel` SVG marker (was declared in
the side-panel coupling but the SVG element didn't exist, so the
dashed line never rendered).
- Relax stopLevel marker gate so it renders for any non-negative typed
value — start/stop ordering is the ribbon's job, not the marker's
(was hiding the line whenever startLevel was momentarily smaller).
- Add holdLevel to the marker loop in mode-preview so changes track.
- Add stopLevel + holdLevel + maxLevel to all three bindRedraw lists
(basin-diagram, mode-preview, bounds.apply) so the SVG, validation
ribbon, and HTML5 min/max attrs update on every edit.
- Initialise stopLevel + holdLevel + deadZoneKeepAlivePercent inputs
in oneditprepare so reopening the editor shows the saved values.
- nodeClass passes holdLevel + deadZoneKeepAlivePercent into the
domain config.
Tests:
- New test/basic/_probe_upstream_emit.test.js: confirms the parent
surfaces flow.measured.upstream.* on Port 0 after a measurement
child write — pins the previously-invisible measured variant flow.
- flowAggregator.basic.test.js: two new regression cases — measured
inflow when predicted side is empty, and the measured-in /
predicted-out mixed case.
- control-levelBased.basic.test.js: new cases for the holdLevel hold
band, the [stopLevel, startLevel] keep-alive, the engagement gate,
and the "0 % at startLevel = setDemand" contract.
- specificClass.test.js: zone tests adjusted to the new ramp foot.
Shifted-ramp tests pin holdLevel = 3 explicitly so their legacy
arithmetic (ramp foot at inflowLevel) stays self-consistent.
- shifted-ramp-end-to-end.test.js: same holdLevel pin for the same
reason.
Packaging:
- Add .gitignore + .npmignore so the published tarball drops the
wiki/, simulations/, test/, tools/, .claude/ etc. The pack went
from 1.5 MB (72 files) to ~57 KB (30 files).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Adds to scalar setters whose payloads are
plain numbers OR {value, unit}. Skipped where payload is compound or
mode-dependent (control-%, {F, C: [...]}, etc.) — documented inline.
Every command gains a description field for wikiGen consumption.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Runtime (specificClass.js):
- Replace the "shift left both ramp ends" geometry with a true
hold-then-ramp hysteresis driven by output %, not level:
• Up-curve % crosses shiftArmPercent on the way up → ARM.
• Filling→draining transition while armed → capture the up-curve %
at that moment as _shiftHoldValue.
• Draining + level ≥ shiftLevel → output stays at _shiftHoldValue
(horizontal hold, matching the dashed segment in the SVG).
• Draining + level in [start, shift] → output ramps holdValue → 0 %
along the same curve shape (linear or log) as the up curve.
• Draining + level < startLevel → 0 % AND disarm.
• Returning to filling clears holdValue, stays armed; next drain
transition captures a fresh hold so bouncing fills rearm cleanly.
• Disarm only when level ≤ startLevel.
- New _curveShape(x) helper for shared linear/log shaping.
- Removed legacy _levelBasedRampStart / _levelBasedRampTop /
_updateShiftArmed in favour of the inline state machine.
Adapter (nodeClass.js):
- Pipe shiftArmPercent through to control.levelbased.
Editor (pumpingStation.html + src/editor/):
- Add shiftArmPercent input row (% with unit) to the mode side panel
(only shown when shifted ramp is enabled). Default 95 %.
- Add the horizontal arming-% line + label inside the mode SVG —
this is the "% Threshold triggering shifted ramp down" line from
the original drawing that had been missing.
- Redraw the shifted-down curve to match the SVG geometry literally:
100 % flat from maxLevel → shiftLevel, then ramp shiftLevel →
startLevel down to 0 %, OFF below startLevel. Preview shows the
worst-case envelope (hold = 100 %); runtime hold is captured live.
- Validation extended: 0 < shiftArmPercent ≤ 100; ordering rules
preserved (start < shift ≤ max etc.).
- Auto-default shiftArmPercent to 95 when shift is enabled and the
current value is missing or out of range.
Dashboard example (examples/basic-dashboard.flow.json):
- Parser now reads `level.predicted.atequipment.default` etc. The
MeasurementContainer flatten format includes the implicit 'default'
childId; consumers must include it. Comment in the parser points
at the documenting source in generalFunctions.
Tests:
- test/basic: replace old level-armed-shift tests with two new ones
that exercise the hold-then-ramp arming, capture, hold, ramp-down,
disarm, and the bounce case (filling→draining→filling→draining
captures a fresh hold each time).
- test/integration/shifted-ramp-end-to-end.test.js: new file. Drives
Q_IN/Q_OUT through the full runtime tick with a controllable clock,
asserting the same hysteresis path the dashboard exercises.
- test/integration/basic-dashboard-flow.test.js: fixture keys updated
to the .default-suffixed form so they match the real flatten output.
56/56 tests pass.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
