SAFETY-28: gate the write path on the allocation record, not on key count

specs §1.5 makes "any configuration in which two writers can reach one
actuator" a non-goal. That non-goal was enforced by counting config keys:
validate.py's ACTUATOR_WRITE_KEYS = ("setpoint_entity",), consumed at rule 1,
with a comment stating the guarantee outright - "there is exactly one such
key, so a second writer is not expressible in the options schema at all".

That was true and it graded THE SHAPE OF THE OPTIONS SCHEMA, not the writes.
Add CFG-04's per-inverter config - a roster of inverters each with its own
setpoint_entity - and there are two real writers with len() of that tuple
still equal to 1. The check stays green while the property it protects is
gone. sim/inject.py's two_writers scenario asserted on the same tuple, so it
went green too. That is this repository's named failure mode: a check that
observes something other than what it claims to observe.

Demonstrated rather than argued. test_validate.py part 2 now constructs the
hazardous per-inverter config, asserts that the OLD proxy is still green on
it, and then asserts the new check refuses it. Against release/1.0's
validator the updated sim scenario reports: "validate_startup_config()
ACCEPTED a configuration in which 3 declarations reach the ONE actuator
number.goodwe_setpoint ... the old proxy reports 1 write key(s) on this same
config and is therefore GREEN on it".

THE WRITE PATH IS NOW GATED ON THE RECORD
=========================================
Controller.write_refusal() asks Allocation.authorises() whether the single
allocator placed exactly this number, for this unit, on this tick.
write_setpoint() refuses anything else. A second writer with arithmetic of
its own cannot satisfy that - its number appears in no record - so it has to
file a Claim and go through resolve(), which is the one allocator. "Exactly
one allocator per shared resource" stops being a convention somebody can
forget and becomes something the write path checks.

The refusal is a SUBSTITUTION, not a return: 0 W goes on the wire in place of
the number nothing stands behind. Returning would leave the inverter latched
on its last command with the ESP32 heartbeat still being fed - holding an
unauthorised setpoint quietly, which is the outcome the gate exists to stop.
AC 1 is "refused at the write path, not merely logged", and test_clamp.py
part 7a grades the device's writes, not the log.

The gate sits BELOW the non-finite coercion and ABOVE the clamp. Below,
because a nan is loss of input and rule 1 has already turned it into 0 W.
Above, because the question is who chose this number, and the answer is only
meaningful about the number that was asked for - gating the CLAMPED value
would refuse exactly the cycles SAFETY-03 exists for, since a clamped write
differs from the allocator's share by construction. Mutation M7 moves the
gate below the clamp and turns nine checks red, part 6c among them.

A STALE RECORD CANNOT BE REPLAYED
=================================
Every Allocation now carries the `tick` it was made for. It is handed IN by
the caller - plan(..., tick=) - rather than counted inside the allocator,
because test_alloc.py part 10 grades that the module holds no state at all,
and a serial number incremented in there would be the cached-across-ticks
thing the envelope rule forbids wearing a different hat.

Controller.alloc_tick advances ONCE PER RESOLUTION, not once per loop
iteration, and both halves are load-bearing:

  * a new allocation makes the previous record stale immediately, so a record
    whose envelopes have moved cannot authorise a write. That is the replay
    half (AC 2), graded by capturing a real record, running another real
    cycle, putting the old one back and observing refusal.
  * the "inputs missing, not yet stale" hold returns BEFORE the allocator
    runs, exactly so one dropped meter reading does not zero the inverter,
    and the heartbeat re-affirms self.target through this same gate while it
    does. A tick incremented per loop iteration would refuse that heartbeat
    and turn the hold into the outage it exists to prevent. Graded.

An UNSTAMPED record (tick None) authorises nothing: "I cannot say when I was
made" fails closed rather than reading as tick zero.

THE FAILSAFE CANNOT DEADLOCK BEHIND THE GATE, AND HERE IS WHY
=============================================================
write_setpoint() is also how layer 2 commands 0 W. cycle()'s two refusal
branches substitute a 0 W failsafe and write it like any other cycle;
shutdown() and the operator's stop button do the same. EVERY ONE OF THOSE
RUNS WHILE THE ALLOCATOR HAS REFUSED - ok is False and there are no shares -
so a gate that asked the allocator's permission to command zero would block
the safety write behind the very component whose failure the safety write
answers. A gate that can do that is worse than the hole it closes.

