stopLevel Schmitt-trigger hysteresis + dead-zone keep-alive

Levelbased control now distinguishes startLevel (rising-edge engage, ramp foot) from stopLevel (falling-edge disengage). _stopHystRunning flag flips TRUE crossing startLevel up, FALSE crossing stopLevel down. While engaged AND level inside [stopLevel, startLevel] (basin draining through the dead band), emit a configurable keep-alive percControl (default 1 %) so MGC keeps a single pump running for a full drain stroke instead of oscillating at startLevel. Hard turn-off the moment level <= stopLevel — independent of ramp scaling. Manual-mode demand=0 now also issues explicit turnOff to keep parity with the new MGC handleInput semantics where demand<=0 means "off". Editor preview shades the new hysteresis band; admin endpoint exposes runtime engaged state. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Docs + simulations refresh; align spill-flow keys with new position
2026-05-08 11:20:36 +02:00 · 2026-05-06 17:23:20 +02:00 · 2026-05-06 17:18:23 +02:00 · 2026-05-06 14:47:46 +02:00 · 2026-05-06 14:10:22 +02:00 · 2026-05-06 11:46:46 +02:00
26 changed files with 1309 additions and 233 deletions
--- a/README.md
+++ b/README.md
@@ -5,5 +5,6 @@ Wet-well basin model and pump orchestration node for EVOLV.
 The detailed documentation lives in [`wiki/`](wiki/):

 - [`wiki/functional-description.md`](wiki/functional-description.md) defines the shared basin model, pipe reference semantics, safety points, net-flow selection, and child registration behaviour.
- [`wiki/modes/`](wiki/modes/) documents control-mode-specific behaviour such as the level-linear `startLevel` demand ramp.
+- [`wiki/modes/`](wiki/modes/) documents control-mode-specific behaviour. For v1.0 the editor exposes `levelbased` and `manual`; levelbased supports linear and log curves with separate rising/falling ramp semantics.
 - [`wiki/diagrams/basin-model.drawio.svg`](wiki/diagrams/basin-model.drawio.svg) is the current source of truth for the generic basin model.
+- [`examples/basic-dashboard.flow.json`](examples/basic-dashboard.flow.json) provides a simple Node-RED Dashboard 2 flow with level, volume, demand, net-flow, and safety-state trends.
--- a/examples/basic-dashboard.flow.json
+++ b/examples/basic-dashboard.flow.json
@@ -295,7 +295,7 @@
    "type": "function",
    "z": "ps_tab_basic_dashboard",
    "name": "Parse PS output",
-    "func": "const fields = (msg.payload && typeof msg.payload === 'object') ? msg.payload : {};\nconst snapshot = Object.assign({}, context.get('snapshot') || {}, fields);\ncontext.set('snapshot', snapshot);\nconst firstFinite = (...keys) => {\n  for (const key of keys) {\n    const value = Number(snapshot[key]);\n    if (Number.isFinite(value)) return value;\n  }\n  return null;\n};\nconst level = firstFinite('level.predicted.atequipment', 'level.measured.atequipment');\nconst volume = firstFinite('volume.predicted.atequipment', 'volume.measured.atequipment');\nconst netFlow = firstFinite('netFlowRate.predicted.atequipment', 'netFlowRate.measured.atequipment');\nconst demand = firstFinite('percControl');\nconst safety = snapshot.safetyState || 'normal';\nconst direction = snapshot.direction || 'unknown';\nconst overflow = snapshot.isOverflowing === true || snapshot.isOverflowing === 'true';\nconst timeleft = Number(snapshot.timeleft);\nconst fmt = (value, digits = 2) => Number.isFinite(value) ? value.toFixed(digits) : '-';\nreturn [\n  level == null ? null : { topic: 'level', payload: level },\n  volume == null ? null : { topic: 'volume', payload: volume },\n  demand == null ? null : { topic: 'demand', payload: demand },\n  netFlow == null ? null : { topic: 'net_flow', payload: netFlow },\n  { topic: 'safety', payload: `${safety} | overflowing=${overflow}` },\n  { topic: 'snapshot', payload: `level=${fmt(level)} m | volume=${fmt(volume)} m3 | demand=${fmt(demand, 0)}% | direction=${direction} | t=${Number.isFinite(timeleft) ? Math.round(timeleft) + ' s' : '-'}` }\n];",
+    "func": "// MeasurementContainer flat keys are `${type}.${variant}.${position}.${childId}`.\n// When PS writes without an explicit .child(), the childId is the literal\n// string 'default' — DON'T strip it. See generalFunctions/src/measurements/\n// MeasurementContainer.js getFlattenedOutput for details.\nconst fields = (msg.payload && typeof msg.payload === 'object') ? msg.payload : {};\nconst snapshot = Object.assign({}, context.get('snapshot') || {}, fields);\ncontext.set('snapshot', snapshot);\nconst firstFinite = (...keys) => {\n  for (const key of keys) {\n    const value = Number(snapshot[key]);\n    if (Number.isFinite(value)) return value;\n  }\n  return null;\n};\nconst level = firstFinite('level.predicted.atequipment.default', 'level.measured.atequipment.default');\nconst volume = firstFinite('volume.predicted.atequipment.default', 'volume.measured.atequipment.default');\nconst netFlow = firstFinite('netFlowRate.predicted.atequipment.default', 'netFlowRate.measured.atequipment.default');\nconst demand = firstFinite('percControl');\nconst safety = snapshot.safetyState || 'normal';\nconst direction = snapshot.direction || 'unknown';\nconst overflow = snapshot.isOverflowing === true || snapshot.isOverflowing === 'true';\nconst timeleft = Number(snapshot.timeleft);\nconst fmt = (value, digits = 2) => Number.isFinite(value) ? value.toFixed(digits) : '-';\nreturn [\n  level == null ? null : { topic: 'level', payload: level },\n  volume == null ? null : { topic: 'volume', payload: volume },\n  demand == null ? null : { topic: 'demand', payload: demand },\n  netFlow == null ? null : { topic: 'net_flow', payload: netFlow },\n  { topic: 'safety', payload: `${safety} | overflowing=${overflow}` },\n  { topic: 'snapshot', payload: `level=${fmt(level)} m | volume=${fmt(volume)} m3 | demand=${fmt(demand, 0)}% | direction=${direction} | t=${Number.isFinite(timeleft) ? Math.round(timeleft) + ' s' : '-'}` }\n];",
    "outputs": 6,
    "noerr": 0,
    "initialize": "",
--- a/pumpingStation.html
+++ b/pumpingStation.html
@@ -14,6 +14,7 @@
 <!-- Editor JS modules — see nodes/pumpingStation/src/editor/. Loaded in
     dependency order: index.js (namespace + helpers) → diagrams → handlers. -->
 <script src="/pumpingStation/editor/index.js"></script>
+<script src="/pumpingStation/editor/bounds.js"></script>
 <script src="/pumpingStation/editor/basin-diagram.js"></script>
 <script src="/pumpingStation/editor/mode-preview.js"></script>
 <script src="/pumpingStation/editor/hover-couple.js"></script>
@@ -83,7 +84,9 @@
      logCurveFactor: { value: 9 },
      enableShiftedRamp: { value: false },
      shiftLevel: { value: 0 },
+      shiftArmPercent: { value: 95 },
      startLevel: { value: null },
+      stopLevel: { value: null },
      minLevel: { value: null },
      maxLevel: { value: null },
      flowSetpoint: { value: null },
@@ -126,17 +129,19 @@
  
  <h4>Basin parameters</h4>
  <p style="font-size:12px;color:#777;margin:0 0 8px 0;">Heights are measured from the basin floor (0 m). Each input on the left controls a line in the diagram on the right — hover an input to highlight its line.</p>
+  <div id="ps-basin-validation" style="display:none;color:#C0392B;font-size:11px;margin:0 0 8px 0;border:1px solid #C0392B;border-radius:3px;padding:6px 8px;background:#FDECEA;"></div>

  <style>
    /* Two-column layout: stacked colour-coded inputs on the left,
       SVG on the right. Hover an input row → its paired SVG line
       (referenced by data-couples-line) gets a thicker stroke. */
