feat(heartbeat): add an embedded TCP/UDP push transport for constrained devices

[fclairamb]

Batch of four specs from specs/todos/, each implemented on its own and gated on an independent completeness audit before being archived to specs/done/2026/09/.

Embedded TCP/UDP heartbeat push transport

Heartbeat checks could only be fed over HTTPS, which shuts out the fleet the primitive fits best — microcontrollers, cellular modems driven by AT commands, battery sensors, legacy PLCs — because TLS costs tens of KB of RAM, a CA store and a correct clock. This adds two small listeners (one port number, 4001, on both TCP and UDP, off by default) speaking a one-line, netcat-debuggable protocol in two forms:

• SP1 — SP1 <org>/<check> <token> — plaintext token, convenience default.
• SP2 — SP2 <org>/<check> <ts> <ctr> <mac> — HMAC-SHA256 keyed with the check's token, no secret on the wire, ~80 bytes.

Replay protection is a strictly-increasing per-check counter enforced by the database itself (a single conditional upsert), so an old datagram fails and even the latest datagram cannot be replayed. The new per-check require_hmac option rejects SP1 outright; the dashboard pairs the toggle with a token-rotation nudge, because a check that ever accepted SP1 has leaked the key.

Beats carry an optional annotation (a status word plus logfmt key=value pairs). Numeric values land in the result's metrics jsonb, so battery volts and RSSI become first-class time series charted on the check page. An annotation never invalidates a beat — a firmware typo must not make a healthy device look dead.

Security posture is stated explicitly in the code and the docs: SP1 is replayable to mask an outage (that is what require_hmac closes), SP2 authenticates the message rather than the transport, and UDP source addresses are spoofable and are never treated as identity. UDP answers nothing at all on any failure — a nonexistent org is byte-identical to a bad MAC — and never replies with more bytes than it received.

New docs page: Embedded / push monitoring. Enabling the ports is a deployment decision (k8s Service / LB) and is documented, not automated.

gRPC checks: real phase breakdown and request metadata

connection_time_ms was fiction — grpc.NewClient is lazy, so the metric measured struct construction while the real DNS + TCP + TLS cost hid inside rpc_time_ms. The connection is now established eagerly and instrumented, reporting genuine dns_time_ms / connect_time_ms / tls_time_ms / rpc_time_ms, with failures classified by the phase that failed instead of collapsing into one opaque RPC error. Checking a service the server never registered now says so in words rather than surfacing a raw NotFound.

gRPC checks also gain metadata and encrypted secretMetadata, so a health endpoint behind an authenticating proxy can be checked at all — and the dashboard form is no longer a stub: TLS skip-verify, timeout and both metadata editors are now reachable.

Uptime report emails: trends, latency and worst-first ordering

The scheduled report showed one period in isolation. It now carries period-over-period deltas, a response-time block, average incident duration, and a check table sorted worst-first with a per-day availability strip — so a broken check can no longer sit invisibly at the bottom of a 50-row alphabetical table.

Considerable care went into the degenerate cases, because this is exactly where a digest starts lying: zero is never green, a missing baseline omits the delta entirely rather than rendering "±0.00%", a monitor down all period gets a plain factual sentence instead of a grid of zeros and a celebrated response-time "improvement" measured on error responses, and days before a check existed are gray rather than red. No MTBF, and no plan-upsell content in report emails by explicit product decision.

Dashboard polish

The "Getting started" checklist rows had no background of their own, so the card's tint bled through and completed rows looked identical to pending ones. Rows now carry an explicit surface with a faint emerald wash when done.

---

Changelog entries

feat(heartbeat): add an embedded TCP/UDP push transport so constrained devices can beat without TLS
feat(heartbeat): add the SP1/SP2 beat wire protocol, annotation parsing and the per-check require_hmac option
feat(dash0): show the embedded beat examples and the require_hmac toggle on heartbeat checks
feat(grpc): report a real DNS/connect/TLS/RPC phase breakdown and classify failures by phase
feat(grpc): support request metadata and encrypted secretMetadata, and complete the dashboard form
feat(uptimereport): add period-over-period trends, a response-time summary and a worst-first check table with a per-day strip
feat(heartbeat): expire an SP2 replay counter a week after the last beat
feat(dash0): give the Getting started checklist rows their own backgrounds and a done state
fix(checks): a heartbeat config PATCH no longer destroys the check's ping token
fix(uptimereport): render a zero previous-incident count instead of ""
fix(dash0): render the TCP beat one-liner's newline escape

Notes for review

• Two bugs were found and fixed in passing, neither in this batch's own new code: a heartbeat config PATCH silently destroyed the check's ping token (the public patch path is REPLACE, and Validate's regenerated token was discarded because it ran on a deep copy), and Data.PreviousIncidentCount carried omitempty, so the commonest healthy report — no incidents this month or last — printed <no value> where it meant 0.
• No new migration. The SP2 counter lives in the existing generic state_entries store rather than a dedicated table, matching the consolidation already made for OAuth storage in batch/2026-06-23: realtime v2 (WebSocket), scheduler lanes & fairness, discovery, maintenance windows, availability API (41 specs) #89. Strict monotonicity stays in the SQL WHERE clause on both dialects, never in Go — a read-modify-write there would reintroduce the replay race under exactly the concurrency a retried UDP datagram produces. Net DDL for this cycle is nothing, so there is no 018 file.
• Counters expire on a sliding 7-day window, refreshed by every accepted beat, so a beating device never expires its own counter and a check that went quiet stops occupying a row forever. That sweep is a soft delete and the guard ignores deleted_at, so a swept counter keeps refusing replays — pinned by a test per dialect. The one thing a future change should weigh is recorded in the code and the spec: if a hard purge of soft-deleted state entries is ever added, a clockless (ts=0) device silent for over a week could have an old beat replayed at it.
• Dev-database note: an earlier commit in this branch briefly added an 018_v0_22_0 migration that was withdrawn. A local dev database that ran it carries a bun_migrations row for a file that no longer exists. The runner tolerates that and boots normally, but reset any dev DB that ran it before a future 018 lands, rather than using migrate repair.