@myrobotaxi/contracts 0.1.0

package/CONTRIBUTING.md

@@ -0,0 +1,67 @@
+# Contributing to @myrobotaxi/contracts
+
+This package is the canonical wire-protocol surface for the MyRoboTaxi platform. Changes here affect downstream consumers across the TypeScript SDK, the Go telemetry server, and (eventually) the Swift SDK.
+
+## Schema-authoring policy
+
+Schemas in this repo are currently **vendored** from `myrobotaxi/telemetry/docs/contracts/schemas/`. The telemetry repo is the active authoring home.
+
+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
+   - 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).
+
+## Versioning policy
+
+Per `NFR-3.37` (telemetry repo contracts/README.md):
+
+- **Major version bump** (`v1.0.0` → `v2.0.0`) — any breaking wire change: removing a field, narrowing a type, tightening a `required` array, removing an enum member.
+- **Minor version bump** (`v1.0.0` → `v1.1.0`) — additive, backwards-compatible: new optional field, new message type, new enum member on an append-only enum.
+- **Patch version bump** (`v1.0.0` → `v1.0.1`) — documentation/annotation changes that don't alter the generated TypeScript surface.
+
+The contracts package is currently pre-1.0 (`v0.x.y`), so all changes may be minor or patch. The first wire-stable cut will be tagged `v1.0.0`.
+
+## Custom JSON Schema annotations
+
+The MyRoboTaxi schemas use these non-standard keywords:
+
+| Keyword | Purpose |
+|---|---|
+| `x-classification` | P0/P1 data classification per `data-classification.md` |
+| `x-atomic-group` | Marks a field as part of an atomic-delivery group |
+| `x-atomic-groups` | Root-level definition of all atomic groups |
+| `x-unit` | Physical unit for numeric fields (`mph`, `degrees`, `percent`, etc.) |
+| `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.
+
+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`.
+
+## Release process
+
+1. Land your PR on `main` (CI green: lint + typecheck + test + codegen-drift + build).
+2. Bump `package.json` `version` per the [versioning policy](#versioning-policy).
+3. Tag: `git tag v0.1.X && git push --tags`.
+4. The `release.yml` workflow publishes to npm with `provenance: true` via GitHub Actions OIDC.
+
+## Phase 2 migration (authoring home)
+
+A planned follow-up issue (filed after MYR-49 ships) moves the schema authoring home from `telemetry/docs/contracts/schemas/` into this repo. After that lands:
+
+- The telemetry repo's Go contract-tester will consume `@myrobotaxi/contracts` (either via vendored JSON or a Go submodule).
+- The paired-PR convention drops out — schemas have a single home.
+- This file will be updated to reflect the new workflow.
+
+## Code style
+
+- TypeScript strict mode; `verbatimModuleSyntax` on.
+- `import type` for type-only imports.
+- Generated code in `src/generated/` is excluded from lint (it's auto-emitted).
+- Manual edits in `src/` must pass `npm run lint && npm run typecheck && npm run test`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Thomas Nandola
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,94 @@
+# @myrobotaxi/contracts
+
+Canonical wire-protocol schemas for the MyRoboTaxi platform.
+
+- **JSON Schema (draft-2020-12)** under `schemas/` — the language-neutral source of truth.
+- **Pre-generated TypeScript types** under `dist/` (via the `./types` subpath) — produced by `json-schema-to-typescript` and committed to `src/generated/` for diff review.
+
+Consumed by [@myrobotaxi/sdk](https://github.com/myrobotaxi/typescript-sdk), the Go [telemetry server](https://github.com/myrobotaxi/telemetry), and the [react-frontend](https://github.com/myrobotaxi/react-frontend) Next.js app.
+
+## Install
+
+```bash
+npm install @myrobotaxi/contracts
+```
+
+## Usage
+
+Type-only import (no runtime payload, tree-shakes to zero bytes):
+
+```ts
+import type { VehicleState, WebSocketEnvelope } from '@myrobotaxi/contracts/types';
+```
+
+Runtime schemas for Ajv / runtime validation:
+
+```ts
+import { schemas } from '@myrobotaxi/contracts';
+// schemas.vehicleState, schemas.wsMessages, schemas.wsEnvelope
+```
+
+Raw JSON for non-JS consumers (Go, Swift):
+
+```
+./node_modules/@myrobotaxi/contracts/schemas/vehicle-state.schema.json
+./node_modules/@myrobotaxi/contracts/schemas/ws-messages.schema.json
+./node_modules/@myrobotaxi/contracts/schemas/ws-envelope.schema.json
+```
+
+## 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.
+
+```ts
+/**
+ * GPS latitude. Encrypted at rest (AES-256-GCM) per FR-11.1.
+ *
+ * @classification "P1"
+ * @atomic-group "gps"
+ * @encrypted true
+ */
+latitude: number;
+```
+
+## Tool choice: `json-schema-to-typescript`
+
+We picked `json-schema-to-typescript` v15+ over `quicktype` for three reasons:
+
+1. **Matches the telemetry repo's existing convention.** The Go-side [`vehicle-state-schema.md` §6.1](https://github.com/myrobotaxi/telemetry/blob/main/docs/contracts/vehicle-state-schema.md) already documents `json-schema-to-typescript` as the TS-side tool. Picking the same one in the contracts package guarantees zero drift between the docs and the actual output.
+2. **Pure JS (no Rust binary).** Easier to vendor into CI, no platform-specific install issues.
+3. **TSDoc-preserving.** The `description` field on each JSON Schema property is copied verbatim into the generated TSDoc comment. `quicktype` produces leaner runtime helpers (parsers / serializers) but does not preserve descriptions as cleanly, and we don't need its runtime artifacts here.
+
+The trade-off is that `quicktype`'s discriminated-union handling for `oneOf` payloads is more idiomatic. The current schemas use a nullable-enum-with-explicit-null pattern instead of `oneOf`, so this doesn't bite us yet. If the schema set grows to need true discriminated unions, we may revisit.
+
+## Schema-authoring policy
+
+Schemas in this repo are **vendored** from [`myrobotaxi/telemetry/docs/contracts/schemas/`](https://github.com/myrobotaxi/telemetry/tree/main/docs/contracts/schemas) — that repo is the current authoring home.
+
+Until [Phase 2](#phase-2-migration) ships, schema changes require a **paired PR** to this repo (mirroring the change here, re-running codegen, bumping the version).
+
+## Phase 2 migration
+
+A planned follow-up moves the schema authoring home from `telemetry/docs/contracts/schemas/` into this repo, eliminating the paired-PR requirement. After Phase 2, the telemetry server's Go contract-tester will consume the published `@myrobotaxi/contracts` package directly.
+
+## Versioning policy
+
+- **Major version bump** required for any wire-incompatible change (per NFR-3.37 in the telemetry docs).
+- **Minor version bump** for additive, backwards-compatible additions (new optional fields, new message types, new enum members on append-only enums).
+- **Patch version bump** for documentation / annotation changes that don't alter the generated TypeScript surface.
+
+## Development
+
+```bash
+npm install
+npm run codegen        # regenerate src/generated/ from schemas/
+npm run typecheck
+npm run test
+npm run build          # tsup → dist/
+```
+
+CI runs `codegen` and fails if `src/generated/` drifts from the schemas — every schema bump must be paired with a regenerate-and-commit.
+
+## License
+
+MIT