Resolved by authorising 0 W unconditionally, and on the VALUE rather than on
a failsafe=True flag: a flag is an assertion by the caller, which is exactly
what a second writer would pass; the value is a fact about what will be
written. The argument that this is safe and not merely convenient is that the
hazard §1.5 names is N-times loop gain from BROADCAST - handing every inverter
the same target so each supplies it in full (allocator.py's opening argument;
TEST-19 measured a permanent 4000 W p2p limit cycle at gain 1.0 with no guard
firing). At S = 0 the broadcast and the correct allocation COINCIDE: a_i = 1
for every unit gives every unit 0 W, which is exactly its share. There is no
over-command to make at zero. Said at the line, in write_refusal().

test_clamp.py part 7c drives it end to end through the real cycle() and the
real REFUSE_EMPTY branch: the allocator refuses every tick, the device still
sees 0 W, and the action log says ARBITER: REFUSED rather than WRITE REFUSED
so the two failures stay distinguishable to whoever has to debug them.

unmet_w IS STILL NOT ok
=======================
The gate reads ok and the unit's share and never unmet_w. allocator.py:179
says why: an allocation that could not place every watt is still safe to
write, and fusing them would let one saturated inverter park the whole site.
Graded on a record with 3800 W unmet and every share legal - mutation M5 adds
`or self.unmet_w` to the gate and that check goes red.

THE CONFIG CHECK, REPLACED RATHER THAN DELETED
==============================================
actuator_writers() counts WRITERS PER ACTUATOR instead of option keys. It
walks the options TREE rather than looking for a container called `inverters`,
because CFG-04 has not chosen that name yet and a census that guessed wrong
would go green while two writers existed - the same defect one step along.
Entity ids are folded to lower case so a second writer cannot be smuggled in
as Number.X versus number.x.

Two inverters with two entities are ACCEPTED - that is what the per-inverter
roster is for, and a validator that refuses the feature it guards is one
somebody switches off. Two declarations aimed at ONE entity are refused,
naming the actuator and every writer pointed at it. That includes the case an
author will meet first - keeping setpoint_entity as A's and listing A again -
because "they happen to be the same entity, so it is fine" is precisely the
reasoning that makes two writers invisible.

ACTUATOR_WRITE_KEYS survives ONLY as the enumeration a census needs, with its
guarantee comment deleted; nothing asserts on its length any more. Keeping the
name is also what stops admin/goodwe's current two_writers scenario failing on
an AttributeError between the two merges.

WHAT NEITHER CHECK OBSERVES, SAID OUT LOUD
==========================================
The census sees CONFIGURED writers. A second write path added in CODE - a
hass.set_number() call next to some new strategy - declares nothing and is
invisible to it, exactly as it was invisible to the tuple. That half is not
closed at startup and cannot be; it is closed at runtime by the record gate,
which does not care what the options look like or who called the method. The
two checks are deliberately different kinds, and only the runtime one survives
a schema this file has not seen yet.

EVIDENCE
========
* Full 18-file suite green on a purged tree (tools/mutation_run.sh).
* Verified by breaking it - seven mutations, each on a purged tree, each
  reverted and re-verified:
    M1 remove the gate                -> test_clamp red (4 checks)
    M2 make the zero exit an amnesty  -> test_clamp red (12 checks)
    M3 drop the tick comparison       -> test_clamp red (5 checks)
    M4 delete the census refusal      -> test_validate red (3 checks)
    M5 fuse unmet_w into ok           -> test_clamp red (1 check)
    M6 freeze the tick on the live path -> test_clamp red (2 checks)
    M7 move the gate below the clamp  -> test_clamp red (9 checks)
* AC 5: no existing check was weakened. The two edits to test_clamp.py are
  fixtures, not assertions - parts 5 and 6c call write_setpoint() directly
  with a number nothing allocated, which is now refused, so they say where
  their number came from. Every assertion in both parts is unchanged, and
  part 7f asserts that across part 3's sixty real cycles the gate refused
  zero writes.
* admin/goodwe's TEST-19 norig scenarios (planner_binding, two_master_plant,
  two_master_broadcast) still pass against this tree - they import the
  add-on's control law across the repo boundary.

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

goodwe_controller/app/allocator.py

