"""Who gets to command the inverter, and why. Every strategy - the grid-following loop, the maintenance cycle, peak shaving, the safety stops - stops writing the setpoint directly and instead returns a CLAIM each cycle. This module resolves the claims into one number. ⚠️ THE REASON THIS EXISTS. Two controllers writing one actuator is the failure this whole system is built to avoid: it is what the vendor controller did to the reference site, and §4.4 of the project notes calls it out by name. Before this module, "exactly one writer" was a convention held up by an if/else ladder and careful reading. With an EV charger and a heat pump eventually wanting the same battery, a convention is not good enough - so precedence is now a first-class object with one rule and a printable explanation. THE RULE, in full: 1. The highest-priority `set` claim wins. If there is no set claim at all, the target is 0 W - fail toward inaction, never "hold the last value". 2. Every `limit` claim whose priority is >= the winning set's priority is then applied. Most restrictive wins. 3. Contradictory limits (lo > hi) are a BUG, not a tie to break: command 0 W and say so loudly. Clause 2 is the interesting one. It is what makes "money outranks maintenance" a consequence of the priorities instead of a special case somebody can forget: the maintenance charge-only limit binds the loop, but a higher-priority peak shaving claim simply is not bound by it. ⚠️ AND WHICH ACTUATOR IS A CLAIM ABOUT? THAT QUESTION HAS AN ANSWER AGAIN. specs.md §6.1 declared `actuator: str` as the first field of `Claim` and the implementation shipped without it, so every claim was implicitly about "the one and only actuator" and `resolve()` returned one scalar. ARB-03 restores the field, because §6.2 decided the site grid target is ALLOCATED across several inverters and never broadcast to each of them - and an allocator needs a seam to occupy that a single scalar does not have. So resolution is now THREE STAGES, and they are separate functions so that a test can construct a case at any one of them: 1. `pre_resolve()` - each inverter's OWN claims become an interval for that unit. One unit's claims, one unit's bounds. 2. `site_resolve()` - the SITE claims become one grid target S. This is the rule above, unchanged, and it is deliberately the same code it was: at N=1 there are no unit claims, so this stage sees the whole list and answers exactly what the shipped arbiter answered. 3. `allocate()` - THE SEAM. It turns S into per-inverter shares subject to stage 1's intervals. ⚠️ IT IS NOT AN ALLOCATOR AND MUST NOT BECOME ONE HERE - see its own docstring. ALLOC-01 builds it. ⚠️ THE STRUCTURAL PROPERTY, AND IT IS THE REASON FOR THE SPLIT. A per-inverter constraint is consumed by the allocator as an INTERVAL; it is never promoted into the site claim list. So a unit `hi` and a site `lo` are never terms of the same `lo > hi` test, and the contradiction clause below - which resolves to 0 W, a battery parked inside a billed quarter - cannot be reached across two inverters. That is DECISIONS/SAFETY-25-loop-soc-floor.md §0c, made mechanical: not "guarded against", NOT EXPRESSIBLE. Filing a unit constraint as a site claim to "keep it simple" is the whole bug, and `actuator_for()` is what stops a strategy doing it by hand. """ from dataclasses import dataclass, field from math import inf # Priorities live here and nowhere else. The moment these become magic numbers # scattered through the strategies, the whole point of this module is lost. P_SAFETY = 100 # stopped, inputs missing, shutting down, device limits P_MAINTENANCE = 60 # maintenance owns the actuator outright (drain, hold) P_PEAK = 50 # capacity-tariff peak shaving - costs real money P_MAINT_SHAPE = 40 # maintenance shaping the loop (charge-only) # OPT-04. §10.1 priority 3 - price arbitrage. ⚠️ ITS POSITION IS THE SPEC, NOT A # preference: P_PEAK (50) is ABOVE it so clause 2 lets the capacity-tariff floor # clamp an arbitrage charge, which is §9.1's "give peak shaving priority over # arbitrage whenever the two conflict" expressed as arithmetic rather than as a # rule somebody has to remember. P_MAINT_SHAPE (40) is above it so a speculative # spread cannot override the pack's balancing cycle. P_LOOP (10) is below it # because trading against the meter is the entire point - the grid-following # loop would otherwise cancel every charge the moment it created import. P_ARBITRAGE = 30 # price arbitrage - trades against the meter on purpose P_LOOP = 10 # ordinary grid-following SET = "set" LIMIT = "limit" # --- actuators, and the two scopes a claim can have ------------------------- # ⚠️ §6.2: THE GRID CONNECTION IS AN ACTUATOR TOO. It is the one every inverter # at the site shares, and two inverters regulating against one meter are two # writers on it - which is the failure this module exists to prevent, one level # up from the one it was built for. So it gets a name, and claims about it are # filed on that name rather than on nothing in particular. ACTUATOR_SITE = "site" SCOPE_SITE = "site" # about the grid connection: one of these per site SCOPE_UNIT = "unit" # about one pack, one inverter, one device # ⚠️ THE CLASSIFICATION, AND IT IS THE REAL OUTPUT OF ARB-03. Each entry is read # off what the claim is ABOUT at its construction site in main.py, not off which # module builds it. Getting an entry wrong is not cosmetic: a per-inverter # reserve filed as a site `hi` against the peak guard's site `lo` is `lo > hi`, # clause 3, 0 W - the battery parked in the billed quarter that SAFETY-25's memo # calls fatal. The reasoning is recorded here, at the line, because this table is # where a ninth source will be classified and the reasoning is what a future # reader needs in order to classify it correctly. CLAIM_SCOPE = { # --- SITE: about the grid connection --------------------------------- # main.py: `Claim.set("loop", P_LOOP, decision.target_w, ...)`. compute() # regulates `grid_w` - the P1 measurement - to zero. Its subject is the # meter, and §6.2's whole architecture is ONE integrator on P1 whose output # is then split. A site claim, and the one the split exists for. "loop": SCOPE_SITE, # main.py: `peakguard.claim(...)`. The quantity is the 15-minute average # OFFTAKE AT THE GRID CONNECTION, which is what the Belgian capacity tariff # bills. There is one quarter-hour peak per site, not one per pack. "peak": SCOPE_SITE, # main.py: `arbitrage.claim(...)`. It buys and sells at the grid against a # day-ahead price. The price is a property of the connection, and the energy # it trades crosses the meter. "arbitrage": SCOPE_SITE, # main.py: `Claim.set("safety", P_SAFETY, 0.0, "stopped" | "inputs missing")`. # ⚠️ READ BOTH CONSTRUCTION SITES BEFORE MOVING THIS ONE. Neither is about a # pack. "stopped" is the operator switching control off for the SITE, and # "inputs missing" is the SITE's own telemetry gone - the meter this whole # controller regulates against. Both must stop every inverter, and a site # SET at P_SAFETY is how that is said once rather than N times. "safety": SCOPE_SITE, # --- UNIT: about one pack, one inverter, one device ------------------- # main.py: `Claim.limit("device", P_SAFETY, self.dev_min, self.dev_max, # "rating")`. The numbers are read off ONE inverter's own reported min/max. # Another inverter has another rating; there is no site rating. "device": SCOPE_UNIT, # main.py: `Claim.limit("supervised", P_SAFETY, -max_w, max_w, "max_w")`. # `max_w` is the supervised cap on what this controller may WRITE to a # setpoint entity - §11.3's "the actuator is capped below the inverter # rating". It bounds a write to one device, like `device` does and for the # same reason, so it is scoped like `device`. "supervised": SCOPE_UNIT, # main.py: `Claim.set("failsafe", P_SAFETY, 0.0, "sign disagreement")`. # ⚠️ THE EVIDENCE IS SITE-WIDE AND THE REMEDY IS NOT, and that is why this # entry needs its reasoning written down. SAFETY-02 compares P1 - a site # measurement - against `standing`, THE COMMAND THIS CONTROLLER PUT ON THIS # ACTUATOR. What it concludes is "the unit I am driving is pushing power the # wrong way", and what it does is park that unit. At N>=2 the same evidence # cannot be attributed to a sibling nobody here commands, so a site-wide # remedy would be this watchdog stopping an inverter it never graded. "failsafe": SCOPE_UNIT, # main.py: `Claim.set("maintenance", P_MAINTENANCE, ...)` when the cycle owns # the setpoint, and `Claim.limit("maintenance", P_MAINT_SHAPE, hi=...)` when # it only shapes. §12's monthly recalibration is a PACK procedure - drain # this pack to its floor, charge this pack to full, recalibrate this pack's # coulomb counter. Two packs recalibrate on their own schedules. "maintenance": SCOPE_UNIT, } def actuator_for(source: str, unit: str, units=()) -> str: """Which actuator a claim from `source` belongs on, given the site's roster. ⚠️ ROUTE THROUGH THIS, DO NOT PASS `actuator=` BY HAND. An unclassified source raises `KeyError` here rather than defaulting to the site, which is the one direction that is not safe to default in: a per-inverter constraint that lands in the site claim list is exactly the `lo > hi` this card exists to make unreachable. A ninth claim source has to be classified in CLAIM_SCOPE before it can be filed, and test_peakguard.py part 10f is the other half of that - it goes red on the line the ninth append is written. ⚠️ AND AT N=1 EVERY SOURCE ROUTES TO THE SITE. That is not the classification being ignored, it is §6.2's identity: with one inverter the fabricated grid reading and the battery setpoint are the same number, so the grid connection and the only unit ARE the same actuator and there is nothing to allocate. Splitting the list at N=1 would be a behaviour change on a live safety path - the `failsafe` and `maintenance` SET claims would stop competing with the site's for the winner, `explain()` would name a different source, and `loop_is_following()` reads that name. The identity holds only at N=1, so this function is the ONE place that stops relying on it, the day the roster grows. """ if CLAIM_SCOPE[source] == SCOPE_SITE: return ACTUATOR_SITE return ACTUATOR_SITE if len(units) <= 1 else unit def scope_violations(claims) -> list: """Claims filed on an actuator their source's scope does not permit. A list of one-line complaints, empty when the routing is right. This is the check `actuator_for()` cannot make on its own, because a caller can always write `actuator=` by hand: it grades the claim list that actually reached the arbiter, whatever built it. """ out = [] # ⚠️ THE SECOND TEST IS CONDITIONAL ON THE SITE HAVING NAMED UNITS AT ALL, # and that is not laxity. At N=1 §6.2's identity holds and a per-inverter # source filed on the site is CORRECT - it is what `actuator_for()` returns. # The direction that produces `lo > hi` only exists once there is a second # actuator for the constraint to have belonged to. split = any(c.actuator != ACTUATOR_SITE for c in claims) for c in claims: scope = CLAIM_SCOPE.get(c.source) if scope is None: out.append(f"{c.source}: not classified in CLAIM_SCOPE") elif scope == SCOPE_SITE and c.actuator != ACTUATOR_SITE: out.append(f"{c.source}: a SITE claim filed on unit {c.actuator!r} - " f"it would bound one inverter's share instead of the grid") elif scope == SCOPE_UNIT and c.actuator == ACTUATOR_SITE and split: out.append(f"{c.source}: a UNIT claim filed on the site while the " f"site has named units - it can cross a site limit") return out @dataclass(frozen=True) class Claim: source: str priority: int kind: str = SET value: float = 0.0 # for SET lo: float = -inf # for LIMIT hi: float = inf # for LIMIT reason: str = "" # ⚠️ specs.md §6.1 DECLARES THIS FIELD FIRST AND IT IS LAST HERE, ON PURPOSE. # The spec's point is that a claim NAMES its actuator; the tuple position is # not the point, and it is load-bearing for two things that are. Every # construction in this repository passes `source` first, and # test_peakguard.py part 10f reads `Claim.set(...)`/`Claim.limit(...)`'s # FIRST POSITIONAL ARGUMENT off main.py's AST to pin the claim-source set - # the tripwire that guards SAFETY-25's deferred option. Moving `source` off # position 0 would silently blind that scan, which is this repository's named # failure mode. So the field is restored where it costs nothing. # # ⚠️ AND ITS DEFAULT IS THE SITE, EXPLICITLY. Not None, not "". A claim that # does not name an actuator is a claim about the grid connection and says so; # "unspecified" is what the shipped code already had, and it is what made # every claim implicitly about the one and only actuator. actuator: str = ACTUATOR_SITE @staticmethod def set(source: str, priority: int, value: float, reason: str = "", *, actuator: str = ACTUATOR_SITE) -> "Claim": return Claim(source, priority, SET, value=value, reason=reason, actuator=actuator) @staticmethod def limit(source: str, priority: int, lo: float = -inf, hi: float = inf, reason: str = "", *, actuator: str = ACTUATOR_SITE) -> "Claim": return Claim(source, priority, LIMIT, lo=lo, hi=hi, reason=reason, actuator=actuator) @dataclass(frozen=True) class UnitBounds: """What one inverter's OWN claims say about that inverter's share. STAGE 1's output, one per unit, and the thing ALLOC-01 consumes. It is an INTERVAL plus the two facts an allocator cannot reconstruct from an interval: * `pinned_w` - the value that unit's own winning SET asked for. A SET is not a bound: `resolve()` CLAMPS a set value into the limits rather than intersecting with it, and folding a 2500 W drain into `[2500, 2500]` would turn "clamped to the rating" into "contradicts the rating". So it travels beside the interval, not inside it. * `gate` - the priority of that winning SET, or None. Clause 2 applies a limit only at or above the winner's priority, and at N>=2 the winner may be a SITE set chosen at stage 2, i.e. AFTER this. Stage 1 states the constraint and records what it is gated on; deciding whether it applies is stage 3's business. Guessing here is how a maintenance charge-only `hi` would come to bind a peak discharge it does not outrank. `contradiction` is a unit contradicting ITSELF - its own `lo` above its own `hi`. It parks that unit and says so; it does not park the site, which is the entire difference this card is about. """ lo: float = -inf hi: float = inf lo_src: str | None = None hi_src: str | None = None gate: int | None = None pinned_w: float | None = None pinned_by: str | None = None contradiction: bool = False def explain(self) -> str: if self.contradiction: return (f"CONTRADICTION within the unit ({self.lo_src} lo=" f"{self.lo:.0f} > {self.hi_src} hi={self.hi:.0f})") span = (f"[{'-inf' if self.lo == -inf else format(self.lo, '.0f')}, " f"{'+inf' if self.hi == inf else format(self.hi, '.0f')}]") if self.pinned_by is not None: return f"{span} around {self.pinned_by} -> {self.pinned_w:.0f} W" return span @dataclass class Resolution: target_w: float winner: str # which source set the value bound_by: str | None = None # which limit actually changed it, if any contradiction: bool = False considered: list = field(default_factory=list) # --- the three-stage fields. ⚠️ APPENDED, AND DEFAULTED, ON PURPOSE: every # existing construction of this type is positional in its first five fields # and `target_w` still means exactly what it meant - the SITE grid target. # main.py assigns it to `self.target` unchanged. unit_bounds: dict = field(default_factory=dict) # stage 1, per actuator shares: dict = field(default_factory=dict) # stage 3, per actuator allocated: bool = True # False when stage 3 declined to split scope_errors: list = field(default_factory=list) # mis-routed claims def explain(self) -> str: """One line an operator can act on - this is the point of the module.""" if self.contradiction: return f"CONTRADICTION between limits - commanding 0 W ({self.winner})" if self.bound_by: return f"{self.winner} -> {self.target_w:.0f} W, limited by {self.bound_by}" return f"{self.winner} -> {self.target_w:.0f} W" def pre_resolve(unit_claims: list) -> UnitBounds: """STAGE 1. One inverter's own claims -> that inverter's interval. Clauses 1 and 2 of the rule, transposed: the unit's highest-priority SET names what the unit wants and gates which of the unit's limits apply, and the most restrictive of those limits gives the interval. Read UnitBounds on why the SET value is not folded into the interval. ⚠️ THE INPUT IS ONE UNIT'S CLAIMS AND NOTHING ELSE. A site claim reaching this function would become a bound on one inverter's share - the mirror image of the fault this card removes, and the reason `resolve()` partitions rather than filters twice. """ sets = sorted((c for c in unit_claims if c.kind == SET), key=lambda c: c.priority, reverse=True) gate = pinned_w = pinned_by = None if sets: gate, pinned_w, pinned_by = sets[0].priority, sets[0].value, sets[0].source lo, hi = -inf, inf lo_src = hi_src = None for c in unit_claims: if c.kind != LIMIT or (gate is not None and c.priority < gate): continue if c.lo > lo: lo, lo_src = c.lo, c.source if c.hi < hi: hi, hi_src = c.hi, c.source return UnitBounds(lo, hi, lo_src, hi_src, gate, pinned_w, pinned_by, contradiction=lo > hi) def allocate(target_w: float, bounds: dict) -> tuple: """STAGE 3. THE SEAM. Returns `(shares, allocated)`. ⚠️ THIS IS NOT THE ALLOCATOR AND MUST NOT BECOME ONE HERE. ALLOC-01 owns that, and §6.2 already fixed its shape: SUM-INVARIANT SHARE ALLOCATION - the shares sum to `target_w` exactly, each unit is told a function of its OWN share, and the weights are a comfort choice (SoC, thermals, wear) and explicitly not a tuning parameter, because the effective gain at the meter is then a convex combination of the per-unit gains for any split. What it does today, and why each half is what it is: * WITH AT MOST ONE UNIT there is nothing to divide. The share IS the site target, and that is not an approximation - it is §6.2's N=1 identity, the one that makes "the battery moves X W" and "the grid is at X W" the same sentence. Pass-through. * WITH TWO OR MORE UNITS IT DECLINES: no shares, `allocated=False`. ⚠️ THE OBVIOUS PLACEHOLDER - hand `target_w` to each unit - IS THE FAULT ARCH-01 WAS FILED ABOUT. Each inverter would supply it in full, the loop gain at the meter would be N times the per-unit gain, and at the gain config.yaml accepts as its documented maximum that is a permanent +-2 kW limit cycle with every watchdog in §11.2 reporting healthy. A placeholder that cannot be told apart from the real thing by any guard we have is worse than no placeholder, so this one refuses out loud instead. """ if len(bounds) <= 1: only = next(iter(bounds), ACTUATOR_SITE) return {only: float(target_w)}, True return {}, False def site_resolve(claims: list) -> Resolution: """STAGE 2. The SITE claims -> one grid target. ⚠️ THIS FUNCTION IS THE SHIPPED ARBITER, UNCHANGED. It is a separate name and the same code, deliberately: at N=1 nothing is filed on a unit, so `resolve()` hands it the whole claim list and it answers what it has always answered. Every check in test_arbiter.py, test_watchdog.py, test_validate.py and test_peakguard.py replays through here unedited, which is the proof that ARB-03 changed no behaviour on the live path. """ sets = sorted((c for c in claims if c.kind == SET), key=lambda c: c.priority, reverse=True) if sets: winner = sets[0] else: # No strategy asked for anything. That is not "carry on as before" - the # inverter holds its last command forever, so silence must mean zero. winner = Claim.set("failsafe", P_SAFETY, 0.0, "no claim was made") lo, hi = -inf, inf lo_src = hi_src = None for c in claims: if c.kind != LIMIT or c.priority < winner.priority: continue if c.lo > lo: lo, lo_src = c.lo, c if c.hi < hi: hi, hi_src = c.hi, c considered = [f"{c.source}:{c.kind}" for c in claims] if lo > hi: return Resolution(0.0, winner.source, bound_by=None, contradiction=True, considered=considered) target = max(lo, min(hi, winner.value)) bound_by = None if target != winner.value: binder = lo_src if target == lo else hi_src if binder is not None: bound_by = f"{binder.source}({binder.reason})" if binder.reason else binder.source return Resolution(float(target), winner.source, bound_by, False, considered) def resolve(claims: list, *, units=None) -> Resolution: """The three stages, in order, over one cycle's claims. `units` is the site's roster of inverters. Left None it is derived from the claims themselves, which is right for a caller that files a claim for every unit every cycle (main.py does - `supervised` is unconditional) and wrong for one that does not, so ALLOC-01 will pass the real roster rather than let a silent unit look like a smaller site. ⚠️ AND THE ARGUMENT HAS TO BE HONOURED, WHICH IS NOT THE SAME AS EXISTING. Ignore it - derive always - and a unit that filed nothing this cycle ceases to exist: a site of two reads as a site of one and stage 3 passes the whole grid target through to the inverter that spoke, which is ARCH-01's fault with its own evidence removed. That mutation survived the whole suite until test_arbiter.py part 7 graded it on a SILENT unit. ⚠️ THE PARTITION IS BY `actuator`, AND IT IS A PARTITION, NOT A FILTER. Every claim lands in exactly one stage. That is the whole structural argument: a unit's `hi` and the site's `lo` are never both terms of the same `lo > hi` test, so SAFETY-25 §0a's cross-inverter contradiction - 0 W inside the billed quarter - is not something to guard against, it is something that cannot be written down. """ site_claims = [c for c in claims if c.actuator == ACTUATOR_SITE] if units is None: units = {c.actuator for c in claims if c.actuator != ACTUATOR_SITE} units = tuple(sorted(units)) # STAGE 1 - each unit's own claims become that unit's interval. bounds = {u: pre_resolve([c for c in claims if c.actuator == u]) for u in units} # STAGE 2 - the site claims become the grid target. At N=1 `site_claims` IS # `claims`, so this is the shipped arbiter on the shipped list. out = site_resolve(site_claims) # STAGE 3 - the seam. out.shares, out.allocated = allocate(out.target_w, bounds) out.unit_bounds = bounds out.scope_errors = scope_violations(claims) return out