@myrobotaxi/contracts 0.5.0 → 0.7.0

package/dist/types.d.ts

@@ -338,6 +338,375 @@ interface VehicleSummary {
     role: 'owner' | 'viewer';
 }
 
+/**
+ * AUTO-GENERATED by scripts/codegen.mjs from the corresponding JSON Schema
+ * in ../schemas/. DO NOT EDIT BY HAND — re-run `npm run codegen` instead.
+ *
+ * The x-classification / x-atomic-group / x-unit / x-encrypted custom JSON
+ * Schema annotations from the source schemas are folded into the generated
+ * TSDoc comments so grep can find them without leaving the editor.
+ */
+/**
+ * Cursor-paginated envelope returned by GET /api/vehicles/{vehicleId}/drives (rest-api.md §7.2). Wraps an array of DriveSummary rows under `items`, newest first (ORDER BY startTime DESC, id DESC). Mirrors the Go `drivesPageResponse` struct in telemetry/internal/telemetry/vehicle_drives_types.go and the `PaginatedDrives` component in telemetry/docs/contracts/specs/rest.openapi.yaml. Pairs with the WebSocket `drive_ended` subscription for FR-9.1/FR-9.2: the SDK hydrates the first page here and prepends live `drive_ended` frames without re-fetching. The envelope is part of the wire contract: consumers MUST NOT strip it silently.
+ */
+interface DrivesListResponse {
+    /**
+     * Drive summary rows for this page. Always present; an empty array (never null) means no more drives — e.g. the final page or a vehicle with no completed drives. Ordered startTime DESC, id DESC (rest-api.md §7.2 Ordering).
+     *
+     * @classification "P0"
+     */
+    items: DriveSummary[];
+    /**
+     * Opaque base64 cursor for the next page, or null on the final page. Pass it back as the `cursor` query param to fetch the next page. Encodes (startTime, id) so pagination is stable across concurrent writes. Nullable on the wire — the Go server emits JSON `null` (not an omitted key) when there is no further page (drivesPageResponse.NextCursor is a `*string` with no omitempty, telemetry/internal/telemetry/vehicle_drives_types.go). Redundant with `hasMore == false`.
+     *
+     * @classification "P0"
+     */
+    nextCursor: string | null;
+    /**
+     * True iff more pages exist after this one. Redundant with `nextCursor != null`, provided for caller convenience.
+     *
+     * @classification "P0"
+     */
+    hasMore: boolean;
+}
+/**
+ * Lightweight per-drive row returned by GET /api/vehicles/{vehicleId}/drives. A list-view projection of a completed drive containing the FR-3.4 headline stats plus origin/destination labels, so the history list renders without a per-row DriveDetail fetch. Includes the four P1 location/address labels (MYR-145) and the P0 fsdMiles/fsdPercentage stats (MYR-152). Deliberately omits energyUsedKwh, interventions, and routePoints — those live on Drive (drive detail, §7.3) and DriveRoute (§7.4). Mirrors the Go `driveSummary` struct + `toMaskMap` in telemetry/internal/telemetry/vehicle_drives_types.go and the `DriveSummary` component in telemetry/docs/contracts/specs/rest.openapi.yaml.
+ *
+ * This interface was referenced by `DrivesListResponse`'s JSON-Schema
+ * via the `definition` "DriveSummary".
+ */
+interface DriveSummary {
+    /**
+     * Opaque database identifier (cuid) for this drive. Matches the `driveId` carried by `drive_started` / `drive_ended` WebSocket frames and the path param of GET /api/drives/{driveId}.
+     *
+     * @classification "P0"
+     */
+    id: string;
+    /**
+     * Opaque database identifier (cuid) for the drive's parent vehicle. Matches VehicleState.vehicleId / VehicleSummary.vehicleId.
+     *
+     * @classification "P0"
+     */
+    vehicleId: string;
+    /**
+     * ISO 8601 / RFC 3339 UTC timestamp when the drive began (e.g., '2026-04-13T18:22:00Z').
+     *
+     * @classification "P0"
+     */
+    startTime: string;
+    /**
+     * ISO 8601 / RFC 3339 UTC timestamp when the drive ended (e.g., '2026-04-13T18:46:18Z').
+     *
+     * @classification "P0"
+     */
+    endTime: string;
+    /**
+     * Local calendar date of the drive as a 'YYYY-MM-DD' string (e.g., '2026-04-13'), for day-grouping the history list. Not a full timestamp — use startTime/endTime for instants.
+     *
+     * @classification "P0"
+     */
+    date: string;
+    /**
+     * Reverse-geocoded place name at the drive's start (e.g., 'Home', 'Whole Foods Market'). OPTIONAL on the wire: the Go handler OMITS this key entirely (never emits '' or null) when the underlying Drive.startLocation column is empty — zero-GPS at drive start or reverse-geocode failed (toMaskMap, telemetry/internal/telemetry/vehicle_drives_types.go). Consumers branch on key presence.
+     *
+     * @classification "P1"
+     */
+    startLocation?: string;
+    /**
+     * Reverse-geocoded street address at the drive's start. OPTIONAL on the wire: the key is omitted entirely when the underlying Drive.startAddress column is empty (same omit-when-empty convention as startLocation).
+     *
+     * @classification "P1"
+     */
+    startAddress?: string;
+    /**
+     * Reverse-geocoded place name at the drive's end. OPTIONAL on the wire: the key is omitted entirely when the underlying Drive.endLocation column is empty — drive in progress, zero-GPS at drive end, or reverse-geocode failed.
+     *
+     * @classification "P1"
+     */
+    endLocation?: string;
+    /**
+     * Reverse-geocoded street address at the drive's end. OPTIONAL on the wire: the key is omitted entirely when the underlying Drive.endAddress column is empty.
+     *
+     * @classification "P1"
+     */
+    endAddress?: string;
+    /**
+     * Total distance driven, in miles (FR-3.4).
+     *
+     * @classification "P0"
+     * @unit "miles"
+     */
+    distanceMiles: number;
+    /**
+     * Total drive duration, in seconds (FR-3.4). The Go server converts the stored DurationMinutes to seconds (DurationMinutes * 60) before emitting. Matches the WebSocket drive_ended.payload.durationSeconds shape (DV-12).
+     *
+     * @classification "P0"
+     * @unit "seconds"
+     */
+    durationSeconds: number;
+    /**
+     * Average speed over the drive, in miles per hour (FR-3.4).
+     *
+     * @classification "P0"
+     * @unit "mph"
+     */
+    avgSpeedMph: number;
+    /**
+     * Maximum speed reached during the drive, in miles per hour (FR-3.4).
+     *
+     * @classification "P0"
+     * @unit "mph"
+     */
+    maxSpeedMph: number;
+    /**
+     * Battery state of charge at drive start (FR-3.4).
+     *
+     * @classification "P0"
+     * @unit "percent"
+     */
+    startChargeLevel: number;
+    /**
+     * Battery state of charge at drive end (FR-3.4).
+     *
+     * @classification "P0"
+     * @unit "percent"
+     */
+    endChargeLevel: number;
+    /**
+     * Miles driven under Full Self-Driving during this drive (FR-3.4, MYR-152). Always present; defaults to 0 for a drive with no FSD usage.
+     *
+     * @classification "P0"
+     * @unit "miles"
+     */
+    fsdMiles: number;
+    /**
+     * Percent of the drive covered by FSD (FR-3.4, MYR-152). Always present; defaults to 0 for a drive with no FSD usage.
+     *
+     * @classification "P0"
+     * @unit "percent"
+     */
+    fsdPercentage: number;
+    /**
+     * ISO 8601 / RFC 3339 UTC row-creation timestamp. The Go server renders it as `CreatedAt.UTC().Format(time.RFC3339)` (telemetry/internal/telemetry/vehicle_drives_types.go).
+     *
+     * @classification "P0"
+     */
+    createdAt: string;
+}
+
+/**
+ * AUTO-GENERATED by scripts/codegen.mjs from the corresponding JSON Schema
+ * in ../schemas/. DO NOT EDIT BY HAND — re-run `npm run codegen` instead.
+ *
+ * The x-classification / x-atomic-group / x-unit / x-encrypted custom JSON
+ * Schema annotations from the source schemas are folded into the generated
+ * TSDoc comments so grep can find them without leaving the editor.
+ */
+/**
+ * Full FR-3.4 record for a single completed drive, returned as a bare object (NOT an envelope) by GET /api/drives/{driveId} (rest-api.md §7.3). Contains every FR-3.4 stat EXCEPT routePoints, which is served separately by GET /api/drives/{driveId}/route (DriveRoute, §7.4). This is the tap-through detail behind a DriveSummary row / a `drive_ended` frame: the SDK's fetchDrive(driveId) helper. Mirrors the Go `driveDetail` struct + `toMaskMap` in telemetry/internal/telemetry/drive_detail_types.go and the `DriveDetail` component in telemetry/docs/contracts/specs/rest.openapi.yaml. Owners and viewers see the same field set including start/end location and address (viewer consent via accepted invite, §5.2.3).
+ */
+interface Drive {
+    /**
+     * Opaque database identifier (cuid) for this drive. Matches DriveSummary.id and the `driveId` carried by `drive_started` / `drive_ended` WebSocket frames.
+     *
+     * @classification "P0"
+     */
+    id: string;
+    /**
+     * Opaque database identifier (cuid) for the drive's parent vehicle. Matches VehicleState.vehicleId / VehicleSummary.vehicleId / DriveSummary.vehicleId.
+     *
+     * @classification "P0"
+     */
+    vehicleId: string;
+    /**
+     * ISO 8601 / RFC 3339 UTC timestamp when the drive began (e.g., '2026-04-13T18:22:00Z').
+     *
+     * @classification "P0"
+     */
+    startTime: string;
+    /**
+     * ISO 8601 / RFC 3339 UTC timestamp when the drive ended (e.g., '2026-04-13T18:46:18Z').
+     *
+     * @classification "P0"
+     */
+    endTime: string;
+    /**
+     * Local calendar date of the drive as a 'YYYY-MM-DD' string (e.g., '2026-04-13'). Same field as DriveSummary.date.
+     *
+     * @classification "P0"
+     */
+    date: string;
+    /**
+     * Total distance driven, in miles (FR-3.4).
+     *
+     * @classification "P0"
+     * @unit "miles"
+     */
+    distanceMiles: number;
+    /**
+     * Total drive duration, in seconds (FR-3.4). The Go server converts the stored DurationMinutes to seconds (DurationMinutes * 60) before emitting.
+     *
+     * @classification "P0"
+     * @unit "seconds"
+     */
+    durationSeconds: number;
+    /**
+     * Average speed over the drive, in miles per hour (FR-3.4).
+     *
+     * @classification "P0"
+     * @unit "mph"
+     */
+    avgSpeedMph: number;
+    /**
+     * Maximum speed reached during the drive, in miles per hour (FR-3.4).
+     *
+     * @classification "P0"
+     * @unit "mph"
+     */
+    maxSpeedMph: number;
+    /**
+     * Energy consumed during the drive, in kilowatt-hours (FR-3.4). Detail-only stat — deliberately absent from DriveSummary.
+     *
+     * @classification "P0"
+     * @unit "kWh"
+     */
+    energyUsedKwh: number;
+    /**
+     * Battery state of charge at drive start (FR-3.4).
+     *
+     * @classification "P0"
+     * @unit "percent"
+     */
+    startChargeLevel: number;
+    /**
+     * Battery state of charge at drive end (FR-3.4).
+     *
+     * @classification "P0"
+     * @unit "percent"
+     */
+    endChargeLevel: number;
+    /**
+     * Miles driven under Full Self-Driving during this drive (FR-3.4). Always present; defaults to 0 for a drive with no FSD usage.
+     *
+     * @classification "P0"
+     * @unit "miles"
+     */
+    fsdMiles: number;
+    /**
+     * Percent of the drive covered by FSD (FR-3.4). Always present; defaults to 0 for a drive with no FSD usage.
+     *
+     * @classification "P0"
+     * @unit "percent"
+     */
+    fsdPercentage: number;
+    /**
+     * Count of FSD interventions recorded during the drive (FR-3.4). Detail-only stat — deliberately absent from DriveSummary.
+     *
+     * @classification "P0"
+     */
+    interventions: number;
+    /**
+     * Reverse-geocoded place name at the drive's start (e.g., 'Home'). OPTIONAL on the wire: the Go handler OMITS this key entirely (never emits '' or null) when the underlying Drive.startLocation column is empty (toMaskMap, telemetry/internal/telemetry/drive_detail_types.go). Consumers branch on key presence. NOTE: the OpenAPI DriveDetail component types this `[string, null]`, but the Go handler omits the key rather than emitting null — the code is ground truth (see MYR-202 PR body doc-drift note).
+     *
+     * @classification "P1"
+     */
+    startLocation?: string;
+    /**
+     * Reverse-geocoded street address at the drive's start. OPTIONAL on the wire: the key is omitted entirely when the underlying Drive.startAddress column is empty (same omit-when-empty convention as startLocation).
+     *
+     * @classification "P1"
+     */
+    startAddress?: string;
+    /**
+     * Reverse-geocoded place name at the drive's end. OPTIONAL on the wire: the key is omitted entirely when the underlying Drive.endLocation column is empty.
+     *
+     * @classification "P1"
+     */
+    endLocation?: string;
+    /**
+     * Reverse-geocoded street address at the drive's end. OPTIONAL on the wire: the key is omitted entirely when the underlying Drive.endAddress column is empty.
+     *
+     * @classification "P1"
+     */
+    endAddress?: string;
+    /**
+     * ISO 8601 / RFC 3339 UTC row-creation timestamp. The Go server renders it as `CreatedAt.UTC().Format(time.RFC3339)` (telemetry/internal/telemetry/drive_detail_types.go).
+     *
+     * @classification "P0"
+     */
+    createdAt: string;
+}
+
+/**
+ * AUTO-GENERATED by scripts/codegen.mjs from the corresponding JSON Schema
+ * in ../schemas/. DO NOT EDIT BY HAND — re-run `npm run codegen` instead.
+ *
+ * The x-classification / x-atomic-group / x-unit / x-encrypted custom JSON
+ * Schema annotations from the source schemas are folded into the generated
+ * TSDoc comments so grep can find them without leaving the editor.
+ */
+/**
+ * Full GPS polyline for a single completed drive, returned as a bare object by GET /api/drives/{driveId}/route (rest-api.md §7.4, FR-3.3). This is the heavy per-drive route payload deliberately excluded from both DriveSummary (§7.2) and Drive detail (§7.3): the SDK fetches it lazily on tap-through of a drive's map view, NOT eagerly per drive-list row (see §7.4 lazy-fetch guidance — cellular bandwidth / perceived latency, not heap pressure). The polyline is AES-256-GCM encrypted at rest on Drive.routePoints (NFR-3.23, data-classification.md §1.5) and decrypted in the store layer (NFR-3.25) before the handler serializes it; the SDK never sees ciphertext. Mirrors the Go `driveRouteResponse` struct in telemetry/internal/telemetry/drive_route_handler.go and the `DriveRoute` component in telemetry/docs/contracts/specs/rest.openapi.yaml. NOTE: the handler passes `routePoints` through as `json.RawMessage` (raw decrypted JSONB) — the per-point shape is owned by the writer that persisted it (store.RoutePointRecord, telemetry/internal/store/types.go), so RoutePoint below documents that persisted format field-for-field.
+ */
+interface DriveRoute {
+    /**
+     * Opaque database identifier (cuid) for this drive. Echoes the `driveId` path param and matches Drive.id / DriveSummary.id and the `driveId` carried by `drive_started` / `drive_ended` WebSocket frames. Always present (Go `driveRouteResponse.DriveID`, no omitempty).
+     *
+     * @classification "P0"
+     */
+    driveId: string;
+    /**
+     * Ordered GPS breadcrumb trail for the drive, oldest point first, suitable for rendering the drive's polyline on a map. ALWAYS PRESENT and ALWAYS AN ARRAY, never null: the Go handler substitutes an empty `[]` when the underlying Drive.routePoints column is empty/absent (writeMaskedRoute, telemetry/internal/telemetry/drive_route_handler.go) — so a very short drive with no captured points, or a route that failed to decrypt, yields `[]` rather than a missing key or null. A 60-minute drive captured at ~1 Hz is roughly 3,600 points (~200-300 KB JSON); no server-side downsampling or paging — the entire polyline is returned in one response (there is no cursor/limit on this endpoint, unlike the §7.2 drives list).
+     *
+     * @classification "mixed"
+     */
+    routePoints: RoutePoint[];
+}
+/**
+ * A single GPS sample on a drive's polyline. Matches the `RoutePointRecord` shape from data-classification.md §1.5 — the JSONB element format persisted by the Go writer (store.RoutePointRecord, telemetry/internal/store/types.go) and the legacy Next.js app. lat/lng are P1 (identifying GPS); speed, heading, and timestamp are P0 in isolation but are encrypted at rest as a unit inside the P1 routePoints column (NFR-3.23) and MUST NOT be logged separately. All five fields are always present on the wire (the Go struct carries no omitempty). Mirrors the `RoutePoint` component in telemetry/docs/contracts/specs/rest.openapi.yaml.
+ *
+ * This interface was referenced by `DriveRoute`'s JSON-Schema
+ * via the `definition` "RoutePoint".
+ */
+interface RoutePoint {
+    /**
+     * Latitude in degrees at this point. Emitted as a JSON number (Go float64); whole-degree values serialize without a decimal point (Go shortest-float marshaling), so `10` and `10.0000` are the same value on the wire.
+     *
+     * @classification "P1"
+     * @unit "degrees"
+     * @encrypted-at-rest true
+     */
+    lat: number;
+    /**
+     * Longitude in degrees at this point. Emitted as a JSON number (Go float64).
+     *
+     * @classification "P1"
+     * @unit "degrees"
+     * @encrypted-at-rest true
+     */
+    lng: number;
+    /**
+     * Instantaneous speed at this point, in miles per hour. P0 in isolation but encrypted at rest alongside the parent P1 routePoints column. Emitted as a JSON number (Go float64).
+     *
+     * @classification "P0"
+     * @unit "mph"
+     */
+    speed: number;
+    /**
+     * Compass heading at this point, in degrees (0-360, 0 = North). P0 in isolation but encrypted at rest alongside the parent P1 routePoints column. Emitted as a JSON number (Go float64).
+     *
+     * @classification "P0"
+     * @unit "degrees"
+     */
+    heading: number;
+    /**
+     * ISO 8601 / RFC 3339 UTC timestamp at which this point was captured. The Go writer renders it as `Timestamp.Format(time.RFC3339)` (telemetry/internal/store/drive_mapper.go). P0 in isolation but encrypted at rest alongside the parent P1 routePoints column.
+     *
+     * @classification "P0"
+     */
+    timestamp: string;
+}
+
 /**
  * AUTO-GENERATED by scripts/codegen.mjs from the corresponding JSON Schema
  * in ../schemas/. DO NOT EDIT BY HAND — re-run `npm run codegen` instead.
@@ -681,4 +1050,4 @@ interface WebSocketEnvelope {
     ts?: string;
 }
 
-export type { AuthOkPayload, AuthPayload, ConnectivityPayload, DriveEndedPayload, DriveStartedPayload, ErrorPayload, HeartbeatPayload, MessageType, PingPayload, PongPayload, SubscribePayload, UnsubscribePayload, VehicleListResponse, VehicleState, VehicleSummary, VehicleUpdatePayload, WebSocketEnvelope, WebSocketMessages };
+export type { AuthOkPayload, AuthPayload, ConnectivityPayload, Drive, DriveEndedPayload, DriveRoute, DriveStartedPayload, DriveSummary, DrivesListResponse, ErrorPayload, HeartbeatPayload, MessageType, PingPayload, PongPayload, RoutePoint, SubscribePayload, UnsubscribePayload, VehicleListResponse, VehicleState, VehicleSummary, VehicleUpdatePayload, WebSocketEnvelope, WebSocketMessages };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@myrobotaxi/contracts",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "Canonical wire-protocol schemas for the MyRoboTaxi platform. JSON Schema (draft-2020-12) + pre-generated TypeScript types. Consumed by SDKs (TS, Swift) and the Go telemetry server.",
   "license": "MIT",
   "repository": {
@@ -39,6 +39,9 @@
     },
     "./schemas/vehicle-state.json": "./schemas/vehicle-state.schema.json",
     "./schemas/vehicle-summary.json": "./schemas/vehicle-summary.schema.json",
+    "./schemas/drives-list.json": "./schemas/drives-list.schema.json",
+    "./schemas/drive-detail.json": "./schemas/drive-detail.schema.json",
+    "./schemas/drive-route.json": "./schemas/drive-route.schema.json",
     "./schemas/ws-messages.json": "./schemas/ws-messages.schema.json",
     "./schemas/ws-envelope.json": "./schemas/ws-envelope.schema.json"
   },

package/schemas/drive-detail.schema.json

@@ -0,0 +1,174 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://myrobotaxi.com/schemas/drive-detail.schema.json",
+  "title": "Drive",
+  "description": "Full FR-3.4 record for a single completed drive, returned as a bare object (NOT an envelope) by GET /api/drives/{driveId} (rest-api.md §7.3). Contains every FR-3.4 stat EXCEPT routePoints, which is served separately by GET /api/drives/{driveId}/route (DriveRoute, §7.4). This is the tap-through detail behind a DriveSummary row / a `drive_ended` frame: the SDK's fetchDrive(driveId) helper. Mirrors the Go `driveDetail` struct + `toMaskMap` in telemetry/internal/telemetry/drive_detail_types.go and the `DriveDetail` component in telemetry/docs/contracts/specs/rest.openapi.yaml. Owners and viewers see the same field set including start/end location and address (viewer consent via accepted invite, §5.2.3).",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "id",
+    "vehicleId",
+    "startTime",
+    "endTime",
+    "date",
+    "distanceMiles",
+    "durationSeconds",
+    "avgSpeedMph",
+    "maxSpeedMph",
+    "energyUsedKwh",
+    "startChargeLevel",
+    "endChargeLevel",
+    "fsdMiles",
+    "fsdPercentage",
+    "interventions",
+    "createdAt"
+  ],
+  "properties": {
+    "id": {
+      "type": "string",
+      "description": "Opaque database identifier (cuid) for this drive. Matches DriveSummary.id and the `driveId` carried by `drive_started` / `drive_ended` WebSocket frames.",
+      "x-classification": "P0",
+      "examples": ["clmno9876543210zyxw0001"]
+    },
+    "vehicleId": {
+      "type": "string",
+      "description": "Opaque database identifier (cuid) for the drive's parent vehicle. Matches VehicleState.vehicleId / VehicleSummary.vehicleId / DriveSummary.vehicleId.",
+      "x-classification": "P0",
+      "examples": ["clxyz1234567890abcdef"]
+    },
+    "startTime": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO 8601 / RFC 3339 UTC timestamp when the drive began (e.g., '2026-04-13T18:22:00Z').",
+      "x-classification": "P0",
+      "examples": ["2026-04-13T18:22:00Z"]
+    },
+    "endTime": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO 8601 / RFC 3339 UTC timestamp when the drive ended (e.g., '2026-04-13T18:46:18Z').",
+      "x-classification": "P0",
+      "examples": ["2026-04-13T18:46:18Z"]
+    },
+    "date": {
+      "type": "string",
+      "format": "date",
+      "description": "Local calendar date of the drive as a 'YYYY-MM-DD' string (e.g., '2026-04-13'). Same field as DriveSummary.date.",
+      "x-classification": "P0",
+      "examples": ["2026-04-13"]
+    },
+    "distanceMiles": {
+      "type": "number",
+      "description": "Total distance driven, in miles (FR-3.4).",
+      "x-classification": "P0",
+      "x-unit": "miles",
+      "minimum": 0,
+      "examples": [12.4]
+    },
+    "durationSeconds": {
+      "type": "integer",
+      "description": "Total drive duration, in seconds (FR-3.4). The Go server converts the stored DurationMinutes to seconds (DurationMinutes * 60) before emitting.",
+      "x-classification": "P0",
+      "x-unit": "seconds",
+      "minimum": 0,
+      "examples": [1458]
+    },
+    "avgSpeedMph": {
+      "type": "number",
+      "description": "Average speed over the drive, in miles per hour (FR-3.4).",
+      "x-classification": "P0",
+      "x-unit": "mph",
+      "minimum": 0,
+      "examples": [30.5]
+    },
+    "maxSpeedMph": {
+      "type": "number",
+      "description": "Maximum speed reached during the drive, in miles per hour (FR-3.4).",
+      "x-classification": "P0",
+      "x-unit": "mph",
+      "minimum": 0,
+      "examples": [65.2]
+    },
+    "energyUsedKwh": {
+      "type": "number",
+      "description": "Energy consumed during the drive, in kilowatt-hours (FR-3.4). Detail-only stat — deliberately absent from DriveSummary.",
+      "x-classification": "P0",
+      "x-unit": "kWh",
+      "minimum": 0,
+      "examples": [4.2]
+    },
+    "startChargeLevel": {
+      "type": "integer",
+      "description": "Battery state of charge at drive start (FR-3.4).",
+      "x-classification": "P0",
+      "x-unit": "percent",
+      "minimum": 0,
+      "maximum": 100,
+      "examples": [82]
+    },
+    "endChargeLevel": {
+      "type": "integer",
+      "description": "Battery state of charge at drive end (FR-3.4).",
+      "x-classification": "P0",
+      "x-unit": "percent",
+      "minimum": 0,
+      "maximum": 100,
+      "examples": [76]
+    },
+    "fsdMiles": {
+      "type": "number",
+      "description": "Miles driven under Full Self-Driving during this drive (FR-3.4). Always present; defaults to 0 for a drive with no FSD usage.",
+      "x-classification": "P0",
+      "x-unit": "miles",
+      "minimum": 0,
+      "examples": [8.1]
+    },
+    "fsdPercentage": {
+      "type": "number",
+      "description": "Percent of the drive covered by FSD (FR-3.4). Always present; defaults to 0 for a drive with no FSD usage.",
+      "x-classification": "P0",
+      "x-unit": "percent",
+      "minimum": 0,
+      "maximum": 100,
+      "examples": [65.3]
+    },
+    "interventions": {
+      "type": "integer",
+      "description": "Count of FSD interventions recorded during the drive (FR-3.4). Detail-only stat — deliberately absent from DriveSummary.",
+      "x-classification": "P0",
+      "minimum": 0,
+      "examples": [1]
+    },
+    "startLocation": {
+      "type": "string",
+      "description": "Reverse-geocoded place name at the drive's start (e.g., 'Home'). OPTIONAL on the wire: the Go handler OMITS this key entirely (never emits '' or null) when the underlying Drive.startLocation column is empty (toMaskMap, telemetry/internal/telemetry/drive_detail_types.go). Consumers branch on key presence. NOTE: the OpenAPI DriveDetail component types this `[string, null]`, but the Go handler omits the key rather than emitting null — the code is ground truth (see MYR-202 PR body doc-drift note).",
+      "x-classification": "P1",
+      "examples": ["Home"]
+    },
+    "startAddress": {
+      "type": "string",
+      "description": "Reverse-geocoded street address at the drive's start. OPTIONAL on the wire: the key is omitted entirely when the underlying Drive.startAddress column is empty (same omit-when-empty convention as startLocation).",
+      "x-classification": "P1",
+      "examples": ["742 Evergreen Terrace, San Francisco, CA 94107"]
+    },
+    "endLocation": {
+      "type": "string",
+      "description": "Reverse-geocoded place name at the drive's end. OPTIONAL on the wire: the key is omitted entirely when the underlying Drive.endLocation column is empty.",
+      "x-classification": "P1",
+      "examples": ["Whole Foods Market"]
+    },
+    "endAddress": {
+      "type": "string",
+      "description": "Reverse-geocoded street address at the drive's end. OPTIONAL on the wire: the key is omitted entirely when the underlying Drive.endAddress column is empty.",
+      "x-classification": "P1",
+      "examples": ["399 4th Street, San Francisco, CA 94107"]
+    },
+    "createdAt": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO 8601 / RFC 3339 UTC row-creation timestamp. The Go server renders it as `CreatedAt.UTC().Format(time.RFC3339)` (telemetry/internal/telemetry/drive_detail_types.go).",
+      "x-classification": "P0",
+      "examples": ["2026-04-13T18:46:19Z"]
+    }
+  }
+}

package/schemas/drive-route.schema.json

@@ -0,0 +1,78 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://myrobotaxi.com/schemas/drive-route.schema.json",
+  "title": "DriveRoute",
+  "description": "Full GPS polyline for a single completed drive, returned as a bare object by GET /api/drives/{driveId}/route (rest-api.md §7.4, FR-3.3). This is the heavy per-drive route payload deliberately excluded from both DriveSummary (§7.2) and Drive detail (§7.3): the SDK fetches it lazily on tap-through of a drive's map view, NOT eagerly per drive-list row (see §7.4 lazy-fetch guidance — cellular bandwidth / perceived latency, not heap pressure). The polyline is AES-256-GCM encrypted at rest on Drive.routePoints (NFR-3.23, data-classification.md §1.5) and decrypted in the store layer (NFR-3.25) before the handler serializes it; the SDK never sees ciphertext. Mirrors the Go `driveRouteResponse` struct in telemetry/internal/telemetry/drive_route_handler.go and the `DriveRoute` component in telemetry/docs/contracts/specs/rest.openapi.yaml. NOTE: the handler passes `routePoints` through as `json.RawMessage` (raw decrypted JSONB) — the per-point shape is owned by the writer that persisted it (store.RoutePointRecord, telemetry/internal/store/types.go), so RoutePoint below documents that persisted format field-for-field.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["driveId", "routePoints"],
+  "properties": {
+    "driveId": {
+      "type": "string",
+      "description": "Opaque database identifier (cuid) for this drive. Echoes the `driveId` path param and matches Drive.id / DriveSummary.id and the `driveId` carried by `drive_started` / `drive_ended` WebSocket frames. Always present (Go `driveRouteResponse.DriveID`, no omitempty).",
+      "x-classification": "P0",
+      "examples": ["clmno9876543210zyxw0001"]
+    },
+    "routePoints": {
+      "type": "array",
+      "description": "Ordered GPS breadcrumb trail for the drive, oldest point first, suitable for rendering the drive's polyline on a map. ALWAYS PRESENT and ALWAYS AN ARRAY, never null: the Go handler substitutes an empty `[]` when the underlying Drive.routePoints column is empty/absent (writeMaskedRoute, telemetry/internal/telemetry/drive_route_handler.go) — so a very short drive with no captured points, or a route that failed to decrypt, yields `[]` rather than a missing key or null. A 60-minute drive captured at ~1 Hz is roughly 3,600 points (~200-300 KB JSON); no server-side downsampling or paging — the entire polyline is returned in one response (there is no cursor/limit on this endpoint, unlike the §7.2 drives list).",
+      "x-classification": "mixed",
+      "items": { "$ref": "#/$defs/RoutePoint" }
+    }
+  },
+  "$defs": {
+    "RoutePoint": {
+      "title": "RoutePoint",
+      "description": "A single GPS sample on a drive's polyline. Matches the `RoutePointRecord` shape from data-classification.md §1.5 — the JSONB element format persisted by the Go writer (store.RoutePointRecord, telemetry/internal/store/types.go) and the legacy Next.js app. lat/lng are P1 (identifying GPS); speed, heading, and timestamp are P0 in isolation but are encrypted at rest as a unit inside the P1 routePoints column (NFR-3.23) and MUST NOT be logged separately. All five fields are always present on the wire (the Go struct carries no omitempty). Mirrors the `RoutePoint` component in telemetry/docs/contracts/specs/rest.openapi.yaml.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["lat", "lng", "speed", "heading", "timestamp"],
+      "properties": {
+        "lat": {
+          "type": "number",
+          "description": "Latitude in degrees at this point. Emitted as a JSON number (Go float64); whole-degree values serialize without a decimal point (Go shortest-float marshaling), so `10` and `10.0000` are the same value on the wire.",
+          "x-classification": "P1",
+          "x-encrypted-at-rest": true,
+          "x-unit": "degrees",
+          "minimum": -90,
+          "maximum": 90,
+          "examples": [37.7749]
+        },
+        "lng": {
+          "type": "number",
+          "description": "Longitude in degrees at this point. Emitted as a JSON number (Go float64).",
+          "x-classification": "P1",
+          "x-encrypted-at-rest": true,
+          "x-unit": "degrees",
+          "minimum": -180,
+          "maximum": 180,
+          "examples": [-122.4194]
+        },
+        "speed": {
+          "type": "number",
+          "description": "Instantaneous speed at this point, in miles per hour. P0 in isolation but encrypted at rest alongside the parent P1 routePoints column. Emitted as a JSON number (Go float64).",
+          "x-classification": "P0",
+          "x-unit": "mph",
+          "minimum": 0,
+          "examples": [15]
+        },
+        "heading": {
+          "type": "number",
+          "description": "Compass heading at this point, in degrees (0-360, 0 = North). P0 in isolation but encrypted at rest alongside the parent P1 routePoints column. Emitted as a JSON number (Go float64).",
+          "x-classification": "P0",
+          "x-unit": "degrees",
+          "minimum": 0,
+          "maximum": 360,
+          "examples": [175]
+        },
+        "timestamp": {
+          "type": "string",
+          "format": "date-time",
+          "description": "ISO 8601 / RFC 3339 UTC timestamp at which this point was captured. The Go writer renders it as `Timestamp.Format(time.RFC3339)` (telemetry/internal/store/drive_mapper.go). P0 in isolation but encrypted at rest alongside the parent P1 routePoints column.",
+          "x-classification": "P0",
+          "examples": ["2026-04-13T18:22:00Z"]
+        }
+      }
+    }
+  }
+}