| Secondary inputs | measured pump power, live grid-price / peak-hours signal |
| Output | demand 0–100 % clipped so `Σ pump power ≤ maxPowerKW(t)` |
| Thresholds adjusted at runtime? | `maxPowerKW(t)` yes — level thresholds no |
| Use when | Grid has peak-hour tariffs or net-congestion caps |
## Diagram — the levelbased curve with a moving clip ceiling
```
demand % ← dashed line: levelbased curve
100 ┤ ╱ ─────── ← solid: clip at powerBudget(t)
│ ╱ clip lowers
│ ╱ during grid peak
│ ╱ ─────────
│ ╱╱
│ ╱╱
│ ╱╱
0 ┼────────●───────●─────────────────────► level
startLevel maxLevel
↑ the family of curves:
clip=100% (grid idle),
clip=70% (shoulder),
clip=40% (peak).
```
The *shape* stays levelbased; the *ceiling* drops when the grid is strained. That's the Tier-2 signature: same input axis, parameter shifts the curve.
## Inputs
| Signal | Where from | Role |
|---|---|---|
| current level | as in levelbased | primary input |
| `config.control.powerBased.maxPowerKW` | editor, static | hard cap on station power |
| `config.control.powerBased.powerControlMode` | `limit` / `optimize` | whether to just clip or to schedule |
| live grid signal (future) | external topic or forecast | modulates the cap over time |
| measured pump power | `power.measured.*` from children | real-time feedback against the cap |
## Threshold policy
Level thresholds (`minLevel`, `startLevel`, `maxLevel`) are **identical to levelbased** — they define the shape of the underlying curve. What's new is a runtime-varying ceiling `demandCap(t)` derived from the power budget.
`demandCap(t) = 100 × (maxPowerKW(t) / nominalStationPowerAtFull)` — where `maxPowerKW(t)` may come from config (static `limit` mode) or an external grid-price feed (dynamic).
## Demand formula
```text
rawDemand = levelbasedDemand(level) # the underlying Tier-1 curve
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.
- **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.
