@myrobotaxi/contracts 0.1.0

package/schemas/ws-messages.schema.json

@@ -0,0 +1,295 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://myrobotaxi.com/schemas/ws-messages.schema.json",
+  "title": "WebSocketMessages",
+  "description": "JSON Schemas for every WebSocket payload exchanged between the telemetry server and SDK clients. The vehicle_update payload's `fields` map is a subset of the canonical VehicleState (see vehicle-state.schema.json); per-field types/units/classification live there and are NOT duplicated here. This file holds the wire-only shapes (envelope payloads, control messages, errors).",
+  "$defs": {
+    "AuthPayload": {
+      "type": "object",
+      "description": "Client->server authentication payload. The first frame on every WebSocket connection MUST be {type: 'auth', payload: {token: '...'}}. The token is opaque to the server's transport layer and is validated by the configured Authenticator (JWT in production, NoopAuthenticator in dev). Anchored by FR-6.1, NFR-3.21.",
+      "required": ["token"],
+      "additionalProperties": false,
+      "properties": {
+        "token": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Bearer-style session token resolved by the consumer's getToken() callback (FR-6.1). Server validates via Authenticator.ValidateToken. P1 — never log this value (data-classification.md §1.2).",
+          "x-classification": "P1"
+        }
+      }
+    },
+    "AuthOkPayload": {
+      "type": "object",
+      "description": "Server->client positive authentication acknowledgement. v1-required. Emitted as the FIRST frame after successful `Authenticator.ValidateToken` + `GetUserVehicles` + `Hub.Register`. Triggers the SDK `connectionState` transition `connecting -> connected` (state-machine C-3). Without this frame, SDKs on idle vehicles would sit in `connecting` up to one heartbeat interval waiting for telemetry traffic — an unacceptable regression on cold watchOS wakes. See websocket-protocol.md §2.3 for the full handshake contract. Note: `auth_ok` has been pulled OUT of divergence DV-07 and is v1-required; the rest of DV-07 (subscribe/unsubscribe/ping/pong + typed permission_denied) remains deferred. `state-machine.md` §1.3 C-3 trigger alignment is tracked as DV-15 (requires a follow-up MYR-10 amendment PR). Anchored by FR-6.1, FR-8.1, NFR-3.21.",
+      "required": ["userId", "vehicleCount", "issuedAt"],
+      "additionalProperties": false,
+      "properties": {
+        "userId": {
+          "type": "string",
+          "description": "Opaque cuid of the authenticated user. Echoed back from the resolved token so the SDK can sanity-check ownership set on reconnect (e.g., compare against a cached userId and clear caches if they disagree, defending against consumer token-mixup bugs). P1 per data-classification.md §1.1 User.id.",
+          "x-classification": "P1"
+        },
+        "vehicleCount": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Size of the user's vehicle set at handshake time (length of `Authenticator.GetUserVehicles(userId)`). Informational integrity check against the SDK's cached snapshot; the authoritative ownership set is populated via the REST snapshot fetch on reconnect (NFR-3.11). P1 because vehicle count leaks the shape of a user's fleet.",
+          "x-classification": "P1"
+        },
+        "issuedAt": {
+          "type": "string",
+          "format": "date-time",
+          "description": "Server-authoritative ISO 8601 UTC timestamp at which Hub.Register returned success. Debug/telemetry only — the SDK MUST NOT use this value for any behavioral decision. P2 because it reveals server-side timing to an observer.",
+          "x-classification": "P2"
+        }
+      }
+    },
+    "VehicleUpdatePayload": {
+      "type": "object",
+      "description": "Server->client telemetry update for a single vehicle. The `fields` map carries one or more atomic-group members from VehicleState (see vehicle-state.schema.json). Each call to broadcast carries fields from at most ONE atomic group plus optionally non-grouped fields delivered alongside (NFR-3.1). Anchored by FR-1.1, FR-1.2, FR-1.3, FR-2.1, FR-2.2, FR-2.3, NFR-3.1, NFR-3.2.",
+      "required": ["vehicleId", "fields", "timestamp"],
+      "additionalProperties": false,
+      "properties": {
+        "vehicleId": {
+          "type": "string",
+          "description": "Opaque database cuid for the vehicle (NOT the VIN). All SDK API calls use this ID per FR-4.2. VINs are P0 with mandatory last-4 redaction in logs (data-classification.md §2.1) and MUST NOT appear in this payload under any circumstance.",
+          "x-classification": "P0"
+        },
+        "fields": {
+          "type": "object",
+          "description": "Map of field name -> value. Field names and per-field classifications are defined in vehicle-state.schema.json. A single vehicle_update message contains the members of at most ONE atomic group plus any individually-delivered fields (speed, odometerMiles, interiorTemp, exteriorTemp, fsdMilesSinceReset, locationName, locationAddress, lastUpdated). v1 atomic groups: navigation = {destinationName, destinationAddress, destinationLatitude, destinationLongitude, originLatitude, originLongitude, etaMinutes, tripDistanceRemaining, navRouteCoordinates}; charge = {chargeLevel, chargeState, estimatedRange, timeToFull}; gps = {latitude, longitude, heading}; gear = {gearPosition, status}. The `drive` atomic group's single member `startedAt` is delivered via the `drive_started` lifecycle message, not via `vehicle_update.fields` — see DV-13 in websocket-protocol.md §10. Server explicitly clears a navigation field by sending it as JSON null; the SDK MUST atomically null all members of the affected group per NFR-3.9. The optional `driveTrailCoordinates` field (array of [lng, lat] pairs) carries an active drive's accumulated GPS trail (\"where the car has been\") and is not part of a normal atomic group — it is always paired with an active drive and routed to dataState.gps. It is semantically distinct from the navigation group's `navRouteCoordinates` (Tesla's planned route polyline; \"where the car is going\") and the two MUST NOT be conflated.",
+          "additionalProperties": true,
+          "x-classification": "mixed (per-field; see vehicle-state.schema.json)"
+        },
+        "timestamp": {
+          "type": "string",
+          "format": "date-time",
+          "description": "Server-authoritative ISO 8601 UTC timestamp for this update. Not the Tesla telemetry emission time — this is the server's `time.Now().UTC()` at broadcast (or the event's CreatedAt for non-nav fields). Drives the SDK's lastUpdated state and feeds NFR-3.11 snapshot resume.",
+          "x-classification": "P0"
+        }
+      }
+    },
+    "DriveStartedPayload": {
+      "type": "object",
+      "description": "Server->client message announcing the start of a new drive. Also carries the drive atomic group's `startedAt` field, which is the v1 home of `tripStartTime` (relocated from the navigation group per DV-13 — see websocket-protocol.md §4.2). The drive group is NOT delivered via vehicle_update.fields; it is delivered via this message. Anchored by FR-3.1, NFR-3.1.",
+      "required": ["vehicleId", "driveId", "startLocation", "startedAt", "timestamp"],
+      "additionalProperties": false,
+      "properties": {
+        "vehicleId": {
+          "type": "string",
+          "description": "Opaque vehicle cuid.",
+          "x-classification": "P0"
+        },
+        "driveId": {
+          "type": "string",
+          "description": "Opaque drive cuid. Matches the eventual Drive row's id when the drive completes and is persisted.",
+          "x-classification": "P0"
+        },
+        "startLocation": {
+          "type": "object",
+          "description": "GPS coordinates where the drive began. Encrypted at rest in the eventual Drive row but transported plaintext over WSS (NFR-3.22, NFR-3.25).",
+          "required": ["latitude", "longitude"],
+          "additionalProperties": false,
+          "properties": {
+            "latitude": {
+              "type": "number",
+              "minimum": -90,
+              "maximum": 90,
+              "x-classification": "P1",
+              "x-encrypted-at-rest": true
+            },
+            "longitude": {
+              "type": "number",
+              "minimum": -180,
+              "maximum": 180,
+              "x-classification": "P1",
+              "x-encrypted-at-rest": true
+            }
+          }
+        },
+        "startedAt": {
+          "type": "string",
+          "format": "date-time",
+          "description": "v1 home of `tripStartTime` (per DV-13). Server-authoritative ISO 8601 UTC timestamp at which the drive detector's `started_at` was recorded. SDKs MUST surface this as the authoritative tripStartTime for consumers. Value is always equal to `timestamp` for drive_started; the two fields are separate so `timestamp` can remain the uniform envelope-event time across every server->client message while `startedAt` carries the semantic drive-lifecycle meaning.",
+          "x-classification": "P0"
+        },
+        "timestamp": {
+          "type": "string",
+          "format": "date-time",
+          "description": "Server-authoritative ISO 8601 UTC timestamp at which the drive detector (`internal/drives/`) declared the drive started. Equal to `startedAt` for this message type.",
+          "x-classification": "P0"
+        }
+      }
+    },
+    "DriveEndedPayload": {
+      "type": "object",
+      "description": "Server->client message announcing a completed drive that passed the micro-drive filter (state-machine.md §3.5). The wire payload is intentionally a SUMMARY — it carries only the handful of fields the SDK needs for an immediate 'drive finished' toast or card. The full FR-3.4 drive record (energy used, FSD miles, intervention count, start/end charge level, start/end addresses, full route polyline) is fetched on demand via REST `GET /drives/{id}` (see rest-api.md) using the SDK's `fetchDrive(driveId)` helper. Neither the TypeScript nor the Swift SDK auto-fetches the full record on drive_ended; doing so would burn cellular bandwidth on idle consumers (per NFR-3.36, this is especially bad for watchOS). Tracked as DV-11 (RESOLVED) in websocket-protocol.md §10. Anchored by FR-3.1, FR-3.4.",
+      "required": ["vehicleId", "driveId", "distance", "durationSeconds", "avgSpeed", "maxSpeed", "timestamp"],
+      "additionalProperties": false,
+      "properties": {
+        "vehicleId": {
+          "type": "string",
+          "description": "Opaque vehicle cuid.",
+          "x-classification": "P0"
+        },
+        "driveId": {
+          "type": "string",
+          "description": "Opaque drive cuid (matches the persisted Drive row id). Input to `fetchDrive(driveId)` for the full FR-3.4 record.",
+          "x-classification": "P0"
+        },
+        "distance": {
+          "type": "number",
+          "minimum": 0,
+          "description": "Total distance driven in miles. Computed as the haversine sum of route points at drive completion.",
+          "x-unit": "miles",
+          "x-classification": "P0"
+        },
+        "durationSeconds": {
+          "type": "number",
+          "minimum": 0,
+          "description": "Drive duration in seconds, as a JSON number (double). Server-side value is `DriveStats.Duration.Seconds()`. This replaces the earlier `duration` string field (Go `time.Duration` format like '12m34s'), which was dropped before v1 ship — there are no pre-v1 consumers, so there is no deprecation tail. TypeScript consumers construct `Temporal.Duration` or a Date delta from this value; Swift consumers map directly to `Duration(secondsComponent:attosecondsComponent:)` or `TimeInterval`. Tracked as DV-12 (RESOLVED) in websocket-protocol.md §10.",
+          "x-unit": "seconds",
+          "x-classification": "P0"
+        },
+        "avgSpeed": {
+          "type": "number",
+          "minimum": 0,
+          "x-unit": "mph",
+          "x-classification": "P0"
+        },
+        "maxSpeed": {
+          "type": "number",
+          "minimum": 0,
+          "x-unit": "mph",
+          "x-classification": "P0"
+        },
+        "timestamp": {
+          "type": "string",
+          "format": "date-time",
+          "description": "Server-authoritative ISO 8601 UTC timestamp at which the drive detector declared the drive ended.",
+          "x-classification": "P0"
+        }
+      }
+    },
+    "ConnectivityPayload": {
+      "type": "object",
+      "description": "Server->client signal that a vehicle's mTLS connection to the telemetry server has changed state. This is vehicle<->server connectivity, NOT client<->server connectivity (the latter is implicit in the WebSocket connection itself). Anchored by FR-1.3 (extensibility) and FR-8.1 (state surface).",
+      "required": ["vehicleId", "online", "timestamp"],
+      "additionalProperties": false,
+      "properties": {
+        "vehicleId": {
+          "type": "string",
+          "x-classification": "P0"
+        },
+        "online": {
+          "type": "boolean",
+          "description": "True when the vehicle has an active mTLS Tesla Fleet Telemetry stream into the server. False on disconnect (e.g., vehicle asleep, network drop).",
+          "x-classification": "P0"
+        },
+        "timestamp": {
+          "type": "string",
+          "format": "date-time",
+          "x-classification": "P0"
+        }
+      }
+    },
+    "HeartbeatPayload": {
+      "type": "object",
+      "description": "Server->client keepalive frame. The current server emits a bare envelope `{\"type\":\"heartbeat\"}` with NO payload (heartbeat.go computes the message once at init). The optional `timestamp` field is reserved for future use. Anchored by NFR-3.10 (reconnect cadence).",
+      "additionalProperties": false,
+      "properties": {
+        "timestamp": {
+          "type": "string",
+          "format": "date-time",
+          "description": "OPTIONAL and NOT currently emitted. Reserved for future use to expose server clock to clients (would also enable client clock-skew detection). Tracked by follow-up issue.",
+          "x-classification": "P0"
+        }
+      }
+    },
+    "ErrorPayload": {
+      "type": "object",
+      "description": "Server->client error frame. The server sends this for transport-level failures the client must surface (auth rejection, auth timeout). The Code field is a stable enum that consumers branch on (FR-7.1) — never string-match the Message field. Anchored by FR-7.1, FR-7.3.",
+      "required": ["code", "message"],
+      "additionalProperties": false,
+      "properties": {
+        "code": {
+          "type": "string",
+          "description": "Stable typed error code from the catalog in websocket-protocol.md §6.1.1. Consumer SDKs map these to typed errors per FR-7.1 and MUST NOT string-match on the sibling `message` field. `auth_failed` and `auth_timeout` are emitted today; the remaining values are reserved for PLANNED server emission tracked by divergences DV-02 / DV-07 / DV-08 in websocket-protocol.md §10. `rate_limited` has two carriers: (a) an HTTP 429 response on the WS upgrade (per-IP cap breach, pre-auth) and (b) an `error` frame paired with WebSocket close code 4003 Server Overload (per-user cap breach, post-auth). The SDK MUST treat both carriers as the same typed error and apply the extended reconnect backoff documented in websocket-protocol.md §6.1.1 and §7.1.",
+          "enum": [
+            "auth_failed",
+            "auth_timeout",
+            "permission_denied",
+            "vehicle_not_owned",
+            "rate_limited",
+            "internal_error",
+            "snapshot_required"
+          ],
+          "x-classification": "P0"
+        },
+        "message": {
+          "type": "string",
+          "description": "Human-readable description for logs and developer tooling. P0 BUT MUST NOT contain P1 values (no GPS, no addresses, no tokens, no emails, no VINs unless redacted to ***XXXX). Per data-classification.md §2.1-2.2, error message construction sites MUST use opaque IDs only.",
+          "x-classification": "P0"
+        },
+        "subCode": {
+          "type": "string",
+          "description": "Optional typed sub-code for branching consumer-visible UI when the primary code is ambiguous across carriers. Currently defined only for `rate_limited`: when the server rejects a connection because it breached the per-user cap (post-auth, close 4003), the error frame MUST carry `subCode: \"device_cap\"` so SDKs can surface an actionable 'Too many devices signed in' message instead of a generic rate-limit toast. Per-IP breaches (HTTP 429 on upgrade) do NOT carry a sub-code because the SDK cannot distinguish NAT-mate floods from user intent. See websocket-protocol.md §6.1.1 for the full device_cap UX contract.",
+          "enum": ["device_cap"],
+          "x-classification": "P0"
+        }
+      }
+    },
+    "SubscribePayload": {
+      "type": "object",
+      "description": "PLANNED — NOT accepted by the server today. Client->server request to begin or resume streaming a specific vehicle. Today the server implicitly subscribes the client to ALL vehicles owned by the authenticated user as part of the auth handshake (handler.go authenticateClient -> Authenticator.GetUserVehicles). Adding explicit subscribe/unsubscribe is tracked as divergence DV-07 in websocket-protocol.md §10. `sinceSeq` snapshot-resume depends on divergence DV-02 (envelope `seq`) landing first.",
+      "required": ["vehicleId"],
+      "additionalProperties": false,
+      "properties": {
+        "vehicleId": {
+          "type": "string",
+          "x-classification": "P0"
+        },
+        "sinceSeq": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "PLANNED. Last envelope `seq` the client successfully processed for this vehicle. The server uses this to choose between snapshot-resume (replay missed frames) and full-refresh (REST snapshot fetch + live stream from current seq).",
+          "x-classification": "P0"
+        }
+      }
+    },
+    "UnsubscribePayload": {
+      "type": "object",
+      "description": "PLANNED — NOT accepted by the server today. Client->server request to stop receiving updates for a specific vehicle without closing the underlying WebSocket. Tracked as divergence DV-07 in websocket-protocol.md §10. Note: `auth_ok` has been pulled out of DV-07 and is v1-required (see AuthOkPayload); the rest of DV-07 remains deferred.",
+      "required": ["vehicleId"],
+      "additionalProperties": false,
+      "properties": {
+        "vehicleId": {
+          "type": "string",
+          "x-classification": "P0"
+        }
+      }
+    },
+    "PingPayload": {
+      "type": "object",
+      "description": "PLANNED — NOT accepted by the server today. Client->server ping. Today, browser clients rely on the server's outbound `heartbeat` frames (§7.4) and the underlying WebSocket protocol's PING/PONG control frames (handled transparently by coder/websocket) to detect liveness. An app-level `ping` is reserved for platforms where the WebSocket library does not expose RFC 6455 PING/PONG — specifically watchOS extended-runtime sessions and iOS background sockets, per NFR-3.36 / NFR-3.36a-d. The TypeScript SDK runs on browser `WebSocket` and Node `ws`, both of which expose transport-level PING/PONG, so this is a Swift-SDK forward-compatibility concern only. Tracked as divergence DV-07 in websocket-protocol.md §10. Note: `auth_ok` has been pulled out of DV-07 and is v1-required (see AuthOkPayload); the rest of DV-07 remains deferred.",
+      "additionalProperties": false,
+      "properties": {
+        "nonce": {
+          "type": "string",
+          "description": "Optional opaque value echoed back in the corresponding `pong` for round-trip latency measurement.",
+          "x-classification": "P0"
+        }
+      }
+    },
+    "PongPayload": {
+      "type": "object",
+      "description": "PLANNED — NOT emitted by the server today. Server->client response to a client-initiated `ping`. Echoes the nonce so the client can compute round-trip latency. Tracked as divergence DV-07 in websocket-protocol.md §10. Note: `auth_ok` has been pulled out of DV-07 and is v1-required (see AuthOkPayload); the rest of DV-07 remains deferred.",
+      "additionalProperties": false,
+      "properties": {
+        "nonce": {
+          "type": "string",
+          "x-classification": "P0"
+        }
+      }
+    }
+  }
+}