@fleetless/contracts 1.0.0 → 1.0.2

package/dist/protocol.d.ts

@@ -1,11 +1,11 @@
+// SPDX-License-Identifier: Apache-2.0
 import { z } from 'zod';
 /**
  * Bridge <-> cloud protocol, version 2.
  *
  * The version is exchanged in the hello handshake; the cloud refuses an
- * incompatible bridge with a clear message (spec §5) — `ws/bridge.ts`'s
- * `protocol_mismatch`, which names both versions and lands on the robot
- * detail page as `last_hello_error`.
+ * incompatible bridge with a clear message: `protocol_mismatch`, which names
+ * both versions and reaches the robot's detail view as `last_hello_error`.
  *
  * **2 (2026-08-21):** `config_applied.errors` entries gained `kind` and `code`
  * beside `message`. The check is `!==`, not a floor, so a bridge that is not
@@ -14,7 +14,7 @@ import { z } from 'zod';
  */
 export declare const PROTOCOL_VERSION = 2;
 /**
- * The bridge socket close code for "this robot no longer exists" (W6a).
+ * The bridge socket close code for "this robot no longer exists".
  *
  * Deliberately distinct from the auth failures: a deleted robot must **stop**,
  * and a token that was valid a second ago is indistinguishable from one that
@@ -26,42 +26,37 @@ export declare const PROTOCOL_VERSION = 2;
 export declare const CLOSE_ROBOT_DELETED = 4004;
 /**
  * How long a command waits for its answer when the caller names no patience
- * of its own (W6b).
+ * of its own.
  *
- * 15 s, which is what both halves already used independently: the cloud's
- * `commandTimeoutMs` and the bridge's `GOAL_ACCEPT_TIMEOUT_S`. That they
- * agreed was a coincidence of two separate decisions, and neither side could
- * be told otherwise for a single call. Naming the number once, here, is what
- * makes it one number rather than two that happen to match.
+ * 15 s, stated once here rather than once in the cloud and once in the bridge.
+ * Two constants that happen to match are not one number: neither side can be
+ * told otherwise for a single call, and when they drift nobody can say whose
+ * deadline a caller hit.
  *
- * A caller who knows their robot's work takes longer says so per call. A
- * caller who says nothing gets exactly today's behaviour — which is the point
- * of picking today's number as the default rather than a nicer one.
+ * A caller who knows their robot's work takes longer says so per call.
  */
 export declare const DEFAULT_PATIENCE_MS = 15000;
 /**
  * The longest patience a caller may ask for.
  *
- * A waiting REST request is a held-open connection, and there is **no rate
- * limiting** on this platform until W8 — so an unbounded `patience_ms` is an
- * unauthenticated way to pin the cloud's sockets open. Two minutes is long
- * enough for the robot work anybody has described (a planner, a docking
+ * A waiting REST request is a held-open connection, so an unbounded
+ * `patience_ms` is a way to pin the cloud's sockets open. Two minutes is long
+ * enough for the robot work this API is meant for (a planner, a docking
  * manoeuvre, an arm trajectory) and short enough that a thousand of them is
  * still a bounded amount of cloud.
  *
- * Raising it is a W8 conversation, after rate limiting exists — not a
- * one-line change here.
+ * Raising it is a conversation about rate limiting, not a one-line change
+ * here.
  */
 export declare const MAX_PATIENCE_MS = 120000;
 /**
  * The shortest patience a caller may ask for.
  *
- * A floor exists because **impatience reaches the robot**. Measured in W6b's
- * review: `patience_ms: 1` on an action makes the bridge report `goal_timeout`
- * and then issue a *corrective cancel* against a goal the action server
- * accepts a moment later — so a caller who asks for an unreachable deadline
- * does not merely get an error, they cause a cancellation on the machine.
- * Repeatable, and on a platform with no rate limiting until W8.
+ * A floor exists because **impatience reaches the robot**. A `patience_ms` of
+ * 1 on an action makes the bridge report `goal_timeout` and then issue a
+ * *corrective cancel* against a goal the action server accepts a moment later
+ * — so a caller who asks for an unreachable deadline does not merely get an
+ * error, they cause a cancellation on the machine.
  *
  * One second, because it has to be longer than a goal-acceptance round trip on
  * a healthy robot and shorter than any wait a human would call patient. It is
@@ -73,7 +68,7 @@ export declare const MIN_PATIENCE_MS = 1000;
 /** Re-exported so consumers keep importing wire names from one place. */
 export { slug } from './common.js';
 /**
- * One job the bridge still has, as reported in the handshake (W6b).
+ * One job the bridge still has, as reported in the handshake.
  *
  * It carries the **slug and the state**, not only the id, because the cloud's
  * reconciliation needs both and had neither. Reading `active_job_ids` as bare
@@ -134,7 +129,7 @@ export declare const cloudHelloError: z.ZodObject<{
 export type CloudHelloError = z.infer<typeof cloudHelloError>;
 /**
  * One datapoint sample. `timestamp_ms` is the capture time at the bridge —
- * never the receive time — so clients compute age themselves (spec §6.3).
+ * never the receive time — so clients compute age themselves.
  */
 export declare const datapointFrame: z.ZodObject<{
     type: z.ZodLiteral<"datapoint">;
@@ -160,9 +155,9 @@ export declare const bridgePong: z.ZodObject<{
 }, z.core.$strip>;
 export type BridgePong = z.infer<typeof bridgePong>;
 /**
- * The published configuration, cloud → bridge (spec §4.1: the bridge applies
- * the published version). Sent right after `hello_ok` and again on every
- * publish, so a bridge never has to ask.
+ * The published configuration, cloud → bridge — the bridge applies the
+ * published version. Sent right after `hello_ok` and again on every publish,
+ * so a bridge never has to ask.
  *
  * `version: 0` with an empty document means *nothing published yet* — a fresh
  * robot, not an error.
@@ -391,7 +386,7 @@ export declare const bridgeConfigApplied: z.ZodObject<{
 }, z.core.$strip>;
 export type BridgeConfigApplied = z.infer<typeof bridgeConfigApplied>;
 /**
- * Commands, cloud → bridge (spec §6.1, §11.3). The **cloud** mints the
+ * Commands, cloud → bridge. The **cloud** mints the
  * `job_id` before the bridge is asked to do anything, so a job exists —
  * and can be reported `lost` — even if the answer never comes back.
  */
@@ -404,13 +399,13 @@ export declare const cloudInvoke: z.ZodObject<{
 }, z.core.$strip>;
 export type CloudInvoke = z.infer<typeof cloudInvoke>;
 /**
- * Cancel — the bridge must issue a real ROS goal cancel (§11.3).
+ * Cancel — the bridge must issue a real ROS goal cancel.
  *
  * `slug` stays, and stays required: it is how the bridge finds the tracker,
  * and it is what a cancel with no id means.
  *
- * `job_id` is what W6b adds, and what makes a cancel say *which* job. Without
- * it a cancel arriving a moment after one job ended and another began on the
+ * `job_id` is what makes a cancel say *which* job. Without it a cancel
+ * arriving a moment after one job ended and another began on the
  * same slug stops the **new** one — the caller asked to stop something that
  * had already finished and stopped a machine that had just started moving.
  * That is not a race anybody had to lose: the caller knew the id, and the
@@ -437,7 +432,7 @@ export declare const cloudPublish: z.ZodObject<{
 export type CloudPublish = z.infer<typeof cloudPublish>;
 /**
  * Progress on a job, bridge → cloud. `timestamp_ms` is capture time, so a
- * burst delivered late after a reconnect is visibly late (§6.3).
+ * burst delivered late after a reconnect is visibly late.
  */
 export declare const bridgeJobUpdate: z.ZodObject<{
     type: z.ZodLiteral<"job_update">;
@@ -462,7 +457,7 @@ export declare const bridgeJobUpdate: z.ZodObject<{
 }, z.core.$strip>;
 export type BridgeJobUpdate = z.infer<typeof bridgeJobUpdate>;
 /**
- * Jobs the bridge can no longer account for **while connected** (§6.1) — a
+ * Jobs the bridge can no longer account for **while connected** — a
  * tracker dropped, an action server that vanished mid-goal, anything where
  * the honest answer is "I lost this" rather than a state.
  *
@@ -542,8 +537,8 @@ export declare const bridgeTypeDefinitions: z.ZodObject<{
 }, z.core.$strip>;
 export type BridgeTypeDefinitions = z.infer<typeof bridgeTypeDefinitions>;
 /**
- * The built-in `bridge_state` datapoint every robot has (spec §4.3):
- * connection status plus latency, the basis for offline-aware client UIs.
+ * The built-in `bridge_state` datapoint every robot has: connection status
+ * plus latency, the basis for offline-aware client UIs.
  */
 export declare const bridgeState: z.ZodObject<{
     online: z.ZodBoolean;
@@ -551,8 +546,7 @@ export declare const bridgeState: z.ZodObject<{
 }, z.core.$strip>;
 export type BridgeState = z.infer<typeof bridgeState>;
 /**
- * The built-in `bridge_pressure` datapoint (spec §4.3, the pressure-telemetry
- * design's "The decision that shapes everything"): the bridge's own
+ * The built-in `bridge_pressure` datapoint: the bridge's own
  * bandwidth-shaping state, sent on the same reserved-slug path as
  * `bridge_state` so history, realtime, REST and MCP exposure fall out of the
  * ordinary datapoint machinery for free.
@@ -621,13 +615,11 @@ export declare const PRESSURE_SLUG: "bridge_pressure";
  * Binary rather than base64 in a text frame, because base64 costs a third of
  * the robot's upstream for nothing. Self-contained rather than a JSON frame
  * followed by a binary one, because that pairing would depend on frame
- * ordering — and W4 established, at some cost, that ordering across a socket
- * is not something to lean on.
+ * ordering, and ordering across a socket is not something to lean on.
  *
- * `timestamp_ms` is the bridge's **capture** time (§6.3), which is what lets
- * every consumer state a snapshot's true age. A picture that lies about when
- * it was taken is this wave's version of a job that reads "running" when
- * nobody knows.
+ * `timestamp_ms` is the bridge's **capture** time, which is what lets every
+ * consumer state a snapshot's true age. A picture that lies about when it was
+ * taken is as bad as a job that reads "running" when nobody knows.
  */
 /**
  * The largest a snapshot frame — header and image bytes together — may be on
@@ -643,15 +635,13 @@ export declare const PRESSURE_SLUG: "bridge_pressure";
  * connection with 1009 — taking datapoints, jobs, commands and configuration
  * down with it. The bridge would then reconnect, receive the same
  * configuration, capture the same frame and be closed again: a robot that
- * will not stay online, from a configuration the platform accepted. Measured
- * during the W5 review, a 4K JPEG of real camera content lands around
- * 2.2 MiB and 1080p on a noisy scene within 40% of this number, so the margin
- * is thinner than it looks.
+ * will not stay online, from a configuration the platform accepted. The margin
+ * is thinner than it looks — a 4K JPEG of real camera content lands around
+ * 2.2 MiB, and 1080p on a noisy scene comes within half of this number.
  *
- * **The bridge must degrade rather than exceed it** — lower JPEG quality,
- * then downscale, and if it still does not fit, skip the frame and say so.
- * A missing snapshot is a gap, and this wave already established that a gap
- * is an honest answer; a closed socket is not.
+ * **The bridge must degrade rather than exceed it** — lower JPEG quality, then
+ * downscale, and if it still does not fit, skip the frame and say so. A missing
+ * snapshot is a gap, and a gap is an honest answer; a closed socket is not.
  */
 export declare const SNAPSHOT_MAX_BYTES = 1572864;
 export declare const snapshotHeader: z.ZodObject<{
@@ -667,7 +657,7 @@ export type SnapshotHeader = z.infer<typeof snapshotHeader>;
  * Cloud → bridge: start publishing this camera live.
  *
  * The **cloud** mints the room and the publisher token, for the same reason
- * it mints a `job_id` before asking anything (§6.1): the side that owns the
+ * it mints a `job_id` before asking anything: the side that owns the
  * refcount must own the identity of the stream, or a robot could end up
  * publishing into a room nobody is watching.
  */
@@ -680,14 +670,13 @@ export declare const cloudCameraStart: z.ZodObject<{
     request_id: z.ZodString;
 }, z.core.$strip>;
 export type CloudCameraStart = z.infer<typeof cloudCameraStart>;
-/** Cloud → bridge: the last viewer left; stop publishing (§10 refcount). */
+/** Cloud → bridge: the last viewer left; stop publishing. */
 /**
- * Assets (spec §4.6, W7): the bridge **reports availability and transfers
- * nothing** until asked.
+ * Assets: the bridge **reports availability and transfers nothing** until
+ * asked.
  *
- * **The bytes never travel on this socket.** `server.ts` caps a frame at
- * 2 MiB, a single mesh exceeds that routinely, and raising the cap is already
- * tied to W8's rate limiting in the deferral register because it amplifies an
+ * **The bytes never travel on this socket.** A frame is capped at 2 MiB and a
+ * single mesh exceeds that routinely; raising the cap amplifies an
  * unauthenticated path. So the socket carries the *conversation* — what exists,
  * transfer this, here is how far I got — and the bytes go over HTTP with the
  * robot's own credential.
@@ -703,7 +692,7 @@ export declare const bridgeAssetsAvailable: z.ZodObject<{
 }, z.core.$strip>;
 export type BridgeAssetsAvailable = z.infer<typeof bridgeAssetsAvailable>;
 /**
- * The explicit request §4.6 requires — nothing moves without it.
+ * The explicit request that starts a transfer — nothing moves without it.
  *
  * The upload credential is minted per sync and travels here rather than being
  * derived from the robot token: it is scoped to one robot's assets and one