@glassly/cloud-protocol 0.1.0-dev.0

package/README.md

@@ -0,0 +1,45 @@
+# @glassly/cloud-protocol
+
+The Glassly phone ↔ cloud wire protocol: message schemas, envelopes, and
+error types shared by everything that speaks to the Glassly cloud. Pure
+TypeScript + [zod](https://github.com/colinhacks/zod) — no server or native
+dependencies.
+
+This is a **leaf package**: [`@glassly/cloud-client`](https://www.npmjs.com/package/@glassly/cloud-client)
+and [`@glassly/engine`](https://www.npmjs.com/package/@glassly/engine) depend on
+it, and the Glassly cloud runtime consumes the same schemas server-side, so
+both ends of the wire validate against one definition.
+
+## Install
+
+You normally get this package automatically as a dependency of
+`@glassly/cloud-client` or a peer of `@glassly/engine`. For direct use:
+
+```sh
+npm install @glassly/cloud-protocol@dev
+```
+
+> Currently published on the `dev` dist-tag (prerelease channel).
+
+## Usage
+
+```ts
+import {envelopeSchema, PROTOCOL_MAJOR, type Envelope} from "@glassly/cloud-protocol";
+
+const message: Envelope = envelopeSchema.parse(JSON.parse(raw));
+
+// or per-module subpaths:
+import {normalizePhotoSizeTier} from "@glassly/cloud-protocol/camera";
+```
+
+Modules: `envelope`, `messages`, `handshake`, `control`, `camera`, `audio`,
+`maps`, `errors` — each importable as `@glassly/cloud-protocol/<module>`.
+
+The package ships TypeScript source (`main: ./src/index.ts`) and targets
+consumers that compile TS themselves (Metro / bundlers / tsc); it is not
+precompiled for plain Node `require`.
+
+## Part of Glassly
+
+Source lives in the [Glassly monorepo](https://github.com/tetramo-labs/glassly)
+under `cloud-v2/packages/protocol`. Issues and contributions welcome there.

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@glassly/cloud-protocol",
+  "version": "0.1.0-dev.0",
+  "type": "module",
+  "main": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./*": "./src/*.ts"
+  },
+  "files": [
+    "src",
+    "!src/**/*.test.ts"
+  ],
+  "scripts": {
+    "test": "bun test"
+  },
+  "dependencies": {
+    "zod": "^3.24.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tetramo-labs/glassly.git",
+    "directory": "cloud-v2/packages/protocol"
+  },
+  "description": "Glassly phone-cloud wire protocol — message schemas, envelopes and error types (zod)",
+  "keywords": [
+    "glassly",
+    "glassly",
+    "protocol",
+    "schemas",
+    "zod"
+  ],
+  "homepage": "https://github.com/tetramo-labs/glassly/tree/dev/cloud-v2/packages/protocol#readme",
+  "bugs": {
+    "url": "https://github.com/tetramo-labs/glassly/issues"
+  }
+}

package/src/audio.ts

@@ -0,0 +1,134 @@
+/**
+ * @fileoverview Canonical audio wire types for the Glassly Runtime protocol.
+ *
+ * zod schemas + inferred TS types for the audio service's subscription model
+ * and result types. These are the single source of truth; `src/audio.types.ts`
+ * re-exports the subscription types from here and adds `subscriptionKey()`.
+ *
+ * Mirrors docs/issues/002-cloud-runtime/audio/spec.md
+ * ("Subscription model" and "Result types"). Pure + isomorphic: no server
+ * imports, safe to bundle into the RN client.
+ */
+import { z } from "zod";
+
+// --- Subscription model -----------------------------------------------------
+
+export const languageSourceSchema = z.discriminatedUnion("mode", [
+  z.object({ mode: z.literal("specific"), code: z.string() }),
+  z.object({ mode: z.literal("auto"), hints: z.array(z.string()).optional() }),
+]);
+export type LanguageSource = z.infer<typeof languageSourceSchema>;
+
+export const transcriptionSubscriptionSchema = z.object({
+  kind: z.literal("transcription"),
+  language: languageSourceSchema,
+});
+export type TranscriptionSubscription = z.infer<
+  typeof transcriptionSubscriptionSchema
+>;
+
+export const translationSubscriptionSchema = z.object({
+  kind: z.literal("translation"),
+  source: languageSourceSchema,
+  target: z.string(),
+});
+export type TranslationSubscription = z.infer<
+  typeof translationSubscriptionSchema
+>;
+
+export const audioSubscriptionSchema = z.discriminatedUnion("kind", [
+  transcriptionSubscriptionSchema,
+  translationSubscriptionSchema,
+]);
+export type AudioSubscription = z.infer<typeof audioSubscriptionSchema>;
+
+// --- UDP liveness -----------------------------------------------------------
+
+export const UDP_LIVENESS_PROBE_PREFIX = "glassly:udp-probe:";
+
+export const udpLivenessAckPayloadSchema = z.object({
+  sessionId: z.string(),
+  sessionTag: z.number().int(),
+  probeId: z.string(),
+  receivedAt: z.number().int(),
+});
+export type UdpLivenessAckPayload = z.infer<typeof udpLivenessAckPayloadSchema>;
+
+/**
+ * Push: a metered feature was blocked (or unblocked) by the account's plan
+ * quota. `blocked: true` fires when the cloud closes/refuses transcription
+ * because the free-tier allowance ran out mid-session; `false` when a later
+ * check clears it (upgrade, new billing month). The client uses this to tell
+ * the wearer WHY transcription went quiet — without it the lens just stops.
+ */
+export const quotaStatusPayloadSchema = z.object({
+  feature: z.enum(["transcription"]),
+  blocked: z.boolean(),
+});
+export type QuotaStatusPayload = z.infer<typeof quotaStatusPayloadSchema>;
+
+// --- Result types -----------------------------------------------------------
+
+export const transcriptionTokenSchema = z.object({
+  text: z.string(),
+  startMs: z.number(),
+  endMs: z.number(),
+  confidence: z.number(),
+  isFinal: z.boolean(),
+  speaker: z.string().optional(),
+  // per-token; mid-sentence language switches are possible
+  detectedLanguage: z.string().optional(),
+});
+export type TranscriptionToken = z.infer<typeof transcriptionTokenSchema>;
+
+export const transcriptionDataSchema = z.object({
+  userId: z.string(),
+  subscription: transcriptionSubscriptionSchema,
+
+  // Aggregated for simple consumers
+  text: z.string(),
+  isFinal: z.boolean(),
+  utteranceId: z.string().optional(),
+  speakerId: z.string().optional(),
+  startMs: z.number(),
+  endMs: z.number(),
+  durationMs: z.number().optional(),
+  confidence: z.number().optional(),
+
+  // Language resolution
+  resolvedLanguage: z.string(),
+  languageDetected: z.boolean(),
+
+  // Per-token detail for consumers that need it
+  tokens: z.array(transcriptionTokenSchema),
+
+  provider: z.string(),
+  timestamp: z.number(),
+});
+export type TranscriptionData = z.infer<typeof transcriptionDataSchema>;
+
+export const translationDataSchema = z.object({
+  userId: z.string(),
+  subscription: translationSubscriptionSchema,
+
+  text: z.string(), // translated
+  originalText: z.string().optional(), // source-language text
+  isFinal: z.boolean(),
+  utteranceId: z.string().optional(),
+  speakerId: z.string().optional(),
+  startMs: z.number(),
+  endMs: z.number(),
+  durationMs: z.number().optional(),
+  confidence: z.number().optional(),
+
+  source: z.object({
+    language: z.string(), // resolved (specified or detected)
+    detected: z.boolean(),
+    confidence: z.number().optional(),
+  }),
+  target: z.object({ language: z.string() }),
+
+  provider: z.string(),
+  timestamp: z.number(),
+});
+export type TranslationData = z.infer<typeof translationDataSchema>;

package/src/camera.ts

@@ -0,0 +1,157 @@
+/**
+ * @fileoverview Canonical camera wire types: managed photo + managed stream.
+ *
+ * zod schemas + inferred TS types for the camera service. The request/result
+ * shapes ride REST; `photo.ready` / `photo.error` are WebSocket push events
+ * registered into the message union (messages.ts). Pure + isomorphic: no server
+ * imports, safe to bundle into the client.
+ *
+ * Mirrors docs/issues/002-cloud-runtime/camera/spec.md.
+ */
+import { z } from "zod";
+
+// --- Managed photo ----------------------------------------------------------
+
+/** Device-canonical photo size tier (matches miniapp SDK and ASG). */
+export const photoSizeCanonicalSchema = z.enum(["low", "medium", "high", "max"]);
+export type PhotoSizeTier = z.infer<typeof photoSizeCanonicalSchema>;
+
+/** Accepted on the wire: canonical names plus legacy cloud aliases. */
+const photoSizeInputSchema = z.enum([
+  "low",
+  "medium",
+  "high",
+  "max",
+  "small",
+  "large",
+  "full",
+]);
+
+/**
+ * Normalize a photo size string to the device-canonical tier.
+ * Legacy aliases: small→low, large→high, full→max.
+ */
+export function normalizePhotoSizeTier(value: string): PhotoSizeTier {
+  switch (value) {
+    case "small":
+      return "low";
+    case "large":
+      return "high";
+    case "full":
+      return "max";
+    case "low":
+    case "medium":
+    case "high":
+    case "max":
+      return value;
+    default:
+      throw new Error(`invalid photo size: ${value}`);
+  }
+}
+
+const photoCompressInputSchema = z.enum(["none", "low", "medium", "high", "heavy"]);
+
+/** Normalize compression aliases to the cloud wire enum. */
+export function normalizePhotoCompress(
+  value: string,
+): "none" | "medium" | "heavy" {
+  switch (value) {
+    case "low":
+    case "medium":
+      return "medium";
+    case "high":
+    case "heavy":
+      return "heavy";
+    case "none":
+      return "none";
+    default:
+      throw new Error(`invalid photo compress: ${value}`);
+  }
+}
+
+export const photoOptionsSchema = z.object({
+  size: photoSizeInputSchema
+    .optional()
+    .transform((value) => (value === undefined ? undefined : normalizePhotoSizeTier(value))),
+  compress: photoCompressInputSchema
+    .optional()
+    .transform((value) => (value === undefined ? undefined : normalizePhotoCompress(value))),
+  saveToGallery: z.boolean().optional(),
+  sound: z.boolean().optional(),
+});
+export type PhotoOptions = z.infer<typeof photoOptionsSchema>;
+
+/**
+ * The REST response to a photo request. The capture happens out of band (the
+ * glasses upload to `uploadUrl`); `readUrl` is the presigned URL the finished
+ * photo will be readable at, returned up front so the client has it before the
+ * `photo.ready` push confirms the upload landed.
+ */
+export const photoRequestResultSchema = z.object({
+  requestId: z.string(),
+  uploadUrl: z.string(),
+  readUrl: z.string(),
+});
+export type PhotoRequestResult = z.infer<typeof photoRequestResultSchema>;
+
+/** `photo.ready` push payload: the capture+upload completed. */
+export const photoReadyPayloadSchema = z.object({
+  requestId: z.string(),
+  readUrl: z.string(),
+});
+export type PhotoReady = z.infer<typeof photoReadyPayloadSchema>;
+
+/** `photo.error` push payload: the capture+upload failed. */
+export const photoErrorPayloadSchema = z.object({
+  requestId: z.string(),
+  reason: z.string(),
+});
+export type PhotoError = z.infer<typeof photoErrorPayloadSchema>;
+
+// --- Managed stream ---------------------------------------------------------
+
+/** A restream destination: re-publish the ingest to an external RTMP target. */
+export const restreamDestinationSchema = z.union([
+  z.string(),
+  z.object({ url: z.string(), name: z.string().optional() }),
+]);
+export type RestreamDestination = z.infer<typeof restreamDestinationSchema>;
+
+export const streamOptionsSchema = z.object({
+  /** Region hint so the cloud provisions a nearby ingest endpoint. */
+  region: z.string().optional(),
+  /** External RTMP targets the provider re-publishes the ingest to. */
+  restreamDestinations: z.array(restreamDestinationSchema).optional(),
+});
+export type StreamOptions = z.infer<typeof streamOptionsSchema>;
+
+/**
+ * A provisioned stream. `ingest` is where the device pushes frames; `playback`
+ * is where viewers watch. Both are left as open records because the provider
+ * (Cloudflare Stream by default) is swappable per region and its exact field
+ * shapes are not finalized. The Cloudflare provider populates ingest
+ * `{protocol, url, streamKey, rtmpUrl, srtUrl?, webrtcPublishUrl?}` (the last
+ * three ready-to-publish with credentials embedded) and playback
+ * `{hls, dash, webrtc?}`.
+ */
+export const managedStreamSchema = z.object({
+  streamId: z.string(),
+  ingest: z.record(z.unknown()),
+  playback: z.record(z.unknown()),
+});
+export type ManagedStream = z.infer<typeof managedStreamSchema>;
+
+/**
+ * `GET /api/camera/stream/:id` result: the provider's view of the ingest.
+ * `isConnected` is the portable signal (is the device's push arriving?);
+ * the rest is provider detail for debugging.
+ */
+export const streamStatusResultSchema = z.object({
+  streamId: z.string(),
+  isConnected: z.boolean(),
+  state: z.string().nullable(),
+  connectedAt: z.string().optional(),
+  lastSeenAt: z.string().optional(),
+  reason: z.string().optional(),
+});
+export type StreamStatusResult = z.infer<typeof streamStatusResultSchema>;

package/src/control.ts

@@ -0,0 +1,13 @@
+/**
+ * @fileoverview Control payloads: control.ping and control.pong.
+ *
+ * Mirrors docs/issues/002-cloud-runtime/protocol.md ("Control"). Liveness and
+ * RTT, separate from the WebSocket ping frame. Pure + isomorphic.
+ */
+import { z } from "zod";
+
+export const controlPingPayloadSchema = z.object({}).strict();
+export type ControlPing = z.infer<typeof controlPingPayloadSchema>;
+
+export const controlPongPayloadSchema = z.object({}).strict();
+export type ControlPong = z.infer<typeof controlPongPayloadSchema>;

package/src/envelope.ts

@@ -0,0 +1,48 @@
+/**
+ * @fileoverview The transport envelope shared by every WebSocket message.
+ *
+ * Mirrors docs/issues/002-cloud-runtime/protocol.md ("Envelope"). Pure +
+ * isomorphic: no server imports.
+ */
+import { z } from "zod";
+
+/** Protocol major. A mismatched major is rejected at the handshake. */
+export const PROTOCOL_MAJOR = 2 as const;
+
+/**
+ * Wraps a payload schema in the protocol envelope with a literal `type`, so a
+ * set of message schemas can be combined into a discriminated union on `type`.
+ *
+ *   const connectionAck = envelope("connection.ack", connectionAckPayloadSchema)
+ */
+export function envelope<Type extends string, Payload extends z.ZodTypeAny>(
+  type: Type,
+  payload: Payload,
+) {
+  return z.object({
+    v: z.literal(PROTOCOL_MAJOR),
+    type: z.literal(type),
+    // present only when a message needs request/ack correlation
+    id: z.string().optional(),
+    // epoch milliseconds (Unix time)
+    timestamp: z.number().int(),
+    payload,
+  });
+}
+
+/** The structural envelope, payload left open. Useful for a first-pass parse. */
+export const envelopeSchema = z.object({
+  v: z.literal(PROTOCOL_MAJOR),
+  type: z.string(),
+  id: z.string().optional(),
+  timestamp: z.number().int(),
+  payload: z.unknown(),
+});
+
+export interface Envelope<T = unknown> {
+  v: typeof PROTOCOL_MAJOR;
+  type: string;
+  id?: string;
+  timestamp: number;
+  payload: T;
+}

package/src/errors.ts

@@ -0,0 +1,27 @@
+/**
+ * @fileoverview The error payload and transport-level error codes.
+ *
+ * Mirrors docs/issues/002-cloud-runtime/protocol.md ("Errors"). Services may
+ * define additional codes for their own payloads (documented in the service
+ * doc). Pure + isomorphic.
+ */
+import { z } from "zod";
+
+/** Transport-level error codes shared by every runtime service. */
+export const PROTOCOL_ERROR_CODES = {
+  AUTH_FAILED: { fatal: true }, // token missing or invalid
+  AUTH_EXPIRED: { fatal: true }, // token expired; client should refresh and reopen
+  UNSUPPORTED_VERSION: { fatal: true }, // protocol major mismatch
+  BAD_REQUEST: { fatal: false }, // malformed payload for a known type
+  UNKNOWN_TYPE: { fatal: false }, // unrecognized `type`
+  INTERNAL: { fatal: false }, // server-side failure
+} as const;
+
+export type ProtocolErrorCode = keyof typeof PROTOCOL_ERROR_CODES;
+
+export const protocolErrorPayloadSchema = z.object({
+  code: z.string(), // a ProtocolErrorCode or a service-defined code
+  message: z.string(),
+  fatal: z.boolean(), // if true, the server closes the socket after sending
+});
+export type ProtocolError = z.infer<typeof protocolErrorPayloadSchema>;

package/src/handshake.ts

@@ -0,0 +1,60 @@
+/**
+ * @fileoverview Handshake payloads: connection.init and connection.ack.
+ *
+ * Mirrors docs/issues/002-cloud-runtime/protocol.md ("Auth and handshake").
+ * Service-scoped config rides in scoped blocks; audio is the only one today.
+ * Pure + isomorphic: no server imports.
+ */
+import { z } from "zod";
+import { audioSubscriptionSchema } from "./audio";
+
+// --- connection.init (client to cloud) --------------------------------------
+
+export const connectionInitPayloadSchema = z.object({
+  // omitted if provided via the ?token= fallback
+  token: z.string().optional(),
+  // semver of the client protocol build, e.g. "2.0.0"
+  protocolVersion: z.string(),
+  client: z
+    .object({
+      platform: z.enum(["ios", "android"]),
+      appVersion: z.string().optional(),
+    })
+    .optional(),
+  // Service-scoped config blocks. Audio is the only one today.
+  audio: z
+    .object({
+      codec: z.enum(["lc3", "pcm"]),
+      sampleRate: z.number().int(), // e.g. 16000
+      // LC3 bitrate / frame size in bytes. Only meaningful when codec is
+      // "lc3"; omitted PCM sessions keep treating payload bytes as PCM.
+      frameSizeBytes: z.union([z.literal(20), z.literal(40), z.literal(60)]).optional(),
+      // Optional initial subscription set, seeded atomically with the session
+      // so audio that starts before the first REST update is not transcribed
+      // with an empty set.
+      initialSubscriptions: z.array(audioSubscriptionSchema).optional(),
+    })
+    .optional(),
+});
+export type ConnectionInit = z.infer<typeof connectionInitPayloadSchema>;
+
+// --- connection.ack (cloud to client) ---------------------------------------
+
+export const connectionAckPayloadSchema = z.object({
+  sessionId: z.string(), // control-plane runtime session id
+  negotiatedVersion: z.string(),
+  // Audio session ingest coordinates (audio service, UDP path).
+  audio: z
+    .object({
+      sessionTag: z.number().int(), // u32 stamped into UDP audio frames
+      udp: z.object({ host: z.string(), port: z.number().int() }),
+      // Per-session key for encrypting UDP audio. Delivered here because the
+      // handshake is over the TLS WebSocket.
+      encryption: z.object({
+        algorithm: z.literal("xsalsa20-poly1305"), // NaCl secretbox
+        key: z.string(), // base64, 32 bytes
+      }),
+    })
+    .optional(),
+});
+export type ConnectionAck = z.infer<typeof connectionAckPayloadSchema>;

package/src/index.ts

@@ -0,0 +1,19 @@
+/**
+ * @fileoverview `@glassly/cloud-runtime/protocol` public entrypoint.
+ *
+ * Pure, isomorphic transport types + zod validators for the Glassly Runtime
+ * protocol. Zero server imports (no `node:*`, no service code) so the client
+ * can import the contract without pulling in server code.
+ *
+ * See docs/issues/002-cloud-runtime/protocol.md.
+ */
+export * from "./envelope";
+export * from "./handshake";
+export * from "./control";
+export * from "./errors";
+export * from "./messages";
+export * from "./audio";
+export * from "./languages";
+export * from "./camera";
+export * from "./maps";
+export * from "./llm";

package/src/languages.ts

@@ -0,0 +1,209 @@
+/**
+ * @fileoverview The canonical language registry (issue 021, WP1).
+ *
+ * Single source of truth for every language value that crosses a layer
+ * boundary: miniapp SDK types, miniapp UI pickers, engine validation, cloud
+ * subscription validation, and STT provider config all derive from THIS
+ * module. Per-miniapp mapping tables are banned; the captions bugbash
+ * (OS-1746) traced directly to two hand-maintained registries disagreeing.
+ *
+ * Two vocabularies exist on purpose:
+ *   - `TranscriptionLanguage`: BCP-47 tags ("en-US") used in subscriptions and
+ *     stream keys. What a miniapp asks for.
+ *   - `LanguageHint`: bare ISO 639-1 codes ("en") — the only format the STT
+ *     provider (Soniox) accepts as language hints. Passing a BCP-47 tag kills
+ *     the session with "Invalid language hint." (verified live 2026-07-21).
+ *
+ * Design doc: docs/issues/021-typed-language-subscriptions/README.md
+ */
+
+/**
+ * Bare ISO 639-1 code -> canonical default BCP-47 tag. One entry per language
+ * the platform offers. The key set doubles as the supported-hints list; the
+ * value set doubles as the supported-subscription-tags list.
+ *
+ * Seeded from the 63 languages the captions UI offers (all Soniox stt-rt-v4
+ * supported); regional variants beyond the default (e.g. "en-GB", "zh-TW",
+ * "pt-PT") are listed in EXTRA_REGIONAL_TAGS below.
+ */
+const CANONICAL_TAG_BY_CODE = {
+  af: "af-ZA",
+  am: "am-ET",
+  ar: "ar-AE",
+  az: "az-AZ",
+  be: "be-BY",
+  bg: "bg-BG",
+  bn: "bn-IN",
+  bs: "bs-BA",
+  ca: "ca-ES",
+  cs: "cs-CZ",
+  cy: "cy-GB",
+  da: "da-DK",
+  de: "de-DE",
+  el: "el-GR",
+  en: "en-US",
+  es: "es-ES",
+  et: "et-EE",
+  eu: "eu-ES",
+  fa: "fa-IR",
+  fi: "fi-FI",
+  fr: "fr-FR",
+  gl: "gl-ES",
+  gu: "gu-IN",
+  he: "he-IL",
+  hi: "hi-IN",
+  hr: "hr-HR",
+  hu: "hu-HU",
+  hy: "hy-AM",
+  id: "id-ID",
+  it: "it-IT",
+  ja: "ja-JP",
+  ka: "ka-GE",
+  kk: "kk-KZ",
+  kn: "kn-IN",
+  ko: "ko-KR",
+  lt: "lt-LT",
+  lv: "lv-LV",
+  mk: "mk-MK",
+  ml: "ml-IN",
+  mr: "mr-IN",
+  ms: "ms-MY",
+  nb: "nb-NO",
+  ne: "ne-NP",
+  nl: "nl-NL",
+  no: "nb-NO",
+  pa: "pa-IN",
+  pl: "pl-PL",
+  pt: "pt-BR",
+  ro: "ro-RO",
+  ru: "ru-RU",
+  sk: "sk-SK",
+  sl: "sl-SI",
+  sq: "sq-AL",
+  sr: "sr-RS",
+  sv: "sv-SE",
+  sw: "sw-KE",
+  ta: "ta-IN",
+  te: "te-IN",
+  th: "th-TH",
+  tl: "fil-PH",
+  tr: "tr-TR",
+  uk: "uk-UA",
+  ur: "ur-IN",
+  vi: "vi-VN",
+  zh: "zh-CN",
+} as const;
+
+/**
+ * Regional variants accepted IN ADDITION to the canonical defaults above.
+ * A tag listed here is a valid `TranscriptionLanguage` but is never produced
+ * by bare-code canonicalization.
+ */
+const EXTRA_REGIONAL_TAGS = [
+  "ar-EG",
+  "ar-SA",
+  "de-AT",
+  "de-CH",
+  "en-AU",
+  "en-CA",
+  "en-GB",
+  "en-IN",
+  "es-419",
+  "es-MX",
+  "es-US",
+  "fr-CA",
+  "nl-BE",
+  "pt-PT",
+  "zh-HK",
+  "zh-TW",
+] as const;
+
+type CodeMap = typeof CANONICAL_TAG_BY_CODE;
+
+/** Bare ISO 639-1 hint codes the STT provider accepts ("en", "fr", ...). */
+export type LanguageHint = keyof CodeMap;
+
+/** BCP-47 tags valid in transcription subscriptions and stream keys. */
+export type TranscriptionLanguage =
+  | CodeMap[LanguageHint]
+  | (typeof EXTRA_REGIONAL_TAGS)[number];
+
+/** Every supported hint code, sorted, deduped. */
+export const SUPPORTED_LANGUAGE_HINTS = Object.freeze(
+  [...new Set(Object.keys(CANONICAL_TAG_BY_CODE))].sort(),
+) as readonly LanguageHint[];
+
+/** Every supported subscription tag, sorted, deduped. */
+export const SUPPORTED_TRANSCRIPTION_LANGUAGES = Object.freeze(
+  [
+    ...new Set<string>([
+      ...Object.values(CANONICAL_TAG_BY_CODE),
+      ...EXTRA_REGIONAL_TAGS,
+    ]),
+  ].sort(),
+) as readonly TranscriptionLanguage[];
+
+const TAG_SET = new Set<string>(SUPPORTED_TRANSCRIPTION_LANGUAGES);
+const HINT_SET = new Set<string>(SUPPORTED_LANGUAGE_HINTS);
+
+/** Type guard: is `value` a supported subscription tag? */
+export function isTranscriptionLanguage(
+  value: string,
+): value is TranscriptionLanguage {
+  return TAG_SET.has(value);
+}
+
+/** Type guard: is `value` a supported bare hint code? */
+export function isLanguageHint(value: string): value is LanguageHint {
+  return HINT_SET.has(value);
+}
+
+/**
+ * Canonicalize developer input to a subscription tag:
+ *   - a supported tag passes through ("fr-FR" -> "fr-FR")
+ *   - a bare supported code maps to its canonical default ("fr" -> "fr-FR")
+ *   - anything else returns null (caller decides how loudly to fail)
+ *
+ * Per issue 021 open question 1, bare codes are accepted and canonicalized
+ * rather than rejected: it matches user intent and the canonicalization table
+ * lives HERE, nowhere else.
+ */
+export function toTranscriptionLanguage(
+  value: string,
+): TranscriptionLanguage | null {
+  if (TAG_SET.has(value)) return value as TranscriptionLanguage;
+  const canonical = (CANONICAL_TAG_BY_CODE as Record<string, string>)[
+    value.toLowerCase()
+  ];
+  return (canonical as TranscriptionLanguage) ?? null;
+}
+
+/**
+ * Reduce a subscription tag (or bare code) to the hint format the STT
+ * provider accepts. "en-US" -> "en", "fil-PH" -> "tl" is NOT attempted (the
+ * primary subtag is what providers key on), so "fil-PH" -> "fil" falls back
+ * to null and the caller simply omits the hint. Null means "no valid hint";
+ * never pass the raw value through on null (that is the exact Soniox
+ * session-killer this registry exists to prevent).
+ */
+export function toLanguageHint(value: string): LanguageHint | null {
+  const primary = value.split("-")[0].toLowerCase();
+  return HINT_SET.has(primary) ? (primary as LanguageHint) : null;
+}
+
+/**
+ * Nearest valid tag for an invalid input, for error messages
+ * ("unknown language \"fr_FR\", did you mean \"fr-FR\"?"). Cheap heuristics
+ * only: underscore/case fixes, then primary-subtag canonical default.
+ */
+export function suggestTranscriptionLanguage(
+  value: string,
+): TranscriptionLanguage | null {
+  const normalized = value.replace(/_/g, "-");
+  const parts = normalized.split("-");
+  const recased =
+    parts.length >= 2
+      ? `${parts[0].toLowerCase()}-${parts[1].toUpperCase()}`
+      : normalized.toLowerCase();
+  return toTranscriptionLanguage(recased);
+}

package/src/llm.ts

@@ -0,0 +1,279 @@
+/**
+ * @fileoverview Canonical LLM wire types: single-shot completion + client-side
+ * tool loop.
+ *
+ * zod schemas + inferred TS types for the runtime LLM service. Plain REST
+ * request/result (no WebSocket push, like maps), so nothing here is registered
+ * into the message union. Pure + isomorphic: no server imports, safe to bundle
+ * into the client.
+ *
+ * These are the PROVIDER-NEUTRAL types. Each provider (Anthropic, Gemini)
+ * normalizes its own request/response into these inside its provider file, so
+ * this contract never leaks a vendor's shape — the same rule maps.ts follows.
+ *
+ * DELIBERATELY NOT MODELLED on the COMPLETE surface (the abstraction stops
+ * here on purpose):
+ *   - streaming; every current caller is single-shot request/response
+ *   - provider server-side tools OTHER than web search (Anthropic
+ *     `code_execution` / Files API) — vendor-specific, beta-header-gated,
+ *     and returning vendor-shaped result blocks
+ *
+ * Web search IS modelled, as the one neutral capability flag (`webSearch`):
+ * both Anthropic (`web_search`) and Gemini (`google_search`) offer a
+ * server-side search tool whose results fold into ordinary text output, so a
+ * single boolean stays provider-neutral. Providers without an equivalent
+ * (OpenAI Chat Completions) ignore the flag — it is a capability GRANT, not a
+ * guarantee that a search happens; `webSearchCount` on the result reports what
+ * actually ran.
+ *
+ * The GENERATE surface (llmGenerate*) is the one sanctioned exception: an
+ * agentic visual-generation call where the SERVER runs a provider loop with
+ * server-side tools (web search + code execution + file retrieval) and
+ * returns text plus rendered images. It is Anthropic-only by design and does
+ * not pretend to be provider-neutral — callers get a neutral result shape,
+ * not a neutral capability.
+ */
+import { z } from "zod";
+
+// --- Providers + models -----------------------------------------------------
+
+/**
+ * Provider selector. Omitted means "let the service pick its default", which is
+ * what keeps callers portable — a miniapp that never names a provider keeps
+ * working when the platform default changes.
+ */
+export const llmProviderSchema = z.enum(["anthropic", "gemini", "openai"]);
+export type LlmProvider = z.infer<typeof llmProviderSchema>;
+
+// --- Tools (client-side function calling) -----------------------------------
+
+/**
+ * A tool the CALLER executes. The service never runs these — it relays the
+ * model's request back and waits for the caller to supply results on the next
+ * turn.
+ *
+ * `inputSchema` is JSON Schema. Providers disagree on dialect (Anthropic wants
+ * lowercase `"object"`, Gemini's OpenAPI flavour wants `"OBJECT"`), so callers
+ * write it once in the lowercase JSON Schema form and each provider translates.
+ */
+export const llmToolSchema = z.object({
+  name: z.string().min(1),
+  description: z.string(),
+  /** JSON Schema for the tool's arguments, lowercase-dialect. */
+  inputSchema: z.record(z.unknown()),
+});
+export type LlmTool = z.infer<typeof llmToolSchema>;
+
+/** A model-issued tool call, relayed to the caller to execute. */
+export const llmToolCallSchema = z.object({
+  /**
+   * Correlation id. Anthropic supplies a real `tool_use.id`; Gemini has no ids,
+   * so its provider synthesizes positional ones (`call-0`, `call-1`). Callers
+   * must echo the id back verbatim — never reorder or invent them.
+   */
+  id: z.string(),
+  name: z.string(),
+  input: z.record(z.unknown()),
+});
+export type LlmToolCall = z.infer<typeof llmToolCallSchema>;
+
+/** The caller's answer to one {@link LlmToolCall}. */
+export const llmToolResultSchema = z.object({
+  toolCallId: z.string(),
+  /** Serialized result. Callers JSON.stringify structured data themselves. */
+  content: z.string(),
+  /** True when the tool failed; the model is told so it can recover. */
+  isError: z.boolean().optional(),
+});
+export type LlmToolResult = z.infer<typeof llmToolResultSchema>;
+
+// --- Conversation -----------------------------------------------------------
+
+/**
+ * One turn. `toolCalls` is only present on assistant turns the model paused on;
+ * `toolResults` only on user turns answering them.
+ *
+ * The whole array round-trips through the caller on every request: the service
+ * holds NO per-conversation state. That mirrors the existing relay design in
+ * the assistant backend, where the conversation is client-held precisely so any
+ * replica can serve the next turn.
+ */
+export const llmMessageSchema = z.object({
+  role: z.enum(["user", "assistant"]),
+  content: z.string(),
+  toolCalls: z.array(llmToolCallSchema).optional(),
+  toolResults: z.array(llmToolResultSchema).optional(),
+});
+export type LlmMessage = z.infer<typeof llmMessageSchema>;
+
+// --- Request ----------------------------------------------------------------
+
+export const llmCompleteRequestSchema = z.object({
+  /** Conversation so far. At least one turn. */
+  messages: z.array(llmMessageSchema).min(1),
+  /** System prompt. Providers place this in their own system slot. */
+  system: z.string().optional(),
+  provider: llmProviderSchema.optional(),
+  /** Provider-specific model id. Omit to use the provider's default. */
+  model: z.string().optional(),
+  maxTokens: z.number().int().positive().max(32_000).optional(),
+  temperature: z.number().min(0).max(2).optional(),
+  /**
+   * Ask for a JSON object back. Gemini sets `responseMimeType`; Anthropic has
+   * no equivalent knob, so its provider appends a system-prompt instruction.
+   * Either way the caller still has to parse and validate the text.
+   */
+  jsonMode: z.boolean().optional(),
+  /** Client-side tools. See {@link LlmTool}. */
+  tools: z.array(llmToolSchema).optional(),
+  /**
+   * Let the model search the web (the provider's own server-side search tool)
+   * when it decides live data would help. A grant, not a command: the model
+   * may answer without searching, and providers with no equivalent tool ignore
+   * the flag entirely. Searches run inside this single call — there is no
+   * extra round-trip — and platform-funded searches are metered with a
+   * per-search surcharge on top of tokens.
+   */
+  webSearch: z.boolean().optional(),
+});
+export type LlmCompleteRequest = z.infer<typeof llmCompleteRequestSchema>;
+
+// --- Result -----------------------------------------------------------------
+
+/**
+ * Why the model stopped.
+ *   `end_turn`    — finished normally.
+ *   `tool_use`    — wants tool results; `toolCalls` is populated. Answer them
+ *                   and call again with the turn appended.
+ *   `max_tokens`  — hit the output cap; `text` is truncated.
+ *   `refusal`     — declined to answer. Note this arrives as a SUCCESS, not an
+ *                   error, matching how Anthropic reports it (HTTP 200 with
+ *                   stop_reason "refusal") — see miniapps/notes/src/background/llm.ts.
+ */
+export const llmStopReasonSchema = z.enum(["end_turn", "tool_use", "max_tokens", "refusal"]);
+export type LlmStopReason = z.infer<typeof llmStopReasonSchema>;
+
+/**
+ * Token counts for this call. Every provider reports these; the platform meters
+ * them per user. Zero is a legitimate value (a refusal may spend no output
+ * tokens), so callers must not treat 0 as "unknown".
+ */
+export const llmUsageSchema = z.object({
+  inputTokens: z.number().int().nonnegative(),
+  outputTokens: z.number().int().nonnegative(),
+});
+export type LlmUsage = z.infer<typeof llmUsageSchema>;
+
+// --- Generate (agentic visual generation) -----------------------------------
+
+/**
+ * Request for one agentic generation run. The server drives the provider loop
+ * (web search for live data, code execution for rendering, file retrieval for
+ * image bytes) — the caller sends a single prompt and gets the finished
+ * result. No conversation, no client tools: one shot per call.
+ */
+export const llmGenerateRequestSchema = z.object({
+  /** The task, written by the caller (usually composed by an on-device model). */
+  prompt: z.string().min(1).max(20_000),
+  /** Optional extra system guidance appended to the server's base prompt. */
+  system: z.string().max(10_000).optional(),
+  /** Provider-specific model id. Omit to use the generate default. */
+  model: z.string().optional(),
+  /** Output-token budget per round. The server clamps to its own ceiling. */
+  maxTokens: z.number().int().positive().max(32_000).optional(),
+  /** Agentic round budget (pause_turn continuations). Server-clamped. */
+  maxRounds: z.number().int().positive().max(6).optional(),
+});
+export type LlmGenerateRequest = z.infer<typeof llmGenerateRequestSchema>;
+
+/** One image produced by the run, ready to display. */
+export const llmGeneratedImageSchema = z.object({
+  /** Base64 image bytes (no data: prefix). */
+  data: z.string(),
+  mimeType: z.string(),
+  width: z.number().int().positive().optional(),
+  height: z.number().int().positive().optional(),
+});
+export type LlmGeneratedImage = z.infer<typeof llmGeneratedImageSchema>;
+
+export const llmGenerateResultSchema = z.object({
+  /** The model's final text (caption/answer). May be empty if it only drew. */
+  text: z.string(),
+  /** Images extracted from the run, in generation order. */
+  images: z.array(llmGeneratedImageSchema),
+  stopReason: llmStopReasonSchema,
+  usage: llmUsageSchema.extend({
+    /** Agentic rounds actually consumed. */
+    rounds: z.number().int().nonnegative(),
+  }),
+  provider: llmProviderSchema,
+  model: z.string(),
+  billedToUserKey: z.boolean(),
+});
+export type LlmGenerateResult = z.infer<typeof llmGenerateResultSchema>;
+
+// --- Generate jobs (async progress/cancel wrapper over generate) ------------
+
+/**
+ * A generate run wrapped in a pollable job, so a caller staring at a 10-60s
+ * agentic loop can show honest progress and cancel an abandoned run.
+ *
+ *   POST   /api/llm/generate/jobs      -> { jobId }        (202)
+ *   GET    /api/llm/generate/jobs/:id  -> LlmGenerateJobStatus
+ *   DELETE /api/llm/generate/jobs/:id  -> LlmGenerateJobStatus (cancelled)
+ *
+ * The job store is in-memory per runtime instance: a poll must land on the
+ * instance that created the job. True for a phone talking to one region over
+ * a stable connection; a cross-region failover mid-job surfaces as 404 and
+ * the caller treats it like a failed run.
+ *
+ * `activity` is a coarse, forward-compatible label ("thinking" | "searching"
+ * | "drawing" | "finishing" today) — clients map known values to UI copy and
+ * fall back to a generic label for unknown ones, so the server can refine
+ * labels without a lockstep client release.
+ */
+export const llmGenerateJobStateSchema = z.enum(["running", "done", "error", "cancelled"]);
+export type LlmGenerateJobState = z.infer<typeof llmGenerateJobStateSchema>;
+
+export const llmGenerateJobCreatedSchema = z.object({
+  jobId: z.string().min(1),
+});
+export type LlmGenerateJobCreated = z.infer<typeof llmGenerateJobCreatedSchema>;
+
+export const llmGenerateJobStatusSchema = z.object({
+  jobId: z.string().min(1),
+  state: llmGenerateJobStateSchema,
+  /** What the run is doing right now; only meaningful while `state` is "running". */
+  activity: z.string().optional(),
+  /** Present iff `state` is "done". */
+  result: llmGenerateResultSchema.optional(),
+  /** Present iff `state` is "error". */
+  error: z.string().optional(),
+});
+export type LlmGenerateJobStatus = z.infer<typeof llmGenerateJobStatusSchema>;
+
+export const llmCompleteResultSchema = z.object({
+  /** Concatenated text blocks. Empty string when the model only called tools. */
+  text: z.string(),
+  stopReason: llmStopReasonSchema,
+  /** Populated iff `stopReason === "tool_use"`. */
+  toolCalls: z.array(llmToolCallSchema).optional(),
+  usage: llmUsageSchema,
+  /** Which provider/model actually served this — the request may have omitted both. */
+  provider: llmProviderSchema,
+  model: z.string(),
+  /**
+   * True when the caller's own API key paid for this call. Such calls are NOT
+   * metered against the account, so the Settings usage display can explain why
+   * a number looks lower than expected.
+   */
+  billedToUserKey: z.boolean(),
+  /**
+   * Server-side web searches the model actually ran (see `webSearch` on the
+   * request). Absent/0 when the request didn't grant search, the provider has
+   * no search tool, or the model answered from knowledge. Drives the
+   * per-search metering surcharge.
+   */
+  webSearchCount: z.number().int().nonnegative().optional(),
+});
+export type LlmCompleteResult = z.infer<typeof llmCompleteResultSchema>;

package/src/maps.ts

@@ -0,0 +1,199 @@
+/**
+ * @fileoverview Canonical maps wire types: directions + reverse geocoding.
+ *
+ * zod schemas + inferred TS types for the maps service. Both flows are plain
+ * REST request/result (no WebSocket push, unlike camera), so nothing here is
+ * registered into the message union. Pure + isomorphic: no server imports, safe
+ * to bundle into the client.
+ *
+ * The vocabulary (TravelMode, ManeuverKind, avoidances, the route/step shapes)
+ * deliberately mirrors the mobile miniapp navigation SDK
+ * (mobile/modules/miniapp/src/modules/navigation.ts) so the contract is identical
+ * end-to-end: miniapp SDK <-> cloud-client <-> runtime. These are the PROVIDER-
+ * NEUTRAL types; each provider (Mapbox, Google) normalizes its own response into
+ * these inside its provider file, so this contract never leaks a vendor's shape.
+ *
+ * See docs/issues/002-cloud-runtime/maps/spec.md.
+ */
+import { z } from "zod";
+
+// --- Shared geometry --------------------------------------------------------
+
+export const latLngSchema = z.object({
+  lat: z.number(),
+  lng: z.number(),
+});
+export type LatLng = z.infer<typeof latLngSchema>;
+
+/** Travel profile. Providers map this to their own profile vocabulary. */
+export const travelModeSchema = z.enum(["walking", "driving", "cycling", "two_wheeler"]);
+export type TravelMode = z.infer<typeof travelModeSchema>;
+
+/** Routing preferences. All flags default to false. */
+export const routeAvoidancesSchema = z.object({
+  highways: z.boolean().optional(),
+  tolls: z.boolean().optional(),
+  ferries: z.boolean().optional(),
+});
+export type RouteAvoidances = z.infer<typeof routeAvoidancesSchema>;
+
+/**
+ * Neutral maneuver vocabulary. Each provider maps its own maneuver type/modifier
+ * vocabulary into exactly these values; consumers never see vendor strings.
+ */
+export const maneuverKindSchema = z.enum([
+  "STRAIGHT",
+  "CONTINUE",
+  "SLIGHT_LEFT",
+  "SLIGHT_RIGHT",
+  "TURN_LEFT",
+  "TURN_RIGHT",
+  "SHARP_LEFT",
+  "SHARP_RIGHT",
+  "U_TURN",
+  "NAME_CHANGE",
+  "DEPART",
+  "ARRIVE",
+  "CROSS_STREET",
+]);
+export type ManeuverKind = z.infer<typeof maneuverKindSchema>;
+
+// --- Directions -------------------------------------------------------------
+
+export const directionsRequestSchema = z.object({
+  origin: latLngSchema,
+  /** Ordered stops; last is the final destination. Must have >= 1 entry. */
+  stops: z.array(latLngSchema).min(1),
+  /** Defaults to "driving" when omitted. */
+  mode: travelModeSchema.optional(),
+  avoid: routeAvoidancesSchema.optional(),
+  /**
+   * Total number of routes to return — the primary plus any alternates, provider
+   * permitting. 1 (the default) means the primary route only, no alternates; a
+   * value > 1 asks the provider for alternates. (Mirrors the prior on-device
+   * behavior: Mapbox `alternatives` is requested only when this exceeds 1.)
+   */
+  alternatives: z.number().int().positive().optional(),
+});
+export type DirectionsRequest = z.infer<typeof directionsRequestSchema>;
+
+/** One step of a computed route. The maneuver ENDS the segment. */
+export const routeStepSchema = z.object({
+  lat: z.number(),
+  lng: z.number(),
+  endLat: z.number(),
+  endLng: z.number(),
+  distanceMeters: z.number(),
+  maneuver: maneuverKindSchema.optional(),
+  /** Full instruction from the provider (e.g. "Turn left onto Fell St"). */
+  instruction: z.string().optional(),
+  /** Resolved road name. Prefer this over parsing `instruction`. */
+  road: z.string().nullable().optional(),
+});
+export type RouteStep = z.infer<typeof routeStepSchema>;
+
+export const routeSchema = z.object({
+  points: z.array(latLngSchema),
+  totalDistanceMeters: z.number(),
+  totalDurationSeconds: z.number(),
+  summary: z.string().optional(),
+  steps: z.array(routeStepSchema).optional(),
+});
+export type Route = z.infer<typeof routeSchema>;
+
+/** The REST response for `POST /api/maps/directions`. Primary route first. */
+export const directionsResultSchema = z.object({
+  routes: z.array(routeSchema),
+});
+export type DirectionsResult = z.infer<typeof directionsResultSchema>;
+
+// --- Reverse geocoding ------------------------------------------------------
+
+export const reverseGeocodeRequestSchema = latLngSchema;
+export type ReverseGeocodeRequest = z.infer<typeof reverseGeocodeRequestSchema>;
+
+/**
+ * The REST response for `POST /api/maps/reverse-geocode`.
+ *
+ * - `road`    — short street name (e.g. "Hayes Street"). Backs the pivot
+ *   engine's road-name fallback.
+ * - `address` — full formatted street address with house number + locality
+ *   (e.g. "369 Hayes Street, San Francisco, California 94102"). Backs the
+ *   navigation miniapp's dropped-pin / POI-tap labels.
+ *
+ * Either field is null when nothing of that kind was found near the coordinate;
+ * that is a successful empty answer, not an error (an actual failure is a
+ * non-2xx response).
+ */
+export const reverseGeocodeResultSchema = z.object({
+  road: z.string().nullable(),
+  address: z.string().nullable(),
+});
+export type ReverseGeocodeResult = z.infer<typeof reverseGeocodeResultSchema>;
+
+// --- Place search (autocomplete + details) ----------------------------------
+//
+// A two-step "type-ahead then pick" flow, provider-neutral like the rest of this
+// file. `placeAutocomplete` lists lightweight suggestions as the user types;
+// `placeDetails` resolves the chosen suggestion to coordinates. A `sessionToken`
+// threads BOTH calls so the provider can bill the keystrokes + the final detail
+// fetch as ONE search session (Mapbox Search Box and Google Places both work
+// this way). Callers create one token per "search box opening" and rotate it
+// after a pick.
+
+export const placeAutocompleteRequestSchema = z.object({
+  /** The user's partial query. Empty/whitespace yields no suggestions. */
+  query: z.string(),
+  /** Optional location bias — rank results near this coordinate. */
+  near: latLngSchema.optional(),
+  /** Opaque per-search-session token; the same value should go on `placeDetails`. */
+  sessionToken: z.string(),
+});
+export type PlaceAutocompleteRequest = z.infer<typeof placeAutocompleteRequestSchema>;
+
+/** One type-ahead suggestion. `placeId` is fed back into `placeDetails`. */
+export const placeSuggestionSchema = z.object({
+  placeId: z.string(),
+  /** Primary line, e.g. "Blue Bottle Coffee". */
+  mainText: z.string(),
+  /** Secondary line, e.g. "66 Mint St, San Francisco". Empty when none. */
+  secondaryText: z.string(),
+});
+export type PlaceSuggestion = z.infer<typeof placeSuggestionSchema>;
+
+export const placeAutocompleteResultSchema = z.object({
+  suggestions: z.array(placeSuggestionSchema),
+});
+export type PlaceAutocompleteResult = z.infer<typeof placeAutocompleteResultSchema>;
+
+export const placeDetailsRequestSchema = z.object({
+  /** A `placeId` returned by a prior `placeAutocomplete` suggestion. */
+  placeId: z.string(),
+  /** The same session token used for the autocomplete that produced this id. */
+  sessionToken: z.string(),
+});
+export type PlaceDetailsRequest = z.infer<typeof placeDetailsRequestSchema>;
+
+/** The resolved place: a name, formatted address, and coordinates to route to. */
+export const placeDetailsResultSchema = z.object({
+  placeId: z.string(),
+  name: z.string(),
+  address: z.string(),
+  lat: z.number(),
+  lng: z.number(),
+});
+export type PlaceDetailsResult = z.infer<typeof placeDetailsResultSchema>;
+
+/**
+ * The deployment's PUBLIC client-side map render token. Some map consumers
+ * cannot be proxied through the cloud (map tile rendering, native map SDKs) —
+ * this is the token the runtime hands to authenticated clients for those, so
+ * the mobile binary ships no baked provider key. `token` is null when the
+ * deployment has none configured; it is never a secret-scope credential.
+ */
+export const mapsRenderTokenResultSchema = z.object({
+  /** Provider the token belongs to (e.g. "mapbox"). */
+  provider: z.string(),
+  token: z.string().nullable(),
+});
+export type MapsRenderTokenResult = z.infer<typeof mapsRenderTokenResultSchema>;

package/src/messages.ts

@@ -0,0 +1,82 @@
+/**
+ * @fileoverview The WebSocket message registry.
+ *
+ * Each transport `type` maps 1:1 to an enveloped zod schema; the schemas are
+ * combined into discriminated unions on `type` for parse-time validation on
+ * both ends. Transport-level types live in protocol.md; per-service push events
+ * (stream.transcript / stream.translation) are registered by the audio service
+ * doc but their schemas live here so the one union validates everything.
+ *
+ * Pure + isomorphic: no server imports.
+ */
+import { z } from "zod";
+import { envelope } from "./envelope";
+import { connectionInitPayloadSchema, connectionAckPayloadSchema } from "./handshake";
+import { controlPingPayloadSchema, controlPongPayloadSchema } from "./control";
+import { protocolErrorPayloadSchema } from "./errors";
+import {
+  quotaStatusPayloadSchema,
+  transcriptionDataSchema,
+  translationDataSchema,
+  udpLivenessAckPayloadSchema,
+} from "./audio";
+import { photoReadyPayloadSchema, photoErrorPayloadSchema } from "./camera";
+
+// --- Per-type enveloped message schemas -------------------------------------
+
+export const connectionInitMessage = envelope("connection.init", connectionInitPayloadSchema);
+export const connectionAckMessage = envelope("connection.ack", connectionAckPayloadSchema);
+export const controlPingMessage = envelope("control.ping", controlPingPayloadSchema);
+export const controlPongMessage = envelope("control.pong", controlPongPayloadSchema);
+export const errorMessage = envelope("error", protocolErrorPayloadSchema);
+
+// Audio service push events (registered in audio/protocol.md).
+export const streamTranscriptMessage = envelope("stream.transcript", transcriptionDataSchema);
+export const streamTranslationMessage = envelope("stream.translation", translationDataSchema);
+export const audioUdpLivenessAckMessage = envelope("audio.udp_liveness_ack", udpLivenessAckPayloadSchema);
+export const streamQuotaMessage = envelope("stream.quota", quotaStatusPayloadSchema);
+
+// Camera service push events (registered in camera/spec.md).
+export const photoReadyMessage = envelope("photo.ready", photoReadyPayloadSchema);
+export const photoErrorMessage = envelope("photo.error", photoErrorPayloadSchema);
+
+// --- Direction-scoped unions ------------------------------------------------
+
+/** Messages the client sends to the cloud. */
+export const clientToCloudMessage = z.discriminatedUnion("type", [
+  connectionInitMessage,
+  controlPingMessage,
+  controlPongMessage,
+]);
+export type ClientToCloudMessage = z.infer<typeof clientToCloudMessage>;
+
+/** Messages the cloud pushes to the client. */
+export const cloudToClientMessage = z.discriminatedUnion("type", [
+  connectionAckMessage,
+  controlPingMessage,
+  controlPongMessage,
+  errorMessage,
+  streamTranscriptMessage,
+  streamTranslationMessage,
+  audioUdpLivenessAckMessage,
+  streamQuotaMessage,
+  photoReadyMessage,
+  photoErrorMessage,
+]);
+export type CloudToClientMessage = z.infer<typeof cloudToClientMessage>;
+
+/** Every known message in either direction. */
+export const anyMessage = z.discriminatedUnion("type", [
+  connectionInitMessage,
+  connectionAckMessage,
+  controlPingMessage,
+  controlPongMessage,
+  errorMessage,
+  streamTranscriptMessage,
+  streamTranslationMessage,
+  audioUdpLivenessAckMessage,
+  streamQuotaMessage,
+  photoReadyMessage,
+  photoErrorMessage,
+]);
+export type AnyMessage = z.infer<typeof anyMessage>;