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>

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.

pumpingStation.html

@@ -86,6 +86,7 @@
       shiftLevel: { value: 0 },
       shiftArmPercent: { value: 95 },
       startLevel: { value: null },
+      stopLevel: { value: null },
       minLevel: { value: null },
       maxLevel: { value: null },
       flowSetpoint: { value: null },
@@ -413,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>
@@ -469,6 +475,7 @@
       <!-- 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" />
@@ -484,6 +491,7 @@
            (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>

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` |

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})` };

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 },
   ],
 };

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 },
   ],
 };

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,
     },
   },

src/editor/bounds.js

@@ -66,6 +66,13 @@
         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',

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
@@ -85,11 +90,14 @@
         return pts.join(' ');
       };
 
-      // Up curve: same as before.
+      // 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
@@ -152,6 +160,7 @@
       [
         ['dryRunLevel', dryRun],
         ['startLevel', start],
+        ['stopLevel', stop],
         ['inflowLevel', inlet],
         ['maxLevel', max],
         ['overflowLevel', overflow],

src/nodeClass.js

@@ -66,6 +66,7 @@ class nodeClass {
         levelbased:{
           minLevel:uiConfig.minLevel,
           startLevel:uiConfig.startLevel,
+          stopLevel: uiConfig.stopLevel,
           maxLevel:uiConfig.maxLevel,
           curveType: uiConfig.levelCurveType || uiConfig.curveType,
           logCurveFactor: uiConfig.logCurveFactor,

src/specificClass.js

@@ -119,6 +119,28 @@ class PumpingStation {
     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.
     // Default 1e-4 m3/s ≈ 0.36 m3/h — below this, net flow is
@@ -379,13 +401,45 @@ class PumpingStation {
       this.percControl = 0;
       this._shiftHoldValue = null;
       this._shiftArmed = false;
+      this._stopHystRunning = false;
       this._lastDirection = direction;
       Object.values(this.machineGroups).forEach((group) => group.turnOffAllMachines());
       return;
     }
 
-    // Up-curve value (always defined; foot=inflowLevel, top=maxLevel).
-    const upPct = this._scaleLevelToFlowPercent(level, this.basin?.inflowLevel ?? startLevel, cfg.maxLevel);
+    // 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;
+
+    if (stopThresholdActive && level <= stopLvl) {
+      // Hard off: drained past stopLevel.
+      this.percControl = 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) {
@@ -423,9 +477,23 @@ class PumpingStation {
       && direction === 'draining' && this._shiftHoldValue != null;
 
     if (!inDrainingHold) {
-      // Up curve: 0 % below inflow, scaled inflow..max → 0..100, saturates above max.
-      if (level < (this.basin?.inflowLevel ?? startLevel)) {
-        percControl = 0;
+      // 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);
       }
@@ -484,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(
@@ -645,15 +723,13 @@ 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 outflowTotal = this.measurements.sum('flow', 'predicted', this.flowPositions.outflow, flowUnit) || 0;
-    // Subtract the previous tick's synthetic spill so it doesn't feed back into the integrator.
-    // The spill is registered as a 'predicted out' flow (child='overflow') so _selectBestNetFlow
-    // sees it for net-flow balance, but the volume math here must use REAL outflow only.
-    const spillPrev = this.measurements
-      .type('flow').variant('predicted').position('out').child('overflow')
-      .getCurrentValue(flowUnit) || 0;
-    const outflowReal = outflowTotal - spillPrev;
+    const outflowReal = this.measurements.sum('flow', 'predicted', this.flowPositions.outflow, flowUnit) || 0;
 
     if (!this._predictedFlowState) {
       this._predictedFlowState = { inflow, outflow: outflowReal, lastTimestamp: now };
@@ -673,12 +749,17 @@ class PumpingStation {
     const writeTimestamp = timestampPrev + deltaSeconds * 1000;
 
     // Predicted-volume bounds.
-    //   Upper: maxVolAtOverflow — past this the basin is physically spilling
-    //          over the weir, so predicted level pins at overflowLevel and
-    //          the excess is tracked as overflow volume + spill flow.
-    //   Lower: dryRunSafetyVol — pumps physically can't pump below this.
-    // Only a measured level can show level outside this range (e.g. inflow
-    // exceeds pump+weir capacity → ceiling-pressure case).
+    //   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);
@@ -686,27 +767,29 @@ class PumpingStation {
     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) {
-      // Drained across the dry-run threshold — pumps would have stopped here.
-      // If we were already below (via calibration / low seed), leave the
-      // integrator alone so it follows the physics it's been told.
       nextVolume = lowerClamp;
     }
+    if (nextVolume < 0) {
+      underflowIncrement = -nextVolume;
+      nextVolume = 0;
+    }
 
-    // Synthetic spill flow.
-    // While pinned at overflow with continuing net-positive inflow, the
-    // weir is carrying away (inflow − outflowReal). Registering this as
-    // an 'out' flow keeps the predicted net-flow balance at ~0 (matches
-    // the level-pinned reality).
+    // 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('out').child('overflow')
+      .type('flow').variant('predicted').position('overflow')
       .value(spillRate, writeTimestamp, 'm3/s').unit('m3/s');
 
     // Cumulative overflow volume — for compliance reporting via InfluxDB.
@@ -718,6 +801,19 @@ class PumpingStation {
         .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');
@@ -756,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;
@@ -1099,7 +1200,9 @@ class PumpingStation {
     output.predictedOverflowVolume = this.measurements
       .type('overflowVolume').variant('predicted').position('atequipment').getCurrentValue('m3') ?? 0;
     output.predictedOverflowRate = this.measurements
-      .type('flow').variant('predicted').position('out').child('overflow').getCurrentValue('m3/s') ?? 0;
+      .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;
   }
 

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);
+});

test/basic/specificClass.test.js

@@ -472,7 +472,7 @@ test('Predicted volume — overflow clamp and spill tracking', async (t) => {
     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('out').child('overflow').getCurrentValue('m3/s');
+    const spill = ps.measurements.type('flow').variant('predicted').position('overflow').getCurrentValue('m3/s');
     assert.equal(spill, 2);  // instantaneous balance: inflow − outflowReal
   });
 
@@ -483,7 +483,7 @@ test('Predicted volume — overflow clamp and spill tracking', async (t) => {
     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('out').child('overflow').getCurrentValue('m3/s');
+    const spill = ps.measurements.type('flow').variant('predicted').position('overflow').getCurrentValue('m3/s');
     assert.equal(spill, 2);
   });
 
@@ -499,7 +499,7 @@ test('Predicted volume — overflow clamp and spill tracking', async (t) => {
     ps._predictedFlowState = { inflow: 0, outflow: 0, lastTimestamp: t0 + 2000 };
     Date.now = () => t0 + 3000;
     ps._updatePredictedVolume();
-    const spill = ps.measurements.type('flow').variant('predicted').position('out').child('overflow').getCurrentValue('m3/s');
+    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');
@@ -549,3 +549,53 @@ test('getOutput — exposes predictedOverflowVolume / predictedOverflowRate', ()
   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
+  });
+});

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
 

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
 

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
 

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.