Repository navigation
docs: add the consumer-side contract guide (consuming-a-homie-tree) - #33
Merged
Merged
Conversation
States the asymmetry the convention relies on and that this repo had never written down: a producer SHOULD minimize $state/$description transitions (quality-of-implementation, best-effort), while a consumer MUST react to every one of them, unconditionally (correctness). Covers why the asymmetry exists (the four optimizations this SDK already grants itself as a producer all change WHEN and WHETHER a message appears, never what is true), what $state=ready does and does not promise, and the three ways consumers get this wrong: the one-shot barrier that stops reconciling after startup, awaiting a $description that the content-hash suppression never sends, and inferring publish order across retained messages. Prompted by #31, where a careful integrator read our observable behaviour, inferred a timing contract from it, and built against the inference. The absence of a stated SHOULD/MUST split is what made that inference look safe. Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
dcj
added a commit
that referenced
this pull request
Aug 7, 2026
…de) (#34) Pure-fix release. No API change, no ebus-mqtt-client floor bump. - fix: Device.refresh_tree() now publishes a device's own $state after its descendants rather than before, so a device no longer announces ready while the children its $description names have published nothing (#31, #32). Thanks to @cayossarian. - docs: doc/consuming-a-homie-tree.md, the consumer-side contract guide (#33). Co-authored-by: Claude Opus 5 (1M context) <[email protected]>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Counterpart to
doc/building-a-proxy.md, for the controller/subscriber side. Follows #31 / #32.Why
#31 was filed by a careful integrator who read our observable behaviour, inferred a timing contract from it, and built against the inference. The producer-side ordering defect was real and is fixed in #32, but the deeper problem is that this repo has never stated the asymmetry the convention actually relies on, so the inference looked safe.
Those are not two halves of one contract. The first is quality-of-implementation and best-effort; the second is correctness and unconditional.
What it covers
$state=readyactually means. "My own$descriptionis current", never "my children are present". The rollup reading cannot be made true by any producer, because children are commissioned and decommissioned out of band and there is no moment at which a producer knows it has published all of them. Also documents the one thing a root's state is authoritative for: effective state, keyed on the root rather than the immediate parent.$descriptionthat the content-hash suppression never sends (theinittoreadyedge of an empty transition is not suppressed); and inferring order across retained messages, which is exactly the broker-restart case people reason about first.Controlleralready does for you, including the known gap: there is no public tree-complete affordance.Notes
Documentation only, no code changes. Ships with #32 as 0.18.1.