# Decision: Shared Modern PID in generalFunctions + PumpingStation Flow-Based Adoption

- Date: 2026-02-23
- Scope: `nodes/generalFunctions/src/pid/*`, `nodes/pumpingStation/src/*`

## Context
Flow-based control in `pumpingStation` needed a production-grade PID with freeze/unfreeze, runtime retuning, and support for cascade/secondary-loop architecture.

## Options Considered
1. Implement PID only inside `pumpingStation`.
2. Implement shared PID in `generalFunctions` and consume it from `pumpingStation`.
3. Keep current heuristic (non-PID) flow controller.

## Decision
Chose option 2.

## Rationale
- PID behavior is cross-domain control functionality and should be reusable across EVOLV nodes.
- `generalFunctions` already serves as shared utility/runtime infrastructure.
- Reuse reduces drift and duplicated control logic.
- PumpingStation can immediately adopt shared PID while preserving existing topic contracts.

## Consequences
- Positive:
  - Single, test-covered PID implementation with modern features.
  - PumpingStation flow mode becomes true closed-loop control.
  - Runtime support for freeze/unfreeze and tuning updates without redeploy.
- Risks:
  - Behavioral differences versus prior heuristic flow control.
  - Requires conservative tuning per site.

## Safety / Compatibility
- No existing topic names were removed.
- Added optional control topics for PID runtime management.
- Existing non-flowbased modes remain intact.

## Rollback
- Revert `nodes/pumpingStation/src/specificClass.js` flow-based branch to previous heuristic logic.
- Keep shared PID module in `generalFunctions` for future use, or revert `nodes/generalFunctions/src/pid/*` if required.

## Migration Notes
- For `flowbased`, start with low `kp/ki`, verify stability in commissioning, then tune upward.
- Use `freezeFlowPid` and `setFlowPidMode` during maintenance or manual takeover.