ALLOC-01: allocate the site grid target, sum-invariant, never broadcast

ARB-03 left `allocate()` as a documented seam that passed through at N<=1 and
DECLINED at N>=2, with the reasoning recorded at the line: the obvious
placeholder - hand the site target to each inverter - IS the ARCH-01 fault, and
"a placeholder that cannot be told apart from the real thing by any guard we
have is worse than no placeholder". This fills the seam.

WHY A BROADCAST IS A FAULT AND NOT AN INEFFICIENCY. 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 this
add-on and "the grid is at X W" to the inverter - an identity that holds only at
N=1. Hand two inverters the same target and each supplies it IN FULL, so the
loop gain at the meter becomes N times the per-unit gain. Reproduced on
admin/goodwe's two-master rig against this tree: -400 W export overshoot at
gain 0.6, and at gain 1.0 - which config.yaml accepts as its documented maximum
- a permanent 4000 W peak-to-peak limit cycle, commands alternating
1000/2000/1000/0 W, with NOT ONE GUARD FIRING. The sign watchdog is evaluated on
every cycle and never trips, because the disagreement flips on alternate ticks
and never holds its 180 s window.

WHAT WAS BUILT. `app/allocator.py`, host-side and strictly above the driver
seam. It consumes intervals and a number and nothing else - no claims, no
priorities, and no measurement, because an allocator that read P1 would be a
SECOND integrator on the site measurement.

  * ENVELOPE CLAMP, from ARB-03 stage 1's `UnitBounds`, read PER TICK. `plan()`
    is a pure function and the module holds no state, so there is nowhere for a
    construction-time envelope to be cached.
  * WATER-FILL by weight, with the surplus of a full unit moving to the others.
    Weights express PREFERENCE, envelopes express PERMISSION: a zero weight is
    honoured while another unit has headroom and overridden when it does not,
    because the SUM is the safety property and stranding capacity behind a
    comfort choice manufactures a standing error at the meter.
  * LARGEST-REMAINDER ROUNDING. The target is rounded ONCE, at the top; every
    sum below that line is integer arithmetic, so it cannot drift. Measured: a
    per-unit round() drifts -125 W over 50 000 ticks at three inverters.
  * THE ALLOCATION RECORD, with `unmet_w`, `dropped` and a per-unit reason.
    `ok` is one boolean for SAFETY-28 to gate on, and `unmet_w` is deliberately
    NOT fused into it - a saturated inverter must not park the whole site.

THE STABILITY PROPERTY IS STRUCTURAL. With sum(a_i) = 1 the gain at the meter is
sum(a_i * g_i), a convex combination of the per-unit gains, so it lies in
[min g_i, max g_i] FOR ANY SPLIT. That is what makes the weights a comfort
choice rather than a tuning parameter, and it is why a bad split cannot
destabilise the site. Graded directly, and measured end to end: 90/10, 50/50 and
100/0 give a bit-identical aggregate trace at the meter, and a gain sweep to 1.0
at every split has a flat tail at all 84 combinations.

THE TWO REFUSALS main.py NOW MAKES, AND WHY THERE ARE TWO. `allocated=False` no
longer means "no allocator"; it means no safe split EXISTS - a mis-routed claim,
an empty envelope set, or a split that could only be made by commanding one pack
to charge while another discharges. Separately, and this guard is the price of
making allocate() succeed rather than something inherited, main.py refuses to
act on a valid split it cannot DELIVER: there is one `setpoint_entity`, so
writing the site target to the one inverter it can reach would over-command that
inverter by exactly the other's share. Commanding a partial site is a worse
instruction than commanding nothing. DEV-02 gives it the second writer.

scope_violations() IS NOW CONSUMED, AND AS A REFUSAL. ARB-03 left it logging
without changing the resolution. A mis-routed claim means the number about to be
divided may itself be wrong, and dividing a number that may be wrong is worse
than not dividing it - the same answer clause 3 already gives a contradiction.
It is NOT promoted into an envelope: a unit-scoped claim that landed on the site
names no unit, so promoting it would mean guessing one, or applying one
inverter's rating to a sibling that does not have it.

AT N<=1 IT IS A PASS-THROUGH, BYTE-IDENTICAL: the share is the site target, as a
float, unrounded and unclamped. All 17 existing suites replay unedited.

test_peakguard.py part 10h and test_arbiter.py part 7 were RE-AIMED, not
deleted. PR #40's reviewer proved that refusal branch was unreachable and
untested once; removing its trigger without giving it a new one would have
rebuilt the hole. Part 10h now drives three real cycles - a deliverable split, a
dead sibling, and every master stale - and grades all three.