-    .ps-diag { display:flex; gap:14px; align-items:flex-start; margin:0 0 14px 0; }
-    .ps-diag-side { width: 200px; flex: 0 0 200px; display:flex; flex-direction:column; gap:6px; }
+    .ps-diag { display:flex; gap:28px; align-items:flex-start; margin:0 0 14px 0; }
+    .ps-diag-side { width: 220px; flex: 0 0 220px; display:flex; flex-direction:column; gap:6px; }
    .ps-diag-side .ps-row {
-      display:grid; grid-template-columns: 1fr 78px 18px; align-items:center;
+      display:grid; grid-template-columns: minmax(0,1fr) 70px 16px; align-items:center;
      gap:6px; padding:4px 6px 4px 10px; border-left:4px solid #ccc;
      background:#fafafa; border-radius:3px; font-size:11px; cursor:pointer;
+      min-width:0;
    }
    .ps-diag-side .ps-row:hover { background:#f0f0f0; }
    .ps-diag-side .ps-row.ps-readonly { background:#fff; cursor:default; opacity:0.85; }
@@ -266,55 +271,58 @@
    <!-- RIGHT: SVG. The viewBox is now narrower (320 wide) since the right
         input column is gone — labels render inside the tank's right margin. -->
    <svg id="ps-basin-diagram" class="ps-diag-svg" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 360 430"
-         style="display:block;width:100%;max-width:380px;background:#fff;border:1px solid #e5e5e5;border-radius:4px;"
+         style="display:block;width:100%;max-width:360px;background:#fff;border:1px solid #e5e5e5;border-radius:4px;"
         font-family="Arial,sans-serif" font-size="11">
      <defs>
        <marker id="ps-arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
          <path d="M 0 0 L 10 5 L 0 10 z" fill="#1F4E79" />
        </marker>
      </defs>
-      <!-- Tank body — x=120,width=120 (was 200,120 in the old wider viewBox).
-           Threshold tick lines extend a few px outside the tank walls. -->
-      <rect x="120" y="40" width="120" height="340" fill="#F0F8FF" stroke="#333" stroke-width="1.5" />
-      <rect id="ps-deadvol" x="121" width="118" fill="#AACCE0" />
+      <!-- Tank body — shifted right (x=145, width=110) to give the inlet
+           sub-label "bottom of pipe" room on the left without clipping.
+           Threshold tick lines extend 5 px outside the tank walls. -->
+      <rect x="145" y="40" width="110" height="340" fill="#F0F8FF" stroke="#333" stroke-width="1.5" />
+      <rect id="ps-deadvol" x="146" width="108" fill="#AACCE0" />

-      <!-- Mid-tank zone labels — centred at x=180. -->
-      <text id="ps-zone-spare"   x="180" text-anchor="middle" fill="#B78200" font-size="10" font-style="italic" visibility="hidden">Spare volume before spilling</text>
-      <text id="ps-zone-sewage"  x="180" text-anchor="middle" fill="#1F4E79" font-size="10" font-style="italic" visibility="hidden">Sewage + tank buffer</text>
-      <text id="ps-zone-buffer1" x="180" text-anchor="middle" fill="#1F4E79" font-size="10" font-style="italic" visibility="hidden">Tank buffer</text>
-      <text id="ps-zone-buffer2" x="180" text-anchor="middle" fill="#1F4E79" font-size="10" font-style="italic" visibility="hidden">Tank buffer</text>
-      <text id="ps-zone-dead"    x="180" text-anchor="middle" fill="#444" font-size="10" font-style="italic" visibility="hidden">Dead volume</text>
+      <!-- Mid-tank zone labels — centred at x=200 (tank centre). -->
+      <text id="ps-zone-spare"   x="200" text-anchor="middle" fill="#B78200" font-size="10" font-style="italic" visibility="hidden">Spare</text>
+      <text id="ps-zone-sewage"  x="200" text-anchor="middle" fill="#1F4E79" font-size="10" font-style="italic" visibility="hidden">Sewage + buffer</text>
+      <text id="ps-zone-buffer1" x="200" text-anchor="middle" fill="#1F4E79" font-size="10" font-style="italic" visibility="hidden">Buffer</text>
+      <text id="ps-zone-buffer2" x="200" text-anchor="middle" fill="#1F4E79" font-size="10" font-style="italic" visibility="hidden">Buffer</text>
+      <text id="ps-zone-dead"    x="200" text-anchor="middle" fill="#444" font-size="10" font-style="italic" visibility="hidden">Dead vol</text>

      <!-- basinHeight tick at tank rim (y=40, static). -->
-      <line id="ps-line-basinHeight" x1="115" y1="40" x2="245" y2="40" stroke="#333" stroke-width="1.5" />
-      <text id="ps-label-basinHeight" x="250" y="44" fill="#333">basinHeight</text>
+      <line id="ps-line-basinHeight" x1="140" y1="40" x2="260" y2="40" stroke="#333" stroke-width="1.5" />
+      <text id="ps-label-basinHeight" x="265" y="44" fill="#333">basinHeight</text>

-      <line id="ps-line-overflowLevel" x1="115" x2="245" stroke="#C0392B" stroke-dasharray="4 2" stroke-width="1.5" />
-      <text id="ps-label-overflowLevel" x="250" fill="#C0392B">overflowLevel</text>
+      <line id="ps-line-overflowLevel" x1="140" x2="260" stroke="#C0392B" stroke-dasharray="4 2" stroke-width="1.5" />
+      <text id="ps-label-overflowLevel" x="265" fill="#C0392B">overflowLevel</text>

-      <line id="ps-line-highVolumeSafetyLevel" x1="115" x2="245" stroke="#D68910" stroke-dasharray="1 2" stroke-width="1" opacity="0.7" />
-      <text id="ps-label-highVolumeSafetyLevel" x="250" fill="#D68910" font-size="10" font-style="italic">highVolumeSafety</text>
+      <line id="ps-line-highVolumeSafetyLevel" x1="140" x2="260" stroke="#D68910" stroke-dasharray="1 2" stroke-width="1" opacity="0.7" />
+      <text id="ps-label-highVolumeSafetyLevel" x="265" fill="#D68910" font-size="10" font-style="italic">highVolSafety</text>

-      <line id="ps-line-inflowLevelGuide" x1="120" x2="240" stroke="#1F4E79" stroke-dasharray="2 3" stroke-width="1" opacity="0.55" />
-      <text id="ps-label-inflowLevelGuide" x="250" fill="#1F4E79" font-size="10" font-style="italic">inlet invert</text>
+      <line id="ps-line-inflowLevelGuide" x1="145" x2="255" stroke="#1F4E79" stroke-dasharray="2 3" stroke-width="1" opacity="0.55" />
+      <text id="ps-label-inflowLevelGuide" x="265" fill="#1F4E79" font-size="10" font-style="italic">inlet invert</text>

-      <line id="ps-line-inflowLevel" x1="60" x2="120" stroke="#1F4E79" stroke-width="2" marker-end="url(#ps-arrow)" />
-      <text id="ps-label-inflowLevel" x="55" text-anchor="end" fill="#1F4E79" font-weight="bold">Inlet</text>
-      <text id="ps-sub-inflowLevel" x="55" text-anchor="end" fill="#777" font-size="9">bottom of pipe</text>
+      <line id="ps-line-inflowLevel" x1="85" x2="145" stroke="#1F4E79" stroke-width="2" marker-end="url(#ps-arrow)" />
+      <text id="ps-label-inflowLevel" x="80" text-anchor="end" fill="#1F4E79" font-weight="bold">Inlet</text>
+      <text id="ps-sub-inflowLevel" x="80" text-anchor="end" fill="#777" font-size="9">bottom of pipe</text>

-      <line id="ps-line-dryRunLevel" x1="115" x2="245" stroke="#C0392B" stroke-dasharray="1 2" stroke-width="1" opacity="0.6" />
-      <text id="ps-label-dryRunLevel" x="250" fill="#C0392B" font-size="10" font-style="italic">dryRunLevel</text>
+      <line id="ps-line-dryRunLevel" x1="140" x2="260" stroke="#C0392B" stroke-dasharray="1 2" stroke-width="1" opacity="0.6" />
+      <text id="ps-label-dryRunLevel" x="265" fill="#C0392B" font-size="10" font-style="italic">dryRunLevel</text>

-      <line id="ps-line-outflowLevel" x1="240" x2="280" stroke="#1F4E79" stroke-width="2" marker-end="url(#ps-arrow)" />
-      <text id="ps-label-outflowLevel" x="285" fill="#1F4E79" font-weight="bold">Outlet</text>
-      <text id="ps-sub-outflowLevel" x="285" fill="#777" font-size="9">top of pipe</text>
+      <line id="ps-line-outflowLevel" x1="255" x2="295" stroke="#1F4E79" stroke-width="2" marker-end="url(#ps-arrow)" />
+      <text id="ps-label-outflowLevel" x="300" fill="#1F4E79" font-weight="bold">Outlet</text>
+      <text id="ps-sub-outflowLevel" x="300" fill="#777" font-size="9">top of pipe</text>

-      <!-- Floor / datum -->
-      <line x1="115" y1="380" x2="245" y2="380" stroke="#000" stroke-width="2" />
-      <text x="250" y="384" fill="#000">0 m (datum)</text>
+      <!-- Floor / datum — datum label sits BELOW the tank (y=395) so it
+           never collides with the Outlet / top-of-pipe sub-label when
+           outflowLevel is near the floor. -->
+      <line x1="140" y1="380" x2="260" y2="380" stroke="#000" stroke-width="2" />
+      <text x="200" y="395" text-anchor="middle" fill="#000" font-size="10">0 m (datum)</text>

      <!-- Ordering-warning ribbon -->
-      <text id="ps-warning" x="180" y="410" text-anchor="middle" fill="#C0392B" font-size="10" font-style="italic" visibility="hidden"></text>
+      <text id="ps-warning" x="200" y="410" text-anchor="middle" fill="#C0392B" font-size="10" font-style="italic" visibility="hidden"></text>
    </svg>
  </div>

@@ -406,6 +414,11 @@
        <input type="number" id="node-input-startLevel" min="0" step="0.01" />
        <span class="ps-unit">m</span>
      </div>
+      <div class="ps-row" data-stroke="#7D3C98" data-couples-line="ps-mode-line-stopLevel">
+        <div><label>stopLevel</label><div class="ps-sub">pump-off threshold (optional, ≤ startLevel)</div></div>
+        <input type="number" id="node-input-stopLevel" min="0" step="0.01" />
+        <span class="ps-unit">m</span>
+      </div>
      <div class="ps-row ps-readonly" data-stroke="#1F4E79" data-couples-line="ps-mode-line-inflowLevel">
        <div><label>inflowLevel</label><div class="ps-sub">from basin above</div></div>
        <span id="ps-mode-readout-inflow" class="ps-readonly-val">— m</span>
@@ -417,10 +430,15 @@
        <span class="ps-unit">m</span>
      </div>
      <div class="ps-row" id="ps-shiftLevel-row" data-stroke="#D68910" data-couples-line="ps-mode-line-shiftLevel" style="display:none;">
-        <div><label>shiftLevel</label><div class="ps-sub">arms hysteresis</div></div>
+        <div><label>shiftLevel</label><div class="ps-sub">held output drops here</div></div>
        <input type="number" id="node-input-shiftLevel" min="0" step="0.01" />
        <span class="ps-unit">m</span>
      </div>
+      <div class="ps-row" id="ps-shiftArmPercent-row" data-stroke="#D68910" data-couples-line="ps-mode-line-armPercent" style="display:none;">
+        <div><label>shiftArmPercent</label><div class="ps-sub">arms when output % crosses this</div></div>
+        <input type="number" id="node-input-shiftArmPercent" min="0" max="100" step="1" />
+        <span class="ps-unit">%</span>
+      </div>
      <div class="ps-row ps-readonly" data-stroke="#C0392B" data-couples-line="ps-mode-line-overflowLevel">
        <div><label>overflowLevel</label><div class="ps-sub">from basin above</div></div>
        <span id="ps-mode-readout-overflow" class="ps-readonly-val">— m</span>
@@ -457,22 +475,32 @@
      <!-- Vertical level-marker lines — span y=24..140 (top to baseline only, NOT into OFF tier). x set dynamically. -->
      <line id="ps-mode-line-dryRunLevel"  y1="24" y2="140" stroke="#C0392B" stroke-dasharray="2 2" />
      <line id="ps-mode-line-startLevel" y1="24" y2="140" stroke="#1E8449" stroke-dasharray="2 2" />
+      <line id="ps-mode-line-stopLevel" y1="24" y2="140" stroke="#7D3C98" stroke-dasharray="2 2" />
      <line id="ps-mode-line-inflowLevel" y1="24" y2="140" stroke="#1F4E79" stroke-dasharray="2 2" />
      <line id="ps-mode-line-maxLevel" y1="24" y2="140" stroke="#D68910" stroke-dasharray="2 2" />
      <line id="ps-mode-line-overflowLevel" y1="24" y2="140" stroke="#C0392B" stroke-dasharray="2 2" />
      <line id="ps-mode-line-shiftLevel" y1="24" y2="140" stroke="#D68910" stroke-dasharray="2 2" style="display:none;" />
-      <!-- Axis labels — y=180 row sits below the OFF baseline (y=160). x set dynamically. -->
-      <text id="ps-mode-label-dryRunLevel"  y="180" text-anchor="middle" fill="#C0392B">dry run</text>
-      <text id="ps-mode-label-startLevel" y="180" text-anchor="middle" fill="#1E8449">start</text>
-      <text id="ps-mode-label-inflowLevel" y="180" text-anchor="middle" fill="#1F4E79">inlet</text>
-      <text id="ps-mode-label-maxLevel" y="180" text-anchor="middle" fill="#D68910">max</text>
-      <text id="ps-mode-label-overflowLevel" y="180" text-anchor="middle" fill="#C0392B">overflow</text>
-      <text id="ps-mode-label-shiftLevel" y="180" text-anchor="middle" fill="#D68910" style="display:none;">shift</text>
+      <!-- Horizontal arming-% line — y is set DYNAMICALLY by the JS to the
+           shiftArmPercent value (in plot-y space). Spans full plot width. -->
+      <line id="ps-mode-line-armPercent" x1="52" x2="392" stroke="#D68910" stroke-dasharray="4 3" stroke-width="1" opacity="0.7" style="display:none;" />
+      <text id="ps-mode-label-armPercent" x="394" text-anchor="start" fill="#D68910" font-size="9" style="display:none;">arm%</text>
+      <!-- Axis labels under the plot were removed — they crowded each other
+           when levels were close. Identification comes from the line colour
+           (matched to the side-panel input row) and hover-coupling. -->
+      <!-- Empty <text> stubs kept for the redraw loop's getElementById calls
+           (cheaper than guarding each one). They're hidden via display:none. -->
+      <text id="ps-mode-label-dryRunLevel"   style="display:none;"></text>
+      <text id="ps-mode-label-startLevel"    style="display:none;"></text>
+      <text id="ps-mode-label-stopLevel"     style="display:none;"></text>
+      <text id="ps-mode-label-inflowLevel"   style="display:none;"></text>
+      <text id="ps-mode-label-maxLevel"      style="display:none;"></text>
+      <text id="ps-mode-label-overflowLevel" style="display:none;"></text>
+      <text id="ps-mode-label-shiftLevel"    style="display:none;"></text>
      <!-- Legend captions — placed BELOW the axis labels (y=200) on their own row,
           so they never collide with the title (y=14). Up-caption left-aligned at
           x=60; down-caption to its right at x=210. Both font-size 10. -->
      <text id="ps-mode-curve-up-label" x="60" y="205" fill="#1E8449" font-size="10">— ramp inlet→max</text>
-      <text id="ps-mode-curve-down-label" x="210" y="205" fill="#D68910" font-size="10" style="display:none;">— shifted start→shift</text>
+      <text id="ps-mode-curve-down-label" x="210" y="205" fill="#D68910" font-size="10" style="display:none;">— shifted (held @100% then ramp shift→start)</text>
    </svg>
    </div>
  </div>
--- a/simulations/README.md
+++ b/simulations/README.md
@@ -49,6 +49,7 @@ module.exports = {
 | `max_level_bounded` | max level across the run must be `≤ value` |
 | `min_level_bounded` | min level across the run must be `≥ value` |
 | `max_demand_bounded` | max percControl must be `≤ value` |
+| `max_demand_gt` | max percControl must be `> value` |
 | `safety_trips_eq` | total ticks with `safetyActive` must equal `value` |
 | `safety_trips_gt` | total ticks with `safetyActive` must be `> value` |
 | `end_state_eq` | final record's `field` must equal `value` |
--- a/simulations/run.js
+++ b/simulations/run.js
@@ -54,6 +54,10 @@ function evalExpectation(ex, records) {
      const v = Math.max(...demands);
      return { ok: v <= ex.value, msg: `max demand = ${v.toFixed(0)} % (bound: ≤ ${ex.value})` };
    }
+    case 'max_demand_gt': {
+      const v = Math.max(...demands);
+      return { ok: v > ex.value, msg: `max demand = ${v.toFixed(0)} % (expected > ${ex.value})` };
+    }
    case 'safety_trips_eq': {
      const n = records.filter((r) => r.safetyActive).length;
      return { ok: n === ex.value, msg: `${n} ticks with safetyActive (expected ${ex.value})` };
--- a/simulations/scenarios/levelbased-steady.js
+++ b/simulations/scenarios/levelbased-steady.js
@@ -2,30 +2,30 @@
 //
 // Expectation: with a stable inflow of 0.008 m³/s and a pump bank with
 // max capacity 0.012 m³/s, the level settles in the RAMP zone (between
-// startLevel and maxLevel) at roughly the point where demand matches
+// inflowLevel and maxLevel while filling) at roughly the point where demand matches
 // inflow. No safety trips should fire.

 module.exports = {
  name: 'levelbased-steady',
  description: 'Constant sewer inflow below pump capacity; level converges inside the RAMP zone with demand matching inflow.',
-  durationSec: 1200,
+  durationSec: 3600,

  config: {
    general: { name: 'EvalSteady', id: 'eval-steady', unit: 'm3/h',
      logging: { enabled: false, logLevel: 'error' } },
    functionality: { softwareType: 'pumpingStation', role: 'stationcontroller', positionVsParent: 'atEquipment' },
-    basin: { volume: 50, height: 5, inflowLevel: 3, outflowLevel: 0.2, overflowLevel: 4.5 },
+    basin: { volume: 50, height: 5, inflowLevel: 3, outflowLevel: 0.2, overflowLevel: 4.5, inletPipeDiameter: 0.4, outletPipeDiameter: 0.3 },
    hydraulics: { refHeight: 'NAP', basinBottomRef: 0, minHeightBasedOn: 'outlet' },
    control: {
      mode: 'levelbased',
      allowedModes: new Set(['levelbased']),
-      levelbased: { minLevel: 1, startLevel: 2, maxLevel: 4 },
+      levelbased: { minLevel: 1, startLevel: 2, maxLevel: 4, curveType: 'linear', logCurveFactor: 9 },
    },
    safety: {
      enableDryRunProtection: true,
      dryRunThresholdPercent: 2,
-      enableOverfillProtection: true,
-      overfillThresholdPercent: 98,
+      enableHighVolumeSafety: true,
+      highVolumeSafetyThresholdPercent: 98,
      timeleftToFullOrEmptyThresholdSeconds: 0,
    },
  },
@@ -44,7 +44,7 @@ module.exports = {
        ps.measurements.type('flow').variant('predicted').position('out').child('mgc1').value(outflow, Date.now(), 'm3/s');
      },
    };
-    ps.calibratePredictedLevel(2.0);  // start at the bottom of the RAMP zone
+    ps.calibratePredictedLevel(2.0);  // start at the mode start level, below the rising ramp
  },

  inputs: (t, ps) => {
@@ -55,6 +55,7 @@ module.exports = {
    { name: 'no safety trips', type: 'safety_trips_eq', value: 0 },
    { name: 'level stays below overflow', type: 'max_level_bounded', value: 4.5 },
    { name: 'level stays above outflow', type: 'min_level_bounded', value: 0.2 },
+    { name: 'rising ramp engages after inlet level', type: 'max_demand_gt', value: 0 },
    { name: 'no threshold issues on init', type: 'threshold_issues_eq', value: 0 },
  ],
 };
--- a/simulations/scenarios/levelbased-storm.js
+++ b/simulations/scenarios/levelbased-storm.js
@@ -1,31 +1,31 @@
-// Storm surge — inflow triples briefly, pumps should saturate at 100%,
-// level rises toward overflow then recedes.
+// Storm surge — inflow triples briefly, pumps should increase demand as
+// the level enters the rising ramp.
 //
-// Expectation: during the surge (t=300..600), demand reaches 100% and
-// level may transiently climb above maxLevel. Overflow safety should
-// fire if the surge overwhelms pump capacity; dry-run should not fire.
+// Expectation: during the surge (t=300..600), demand rises but remains
+// bounded. High-volume safety should fire if the surge overwhelms pump
+// capacity; dry-run should not fire.

 module.exports = {
  name: 'levelbased-storm',
-  description: 'Sewer inflow triples from 0.008 → 0.024 m³/s for 5 minutes then returns to baseline. Overfill safety may engage.',
+  description: 'Sewer inflow triples from 0.008 → 0.024 m³/s for 5 minutes then returns to baseline. High-volume safety may engage.',
  durationSec: 1500,

  config: {
    general: { name: 'EvalStorm', id: 'eval-storm', unit: 'm3/h',
      logging: { enabled: false, logLevel: 'error' } },
    functionality: { softwareType: 'pumpingStation', role: 'stationcontroller', positionVsParent: 'atEquipment' },
-    basin: { volume: 50, height: 5, inflowLevel: 3, outflowLevel: 0.2, overflowLevel: 4.5 },
+    basin: { volume: 50, height: 5, inflowLevel: 3, outflowLevel: 0.2, overflowLevel: 4.5, inletPipeDiameter: 0.4, outletPipeDiameter: 0.3 },
    hydraulics: { refHeight: 'NAP', basinBottomRef: 0, minHeightBasedOn: 'outlet' },
    control: {
      mode: 'levelbased',
      allowedModes: new Set(['levelbased']),
-      levelbased: { minLevel: 1, startLevel: 2, maxLevel: 4 },
+      levelbased: { minLevel: 1, startLevel: 2, maxLevel: 4, curveType: 'linear', logCurveFactor: 9 },
    },
    safety: {
      enableDryRunProtection: true,
      dryRunThresholdPercent: 2,
-      enableOverfillProtection: true,
-      overfillThresholdPercent: 95,
+      enableHighVolumeSafety: true,
+      highVolumeSafetyThresholdPercent: 95,
      timeleftToFullOrEmptyThresholdSeconds: 0,
    },
  },
@@ -55,6 +55,6 @@ module.exports = {
    { name: 'dry-run never trips', type: 'end_state_eq', field: 'safetyActive', value: false },
    // Level may exceed maxLevel transiently but must stay under basinHeight
    { name: 'level never breaches physical basin', type: 'max_level_bounded', value: 5.0 },
-    { name: 'demand saturates at 100% during surge', type: 'max_demand_bounded', value: 100 },
+    { name: 'demand remains bounded during surge', type: 'max_demand_bounded', value: 100 },
  ],
 };
--- a/simulations/scenarios/safety-dry-run-trip.js
+++ b/simulations/scenarios/safety-dry-run-trip.js
@@ -12,18 +12,18 @@ module.exports = {
    general: { name: 'EvalDryRun', id: 'eval-dry-run', unit: 'm3/h',
      logging: { enabled: false, logLevel: 'error' } },
    functionality: { softwareType: 'pumpingStation', role: 'stationcontroller', positionVsParent: 'atEquipment' },
-    basin: { volume: 50, height: 5, inflowLevel: 3, outflowLevel: 0.2, overflowLevel: 4.5 },
+    basin: { volume: 50, height: 5, inflowLevel: 3, outflowLevel: 0.2, overflowLevel: 4.5, inletPipeDiameter: 0.4, outletPipeDiameter: 0.3 },
    hydraulics: { refHeight: 'NAP', basinBottomRef: 0, minHeightBasedOn: 'outlet' },
    control: {
      mode: 'manual',
      allowedModes: new Set(['levelbased', 'manual']),
-      levelbased: { minLevel: 0.5, startLevel: 2, maxLevel: 4 },
+      levelbased: { minLevel: 0.5, startLevel: 2, maxLevel: 4, curveType: 'linear', logCurveFactor: 9 },
    },
    safety: {
      enableDryRunProtection: true,
      dryRunThresholdPercent: 50,
-      enableOverfillProtection: false,
-      overfillThresholdPercent: 98,
+      enableHighVolumeSafety: false,
+      highVolumeSafetyThresholdPercent: 98,
      timeleftToFullOrEmptyThresholdSeconds: 0,
    },
  },
--- a/src/editor/basin-diagram.js
+++ b/src/editor/basin-diagram.js
@@ -69,12 +69,18 @@
      }
      for (const it of items) placeItem(it.id, it.y);

+      // Zone labels show only when the gap between the bracketing
+      // thresholds is at least MIN_ZONE_GAP px high — otherwise the label
+      // collides with one of the threshold labels (which sit at threshold
+      // y ±6 px text-height). 28 px keeps a 6 px clear gap above and
+      // below the zone label.
+      const MIN_ZONE_GAP = 28;
      const placeZone = (zoneId, topId, botId) => {
        const el = document.getElementById(`ps-zone-${zoneId}`);
        if (!el) return;
        const top = items.find(it => it.id === topId);
        const bot = items.find(it => it.id === botId);
-        if (!top || !bot || (bot.y - top.y) < 14) {
+        if (!top || !bot || (bot.y - top.y) < MIN_ZONE_GAP) {
          el.setAttribute('visibility', 'hidden'); return;
        }
        el.setAttribute('y', (top.y + bot.y) / 2 + 3);
@@ -127,21 +133,59 @@
      const d2 = document.getElementById('derived-highVolumeSafetyLevel');
      if (d2) d2.textContent = fmt(highLvl);

-      const warn = document.getElementById('ps-warning');
+      // Hierarchy validation. Soft '≤' relations follow the user's choice:
+      // start ≤ inflow, max ≤ overflow, overflow ≤ basinHeight (equality OK).
+      // dryRunLevel must be < startLevel strictly (otherwise the runtime
+      // would trip dry-run before it could ramp).
+      // Re-read the raw value (basinH falls back to 5 for diagram scaling;
+      // here we want null when the user hasn't entered anything so the
+      // ≤-checks below are skipped rather than false-flagged).
+      const basinHraw = fNum('basinHeight');
+      const start = fNum('startLevel');
+      const inlet = fNum('inflowLevel');
+      const max   = fNum('maxLevel');
+      const ovfl  = fNum('overflowLevel');
      const issues = [];
-      const pairs = [
-        ['outflowLevel', 'inflowLevel',   '<'],
-        ['inflowLevel',  'overflowLevel', '<'],
-      ];
-      for (const [a, b, op] of pairs) {
-        const av = fNum(a), bv = fNum(b);
-        if (av == null || bv == null) continue;
-        if (op === '<' ? !(av < bv) : !(av <= bv)) issues.push(`${a} ${op} ${b}`);
+      const ok = (a, b, op) => {
+        if (!Number.isFinite(a) || !Number.isFinite(b)) return true;
+        return op === '<' ? a < b : a <= b;
+      };
+      if (Number.isFinite(refLow) && refLow <= 0)
+        issues.push('outflowLevel must be > 0');
+      if (!ok(dryLvl, start, '<'))
+        issues.push(`dryRunLevel (${(dryLvl ?? NaN).toFixed(2)} m, derived) must be < startLevel — lower dryRun% or raise startLevel`);
+      if (!ok(start, inlet, '<='))
+        issues.push('startLevel must be ≤ inflowLevel');
+      if (!ok(inlet, max, '<='))
+        issues.push('inflowLevel must be ≤ maxLevel');
+      if (!ok(max, ovfl, '<='))
+        issues.push('maxLevel must be ≤ overflowLevel');
+      if (!ok(ovfl, basinHraw, '<='))
+        issues.push('overflowLevel must be ≤ basinHeight');
+
+      // Visible ribbon above the basin diagram.
+      const warnDiv = document.getElementById('ps-basin-validation');
+      if (warnDiv) {
+        if (issues.length) {
+          warnDiv.innerHTML = '⚠ Fix before deploy:<ul style="margin:4px 0 0 18px;padding:0;">'
+            + issues.map((i) => `<li>${i}</li>`).join('') + '</ul>';
+          warnDiv.style.display = '';
+        } else {
+          warnDiv.style.display = 'none';
+        }
      }
+      // Legacy in-SVG warning text — kept for the small reminder inside
+      // the diagram. Only shows the count.
+      const warn = document.getElementById('ps-warning');
      if (warn) {
-        if (issues.length) { warn.setAttribute('visibility', 'visible'); warn.textContent = `⚠ Check ordering: ${issues.join(', ')}`; }
-        else { warn.setAttribute('visibility', 'hidden'); }
+        if (issues.length) {
+          warn.setAttribute('visibility', 'visible');
+          warn.textContent = `⚠ ${issues.length} ordering issue${issues.length > 1 ? 's' : ''}`;
+        } else {
+          warn.setAttribute('visibility', 'hidden');
+        }
      }
+      window._psBasinValidationIssues = issues;
    },
  };
 })();
--- a/src/editor/bounds.js
+++ b/src/editor/bounds.js
@@ -0,0 +1,96 @@
+// PumpingStation editor — dynamic input bounds.
+// Sets HTML5 min/max attributes on every level and percent input based on
+// the current values of related inputs, so the up/down arrows stop at
+// values that respect the basin hierarchy:
+//
+//   0 < outflowLevel < dryRunLevel < startLevel ≤ inflowLevel
+//       ≤ shiftLevel ≤ maxLevel ≤ overflowLevel ≤ basinHeight
+//
+// The user can still type out-of-range values via the keyboard (HTML5
+// min/max only constrain the spinner). The validation ribbons in
+// basin-diagram.js and mode-preview.js catch typed violations and the
+// oneditsave handler blocks Deploy until they're resolved.
+
+(function () {
+  const ns = window.PSEditor = window.PSEditor || {};
+  const fNum = (id) => ns.fNum(id);
+  const EPS = 0.001; // smallest meaningful step (mm-precision)
+
+  const setBounds = (id, min, max) => {
+    const el = document.getElementById(`node-input-${id}`);
+    if (!el) return;
+    if (Number.isFinite(min)) el.setAttribute('min', String(min));
+    else el.removeAttribute('min');
+    if (Number.isFinite(max)) el.setAttribute('max', String(max));
+    else el.removeAttribute('max');
+  };
+
+  ns.bounds = {
+    apply() {
+      const basinHeight = fNum('basinHeight');
+      const outflow     = fNum('outflowLevel');
+      const dryPct      = fNum('dryRunThresholdPercent');
+      const start       = fNum('startLevel');
+      const inlet       = fNum('inflowLevel');
+      const max         = fNum('maxLevel');
+      const overflow    = fNum('overflowLevel');
+      const shiftEnabled = !!document.getElementById('node-input-enableShiftedRamp')?.checked;
+
+      // Derived dryRunLevel (lower bound for startLevel).
+      const dryRun = (Number.isFinite(outflow) && Number.isFinite(dryPct))
+        ? outflow * (1 + dryPct / 100) : null;
+
+      // Geometry — basin envelope.
+      setBounds('basinHeight',   EPS, undefined);
+      setBounds('basinVolume',   EPS, undefined);
+
+      // Levels (each capped by the next-higher level if defined).
+      setBounds('outflowLevel',  EPS,
+        Number.isFinite(start) && Number.isFinite(dryPct)
+          ? start / (1 + dryPct / 100) - EPS  // keep dryRun < start
+          : (start ?? inlet ?? max ?? overflow ?? basinHeight));
+
+      setBounds('startLevel',
+        Number.isFinite(dryRun) ? dryRun + EPS : EPS,
+        inlet ?? max ?? overflow ?? basinHeight);
+
+      setBounds('inflowLevel',
+        start ?? EPS,
+        max ?? overflow ?? basinHeight);
+
+      setBounds('maxLevel',
+        inlet ?? start ?? EPS,
+        overflow ?? basinHeight);
+
+      setBounds('overflowLevel',
+        max ?? inlet ?? start ?? EPS,
+        basinHeight);
+
+      // stopLevel — explicit pump-off threshold. Must sit between
+      // dryRunLevel and startLevel (so it can be reached during draining
+      // before pumps re-engage).
+      setBounds('stopLevel',
+        Number.isFinite(dryRun) ? dryRun + EPS : EPS,
+        start ?? inlet ?? max ?? overflow ?? basinHeight);
+
+      // Shift inputs (only relevant when shifted ramp enabled).
+      if (shiftEnabled) {
+        setBounds('shiftLevel',
+          Number.isFinite(start) ? start : EPS,
+          max ?? overflow ?? basinHeight);
+        setBounds('shiftArmPercent', 1, 100);
+      }
+
+      // Percentages.
+      // dryRun% capped so dryRunLevel ≤ startLevel.
+      let dryMax = 99;
+      if (Number.isFinite(start) && Number.isFinite(outflow) && outflow > 0) {
+        dryMax = Math.max(0, Math.min(99, ((start / outflow) - 1) * 100));
+      }
+      setBounds('dryRunThresholdPercent', 0, dryMax);
+
+      // highVol% bounded (1, 100). Equal to 100 means no margin to overflow.
+      setBounds('highVolumeSafetyThresholdPercent', 1, 100);
+    },
+  };
+})();
--- a/src/editor/mode-preview.js
+++ b/src/editor/mode-preview.js
@@ -25,6 +25,11 @@
      const start = fNum('startLevel');
      const inlet = fNum('inflowLevel');
      const max = fNum('maxLevel');
+      // Optional stopLevel — explicit pump-off threshold. Drawn as its
+      // own marker line; does NOT shift the ramp foot. Must be < startLevel
+      // for the marker to render.
+      const stopRaw = fNum('stopLevel');
+      const stop = Number.isFinite(stopRaw) && stopRaw >= 0 && Number.isFinite(start) && stopRaw < start ? stopRaw : null;
      // dryRunLevel is derived from the basin's outflowLevel + dryRun%
      // (no separate input). Below dryRunLevel the runtime hard-stops;
      // we draw it as the leftmost vertical marker so the user sees
@@ -34,6 +39,8 @@
      const shiftEnabled = !!document.getElementById('node-input-enableShiftedRamp')?.checked;
      const shiftRaw = fNum('shiftLevel');
      const shift = Number.isFinite(shiftRaw) && shiftRaw > 0 ? Math.min(shiftRaw, max ?? shiftRaw) : null;
+      const armRaw = fNum('shiftArmPercent');
+      const armPct = Number.isFinite(armRaw) ? Math.max(0, Math.min(100, armRaw)) : 95;
      const curveType = document.getElementById('node-input-levelCurveType')?.value || 'linear';
      const factorRaw = parseFloat(document.getElementById('node-input-logCurveFactor')?.value);
      const factor = Number.isFinite(factorRaw) && factorRaw > 0 ? factorRaw : 9;
@@ -83,14 +90,43 @@
        return pts.join(' ');
      };

