fix(safety): overfill must keep pumps running, not shut them down

Two hard rules for the safety controller, matching sewer PS design:

1. BELOW stopLevel (dry-run): pumps CANNOT start.
   All downstream equipment shut down. safetyControllerActive=true
   blocks _controlLogic so level control can't restart pumps.
   Only manual override or emergency can change this.

2. ABOVE overflow level (overfill): pumps CANNOT stop.
   Only UPSTREAM equipment is shut down (stop more water coming in).
   Machine groups (downstream pumps) are NOT shut down — they must
   keep draining. safetyControllerActive is NOT set, so _controlLogic
   continues commanding pumps at the demand dictated by the level
   curve (which is >100% near overflow = all pumps at maximum).
   Only manual override or emergency stop can shut pumps during
   an overfill event.

Previously the overfill branch called turnOffAllMachines() on machine
groups AND set safetyControllerActive=true, which shut down the pumps
and blocked level control from restarting them — exactly backwards
for a sewer pumping station where the sewage keeps coming.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

CLAUDE.md

@@ -0,0 +1,23 @@
+# pumpingStation — Claude Code context
+
+Wet-well basin model and pump orchestration.
+Part of the [EVOLV](https://gitea.wbd-rd.nl/RnD/EVOLV) wastewater-automation platform.
+
+## S88 classification
+
+| Level | Colour | Placement lane |
+|---|---|---|
+| **Process Cell** | `#0c99d9` | L5 |
+
+## Flow layout rules
+
+When wiring this node into a multi-node demo or production flow, follow the
+placement rule set in the **EVOLV superproject**:
+
+> `.claude/rules/node-red-flow-layout.md` (in the EVOLV repo root)
+
+Key points for this node:
+- Place on lane **L5** (x-position per the lane table in the rule).
+- Stack same-level siblings vertically.
+- Parent/children sit on adjacent lanes (children one lane left, parent one lane right).
+- Wrap in a Node-RED group box coloured `#0c99d9` (Process Cell).

src/nodeClass.js

@@ -221,6 +221,27 @@ class nodeClass {
           this.source.setManualInflow(val, ts, unit);
           break;
         }
+        case 'Qd': {
+          // Manual demand: operator sets the target output via a
+          // dashboard slider. Only accepted when PS is in 'manual'
+          // mode — mirrors how rotatingMachine gates commands by
+          // mode (virtualControl vs auto).
+          const demand = Number(msg.payload);
+          if (!Number.isFinite(demand)) {
+            this.source.logger.warn(`Invalid Qd value: ${msg.payload}`);
+            break;
+          }
+          if (this.source.mode === 'manual') {
+            this.source.forwardDemandToChildren(demand).catch((err) =>
+              this.source.logger.error(`Failed to forward demand: ${err.message}`)
+            );
+          } else {
+            this.source.logger.debug(
+              `Qd ignored in ${this.source.mode} mode. Switch to manual to use the demand slider.`
+            );
+          }
+          break;
+        }
       }
       done();
     });

src/specificClass.js

@@ -63,10 +63,21 @@ class PumpingStation {
       this.stations[child.config.general.id] = child;
     } else if (softwareType === 'machinegroup') {
       this.machineGroups[child.config.general.id] = child;
-      this._registerPredictedFlowChild(child);
     }
 
-    if (softwareType === 'machine' || softwareType === 'pumpingstation' || softwareType === 'machinegroup') {
+    // Register predicted-flow subscription. Only register the HIGHEST-
+    // level aggregator: if a machinegroup is present, subscribe to IT
+    // (its flow.predicted already aggregates all child machines). Do NOT
+    // also subscribe to individual machines — that would double-count
+    // because each pump's flow is included in the group total.
+    //
+    // Individual machines (softwareType='machine') are only subscribed
+    // when there is NO machinegroup parent — i.e., pumps wired directly
+    // to the pumping station without an MGC in between.
+    if (softwareType === 'machinegroup' || softwareType === 'pumpingstation') {
+      this._registerPredictedFlowChild(child);
+    } else if (softwareType === 'machine' && Object.keys(this.machineGroups).length === 0) {
+      // Direct-child machine, no group above it — register its flow.
       this._registerPredictedFlowChild(child);
     }
   }
