@fleetless/contracts 1.0.0

package/dist/realtime.js

@@ -0,0 +1,512 @@
+// SPDX-License-Identifier: Apache-2.0
+import { z } from 'zod';
+import { RESOURCE_HEALTH_STATES } from './rest.js';
+import { MAX_PATIENCE_MS, MIN_PATIENCE_MS } from './protocol.js';
+import { slug } from './common.js';
+import { clientIdentity } from './client-auth.js';
+import { job } from './jobs.js';
+/**
+ * Client realtime protocol (spec §11.1): WebSocket subscriptions on
+ * datapoints. W1 scope: subscribe/unsubscribe plus the datapoint event
+ * stream; command parity arrives in W4.
+ */
+/**
+ * The first frame a client sends after the socket opens (W3, spec §3.4).
+ *
+ * A browser cannot set an `Authorization` header on a WebSocket handshake,
+ * and a token in the query string would outlive the request in server,
+ * proxy and browser-history logs. So `/realtime` authenticates the way
+ * `/bridge` already does: with a frame. `token` is the same bearer value
+ * REST takes — a user's JWT or a server key (`flk_…`), told apart by prefix.
+ *
+ * Any `subscribe` before `auth_ok` is refused, and a socket that sends no
+ * auth frame in time is closed with **4002**, the code the bridge socket
+ * already uses for a missing hello.
+ */
+export const clientAuth = z.object({
+    type: z.literal('auth'),
+    token: z.string().min(1),
+});
+/**
+ * Who the socket turned out to belong to. Carrying the identity here means a
+ * client never has to decode a JWT to render its own session — decoding a
+ * token client-side is how apps end up trusting claims nobody verified.
+ */
+export const authOk = z.object({
+    type: z.literal('auth_ok'),
+    identity: clientIdentity,
+});
+/** Refusal, followed by close 1008 — same shape as the bridge's hello_error. */
+export const authError = z.object({
+    type: z.literal('auth_error'),
+    code: z.string().min(1),
+    message: z.string().min(1),
+});
+/**
+ * Command parity (spec §11.1): everything REST can do — invoke an action,
+ * call a service, publish, cancel — also travels over this socket.
+ *
+ * **Every command carries a `request_id` and every reply echoes it.** A
+ * subscribe that gets dropped is self-healing: the client resubscribes on
+ * reconnect and nothing was promised. A *command* that gets dropped is an
+ * instruction someone believes they issued and no one will ever run — on a
+ * machine that may be moving. Correlation is what makes the difference
+ * observable instead of silent.
+ */
+export const clientInvoke = z.object({
+    type: z.literal('invoke'),
+    request_id: z.string().min(1).max(64),
+    robot_id: z.uuid(),
+    slug,
+    /** Parameters by field path, validated against the config's rules (§4.4). */
+    params: z.record(z.string(), z.unknown()),
+    /**
+     * How long this one call is worth waiting for (W6b) — the same field,
+     * meaning and cap as `invokeRequest.patience_ms`; absent means
+     * `DEFAULT_PATIENCE_MS`.
+     *
+     * It is here because **§11.1 parity is a rule, not a preference**: what REST
+     * can do travels over this socket. The first version of this delta gave
+     * `patience_ms` to the REST body only — and the SDK invokes exclusively over
+     * the realtime channel, so the field would have been unreachable for every
+     * SDK caller while appearing in the documentation. W6a shipped four SDK
+     * methods no SDK caller could invoke; this is the same defect caught before
+     * it shipped, by the SDK owner rather than by a reviewer.
+     */
+    patience_ms: z.number().int().min(MIN_PATIENCE_MS).max(MAX_PATIENCE_MS).optional(),
+});
+export const clientCancel = z.object({
+    type: z.literal('cancel'),
+    request_id: z.string().min(1).max(64),
+    robot_id: z.uuid(),
+    /** Which slug — required, and the only address a cancel had until W6b. */
+    slug,
+    /**
+     * Which job on that slug (W6b), or `null` for *whatever is running there*.
+     *
+     * The two are different requests and both are legitimate. An operator
+     * hitting a stop button means the second: stop the machine, whatever it is
+     * doing. A client cancelling the job it started means the first — and until
+     * this field existed it could not say so, so a cancel that arrived just
+     * after its own job ended stopped the next caller's job instead. Same slug,
+     * same wire frame, entirely different machine behaviour, and nothing in the
+     * protocol able to tell them apart.
+     *
+     * A named id that is not running answers `not_found` rather than falling
+     * back to the slug. Falling back would be the platform deciding that the
+     * caller did not really mean the id they typed.
+     */
+    job_id: z.uuid().nullable(),
+});
+export const clientPublish = z.object({
+    type: z.literal('publish'),
+    request_id: z.string().min(1).max(64),
+    robot_id: z.uuid(),
+    slug,
+    message: z.record(z.string(), z.unknown()),
+});
+/**
+ * The reply to exactly one command. `ok:false` carries the stable code —
+ * `busy`, `robot_offline`, `parameter_invalid`, `forbidden` — so a caller
+ * branches without parsing prose.
+ *
+ * **`request_id` is the only correlation, and the order these arrive in is
+ * not promised.** Commands sent on one socket reach the robot in the order
+ * they were sent — that ordering is guaranteed and is the point of the
+ * command chain — but their *replies* may arrive in any order, and a client
+ * that pairs them up by arrival order will attribute an outcome to the wrong
+ * command.
+ *
+ * This is not theoretical and not jitter. The ordering chain is released once
+ * a command has reached the bridge, deliberately, so that the next command —
+ * a stop, say — is never held up behind bookkeeping. Work that follows the
+ * send therefore runs unordered: a publish that *acquires* a slug writes an
+ * audit record before answering, while an immediately following publish by
+ * the now-current holder has nothing to write and answers at once. Its reply
+ * overtakes. Measured in W5: exactly one reversal in fifty-six zero-gap
+ * bursts, which is the signature of that cause — it can happen only once per
+ * identity and slug — and not of a race.
+ *
+ * Serialising the replies would mean putting that bookkeeping in front of
+ * every following command, including the stop. The ordering that matters is
+ * the one on the wire to the robot, and it is kept.
+ */
+export const commandResult = z.object({
+    type: z.literal('command_result'),
+    request_id: z.string().min(1).max(64),
+    ok: z.boolean(),
+    /**
+     * The job this reply is *about* — which is not always the caller's own.
+     *
+     * - `ok:true` on an invoke or a call: the job that was just created.
+     * - `ok:true` on a cancel: the job the cancel was sent to.
+     * - `ok:false, code:'busy'`: **the job that is already running** — the
+     *   caller has none. This is the §11.3 "inkl. Information, was läuft", and
+     *   it is the whole reason a busy refusal is useful: the caller learns
+     *   whether to wait or to give up (see `busyDetails`).
+     * - any other refusal: `null`.
+     */
+    job: job.nullable(),
+    /**
+     * The **kind** of the slug this command addressed, when the slug resolved.
+     *
+     * Invoke and call share a route on purpose — both create the job on the
+     * slug — but a *client* library distinguishes them: `services.call` waits
+     * for a terminal state, `actions.invoke` does not. Without the kind coming
+     * back, calling a service helper on an action slug **starts the real action
+     * on the robot** and then blames the robot for not finishing, half a minute
+     * later. Returning the kind lets a client refuse its own mistake at once,
+     * instead of reporting it as the machine's.
+     */
+    kind: z.enum(['datapoint', 'action', 'service', 'publisher', 'camera']).nullable(),
+    code: z.string().nullable(),
+    message: z.string().nullable(),
+    /**
+     * The same payload the REST envelope carries in `apiError.details` — for
+     * `parameter_invalid`, a `parameterInvalidDetails`.
+     *
+     * Added because it was missing, and its absence quietly broke §11.1: this
+     * socket is supposed to do *everything* REST can do, but a
+     * `parameter_invalid` arriving here had nowhere to put its violations, so
+     * the same refusal was actionable over HTTP and opaque over the socket.
+     * A client cannot bind an error to the input that caused it from a code
+     * alone — which is the entire point of the flat parameter shape.
+     */
+    details: z.unknown().optional(),
+});
+/**
+ * A well-formed frame this server does not understand. The socket **stays
+ * open** — closing it would mean a newer client against an older cloud
+ * reconnects, resends, and takes every unrelated subscription down with it
+ * on every attempt. Close 1008 is reserved for frames that are not parseable
+ * JSON objects at all.
+ */
+export const errorFrame = z.object({
+    type: z.literal('error'),
+    code: z.string().min(1),
+    message: z.string().min(1),
+});
+/**
+ * Subscribe to a slug's stream (spec §11.3: **state is observed by slug**).
+ *
+ * Which kinds are subscribable, and why it is not a matter of taste:
+ *
+ * - **datapoint** — its values.
+ * - **action** — its `jobEvent`s.
+ * - **service** — its `jobEvent`s too. A service call mints a job like an
+ *   action does; the only difference is that the caller usually gets the
+ *   result inline. But when they do *not* — a socket that died before the
+ *   reply, answered with `command_outcome_unknown` — the documented recovery
+ *   is to observe the slug. Refusing that leaves the caller with an error
+ *   that names a remedy the platform does not offer.
+ * - **publisher** — not subscribable: there is no job and no stream. It must
+ *   still be refused *honestly*, with a code saying so, and never as though
+ *   the slug did not exist. A caller who was granted a slug is entitled to
+ *   be told the truth about it.
+ */
+export const clientSubscribe = z.object({
+    type: z.literal('subscribe'),
+    robot_id: z.uuid(),
+    slug,
+    /**
+     * What the subscriber expects, and how it wants it (W5).
+     *
+     * `kind` lets the server answer **`wrong_kind`** instead of accepting a
+     * subscribe the client will then filter to silence — and silence is
+     * indistinguishable from an idle slug, so it tells a developer nothing.
+     * Optional, so an older client that omits it keeps today's behaviour.
+     *
+     * `options` is where a camera says what it wants; a datapoint needs none.
+     * It exists now rather than later because adding a field to a frame three
+     * repos parse is cheap once and expensive twice.
+     */
+    /**
+     * `publisher` is here even though a publisher is not subscribable: a client
+     * that models the five grantable kinds and honestly names one gets the
+     * informative `not_subscribable` the cloud already computes, instead of a
+     * `validation_error` reciting an enum. Refusing the *word* rather than the
+     * request was the same mistake as the silent wrong-verb subscribe this
+     * field was added to fix.
+     */
+    kind: z.enum(['datapoint', 'action', 'service', 'publisher', 'camera']).optional(),
+    options: z.record(z.string(), z.unknown()).optional(),
+});
+export const clientUnsubscribe = z.object({
+    type: z.literal('unsubscribe'),
+    robot_id: z.uuid(),
+    slug,
+});
+/**
+ * Refusal of a subscribe, addressed by the (robot_id, slug) it refers to.
+ * Codes follow the §11.5 error culture: stable code + human message.
+ * robot_id/slug are plain strings ECHOING what the client sent — the frame
+ * must be constructible precisely when those values are malformed, so that
+ * a bad robot_id or slug gets a diagnosis instead of a dead socket.
+ */
+export const subscribeError = z.object({
+    type: z.literal('subscribe_error'),
+    robot_id: z.string(),
+    slug: z.string(),
+    code: z.string().min(1),
+    message: z.string().min(1),
+});
+/**
+ * One datapoint sample pushed to a subscriber. The current value arrives
+ * immediately on subscribe, then every change. `timestamp_ms` semantics as
+ * in `datapointValue` (capture time; cloud-observed for `bridge_state`).
+ */
+export const datapointEvent = z.object({
+    type: z.literal('datapoint'),
+    robot_id: z.uuid(),
+    slug,
+    value: z.unknown(),
+    timestamp_ms: z.number().int().nonnegative(),
+});
+/**
+ * A change in the health of something the developer configured (W6a).
+ *
+ * The push half of `resourceHealthState`; the REST list is the snapshot half,
+ * and neither is useful alone — a page that loads after the change would see
+ * nothing, and a page that never reloads would never learn.
+ *
+ * Delivered on the **developer** socket and scoped to the org, not to a
+ * subscription: the whole point is to reach somebody who is *not* currently
+ * looking at the thing that broke.
+ */
+/**
+ * Why a live camera session ended (W9a).
+ *
+ * **The reason travels WITH the ending, and that is the whole point of this
+ * enum existing rather than a state somebody reads afterwards.** W6a put a
+ * `cause` on the wire, the console named the real reason, and the lead
+ * observed the gate step and closed it — and the review then found it still
+ * could not tell, for a different reason: `stopped_by_config_change` is
+ * **sticky**, nothing moves a camera out of it, and `LiveCameraRow` read that
+ * *current* state at the moment a stream ended. A config change at 10:00 and
+ * an unrelated release at 10:30 therefore reported the same cause (DEF-070).
+ *
+ * A state read after the fact answers "what is true now". A viewer needs
+ * "what happened to my session", and only an event carries that.
+ */
+export const liveSessionEndReason = z.enum([
+    /** Another holder of this camera released it — another tab, or another client. */
+    'released_by_peer',
+    /** The robot's configuration was published and this camera changed with it. */
+    'config_changed',
+    /** The robot said it could not publish. `detail` carries its own words. */
+    'publish_failed',
+    /** The bridge stopped answering. */
+    'robot_offline',
+    /** The grant this session was minted under was withdrawn. */
+    'revoked',
+    /** The session's own lifetime ran out. */
+    'expired',
+    /** The robot was deleted out from under the session. */
+    'robot_deleted',
+    /**
+     * The cloud ended it and cannot say which of the above applied. **Kept
+     * deliberately**: a channel that cannot say "I do not know" will say
+     * something false instead, and this project has paid for that four times in
+     * the camera path alone.
+     */
+    'unknown',
+]);
+/**
+ * A live camera session ended, told to the **client that holds it** (W9a).
+ *
+ * This is the channel `DEF-051`, `DEF-052`, `DEF-053` and `DEF-070` each
+ * described from a different direction across four waves. Until now the only
+ * vehicle was `camera_state`, which the cloud stores in `publishState` and
+ * reads in exactly one place — refusing a *later* joiner — so reporting a
+ * failure would have written to a dead end.
+ *
+ * Unlike `resourceHealthEvent`, which is developer-only and org-scoped, this
+ * one is addressed to the **holder of the session**: it names `session_id`
+ * (W6b gave `liveSessionResponse` one precisely so a session could be
+ * addressed) and is delivered only to the identity that session was minted
+ * for. A developer watching the same robot learns about the *resource* health;
+ * the viewer learns about *their own session*. Two questions, two channels,
+ * on purpose.
+ */
+export const liveSessionEvent = z.object({
+    type: z.literal('live_session'),
+    robot_id: z.uuid(),
+    slug,
+    session_id: z.uuid(),
+    state: z.literal('ended'),
+    reason: liveSessionEndReason,
+    /**
+     * **Classified text the cloud produced, never text the robot sent.**
+     *
+     * An earlier draft of this comment said *"the robot's own words when it has
+     * any"*, which reads as permission to pass `bridgeCameraState.error.message`
+     * straight through. Nothing sanitises that field, and this codebase has a
+     * documented incident of a password reaching a developer surface through
+     * exactly that route — `camera-health.ts`'s fixed-string `REASON` discipline
+     * exists because of it. Nimbus-W9a stopped at the sentence and asked rather
+     * than taking the permission it appeared to give (2026-08-19).
+     *
+     * So: `null` unless the cloud itself has something classified to say. If a
+     * developer needs the robot's own diagnosis later, it arrives as a mapped
+     * code with fixed text, the way camera health already does it — not as
+     * forwarded foreign text on a channel a client reads.
+     */
+    detail: z.string().max(200).nullable(),
+    /** When it ended — not when this frame was sent. Same reasoning as `changed_at_ms`. */
+    ended_at_ms: z.number().int().nonnegative(),
+});
+/**
+ * A resource's health entry was **withdrawn** (W9a, DEF-071).
+ *
+ * The store's `invalidate()` deliberately emitted nothing, reasoning that
+ * "withdrawing a claim nobody can currently stand behind is not new
+ * information — the next `GET` already reflects it." That holds for a page
+ * that loads later. **It is false for a page that is already open, because
+ * there is no next `GET`:** `ensureSnapshot()` runs on `acquire` and nowhere
+ * else, there is no interval, and the event handler only ever *writes* keys.
+ * A camera retargeted to a source that never reports — which is the case the
+ * clearing exists for — leaves an open tab showing the old value indefinitely.
+ *
+ * **A separate event type rather than a nullable `state` on the existing
+ * one**, so a consumer's `switch` has to name it. A nullable field invites
+ * `if (state)` and fails silently when somebody forgets; an unhandled variant
+ * fails `tsc`, which is the difference between a rule and a mechanism.
+ */
+export const resourceHealthCleared = z.object({
+    type: z.literal('resource_health_cleared'),
+    robot_id: z.uuid(),
+    kind: z.enum(['camera']),
+    ref: z.string().min(1).max(64),
+    facet: z.enum(['source', 'publish']),
+    cleared_at_ms: z.number().int().nonnegative(),
+});
+export const resourceHealthEvent = z.object({
+    type: z.literal('resource_health'),
+    robot_id: z.uuid(),
+    kind: z.enum(['camera']),
+    ref: z.string().min(1).max(64),
+    /** Which of the two questions this entry answers — see `resourceHealthState.facet`. */
+    facet: z.enum(['source', 'publish']),
+    state: z.enum(RESOURCE_HEALTH_STATES),
+    reason: z.string().max(200).nullable(),
+    changed_at_ms: z.number().int().nonnegative(),
+});
+/**
+ * One line of the developer console's activity panel (spec
+ * `2026-08-20-org-event-stream`).
+ *
+ * **This is an activity log for humans, not a complete feed.** It is throttled
+ * and sampled. `orgEventDropped` still reports a drop on the wire, but since
+ * FL-001 **no Fleetless surface renders it** — the console's gap banner was
+ * removed on request, and nothing replaced it. A reader of this stream
+ * therefore cannot tell a complete window from a sampled one, and this
+ * comment says so rather than implying a notice that exists only in the
+ * protocol. Anything that needs completeness reads the audit log or the
+ * job-run history, both durable, both 90 days.
+ */
+export const ORG_EVENT_SAMPLE_INTERVAL_MS = 1_000;
+/** The backstop above the per-slug cap: a fleet larger than the panel could serve anyway. */
+export const ORG_EVENT_ORG_CEILING_PER_SECOND = 50;
+/** Roughly 25 screens of scrollback. */
+export const ORG_EVENT_BUFFER_SIZE = 200;
+/** An org's buffer is dropped after this long without an event, so memory follows active orgs rather than all of them. */
+export const ORG_EVENT_BUFFER_IDLE_MS = 3_600_000;
+/** A log line, not a payload: a datapoint value is `unknown` and a LaserScan is megabytes. */
+export const ORG_EVENT_DETAIL_MAX_BYTES = 4_096;
+/**
+ * `'alert'` — a transition of a datapoint alert (`ok ⇄ firing`, spec
+ * `2026-08-28-alerts-and-datapoint-modal-design` D2). A firing event carries
+ * the alert's own `severity`; a resolved event is always `info` — resolving
+ * is good news regardless of how bad the firing was.
+ *
+ * `'datapoint'` — since FL-001, **no producer emits this kind**: the
+ * datapoint producer was made a deliberate no-op (Task 5/6, this stream's own
+ * per-slug sampling made it redundant with what the datapoint history route
+ * already serves). The member stays in the enum rather than being removed,
+ * because a reader may still hold a pre-deploy frame of this kind sitting in
+ * a buffer (a reconnect replay, a client that hasn't refreshed) and must be
+ * able to parse it rather than fail closed on an old, valid value. Same shape
+ * as the correction on `ORG_EVENT_SAMPLE_INTERVAL_MS`'s comment just above:
+ * name what the wire no longer does instead of leaving a value the cloud can
+ * never send undocumented.
+ */
+export const orgEventKind = z.enum(['datapoint', 'health', 'job', 'bridge', 'audit', 'alert']);
+/**
+ * Assigned by the **producer**, never derived by the reader. The console's
+ * `errors` filter cuts across all five kinds, and only the source knows whether
+ * an `auth_failed` is bad. A reader guessing from `detail` guesses differently
+ * for each source.
+ */
+export const orgEventSeverity = z.enum(['info', 'warning', 'error']);
+export const orgEvent = z
+    .object({
+    type: z.literal('org_event'),
+    /**
+     * **Per org, per process.** Like `job.seq` and unlike `job_runs.seq`, which
+     * is a postgres `bigserial` and durable. All three say which they are,
+     * because anyone who confuses them will confuse them in both directions.
+     */
+    seq: z.number().int().positive(),
+    at: z.iso.datetime(),
+    kind: orgEventKind,
+    severity: orgEventSeverity,
+    /** `null` for an org-level event — an invitation, a quota change — which belongs to no robot. */
+    robot_id: z.uuid().nullable(),
+    /** What the line is about: a slug, a camera, an actor's email. */
+    subject: z.string().min(1).max(200),
+    /**
+     * Kind-specific, and **capped at `ORG_EVENT_DETAIL_MAX_BYTES`** — above it
+     * the producer substitutes `{ omitted: 'too_large', bytes }`. Truncated,
+     * and saying so.
+     *
+     * Never a pre-formatted line: the reader decides language, number format
+     * and truncation, so changing how a line reads is not a cloud deploy.
+     */
+    detail: z.unknown().nullable(),
+})
+    .strict();
+/** Sent by a developer's socket to start the stream. Answered by `orgEventReplay`, then live `orgEvent`s. */
+export const orgEventSubscribe = z.object({ type: z.literal('org_event_subscribe') }).strict();
+export const orgEventUnsubscribe = z.object({ type: z.literal('org_event_unsubscribe') }).strict();
+/**
+ * What the cloud still remembers, oldest first, sent once before the live
+ * stream starts — so the panel is filled on arrival rather than blank until
+ * something happens. A blank panel is indistinguishable from a broken one.
+ */
+export const orgEventReplay = z
+    .object({
+    type: z.literal('org_event_replay'),
+    events: z.array(orgEvent).max(ORG_EVENT_BUFFER_SIZE),
+    /**
+     * **`false` means three different things, on purpose**: the buffer was
+     * already full, the cloud restarted, or this org's buffer had expired. All
+     * three mean the same thing to a reader — *something is missing above this
+     * line* — and a field separating them would claim a distinction nobody
+     * would act on differently.
+     */
+    complete: z.boolean(),
+})
+    .strict();
+/**
+ * Events this socket will never see. Two causes, reported alike: the cloud
+ * sampled them away, or this socket's send buffer was too far behind. Both mean
+ * *there was more than you are being shown*.
+ */
+export const orgEventDropped = z
+    .object({
+    type: z.literal('org_event_dropped'),
+    /**
+     * **An epoch instant in milliseconds (`Date.now()`), not a duration.**
+     * The moment this socket last reported a drop — or the moment it
+     * subscribed, if this is its first such frame. The window the `dropped`
+     * count covers is `since_ms` to now, so a reader wanting an age
+     * subtracts: `Date.now() - since_ms`. Spelled out because the type
+     * admits both readings and the wrong one is silent: a consumer treating
+     * it as "milliseconds ago" renders a drop that happened seconds ago as
+     * having happened in 1970.
+     */
+    since_ms: z.number().int().nonnegative(),
+    /** Always at least one — a frame reporting nothing lost is noise on a channel built to be quiet. */
+    dropped: z.number().int().positive(),
+})
+    .strict();