+      // Up curve. Foot is startLevel (the configured pump-on threshold and
+      // ramp foot per the runtime in _controlLevelBased). The OFF baseline
+      // is drawn for level < startLevel; at startLevel demand jumps from
+      // OFF to 0 % and ramps up to 100 % at maxLevel.
      const up = document.getElementById('ps-mode-curve-up');
      const down = document.getElementById('ps-mode-curve-down');
      const downLabel = document.getElementById('ps-mode-curve-down-label');
-      if (up) up.setAttribute('points', buildPath(start, inlet, max));
+      if (up) up.setAttribute('points', buildPath(start, start, max));
+
+      // Shifted-DOWN curve (only when shift enabled): represents the
+      // worst-case held-then-ramp path drawn for hold=100 % (the SVG
+      // ideal). Geometry: 100 % flat from levelMax back to shiftLevel,
+      // then linear/log ramp from (shiftLevel, 100 %) down to
+      // (startLevel, 0 %), then OFF below startLevel.
+      // Real runtime hold value depends on where direction flips, so the
+      // preview shows the maximum extent.
+      const buildShiftedDown = () => {
+        if (![start, shift].every(Number.isFinite) || shift <= start) return '';
+        const pts = [];
+        // OFF baseline far-left to startLevel
+        pts.push(`${xFor(levelMin)},${yForPct(yOffPct)}`);
+        pts.push(`${xFor(start)},${yForPct(yOffPct)}`);
+        // Jump 0 % at startLevel
+        pts.push(`${xFor(start)},${yForPct(0)}`);
+        // Ramp start→shift = 0..100 % (peak hold = 100 % for this preview)
+        for (let i = 0; i <= 24; i++) {
+          const t = i / 24;
+          const lvl = start + t * (shift - start);
+          pts.push(`${xFor(lvl)},${yForPct(scale(t) * 100)}`);
+        }
+        // Held at 100 % from shift → far-right
+        pts.push(`${xFor(levelMax)},${yForPct(100)}`);
+        return pts.join(' ');
+      };
      if (down) {
        if (shiftEnabled) {
-          const shiftedTop = Number.isFinite(shift) && shift > start ? shift : max;
-          down.setAttribute('points', buildPath(start, start, shiftedTop));
+          down.setAttribute('points', buildShiftedDown());
          down.style.display = '';
          if (downLabel) downLabel.style.display = '';
        } else {
@@ -100,27 +136,44 @@
        }
      }

-      // Vertical level markers + axis labels.
+      // Horizontal arming-% line — only meaningful when shift enabled.
+      const armLine = document.getElementById('ps-mode-line-armPercent');
+      const armLabel = document.getElementById('ps-mode-label-armPercent');
+      if (armLine && armLabel) {
+        if (shiftEnabled) {
+          const yArm = yForPct(armPct);
+          armLine.setAttribute('y1', yArm);
+          armLine.setAttribute('y2', yArm);
+          armLabel.setAttribute('y', yArm - 2);
+          armLabel.textContent = `arm ${Math.round(armPct)}%`;
+          armLine.style.display = '';
+          armLabel.style.display = '';
+        } else {
+          armLine.style.display = 'none';
+          armLabel.style.display = 'none';
+        }
+      }
+
+      // Vertical level markers — line only. Axis labels were removed;
+      // identification comes from line colour + side-panel labels +
+      // hover coupling.
      [
        ['dryRunLevel', dryRun],
        ['startLevel', start],
+        ['stopLevel', stop],
        ['inflowLevel', inlet],
        ['maxLevel', max],
        ['overflowLevel', overflow],
      ].forEach(([id, level]) => {
        const line = document.getElementById(`ps-mode-line-${id}`);
-        const label = document.getElementById(`ps-mode-label-${id}`);
-        if (!line || !label) return;
+        if (!line) return;
        if (!Number.isFinite(level)) {
          line.style.display = 'none';
-          label.style.display = 'none';
          return;
        }
        const x = xFor(level);
        line.style.display = '';
-        label.style.display = '';
        line.setAttribute('x1', x); line.setAttribute('x2', x);
-        label.setAttribute('x', x);
      });

      // Background zone bands.
@@ -146,19 +199,15 @@
      setBand('ps-zone-safetyHigh', xMax,  xOvf);
      setBand('ps-zone-overflow',   xOvf,  plotR);

-      // Shift level marker.
+      // Shift level marker (line only).
      const shiftLine = document.getElementById('ps-mode-line-shiftLevel');
-      const shiftLabel = document.getElementById('ps-mode-label-shiftLevel');
-      if (shiftLine && shiftLabel) {
+      if (shiftLine) {
        if (shiftEnabled && Number.isFinite(shift)) {
          const x = xFor(shift);
          shiftLine.setAttribute('x1', x); shiftLine.setAttribute('x2', x);
-          shiftLabel.setAttribute('x', x);
          shiftLine.style.display = '';
-          shiftLabel.style.display = '';
        } else {
          shiftLine.style.display = 'none';
-          shiftLabel.style.display = 'none';
        }
      }

@@ -167,6 +216,8 @@
      if (curveLabel) curveLabel.textContent = curveType === 'log' ? 'log curve: fast early response' : 'linear curve';
      const shiftRow = document.getElementById('ps-shiftLevel-row');
      if (shiftRow) shiftRow.style.display = shiftEnabled ? '' : 'none';
+      const armRow = document.getElementById('ps-shiftArmPercent-row');
+      if (armRow) armRow.style.display = shiftEnabled ? '' : 'none';
      const logRow = document.getElementById('ps-log-factor-row');
      if (logRow) logRow.style.display = curveType === 'log' ? '' : 'none';

@@ -179,17 +230,21 @@
          shiftInput.value = (max * 0.9).toFixed(2);
        }
      }
+      // Auto-default shiftArmPercent to 95 % when shift is enabled and the
+      // current value is missing / out of [0, 100].
+      const armInput = document.getElementById('node-input-shiftArmPercent');
+      if (shiftEnabled && armInput) {
+        const cur = parseFloat(armInput.value);
+        if (!Number.isFinite(cur) || cur < 0 || cur > 100) {
+          armInput.value = 95;
+        }
+      }

-      // Validation: ordering constraints.
+      // Validation: only mode-specific (shift) ordering. Basin-level
+      // hierarchy (start ≤ inlet ≤ max ≤ overflow ≤ basinHeight,
+      // dryRun < start) is owned by basin-diagram.js so it shows in the
+      // basin section near the offending inputs.
      const issues = [];
-      if (Number.isFinite(dryRun) && Number.isFinite(start) && dryRun >= start)
-        issues.push('dryRunLevel (derived) must be < startLevel — increase startLevel or lower dryRun%');
-      if (Number.isFinite(start) && Number.isFinite(inlet) && start >= inlet)
-        issues.push('startLevel must be < inflowLevel (set in basin above)');
-      if (Number.isFinite(inlet) && Number.isFinite(max) && inlet >= max)
-        issues.push('inflowLevel must be < maxLevel');
-      if (Number.isFinite(max) && Number.isFinite(overflow) && max > overflow)
-        issues.push('maxLevel must be ≤ overflowLevel');
      if (shiftEnabled) {
        const shiftVal = Number(shiftInput?.value);
        if (Number.isFinite(shiftVal)) {
@@ -200,6 +255,9 @@
        } else {
          issues.push('shiftLevel is required when shifted ramp is enabled');
        }
+        const armVal = Number(armInput?.value);
+        if (!Number.isFinite(armVal) || armVal <= 0 || armVal > 100)
+          issues.push('shiftArmPercent must be in (0, 100]');
      }
      const warnBox = document.getElementById('ps-mode-validation');
      if (warnBox) {
--- a/src/editor/oneditprepare.js
+++ b/src/editor/oneditprepare.js
@@ -68,6 +68,7 @@
    ns.setNumberField('node-input-maxLevel',       node.maxLevel);
    ns.setNumberField('node-input-logCurveFactor', node.logCurveFactor);
    ns.setNumberField('node-input-shiftLevel',     node.shiftLevel);
+    ns.setNumberField('node-input-shiftArmPercent', Number.isFinite(node.shiftArmPercent) ? node.shiftArmPercent : 95);
    ns.setNumberField('node-input-flowSetpoint',   node.flowSetpoint);
    ns.setNumberField('node-input-flowDeadband',   node.flowDeadband);

@@ -87,12 +88,24 @@
      // so the mode preview must redraw when either of those change.
      ['startLevel', 'maxLevel', 'inflowLevel', 'outflowLevel', 'overflowLevel',
       'dryRunThresholdPercent',
-       'levelCurveType', 'logCurveFactor', 'enableShiftedRamp', 'shiftLevel'],
+       'levelCurveType', 'logCurveFactor', 'enableShiftedRamp', 'shiftLevel',
+       'shiftArmPercent'],
      ns.modePreview.redraw
    );