@@ -197,12 +197,82 @@ class Allocation:
     quantisation_w: float = 0.0
     refused: str | None = None
     passthrough: bool = False    # N<=1: the share IS the site target, unrounded
+    # SAFETY-28. WHICH TICK PRODUCED THIS RECORD, as an opaque token minted by
+    # the caller - `Controller.alloc_tick`, incremented once per resolution.
+    #
+    # ⚠️ IT IS AN INPUT, NOT A COUNTER THIS MODULE KEEPS. `plan()` is a pure
+    # function and part 10 of test_alloc.py grades that by asserting the module
+    # holds no state at all; a serial number incremented in here would be
+    # exactly the cached-across-ticks thing the envelope rule forbids, wearing a
+    # different hat. So the tick is handed in and handed back out, and the
+    # freshness question is answered by whoever owns the clock.
+    #
+    # ⚠️ AND IT DEFAULTS TO None, WHICH THE WRITE GATE REFUSES. A record built
+    # without a tick is not "tick zero", it is a record that cannot say when it
+    # was made - and the gate fails closed on it. Every test in this repository
+    # that calls `plan()` for its arithmetic gets None and does not care;
+    # main.py stamps every record it puts on the write path.
+    tick: int | None = None
 
     @property
     def ok(self) -> bool:
         """The one boolean SAFETY-28's write gate reads."""
         return self.refused is None
 
+    def authorises(self, unit: str, value: float, tick: int | None) -> str | None:
+        """Why `unit` may NOT be written `value` on tick `tick`, or None if it may.
+
+        ⚠️ THIS IS THE QUESTION SAFETY-28 REPLACED A CONFIG-SHAPE PROXY WITH, and
+        it lives on the record rather than in main.py so that the record is the
+        thing that answers it. Before this, "two writers can never reach one
+        actuator" was enforced by `len(validate.ACTUATOR_WRITE_KEYS) == 1` -
+        true, but a statement about the OPTIONS SCHEMA. Add a per-inverter
+        config (CFG-04) and there are two real writers with that length still 1:
+        the check stays green while the property it protects is gone.
+
+        Asking the record instead makes the property mechanical. A number
+        reaches the wire only if the single allocator placed it, on THIS tick,
+        for THIS unit. A second writer with its own arithmetic cannot produce
+        one, because it does not appear in a record; and it cannot borrow an old
+        one, because the tick has moved on.
+
+        ⚠️ `unmet_w` IS NOT CONSULTED AND MUST NOT BE. An allocation that could
+        not place every watt is still SAFE TO WRITE - see this class's own
+        docstring. Fusing the two would let one saturated inverter park the
+        whole site, which is a worse outcome than the hole this gate closes.
+
+        ⚠️ NOR IS 0 W ITS BUSINESS. The caller answers that one before it asks
+        this, and the reason is at `Controller.write_refusal()`: a gate that can
+        block the failsafe is worse than the hole it closes.
+        """
+        if tick is None or self.tick is None or self.tick != tick:
+            return (f"the allocation record on hand was made on tick "
+                    f"{self.tick!r} and this is tick {tick!r} - a record whose "
+                    f"envelopes have moved cannot authorise a write")
+        if not self.ok:
+            return f"the allocator refused this tick ({self.explain()})"
+        if unit not in self.shares:
+            return (f"{unit} has no share in this tick's allocation "
+                    f"({self.explain()})")
+        share = self.shares[unit]
+        if value != share:
+            return (f"{value:+.0f} W is not {unit}'s share of this tick's "
+                    f"allocation, which is {share:+.0f} W ({self.explain()})")
+        # ⚠️ THE RECORD IS ASKED WHETHER IT AGREES WITH ITSELF. `within_envelope`
+        # exists because the half-open clamp defect once shipped a plan reading
+        # `inverter-a -> +500 W in [2000, +inf]` - stating the floor and a share
+        # below it in one breath - and `UnitPlan.explain()` renders that as
+        # ENVELOPE VIOLATED, DO NOT WRITE. This is the DO NOT WRITE.
+        #
+        # Unreachable at the shipped roster of one, where the pass-through's
+        # interval is (-inf, +inf) and every number is inside it. Graded anyway,
+        # on a constructed record, because the branch PR #40's reviewer replaced
+        # with `if False:` was unreachable too and the whole suite stayed green.
+        for p in self.plans:
+            if p.unit == unit and not p.within_envelope:
+                return (f"the record contradicts itself: {p.explain()}")
+        return None
+
     def explain(self) -> str:
         """One line an operator can act on."""
         if self.refused is not None:
