@myrobotaxi/contracts 0.3.0 → 0.5.0

package/CONTRIBUTING.md

@@ -11,8 +11,8 @@ This means any schema change requires:
 1. Open a PR in [`myrobotaxi/telemetry`](https://github.com/myrobotaxi/telemetry) that edits the source `.schema.json` file under `docs/contracts/schemas/`. Get it reviewed and merged.
 2. Open a paired PR in this repo that:
    - Copies the new schema file from the telemetry repo into `schemas/`
-   - Runs `npm run codegen` to regenerate `src/generated/`
-   - Commits the regenerated `.ts` files
+   - Runs `npm run codegen` to regenerate `src/generated/` and `npm run codegen:swift` to regenerate `Sources/MyRobotaxiContracts/Generated/`
+   - Commits the regenerated `.ts` and `.swift` files
    - Bumps the version per the [versioning policy](#versioning-policy)
 
 Until [Phase 2](#phase-2-migration-authoring-home) ships, this paired-PR convention is enforced by review (no automation).
@@ -40,9 +40,23 @@ The MyRoboTaxi schemas use these non-standard keywords:
 | `x-encrypted` / `x-encrypted-at-rest` | AES-256-GCM at rest |
 | `x-tesla-proto-field` | Source Tesla protobuf field number |
 
-The codegen pipeline (`scripts/codegen.mjs`) **folds these into TSDoc comments** at generation time, so they survive into the consumer's editor as `@classification "P0"` annotations.
+The codegen pipeline (`scripts/codegen.mjs`) **folds these into TSDoc comments** at generation time, so they survive into the consumer's editor as `@classification "P0"` annotations. The Swift pipeline (`scripts/codegen-swift.mjs`) does the same folding into SwiftDoc (`///`) comments.
 
-If you add a new `x-*` keyword to a schema, add it to the `ANNOTATIONS` array in `scripts/codegen.mjs` and re-run `npm run codegen`.
+If you add a new `x-*` keyword to a schema, add it to the `ANNOTATIONS` array in **both** `scripts/codegen.mjs` and `scripts/codegen-swift.mjs`, then re-run `npm run codegen` and `npm run codegen:swift`.
+
+## Swift codegen pipeline
+
+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 **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.
+- **CI**: the `swift` job on `macos-latest` runs `swift build`, `swift test`, then `npm run codegen:swift` and fails on drift in `Sources/MyRobotaxiContracts/Generated/` — mirroring the TypeScript `codegen-drift` job.
+- **Consumption**: Swift consumers resolve the package by git URL + tag (`from: "0.x.y"`); there is no Swift registry publish. The `v0.x.y` git tags pushed for npm releases are also what SwiftPM resolves against, so the versioning policy above applies to the Swift surface too.
 
 ## Release process
 

package/README.md

@@ -28,7 +28,7 @@ import { schemas } from '@myrobotaxi/contracts';
 // schemas.vehicleState, schemas.wsMessages, schemas.wsEnvelope
 ```
 
-Raw JSON for non-JS consumers (Go, Swift):
+Raw JSON for non-JS consumers (Go):
 
 ```
 ./node_modules/@myrobotaxi/contracts/schemas/vehicle-state.schema.json
@@ -36,6 +36,60 @@ Raw JSON for non-JS consumers (Go, Swift):
 ./node_modules/@myrobotaxi/contracts/schemas/ws-envelope.schema.json
 ```
 
+## Swift
+
+This repo is also a Swift package (`MyRobotaxiContracts`) with **pre-generated `Codable`/`Sendable` structs** under `Sources/MyRobotaxiContracts/Generated/` — produced by `scripts/codegen-swift.mjs` and committed for diff review, exactly like the TypeScript types. Swift consumers resolve by git URL + semver tag (no registry publish).
+
+In your `Package.swift`:
+
+```swift
+dependencies: [
+  .package(url: "https://github.com/myrobotaxi/contracts.git", from: "0.4.0")
+],
+targets: [
+  .target(
+    name: "MyApp",
+    dependencies: [.product(name: "MyRobotaxiContracts", package: "contracts")]
+  )
+]
+```
+
+Usage:
+
+```swift
+import MyRobotaxiContracts
+
+let state = try JSONDecoder().decode(VehicleState.self, from: snapshotData)
+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 **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
+
+Like the TypeScript side, the Swift generator is a small custom script (`scripts/codegen-swift.mjs`, no `quicktype`): it keeps the annotation-folding grep affordance, emits exactly one type per root schema and per `$defs` entry (websocket-protocol.md §9.2), needs no npm install (zero dependencies), and is deterministic so CI can diff the committed output.
+
 ## What's in the generated TypeScript
 
 Custom JSON Schema annotations from the source schemas — `x-classification`, `x-atomic-group`, `x-unit`, `x-encrypted`, `x-tesla-proto-field` — are folded into the generated TSDoc comments at codegen time. This means consumers can `grep '@classification "P1"'` inside their `node_modules` to find every sensitive field without leaving their editor.
@@ -82,12 +136,16 @@ A planned follow-up moves the schema authoring home from `telemetry/docs/contrac
 ```bash
 npm install
 npm run codegen        # regenerate src/generated/ from schemas/
+npm run codegen:swift  # regenerate Sources/MyRobotaxiContracts/Generated/ from schemas/
 npm run typecheck
 npm run test
 npm run build          # tsup → dist/
+
+swift build            # Swift package
+swift test
 ```
 
-CI runs `codegen` and fails if `src/generated/` drifts from the schemas — every schema bump must be paired with a regenerate-and-commit.
+CI runs both codegens and fails if `src/generated/` or `Sources/MyRobotaxiContracts/Generated/` drifts from the schemas — every schema bump must be paired with a regenerate-and-commit (both languages).
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@myrobotaxi/contracts",
-  "version": "0.3.0",
+  "version": "0.5.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": {
@@ -52,6 +52,7 @@
   ],
   "scripts": {
     "codegen": "node scripts/codegen.mjs",
+    "codegen:swift": "node scripts/codegen-swift.mjs",
     "build": "tsup",
     "clean": "rm -rf dist coverage",
     "lint": "eslint .",