OPT-09: the weights parameter nothing ever passed, and what it cannot do

`allocator.plan()` has taken a `weights` argument since ALLOC-01 and NOTHING
had ever passed one - main.py called `resolve()` without it and the arbiter
defaulted it to 1.0 per unit - so the site target was split 50/50 regardless
of what either pack could do. Two things now feed it, and they are different
kinds of thing:

  * a `pack` UNIT claim at P_SAFETY that CLOSES a unit's envelope at its own
    `bms_soc_floor` or at 100 % - a PERMISSION, obeyed absolutely, so an empty
    pack is not asked to discharge and its share goes to the sibling;
  * SoC-aware weights by ENERGY headroom in kWh - a PREFERENCE, which
    `_fill()`'s last-resort pass will override the moment the sibling saturates.

Measured (test_packshare.py part 8): at a load one pack cannot cover, the
weighted arm and the shipped arm command the IDENTICAL watts into an empty pack
and deliver the IDENTICAL watts. Only the envelope stops the ask, and what it
buys is not delivery - it is a reported `unmet_w` where the record used to read
impeccable. Weights are a comfort choice for STABILITY and NOT for DELIVERY.

Also: an optional per-entry `capacity_kwh` (schema change, all-or-nothing across
the roster, rule 9 refuses a partial one); per-pack arbitrage sizing, with the
sell side's no-op stated rather than hidden; and a 0 W trade refused by name,
because a 0 W arbitrage claim is a park order that outranks the loop.

SAFETY-42 and this card meet at one hazard from opposite sides - OPT-09 stops
the site ASKING a pack whose SoC says it cannot deliver, SAFETY-42 alarms when a
pack that said it could does not - and its end-to-end fixture moved as a result.
Its finding is unchanged and is now stated on the two quantities its rejected
discriminator actually reads.

Not filed at all at a roster of one: at N=1 every source routes to the site, so
the interval would bound the SITE TARGET, and SAFETY-25's decided Option A
stands untouched on the live install.

⚠️ INVERTER B DOES NOT EXIST. Its 4600 W / 20.48 kWh / 10 % are FROM DATASHEET
AND SERIAL, and `sim/plantsim.py`'s INVERTER_B is inverter A copied
(`measured=False`), so every two-inverter figure here is arithmetic or two
copies of A. No hardware was touched.

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

goodwe_controller/DOCS.md

@@ -136,6 +136,7 @@ either direction, and the check is mutation-tested both ways.
 | `soc_entity` | yes | Battery state of charge — use the **ESP32's own read** |
 | `batt_entity` | yes | Battery power — again the ESP32's read, `+` = discharging |
 | `batt_invert` | | Flip if needed |
+| `capacity_kwh` | | This pack's usable capacity. Read only to divide the site target between packs by **energy** headroom — see below |
 | `setpoint_entity` | yes | The ESPHome `number.*_goodwe_setpoint_w` |
 
 Use the ESP32's readings rather than the inverter's cloud or dongle sensors:
@@ -161,11 +162,13 @@ inverters:
     soc_entity: sensor.goodwe_a_soc
     batt_entity: sensor.goodwe_a_battery_power
     max_w: 5000
+    capacity_kwh: 15.36
   - name: inverter-b
     setpoint_entity: number.goodwe_b_setpoint_w
     soc_entity: sensor.goodwe_b_soc
     batt_entity: sensor.goodwe_b_battery_power
     max_w: 4600
+    capacity_kwh: 20.48
 ```
 
 ⚠️ **The 4600 W is inverter B's *datasheet* figure, not a measured one.** B is a
@@ -229,6 +232,51 @@ in the log rather than silent, but it is an outage until someone puts the
 single-inverter entity back in that field. **Before downgrading, write down the
 `setpoint_entity` of the unit you want to keep running.**
 
+#### How the site target is divided between the packs (OPT-09)
+
+Two packs do not get half each. Since 0.7.x the split is driven by two separate
+things, and it is worth knowing which is which, because only one of them is a
+rule:
+
+* **The envelope — a permission.** A pack whose own state of charge is at or
+  under its own `bms_soc_floor` is **not asked to discharge**; a pack at 100 %
+  is **not asked to charge**. Its share goes to the sibling, inside that
+  sibling's own rating. This is absolute: the allocator cannot exceed it.
+* **The weights — a preference.** Between those limits, each pack is asked for
+  the fraction of the site target that matches its **energy headroom**: the kWh
+  it has above its own cut-out when the site is discharging, the kWh it has
+  below full when the site is charging. That is what `capacity_kwh` is for.
+
+⚠️ **`capacity_kwh` is optional, and it is all-or-nothing.** Leave it out
+everywhere and the add-on has no opinion about the split — the target is divided
+evenly, exactly as it was before. Fill it in on **every** entry or on none: a
+pack measured in kWh beside one that is not is not a comparison, and the add-on
+refuses to start rather than ignore half of what you typed.
+
+⚠️ **Why energy and not the rating.** The two packs here pull in opposite
+directions — A is 5000 W with 15.36 kWh, B is 4600 W with 20.48 kWh, so B has
+about a third more energy and about 8 % less power. Dividing by rating hands the
+work to A; dividing by energy hands it to B. The question a split is answering is
+"which pack can sustain its share for the hour", so it is the energy one. Each
+inverter's own rating still binds its own share, separately, through `max_w`.
+
+⚠️ **What the weights will NOT do for you, stated plainly.** They are a comfort
+choice about which pack does the work. They are **not** a way to make the site
+deliver. A unit that is at its energy limit — or that has simply stopped
+responding — does not hand its load to its sibling: the loop sees the shortfall,
+freezes, and the site runs short by that unit's share. Weighting a failing unit
+down does not fix that, because when the healthy unit reaches its own rating the
+allocator hands the remainder to the down-weighted one anyway rather than leave
+watts unplaced. What you get instead is honesty: the action log reports the watts
+that could not be placed (`ALLOCATOR: +2000 W of the site target could not be
+placed on any inverter`), and a unit that accepts its share and does not produce
+it is named by the delivery alarm (SAFETY-42, above).
+
+⚠️ **At one inverter none of this applies and nothing changed.** There is no
+split to weight, `capacity_kwh` is not read, and no envelope is closed —
+self-consumption still discharges down to the battery's own cut-out exactly as
+it always has.
+
 ### What appears in Home Assistant at two inverters
 
 **Nothing you already have changes.** The eight entities this add-on has always