@@ -315,7 +385,7 @@ def _fill(order, weights, cap, amount):
 
 
 def plan(target_w, bounds, *, weights=None, live=None, scope_errors=(),
-         site_priority=None, site_key="site") -> Allocation:
+         site_priority=None, site_key="site", tick=None) -> Allocation:
     """Divide the site grid target `target_w` across the units in `bounds`.
 
     `bounds`   unit name -> that unit's interval for THIS TICK (arbiter stage 1,
@@ -333,6 +403,11 @@ def plan(target_w, bounds, *, weights=None, live=None, scope_errors=(),
     `site_priority` the priority of the SITE claim that chose `target_w`. It is
                what a unit's own winning SET is weighed against - see PINS.
     `site_key` the name to use when there are no units at all.
+    `tick`     an opaque token identifying the tick this record is FOR, handed
+               straight back on the record. SAFETY-28's write gate compares it
+               against the tick it is writing on, so that a record cannot be
+               replayed after its envelopes have moved. It is an input rather
+               than something this module counts, for the reason on the field.
 
     ⚠️ N<=1 IS A PASS-THROUGH AND IS BYTE-IDENTICAL TO WHAT SHIPPED. The share
     IS the site target, as a float, unclamped and unrounded. That is §6.2's N=1
@@ -380,7 +455,7 @@ def plan(target_w, bounds, *, weights=None, live=None, scope_errors=(),
             shares={}, plans=(), dropped=(),
             unmet_w=int(round(float(target_w))),
             quantisation_w=float(int(round(float(target_w)))) - float(target_w),
-            refused=f"{REFUSE_SCOPE}: " + "; ".join(scope_errors))
+            refused=f"{REFUSE_SCOPE}: " + "; ".join(scope_errors), tick=tick)
 
     if len(units) <= 1:
         only = units[0] if units else site_key
@@ -390,7 +465,7 @@ def plan(target_w, bounds, *, weights=None, live=None, scope_errors=(),
             shares={only: share},
             plans=(UnitPlan(only, int(round(share)), -inf, inf, 1.0,
                             "N<=1: the share IS the site target"),),
-            passthrough=True)
+            passthrough=True, tick=tick)
 
     w = {u: 1.0 if weights is None else float(weights.get(u, 1.0))
          for u in units}
@@ -443,7 +518,7 @@ def plan(target_w, bounds, *, weights=None, live=None, scope_errors=(),
         return Allocation(
             target_w=float(target_w), sum_w=sum_w, shares={}, plans=(),
             dropped=tuple(dropped), unmet_w=sum_w, quantisation_w=quant,
-            refused=why)
+            refused=why, tick=tick)
 
     # --- REFUSAL 2: nobody is available ------------------------------------
     if not considered:
@@ -576,4 +651,4 @@ def plan(target_w, bounds, *, weights=None, live=None, scope_errors=(),
 
     return Allocation(target_w=float(target_w), sum_w=sum_w, shares=shares,
                       plans=tuple(plans), dropped=tuple(dropped),
-                      unmet_w=int(unmet), quantisation_w=quant)
+                      unmet_w=int(unmet), quantisation_w=quant, tick=tick)

goodwe_controller/app/arbiter.py

@@ -416,11 +416,19 @@ def allocate(target_w: float, bounds: dict, *, weights=None, live=None,
 
 
 def allocate_record(target_w: float, bounds: dict, *, weights=None, live=None,
-                    scope_errors=(), site_priority=None) -> tuple:
-    """`allocate()` plus the record - `(shares, allocated, allocation)`."""
+                    scope_errors=(), site_priority=None, tick=None) -> tuple:
+    """`allocate()` plus the record - `(shares, allocated, allocation)`.
+
+    `tick` is SAFETY-28's freshness token: it identifies the tick the record is
+    FOR and is handed straight through to `allocator.plan()`. Left None the
+    record is UNSTAMPED, which the write gate refuses - so a caller that intends
+    the record to authorise a write must pass one. Every existing caller in this
+    repository wants the arithmetic and not the authority, and gets None.
+    """
     rec = allocator.plan(target_w, bounds, weights=weights, live=live,
                          scope_errors=scope_errors,
-                         site_priority=site_priority, site_key=ACTUATOR_SITE)
+                         site_priority=site_priority, site_key=ACTUATOR_SITE,
+                         tick=tick)
     return rec.shares, rec.ok, rec
 
 
@@ -472,7 +480,8 @@ def site_resolve(claims: list) -> Resolution:
                       winner_priority=winner.priority)
 
 
-def resolve(claims: list, *, units=None, weights=None, live=None) -> Resolution:
+def resolve(claims: list, *, units=None, weights=None, live=None,
+            tick=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
@@ -499,6 +508,14 @@ def resolve(claims: list, *, units=None, weights=None, live=None) -> Resolution:
     with its own evidence removed. That mutation survived the whole suite until
     test_arbiter.py part 7 graded it on a SILENT unit.
 
+    ⚠️ `tick` IS SAFETY-28's FRESHNESS TOKEN AND IT IS NOT OPTIONAL ON THE LIVE
+    PATH. It identifies the tick this resolution is FOR, and it ends up on
+    `Resolution.allocation.tick`, where the write gate compares it against the
+    tick it is writing on. A record with no tick cannot authorise a write, which
+    is why main.py passes `self.alloc_tick` and why a test that only wants the
+    arbiter's arithmetic can leave it out and be sure it has not accidentally
+    minted a licence to write.
+
     ⚠️ 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`
@@ -533,5 +550,6 @@ def resolve(claims: list, *, units=None, weights=None, live=None) -> Resolution:
     out.unit_bounds = bounds
     out.shares, out.allocated, out.allocation = allocate_record(
         out.target_w, bounds, weights=weights, live=live,
-        scope_errors=out.scope_errors, site_priority=out.winner_priority)
+        scope_errors=out.scope_errors, site_priority=out.winner_priority,
+        tick=tick)
     return out

goodwe_controller/app/main.py

@@ -299,6 +299,25 @@ class Controller:
         # the cached envelope this card exists to forbid, wearing a different
         # hat.
         self.allocation = None
+        # SAFETY-28. THE TICK THE RECORD ABOVE BELONGS TO, and the counter that
+        # mints it. It is incremented ONCE PER RESOLUTION - not once per loop
+        # iteration - and that distinction is load-bearing in both directions:
+        #
+        #   * a NEW resolution makes the previous record stale IMMEDIATELY, so a
+        #     record cannot be replayed into a later tick after the envelopes it
+        #     describes have moved. That is the replay half of the gate.
+        #   * a cycle that produced NO resolution does not bump it. The "inputs
+        #     missing, not yet stale" hold above returns before the allocator
+        #     runs precisely so that a single missed poll does not zero the
+        #     inverter, and the heartbeat re-affirms `self.target` through the
+        #     write path while it does. Bumping here would make that heartbeat
+        #     unauthorised and drop the site to 0 W on the first dropped poll -
+        #     turning a hold into the outage it exists to prevent.
+        #
+        # So the record is SUPERSEDED, never expired: it stands until the
+        # allocator produces its successor, and nothing else has moved in
+        # between that it does not still describe.
+        self.alloc_tick = 0
         # What the last cycle's allocator dropped, so the log line above is
         # edge-triggered. Starts as the empty tuple - nothing has been dropped
         # yet and nothing has been said about it.
@@ -406,6 +425,67 @@ class Controller:
         elif self.inputs_bad_since is None:
             self.inputs_bad_since = datetime.now(timezone.utc)
 
+    def write_refusal(self, value: float) -> str | None:
+        """Why `value` may NOT be written right now, or None if it may.
+
+        --- SAFETY-28: THE WRITE PATH IS GATED ON THE ALLOCATION RECORD --------
+        specs §1.5 makes "any configuration in which two writers can reach one
+        actuator" a non-goal. Until this method that non-goal was enforced by
+        `len(validate.ACTUATOR_WRITE_KEYS) == 1` - there is one option key, so a
+        second writer is not expressible. True, and a statement about the SHAPE
+        OF THE OPTIONS SCHEMA rather than about the writes. Add CFG-04's
+        per-inverter config and there are two real writers with that length
+        still 1: the check stays green while the property it protects is gone.
+        That is this repository's named failure mode - a check that observes
+        something other than what it claims to observe - so the enforcement
+        moved here, onto the writes themselves.
+
+        The rule is: A NUMBER REACHES THE WIRE ONLY IF THE SINGLE ALLOCATOR
+        PLACED IT, ON THIS TICK, FOR THIS UNIT. A second writer with arithmetic
+        of its own cannot satisfy that - its number is not in any record - so it
+        has to file a Claim and go through `resolve()`, which is the one
+        allocator. "Exactly one allocator per shared resource" stops being a
+        convention somebody can forget and becomes a thing the write path
+        checks. `Allocation.authorises()` holds the per-record half of the
+        argument.
+
+        ⚠️ 0 W IS ALWAYS AUTHORISED, AND THAT IS THE ANSWER TO "WHAT IF THE
+        ALLOCATOR IS THE THING THAT FAILED". This is not a convenience exit; it
+        is the one value whose correctness does not depend on a split existing:
+
+          * The hazard the non-goal names is N-times loop gain from BROADCAST -
+            handing every inverter the same target so each supplies it in full
+            (see allocator.py's opening argument, and TEST-19's measured
+            `N=2 gain 1.0` limit cycle). At S = 0 the broadcast and the correct
+            allocation COINCIDE: a_i = 1 for every unit gives every unit 0 W,
+            and 0 W is exactly its share. There is no over-command to make.
+          * It is the fail-toward-inaction direction §11.1 rule 1 already
+            names, and it is what layer 2 commands. `cycle()`'s two refusal
+            branches replace the resolution with a 0 W failsafe and then write
+            it through here like any other cycle; `shutdown()` and the
+            operator's stop button do the same. Every one of those runs while
+            the allocator has REFUSED - `Allocation.ok` is False and there are
+            no shares - so a gate that asked the allocator's permission to
+            command zero would deadlock the failsafe behind the very component
+            whose failure the failsafe exists to answer.
+
+        A gate that can block the safety write is worse than the hole it closes,
+        so it cannot block it: the test for zero is first and reads nothing.
+
+        ⚠️ AND IT IS `value == 0.0`, THE REQUESTED NUMBER - not a `failsafe=True`
+        argument. A flag is an assertion by the caller, which is precisely what
+        a second writer would pass; the value is a fact about what is going to
+        be written. -0.0 == 0.0 in Python, and a nan never reaches here (the
+        caller has already turned it into 0.0), so the predicate is total.
+        """
+        if value == 0.0:
+            return None
+        rec = self.allocation
+        if rec is None:
+            return ("no allocation record exists yet - nothing has authorised "
+                    f"{value:+.0f} W")
+        return rec.authorises(self.unit, value, self.alloc_tick)
+
     async def write_setpoint(self, value: float, *, force: bool = False) -> None:
         entity = self.o.get("setpoint_entity", "")
         if not entity:
@@ -430,6 +510,39 @@ class Controller:
                        "0 W and continuing to command. This is a bug upstream, "
                        "not a limit.", value)
             value = 0.0
+
+        # --- SAFETY-28: AND IT IS REFUSED HERE, NOT LOGGED SOMEWHERE ----------
+        # ⚠️ ABOVE THE CLAMP AND BELOW THE NON-FINITE COERCION, and both halves
+        # of that placement are decisions.
+        #
+        # Below the coercion, because a nan is loss of input rather than an
+        # unauthorised write: rule 1 has already turned it into 0 W, which this
+        # gate then authorises unconditionally, so a transport bug does not get
+        # a second, differently-worded refusal.
+        #
+        # Above the clamp, because the question is WHO CHOSE THIS NUMBER and the
+        # answer is only meaningful about the number that was asked for. The
+        # clamp then narrows what was authorised, always toward safety, and it
+        # stays the last thing between a bug and the hardware. Gating the
+        # CLAMPED value would be worse than useless: on every cycle the clamp
+        # engages, the emitted watts differ from the allocator's share by
+        # construction, so the gate would refuse exactly the cycles SAFETY-03
+        # exists for.
+        #
+        # The refusal is a SUBSTITUTION, not a return: 0 W goes on the wire in
+        # place of the number nothing stands behind. Returning instead would
+        # leave the inverter latched on its last command with the ESP32's
+        # heartbeat still being fed - holding an unauthorised setpoint quietly,
+        # which is the outcome this gate exists to prevent.
+        refusal = self.write_refusal(value)
+        if refusal is not None:
+            self.log_event(f"WRITE REFUSED {value:+.0f} W - commanding 0 W")
+            _LOG.error("SAFETY-28 REFUSED a write of %+.0f W: %s. Commanding "
+                       "0 W instead. Every setpoint must be one the allocator "
+                       "placed on THIS tick - see Controller.write_refusal().",
+                       value, refusal)
+            value = 0.0
+
         result = clamp_to_rating(value, float(self.o.get("max_w", 2000)),
                                  self.dev_min, self.dev_max)
         self.clamp_last = result
@@ -881,7 +994,12 @@ class Controller:
             # de-assert when control is stopped.
             self.loop_clamped = (False, "")
 
-        resolution = resolve(claims, units=self.units, live=self.live_units())
+        # SAFETY-28. A new resolution is a new tick, and the previous record is
+        # stale from this line onwards. Incremented BEFORE resolve() so that the
+        # record resolve() builds is stamped with the tick it is for.
+        self.alloc_tick += 1
+        resolution = resolve(claims, units=self.units, live=self.live_units(),
+                             tick=self.alloc_tick)
         self.allocation = resolution.allocation
         # --- THE TWO REFUSALS, AND THEY ARE NOT THE SAME REFUSAL --------------
         # Both do the same thing - REPLACE the resolution with a 0 W failsafe

goodwe_controller/app/validate.py

@@ -229,17 +229,84 @@ _LOG = logging.getLogger("goodwe.config")
 # a matching integer means a matching rule.
 FIRMWARE_INGEST_VETO_S = 30.0
 
-# ⚠️ The complete set of option keys through which this add-on can reach an
-# actuator. specs §1.5 makes "any configuration in which two writers can reach
-# one actuator" a non-goal, and the way that non-goal is ENFORCED here is by
-# construction: there is exactly one such key, so a second writer is not
-# expressible in the options schema at all. sim/inject.py's `two_writers`
-# scenario asserts on this tuple - if a second write path is ever added, that
-# scenario goes red and somebody has to decide how the two are arbitrated
-# BEFORE the config that allows both can ship.
+# ⚠️ THE OPTION KEYS UNDER WHICH A WRITER CAN BE DECLARED - AN ENUMERATION, AND
+# SAFETY-28 DEMOTED IT TO ONE. This tuple used to BE the guarantee. The comment
+# that stood here said specs §1.5 makes "any configuration in which two writers
+# can reach one actuator" a non-goal, and that the non-goal was ENFORCED by
+# construction: exactly one such key, so a second writer is not expressible in
+# the options schema at all.
+#
+# That was true, and it graded THE SHAPE OF THE OPTIONS SCHEMA rather than the
+# writes. Add CFG-04's per-inverter config - a list of inverters, each with its
+# own `setpoint_entity` - and there are two real writers with `len()` of this
+# tuple still equal to 1. The check stays green while the property it protects
+# is gone, which is this repository's named failure mode: a check that observes
+# something other than what it claims to observe.
+#
+# So the guarantee moved to `actuator_writers()` below, which counts WRITERS PER
+# ACTUATOR rather than keys, and finds them wherever in the options tree they
+# are declared. This tuple survives only because a census has to know which key
+# NAMES an actuator; it is not a bound on how many writers there can be, and
+# nothing should ever assert on its length again.
 ACTUATOR_WRITE_KEYS = ("setpoint_entity",)
 
 
+def _collect_writers(node, path: str, out: list) -> None:
+    """Walk the options tree, collecting `(where, entity)` for every writer.
+
+    ⚠️ STRUCTURAL, NOT NAME-BASED ON THE CONTAINER, and that is the point. A
+    census that looked for a key called `inverters` would be guessing the name
+    CFG-04 has not chosen yet, and a guess that is wrong goes GREEN while two
+    writers exist - the same defect one level along. This walks whatever shape
+    the options happen to have and reports every `setpoint_entity` in it,
+    however deeply nested and under whatever container.
+    """
+    if isinstance(node, dict):
+        for k, v in node.items():
+            here = f"{path}.{k}" if path else str(k)
+            if k in ACTUATOR_WRITE_KEYS:
+                entity = str(v or "").strip()
+                if entity:
+                    out.append((here, entity))
+                continue
+            _collect_writers(v, here, out)
+    elif isinstance(node, (list, tuple)):
+        for i, v in enumerate(node):
+            _collect_writers(v, f"{path}[{i}]", out)
+
+
+def actuator_writers(opts: dict) -> dict:
+    """actuator -> the configured writers that can reach it. INSTANCE-AWARE.
+
+    The replacement for `len(ACTUATOR_WRITE_KEYS) == 1`. It answers HOW MANY
+    THINGS CAN WRITE TO EACH ACTUATOR, which is the property §1.5 actually
+    names, and it keeps answering it when the schema grows a per-inverter list:
+    two inverters with two entities are two writers on two actuators and fine,
+    two declarations naming ONE entity are the non-goal and are refused.
+
+    The key is the entity id, lowercased - Home Assistant entity ids are
+    lowercase by construction, and folding case here means a config cannot
+    smuggle a second writer past the census on `Number.X` versus `number.x`.
+
+    ⚠️ SAY WHAT THIS STILL DOES NOT OBSERVE, because the argument that demoted
+    the tuple applies to its replacement too. This is a census of CONFIGURED
+    writers. A second write path added in CODE - a `hass.set_number()` call next
+    to some new strategy - declares nothing and is invisible here, exactly as it
+    was invisible to the tuple. That hole is not closed at startup and cannot
+    be: it is closed at runtime, by `Controller.write_refusal()`, which refuses
+    any value the single allocator did not place on this tick and does not care
+    what the options look like. The two checks are deliberately different
+    kinds - one grades the config, one grades the writes - and only the second
+    one survives a schema this file has not seen yet.
+    """
+    found: list = []
+    _collect_writers(opts, "", found)
+    census: dict = {}
+    for where, entity in found:
+        census.setdefault(entity.lower(), []).append(where)
+    return census
+
+
 class ConfigRefused(Exception):
     """The configuration is wrong. Not "something broke" - see main.py's handler.
 