@@ -97,18 +108,21 @@ class PumpingStation {
     const childId = child.config.general.id ?? childName;
 
     let posKey;
-    let eventNames;
+    let eventName;
     switch (position) {
       case 'downstream':
       case 'out':
       case 'atequipment':
         posKey = 'out';
-        eventNames = ['flow.predicted.downstream', 'flow.predicted.atequipment'];
+        // Subscribe to ONE event only. 'downstream' is the most specific
+        // — avoids double-counting from 'atequipment' which carries the
+        // same total flow on a different event name.
+        eventName = 'flow.predicted.downstream';
         break;
       case 'upstream':
       case 'in':
         posKey = 'in';
-        eventNames = ['flow.predicted.upstream', 'flow.predicted.atequipment'];
+        eventName = 'flow.predicted.upstream';
         break;
       default:
         this.logger.warn(`Unsupported predicted flow position "${position}" from ${childName}`);
@@ -132,7 +146,7 @@ class PumpingStation {
         .value(eventData.value, ts, unit);
     };
 
-    eventNames.forEach((ev) => child.measurements.emitter.on(ev, handler));
+    child.measurements.emitter.on(eventName, handler);
   }
 
   /* --------------------------- Calibration --------------------------- */
@@ -250,10 +264,26 @@ class PumpingStation {
       return;
     }
 
-    if (level > startLevel && direction === 'filling') {
-      const percControl = this._scaleLevelToFlowPercent(level);
-      this.logger.debug(`Controllevel based => Level ${level} control applying to pump : ${percControl}`);
+    // Continuous proportional control: command pumps whenever level is
+    // above stopLevel. The percControl ramp gives:
+    //   - 0% at minFlowLevel (= startLevel) → pumps barely running
+    //   - linearly up to 100% at maxFlowLevel → all pumps full
+    //   - Below startLevel but above stopLevel: percControl < 0 → clamp
+    //     to 0 → MGC turns off pumps (graceful ramp-down instead of a
+    //     dead zone where pumps keep running at their last setpoint).
+    if (level > stopLevel) {
+      const rawPercControl = this._scaleLevelToFlowPercent(level);
+      const percControl = Math.max(0, rawPercControl);
+      this.logger.debug(`Controllevel based => Level ${level} percControl ${percControl}`);
+      if (percControl > 0) {
         await this._applyMachineLevelControl(percControl);
+        await this._applyMachineGroupLevelControl(percControl);
+      } else {
+        // Between stopLevel and startLevel with percControl ≤ 0:
+        // tell MGC to scale back to 0 rather than leaving pumps
+        // running at the last commanded setpoint.
+        await this._applyMachineGroupLevelControl(0);
+      }
     }
 
     if (level < stopLevel && direction === 'draining') {
@@ -272,6 +302,38 @@ class PumpingStation {
     // placeholder for flow-based logic
   }
 
+  /**
+   * Forward a manual demand value to all child machine groups + direct
+   * machines. Called from the 'Qd' topic handler when PS is in manual
+   * mode — mirrors how rotatingMachine gates commands by mode.
+   * @param {number} demand - the operator-set demand (interpretation
+   *   depends on MGC scaling: 'absolute' = m³/h, 'normalized' = 0-100%)
+   */
+  async forwardDemandToChildren(demand) {
+    this.logger.info(`Manual demand forwarded: ${demand}`);
+    // Forward to machine groups (MGC)
+    if (this.machineGroups && Object.keys(this.machineGroups).length > 0) {
+      await Promise.all(
+        Object.values(this.machineGroups).map((group) =>
+          group.handleInput('parent', demand).catch((err) => {
+            this.logger.error(`Failed to forward demand to group: ${err.message}`);
+          })
+        )
+      );
+    }
+    // Forward to direct machines (if any)
+    if (this.machines && Object.keys(this.machines).length > 0) {
+      const perMachine = demand / Object.keys(this.machines).length;
+      for (const machine of Object.values(this.machines)) {
+        try {
+          await machine.handleInput('parent', 'execMovement', perMachine);
+        } catch (err) {
+          this.logger.error(`Failed to forward demand to machine: ${err.message}`);
+        }
+      }
+    }
+  }
+
   async _applyMachineGroupLevelControl(percentControl) {
     if (!this.machineGroups || Object.keys(this.machineGroups).length === 0) return;
     await Promise.all(
@@ -496,6 +558,24 @@ class PumpingStation {
 
   /* --------------------------- Safety --------------------------- */
 
+  /**
+   * Safety controller — two hard rules:
+   *
+   * 1. BELOW stopLevel (dry-run): pumps CANNOT start.
+   *    Shuts down all downstream machines + machine groups.
+   *    Only a manual override or emergency can restart them.
+   *    safetyControllerActive = true → blocks _controlLogic.
+   *
+   * 2. ABOVE overflow level (overfill): pumps CANNOT stop.
+   *    Shuts down UPSTREAM equipment only (stop more water coming in).
+   *    Does NOT shut down downstream pumps or machine groups — they
+   *    must keep draining. Does NOT set safetyControllerActive — the
+   *    level-based control keeps running so pumps stay at the demand
+   *    dictated by the current level (which will be >100% near overflow,
+   *    meaning all pumps at maximum via the normal demand curve).
+   *    Only a manual override or emergency stop can shut pumps during
+   *    an overfill event.
+   */
   _safetyController(remainingTime, direction) {
     this.safetyControllerActive = false;
 
@@ -522,10 +602,12 @@ class PumpingStation {
     const triggerHighVol = this.basin.maxVolOverflow * ((Number(overfillThresholdPercent) || 0) / 100);
     const triggerLowVol = this.basin.minVol * (1 + ((Number(dryRunThresholdPercent) || 0) / 100));
 
+    // Rule 1: DRY-RUN — below stopLevel, pumps cannot run.
     if (direction === 'draining') {
       const timeTriggered = timeProtectionEnabled && remainingTime != null && remainingTime < timeleftToFullOrEmptyThresholdSeconds;
       const dryRunTriggered = dryRunEnabled && vol < triggerLowVol;
       if (timeTriggered || dryRunTriggered) {
+        // Shut down all downstream equipment — pumps must stop.
         Object.values(this.machines).forEach((machine) => {
           const pos = machine?.config?.functionality?.positionVsParent;
           if ((pos === 'downstream' || pos === 'atequipment') && machine._isOperationalState()) {
@@ -535,28 +617,38 @@ class PumpingStation {
         Object.values(this.stations).forEach((station) => station.handleInput('parent', 'execSequence', 'shutdown'));
         Object.values(this.machineGroups).forEach((group) => group.turnOffAllMachines());
         this.logger.warn(
-          `Safe guard triggered: vol=${vol.toFixed(2)} m3, remainingTime=${remainingTime ? remainingTime.toFixed(1) : 'N/A'} s; shutting down downstream equipment`
+          `Dry-run safety: vol=${vol.toFixed(2)} m3, remainingTime=${remainingTime ? remainingTime.toFixed(1) : 'N/A'} s; shutting down downstream equipment`
         );
+        // Block _controlLogic so level-based control can't restart pumps.
         this.safetyControllerActive = true;
       }
     }
 
+    // Rule 2: OVERFILL — above overflow level, pumps cannot stop.
+    // Only shut down UPSTREAM equipment. Downstream pumps + machine
+    // groups keep running at whatever the level control demands
+    // (which will be >100% near overflow = all pumps at max).
+    // Do NOT set safetyControllerActive — _controlLogic must keep
+    // running to maintain pump demand.
     if (direction === 'filling') {
       const timeTriggered = timeProtectionEnabled && remainingTime != null && remainingTime < timeleftToFullOrEmptyThresholdSeconds;
       const overfillTriggered = overfillEnabled && vol > triggerHighVol;
       if (timeTriggered || overfillTriggered) {
+        // Shut down UPSTREAM only — stop more water coming in.
         Object.values(this.machines).forEach((machine) => {
           const pos = machine?.config?.functionality?.positionVsParent;
           if (pos === 'upstream' && machine._isOperationalState()) {
             machine.handleInput('parent', 'execSequence', 'shutdown');
           }
         });
-        Object.values(this.machineGroups).forEach((group) => group.turnOffAllMachines());
         Object.values(this.stations).forEach((station) => station.handleInput('parent', 'execSequence', 'shutdown'));
+        // NOTE: machine groups (downstream pumps) are NOT shut down.
+        // They must keep draining to prevent overflow from worsening.
         this.logger.warn(
-          `Safe guard triggered: vol=${vol.toFixed(2)} m3, remainingTime=${remainingTime ? remainingTime.toFixed(1) : 'N/A'} s; shutting down upstream equipment`
+          `Overfill safety: vol=${vol.toFixed(2)} m3, remainingTime=${remainingTime ? remainingTime.toFixed(1) : 'N/A'} s; shutting down upstream equipment only — pumps keep running`
         );
-        this.safetyControllerActive = true;
+        // NOTE: safetyControllerActive is NOT set — level control
+        // keeps commanding pumps at maximum demand.
       }
     }
   }