X-Git-Url: https://git.giacomolli.uk/onehouse/blobdiff_plain/b9a4f3bdd2609a8b178dd42f313c383ccb59049b..c36e60046f72af3d0803943185526c27b10aa4ae:/doc/alamo.rst

diff --git a/doc/alamo.rst b/doc/alamo.rst
index c9e6fde..8c02dce 100644
--- a/doc/alamo.rst
+++ b/doc/alamo.rst
@@ -33,3 +33,44 @@ The private control value uses ``settings.mode`` (``off`` or ``heat``),
 ``idle``, or ``heating``), and ``locked``. Commands contain the complete
 mode and target settings only. House-specific target bounds and steps
 belong to core validation. The driver accepts finite targets.
+
+****************
+ Gateway driver
+****************
+
+``New`` takes ``Settings``, the shared publisher and router, and a raw
+``Client``. Settings list all stable thermostat IDs and their unique MAC
+values for one physical gateway. The default poll interval is fifteen
+seconds. An explicit interval is from ten seconds through five minutes.
+The caller runs the publisher, supplies command intake, and owns the
+HTTP transport. The command keeps its explicit empty driver list.
+
+``Run`` serializes polling and commands across the gateway. One status
+request supplies every configured thermostat. It publishes no startup
+availability before evidence. Three failed or missing observations mark
+a thermostat offline. A successful observation resets that count and
+restores online state. A command error does not count as a missed poll.
+Recoverable HTTP failures appear as missed polls or failed command
+results, not logs. Publication failures return to the framework runner.
+Shutdown does not publish an outage. ``Refresh`` coalesces a
+rate-limited status poll and asks the shared publisher to resend cached
+snapshots.
+
+Each command reads a fresh action baseline, turns off before a target
+change, sets and verifies the target, and only then turns on if
+requested. Every action response is feedback. A failed intermediate
+readback stops later actions. A command can leave the thermostat off if
+a later action fails or expires. The driver publishes the last
+successful observation with its observation time and command causation.
+A completed result requires matching power and target readback. A
+complete no-change command still reads the gateway.
+
+One queue consumer per thermostat preserves command order. Work from
+separate thermostats has no cross-device order guarantee. The shared
+ledger stores an outcome before feedback or result publication.
+Duplicate commands replay the first result without another gateway
+exchange, also after a failed publication. The ledger is memory-only
+with the framework limit of 256 results per device. Restart or eviction
+ends that duplicate protection. A gateway request can have an uncertain
+physical outcome when its response fails. The driver does not retry that
+command action.