X-Git-Url: https://git.giacomolli.uk/onehouse/blobdiff_plain/2015860819c6228bf5ec708a48e5ca9b7c04e27d..2392f423feb689c99600e5cb2c37ee93c62e603d:/doc/driver.rst

diff --git a/doc/driver.rst b/doc/driver.rst
index 33086f1..6e13e21 100644
--- a/doc/driver.rst
+++ b/doc/driver.rst
@@ -14,3 +14,66 @@ SIGTERM and finishes cleanup before exit. No integration or broker runs.
 
 Tests use fake drivers. They do not verify a broker or a physical
 device.
+
+******************
+ Typed publishing
+******************
+
+``Publisher`` takes a ``Transport`` with one ``Publish`` operation on
+``protocol.Publication``. No broker client or topic operation belongs in
+the framework. Typed methods cover descriptor, availability, reported
+values, telemetry, events, and results. Missing message IDs and
+observation times use fresh values. Supplied metadata remains subject to
+protocol validation.
+
+Equal retained payloads are suppressed. Correlation and causation bypass
+suppression. A changed telemetry sample uses QoS 0 without retention.
+Its latest complete value supplies a QoS 1 retained reported snapshot at
+the five-minute repeat or reconnect, not on every change. Repeats keep
+observation times, use fresh IDs, and omit command correlation and
+causation. JSON object key order and whitespace do not change equality.
+Measurement topics are independent. Boolean reported state does not
+repeat unless telemetry marks that point as a measurement. Online
+availability repeats every five minutes. Offline availability,
+descriptors, and Boolean state repeat on reconnect only. Expiring
+values, events, and results are not suppressed or cached.
+
+Run one publisher alongside the integration drivers. Its methods are
+safe for concurrent use and copy caller-owned payloads and timestamp
+pointers. Each send has a five-second timeout derived from the caller
+context. A background send error returns to the runner rather than being
+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.
+
+*******************
+ 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.