docs: a transport must preserve publish order, and why

[dcj]

Documents an obligation the injected-transport contract implies but never states. Docs only; no source changed.

Raised by @cayossarian on #46, from building a natively-async MqttDeviceTransport where the hazard is real rather than theoretical.

The gap

MqttDeviceTransport says nothing about ordering, and until now it did not need to: neither transport shipped with the SDK can violate it. paho's own thread and asyncio_driver each pump one client, so publishes reach the wire in the order they were made.

A transport written against the protocol directly need not. One that starts a task per publish() hands ordering to the scheduler.

Why that is a real loss and not a nitpick

Ordering is a guarantee the SDK maintains on a producer's behalf:

• a device's $description precedes the $state=ready that vouches for it
• refresh_tree() publishes a device's own $state after the children it announces, which is what 0.18.1 fixed (refresh_tree() publishes a device's $state before its children, so the root announces ready to an empty tree #31 / fix: publish a device's $state after its children in refresh_tree #32)

Those are quality-of-implementation rather than protocol. A consumer must never depend on them, and doc/consuming-a-homie-tree.md argues that at length, since publish order does not survive retention.

Which is exactly why the warning cannot live in that document. It addresses consumers, so it will never reach a transport author — who can therefore drop a guarantee the SDK spends effort meeting, silently, while every document that discusses ordering is telling the other party not to rely on it.

Also recorded: the teardown consequence

A publish() that enqueues and returns is entirely legitimate. Every return in the protocol is typed object precisely because the SDK discards them (transport.py:29). But Device.stop() publishes the final $state and returns without flushing, so a queueing transport needs a drain point of its own before its client closes, or that last message is lost behind it.

Measured by @cayossarian on his implementation: remove the drain and the root's final $state never reaches the broker, with a log line as the only trace.

Note on scope

This documents the rule. A worked example of a natively-async transport would be more useful still, and @cayossarian has the only known implementation; that is asked for separately on #46 and is his to decline. This paragraph is not blocked on it.

Related: #46 proposes the teardown API whose absence makes the reach-around necessary in the first place.