ARB-03: restore Claim.actuator and make resolve() three-stage #40

Merged

admin merged 2 commits from ARB-03 into release/1.0

2026-09-02 04:16:45 +02:00

Author	SHA1	Message	Date
glenn schrooyenandClaude Opus 5	38f6680639	ARB-03: pin all eight actuator call sites statically checks / unit (pull_request) Successful in 3m45s Details The independent review of PR #40 found AC 6 met at three of the eight claim construction sites while the check claimed to cover the class - this repository's named failure mode, a check observing something other than what it claimed, reproduced inside the check written to prevent it. WHAT WAS WRONG. Part 10g's only call-site check was a real two-inverter cycle. That cycle is auto, P1-healthy, no maintenance procedure, no tripped sign watchdog, the guard idle and arbitrage off, so it reaches `device`, `supervised` and `loop` and nothing else - three of the eight direct appends in `Controller.cycle()`. Its own check text nevertheless read "the line a mis-typed `actuator_of(...)` at a call site goes red on", and the PR body's mutation table presented it as covering the class. The reviewer proved the gap on the shipped tree: `actuator_of("maintenance")` -> `actuator_of("peak")` at the maintenance-shaping append left test_arbiter.py, test_peakguard.py and test_arbitrage.py ALL GREEN, while at a roster of two it built a site loop of -1500 W against the guard's site `lo` of 1500 W and the now-misrouted charge-only `hi = 0` - `lo > hi`, arbiter clause 3, 0 W IN THE BILLED QUARTER, SAFETY-25 §0a's fatal case from a one-word typo. The same mutation at the `failsafe` append survived too. The runtime detector does fire - `scope_violations()` names it - but it only logs; nothing graded it. THE FIX, over machinery already present. Part 10f's AST scan already reads each `claims.append(...)` in `Controller.cycle()`. All eight direct appends expose their actuator statically as `actuator=self.actuator_of('<literal>')`, so 10g now requires that literal to EQUAL the source the claim is filed under, read as SOURCE TEXT rather than evaluated - `actuator_of("peak")` at the maintenance append is the same VALUE at the shipped roster of one and a different string here. That pins all eight routing sites, on the line the typo is written, in every configuration and at every roster, exactly the way 10f pins the source set. Two further lines keep the scan from going vacuous: every direct append must be readable in that shape (a computed or hand-written actuator fails there), and the ten appends must still account for 10f's eight sources. The two INDIRECT appends carry no `actuator=` at the call site to mis-type. `peak_claim` and `arb_claim` are routed where their claim is built, and are pinned there - `peakguard.claim()` by the SWEEP_SITE sweep over every load x elapsed x battery x SoC x floor combination, `arbitrage.claim()` by test_arbitrage.py. 10g now says so at the line, and says which three of the eight its dynamic cycle actually sees, rather than rounding up. MEASURED, NOT ARGUED. Each of the eight direct appends mutated in turn to a wrong actuator - device->loop, supervised->peak, failsafe->safety, safety(stopped)->device, safety(inputs missing)->maintenance, maintenance(SET)->loop, maintenance(shaping)->peak, loop->supervised - each on a purged tree via tools/mutation_run.sh over all 17 files. All eight RED, every one of them on the new line. TWO SURVIVING MUTATIONS OF THE SAME CLASS, ALSO CLOSED. * `resolve()` did not have to honour the roster it was given: `if units is None:` -> `if True:` left the whole suite green. Ignoring the argument makes a unit that filed nothing this cycle cease 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. test_arbiter.py part 7 now grades it on the one case that separates the two, a SILENT unit. Mutation RED in test_arbiter.py and test_peakguard.py. * main.py's N>=2 refusal was unreachable and ungraded: `if not resolution.allocated:` -> `if False:` left the whole suite green, so the right instinct was one refactor away from being deleted as dead code. The guard is KEPT - the alternative default is the ARCH-01 fault - and new part 10h grades it on the two-inverter cycle that already existed: the 0 W, the `failsafe` winner, the log line naming the roster size, and the write that follows. Mutation RED. AND THE WORDING CORRECTED. main.py does not "refuse to write" on `allocated=False`. It SUBSTITUTES a 0 W failsafe and then calls `write_setpoint(0.0)` like any other cycle. 0 W is the correct fail-toward-inaction direction and the log text is accurate about what it refuses - to BROADCAST the site target - but "refuses to write" overstates the code. Said as what it does, in the CHANGELOG, at the branch in main.py, and in 10h's own check text. `resolve()`'s docstring now says the roster argument has to be HONOURED, which is not the same as existing. 17/17 green on a purged tree. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>	2026-09-02 03:46:40 +02:00
adminandClaude Opus 5	06f95e0a64	ARB-03: restore Claim.actuator and make resolve() three-stage checks / unit (pull_request) Successful in 3m45s Details specs.md:467 declares `actuator: str` as the FIRST field of `Claim`. app/arbiter.py:55 had no such field. The specification designed per-actuator claims and the implementation dropped it, so every claim was implicitly about "the one and only actuator", resolve() returned one scalar Resolution.target_w, and main.py assigned it to one self.target. THERE WAS NO SEAM AN ALLOCATOR COULD OCCUPY - and ARCH-01 (specs.md §6.2, 2026-09-02) decided the site grid target is ALLOCATED across several inverters and never broadcast. This is a regression fix against the written design; creating that seam is the whole of the change. WHY IT MATTERS, IN THE UNITS THE SYSTEM IS BILLED IN. The control primitive is meter emulation: the master reports a fabricated grid reading and the inverter regulates itself to it, so one number means "the battery moves X W" to the add-on and "the grid is at X W" to the inverter - an identity that holds only at N=1. Broadcast one target to two inverters and each supplies it in full; the loop gain at the meter becomes N times the per-unit gain, which at the gain config.yaml:374 accepts is a permanent limit cycle with every watchdog in §11.2 reporting healthy. And a per-inverter reserve filed as a site `hi` against the peak guard's site `lo` is `lo > hi`, arbiter clause 3, 0 W IN THE BILLED QUARTER - the parked battery SAFETY-25's memo calls fatal. THE SPLIT, VERIFIED AT EACH CONSTRUCTION SITE RATHER THAN ACCEPTED FROM THE SURVEY. Four sources are about the GRID CONNECTION and are SITE claims: `loop` (compute() regulates grid_w, the P1 measurement, and §6.2's whole architecture is one integrator on P1 whose output is then split), `peak` (the 15-minute average offtake AT the grid connection, which is what the capacity tariff bills - one quarter-hour peak per site, not one per pack), `arbitrage` (buys and sells at the grid against a day-ahead price; the price is a property of the connection and the energy crosses the meter) and `safety` (both construction sites read: "stopped" is the operator switching control off for the site, "inputs missing" is the site's own meter gone - neither is about a pack, and both must stop every inverter). Four are about a pack, a device or one write and are PER-INVERTER: `device` (one inverter's own reported min/max - there is no site rating), `supervised` (max_w caps what may be WRITTEN to one setpoint entity, §11.3, so it is scoped like `device` for the same reason), `maintenance` (§12's recalibration is a pack procedure - drain THIS pack, charge THIS pack, recalibrate THIS pack's counter) and `failsafe`. `failsafe` is the entry that needed the reading rather than the survey: SAFETY-02's EVIDENCE is site-wide (it compares P1 against the standing command) but its CONCLUSION is "the unit I am driving is pushing power the wrong way" and its remedy is to park that unit. At N>=2 the same evidence cannot be attributed to a sibling this controller never commanded, so a site-wide stop would park an inverter this watchdog never graded. The reasoning for all eight is recorded AT THE LINE, in arbiter.CLAIM_SCOPE and again at each claims.append in main.py. WHAT WAS BUILT. resolve() is three stages, each a separate function so a test can construct a case at any one of them: pre_resolve() - one inverter's own claims -> that unit's interval. Clauses 1 and 2 transposed: the unit's own winning SET gates its own limits. The SET's value travels BESIDE the interval, not inside it - folding a -2500 W drain into [-2500, -2500] would turn "clamped to max_w" into "contradicts max_w", a different and wrong answer. site_resolve() - THE SHIPPED ARBITER, UNCHANGED. Same code, new name. allocate() - THE SEAM, AND DELIBERATELY NOT AN ALLOCATOR. ALLOC-01 builds it. At N<=1 it passes the target through (§6.2's identity). At N>=2 it DECLINES - no shares, allocated=False - and main.py refuses to write rather than broadcast, because the obvious placeholder (hand the target to each) is the fault ARCH-01 was filed about and no guard we have can tell it apart from the real thing. THE CONTRADICTION IS NOT GUARDED AGAINST, IT CANNOT BE WRITTEN DOWN. The partition is by `actuator` and it is a partition: a unit's `hi` and the site's `lo` are never both terms of one `lo > hi` test. Constructed and swept - 40 filings (every per-inverter source x unit x bound, including a unit contradicting ITSELF at lo 900 > hi 100) against a live site floor, and not one moves the site target or raises a contradiction. A unit's own impossible pair parks that unit and says so on its own bounds; it does not park the site. That is SAFETY-25 §0c's table made mechanical. AT N=1 THIS IS A PURE REFACTOR, AND THAT IS PROVEN RATHER THAN ASSERTED. With one inverter the fabricated grid reading and the battery setpoint are the same number, so the grid connection and the only unit ARE one actuator: actuator_for() routes every source to the site, no claim is filed on a unit, stage 2 sees the whole list and answers what the shipped arbiter answered. All 17 suites replay UNEDITED above the ARB-03 sections and are green on the same numbers; test_arbiter.py additionally runs 13 claim lists through both resolve() and site_resolve() and compares target, winner, binder, contradiction flag, the considered list and the operator line. EVIDENCE, BY BREAKING EACH THING (tools/mutation_run.sh, purged tree): * Claim's dataclass default emptied -> RED (test_arbiter) ...and it survived until the check was added: the two helpers pass their own default down, so the FIELD's default never ran. Now checked directly. * `peak` reclassified SCOPE_UNIT -> RED (arbiter x4, peakguard x2) * `maintenance` reclassified SCOPE_SITE -> RED (arbiter x4, peakguard) * the N=1 identity dropped in actuator_for() -> RED (arbiter, peakguard incl. the maintenance/peak suppression checks, freeze) - which is the measurement that says splitting at N=1 would be a behaviour change * resolve() stops partitioning -> RED (arbiter x4) * allocate() broadcasts at N>=2 -> RED (arbiter x2) * stage 1 drops clause-2 gating -> RED (arbiter) * a call site routes `device` through `loop` -> RED (peakguard 10g) * SAFETY-25 Option B built as a ninth source -> RED (peakguard 10f, both halves, plus 10g) - the tripwire still bites SAFETY-24's asymmetry proof is re-run and holds: 0 negative floors over the shipped sweep, `hi` still +inf on every claim the guard files, and it now also asserts every one of them is on the SITE actuator - a floor bound to one inverter's share would leave the site, the thing the capacity tariff meters, with no floor at all. test_peakguard.py part 10f is kept, not adapted around. `source` is still Claim.set()'s first positional argument precisely so its AST scan keeps reading it, which is why `actuator` is the LAST field of Claim and not the first - moving `source` off position 0 would silently blind the tripwire that guards SAFETY-25's deferred option. The one adaptation is `**kw` on its spy, so main.py's roster passes through unread rather than being silently dropped. New part 10g pins CLAIM_SCOPE to the same eight-source set and grades a REAL two-inverter cycle, which is the only place a mis-typed actuator_of(...) at a call site is observable - at N=1 every source legitimately routes to the site, so a swap there is invisible by construction. No config key, no option, no operator surface, no default moved. Inverter B does not exist yet and nothing here measures it. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01BwRLw7eKYj2byVdwB6kbjU	2026-09-02 01:54:29 +02:00

Author

SHA1

Message

Date

glenn schrooyenandClaude Opus 5

38f6680639

ARB-03: pin all eight actuator call sites statically

checks / unit (pull_request) Successful in 3m45s

Details

The independent review of PR #40 found AC 6 met at three of the eight claim
construction sites while the check claimed to cover the class - this
repository's named failure mode, a check observing something other than what
it claimed, reproduced inside the check written to prevent it.

WHAT WAS WRONG. Part 10g's only call-site check was a real two-inverter cycle.
That cycle is auto, P1-healthy, no maintenance procedure, no tripped sign
watchdog, the guard idle and arbitrage off, so it reaches `device`,
`supervised` and `loop` and nothing else - three of the eight direct appends in
`Controller.cycle()`. Its own check text nevertheless read "the line a
mis-typed `actuator_of(...)` at a call site goes red on", and the PR body's
mutation table presented it as covering the class. The reviewer proved the gap
on the shipped tree: `actuator_of("maintenance")` -> `actuator_of("peak")` at
the maintenance-shaping append left test_arbiter.py, test_peakguard.py and
test_arbitrage.py ALL GREEN, while at a roster of two it built a site loop of
-1500 W against the guard's site `lo` of 1500 W and the now-misrouted
charge-only `hi = 0` - `lo > hi`, arbiter clause 3, 0 W IN THE BILLED QUARTER,
SAFETY-25 §0a's fatal case from a one-word typo. The same mutation at the
`failsafe` append survived too. The runtime detector does fire -
`scope_violations()` names it - but it only logs; nothing graded it.

THE FIX, over machinery already present. Part 10f's AST scan already reads each
`claims.append(...)` in `Controller.cycle()`. All eight direct appends expose
their actuator statically as `actuator=self.actuator_of('<literal>')`, so 10g
now requires that literal to EQUAL the source the claim is filed under, read as
SOURCE TEXT rather than evaluated - `actuator_of("peak")` at the maintenance
append is the same VALUE at the shipped roster of one and a different string
here. That pins all eight routing sites, on the line the typo is written, in
every configuration and at every roster, exactly the way 10f pins the source
set. Two further lines keep the scan from going vacuous: every direct append
must be readable in that shape (a computed or hand-written actuator fails
there), and the ten appends must still account for 10f's eight sources.

The two INDIRECT appends carry no `actuator=` at the call site to mis-type.
`peak_claim` and `arb_claim` are routed where their claim is built, and are
pinned there - `peakguard.claim()` by the SWEEP_SITE sweep over every load x
elapsed x battery x SoC x floor combination, `arbitrage.claim()` by
test_arbitrage.py. 10g now says so at the line, and says which three of the
eight its dynamic cycle actually sees, rather than rounding up.

MEASURED, NOT ARGUED. Each of the eight direct appends mutated in turn to a
wrong actuator - device->loop, supervised->peak, failsafe->safety,
safety(stopped)->device, safety(inputs missing)->maintenance,
maintenance(SET)->loop, maintenance(shaping)->peak, loop->supervised - each on
a purged tree via tools/mutation_run.sh over all 17 files. All eight RED, every
one of them on the new line.

TWO SURVIVING MUTATIONS OF THE SAME CLASS, ALSO CLOSED.

* `resolve()` did not have to honour the roster it was given: `if units is
  None:` -> `if True:` left the whole suite green. Ignoring the argument makes a
  unit that filed nothing this cycle cease 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.
  test_arbiter.py part 7 now grades it on the one case that separates the two, a
  SILENT unit. Mutation RED in test_arbiter.py and test_peakguard.py.
* main.py's N>=2 refusal was unreachable and ungraded: `if not
  resolution.allocated:` -> `if False:` left the whole suite green, so the right
  instinct was one refactor away from being deleted as dead code. The guard is
  KEPT - the alternative default is the ARCH-01 fault - and new part 10h grades
  it on the two-inverter cycle that already existed: the 0 W, the `failsafe`
  winner, the log line naming the roster size, and the write that follows.
  Mutation RED.

AND THE WORDING CORRECTED. main.py does not "refuse to write" on
`allocated=False`. It SUBSTITUTES a 0 W failsafe and then calls
`write_setpoint(0.0)` like any other cycle. 0 W is the correct
fail-toward-inaction direction and the log text is accurate about what it
refuses - to BROADCAST the site target - but "refuses to write" overstates the
code. Said as what it does, in the CHANGELOG, at the branch in main.py, and in
10h's own check text. `resolve()`'s docstring now says the roster argument has
to be HONOURED, which is not the same as existing.

17/17 green on a purged tree.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

2026-09-02 03:46:40 +02:00

adminandClaude Opus 5

06f95e0a64

ARB-03: restore Claim.actuator and make resolve() three-stage

checks / unit (pull_request) Successful in 3m45s

Details

specs.md:467 declares `actuator: str` as the FIRST field of `Claim`.
app/arbiter.py:55 had no such field. The specification designed
per-actuator claims and the implementation dropped it, so every claim was
implicitly about "the one and only actuator", resolve() returned one scalar
Resolution.target_w, and main.py assigned it to one self.target. THERE WAS
NO SEAM AN ALLOCATOR COULD OCCUPY - and ARCH-01 (specs.md §6.2, 2026-09-02)
decided the site grid target is ALLOCATED across several inverters and never
broadcast. This is a regression fix against the written design; creating that
seam is the whole of the change.

WHY IT MATTERS, IN THE UNITS THE SYSTEM IS BILLED IN. The control primitive
is meter emulation: the master reports a fabricated grid reading and the
inverter regulates itself to it, so one number means "the battery moves X W"
to the add-on and "the grid is at X W" to the inverter - an identity that
holds only at N=1. Broadcast one target to two inverters and each supplies it
in full; the loop gain at the meter becomes N times the per-unit gain, which
at the gain config.yaml:374 accepts is a permanent limit cycle with every
watchdog in §11.2 reporting healthy. And a per-inverter reserve filed as a
site `hi` against the peak guard's site `lo` is `lo > hi`, arbiter clause 3,
0 W IN THE BILLED QUARTER - the parked battery SAFETY-25's memo calls fatal.

THE SPLIT, VERIFIED AT EACH CONSTRUCTION SITE RATHER THAN ACCEPTED FROM THE
SURVEY. Four sources are about the GRID CONNECTION and are SITE claims:
`loop` (compute() regulates grid_w, the P1 measurement, and §6.2's whole
architecture is one integrator on P1 whose output is then split), `peak` (the
15-minute average offtake AT the grid connection, which is what the capacity
tariff bills - one quarter-hour peak per site, not one per pack),
`arbitrage` (buys and sells at the grid against a day-ahead price; the price
is a property of the connection and the energy crosses the meter) and
`safety` (both construction sites read: "stopped" is the operator switching
control off for the site, "inputs missing" is the site's own meter gone -
neither is about a pack, and both must stop every inverter).

Four are about a pack, a device or one write and are PER-INVERTER: `device`
(one inverter's own reported min/max - there is no site rating),
`supervised` (max_w caps what may be WRITTEN to one setpoint entity, §11.3,
so it is scoped like `device` for the same reason), `maintenance` (§12's
recalibration is a pack procedure - drain THIS pack, charge THIS pack,
recalibrate THIS pack's counter) and `failsafe`. `failsafe` is the entry that
needed the reading rather than the survey: SAFETY-02's EVIDENCE is site-wide
(it compares P1 against the standing command) but its CONCLUSION is
"the unit I am driving is pushing power the wrong way" and its remedy is to
park that unit. At N>=2 the same evidence cannot be attributed to a sibling
this controller never commanded, so a site-wide stop would park an inverter
this watchdog never graded. The reasoning for all eight is recorded AT THE
LINE, in arbiter.CLAIM_SCOPE and again at each claims.append in main.py.

WHAT WAS BUILT. resolve() is three stages, each a separate function so a test
can construct a case at any one of them:

  pre_resolve()  - one inverter's own claims -> that unit's interval. Clauses
                   1 and 2 transposed: the unit's own winning SET gates its
                   own limits. The SET's value travels BESIDE the interval,
                   not inside it - folding a -2500 W drain into
                   [-2500, -2500] would turn "clamped to max_w" into
                   "contradicts max_w", a different and wrong answer.
  site_resolve() - THE SHIPPED ARBITER, UNCHANGED. Same code, new name.
  allocate()     - THE SEAM, AND DELIBERATELY NOT AN ALLOCATOR. ALLOC-01
                   builds it. At N<=1 it passes the target through (§6.2's
                   identity). At N>=2 it DECLINES - no shares,
                   allocated=False - and main.py refuses to write rather than
                   broadcast, because the obvious placeholder (hand the target
                   to each) is the fault ARCH-01 was filed about and no guard
                   we have can tell it apart from the real thing.

THE CONTRADICTION IS NOT GUARDED AGAINST, IT CANNOT BE WRITTEN DOWN. The
partition is by `actuator` and it is a partition: a unit's `hi` and the site's
`lo` are never both terms of one `lo > hi` test. Constructed and swept - 40
filings (every per-inverter source x unit x bound, including a unit
contradicting ITSELF at lo 900 > hi 100) against a live site floor, and not
one moves the site target or raises a contradiction. A unit's own impossible
pair parks that unit and says so on its own bounds; it does not park the site.
That is SAFETY-25 §0c's table made mechanical.

AT N=1 THIS IS A PURE REFACTOR, AND THAT IS PROVEN RATHER THAN ASSERTED. With
one inverter the fabricated grid reading and the battery setpoint are the same
number, so the grid connection and the only unit ARE one actuator:
actuator_for() routes every source to the site, no claim is filed on a unit,
stage 2 sees the whole list and answers what the shipped arbiter answered.
All 17 suites replay UNEDITED above the ARB-03 sections and are green on the
same numbers; test_arbiter.py additionally runs 13 claim lists through both
resolve() and site_resolve() and compares target, winner, binder,
contradiction flag, the considered list and the operator line.

EVIDENCE, BY BREAKING EACH THING (tools/mutation_run.sh, purged tree):
  * Claim's dataclass default emptied            -> RED (test_arbiter)
    ...and it survived until the check was added: the two helpers pass their
    own default down, so the FIELD's default never ran. Now checked directly.
  * `peak` reclassified SCOPE_UNIT               -> RED (arbiter x4, peakguard x2)
  * `maintenance` reclassified SCOPE_SITE        -> RED (arbiter x4, peakguard)
  * the N=1 identity dropped in actuator_for()   -> RED (arbiter, peakguard
    incl. the maintenance/peak suppression checks, freeze) - which is the
    measurement that says splitting at N=1 would be a behaviour change
  * resolve() stops partitioning                 -> RED (arbiter x4)
  * allocate() broadcasts at N>=2                -> RED (arbiter x2)
  * stage 1 drops clause-2 gating                -> RED (arbiter)
  * a call site routes `device` through `loop`   -> RED (peakguard 10g)
  * SAFETY-25 Option B built as a ninth source   -> RED (peakguard 10f, both
    halves, plus 10g) - the tripwire still bites

SAFETY-24's asymmetry proof is re-run and holds: 0 negative floors over the
shipped sweep, `hi` still +inf on every claim the guard files, and it now also
asserts every one of them is on the SITE actuator - a floor bound to one
inverter's share would leave the site, the thing the capacity tariff meters,
with no floor at all.

test_peakguard.py part 10f is kept, not adapted around. `source` is still
Claim.set()'s first positional argument precisely so its AST scan keeps
reading it, which is why `actuator` is the LAST field of Claim and not the
first - moving `source` off position 0 would silently blind the tripwire that
guards SAFETY-25's deferred option. The one adaptation is `**kw` on its spy,
so main.py's roster passes through unread rather than being silently dropped.
New part 10g pins CLAIM_SCOPE to the same eight-source set and grades a REAL
two-inverter cycle, which is the only place a mis-typed actuator_of(...) at a
call site is observable - at N=1 every source legitimately routes to the site,
so a swap there is invisible by construction.

No config key, no option, no operator surface, no default moved. Inverter B
does not exist yet and nothing here measures it.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BwRLw7eKYj2byVdwB6kbjU

2026-09-02 01:54:29 +02:00