Share the Alamo gateway request budget

[onehouse] / doc / driver.rst

diff --git a/doc/driver.rst b/doc/driver.rst
index 00b062ab63ce449a51636648e6d2a5e6a3d62cdd..6e13e21170be8e074e6b352927d7efe18808ab18 100644 (file)
--- a/doc/driver.rst
+++ b/doc/driver.rst
@@ -46,3 +46,34 @@ logged by the publisher. Reconnect refresh requests are nonblocking and
 coalesce while pending. The cache is memory-only. Tests use a fake
 transport and simulated time. They do not verify MQTT acknowledgement or
 a broker reconnect.
 coalesce while pending. The cache is memory-only. Tests use a fake
 transport and simulated time. They do not verify MQTT acknowledgement or
 a broker reconnect.

+
+*******************
+ Command ownership
+*******************
+
+``NewRouter`` takes the explicit IDs of command-capable devices. It
+supplies protocol subscriptions and one 64-entry FIFO per device. Each
+entry holds one single command or one ordered batch. Intake parses a
+delivery once through ``protocol.Parse``. A malformed or expired member
+rejects the whole batch. Retained commands and commands for unowned
+devices are errors. A full queue waits for space, cancellation, or the
+earliest member expiry. Each device has one queue consumer. It checks
+physical ownership, capability access, and expiry again before work.
+Read-only devices have no queue.
+
+``NewLedger`` creates a ledger for one device. The consumer checks
+``Lookup`` before a physical action, and stores its result with
+``Remember`` before the first publication attempt. A duplicate reuses
+the first status, reason, message ID, and observation time. It performs
+no second action. This also applies after a failed result send. Pass the
+returned ``ResultRecord`` fields to ``Publisher.Result`` unchanged.
+Records are safe from caller mutation.
+
+The ledger retains 256 results in insertion order per device. Lookup
+does not extend their age. It is not a reservation for concurrent
+physical actions. The single queue consumer provides that exclusion. The
+ledger is memory-only. Eviction or process restart removes duplicate
+protection for that record. Pending physical confirmation and
+device-specific command safety belong to the integration. Fake tests
+verify queue order, backpressure, expiry, per-device bounds, and stable
+duplicate replay without device I/O.