+    // Whenever any level/percent input changes, refresh the bounds first
+    // so the next redraw + validation sees the correct min/max attrs.
+    ns.bindRedraw(
+      ['basinHeight', 'basinVolume', 'overflowLevel', 'maxLevel',
+       'inflowLevel', 'startLevel', 'outflowLevel',
+       'dryRunThresholdPercent', 'highVolumeSafetyThresholdPercent',
+       'enableShiftedRamp', 'shiftLevel', 'shiftArmPercent'],
+      () => ns.bounds?.apply()
+    );
+
    // Initial render + hover-couple wiring once the DOM is settled.
    setTimeout(() => {
+      ns.bounds?.apply();
      ns.basinDiagram.redraw();
      ns.modePreview.redraw();
      ns.hoverCouple?.init();
--- a/src/editor/oneditsave.js
+++ b/src/editor/oneditsave.js
@@ -10,8 +10,12 @@
  ns.oneditsave = function () {
    const node = this;

-    // Block save if the inline validator surfaced any issues.
-    const issues = window._psModeValidationIssues || [];
+    // Block save if EITHER validator surfaced any issues. basin-diagram
+    // owns hierarchy issues (start ≤ inlet ≤ max ≤ overflow ≤ basinHeight,
+    // dryRun < start). mode-preview owns shift-specific issues.
+    const basinIssues = window._psBasinValidationIssues || [];
+    const modeIssues  = window._psModeValidationIssues  || [];
+    const issues = [...basinIssues, ...modeIssues];
    if (issues.length) {
      if (typeof RED !== 'undefined' && RED.notify) {
        RED.notify('PumpingStation config invalid:<br>• ' + issues.join('<br>• '),
@@ -55,6 +59,8 @@
    node.enableShiftedRamp = !!document.getElementById('node-input-enableShiftedRamp')?.checked;
    const shiftLevelVal = parseNum('node-input-shiftLevel');
    node.shiftLevel = Number.isFinite(shiftLevelVal) ? shiftLevelVal : 0;
+    const armPctVal = parseNum('node-input-shiftArmPercent');
+    node.shiftArmPercent = Number.isFinite(armPctVal) ? armPctVal : 95;
    const flowSetpoint = parseNum('node-input-flowSetpoint');
    const flowDeadband = parseNum('node-input-flowDeadband');
    if (Number.isFinite(flowSetpoint)) node.flowSetpoint = flowSetpoint;
--- a/src/nodeClass.js
+++ b/src/nodeClass.js
@@ -66,11 +66,13 @@ class nodeClass {
        levelbased:{
          minLevel:uiConfig.minLevel,
          startLevel:uiConfig.startLevel,
+          stopLevel: uiConfig.stopLevel,
          maxLevel:uiConfig.maxLevel,
          curveType: uiConfig.levelCurveType || uiConfig.curveType,
          logCurveFactor: uiConfig.logCurveFactor,
          enableShiftedRamp: uiConfig.enableShiftedRamp,
-          shiftLevel: uiConfig.shiftLevel
+          shiftLevel: uiConfig.shiftLevel,
+          shiftArmPercent: uiConfig.shiftArmPercent
        }
      },
      safety:{
--- a/src/specificClass.js
+++ b/src/specificClass.js
@@ -45,7 +45,7 @@ class PumpingStation {
    // keep the basin geometry math unit-consistent.
    this.measurements = new MeasurementContainer({
      autoConvert: true,
-      preferredUnits: { flow: 'm3/s', netFlowRate: 'm3/s', level: 'm', volume: 'm3' }
+      preferredUnits: { flow: 'm3/s', netFlowRate: 'm3/s', level: 'm', volume: 'm3', overflowVolume: 'm3' }
    });

    // --- Child registries ---
@@ -105,13 +105,41 @@ class PumpingStation {
    // levelbased mode.  Exposed in getOutput() for dashboards.
    this.percControl = 0;

-    // --- Level-armed hysteresis state ---
-    // _shiftArmed flips true when level rises past shiftLevel (with
-    // enableShiftedRamp). While armed, the demand ramp's lower foot
-    // is startLevel instead of inflowLevel — so on the way down the
-    // pumps stay aggressive until level falls below startLevel, at
-    // which point the arm clears.
+    // --- Level-armed hysteresis state (see _controlLevelBased) ---
+    // _shiftArmed: true once up-curve output % crosses shiftArmPercent on
+    //   the way up. Cleared when level drops to startLevel.
+    // _shiftHoldValue: captured on every filling→draining transition while
+    //   armed. The output stays at this value while level drops from the
+    //   flip point to shiftLevel; below shiftLevel it ramps to 0 % at
+    //   startLevel (linear or log shape).
+    // _lastDirection: tracks the previous tick's direction so we can
+    //   detect filling→draining transitions. We don't update it on
+    //   'steady' ticks so transitions through the dead-band are preserved.
    this._shiftArmed = false;
+    this._shiftHoldValue = null;
+    this._lastDirection = null;
+
+    // --- stopLevel hysteresis (Schmitt trigger) ---
+    // Levelbased control uses two thresholds:
+    //   - startLevel: ramp foot AND rising-edge engage point. Demand
+    //     scales 0..100 % over [startLevel, maxLevel].
+    //   - stopLevel:  falling-edge disengage point. Pumps stay engaged
+    //     (running at minimum flow) while level drains through
+    //     [stopLevel, startLevel]; below stopLevel they're turned off.
+    //
+    // _stopHystRunning is the engaged-state flag: flips TRUE when level
+    // crosses startLevel on the way up, FALSE when level crosses stopLevel
+    // on the way down. While engaged AND level < startLevel (i.e. the
+    // basin is draining through the dead band) the controller emits a
+    // small keep-alive percControl so MGC keeps a single pump running
+    // until level reaches stopLevel. Without this, percControl=0 in the
+    // dead band would let MGC turn the pump off, the basin would refill,
+    // and the pump would oscillate at startLevel instead of running for
+    // a full drain stroke.
+    //
+    // Editor preview also reads _stopHystRunning to shade the hysteresis
+    // band; runtime semantics are now explicit (no longer "bookkeeping").
+    this._stopHystRunning = false;

    // --- Flow dead-band ---
    // flowThreshold (m3/s) prevents control actions on noise.
@@ -339,8 +367,9 @@ class PumpingStation {
    }
  }

-  async _controlLevelBased(_direction) {
-    const { startLevel, minLevel } = this.config.control.levelbased;
+  async _controlLevelBased(direction) {
+    const cfg = this.config.control.levelbased;
+    const { startLevel, minLevel } = cfg;
    const levelUnit = this.measurements.getUnit('level');

    const level = this._pickVariant('level', this.levelVariants, 'atequipment', levelUnit);
@@ -349,49 +378,167 @@ class PumpingStation {
      return;
    }

-    // Level-based pump control via MGC (see wiki/modes/levelbased.md).
+    // Level-based pump control via MGC. See wiki/modes/levelbased.md.
    //
+    // Always:
    //   level < minLevel              → STOP (unconditional MGC shutdown)
-    //   level < startLevel            → 0 % (pumps held off)
-    //   level in [startLevel..rampStart] → 0 %  (HOLD zone)
-    //   level in [rampStart..maxLevel]  → 0..100 % (linear or log curve)
-    //   level > maxLevel              → ≥100 % (MGC clamps internally)
+    //   level < inflowLevel           → 0 % (HOLD zone, pumps idle)
+    //   level in [inflow..max]        → up curve 0..100 % (linear or log)
+    //   level > maxLevel              → 100 % (MGC clamps internally)
    //
-    // With enableShiftedRamp:
-    //   rampStart = inflowLevel by default
-    //   when level rises past shiftLevel → arm  → rampStart = startLevel
-    //   when level drops below startLevel → disarm → rampStart = inflowLevel
-    // Without enableShiftedRamp: rampStart = inflowLevel always.
+    // With enableShiftedRamp (hysteresis):
+    //   When up-curve % rises past shiftArmPercent → ARMED.
+    //   On the next filling→draining transition while armed → capture
+    //     hold = current up-curve %.
+    //   While armed AND draining:
+    //     level >= shiftLevel → output = hold (held)
+    //     level in [start..shift] → output ramps hold→0 % over the range
+    //     level <  startLevel  → output = 0 %
+    //   While armed AND filling/steady → output = up curve (resets hold).
+    //   Disarms only when level <= startLevel.

    if (level < minLevel) {
      this.percControl = 0;
+      this._shiftHoldValue = null;
+      this._shiftArmed = false;
+      this._stopHystRunning = false;
+      this._lastDirection = direction;
      Object.values(this.machineGroups).forEach((group) => group.turnOffAllMachines());
      return;
    }

-    this._updateShiftArmed(level);
-    const rampStartLevel = this._levelBasedRampStart();
-    const rampTopLevel = this._levelBasedRampTop();
+    // stopLevel hysteresis (Schmitt trigger).
+    //   _stopHystRunning becomes TRUE  on rising edge at startLevel
+    //                              FALSE on falling edge at stopLevel
+    // While engaged AND level < startLevel (basin draining through the
+    // dead band), the controller emits a small keep-alive percControl so
+    // a single pump keeps running until level reaches stopLevel. Without
+    // hysteresis the pump would oscillate at startLevel because the
+    // up-curve goes through 0 there.
+    const stopLvl = Number(cfg.stopLevel);
+    const stopThresholdActive = Number.isFinite(stopLvl) && stopLvl >= 0 && stopLvl < cfg.maxLevel;

-    // HOLD/MINIMUM DEMAND — below the active ramp start, command 0 %
-    // without latching dry-run. Dry-run remains the safety layer's job.
-    if (level < rampStartLevel) {
+    if (stopThresholdActive && level <= stopLvl) {
+      // Hard off: drained past stopLevel.
      this.percControl = 0;
-      await this._applyMachineGroupLevelControl(0);
+      this._stopHystRunning = false;
+      this._lastDirection = direction;
+      Object.values(this.machineGroups).forEach((group) => group.turnOffAllMachines());
      return;
    }
+    // Update Schmitt-trigger engaged state.
+    if (stopThresholdActive) {
+      if (!this._stopHystRunning && level >= startLevel) this._stopHystRunning = true;
+      // disengage on falling edge is handled by the `level <= stopLvl` block above.
+    } else {
+      // No stopLevel configured → no hysteresis; engaged only while level >= startLevel.
+      this._stopHystRunning = level >= startLevel;
+    }
+
+    // Up-curve value. Foot stays at startLevel (per the user-set demand
+    // ramp), top is maxLevel. Below startLevel the curve gives 0 %; above
+    // maxLevel it saturates at 100 %.
+    const rampFoot = startLevel;
+    const upPct = this._scaleLevelToFlowPercent(level, rampFoot, cfg.maxLevel);
+
+    // Update arming flag.
+    if (cfg.enableShiftedRamp) {
+      const armPct = Number.isFinite(cfg.shiftArmPercent) ? cfg.shiftArmPercent : 95;
+      if (!this._shiftArmed && upPct >= armPct) {
+        this._shiftArmed = true;
+        this.logger.debug(`Shift armed: upPct=${upPct} >= ${armPct}`);
+      }
+    } else {
+      this._shiftArmed = false;
+    }
+    if (level <= startLevel) {
+      this._shiftArmed = false;
+      this._shiftHoldValue = null;
+    }
+
+    // Capture hold on filling→draining transition while armed.
+    if (cfg.enableShiftedRamp && this._shiftArmed) {
+      if (this._lastDirection !== 'draining' && direction === 'draining') {
+        this._shiftHoldValue = upPct;
+        this.logger.debug(`Shift hold captured: ${upPct} % at level=${level}`);
+      } else if (direction === 'filling') {
+        // Returning to filling clears any captured hold; the next drain
+        // transition will recapture from the up curve.
+        this._shiftHoldValue = null;
+      }
+    }
+    if (direction === 'filling' || direction === 'draining') {
+      this._lastDirection = direction;
+    }
+
+    // Compute output.
+    let percControl;
+    const inDrainingHold = cfg.enableShiftedRamp && this._shiftArmed
+      && direction === 'draining' && this._shiftHoldValue != null;
+
+    if (!inDrainingHold) {
+      // Up curve: 0 % below the ramp foot (startLevel), scaled
+      // startLevel..maxLevel → 0..100 %, saturates above maxLevel.
+      // While engaged via the stopLevel Schmitt trigger AND level is
+      // inside the dead band [stopLevel, startLevel], emit a small
+      // keep-alive value so MGC's normalized scaling resolves to flow.min
+      // (a single pump at minimum stable speed) and the basin actually
+      // drains. Configurable via levelbased.deadZoneKeepAlivePercent
+      // (default 1%). Ramp foot stays at startLevel — keep-alive is a
+      // separate "engaged in dead band" signal, not a shifted ramp.
+      if (level < rampFoot) {
+        if (stopThresholdActive && this._stopHystRunning) {
+          const keepAlive = Number.isFinite(Number(cfg.deadZoneKeepAlivePercent))
+            ? Number(cfg.deadZoneKeepAlivePercent) : 1;
+          percControl = Math.max(0, keepAlive);
+        } else {
+          percControl = 0;
+        }
+      } else {
+        percControl = Math.max(0, upPct);
+      }
+    } else {
+      const hold = this._shiftHoldValue;
+      const shift = cfg.shiftLevel;
+      if (!Number.isFinite(shift) || shift <= startLevel) {
+        // Bad config — fall back to up curve.
+        percControl = Math.max(0, upPct);
+      } else if (level >= shift) {
+        percControl = hold;
+      } else if (level > startLevel) {
+        // Ramp from (shiftLevel, hold) down to (startLevel, 0).
+        // Use the same curve shape (linear/log) as the up curve, scaled to
+        // peak at hold% at level=shiftLevel.
+        const x = (level - startLevel) / (shift - startLevel);
+        const shaped = this._curveShape(x);
+        percControl = Math.max(0, hold * shaped);
+      } else {
+        percControl = 0;
+      }
+    }

-    // RUN — above rampStartLevel, compute demand and forward to MGC.
-    // _scaleLevelToFlowPercent maps [rampStartLevel..rampTopLevel] → [0..100].
-    // Above rampTopLevel demand saturates at 100 %.
-    const rawPercControl = this._scaleLevelToFlowPercent(level, rampStartLevel, rampTopLevel);
-    const percControl = Math.max(0, rawPercControl);
    this.percControl = percControl;
-    this.logger.debug(`Level-based control: level=${level} armed=${this._shiftArmed} foot=${rampStartLevel} top=${rampTopLevel} percControl=${percControl}`);
+    this.logger.debug(
+      `Level-based: level=${level} dir=${direction} armed=${this._shiftArmed} hold=${this._shiftHoldValue} pct=${percControl}`
+    );

    await this._applyMachineGroupLevelControl(percControl);
  }

+  // Apply the configured curve shape to a normalized x in [0,1].
+  // Returns shaped value in [0,1]. Linear by default; log when curveType
+  // is 'log' (with logCurveFactor).
+  _curveShape(x) {
+    const { curveType = 'linear', logCurveFactor = 9 } = this.config.control.levelbased;
+    const clamped = Math.max(0, Math.min(1, x));
+    if (curveType === 'log') {
+      const factor = Number.isFinite(Number(logCurveFactor)) && Number(logCurveFactor) > 0
+        ? Number(logCurveFactor) : 9;
+      return Math.log1p(factor * clamped) / Math.log1p(factor);
+    }
+    return clamped;
+  }
+
  _controlFlowBased() {
    // placeholder for flow-based logic
  }
@@ -405,6 +552,16 @@ class PumpingStation {
   */
  async forwardDemandToChildren(demand) {
    this.logger.info(`Manual demand forwarded: ${demand}`);
+    // Manual-mode explicit stop: MGC's handleInput now treats demand=0 as
+    // "hold current pump states" so the levelbased stopLevel hysteresis
+    // works. In manual mode the operator setting Qd=0 should still mean
+    // "stop now", so we issue an explicit turnOff and short-circuit.
+    if (Number(demand) <= 0) {
+      if (this.machineGroups && Object.keys(this.machineGroups).length > 0) {
+        Object.values(this.machineGroups).forEach((group) => group.turnOffAllMachines());
+      }
+      return;
+    }
    // Forward to machine groups (MGC)
    if (this.machineGroups && Object.keys(this.machineGroups).length > 0) {
      await Promise.all(
@@ -528,43 +685,9 @@ class PumpingStation {
    return null;
  }

-  _levelBasedRampStart() {
-    const { startLevel, enableShiftedRamp } = this.config.control.levelbased;
-    const inflowLevel = this.basin?.inflowLevel;
-    if (enableShiftedRamp && this._shiftArmed) return startLevel;
-    if (Number.isFinite(inflowLevel)) return inflowLevel;
-    return startLevel;
-  }
-
-  _levelBasedRampTop() {
-    // Returns the upper level at which demand saturates at 100 %.
-    // While the shift is armed, top moves left from maxLevel to shiftLevel
-    // so output reaches 100 % earlier and stays at 100 % until level
-    // falls back through shiftLevel on the way down.
-    const { maxLevel, enableShiftedRamp, shiftLevel } = this.config.control.levelbased;
-    if (enableShiftedRamp && this._shiftArmed
-        && Number.isFinite(shiftLevel) && shiftLevel > 0
-        && shiftLevel <= maxLevel) {
-      return shiftLevel;
-    }
-    return maxLevel;
-  }
-
-  _updateShiftArmed(level) {
-    const { enableShiftedRamp, shiftLevel, startLevel } = this.config.control.levelbased;
-    if (!enableShiftedRamp) {
-      this._shiftArmed = false;
-      return;
-    }
-    const trigger = Number.isFinite(shiftLevel) && shiftLevel > 0 ? shiftLevel : null;
-    if (!this._shiftArmed && trigger != null && level >= trigger) {
-      this._shiftArmed = true;
-      this.logger.debug(`Shift armed at level=${level} (shiftLevel=${trigger})`);
-    } else if (this._shiftArmed && Number.isFinite(startLevel) && level < startLevel) {
-      this._shiftArmed = false;
-      this.logger.debug(`Shift disarmed at level=${level} (startLevel=${startLevel})`);
-    }
-  }
+  // (legacy _levelBasedRampStart/_levelBasedRampTop/_updateShiftArmed
+  //  helpers were removed in favour of the inline state machine in
+  //  _controlLevelBased — see that method's doc block.)

  _scaleLevelToFlowPercent(level, rampStartLevel, rampTopLevel) {
    const { maxLevel, curveType = 'linear', logCurveFactor = 9 } = this.config.control.levelbased;
@@ -600,24 +723,100 @@ class PumpingStation {
    const flowUnit = 'm3/s'; // this has to be in m3/s for the actions below
    const now = Date.now();

+    // The synthetic spill flow lives at its OWN position ('overflow') —
+    // not as a child of 'out'. That keeps it out of the operational-outflow
+    // sum here (which only sees pumps + downstream measurements), so no
+    // self-subtraction is needed. _selectBestNetFlow folds it back in for
+    // net-flow balance while pinned at overflow.
    const inflow = this.measurements.sum('flow', 'predicted', this.flowPositions.inflow, flowUnit) || 0;
-    const outflow = this.measurements.sum('flow', 'predicted', this.flowPositions.outflow, flowUnit) || 0;
+    const outflowReal = this.measurements.sum('flow', 'predicted', this.flowPositions.outflow, flowUnit) || 0;

    if (!this._predictedFlowState) {
-      this._predictedFlowState = { inflow, outflow, lastTimestamp: now };
+      this._predictedFlowState = { inflow, outflow: outflowReal, lastTimestamp: now };
    }

    const timestampPrev = this._predictedFlowState.lastTimestamp ?? now;
    const deltaSeconds = Math.max((now - timestampPrev) / 1000, 0);
-    const netVolumeChange = deltaSeconds > 0 ? (inflow - outflow) * deltaSeconds : 0;
+    const netVolumeChange = deltaSeconds > 0 ? (inflow - outflowReal) * deltaSeconds : 0;
+
+    // Read currentVolume via a fresh chain — MeasurementContainer's chain
+    // methods mutate a shared cursor, so any later chain into a different
+    // type/variant invalidates a saved reference. We re-resolve every read
+    // and write below for the same reason.
+    const currentVolume = this.measurements
+      .type('volume').variant('predicted').position('atequipment').getCurrentValue('m3');

-    const volumeSeries = this.measurements.type('volume').variant('predicted').position('atequipment');
-    const currentVolume = volumeSeries.getCurrentValue('m3');  
-  
-    const nextVolume = currentVolume + netVolumeChange;
    const writeTimestamp = timestampPrev + deltaSeconds * 1000;

-    volumeSeries.value(nextVolume, writeTimestamp, 'm3').unit('m3'); //olifant
+    // Predicted-volume bounds.
+    //   Upper (hard physical):  maxVolAtOverflow — past this the basin spills
+    //          over the weir; predicted level pins at overflowLevel and the
+    //          excess is tracked as overflow volume + spill flow.
+    //   Lower (operational):    dryRunSafetyVol — where pumps must stop. Only
+    //          clamps on transition from above; a basin seeded below (e.g.
+    //          startup-from-empty) is left alone so it can fill from 0.
+    //   Lower (hard physical):  0 — basin cannot hold negative water. Always
+    //          clamps. Without this, a seeded-low basin under continued
+    //          net-outflow integrates volume arbitrarily negative (the level
+    //          output looks fine because _calcLevelFromVolume floors at 0,
+    //          masking the underlying drift).
+    const safety = this._computeSafetyPoints();
+    const upperClamp = this.basin.maxVolAtOverflow;
+    const lowerClamp = Math.max(0, safety.dryRunSafetyVol ?? 0);
+
+    const proposedVolume = currentVolume + netVolumeChange;
+    let nextVolume = proposedVolume;
+    let overflowIncrement = 0;
+    let underflowIncrement = 0;
+    if (proposedVolume > upperClamp) {
+      overflowIncrement = proposedVolume - upperClamp;
+      nextVolume = upperClamp;
+    } else if (proposedVolume < lowerClamp && currentVolume >= lowerClamp) {
+      nextVolume = lowerClamp;
+    }
+    if (nextVolume < 0) {
+      underflowIncrement = -nextVolume;
+      nextVolume = 0;
+    }
+
+    // Synthetic spill flow at position 'overflow'.
+    // While pinned at upper bound with continuing net-positive inflow, the
+    // weir is carrying away (inflow − outflowReal). _selectBestNetFlow folds
+    // this into the outflow side so the predicted net-flow balance reads ~0
+    // (matches the level-pinned reality).
+    let spillRate = 0;
+    if (nextVolume >= upperClamp - 1e-9 && (inflow - outflowReal) > this.flowThreshold) {
+      spillRate = inflow - outflowReal;
+    }
+    this.measurements
+      .type('flow').variant('predicted').position('overflow')
+      .value(spillRate, writeTimestamp, 'm3/s').unit('m3/s');
+
+    // Cumulative overflow volume — for compliance reporting via InfluxDB.
+    if (overflowIncrement > 0) {
+      const prevCumulative = this.measurements
+        .type('overflowVolume').variant('predicted').position('atequipment').getCurrentValue('m3') ?? 0;
+      this.measurements
+        .type('overflowVolume').variant('predicted').position('atequipment')
+        .value(prevCumulative + overflowIncrement, writeTimestamp, 'm3').unit('m3');
+    }
+
+    // Cumulative integrator underflow — diagnostic, NOT compliance.
+    // A nonzero value means the predicted-volume integrator tried to go
+    // below the physical floor (negative water). Root causes are usually
+    // upstream: outflow over-reported (sensor drift, pump curve too
+    // optimistic) or an inflow source missing from the measurement set.
+    if (underflowIncrement > 0) {
+      const prevUnderflow = this.measurements
+        .type('underflowVolume').variant('predicted').position('atequipment').getCurrentValue('m3') ?? 0;
+      this.measurements
+        .type('underflowVolume').variant('predicted').position('atequipment')
+        .value(prevUnderflow + underflowIncrement, writeTimestamp, 'm3').unit('m3');
+    }
+
+    this.measurements
+      .type('volume').variant('predicted').position('atequipment')
+      .value(nextVolume, writeTimestamp, 'm3').unit('m3');

    const nextLevel = this._calcLevelFromVolume(nextVolume);
    this.measurements
@@ -641,7 +840,7 @@ class PumpingStation {
      .position('atequipment')
      .value(percent, writeTimestamp, '%');

-    this._predictedFlowState = { inflow, outflow, lastTimestamp: writeTimestamp };
+    this._predictedFlowState = { inflow, outflow: outflowReal, lastTimestamp: writeTimestamp };
  }

  _selectBestNetFlow() {
@@ -653,7 +852,12 @@ class PumpingStation {
      if (!bucket || Object.keys(bucket).length === 0) continue;

      const inflow = this.measurements.sum(type, variant, this.flowPositions.inflow, unit) || 0;
-      const outflow = this.measurements.sum(type, variant, this.flowPositions.outflow, unit) || 0;
+      const outflowReal = this.measurements.sum(type, variant, this.flowPositions.outflow, unit) || 0;
+      // Fold synthetic spill (position 'overflow') into the outflow side.
+      // It only exists for the predicted variant and only while pinned, so
+      // for measured this is 0.
+      const spill = this.measurements.sum(type, variant, ['overflow'], unit) || 0;
+      const outflow = outflowReal + spill;
      if (Math.abs(inflow) < this.flowThreshold && Math.abs(outflow) < this.flowThreshold) continue;

      const net = inflow - outflow;
@@ -661,11 +865,28 @@ class PumpingStation {
      return { value: net, source: variant, direction: this._deriveDirection(net) };
    }

-    // Fallback: level trend
+    // Fallback: level trend.
+    // When level pins at overflow, dL/dt collapses to 0 and the level-rate
+    // method loses the inflow signal — but flow IS still moving (in → spill).
+    // In that case we hold the last known non-zero net-flow so dashboards
+    // keep showing roughly what's coming in until level starts dropping.
    for (const variant of this.levelVariants) {
      const rate = this._levelRate(variant);
      if (!Number.isFinite(rate)) continue;
-      const netFlow = rate * this.basin.surfaceArea;
+
+      const lvl = this.measurements.type('level').variant(variant).position('atequipment').getCurrentValue('m');
+      const pinnedAtOverflow = Number.isFinite(lvl)
+        && Number.isFinite(this.basin.overflowLevel)
+        && lvl >= this.basin.overflowLevel - 1e-9;
+      const rateNearZero = Math.abs(rate) < 1e-9;
+
+      let netFlow = rate * this.basin.surfaceArea;
+      if (pinnedAtOverflow && rateNearZero && Number.isFinite(this._lastLevelRateNetFlow)) {
+        netFlow = this._lastLevelRateNetFlow;
+      } else if (!rateNearZero) {
+        this._lastLevelRateNetFlow = netFlow;
+      }
+
      return { value: netFlow, source: `level:${variant}`, direction: this._deriveDirection(netFlow) };
    }

@@ -976,6 +1197,12 @@ class PumpingStation {
    output.isOverflowing = Boolean(this.safetyState?.isOverflowing);
    output.safetyState = this._deriveSafetyState();
    output.percControl = this.percControl;
+    output.predictedOverflowVolume = this.measurements
+      .type('overflowVolume').variant('predicted').position('atequipment').getCurrentValue('m3') ?? 0;
+    output.predictedOverflowRate = this.measurements
+      .type('flow').variant('predicted').position('overflow').getCurrentValue('m3/s') ?? 0;
+    output.predictedUnderflowVolume = this.measurements
+      .type('underflowVolume').variant('predicted').position('atequipment').getCurrentValue('m3') ?? 0;
    return output;
  }

--- a/test/basic/nodeClass-config.test.js
+++ b/test/basic/nodeClass-config.test.js
@@ -0,0 +1,74 @@
+const test = require('node:test');
+const assert = require('node:assert/strict');
+
+const NodeClass = require('../../src/nodeClass');
+
+function loadConfig(uiConfig = {}) {
+  const ctx = { name: 'pumpingStation' };
+  NodeClass.prototype._loadConfig.call(ctx, {
+    name: 'PS Config Test',
+    basinVolume: 80,
+    basinHeight: 8,
+    inflowLevel: 3.2,
+    outflowLevel: 0.4,
+    overflowLevel: 7.4,
+    inletPipeDiameter: 0.5,
+    outletPipeDiameter: 0.35,
+    refHeight: 'NAP',
+    minHeightBasedOn: 'outlet',
+    basinBottomRef: -1.2,
+    maxInflowRate: 300,
+    staticHead: 11,
+    maxDischargeHead: 22,
+    pipelineLength: 120,
+    defaultFluid: 'wastewater',
+    temperatureReferenceDegC: 16,
+    controlMode: 'levelbased',
+    minLevel: 0.8,
+    startLevel: 2,
+    maxLevel: 6.5,
+    levelCurveType: 'log',
+    logCurveFactor: 7,
+    enableDryRunProtection: true,
+    dryRunThresholdPercent: 3,
+    enableHighVolumeSafety: true,
+    highVolumeSafetyThresholdPercent: 96,
+    timeleftToFullOrEmptyThresholdSeconds: 60,
+    processOutputFormat: 'process',
+    dbaseOutputFormat: 'influxdb',
+    ...uiConfig,
+  }, { id: 'node-1' });
+  return ctx.config;
+}
+
+test('nodeClass config mapping — basin, hydraulics, mode and safety fields', () => {
+  const cfg = loadConfig();
+
+  assert.equal(cfg.basin.inletPipeDiameter, 0.5);
+  assert.equal(cfg.basin.outletPipeDiameter, 0.35);
+  assert.equal(cfg.hydraulics.maxInflowRate, 300);
+  assert.equal(cfg.hydraulics.staticHead, 11);
+  assert.equal(cfg.hydraulics.maxDischargeHead, 22);
+  assert.equal(cfg.hydraulics.pipelineLength, 120);
+  assert.equal(cfg.hydraulics.defaultFluid, 'wastewater');
+  assert.equal(cfg.hydraulics.temperatureReferenceDegC, 16);
+  assert.equal(cfg.control.mode, 'levelbased');
+  assert.equal(cfg.control.levelbased.curveType, 'log');
+  assert.equal(cfg.control.levelbased.logCurveFactor, 7);
+  assert.equal(cfg.safety.enableHighVolumeSafety, true);
+  assert.equal(cfg.safety.highVolumeSafetyThresholdPercent, 96);
+  assert.equal(cfg.output.process, 'process');
+  assert.equal(cfg.output.dbase, 'influxdb');
+});
+
+test('nodeClass config mapping — accepts deprecated overfill UI fields', () => {
+  const cfg = loadConfig({
+    enableHighVolumeSafety: undefined,
+    highVolumeSafetyThresholdPercent: undefined,
+    enableOverfillProtection: false,
+    overfillThresholdPercent: 91,
+  });
+
+  assert.equal(cfg.safety.enableHighVolumeSafety, false);
+  assert.equal(cfg.safety.highVolumeSafetyThresholdPercent, 91);
+});
--- a/test/basic/specificClass.test.js
+++ b/test/basic/specificClass.test.js
@@ -303,14 +303,17 @@ test('Levelbased control zones — _controlLevelBased', async (t) => {
    assert.equal(ps.percControl, 0);
  });

-  await t.test('shift enabled: arming when level crosses shiftLevel; foot moves to startLevel', async () => {
+  await t.test('shift enabled: arming on % threshold + hold-then-ramp on draining', async () => {
+    // Geometry: inflow=3, max=4 → up curve goes 0%@3 to 100%@4.
+    //   shiftArmPercent=80 ⇒ arms when up curve ≥ 80 % i.e. level ≥ 3.8.
+    //   shiftLevel=3.5 ⇒ held output starts ramping down at this level.
    const ps = new PumpingStation(makeConfig({
      control: {
        mode: 'levelbased',
        allowedModes: new Set(['levelbased']),
        levelbased: {
          minLevel: 1, startLevel: 2, maxLevel: 4, curveType: 'linear', logCurveFactor: 9,
-          enableShiftedRamp: true, shiftLevel: 3.5,
+          enableShiftedRamp: true, shiftLevel: 3.5, shiftArmPercent: 80,
        },
      },
    }));
@@ -319,25 +322,65 @@ test('Levelbased control zones — _controlLevelBased', async (t) => {
      turnOffAllMachines: () => {},
      handleInput: async () => {},
    };
-    // Below shiftLevel: not yet armed → foot=inflowLevel, level 2.5 is in hold zone → 0%.
-    ps.calibratePredictedLevel(2.5);
-    await ps._controlLevelBased();
+    // Filling at level=3.5 ⇒ up curve = 50 %, below arm threshold ⇒ not armed.
+    ps.calibratePredictedLevel(3.5);
+    await ps._controlLevelBased('filling');
+    assert.equal(ps._shiftArmed, false);
+    assert.ok(Math.abs(ps.percControl - 50) < 1e-9);
+    // Filling at level=3.85 ⇒ up curve = 85 % ≥ arm threshold ⇒ ARM.
+    ps.calibratePredictedLevel(3.85);
+    await ps._controlLevelBased('filling');
+    assert.equal(ps._shiftArmed, true);
+    assert.ok(Math.abs(ps.percControl - 85) < 1e-9);  // still up curve while filling
+    // Direction flips to draining at the same level ⇒ capture hold ≈ 85 %.
+    await ps._controlLevelBased('draining');
+    assert.ok(Math.abs(ps._shiftHoldValue - 85) < 1e-6);
+    // While draining and level ≥ shiftLevel ⇒ output stays at hold (≈85 %).
+    ps.calibratePredictedLevel(3.6);
+    await ps._controlLevelBased('draining');
+    assert.ok(Math.abs(ps.percControl - 85) < 1e-6);
+    // Below shiftLevel: ramp [shift, hold] → [start, 0]. At level=2.75
+    // (midpoint of [2, 3.5]), x=0.5, output ≈ 85 × 0.5 = 42.5 %.
+    ps.calibratePredictedLevel(2.75);
+    await ps._controlLevelBased('draining');
+    assert.ok(Math.abs(ps.percControl - 42.5) < 1e-6);
+    // Below startLevel ⇒ output 0 % AND disarm.
+    ps.calibratePredictedLevel(1.9);
+    await ps._controlLevelBased('draining');
    assert.equal(ps.percControl, 0);
    assert.equal(ps._shiftArmed, false);
-    // Cross the shift trigger going up — at level >= shiftLevel, output saturates at 100%.
-    ps.calibratePredictedLevel(3.6);
-    await ps._controlLevelBased();
+    assert.equal(ps._shiftHoldValue, null);
+  });
+
+  await t.test('shift enabled: returning to filling clears hold; new hold captured on next drain', async () => {
+    const ps = new PumpingStation(makeConfig({
+      control: {
+        mode: 'levelbased',
+        allowedModes: new Set(['levelbased']),
+        levelbased: {
+          minLevel: 1, startLevel: 2, maxLevel: 4, curveType: 'linear', logCurveFactor: 9,
+          enableShiftedRamp: true, shiftLevel: 3.5, shiftArmPercent: 80,
+        },
+      },
+    }));
+    ps.machineGroups['mgc1'] = {
+      config: { general: { name: 'mgc1' } },
+      turnOffAllMachines: () => {},
+      handleInput: async () => {},
+    };
+    ps.calibratePredictedLevel(3.85);
+    await ps._controlLevelBased('filling');
+    await ps._controlLevelBased('draining');
+    assert.ok(Math.abs(ps._shiftHoldValue - 85) < 1e-6);
+    // Direction back to filling ⇒ up curve, hold cleared, still armed.
+    ps.calibratePredictedLevel(3.9);
+    await ps._controlLevelBased('filling');
+    assert.equal(ps._shiftHoldValue, null);
    assert.equal(ps._shiftArmed, true);
-    assert.ok(ps.percControl >= 100 - 1e-9);
-    // Drop to midpoint of shifted ramp [start=2 .. shiftLevel=3.5] → x=0.5 → 50%.
-    ps.calibratePredictedLevel(2.75);
-    await ps._controlLevelBased();
-    assert.equal(ps._shiftArmed, true);
-    assert.ok(Math.abs(ps.percControl - 50) < 1e-9);
-    // Drop below startLevel → disarm.
-    ps.calibratePredictedLevel(1.9);
-    await ps._controlLevelBased();
-    assert.equal(ps._shiftArmed, false);
+    assert.ok(Math.abs(ps.percControl - 90) < 1e-6);  // up curve at 3.9 = 90 %
+    // Flip to draining again at higher level ⇒ new hold ≈ 90 %.
+    await ps._controlLevelBased('draining');
+    assert.ok(Math.abs(ps._shiftHoldValue - 90) < 1e-6);
  });

  await t.test('log curve has fast early response', async () => {
@@ -404,3 +447,155 @@ test('Manual inflow — setManualInflow stores predicted inflow', async (t) => {
  const v = ps.measurements.type('flow').variant('predicted').position('in').child('manual-qin').getCurrentValue('m3/s');
  assert.ok(Math.abs(v - 0.05) < 1e-9);
 });
+
+// _updatePredictedVolume now clamps [dryRunSafetyVol, maxVolAtOverflow] and
+// tracks any excess as cumulative `overflowVolume` plus a synthetic
+// `flow.predicted.out.overflow` rate so net-flow balance stays at ~0 while
+// pinned. We drive ticks manually with monotonic timestamps to keep tests
+// deterministic (Date.now() in the integrator can step by 0 ms in fast loops).
+test('Predicted volume — overflow clamp and spill tracking', async (t) => {
+  const ps = new PumpingStation(makeConfig({
+    safety: { enableDryRunProtection: false, enableHighVolumeSafety: false, dryRunThresholdPercent: 0 },
+  }));
+  // Seed predicted volume just below the spill point.
+  // maxVolAtOverflow = overflowLevel × area = 4.5 × 10 = 45 m³.
+  const t0 = 1_700_000_000_000;
+  ps.calibratePredictedVolume(44, t0);
+  // Heavy inflow, no real outflow (no pumps wired).
+  ps.setManualInflow(2, t0, 'm3/s');  // 2 m³/s, dt=1s → 2 m³/tick
+
+  await t.test('first overflow tick clamps volume and records spill increment', () => {
+    ps._predictedFlowState = { inflow: 2, outflow: 0, lastTimestamp: t0 };
+    Date.now = () => t0 + 1000;
+    ps._updatePredictedVolume();
+    const vol = ps.measurements.type('volume').variant('predicted').position('atequipment').getCurrentValue('m3');
+    assert.equal(vol, 45);  // pinned at overflow
+    const cumulative = ps.measurements.type('overflowVolume').variant('predicted').position('atequipment').getCurrentValue('m3');
+    assert.equal(cumulative, 1);  // proposed=44+2=46, excess=1 m³ this tick
+    const spill = ps.measurements.type('flow').variant('predicted').position('overflow').getCurrentValue('m3/s');
+    assert.equal(spill, 2);  // instantaneous balance: inflow − outflowReal
+  });
+
+  await t.test('subsequent ticks accumulate full inflow as spill (stable)', () => {
+    Date.now = () => t0 + 2000;
+    ps._updatePredictedVolume();
+    const vol = ps.measurements.type('volume').variant('predicted').position('atequipment').getCurrentValue('m3');
+    assert.equal(vol, 45);
+    const cumulative = ps.measurements.type('overflowVolume').variant('predicted').position('atequipment').getCurrentValue('m3');
+    assert.equal(cumulative, 3);  // 1 + 2
+    const spill = ps.measurements.type('flow').variant('predicted').position('overflow').getCurrentValue('m3/s');
+    assert.equal(spill, 2);
+  });
+
+  await t.test('predicted net flow reads ~0 while pinned at overflow', () => {
+    const net = ps._selectBestNetFlow();
+    // inflow=2, outflow_total=2 (synthetic spill), net = 0
+    assert.ok(Math.abs(net.value) < 1e-9);
+    assert.equal(net.source, 'predicted');
+  });
+
+  await t.test('once inflow stops, spill flow clears and clamp releases', () => {
+    ps.setManualInflow(0, t0 + 2000, 'm3/s');
+    ps._predictedFlowState = { inflow: 0, outflow: 0, lastTimestamp: t0 + 2000 };
+    Date.now = () => t0 + 3000;
+    ps._updatePredictedVolume();
+    const spill = ps.measurements.type('flow').variant('predicted').position('overflow').getCurrentValue('m3/s');
+    assert.equal(spill, 0);
+    // Volume stays at 45 (no draining force) but is no longer "pinned".
+    const vol = ps.measurements.type('volume').variant('predicted').position('atequipment').getCurrentValue('m3');
+    assert.equal(vol, 45);
+  });
+});
+
+test('Predicted volume — dry-run lower clamp', async (t) => {
+  const ps = new PumpingStation(makeConfig({
+    // dryRunSafetyVol = minVolAtOutflow × (1 + 5/100) = 2 × 1.05 = 2.1 m³
+    safety: { enableDryRunProtection: true, dryRunThresholdPercent: 5 },
+  }));
+  const t0 = 1_700_000_000_000;
+
+  await t.test('initial seed below dryRunSafetyVol is left alone (no upward bump)', () => {
+    // Seed defaults to minVol=2 (below dryRunSafetyVol=2.1).
+    ps._predictedFlowState = { inflow: 0, outflow: 0, lastTimestamp: t0 };
+    Date.now = () => t0 + 1000;
+    ps._updatePredictedVolume();
+    const vol = ps.measurements.type('volume').variant('predicted').position('atequipment').getCurrentValue('m3');
+    assert.equal(vol, 2);  // unchanged — clamp doesn't fire because we started below it
+  });
+
+  await t.test('drain across dryRunSafetyVol clamps at the threshold', () => {
+    // Calibrate well above, then push outflow that would cross the threshold.
+    ps.calibratePredictedVolume(3, t0 + 1000);
+    // outflow=2 m³/s for 1s → would drop to 1; clamp catches at 2.1.
+    ps.setManualOutflow(2, t0 + 1000, 'm3/s');
+    ps._predictedFlowState = { inflow: 0, outflow: 2, lastTimestamp: t0 + 1000 };
+    Date.now = () => t0 + 2000;
+    ps._updatePredictedVolume();
+    const vol = ps.measurements.type('volume').variant('predicted').position('atequipment').getCurrentValue('m3');
+    assert.ok(Math.abs(vol - 2.1) < 1e-9);
+  });
+});
+
+test('getOutput — exposes predictedOverflowVolume / predictedOverflowRate', () => {
+  const ps = new PumpingStation(makeConfig());
+  // Seed an overflow scenario.
+  const t0 = 1_700_000_000_000;
+  ps.calibratePredictedVolume(44, t0);
+  ps.setManualInflow(2, t0, 'm3/s');
+  ps._predictedFlowState = { inflow: 2, outflow: 0, lastTimestamp: t0 };
+  Date.now = () => t0 + 1000;
+  ps._updatePredictedVolume();
+  const out = ps.getOutput();
+  assert.equal(out.predictedOverflowVolume, 1);
+  assert.equal(out.predictedOverflowRate, 2);
+});
+
+// Hard physical floor at 0. The dryRunSafetyVol clamp only fires on transition
+// from above, so a basin seeded below + continued outflow used to integrate
+// the volume arbitrarily negative. The level helper masked this by flooring
+// at 0 in _calcLevelFromVolume — fix is to floor the integrator itself.
+test('Predicted volume — physical floor at 0 (underflow track)', async (t) => {
+  const ps = new PumpingStation(makeConfig({
+    safety: { enableDryRunProtection: true, dryRunThresholdPercent: 5 },
+  }));
+  const t0 = 1_700_000_000_000;
+
+  await t.test('seeded below dryRun + continued outflow does NOT go negative', () => {
+    ps.calibratePredictedVolume(0.5, t0);  // below dryRunSafetyVol (2.1)
+    ps.setManualOutflow(2, t0, 'm3/s');     // 2 m³/s for 1s → would drop to -1.5
+    ps._predictedFlowState = { inflow: 0, outflow: 2, lastTimestamp: t0 };
+    Date.now = () => t0 + 1000;
+    ps._updatePredictedVolume();
+    const vol = ps.measurements.type('volume').variant('predicted').position('atequipment').getCurrentValue('m3');
+    assert.equal(vol, 0);  // floored at 0, not -1.5
+    const underflow = ps.measurements
+      .type('underflowVolume').variant('predicted').position('atequipment').getCurrentValue('m3');
+    assert.equal(underflow, 1.5);  // tracked as diagnostic
+  });
+
+  await t.test('subsequent ticks accumulate underflow while outflow continues', () => {
+    Date.now = () => t0 + 2000;
+    ps._predictedFlowState = { inflow: 0, outflow: 2, lastTimestamp: t0 + 1000 };
+    ps._updatePredictedVolume();
+    const vol = ps.measurements.type('volume').variant('predicted').position('atequipment').getCurrentValue('m3');
+    assert.equal(vol, 0);
+    const underflow = ps.measurements
+      .type('underflowVolume').variant('predicted').position('atequipment').getCurrentValue('m3');
+    assert.equal(underflow, 3.5);  // 1.5 + 2.0
+  });
+
+  await t.test('getOutput exposes predictedUnderflowVolume', () => {
+    const out = ps.getOutput();
+    assert.equal(out.predictedUnderflowVolume, 3.5);
+  });
+
+  await t.test('inflow returns and basin refills from 0 (no jump to dryRunSafetyVol)', () => {
+    ps.setManualInflow(1, t0 + 2000, 'm3/s');
+    ps.setManualOutflow(0, t0 + 2000, 'm3/s');
+    ps._predictedFlowState = { inflow: 1, outflow: 0, lastTimestamp: t0 + 2000 };
+    Date.now = () => t0 + 3000;
+    ps._updatePredictedVolume();
+    const vol = ps.measurements.type('volume').variant('predicted').position('atequipment').getCurrentValue('m3');
+    assert.ok(Math.abs(vol - 1) < 1e-9);  // 0 + 1 = 1, NOT pinned to 2.1
+  });
+});
--- a/test/integration/basic-dashboard-flow.test.js
+++ b/test/integration/basic-dashboard-flow.test.js
@@ -0,0 +1,94 @@
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+
+function loadDashboardFlow() {
+  const flowPath = path.join(__dirname, '../../examples/basic-dashboard.flow.json');
+  return JSON.parse(fs.readFileSync(flowPath, 'utf8'));
+}
+
+function makeContextStub() {
+  const store = {};
+  return {
+    get(key) {
+      return store[key];
+    },
+    set(key, value) {
+      store[key] = value;
+    },
+  };
+}
+
+test('basic dashboard flow contains the pumpingStation node and trend widgets', () => {
+  const flow = loadDashboardFlow();
+  const ps = flow.find((n) => n.id === 'ps_node_basic');
+  const parser = flow.find((n) => n.id === 'ps_parse_output');
+  const levelChart = flow.find((n) => n.id === 'ps_chart_level');
+  const demandChart = flow.find((n) => n.id === 'ps_chart_demand');
+
+  assert.ok(ps, 'ps_node_basic should exist');
+  assert.equal(ps.type, 'pumpingStation');
+  assert.equal(ps.controlMode, 'levelbased');
+  assert.equal(ps.levelCurveType, 'linear');
+  assert.equal(ps.inletPipeDiameter, 0.4);
+  assert.equal(ps.outletPipeDiameter, 0.3);
+  assert.ok(parser, 'ps_parse_output should exist');
+  assert.equal(parser.outputs, 6);
+  assert.equal(levelChart.type, 'ui-chart');
+  assert.equal(demandChart.type, 'ui-chart');
+});
+
+test('basic dashboard parser routes process fields to charts and state text', () => {
+  const flow = loadDashboardFlow();
+  const parser = flow.find((n) => n.id === 'ps_parse_output');
+  assert.ok(parser, 'ps_parse_output should exist');
+
+  const func = new Function('msg', 'context', 'node', parser.func);
+  const context = makeContextStub();
+  const node = { send() {} };
+
+  // Flatten format is `${type}.${variant}.${position}.${childId}`. When the
+  // runtime writes without an explicit .child(), childId='default'. Mirror
+  // the real shape here. (See generalFunctions/src/measurements/
+  // MeasurementContainer.js getFlattenedOutput.)
+  const out = func({
+    payload: {
+      'level.predicted.atequipment.default': 3.25,
+      'volume.predicted.atequipment.default': 32.5,
+      'netFlowRate.predicted.atequipment.default': 0.003,
+      percControl: 25,
+      direction: 'filling',
+      safetyState: 'normal',
+      isOverflowing: false,
+      timeleft: 400,
+    },
+  }, context, node);
+
+  assert.ok(Array.isArray(out));
+  assert.equal(out.length, 6);
+  assert.equal(out[0].topic, 'level');
+  assert.equal(out[0].payload, 3.25);
+  assert.equal(out[1].topic, 'volume');
+  assert.equal(out[1].payload, 32.5);
+  assert.equal(out[2].topic, 'demand');
+  assert.equal(out[2].payload, 25);
+  assert.equal(out[3].topic, 'net_flow');
+  assert.equal(out[3].payload, 0.003);
+  assert.match(out[4].payload, /normal/);
+  assert.match(out[5].payload, /level=3.25 m/);
+});
+
+test('basic dashboard parser keeps previous values when process output sends only changed fields', () => {
+  const flow = loadDashboardFlow();
+  const parser = flow.find((n) => n.id === 'ps_parse_output');
+  const func = new Function('msg', 'context', 'node', parser.func);
+  const context = makeContextStub();
+  const node = { send() {} };
+
+  func({ payload: { 'level.predicted.atequipment.default': 3.1, percControl: 10 } }, context, node);
+  const out = func({ payload: { percControl: 20 } }, context, node);
+
+  assert.equal(out[0].payload, 3.1);
+  assert.equal(out[2].payload, 20);
+});
--- a/test/integration/shifted-ramp-end-to-end.test.js
+++ b/test/integration/shifted-ramp-end-to-end.test.js
@@ -0,0 +1,198 @@
+// End-to-end test for the level-armed hysteresis (shifted ramp) cycle.
+// Drives a full fill→arm→drain cycle through the same code path the
+// dashboard exercises (manual Q_IN / Q_OUT + tick), and asserts the
+// hold-then-ramp output behaviour.
+//
+// Run with:  node --test test/integration/shifted-ramp-end-to-end.test.js
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+
+const PumpingStation = require('../../src/specificClass');
+
+const SURFACE_AREA = 10;        // basin volume / height = 50/5
+const TICK_MS = 1000;           // simulate 1 s per tick
+
+function makeConfig() {
+  return {
+    general: {
+      name: 'TestPS',
+      id: 'ps-e2e',
+      unit: 'm3/h',
+      logging: { enabled: false, logLevel: 'error' },
+      flowThreshold: 1e-4,
+    },
+    functionality: {
+      softwareType: 'pumpingStation',
+      role: 'stationcontroller',
+      positionVsParent: 'atEquipment',
+    },
+    basin: {
+      volume: 50, height: 5,
+      inflowLevel: 3, outflowLevel: 0.2, overflowLevel: 4.5,
+      inletPipeDiameter: 0.4, outletPipeDiameter: 0.3,
+    },
+    hydraulics: { refHeight: 'NAP', basinBottomRef: 0, minHeightBasedOn: 'outlet' },
+    control: {
+      mode: 'levelbased',
+      allowedModes: new Set(['levelbased', 'manual']),
+      levelbased: {
+        minLevel: 1, startLevel: 2, maxLevel: 4,
+        curveType: 'linear', logCurveFactor: 9,
+        enableShiftedRamp: true, shiftLevel: 3.5, shiftArmPercent: 80,
+      },
+    },
+    safety: {
+      enableDryRunProtection: false, enableOverfillProtection: false,
+      dryRunThresholdPercent: 2, highVolumeSafetyThresholdPercent: 98,
+      overfillThresholdPercent: 98, timeleftToFullOrEmptyThresholdSeconds: 0,
+    },
+  };
+}
+
+// Build a PS with a fake MGC that captures every demand sent to it,
+// and a clock we control so _updatePredictedVolume integrates over a
+// known dt regardless of wall-clock.
+function buildHarness() {
+  const ps = new PumpingStation(makeConfig());
+  const demands = [];
+  ps.machineGroups['mgc1'] = {
+    config: { general: { name: 'mgc1' } },
+    turnOffAllMachines: () => {},
+    handleInput: async (_src, d) => { demands.push(d); },
+  };
+  // Seed level at startLevel so the run begins idle.
+  ps.calibratePredictedLevel(2.0);
+  // Override Date.now via a controllable clock that advances `step()`.
+  let now = ps._predictedFlowState.lastTimestamp || 0;
+  ps._fakeNow = () => now;
+  ps._fakeAdvance = (ms) => { now += ms; };
+  // Patch global Date.now JUST inside the scope of these tests.
+  const realNow = Date.now;
+  Date.now = ps._fakeNow;
+  // Restore on completion.
+  ps._restore = () => { Date.now = realNow; };
+  return { ps, demands };
+}
+
+async function step(ps, qIn, qOut) {
+  // Apply the manual Q_IN / Q_OUT (mirroring the dashboard's q_in / q_out
+  // topic handlers in nodeClass.js), advance time, then tick once.
+  if (Number.isFinite(qIn))  ps.setManualInflow(qIn,  Date.now(), 'm3/s');
+  if (Number.isFinite(qOut)) ps.setManualOutflow(qOut, Date.now(), 'm3/s');
+  ps._fakeAdvance(TICK_MS);
+  ps.tick();
+}
+
+function levelOf(ps) {
+  return ps.measurements.type('level').variant('predicted').position('atequipment').getCurrentValue('m');
+}
+
+test('shifted ramp e2e: arm → hold → ramp-down → disarm', async () => {
+  const { ps } = buildHarness();
+  try {
+    // ─── PHASE A: fill from start (2.0) up past the arm point ──────────
+    // Q_IN = 0.05 m3/s, Q_OUT = 0 → net = 0.05 m3/s. Level rises by
+    // 0.05/SURFACE_AREA = 0.005 m per second.
+    let armedAt = null;
+    for (let i = 0; i < 600 && levelOf(ps) < 3.95; i++) {
+      await step(ps, 0.05, 0);
+      if (!armedAt && ps._shiftArmed) armedAt = { level: levelOf(ps), pct: ps.percControl };
+    }
+    assert.ok(armedAt, 'shift should arm during fill');
+    // Should arm right around level=3.8 (up curve = 80 %). Allow ±0.05 m
+    // jitter for time-discretization.
+    assert.ok(Math.abs(armedAt.level - 3.8) < 0.05,
+      `expected arm near level=3.8, got ${armedAt.level}`);
+    assert.ok(armedAt.pct >= 80 - 1e-6,
+      `at arm point output should be ≥ shiftArmPercent, got ${armedAt.pct}`);
+
+    // While still filling and armed, output should track the up curve
+    // (not jump to 100 %). At level ~ 3.95, up curve = 95 %.
+    const fillingPct = ps.percControl;
+    assert.ok(fillingPct < 100 + 1e-6 && fillingPct >= 80 - 1e-6,
+      `filling-armed output should still be on up curve, got ${fillingPct}`);
+    // No hold captured yet (still filling).
+    assert.equal(ps._shiftHoldValue, null);
+
+    // ─── PHASE B: flip to draining ─────────────────────────────────────
+    // First drain tick captures the hold. We need direction='draining' as
+    // determined by _selectBestNetFlow → so q_in - q_out must be negative
+    // by more than the dead-band (1e-4).
+    await step(ps, 0, 0.05);                     // net = -0.05
+    assert.equal(ps.state.direction, 'draining');
+    // Hold captured = up curve at the level when direction flipped. The
+    // captured value is recorded BEFORE this drain tick lowered the level
+    // further, so it should match the last filling tick's output (within
+    // the per-tick step size 0.5 % ~ 0.005 m × 100 / 1 m).
+    assert.ok(ps._shiftHoldValue >= 80 - 1e-6,
+      `hold should be at least the arm threshold, got ${ps._shiftHoldValue}`);
+    const hold = ps._shiftHoldValue;
+
+    // ─── PHASE C: drain while level still ≥ shiftLevel — output HELD ───
+    // Drain until level just above shiftLevel=3.5. Output stays = hold.
+    let held = true;
+    for (let i = 0; i < 200 && levelOf(ps) > 3.51; i++) {
+      await step(ps, 0, 0.05);
+      if (Math.abs(ps.percControl - hold) > 1e-6) { held = false; break; }
+    }
+    assert.ok(held, 'output should HOLD at the captured value while level > shiftLevel');
+    assert.ok(Math.abs(ps.percControl - hold) < 1e-6,
+      `still expected hold=${hold}, got ${ps.percControl}`);
+
+    // ─── PHASE D: drain past shiftLevel — output ramps hold→0 ──────────
+    // Drain until clearly below shiftLevel (level ≤ 3.45). Output should drop.
+    while (levelOf(ps) > 3.45) await step(ps, 0, 0.05);
+    const justBelow = ps.percControl;
+    assert.ok(justBelow < hold,
+      `output should start dropping below shiftLevel, got ${justBelow} vs hold ${hold}`);
+    // Ramp midpoint: level=2.75 (midway in [2, 3.5]). Output ≈ hold × 0.5.
+    while (levelOf(ps) > 2.78 && levelOf(ps) > 2.0) await step(ps, 0, 0.05);
+    const mid = ps.percControl;
+    assert.ok(Math.abs(mid - hold * 0.5) < hold * 0.05,
+      `at level≈2.75 expected ≈ hold/2 (${hold * 0.5}), got ${mid}`);
+
+    // ─── PHASE E: level drops to startLevel — DISARM, output 0 ─────────
+    while (levelOf(ps) > 1.95) await step(ps, 0, 0.05);
+    assert.equal(ps._shiftArmed, false, 'should disarm when level reaches startLevel');
+    assert.equal(ps._shiftHoldValue, null);
+    assert.equal(ps.percControl, 0);
+  } finally {
+    ps._restore();
+  }
+});
+
+test('shifted ramp e2e: bounce — fill, drain a bit, refill, drain — captures fresh hold', async () => {
+  const { ps } = buildHarness();
+  try {
+    // Fill to arm + some headroom.
+    while (levelOf(ps) < 3.85) await step(ps, 0.05, 0);
+    assert.equal(ps._shiftArmed, true);
+
+    // First drain transition → hold #1.
+    await step(ps, 0, 0.05);
+    const hold1 = ps._shiftHoldValue;
+    assert.ok(hold1 >= 80 - 1e-6);
+
+    // Drain a tiny bit (level still > shiftLevel) → output stays at hold1.
+    for (let i = 0; i < 5; i++) await step(ps, 0, 0.05);
+    assert.ok(Math.abs(ps.percControl - hold1) < 1e-6);
+
+    // Flip back to filling at higher rate; up curve resumes; hold cleared.
+    await step(ps, 0.05, 0);
+    assert.equal(ps._shiftHoldValue, null);
+    assert.equal(ps._shiftArmed, true, 'should stay armed across the bounce');
+
+    // Fill higher than before (output goes higher).
+    while (levelOf(ps) < 3.95) await step(ps, 0.05, 0);
+    const fillingPct = ps.percControl;
+    assert.ok(fillingPct > hold1, `bounce should rise above first hold; got ${fillingPct} vs ${hold1}`);
+
+    // Drain again → fresh hold #2 = current up curve %.
+    await step(ps, 0, 0.05);
+    const hold2 = ps._shiftHoldValue;
+    assert.ok(hold2 > hold1, `second hold (${hold2}) should be > first (${hold1})`);
+  } finally {
+    ps._restore();
+  }
+});
--- a/wiki/diagrams/README.md
+++ b/wiki/diagrams/README.md
@@ -51,9 +51,10 @@ Use a descriptive `alt` text; it's the fallback if the SVG fails and it shows up
 | Diagram | Shows |
 |---|---|
 | `basin-model` | Shared physical basin cross-section — walls, pipe reference heights, derived safety zones, storage/dead volumes |
-| `modes/basin-mode-level-linear` | Level-linear control mode — `startLevel`, demand ramp, threshold-shift behaviour |
+| `modes/level-based/basin-mode-level-linear` | Level-based linear control curve — rising ramp starts at inlet level, falling ramp shifts to `startLevel` |
+| `modes/level-based/basin-mode-level-log` | Level-based logarithmic control curve — fast early response, falling ramp shifts to `startLevel` |
 | `control-zones` | Legacy vertical level axis ("thermometer") for `levelbased` mode — STOP / DEAD ZONE / RUN with demand ramp |
-| `safety-rules` | Dry-run vs overfill rule asymmetry — which children stop, which keep running |
+| `safety-rules` | Dry-run vs high-volume safety rule asymmetry — which children stop, which keep running |

 ## Making a brand-new diagram

--- a/wiki/diagrams/modes/basin-mode-level-linear.drawio.svg
+++ b/wiki/diagrams/modes/basin-mode-level-linear.drawio.svg
--- a/wiki/diagrams/modes/level-based/basin-mode-level-linear.drawio.svg
+++ b/wiki/diagrams/modes/level-based/basin-mode-level-linear.drawio.svg
--- a/wiki/diagrams/modes/level-based/basin-mode-level-log.drawio.svg
+++ b/wiki/diagrams/modes/level-based/basin-mode-level-log.drawio.svg
--- a/wiki/functional-description.md
+++ b/wiki/functional-description.md
@@ -79,7 +79,7 @@ The current runtime still uses the level fields directly for its volume math. Pi
 | **Time To Empty/Full (s)** | `0` | If > 0, triggers safety when predicted time-to-overflow or time-to-empty falls below this value. `0` disables time-based protection. |
 | **Enable Dry-Run Protection** | `true` | If on, pumps are shut down once volume drops below the dry-run threshold while draining. |
 | **Low Volume Threshold (%)** | `2` | Safety margin above the configured minimum volume: `dryRunSafetyVol = minVol × (1 + pct/100)`. This creates `dryRunLevel`; it is derived, not a separately entered basin height. |
-| **Enable Overfill Protection** | `true` | If on, upstream inflows are shut down once volume climbs above the high-volume safety point while filling. |
+| **Enable High-volume Safety** | `true` | If on, upstream inflows are shut down once volume climbs above the high-volume safety point while filling. |
 | **High Volume Threshold (%)** | `98` | Safety margin below physical overflow: `highVolumeSafetyVol = maxVolAtOverflow × pct/100`. Actual overflowing is still the boolean condition `level >= overflowLevel`. |

 ### Output formats
@@ -152,12 +152,18 @@ Delta-compressed payload (only changed fields per tick). Keys follow the standar
 | `volumePercent.predicted.atequipment.default` | `(vol - minVol) / (maxVolAtOverflow - minVol) × 100` (%). |
 | `flow.predicted.in.<childId>` | Inflow contribution from a registered child (m³/s internally; editor unit on output). |
 | `flow.predicted.out.<childId>` | Outflow contribution from a registered child. |
+| `flow.predicted.overflow.default` | Synthetic spill rate over the weir while predicted volume is pinned at `maxVolAtOverflow` (m³/s). Zero when not spilling. Lives at its own position (not under `out`) so the operational outflow sum stays clean; `_selectBestNetFlow` folds it into the outflow side for net-flow balance, where it reads ~0 while pinned. |
 | `flow.measured.<position>.<childId>` | Flow sensor reading. |
 | `netFlowRate.<variant>.atequipment.default` | Net flow used for control (inflow − outflow). |
+| `overflowVolume.predicted.atequipment.default` | Cumulative predicted spill volume (m³) — for compliance reporting via InfluxDB. Monotonically non-decreasing. |
+| `underflowVolume.predicted.atequipment.default` | Cumulative volume the integrator tried to drive below 0 m³ (m³). Diagnostic only, NOT compliance — a non-zero value indicates a flow-balance error (over-reported outflow / missing inflow source / pump curve too optimistic). |
 | `direction` | `filling` / `draining` / `steady` / `unknown`. |
 | `flowSource` | Which variant drove the current control cycle (`measured`, `predicted`, `level:predicted`, `null`). |
 | `timeleft` | Predicted seconds to overflow (while filling) or to dry-run (while draining). |
 | `volEmptyBasin`, `inflowLevel`, `overflowLevel`, `maxVol`, `maxVolAtOverflow`, `minVol`, `minVolAtInflow`, `minVolAtOutflow`, `minHeightBasedOn` | Echoes of the basin geometry for dashboards. |
+| `predictedOverflowVolume` | Convenience top-level mirror of `overflowVolume.predicted.atequipment.default` (m³). |
+| `predictedOverflowRate` | Convenience top-level mirror of `flow.predicted.overflow.default` (m³/s). |
+| `predictedUnderflowVolume` | Convenience top-level mirror of `underflowVolume.predicted.atequipment.default` (m³). |
 | `percControl` | Last demand (0–100+ %) forwarded to the machine group during level-based control. |

 Consumers must cache and merge deltas — the example dashboard flows include a reusable function node that does exactly this.
@@ -178,9 +184,9 @@ The basin is modelled as a rectangular prism with constant cross-section. Everyt

 *Editable source: [`diagrams/basin-model.drawio.svg`](diagrams/basin-model.drawio.svg) (drag into draw.io; the SVG embeds the editable source). See [`diagrams/README.md`](diagrams/README.md) for the edit-and-export workflow.*

-**Generic basin ordering** (bottom → top): `outflowLevel ≤ dryRunLevel ≤ minLevel < inflowLevel < maxLevel ≤ highVolumeSafetyLevel < overflowLevel ≤ basinHeight`.
+**Generic basin ordering** (bottom → top): `outflowLevel ≤ dryRunLevel < inflowLevel ≤ highVolumeSafetyLevel < overflowLevel ≤ basinHeight`.

-`startLevel` is deliberately not part of this generic basin diagram. It belongs to a control mode. For the current level-linear mode, see [`diagrams/modes/basin-mode-level-linear.drawio.svg`](diagrams/modes/basin-mode-level-linear.drawio.svg).
+`minLevel`, `startLevel`, and `maxLevel` are deliberately not part of this generic basin diagram. They belong to a control mode. For the current level-based mode variants, see [`diagrams/modes/level-based/`](diagrams/modes/level-based/).

 The pipe labels are intentional:

@@ -215,6 +221,23 @@ The high-volume safety point exists so the station can still react before the ba

 The rectangular approximation is acceptable for this node's first basin model because operational level is always in metres from the basin floor, while calculated m³ can tolerate small shape errors. A later upgrade can replace `volume = level × surfaceArea` with a level-volume curve for benching, sumps, sediment/dead zones, and irregular wet-well geometry.

+### Predicted-volume bounds
+
+The predicted-volume integrator is clamped between two physical limits. **Measured** values are never clamped — only a real sensor can show level outside this range (e.g. inflow exceeds pump+weir capacity and the basin pressurises against the ceiling).
+
+**Upper bound — `maxVolAtOverflow`.** Once the integrator would push past the weir crest, the predicted level pins at `overflowLevel`. The excess is recorded two ways every tick it spills:
+
+- **Cumulative `overflowVolume.predicted.atequipment.default`** — running total of spill in m³, for compliance reporting via InfluxDB.
+- **Synthetic `flow.predicted.out.overflow`** — instantaneous spill rate (m³/s) equal to `inflow − real_outflow`. Registered as a predicted outflow contribution so `_selectBestNetFlow` sees a balanced ledger and reports `netFlowRate ≈ 0` while pinned. The integrator subtracts this synthetic flow before integrating so the spill never feeds back into the volume math.
+
+The `isOverflowing` flag (true when `level >= overflowLevel`) is what tells operators why net flow reads zero even though water is still moving through the basin.
+
+**Lower bound — `dryRunSafetyVol`.** The integrator can't drain below the dry-run threshold because pumps physically can't pump that low (the safety controller would shut them off, and even with safety disabled the suction loses prime). The clamp only fires on the transition — if the basin starts (or is calibrated) below `dryRunSafetyVol` it's left alone; inflow is what brings it back up.
+
+### Level-rate fallback during overflow
+
+When the chosen flow source is `level:measured` or `level:predicted` (priorities 3–4 in the ladder below), `dL/dt × surfaceArea` *is* the net flow. While level is pinned at `overflowLevel`, `dL/dt = 0` collapses the signal even though water is still moving. In that case `_selectBestNetFlow` holds the last known non-zero net flow until level starts dropping again — so dashboards keep a usable "this is roughly what's coming in" reading. The held value is refreshed any tick the level rate is meaningful, so it auto-updates once the basin un-pins.
+
 ## Net-flow selection

 Every tick, `_selectBestNetFlow()` walks a priority ladder and returns the first net flow that clears the dead-band (`|flow| ≥ flowThreshold`):
@@ -245,7 +268,7 @@ flowPositions = { inflow: ['in', 'upstream'], outflow: ['out', 'downstream'] }

 The `pumpingStation` supports multiple control modes. Each mode is a **policy that maps basin state to demand (0-100 %)**. `levelbased` uses `minLevel`, `startLevel`, and `maxLevel`; other modes may use different thresholds or compute them dynamically.

-The basin model owns the shared physical and safety references: pipe elevations, `dryRunLevel`, `highVolumeSafetyLevel`, and `overflowLevel`. `startLevel` is mode-specific and is documented with the mode diagrams, not the generic basin drawing.
+The basin model owns the shared physical and safety references: pipe elevations, `dryRunLevel`, `highVolumeSafetyLevel`, and `overflowLevel`. `minLevel`, `startLevel`, and `maxLevel` are mode-specific and are documented with the mode diagrams, not the generic basin drawing.

 Every mode gets its own page under [`modes/`](modes/README.md) with a consistent layout (inputs, threshold policy, demand formula, edge cases) so they can be compared side-by-side. Currently:

@@ -261,7 +284,7 @@ See [`modes/README.md`](modes/README.md) for the index and page template.

 `_safetyController` runs **before** `_controlLogic` every tick. Two rules, deliberately asymmetric — *dry-run protects the pumps from running themselves into air*, *high-volume protection tries to preserve distance to actual overflow*.

-![Safety rules — dry-run vs overfill](diagrams/safety-rules.drawio.svg)
+![Safety rules — dry-run vs high-volume safety](diagrams/safety-rules.drawio.svg)

 During high-volume or overflow conditions, level-based control naturally commands >=100 % on the downstream MGC because the level is above `maxLevel`.

@@ -319,8 +342,10 @@ The canonical end-to-end demo lives in the EVOLV superproject at [`examples/pump
 | "No volume data available to safe guard system; shutting down all machines." in logs | No measured level, predicted volume not calibrated, and no inflow/outflow samples yet. | Issue `calibratePredictedVolume` (or `calibratePredictedLevel`) once at startup, or wire a level sensor. |
 | `flowSource: null` and `direction: 'steady'` forever | Every flow / level signal falls inside the dead-band (default `1e-4 m³/s`). | Confirm flows are non-zero, or lower `config.general.flowThreshold` for a small-scale demo. |
 | `Qd` ignored | Station is not in `manual` mode. | Send `{ topic: 'changemode', payload: 'manual' }` first, or fall back to level-based control. |
-| Pumps keep running during overfill | Intended — overfill safety only stops **upstream** equipment; downstream pumps must drain. | To override, switch to `manual` and set `Qd = 0`, or issue an emergency-stop at the MGC. |
+| Pumps keep running during high-volume safety | Intended — high-volume safety only stops **upstream** equipment; downstream pumps must drain. | To override, switch to `manual` and set `Qd = 0`, or issue an emergency-stop at the MGC. |
 | Predicted volume drifts away from measured | Flow integrator has no reference — flows might have the wrong sign, or `unit` is mis-declared. | Call `calibratePredictedVolume` periodically from a measured level. |
+| Predicted level pinned at `overflowLevel` and `netFlowRate` reads ~0 | Intended while spilling — the synthetic `flow.predicted.out.overflow` balances the ledger so net is 0. Watch `isOverflowing`, `predictedOverflowRate`, and the cumulative `predictedOverflowVolume` instead. | Lower inflow (or raise pump capacity / `maxLevel`) to clear the overflow condition; level un-pins automatically. |
+| Measured level above `overflowLevel` | Real-world ceiling-pressure case — inflow is exceeding pump *and* weir capacity. | This is the only path to "above overflow" in the model; predicted is clamped. Trust the sensor; treat as an alarmable event. |

 ## Running it locally

--- a/wiki/modes/levelbased.md
+++ b/wiki/modes/levelbased.md
@@ -7,7 +7,7 @@ updated: 2026-04-22

 # Level-based mode

-The simplest and most widely deployed control strategy. Demand is a direct, *static* piecewise-linear function of basin level — no feedback loop, no predictions beyond the level measurement itself. This page uses the [shared basin model](../functional-description.md#basin-model); see [`modes/README.md`](README.md) for the template other mode pages follow.
+The simplest and most widely deployed control strategy. Demand is a direct, static function of basin level — no feedback loop, no predictions beyond the level measurement itself. This page uses the [shared basin model](../functional-description.md#basin-model); see [`modes/README.md`](README.md) for the template other mode pages follow.

 ## At a glance

@@ -20,9 +20,9 @@ The simplest and most widely deployed control strategy. Demand is a direct, *sta

 ## Diagram

-![Level-linear basin mode — demand vs level transfer function](../diagrams/modes/basin-mode-level-linear.drawio.svg)
+![Level-linear basin mode — demand vs level transfer function](../diagrams/modes/level-based/basin-mode-level-linear.drawio.svg)

-*Editable source: [`../diagrams/modes/basin-mode-level-linear.drawio.svg`](../diagrams/modes/basin-mode-level-linear.drawio.svg) (drag into [draw.io](https://app.diagrams.net/) — it round-trips).*
+*Editable sources: [`../diagrams/modes/level-based/basin-mode-level-linear.drawio.svg`](../diagrams/modes/level-based/basin-mode-level-linear.drawio.svg) and [`../diagrams/modes/level-based/basin-mode-level-log.drawio.svg`](../diagrams/modes/level-based/basin-mode-level-log.drawio.svg) (drag into [draw.io](https://app.diagrams.net/) — they round-trip).*

 ## Inputs

@@ -30,10 +30,11 @@ The simplest and most widely deployed control strategy. Demand is a direct, *sta
 |---|---|---|
 | current level | `measurement` child (`measured`) → predicted from volume integrator (fallback) | X-axis of the transfer function |
 | `config.control.levelbased.minLevel` | editor, static | below → pumps hard OFF |
-| `config.control.levelbased.startLevel` | editor, static | where demand-ramp starts |
+| `config.control.levelbased.startLevel` | editor, static | falling ramp reaches 0 % here; rising demand holds 0 % until the inlet level |
 | `config.control.levelbased.maxLevel` | editor, static | where demand saturates at 100 % |
+| `config.control.levelbased.curveType` | editor, static | `linear` or `log`; log is fast early response |

-The three control thresholds are the **only** mode-specific configuration. Nothing here is recomputed at runtime.
+The three control thresholds plus curve type are the mode-specific configuration. Nothing here is recomputed at runtime.

 ## Threshold policy

@@ -42,6 +43,7 @@ The three control thresholds are the **only** mode-specific configuration. Nothi
 | `minLevel` | `config.control.levelbased.minLevel` | No |
 | `startLevel` | `config.control.levelbased.startLevel` | No |
 | `maxLevel` | `config.control.levelbased.maxLevel` | No |
+| `curveType` | `config.control.levelbased.curveType` | No |

 That this policy is trivial (all static) is **the defining simplicity of this mode**. Modes like `powerBased` or future `weather-aware` variants will recompute these thresholds on the fly.

@@ -51,15 +53,15 @@ That this policy is trivial (all static) is **the defining simplicity of this mo
 if level < minLevel:
    demand = 0
    MGC → turnOffAllMachines()      # explicit shutdown, not just "0 %"
-elif level < startLevel:
-    demand = <previous demand>      # dead zone — hold last command (hysteresis)
-elif level <= maxLevel:
-    demand = lerp(level, [startLevel, maxLevel], [0 %, 100 %])
+elif direction == filling:
+    demand = curve(level, [inflowLevel, maxLevel], [0 %, 100 %])
+elif direction == draining:
+    demand = curve(level, [startLevel, maxLevel], [0 %, 100 %])
 else:
-    demand = 100 %                  # saturated; MGC clamps internally if overshoot
+    demand = previous demand
 ```

-Where `lerp` is linear interpolation. The MGC is free to distribute the demand across its pumps however its own policy dictates (equal split, lead-lag, staging — that's the MGC's business).
+Below the active lower ramp point, demand is 0 %. Above `maxLevel`, demand is 100 %. `curve` is either linear or logarithmic; the log variant rises faster early in the ramp. The MGC is free to distribute the demand across its pumps however its own policy dictates (equal split, lead-lag, staging — that's the MGC's business).

 ## Edge cases

--- a/wiki/modes/powerbased.md
+++ b/wiki/modes/powerbased.md
@@ -67,11 +67,11 @@ demandCap = min(100, 100 × maxPowerKW(t) / nominalStationPower)
 demand    = min(rawDemand, demandCap)
 ```

-When `demandCap < rawDemand`, the mode sacrifices drainage rate to stay within power budget. Level may rise — the overfill safety layer still applies as the last line of defence.
+When `demandCap < rawDemand`, the mode sacrifices drainage rate to stay within power budget. Level may rise — the high-volume safety layer still applies as the last line of defence before physical overflow.

 ## Edge cases

- **Peak hour with rising level.** demandCap drops faster than level rises → demand gets clipped; level approaches `overflowLevel`. If overfill safety trips, it overrides the clip (safety wins).
+- **Peak hour with rising level.** demandCap drops faster than level rises → demand gets clipped; level approaches `overflowLevel`. If high-volume safety trips, it overrides the clip (safety wins).
 - **Power signal dropout.** Fall back to static `maxPowerKW` from config; log warning.
 - **Grid exit from peak while basin is nearly full.** demandCap jumps back to 100; PID is memoryless so demand rises in one tick to match rawDemand.
 - **Measured vs predicted pump power.** Cap is enforced on predicted (decisions are made before the pump responds). Reconcile against measured for logging/diagnostics.
Author	SHA1	Message	Date
Rene De Ren	e2ebb31816	stopLevel Schmitt-trigger hysteresis + dead-zone keep-alive Levelbased control now distinguishes startLevel (rising-edge engage, ramp foot) from stopLevel (falling-edge disengage). _stopHystRunning flag flips TRUE crossing startLevel up, FALSE crossing stopLevel down. While engaged AND level inside [stopLevel, startLevel] (basin draining through the dead band), emit a configurable keep-alive percControl (default 1 %) so MGC keeps a single pump running for a full drain stroke instead of oscillating at startLevel. Hard turn-off the moment level <= stopLevel — independent of ramp scaling. Manual-mode demand=0 now also issues explicit turnOff to keep parity with the new MGC handleInput semantics where demand<=0 means "off". Editor preview shades the new hysteresis band; admin endpoint exposes runtime engaged state. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>	2026-05-08 11:20:36 +02:00
Rene De Ren	6ab585bcc2	Docs + simulations refresh; align spill-flow keys with new position - wiki/functional-description.md: rename Overfill Protection → High-volume Safety; tighten basin-ordering chain; relocate level-based mode diagrams under wiki/diagrams/modes/level-based/; document the new flow.predicted.overflow.default position (replaces the previous child='overflow' under position 'out'); add underflowVolume + predictedUnderflowVolume entries. - wiki/modes/{levelbased,powerbased}.md: paragraph cleanups. - wiki/diagrams: move level-linear basin diagram under modes/level-based/ alongside a new level-log variant. - simulations/run.js: add max_demand_gt expectation. - simulations/scenarios/*: minor fixture updates. - test/basic/nodeClass-config.test.js: new config-shape coverage. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>	2026-05-06 17:23:20 +02:00
Rene De Ren	d8490aa949	Predicted-volume hard-floor at 0 + spill flow position refactor Volume integrator changes: - Hard physical floor at 0 added to _updatePredictedVolume. Without it, a basin seeded below dryRunSafetyVol (calibration / startup / low seed) under continued net-outflow drifted volume arbitrarily negative; the level output looked clamped only because _calcLevelFromVolume floors at 0, masking the underlying drift. - New cumulative diagnostic: underflowVolume.predicted.atequipment (m³) + getOutput().predictedUnderflowVolume. Non-zero indicates a flow-balance error (over-reported outflow / missing inflow). - The transition-only dryRunSafetyVol clamp is preserved so startup-from-empty doesn't snap to 2.1 m³ on tick 1. Spill flow refactor (taxonomic + bug fix): - Synthetic spill moved from flow.predicted.out.<child='overflow'> to its own position flow.predicted.overflow.<default>. The spill is a derived quantity, not a physical sub-source sharing a position with pumps — .child() was the wrong knob. - Removes the spillPrev self-subtraction in the integrator (no longer needed: outflowTotal at ['out','downstream'] cleanly excludes spill). - Closes a latent fall-through bug exposed during this work: .child('overflow').getCurrentValue() returned the value of any available sibling child when overflow itself didn't yet exist. Hardened separately in generalFunctions@a516c2b. - _selectBestNetFlow folds the overflow position into the outflow side so the predicted net-flow balance still reads ~0 while pinned. Tests: 70/70 pass. 4 new subtests cover the 0-floor, accumulated underflow tracking, getOutput surface, and refill-from-empty. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>	2026-05-06 17:18:23 +02:00
Rene De Ren	6b46a8a8f0	Predicted-volume overflow clamp + spill tracking Predicted volume is now clamped to [dryRunSafetyVol, maxVolAtOverflow] in _updatePredictedVolume — the integrator can no longer drift above the weir crest (only a real measurement can show level > overflow, e.g. inflow exceeding pump+weir capacity). Excess is recorded as: - overflowVolume.predicted.atequipment.default — cumulative spill (m3) - flow.predicted.out.overflow — instantaneous spill rate (m3/s), registered as a synthetic outflow so net-flow balance reads ~0 while pinned. The integrator subtracts the prior tick's synthetic flow before integrating so it never feeds back into volume math. Lower clamp at dryRunSafetyVol fires only on the transition — a low seed/calibration is left alone; inflow is what brings it back up. _selectBestNetFlow holds the last non-zero level-rate net flow when level pins at overflowLevel and dL/dt collapses to 0, so dashboards keep showing roughly what's coming in. Auto-refreshes once level drops. getOutput() exposes predictedOverflowVolume + predictedOverflowRate as top-level convenience keys; the underlying measurements flow to InfluxDB via the standard MeasurementContainer flatten path. 9 new test assertions cover the upper-clamp + spill increment, stable spill across ticks, net-flow ~0 while pinned, spill clearing when inflow stops, low-seed left alone, drain-across-threshold clamp, and the new top-level output keys. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>	2026-05-06 14:47:46 +02:00
Rene De Ren	62bc73f2f9	Editor: dynamic input bounds + full hierarchy validation, layout polish Bounds (new src/editor/bounds.js): - Sets HTML5 min/max on every level + percent input each redraw, derived from the current values of related inputs so the spinner stops at the basin hierarchy: 0 < outflowLevel < dryRunLevel < startLevel ≤ inflowLevel ≤ shiftLevel ≤ maxLevel ≤ overflowLevel ≤ basinHeight - dryRunPercent capped so dryRunLevel ≤ startLevel given current outflow. - shiftArmPercent ∈ [1, 100]; highVolumeSafety% ∈ [1, 100]. Validation: - New visible ribbon above the basin diagram (#ps-basin-validation) listing every hierarchy violation. The in-SVG warning text is now a small reminder ("⚠ N ordering issues"). - basin-diagram.js owns hierarchy issues; mode-preview.js trimmed to only own shift-specific issues (shift > start, shift ≤ max, shiftArmPercent range, shiftLevel required-when-enabled). - oneditsave blocks Deploy on the union of _psBasinValidationIssues and _psModeValidationIssues with a RED.notify listing all problems. Layout polish: - Side panel widened to 220 px with minmax(0, 1fr) first column so long labels can no longer push the rows past the panel edge. - Basin SVG max-width 380 → 360, gap between side panel and SVG bumped 14 → 28 px. Tank shifted right (x=145 width=110) so the inlet "bottom of pipe" sub-label is no longer clipped on the left edge. - "0 m (datum)" moved below the tank (y=395, centred) so it can't collide with "Outlet / top of pipe" when outflowLevel is near floor. - Zone labels shortened (Spare / Sewage + buffer / Buffer / Dead vol) and only show when the bracketing thresholds are ≥ 28 px apart, so they never sit on a threshold label. - Mode preview axis labels under the chart removed — line colour + side-panel labels + hover-couple already identify each line. Stub <text> elements left hidden to keep the redraw loop simple. Arm-% line + label trimmed in 10 px on the right so they're not clipped. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>	2026-05-06 14:10:22 +02:00
Rene De Ren	de9a79b888	Hold-then-ramp shift semantics + shiftArmPercent + e2e tests 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>	2026-05-06 11:46:46 +02:00