#########################
 Alamo Slim HTTP gateway
#########################

``driver/alamo`` defines a raw ``Client`` contract and an ``HTTPClient``
for the Slim gateway. The client uses ``GET /status`` for all
thermostats and ``GET /acao?mac=...`` for one thermostat. An action
changes power or target temperature, not both at once. Its response is
the complete readback for the requested MAC. The caller owns the HTTP
transport.

The address is an HTTP origin without a path, credentials, query, or
fragment. Redirects are rejected. Each exchange has a five-second
caller-derived timeout and a 64 KiB response limit. Records require all
seven documented properties. Extra gateway properties are permitted.
Errors omit request addresses, queries, and response bodies.

Configure thermostats through the manufacturer's application before use.
The gateway exposes local heating activity, not independent load-current
or contactor feedback. Fake HTTP tests do not verify a physical gateway,
thermostat firmware, or electrical safety.

The driver request scheduler applies one minimum six-second
request-start interval to status polls and actions together. Its
operation timeout starts after the rate wait. Caller cancellation or a
command deadline stops the wait without another exchange. A multi-step
command can expire between actions. The gateway budget belongs to one
driver owner.

The private control value uses ``settings.mode`` (``off`` or ``heat``),
``settings.target_temperature`` in degrees Celsius,
``current_temperature``, ``floor_temperature``, ``action`` (``off``,
``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.