@myrobotaxi/contracts 0.4.0 → 0.6.0

package/CONTRIBUTING.md

@@ -48,7 +48,10 @@ If you add a new `x-*` keyword to a schema, add it to the `ANNOTATIONS` array in
 
 The repo doubles as a Swift package (`Package.swift` at the root, product `MyRobotaxiContracts`). Swift types are generated from the same `schemas/*.json` source of truth:
 
-- **Generator**: `scripts/codegen-swift.mjs` — a small custom Node script (zero npm dependencies; runs without `npm ci`). One `Codable`/`Equatable`/`Sendable` struct per root schema object and per `$defs` entry (websocket-protocol.md §9.2); string enums become Swift `enum ...: String` with wire raw values.
+- **Generator**: `scripts/codegen-swift.mjs` — a small custom Node script (zero npm dependencies; runs without `npm ci`). One `Codable`/`Equatable`/`Sendable` struct per root schema object and per `$defs` entry (websocket-protocol.md §9.2); string enums become **decode-tolerant** Swift enums — a `RawRepresentable` enum with the known cases plus a catch-all `case unrecognized(String)` (MYR-195). Unknown wire values decode to `.unrecognized(raw)` instead of throwing (so a newer contracts version adding an enum member never hard-fails an older installed client's whole-frame decode) and re-encode byte-identically. The generator emits a small suite of unit tests (`src/codegen-swift.test.ts`) alongside the Swift `swift test` round-trip tests.
+- **Loud codegen errors**: to prevent silent wire drift, `scripts/codegen-swift.mjs` hard-errors (naming the schema path) rather than degrading when it hits a construct it can't faithfully map:
+  - a property enum whose members match a `$defs` enum but in a **different order** (would otherwise silently mint a near-duplicate nested type) — reorder the property enum to match the `$defs` order, or replace it with a `$ref`;
+  - schema composition (`oneOf` / `anyOf` / `allOf`) and **non-string enums** (would otherwise silently degrade to `JSONValue` / `Int`) — model the position as a concrete typed object, a string enum, or an explicit open `JSONValue`.
 - **Output**: `Sources/MyRobotaxiContracts/Generated/*.swift` — **committed**, never hand-edited (same rule as `src/generated/`). Regeneration is deterministic: emission order follows the schema JSON, so re-running on an unchanged schema is a no-op diff.
 - **Hand-written support code**: `Sources/MyRobotaxiContracts/JSONValue.swift` (arbitrary-JSON enum used for `WebSocketEnvelope.payload` and `VehicleUpdatePayload.fields`) is NOT generated and may be edited.
 - **Regenerate**: `npm run codegen:swift` after any schema change, and commit the result alongside the regenerated TypeScript.

package/README.md

@@ -25,13 +25,17 @@ Runtime schemas for Ajv / runtime validation:
 
 ```ts
 import { schemas } from '@myrobotaxi/contracts';
-// schemas.vehicleState, schemas.wsMessages, schemas.wsEnvelope
+// schemas.vehicleState, schemas.vehicleSummary, schemas.drivesList,
+// schemas.driveDetail, schemas.wsMessages, schemas.wsEnvelope
 ```
 
 Raw JSON for non-JS consumers (Go):
 
 ```
 ./node_modules/@myrobotaxi/contracts/schemas/vehicle-state.schema.json
+./node_modules/@myrobotaxi/contracts/schemas/vehicle-summary.schema.json
+./node_modules/@myrobotaxi/contracts/schemas/drives-list.schema.json
+./node_modules/@myrobotaxi/contracts/schemas/drive-detail.schema.json
 ./node_modules/@myrobotaxi/contracts/schemas/ws-messages.schema.json
 ./node_modules/@myrobotaxi/contracts/schemas/ws-envelope.schema.json
 ```
@@ -64,7 +68,27 @@ let envelope = try JSONDecoder().decode(WebSocketEnvelope.self, from: frameData)
 if envelope.type == .vehicleUpdate { /* decode VehicleUpdatePayload from envelope.payload */ }
 ```
 
-The same custom annotations are folded into the generated SwiftDoc comments, so `grep '@classification "P1"'` works inside the checked-out package too. Wire enums (`status`, `chargeState`, `MessageType`, error codes, …) generate as Swift `enum ...: String` with wire raw values; nullable / non-required schema fields are Swift optionals. The intentionally-open wire positions — `WebSocketEnvelope.payload` and `VehicleUpdatePayload.fields` — are typed via the hand-written `JSONValue` enum, which preserves explicit JSON `null`s (required for atomic-group clears per NFR-3.9).
+The same custom annotations are folded into the generated SwiftDoc comments, so `grep '@classification "P1"'` works inside the checked-out package too. Wire enums (`status`, `chargeState`, `MessageType`, error codes, …) generate as **decode-tolerant** Swift enums: a `RawRepresentable` enum with the known cases plus a catch-all `case unrecognized(String)` (MYR-195). Nullable / non-required schema fields are Swift optionals. The intentionally-open wire positions — `WebSocketEnvelope.payload` and `VehicleUpdatePayload.fields` — are typed via the hand-written `JSONValue` enum, which preserves explicit JSON `null`s (required for atomic-group clears per NFR-3.9).
+
+### Decode-tolerant wire enums (forward-compat for installed clients)
+
+A plain `enum: String` (Swift's synthesized `Codable`) throws on the first unrecognized value, which would make **one** new enum member shipped in a newer contracts version hard-fail the *entire* frame/snapshot decode on a not-yet-updated iOS app. To keep installed clients forward-compatible, each string wire enum is emitted as:
+
+```swift
+public enum Status: RawRepresentable, Codable, Hashable, Sendable {
+    case driving
+    case parked
+    // …known cases…
+    /// A wire value not known to this build of the contracts package.
+    case unrecognized(String)
+    // init(rawValue:) / rawValue / init(from:) / encode(to:) map every string,
+    // falling back to .unrecognized(raw) instead of throwing.
+}
+```
+
+- **Unknown values never throw** — they decode to `.unrecognized(raw)`, so the surrounding `VehicleState` / `WebSocketEnvelope` still decodes.
+- **Round-trips byte-identically** — the raw string is preserved and re-encoded verbatim, so a relaying client never corrupts a value it doesn't understand.
+- **Ergonomic for consumers** — `switch status { case .driving: …; case .unrecognized(let raw): … }` stays exhaustive and compiler-checked; `== .parked` and `.rawValue` work as before. The catch-all is named `unrecognized` (not `unknown`) because `ChargeState` already has a known member whose wire value is `"Unknown"`.
 
 ## Tool choice (Swift): custom generator
 

package/dist/index.cjs

@@ -455,6 +455,368 @@ var vehicle_summary_schema_default = {
   }
 };
 
+// schemas/drives-list.schema.json
+var drives_list_schema_default = {
+  $schema: "https://json-schema.org/draft/2020-12/schema",
+  $id: "https://myrobotaxi.com/schemas/drives-list.schema.json",
+  title: "DrivesListResponse",
+  description: "Cursor-paginated envelope returned by GET /api/vehicles/{vehicleId}/drives (rest-api.md \xA77.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.",
+  type: "object",
+  additionalProperties: false,
+  required: ["items", "nextCursor", "hasMore"],
+  properties: {
+    items: {
+      type: "array",
+      description: "Drive summary rows for this page. Always present; an empty array (never null) means no more drives \u2014 e.g. the final page or a vehicle with no completed drives. Ordered startTime DESC, id DESC (rest-api.md \xA77.2 Ordering).",
+      "x-classification": "P0",
+      items: { $ref: "#/$defs/DriveSummary" }
+    },
+    nextCursor: {
+      type: ["string", "null"],
+      description: "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 \u2014 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`.",
+      "x-classification": "P0"
+    },
+    hasMore: {
+      type: "boolean",
+      description: "True iff more pages exist after this one. Redundant with `nextCursor != null`, provided for caller convenience.",
+      "x-classification": "P0"
+    }
+  },
+  $defs: {
+    DriveSummary: {
+      title: "DriveSummary",
+      description: "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 \u2014 those live on Drive (drive detail, \xA77.3) and DriveRoute (\xA77.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.",
+      type: "object",
+      additionalProperties: false,
+      required: [
+        "id",
+        "vehicleId",
+        "startTime",
+        "endTime",
+        "date",
+        "distanceMiles",
+        "durationSeconds",
+        "avgSpeedMph",
+        "maxSpeedMph",
+        "startChargeLevel",
+        "endChargeLevel",
+        "fsdMiles",
+        "fsdPercentage",
+        "createdAt"
+      ],
+      properties: {
+        id: {
+          type: "string",
+          description: "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}.",
+          "x-classification": "P0",
+          examples: ["clmno9876543210zyxw0001"]
+        },
+        vehicleId: {
+          type: "string",
+          description: "Opaque database identifier (cuid) for the drive's parent vehicle. Matches VehicleState.vehicleId / VehicleSummary.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'), for day-grouping the history list. Not a full timestamp \u2014 use startTime/endTime for instants.",
+          "x-classification": "P0",
+          examples: ["2026-04-13"]
+        },
+        startLocation: {
+          type: "string",
+          description: "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 \u2014 zero-GPS at drive start or reverse-geocode failed (toMaskMap, telemetry/internal/telemetry/vehicle_drives_types.go). Consumers branch on key presence.",
+          "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 \u2014 drive in progress, zero-GPS at drive end, or reverse-geocode failed.",
+          "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"]
+        },
+        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. Matches the WebSocket drive_ended.payload.durationSeconds shape (DV-12).",
+          "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]
+        },
+        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, MYR-152). 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, MYR-152). 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]
+        },
+        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/vehicle_drives_types.go).",
+          "x-classification": "P0",
+          examples: ["2026-04-13T18:46:19Z"]
+        }
+      }
+    }
+  }
+};
+
+// schemas/drive-detail.schema.json
+var drive_detail_schema_default = {
+  $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 \xA77.3). Contains every FR-3.4 stat EXCEPT routePoints, which is served separately by GET /api/drives/{driveId}/route (DriveRoute, \xA77.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, \xA75.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 \u2014 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 \u2014 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 \u2014 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"]
+    }
+  }
+};
+
 // schemas/ws-messages.schema.json
 var ws_messages_schema_default = {
   $schema: "https://json-schema.org/draft/2020-12/schema",
@@ -825,6 +1187,8 @@ var ws_envelope_schema_default = {
 var schemas = {
   vehicleState: vehicle_state_schema_default,
   vehicleSummary: vehicle_summary_schema_default,
+  drivesList: drives_list_schema_default,
+  driveDetail: drive_detail_schema_default,
   wsMessages: ws_messages_schema_default,
   wsEnvelope: ws_envelope_schema_default
 };