@@ -265,9 +332,8 @@ def validate_startup_config(opts: dict, dev_min=None, dev_max=None) -> list[str]
     """
     problems: list[str] = []
 
-    # --- 1. an actuator to write to ------------------------------------------
-    writers = [k for k in ACTUATOR_WRITE_KEYS
-               if str(opts.get(k, "") or "").strip()]
+    # --- 1. an actuator to write to, and AT MOST ONE WRITER PER ACTUATOR -----
+    writers = actuator_writers(opts)
     if not writers:
         problems.append(
             "setpoint_entity is not set, so this add-on has no actuator: every "
@@ -275,6 +341,29 @@ def validate_startup_config(opts: dict, dev_min=None, dev_max=None) -> list[str]
             "ESP32 heartbeat that holds off the layer-1 failsafe never happens. "
             "It would run, look healthy, and move no energy at all. Set it to "
             "the ESPHome number entity that carries the setpoint.")
+    # SAFETY-28. The §1.5 non-goal, graded on the writers rather than on the
+    # count of option keys. Read `actuator_writers()` for why the old check went
+    # green on the very config this one is here to refuse.
+    #
+    # ⚠️ AND IT REFUSES A DUPLICATE DECLARATION EVEN WHEN BOTH NAME THE SAME
+    # ENTITY, which is the case an author of the per-inverter config will meet
+    # first: keep `setpoint_entity` as inverter A's and add A to the list again
+    # and there are two config sites aimed at one actuator, each with its own
+    # neighbouring options. "They happen to be the same entity, so it is fine"
+    # is precisely the reasoning that makes two writers invisible. Declare each
+    # actuator exactly once and the refusal does not fire.
+    for actuator, who in sorted(writers.items()):
+        if len(who) > 1:
+            problems.append(
+                f"{len(who)} configured writers can reach the one actuator "
+                f"{actuator}: {', '.join(who)}. specs §1.5 makes any "
+                "configuration in which two writers can reach one actuator a "
+                "non-goal - two independent setpoints on one inverter is the "
+                "arbitration problem this add-on refuses to have, and at "
+                "runtime it is a meter-emulation target being written twice a "
+                "second by two strategies that cannot see each other. Give "
+                "each actuator exactly one writer, or point the second one at "
+                "its own entity.")
 
     # --- 2. the configured ceiling against the device's own rating -----------
     max_w = _number(opts, "max_w", 2000.0)