feat(TRA-1028): Gpo.Set on the reader mqtt-rpc contract

[mikestankavich]

Drive a CS463 reader GPO as an alarm output, in the same shape as the Shelly plug. A hospital (Frederick) disabled WiFi, which rules out the WiFi Shelly. The reader is on wired ethernet, so the cloud is still reachable — the GPO replaces the plug, not the cloud. The geofence engine still decides; only the actuator changes.

Two axes: transport is reach, type is device

transport (http | mqtt) is how we reach a device; type (shelly_gen4 | csl_cs463_gpo) is what frame it speaks. Shelly and the CS463 both ride mqtt-rpc; only their frames differ. This supersedes the ticket's original TransportGPO idea, which conflated the two and would cost a migration per device model. It leaves room for an LLRP Speedway wrapper later as a third transport or another type, no schema churn.

	Shelly	Reader GPO
topic	<commandTopic>/rpc	<base>/rpc
method	Switch.Set	Gpo.Set
params	{id, on, toggle_after}	{port, on, pulse_ms}

Reader side (mqtt-rpc daemon)

• readerrpc gains GpoSetParams/GpoSetResult (MethodGpoSet was already reserved), synced across both copies of the contract.
• readerd.Adapter.GpoSet + a Gpo.Set dispatch case.
• CS463 adapter: a sessionless directIOOutput call (bypasses the single-root-session lock — verified on hardware while the web UI held the session; an alarm must not fail because a browser is open), and Gpo.Set moved from Unsupported to Supports.
• Reader-side pulse timer. pulse_ms > 0 arms a one-shot: drive on now, release after the delay from a timer on the reader host, mirroring Shelly's device-side toggle_after. auto_off_seconds maps straight onto it (× 1000), so the OFF edge never depends on a second message arriving. Timers are held per port under a mutex — a new Gpo.Set supersedes any pending release for that port rather than racing it, and the release's OFF write is gated by a pointer-identity check under the port lock so a stale timer can never drive a port OFF after a superseding ON. Same-port calls serialize across the reader HTTP round-trip (bounded by the release/RPC timeouts); different ports don't block each other.

Cloud side

• readercontrol.Notify — fire-and-forget publish alongside the existing reply-correlating call, plus a typed GpoSet wrapper. Gpo.Set rides readercontrol (which already owns the readerrpc frame format and <base>/rpc convention), not a generalized alarm.MQTTPublisher. The alarm path must never block on a reader round trip.
• Fire-and-forget is deliberate, consistent with how RFID is sold: reads and alarms are best-effort. A broker-accepted publish is success. A reader-side error reply (rejected port, /API unreachable, a backwards-wired GPO) used to be dropped at Debug without reading resp.Error — it now logs at Warn with id/code/message, so a silent no-actuation is greppable.
• One branch in alarm.Dispatcher.Set — routes on transport, then type. A GPO device on a non-mqtt transport is rejected up front.
• Geofence engine unchanged — every tuning tier, RSSI gate, latch/re-arm and auto_off_seconds behaviour carries over.

Reader addressed by a scan_device_id FK (not a free-text topic)

A GPO output device is addressed by a nullable output_devices.scan_device_id FK to scan_devices (migration 000033), not by a topic string. The reader's RPC base topic is derived server-side from that reader's publish_topic at fire time (the fire and test-fire reads LEFT JOIN under the org's RLS), single-sourced — retopic the reader and the alarm follows.

This closes a cross-org actuation path a review found: the earlier free-text command_topic was published to with the shared backend broker credential, so an org could have fired another tenant's reader. Now:

• Write-time validation requires a GPO device's scan_device_id to reference a live csl_cs463 reader in the org that has a publish_topic — otherwise a clear 400 (distinct messages for not-your-reader / not-a-cs463-reader / no-publish-topic), instead of a device that validates but silently never fires.
• At fire time a cross-org or deleted reader does not resolve (RLS), so the dispatcher gets an empty base topic and refuses to fire — defense in depth behind the write-time check.
• The frontend replaces the command-topic text field with a reader picker (filtered to csl_cs463) for GPO devices, and defaults the GPO port to 1 (min=1) so the "1–4" field isn't pre-seeded with an invalid 0.

switch_id is reused as the output-channel index — 0-based Shelly relay channel, 1-based CS463 GPO port (1–4) — documented per-type on the column and the model. Shelly (http and mqtt, including switch_id 0) is unchanged throughout.

Verification

go build, go vet, go test (incl. real-DB integration for the FK validation and topic resolution) green across the backend; go test -race green across the reader-side pulse logic (the per-port supersession race is covered by a test that fails against the pre-fix code and passes after); frontend touched-file suites green single-threaded. The only full-suite frontend failure is the pre-existing useReportHydration flake (passes 5/5 in isolation), in a package this branch doesn't touch.

Hardware + end-to-end verified on preview (2026-07-23). The replacement SSR carries a real load (a flasher ran under current, not just open-circuit voltage — the failure mode that killed the first module). And the full path fires: with the branch deployed to preview and the new mqtt-rpcd on cs463-212, a csl_cs463_gpo output device bound to the same boundary + presence rule as the existing Shelly "Portal Alarm" fires in sync with it on the same carousel reads — visually confirmed, both strobes flashing together. The deterministic path is also proven via the test-fire endpoint (gpio205 driven HIGH then released). Remaining hardware step is cosmetic: swapping the vehicle-strobe stand-in for the real Honeywell/System Sensor horn-strobe (24 V-only, non-Temporal-3) — a load-agnostic wiring swap, no code change.

Bringup notes for whoever deploys this: (1) sync-preview filters draft PRs and doesn't trigger on ready_for_review, so a PR marked ready-from-draft won't reach preview until its next push (re-run the workflow, or see the one-line fix below). (2) A presence-mode alarm added while tags are already present won't fire until presence next cycles — no fresh ON edge otherwise. (3) The reader daemon doesn't log directIOOutput at INFO; verify by reading the GPO pin state, not the journal.

The GPO is a polarized switch. Current enters GPO(+) pin 4 and exits GPO(−) pin 14. Wired backwards, an internal body diode conducts continuously — even with the reader powered off — and the obvious checks are blind to it (continuity reads correctly, a manual jumper works, the SSR tests fine standalone). The diagnostic that finds it is measuring with the reader unplugged. Captured in the code comments and docs/cs463-reader-references.md.

Deferred (follow-ups, not blockers)

• GPO safe-state on daemon start. The pulse timer lives in daemon memory, so a daemon restart mid-pulse leaves a port latched on until the next Gpo.Set. Worth a startup drive-all-low; deferred to its own ticket.
• Confirm the CS463 firmware actually emits resp.Error on rejected-port / /API-unreachable conditions — the Warn logging is in place cloud-side, but whether the reply carries an error in those cases is a hardware-confirmation item.
• Converting an existing Shelly device to GPO in the UI needs the reader set first (the inline switch_id/reader edits are row-owned per TRA-940); non-obvious but recoverable.
• scan_device_id FK has no ON DELETE — soft-delete + the fire-time deleted_at IS NULL join means soft-deleting a referenced reader disables its GPO alarms fail-closed, consistent with the design.
• sync-preview trigger gap (surfaced deploying this PR) — the workflow filters draft PRs but doesn't list ready_for_review in its pull_request types, so marking a PR ready never syncs it to preview. One-line fix (add ready_for_review to the trigger). Separate small PR.

Refs TRA-1028.

🤖 Generated with Claude Code

[github-actions]

🚀 Preview Deployment Update

✅ This PR has been successfully merged into the preview branch.

The preview environment will update shortly at: https://app.preview.trakrf.id