Two fields on SpanCircuitSnapshot are in a half-state: declared on the shared model, written by one adapter, ignored by the other, and read by no consumer anywhere. Either they should carry data on both adapters or they should not exist. Not urgent and nothing is broken — filing it so the choice gets made deliberately the next time a release is open, rather than surviving another cycle by default.
Current state
src/span_panel_api/models.py:51-52 declares both, `int = 0`
packages/schema-0/.../consumer.py:374-375 writes both (MQTT arrival time)
packages/schema-1/ writes neither
tests/test_mqtt_homie.py:272-273 asserts schema-0 wrote them
That test is the only reader in existence, and it is a test of the writer. Searched the Home Assistant integration (source and tests), panelbench, and span-card: no consumer reads either field on either adapter. The integration mentions them only in tests/factories.py, as constructor pass-throughs it never asserts on.
So the adapter asymmetry currently costs nothing, because the populated side has no readers to lose. The field defaults to 0, which a consumer would read as "epoch" rather than "unknown" — a second reason not to leave it half-populated if anyone ever does start reading it.
The declaration comment — # v1: poll timestamp | v2: MQTT arrival time — dates them to the REST era, where a poll timestamp was a real thing the client knew. They appear to have been carried forward into the MQTT transport without a consumer following them across.
Option A — remove them
Cheapest, and honest about what they are. Nothing reads them, so nothing regresses. It is a breaking change to a public model, so it wants a release that is already breaking rather than a patch — and there is no rush to invent one.
Option B — populate them on schema-1
More involved than it first looks, which is worth recording. Schema-1 builds from the eBus SDK's DiscoveredDevice, and that type exposes no timestamp accessor — arrival time is not in the data schema-1 works from. So this is not a matter of wiring up a value already present. Two sub-routes:
- Upstream in
ebus-sdk (0.19.0, electrification-bus/python-sdk, third-party). Correct home if property arrival time belongs to Homie handling generally, but it is another project's repo and release cadence.
- Stamp it in schema-1's adapter.
SchemaOneAdapter.handle_message(topic, payload) (adapter.py:96) sees every message, so it can record arrival times itself, the way schema-0's accumulator already does. Self-contained and on our own cadence; duplicates something the SDK arguably should own.
Option B is only worth it if a consumer is going to read the field. The obvious candidate is staleness detection — telling a reading that has not been refreshed from one that has — which nothing currently does.
Recommendation
Weakly Option A, on the grounds that a field nothing reads is not paying for the ambiguity it creates, and Option B can be done later if a real consumer appears. But this is a call about where the concern belongs, not a defect, so it should be made by whoever owns that question rather than settled here.
Provenance
Noticed while diagnosing SpanPanel/span#259. energy_accum_update_time_s == 0 looked like it might serve as an in-band signal that a reading had never arrived — the exact discrimination that issue turned on. It cannot serve that purpose, because schema-1 never sets it and no consumer reads it on either adapter. #259 was fixed a different way, by making an unreported reading None rather than a fabricated 0.0 (#167, in 3.1.0). This field played no part in that fix and nothing about it is a regression.
Two fields on
SpanCircuitSnapshotare in a half-state: declared on the shared model, written by one adapter, ignored by the other, and read by no consumer anywhere. Either they should carry data on both adapters or they should not exist. Not urgent and nothing is broken — filing it so the choice gets made deliberately the next time a release is open, rather than surviving another cycle by default.Current state
That test is the only reader in existence, and it is a test of the writer. Searched the Home Assistant integration (source and tests), panelbench, and span-card: no consumer reads either field on either adapter. The integration mentions them only in
tests/factories.py, as constructor pass-throughs it never asserts on.So the adapter asymmetry currently costs nothing, because the populated side has no readers to lose. The field defaults to
0, which a consumer would read as "epoch" rather than "unknown" — a second reason not to leave it half-populated if anyone ever does start reading it.The declaration comment —
# v1: poll timestamp | v2: MQTT arrival time— dates them to the REST era, where a poll timestamp was a real thing the client knew. They appear to have been carried forward into the MQTT transport without a consumer following them across.Option A — remove them
Cheapest, and honest about what they are. Nothing reads them, so nothing regresses. It is a breaking change to a public model, so it wants a release that is already breaking rather than a patch — and there is no rush to invent one.
Option B — populate them on schema-1
More involved than it first looks, which is worth recording. Schema-1 builds from the eBus SDK's
DiscoveredDevice, and that type exposes no timestamp accessor — arrival time is not in the data schema-1 works from. So this is not a matter of wiring up a value already present. Two sub-routes:ebus-sdk(0.19.0,electrification-bus/python-sdk, third-party). Correct home if property arrival time belongs to Homie handling generally, but it is another project's repo and release cadence.SchemaOneAdapter.handle_message(topic, payload)(adapter.py:96) sees every message, so it can record arrival times itself, the way schema-0's accumulator already does. Self-contained and on our own cadence; duplicates something the SDK arguably should own.Option B is only worth it if a consumer is going to read the field. The obvious candidate is staleness detection — telling a reading that has not been refreshed from one that has — which nothing currently does.
Recommendation
Weakly Option A, on the grounds that a field nothing reads is not paying for the ambiguity it creates, and Option B can be done later if a real consumer appears. But this is a call about where the concern belongs, not a defect, so it should be made by whoever owns that question rather than settled here.
Provenance
Noticed while diagnosing SpanPanel/span#259.
energy_accum_update_time_s == 0looked like it might serve as an in-band signal that a reading had never arrived — the exact discrimination that issue turned on. It cannot serve that purpose, because schema-1 never sets it and no consumer reads it on either adapter. #259 was fixed a different way, by making an unreported readingNonerather than a fabricated0.0(#167, in 3.1.0). This field played no part in that fix and nothing about it is a regression.