Define display boundary protocol v0

What crosses between svc-gw and the app: hello, heartbeats both ways, state snapshots of envelopes with mock flagged per message, and commands carrying an idempotency key. TTS utterances are left for when a TTS exists. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01DDwfd6Ki8UfG4hK6W5YpJz
2026-10-09 20:19:05 +09:00
parent 73eff1c5d6
commit b55ccba268
3 changed files with 71 additions and 14 deletions
@@ -0,0 +1,66 @@
+---
+type: reference
+---
+# Display boundary protocol — v0
+
+Between a display client (`app-flutter`) and [svc-gw](gitea:yukart/svc-gw). The
+bus topics in `schema/` stay inside the Orin; this is what crosses to the tablet.
+
+## Transport
+
+One WebSocket, `ws://<orin>:7700/`, JSON text messages, each with a `"t"` type.
+The tablet reaches the car Orin at `192.168.55.1` over USB NCM; the app binds to
+that network itself (see `app-flutter`'s initial plan).
+
+The client always connects and owns reconnection. svc-gw refuses peers outside
+loopback, RFC 1918 and the tailnet's 100.64.0.0/10.
+
+The two channels from decision 24 share the socket but keep different guarantees:
+
+| | Down (state) | Up (commands) |
+|---|---|---|
+| Loss | tolerated; svc-gw drops the oldest when a client lags (64-message queue) | not tolerated; retry until acked |
+| On reconnect | `hello`, then current state on the next tick | resend anything unacked, same `id` |
+
+## Down: svc-gw → client
+
+| `t` | When | Fields |
+|---|---|---|
+| `hello` | first message | `proto` (0), `server`, `host`, `source` (`mock` \| `none`), `mock`, `hb_ms`, `timeout_ms` |
+| `hb` | every `hb_ms` | `ts` (Orin epoch ms), `clients` |
+| `state` | 5 Hz, when there is a source | `seq`, `mock`, `signals`: name → envelope (`schema/envelope.json`) |
+| `ack` | reply to a `cmd` | `id`, `ok`, `detail`, `dup` (true when answered from the cache) |
+
+`signals` holds only what is currently known. A missing signal is unknown, a
+`null` value is known-without-value, `quality: "stale"` is an old value. All three
+are normal and a display must render each distinctly.
+
+⚠ **`mock: true` must be visible on the display surface** whenever it appears in
+`hello` or in any envelope. Not in a settings page, not in a log.
+
+## Up: client → svc-gw
+
+| `t` | When | Fields |
+|---|---|---|
+| `hb` | every `hb_ms` | — |
+| `cmd` | on user action | `id` (unique, the idempotency key), `cmd`, `args` |
+
+svc-gw drops a client silent for `timeout_ms` (5 s). The client should treat
+`timeout_ms` without any downstream message the same way and reconnect: an asleep
+tablet, or an Orin behind a replugged hub, looks connected at the link layer.
+
+### Commands
+
+| `cmd` | `args` | Effect |
+|---|---|---|
+| `ping` | — | `ack` with `detail: "pong"` |
+| `mark` | `text`, `delay_ms` (optional: how long the command waited before this send) | stamped into the open recording; fails with no session open |
+
+A repeated `id` returns the original `ack` (last 256 kept, shared across
+connections) and never re-runs the command.
+
+## Not yet
+
+- TTS utterances (id, chunk sequence, terminator, expiry) — when there is a TTS.
+- `gnss` and decoded vehicle state from the bus — when the bus exists.
+- Any version beyond `proto: 0`. A breaking change bumps it; the client checks it.