KNOWN AND NOT CLOSED HERE: at a roster of two the loop's `actual_w` is one
inverter's power used as a site measurement, because the add-on binds a single
`inverter_power` sensor. That is the SENSING half of the same N=1 identity this
card removes from the COMMANDING half, and it makes the aggregate trace
split-dependent below gain 1.0. Measured with its counterfactual in test_alloc.py
part 8 and tools/alloc_sim.py --splits. It belongs to DEV-02.

Verified: all 18 suites green in the CI image. 16 mutations run through
tools/mutation_run.sh on a purged tree; 13 red, and the 3 survivors are recorded
in test_alloc.py part 12 with the reason each cannot be caught.

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

goodwe_controller/test_clamp.py

@@ -65,6 +65,7 @@ Read MUTATION.md before you report a survivor.
 """
 
 import asyncio
+import io
 import math
 import sys
 from datetime import datetime, timedelta, timezone
@@ -73,6 +74,7 @@ from app.clamp import (
     CLEAR_CYCLES, REASON_CODE, REASSERT_S, ClampWatchdog, clamp_to_rating,
     is_commandable,
 )
+from app.arbiter import UnitBounds, allocate
 from app.control import Tuning, compute
 from app.main import Controller
 
@@ -558,6 +560,56 @@ check("an in-range value is untouched", hass_d.writes[3] == 1500.0)
 check("every emitted frame satisfies |emitted| <= the rating",
       all(abs(w) <= 2000.0 for w in hass_d.writes))
 
+# --- 5b. ALLOC-01: AND THE ALLOCATOR DID NOT ADD ONE ------------------------
+# ⚠️ "NO PATH REACHES THE WIRE AROUND THE CLAMP" IS A CLAIM ABOUT THE WHOLE
+# ADD-ON, so it has to be re-made every time a module learns to produce a number
+# that looks like a setpoint. ALLOC-01 added `app/allocator.py`, whose output is
+# a dict of per-inverter watts - numbers that are exactly the shape of a thing
+# somebody would write - and the temptation it creates is real: a second writer
+# for a second inverter is DEV-02's card, and the wrong way to build it is a
+# `set_number` call next to the allocation.
+#
+# Two checks, and neither is about the allocator's arithmetic:
+#   * it CANNOT write, and that is established from its imports rather than
+#     from its behaviour, because a behavioural check only sees the paths a
+#     fixture happens to take;
+#   * at the shipped roster the number that reaches the wire is still the
+#     arbiter's `target_w`, unclamped by the allocator, so SAFETY-03's clamp is
+#     still the binding one and not a second opinion after a first clamp.
+import app.allocator as _alloc_mod                                # noqa: E402
+
+_alloc_src = io.open(_alloc_mod.__file__, encoding="utf-8").read()
+_alloc_imports = sorted(
+    n.split(".")[0]
+    for line in _alloc_src.splitlines() if line.startswith(("import ", "from "))
+    for n in [line.split()[1]])
+print(f"    app/allocator.py imports: {_alloc_imports}")
+check("the allocator imports NOTHING that can reach the wire - no `hass`, no "
+      "`aiohttp`, not even `main`. It is a pure function of intervals and a "
+      "number, so 'it cannot write' is a property of the file rather than of "
+      "the paths a fixture happened to take",
+      _alloc_imports == ["dataclasses", "math"])
+check("...and it never mentions the setpoint entity, `set_number`, or the "
+      "clamp - the three names any bypass would have to spell",
+      not any(n in _alloc_src for n in ("set_number", "setpoint_entity",
+                                        "clamp_to_rating")))
+check("...and it must not: it has no measurement either. The allocator reading "
+      "P1 would be a SECOND integrator on the site measurement, which is the "
+      "same two-writers failure one level up",
+      not any(n in _alloc_src for n in ("p1", "P1Ingest", "grid_w")))
+
+check("at the shipped roster of ONE the allocator is a pass-through, so the "
+      "number handed to write_setpoint() is the arbiter's own target and "
+      "SAFETY-03's clamp is still the FIRST and only clamp it meets. An "
+      "allocator that pre-clamped here would leave this file grading a value "
+      "that was already in range, and the clamp untested on the live path",
+      allocate(9999.0, {"inverter-a": UnitBounds()}) == ({"inverter-a": 9999.0},
+                                                        True))
+check("...and that unclamped 9999 W is exactly what part 5 above just proved "
+      "the write path stops at the rating. The two halves meet here: the "
+      "allocator does not clamp, the wire does",
+      hass_d.writes[0] == 2000.0)
+
 # ==============================================================================
 print()
 print("6. TEST-11: the guard's evidence is THIS cycle's write, not the last one")