Planner: add per-slot CapacityLedger (Phase 2 foundation)

Tracks residual charging power per time slot on a shared circuit:
Available/Reserve plus CanHost, the semi-continuous min-power gate (a
charger runs >= min or off). Foundation for priority-ordered, circuit-aware
planning. Single circuit + static budget for now; hierarchy TODO.

Author: andig

core/planner/ledger.go

@@ -0,0 +1,41 @@
+package planner
+
+import (
+	"time"
+
+	"github.com/evcc-io/evcc/api"
+)
+
+// CapacityLedger tracks residual charging power available per time slot on a
+// shared circuit, so loadpoints can be planned in priority order without
+// overcommitting the circuit. Slots are keyed by their truncated start time.
+type CapacityLedger struct {
+	slot   time.Duration
+	budget float64               // total circuit power (W) per slot
+	used   map[time.Time]float64 // reserved power (W) per slot start
+}
+
+// NewCapacityLedger creates a ledger with the given per-slot power budget.
+func NewCapacityLedger(budget float64, slot time.Duration) *CapacityLedger {
+	return &CapacityLedger{slot: slot, budget: budget, used: make(map[time.Time]float64)}
+}
+
+// Available returns the residual power in the slot containing t.
+func (l *CapacityLedger) Available(t time.Time) float64 {
+	return max(0, l.budget-l.used[t.Truncate(l.slot)])
+}
+
+// Reserve subtracts power across every slot the plan occupies.
+func (l *CapacityLedger) Reserve(plan api.Rates, power float64) {
+	for _, r := range plan {
+		for t := r.Start.Truncate(l.slot); t.Before(r.End); t = t.Add(l.slot) {
+			l.used[t] += power
+		}
+	}
+}
+
+// CanHost reports whether the slot containing t can still grant minPower.
+// Semi-continuous: a charger runs at >= minPower or off (evcc-io/optimizer#91).
+func (l *CapacityLedger) CanHost(t time.Time, minPower float64) bool {
+	return l.Available(t) >= minPower
+}

core/planner/ledger_test.go

@@ -0,0 +1,36 @@
+package planner
+
+import (
+	"testing"
+	"time"
+
+	"github.com/evcc-io/evcc/api"
+	"github.com/stretchr/testify/assert"
+)
+
+func TestCapacityLedger(t *testing.T) {
+	start := time.Date(2020, 1, 1, 0, 0, 0, 0, time.UTC)
+	next := start.Add(time.Hour)
+
+	l := NewCapacityLedger(11000, time.Hour)
+
+	// full budget initially, hosts a 3p 6A (4140W) session
+	assert.Equal(t, 11000.0, l.Available(start))
+	assert.True(t, l.CanHost(start, 4140))
+
+	// reserve 7400W in the first slot
+	l.Reserve(api.Rates{{Start: start, End: next}}, 7400)
+	assert.Equal(t, 3600.0, l.Available(start))
+
+	// semi-continuous: 3600 < 4140 min -> cannot host another 3p session,
+	// but a 1p 6A (1380W) still fits
+	assert.False(t, l.CanHost(start, 4140))
+	assert.True(t, l.CanHost(start, 1380))
+
+	// the next slot is untouched
+	assert.Equal(t, 11000.0, l.Available(next))
+
+	// over-reserving never goes negative
+	l.Reserve(api.Rates{{Start: start, End: next}}, 9000)
+	assert.Equal(t, 0.0, l.Available(start))
+}

docs/agents/loadmanagement-aware-planning.md

@@ -91,18 +91,21 @@ Root gap: plans optimise against the tariff and clamp only to the circuit's
       a throttled loadpoint charges slower than `maxPower` assumed, so its plan
       eventually overruns.
 
-### Phase 1 — Deterministic priority-aware clamp (Option C)
-- [x] Order the update round by priority instead of config order
-      (`site.prioritizedLoadpoints`): fast/deadline-bound (`IsFastChargingActive`)
-      first, then descending `EffectivePriority`. So on a shared circuit the
-      higher-priority loadpoints establish draw first and the reactive clamp
-      throttles the rest. Note: forced and plan-active are folded into one tier
-      here; a strict forced > plan-active sub-order can be added later.
-- [x] Regression test (`TestPrioritizedLoadpoints`): fast first, then priority.
+### Phase 1 — Deterministic priority-aware clamp (Option C) — dropped
+
+Reordering the round-robin update sequence by priority was tried and reverted:
+it does not help. Updates are round-robin (one loadpoint per tick) and also
+event-driven (`lpUpdateChan`), and the clamp reacts to *measured* power, so in
+steady state allocation is order-independent and the reorder is a near no-op.
+
+Priority must instead drive **planner allocation** (Phase 2): plan loadpoints in
+priority order against the shared-capacity ledger. The round-robin control
+sequence stays untouched.
 
 ### Phase 2 — Capacity ledger + priority-ordered planning (Option B)
-- [ ] Per-circuit, per-slot residual-capacity ledger, mirroring the parent/child
-      circuit tree (like `ValidatePower` recursion).
+- [x] Per-slot residual-capacity ledger (`planner.CapacityLedger`): `Available`,
+      `Reserve`, and `CanHost` (semi-continuous min-power gate). Single circuit,
+      static budget for now; parent/child tree still TODO.
 - [ ] Extend `planner.Plan` / `optimalPlan` to accept a per-slot power cap.
       Today a slot equals full Pmax; a capped slot delivers
       `min(Pmax, residual) × slotLen`, so a partially-available slot must spill