fix: a control target only where the device declares the control

[cayossarian]

Four findings from the review of #164, landing before 3.1.0 is published so they fold into the same unreleased version rather than costing a 3.1.1.

Three are the same family as the bug #161 fixed: the refusal was right for the case it was written for, and the edges either permitted when they should not have, or refused with the wrong reason.

A target only where the device declares the control

_declared_settable collapsed two different absences onto one caller-chosen answer — a property the device never declared, and a property declared without $settable. Priority passed when_absent=True for the second (the documented firmware-omits-the-attribute case, and the catalog puts no condition on priority), which meant a device with no load-shed node at all was also treated as settable. The reference tree carries five: bess, bess-mid, pv, and both lugs. set_circuit_priority_target("bess") resolved a topic for a control that device never offered.

The undeclared branch now refuses unconditionally, and the parameter is when_unannotated, which is the only question it still answers. Relay behaviour is byte-identical — its default was already refusal — and only priority moves. A definition present but not a mapping counts as undeclared: a malformed declaration has not said the property is settable.

Both adapters answer the same question the same way

schema-0 built targets for wholly unknown circuit ids, because its value lookup defaults to "" and that read as permission. relay_is_settable / priority_is_settable now refuse a node that is not a circuit before reading any value, via a promoted is_circuit_node — so the command path, the snapshot's circuit set and has_circuit all read one thing and cannot drift. That also refuses the snapshot's synthetic unmapped_tab_* keys, which were writable.

A refusal that names the refusal it actually made

An unknown circuit id was refused with "declares its relay non-commandable" and audited as relay not commandable. The refusal was right; the reason was not. That detail reaches after_publish and the Home Assistant integration writes it into a security log where it is read as a fact about the panel.

Unknown circuits now say no such circuit; a genuinely locked relay still says relay not commandable, and a locked priority priority not settable. Both setters route through one _refuse_circuit_control, which consults has_circuit only after a target has already been refused — so an adapter answering it strangely can relabel a refusal but can never cause one. A test asserts the lookup is never made on a command that publishes.

Breaking

SchemaAdapter gains has_circuit. It is the third adapter-contract change in 3.1.0, alongside the four set_*_topic → set_*_target renames, and is named as such in all three changelogs rather than left in prose. Finding 3 is not implementable without it: the client sees only None from the target builder and has nothing else to tell the two cases apart.

Verified rather than assumed — a class carrying every required member except has_circuit is rejected at discovery, and the message names the member and states the remedy. It adds no mismatch anybody can newly hit: a 1.0.0 wheel was already rejected by the renames, and the rejection lists this alongside them with the same fix. ADAPTER_CONTRACT_VERSION does not move, which is what its own docstring reserves it for.

The protocol's documented guarantee changed with it: None from the two circuit target builders now also means the panel carries no circuit under that id, which could not be stated before because only schema-1 honoured it.

The two adapters differ, deliberately

schema-1's target builders do not gate on has_circuit; schema-0's do gate on node type. schema-1 refuses on the declaration, which is the specification's rule and the thing that authorises the write — a type check in front of it would be a second, weaker rule sitting where the authorisation lives. schema-0 has no per-circuit declaration to read, so node type is its only lookup. On schema-1, has_circuit is purely diagnostic and answers on device type rather than tree membership: a BESS is not a circuit whose relay happens to be locked. Both files document this.

Also

scripts/capture_parent_child_reference.py exited with a bare KeyError traceback on a missing pin block where the rest of the script exits with prose. Two sites, not one.

Tests

1061 → 1077, mypy clean across 43 source files, pylint 10.00/10, coverage 95.84%.

Four existing tests were asserting the buggy behaviour and are corrected rather than accommodated: test_schema_zero_adapter.py built targets against a panel that had published no $description at all, and two setter tests commanded a circuit id that was never declared. They now describe the circuit they command.

Not published

Folds into the unreleased 3.1.0 — no version bump, no pin changes.