# Reference — Limitations

![code-ref](https://img.shields.io/badge/code--ref-b825ac1-blue)

> [!NOTE]
> What `pumpingStation` does not do, current rough edges, and open questions tracked against the refactor. Live source for the open items: `.claude/refactor/OPEN_QUESTIONS.md` in the EVOLV superproject.

---

## When you would not use this node

| Scenario | Use instead |
|:---|:---|
| Pressurised distribution network without a basin | Cascade pumpingStations, or a `valveGroupControl` parented to a flow source |
| Single pump, no basin, no level sensor | Parent a `rotatingMachine` directly under a UI driver |
| Air manifold (compressor + valves) | A future `compressorStation` — not implemented |
| Open-channel flow without a wet-well | Out of scope for the current basin model (rectangular prismatic only) |
| Sludge thickening basin | Use a `settler` — different settling-velocity model required |

---

## Known limitations

### Implemented modes vs schema modes

The schema's `control.mode` enum lists eight modes, but only two are implemented in code:

| Mode | Status | Notes |
|:---|:---|:---|
| `levelbased` | Implemented | Default; the most production-tested path |
| `manual` | Implemented | Operator's `set.demand` is forwarded unchanged |
| `flowbased` | Placeholder | Schema accepts it; runtime falls back to levelbased |
| `pressureBased` | Placeholder | Same as above |
| `percentageBased` | Placeholder | Same as above |
| `powerBased` | Placeholder | Same as above |
| `hybrid` | Placeholder | Same as above |
| `mpc` | Not in code | Reserved name |

If you select an unimplemented mode in the editor, the basin runs but the controller stays in level-based. Tracked.

### Basin shape

Only rectangular prismatic basins are supported. Cylindrical, frusto-conical, or stepped basins would need a new `BasinGeometry` implementation. The `volume = level * surfaceArea` relationship is hard-wired.

### Net-flow source selection

When both an MGC parent and direct rotatingMachine children are wired, the station subscribes only to the MGC's predicted flow. If you intentionally have MGC + extra individual pumps, the extras are invisible to the volume integrator. The router protects against double-counting but does not warn about this edge case.

### Aliases not yet removed

The following legacy aliases still work but log a deprecation warning on first use. They are scheduled for removal in Phase 7:

| Canonical | Legacy alias |
|:---|:---|
| `set.mode` | `changemode` |
| `set.inflow` | `q_in` |
| `set.outflow` | `q_out` |
| `set.demand` | `Qd` |
| `cmd.calibrate.volume` | `calibratePredictedVolume` |
| `cmd.calibrate.level` | `calibratePredictedLevel` |
| `child.register` | `registerChild` |

Update integrations now.

---

## Open questions (tracked)

Pulled from `.claude/refactor/OPEN_QUESTIONS.md`. Last reviewed on the date in the badge above.

| Question | Where it lives |
|:---|:---|
| `overfillVol` alias drop — same shape as the already-done `overfillLevel` drop | OPEN_QUESTIONS.md (pumpingStation entry) |
| Net-flow source warning when multiple aggregators are wired | Internal — not yet ticketed |
| Cylindrical basin geometry | Internal — not yet ticketed |
| Docker E2E sign-off (P2.14) | OPEN_QUESTIONS.md (Phase 6) |

---

## Migration notes

### From pre-refactor

| Pre-refactor | Now |
|:---|:---|
| `enableOverfillProtection` | `enableHighVolumeSafety` |
| `overfillThresholdPercent` | `highVolumeSafetyThresholdPercent` |
| Legacy topics (`changemode`, `q_in`, ...) | Canonical topics (see [Reference — Contracts](Reference-Contracts) for the alias map) |
| `basic.flow.json` (legacy) | `01-Basic.json` (canonical-topic version) |

### Renamed safety thresholds

The safety layer used to expose threshold fields named `overfill*`. Those names suggested the layer prevents overflow specifically; in practice the rule handles high-volume conditions more broadly (high level + low inflow / outflow imbalance). The current names (`highVolumeSafety*`) reflect that.

---

## Related pages

| Page | Why |
|:---|:---|
| [Home](Home) | Intuitive overview |
| [Reference — Contracts](Reference-Contracts) | Topic + config + child filters (alias map at the end) |
| [Reference — Architecture](Reference-Architecture) | Code map, state chart |
| [Reference — Examples](Reference-Examples) | Shipped flows |