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>

src/specificClass.js

@@ -264,15 +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}`);
-      await this._applyMachineLevelControl(percControl);
-      // Also forward to machine groups (e.g. MGC) — the level-based
-      // control originally only addressed direct-child machines, but in
-      // a hierarchical topology (PS → MGC → pumps) the machines sit
-      // under MGC and PS.machines is empty.
-      await this._applyMachineGroupLevelControl(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') {
@@ -547,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;
 
@@ -573,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()) {
@@ -586,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.
       }
     }
   }