@fleetless/contracts 1.2.0 → 2.0.0

package/dist/protocol.d.ts

@@ -1,18 +1,67 @@
 // SPDX-License-Identifier: Apache-2.0
 import { z } from 'zod';
 /**
- * Bridge <-> cloud protocol, version 2.
+ * Bridge <-> cloud protocol, version 3.
  *
- * The version is exchanged in the hello handshake; the cloud refuses an
- * incompatible bridge: `protocol_mismatch`, which names both versions and
- * reaches the robot's detail view as `last_hello_error`.
+ * The version is exchanged in the hello handshake. Since 2026-09 the cloud
+ * serves a **window** of versions, not one: every entry of
+ * `PROTOCOL_VERSIONS` whose sunset has not passed. A version is deprecated
+ * by the cloud release that supersedes it and sunset `PROTOCOL_SUNSET_DAYS`
+ * later. Outside the window the cloud refuses with `protocol_mismatch`,
+ * which names the window and reaches the robot's detail view as
+ * `last_hello_error`.
+ *
+ * **3 (2026-09-22):** the ping carries `latency_ms` and `lag_ms`, the bridge
+ * sends `link_mode`, `bridge_state` gains `low_bandwidth`, and the
+ * `bridge_pressure` datapoint is gone. A protocol-2 bridge is served until
+ * its sunset, and the cloud's protocol-2 adapter owes it two translations on
+ * the way in: it drops its pressure datapoints, and it rewrites an
+ * `asset_progress` failure of kind `too_large` — a kind protocol 3 no longer
+ * has — to `refused` with `details: null`, because a 2.0.0 `bridgeAssetProgress`
+ * refuses the frame outright otherwise.
  *
  * **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
- * exactly this version is refused entirely. That is deliberate: a cloud and a
- * bridge that disagree about the wire should not pretend otherwise.
+ * beside `message`.
+ */
+export declare const PROTOCOL_VERSION = 3;
+/** Days between a version's deprecation and its sunset. */
+export declare const PROTOCOL_SUNSET_DAYS = 90;
+export interface ProtocolVersionEntry {
+    version: number;
+    /** The first bridge package version that speaks this protocol. */
+    bridge_from: string;
+    /** ISO date of the cloud release that superseded it; null while current. */
+    deprecated_at: string | null;
+}
+/**
+ * Every protocol version the cloud has served, oldest first. A test keeps
+ * exactly one entry current and equal to `PROTOCOL_VERSION`; `test/changelog.test.ts`
+ * requires the CHANGELOG's current section to name the newest `bridge_from`
+ * and the previous entry's `sunsetOf(...)` date, and `scripts/verify-version-tag.mjs`
+ * requires a dated heading for the tag being released.
  */
-export declare const PROTOCOL_VERSION = 2;
+export declare const PROTOCOL_VERSIONS: readonly ProtocolVersionEntry[];
+/** The newest bridge package. The cloud mails organisations still below it. */
+export declare const LATEST_BRIDGE_VERSION = "4.0.0";
+export interface ProtocolStatus {
+    status: 'current' | 'deprecated' | 'unsupported';
+    /** ISO date, or null for a current or unknown version. */
+    sunset_at: string | null;
+}
+export declare function sunsetOf(entry: ProtocolVersionEntry): string | null;
+/**
+ * The window rule itself: `protocolStatus` and `minimumProtocolVersion` are
+ * this function over `PROTOCOL_VERSIONS`, and the cloud calls it directly.
+ *
+ * The table is a parameter because callers pass one with a deprecated entry —
+ * tests, and any caller reasoning about a sunset. The real table has none
+ * until the first bump, so a hard-coded `PROTOCOL_VERSIONS` would leave the
+ * deprecated and unsupported branches unreachable.
+ */
+export declare function statusFromTable(table: readonly ProtocolVersionEntry[], version: number, today: Date): ProtocolStatus;
+export declare function protocolStatus(version: number, today?: Date): ProtocolStatus;
+/** The lowest version still inside its window today. */
+export declare function minimumProtocolVersion(today?: Date): number;
 /**
  * The bridge socket close code for "this robot no longer exists".
  *
@@ -24,6 +73,20 @@ export declare const PROTOCOL_VERSION = 2;
  * more informative than "connection closed".
  */
 export declare const CLOSE_ROBOT_DELETED = 4004;
+/**
+ * The bridge socket close code for "the token you connected with is gone".
+ *
+ * The cloud closes a robot's live socket with this after the robot's token was
+ * rotated. A 4.0.0 bridge reads it the way it reads `invalid_token` — stop,
+ * exit 2 — because the secret it holds is no longer a secret anyone accepts,
+ * and no amount of reconnecting produces the new one. A 3.x bridge does not
+ * know the code, reconnects, and is refused at hello; that ends the same way,
+ * one round trip later.
+ *
+ * Its own code rather than `CLOSE_ROBOT_DELETED`, which would tell an operator
+ * their robot had been deleted when it very much still exists.
+ */
+export declare const CLOSE_TOKEN_ROTATED = 4005;
 /**
  * How long a command waits for its answer when the caller names no patience
  * of its own.
@@ -113,10 +176,26 @@ export declare const bridgeHello: z.ZodObject<{
     }, z.core.$strip>>>;
 }, z.core.$strip>;
 export type BridgeHello = z.infer<typeof bridgeHello>;
-/** Cloud accepts the bridge: the robot is online from here on. */
+/**
+ * Cloud accepts the bridge: the robot is online from here on.
+ *
+ * `protocol` and `bridge` are optional so that a bridge parsing `hello_ok`
+ * strictly still parses one from an older cloud. `status` here is never
+ * `unsupported`: an unsupported version gets `hello_error`, not this frame.
+ */
 export declare const cloudHelloOk: z.ZodObject<{
     type: z.ZodLiteral<"hello_ok">;
     robot_id: z.ZodUUID;
+    protocol: z.ZodOptional<z.ZodObject<{
+        status: z.ZodEnum<{
+            deprecated: "deprecated";
+            current: "current";
+        }>;
+        sunset_at: z.ZodNullable<z.ZodISODate>;
+    }, z.core.$strip>>;
+    bridge: z.ZodOptional<z.ZodObject<{
+        latest_version: z.ZodString;
+    }, z.core.$strip>>;
 }, z.core.$strip>;
 export type CloudHelloOk = z.infer<typeof cloudHelloOk>;
 /** Cloud refuses the bridge (bad token, incompatible protocol, ...). */
@@ -129,22 +208,40 @@ 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.
+ *
+ * Which is exactly why `backfill` has to be on the frame. A replayed sample
+ * carries the capture time it had during the outage, so a cloud that measures
+ * lag from every arriving frame reads a two-hour disconnect as two hours of
+ * lag the moment the bridge reconnects — and reports a healthy link as the
+ * worst one it has ever seen. Only the bridge knows which frames came out of
+ * its buffer, so only the bridge can say.
  */
 export declare const datapointFrame: z.ZodObject<{
     type: z.ZodLiteral<"datapoint">;
     slug: z.ZodString;
     value: z.ZodUnknown;
     timestamp_ms: z.ZodNumber;
+    backfill: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>;
 export type DatapointFrame = z.infer<typeof datapointFrame>;
 /**
  * Latency probe, cloud → bridge. The cloud sends its own clock in `ts_ms`;
  * the bridge echoes it back untouched and the cloud derives the round-trip
  * latency shown as `bridge_state.latency_ms`.
+ *
+ * Sent every `pingIntervalMs`; the bridge answers with `pong`. Since protocol
+ * 3 it also carries what the cloud measured about this link, so the bridge
+ * can decide on its low-bandwidth mode with an end-to-end number: the
+ * round trip of the last pong, and the datapoint lag — the median over the
+ * last five seconds of (receive time − `timestamp_ms`) minus the minimum of
+ * the last ten minutes, which cancels the robot's clock offset. `null` until
+ * the cloud has a sample. A protocol-2 bridge reads only `ts_ms`.
  */
 export declare const cloudPing: z.ZodObject<{
     type: z.ZodLiteral<"ping">;
     ts_ms: z.ZodNumber;
+    latency_ms: z.ZodNullable<z.ZodNumber>;
+    lag_ms: z.ZodNullable<z.ZodNumber>;
 }, z.core.$strip>;
 export type CloudPing = z.infer<typeof cloudPing>;
 /** Immediate bridge answer to a `CloudPing`, `ts_ms` echoed unchanged. */
@@ -153,6 +250,24 @@ export declare const bridgePong: z.ZodObject<{
     ts_ms: z.ZodNumber;
 }, z.core.$strip>;
 export type BridgePong = z.infer<typeof bridgePong>;
+/**
+ * The bridge's low-bandwidth mode changed. Sent on every transition and once
+ * after `hello_ok`, at tier 0 like the pong: the cloud folds it into
+ * `bridge_state.low_bandwidth`, and a frame that waited behind bulk would
+ * describe a state that is already over.
+ */
+export declare const bridgeLinkMode: z.ZodObject<{
+    type: z.ZodLiteral<"link_mode">;
+    low_bandwidth: z.ZodBoolean;
+    reason: z.ZodEnum<{
+        lag: "lag";
+        dwell: "dwell";
+        forced: "forced";
+        recovered: "recovered";
+    }>;
+    at_ms: z.ZodNumber;
+}, z.core.$strip>;
+export type BridgeLinkMode = z.infer<typeof bridgeLinkMode>;
 /**
  * The published configuration, cloud → bridge — the bridge applies the
  * published version. Sent right after `hello_ok` and again on every publish,
@@ -191,6 +306,7 @@ export declare const cloudConfig: z.ZodObject<{
             type: z.ZodString;
             field: z.ZodOptional<z.ZodString>;
             rate_throttle_hz: z.ZodOptional<z.ZodNumber>;
+            low_bandwidth: z.ZodOptional<z.ZodLiteral<"keep">>;
             description: z.ZodOptional<z.ZodString>;
             numeric: z.ZodOptional<z.ZodObject<{
                 scale: z.ZodOptional<z.ZodNumber>;
@@ -357,6 +473,23 @@ export declare const cloudConfig: z.ZodObject<{
             snapshot_interval_seconds: z.ZodNumber;
             description: z.ZodOptional<z.ZodString>;
         }, z.core.$strict>>>;
+        low_bandwidth: z.ZodOptional<z.ZodObject<{
+            mode: z.ZodOptional<z.ZodEnum<{
+                auto: "auto";
+                on: "on";
+                off: "off";
+            }>>;
+            enter_lag_ms: z.ZodOptional<z.ZodNumber>;
+            enter_after_s: z.ZodOptional<z.ZodNumber>;
+            exit_lag_ms: z.ZodOptional<z.ZodNumber>;
+            exit_after_s: z.ZodOptional<z.ZodNumber>;
+            datapoint_max_hz: z.ZodOptional<z.ZodNumber>;
+            camera: z.ZodOptional<z.ZodEnum<{
+                reduce: "reduce";
+                stop: "stop";
+            }>>;
+            camera_bitrate_kbps: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>>;
     }, z.core.$strict>;
 }, z.core.$strip>;
 export type CloudConfig = z.infer<typeof cloudConfig>;
@@ -377,6 +510,7 @@ export declare const bridgeConfigApplied: z.ZodObject<{
             service: "service";
             publisher: "publisher";
             camera: "camera";
+            low_bandwidth: "low_bandwidth";
         }>;
         code: z.ZodString;
         message: z.ZodString;
@@ -538,72 +672,17 @@ export type BridgeTypeDefinitions = z.infer<typeof bridgeTypeDefinitions>;
 /**
  * The built-in `bridge_state` datapoint every robot has: connection status
  * plus latency, the basis for offline-aware client UIs.
+ *
+ * `online` and `latency_ms` are cloud-observed (the socket, the pong);
+ * `low_bandwidth` is bridge-reported through `link_mode` and `false` for a
+ * bridge that never sends one.
  */
 export declare const bridgeState: z.ZodObject<{
     online: z.ZodBoolean;
     latency_ms: z.ZodNullable<z.ZodNumber>;
+    low_bandwidth: z.ZodBoolean;
 }, z.core.$strip>;
 export type BridgeState = z.infer<typeof bridgeState>;
-/**
- * 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.
- */
-export declare const bridgePressure: z.ZodObject<{
-    link: z.ZodObject<{
-        rate_bps: z.ZodNullable<z.ZodNumber>;
-        snapshot_max_bytes: z.ZodNumber;
-    }, z.core.$strip>;
-    tiers: z.ZodObject<{
-        '0': z.ZodOptional<z.ZodObject<{
-            sent: z.ZodNumber;
-            bytes: z.ZodNumber;
-            drops: z.ZodNumber;
-            high_water: z.ZodNumber;
-        }, z.core.$strip>>;
-        '1': z.ZodOptional<z.ZodObject<{
-            sent: z.ZodNumber;
-            bytes: z.ZodNumber;
-            drops: z.ZodNumber;
-            high_water: z.ZodNumber;
-        }, z.core.$strip>>;
-        '2': z.ZodOptional<z.ZodObject<{
-            sent: z.ZodNumber;
-            bytes: z.ZodNumber;
-            drops: z.ZodNumber;
-            high_water: z.ZodNumber;
-        }, z.core.$strip>>;
-        '3': z.ZodOptional<z.ZodObject<{
-            sent: z.ZodNumber;
-            bytes: z.ZodNumber;
-            drops: z.ZodNumber;
-            high_water: z.ZodNumber;
-        }, z.core.$strip>>;
-        '4': z.ZodOptional<z.ZodObject<{
-            sent: z.ZodNumber;
-            bytes: z.ZodNumber;
-            drops: z.ZodNumber;
-            high_water: z.ZodNumber;
-        }, z.core.$strip>>;
-        '5': z.ZodOptional<z.ZodObject<{
-            sent: z.ZodNumber;
-            bytes: z.ZodNumber;
-            drops: z.ZodNumber;
-            high_water: z.ZodNumber;
-        }, z.core.$strip>>;
-    }, z.core.$strict>;
-    video: z.ZodObject<{
-        active_streams: z.ZodNumber;
-        bitrate_sum_kbps: z.ZodNumber;
-        uplink_kbps: z.ZodNullable<z.ZodNumber>;
-        override_kbps: z.ZodNullable<z.ZodNumber>;
-        video_budget_kbps: z.ZodNullable<z.ZodNumber>;
-        reserve_kbps: z.ZodNumber;
-    }, z.core.$strip>;
-}, z.core.$strip>;
-export type BridgePressure = z.infer<typeof bridgePressure>;
-export declare const PRESSURE_SLUG: "bridge_pressure";
 /**
  * The header of a **binary** snapshot frame, bridge → cloud.
  *
@@ -724,10 +803,10 @@ export declare const bridgeAssetProgress: z.ZodObject<{
             unresolvable: "unresolvable";
             upload_failed: "upload_failed";
             refused: "refused";
-            too_large: "too_large";
         }>;
         details: z.ZodOptional<z.ZodNullable<z.ZodObject<{
-            limit_bytes: z.ZodNumber;
+            store_bytes: z.ZodNumber;
+            used_bytes: z.ZodNumber;
             size_bytes: z.ZodNumber;
         }, z.core.$strip>>>;
     }, z.core.$strip>>;

package/dist/protocol.js

@@ -7,18 +7,79 @@ import { rosGraph, typeDefinition } from './introspection.js';
 import { jobState } from './jobs.js';
 import { rosTypeName } from './common.js';
 /**
- * Bridge <-> cloud protocol, version 2.
+ * Bridge <-> cloud protocol, version 3.
  *
- * The version is exchanged in the hello handshake; the cloud refuses an
- * incompatible bridge: `protocol_mismatch`, which names both versions and
- * reaches the robot's detail view as `last_hello_error`.
+ * The version is exchanged in the hello handshake. Since 2026-09 the cloud
+ * serves a **window** of versions, not one: every entry of
+ * `PROTOCOL_VERSIONS` whose sunset has not passed. A version is deprecated
+ * by the cloud release that supersedes it and sunset `PROTOCOL_SUNSET_DAYS`
+ * later. Outside the window the cloud refuses with `protocol_mismatch`,
+ * which names the window and reaches the robot's detail view as
+ * `last_hello_error`.
+ *
+ * **3 (2026-09-22):** the ping carries `latency_ms` and `lag_ms`, the bridge
+ * sends `link_mode`, `bridge_state` gains `low_bandwidth`, and the
+ * `bridge_pressure` datapoint is gone. A protocol-2 bridge is served until
+ * its sunset, and the cloud's protocol-2 adapter owes it two translations on
+ * the way in: it drops its pressure datapoints, and it rewrites an
+ * `asset_progress` failure of kind `too_large` — a kind protocol 3 no longer
+ * has — to `refused` with `details: null`, because a 2.0.0 `bridgeAssetProgress`
+ * refuses the frame outright otherwise.
  *
  * **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
- * exactly this version is refused entirely. That is deliberate: a cloud and a
- * bridge that disagree about the wire should not pretend otherwise.
+ * beside `message`.
+ */
+export const PROTOCOL_VERSION = 3;
+/** Days between a version's deprecation and its sunset. */
+export const PROTOCOL_SUNSET_DAYS = 90;
+/**
+ * Every protocol version the cloud has served, oldest first. A test keeps
+ * exactly one entry current and equal to `PROTOCOL_VERSION`; `test/changelog.test.ts`
+ * requires the CHANGELOG's current section to name the newest `bridge_from`
+ * and the previous entry's `sunsetOf(...)` date, and `scripts/verify-version-tag.mjs`
+ * requires a dated heading for the tag being released.
+ */
+export const PROTOCOL_VERSIONS = [
+    { version: 2, bridge_from: '3.0.0', deprecated_at: '2026-09-22' },
+    { version: 3, bridge_from: '4.0.0', deprecated_at: null },
+];
+/** The newest bridge package. The cloud mails organisations still below it. */
+export const LATEST_BRIDGE_VERSION = '4.0.0';
+const DAY_MS = 24 * 60 * 60 * 1000;
+function isoDate(date) {
+    return date.toISOString().slice(0, 10);
+}
+export function sunsetOf(entry) {
+    if (entry.deprecated_at === null)
+        return null;
+    return isoDate(new Date(Date.parse(entry.deprecated_at + 'T00:00:00Z') + PROTOCOL_SUNSET_DAYS * DAY_MS));
+}
+/**
+ * The window rule itself: `protocolStatus` and `minimumProtocolVersion` are
+ * this function over `PROTOCOL_VERSIONS`, and the cloud calls it directly.
+ *
+ * The table is a parameter because callers pass one with a deprecated entry —
+ * tests, and any caller reasoning about a sunset. The real table has none
+ * until the first bump, so a hard-coded `PROTOCOL_VERSIONS` would leave the
+ * deprecated and unsupported branches unreachable.
  */
-export const PROTOCOL_VERSION = 2;
+export function statusFromTable(table, version, today) {
+    const entry = table.find((candidate) => candidate.version === version);
+    if (!entry)
+        return { status: 'unsupported', sunset_at: null };
+    const sunset = sunsetOf(entry);
+    if (sunset === null)
+        return { status: 'current', sunset_at: null };
+    return { status: isoDate(today) < sunset ? 'deprecated' : 'unsupported', sunset_at: sunset };
+}
+export function protocolStatus(version, today = new Date()) {
+    return statusFromTable(PROTOCOL_VERSIONS, version, today);
+}
+/** The lowest version still inside its window today. */
+export function minimumProtocolVersion(today = new Date()) {
+    const alive = PROTOCOL_VERSIONS.filter((entry) => statusFromTable(PROTOCOL_VERSIONS, entry.version, today).status !== 'unsupported');
+    return alive[0]?.version ?? PROTOCOL_VERSION;
+}
 /**
  * The bridge socket close code for "this robot no longer exists".
  *
@@ -30,6 +91,20 @@ export const PROTOCOL_VERSION = 2;
  * more informative than "connection closed".
  */
 export const CLOSE_ROBOT_DELETED = 4004;
+/**
+ * The bridge socket close code for "the token you connected with is gone".
+ *
+ * The cloud closes a robot's live socket with this after the robot's token was
+ * rotated. A 4.0.0 bridge reads it the way it reads `invalid_token` — stop,
+ * exit 2 — because the secret it holds is no longer a secret anyone accepts,
+ * and no amount of reconnecting produces the new one. A 3.x bridge does not
+ * know the code, reconnects, and is refused at hello; that ends the same way,
+ * one round trip later.
+ *
+ * Its own code rather than `CLOSE_ROBOT_DELETED`, which would tell an operator
+ * their robot had been deleted when it very much still exists.
+ */
+export const CLOSE_TOKEN_ROTATED = 4005;
 /**
  * How long a command waits for its answer when the caller names no patience
  * of its own.
@@ -120,10 +195,35 @@ export const bridgeHello = z.object({
      */
     active_jobs: z.array(activeJob).max(500).default([]),
 });
-/** Cloud accepts the bridge: the robot is online from here on. */
+/**
+ * Cloud accepts the bridge: the robot is online from here on.
+ *
+ * `protocol` and `bridge` are optional so that a bridge parsing `hello_ok`
+ * strictly still parses one from an older cloud. `status` here is never
+ * `unsupported`: an unsupported version gets `hello_error`, not this frame.
+ */
 export const cloudHelloOk = z.object({
     type: z.literal('hello_ok'),
     robot_id: z.uuid(),
+    protocol: z
+        .object({
+        status: z.enum(['current', 'deprecated']).meta({
+            description: '`current` or `deprecated` — never `unsupported`, which is a `hello_error`.',
+        }),
+        sunset_at: z.iso.date().nullable().meta({
+            description: 'ISO date a deprecated version stops being served; `null` when current.',
+        }),
+    })
+        .optional()
+        .meta({ description: "The cloud's verdict on the announced protocol version; absent from an older cloud." }),
+    bridge: z
+        .object({
+        latest_version: z.string().min(1).meta({
+            description: "The newest published fleetless-bridge package version, for the bridge's own upgrade hint.",
+        }),
+    })
+        .optional()
+        .meta({ description: 'What the cloud knows about bridge packages; absent from an older cloud.' }),
 });
 /** Cloud refuses the bridge (bad token, incompatible protocol, ...). */
 export const cloudHelloError = z.object({
@@ -134,27 +234,57 @@ export const cloudHelloError = z.object({
 /**
  * One datapoint sample. `timestamp_ms` is the capture time at the bridge —
  * never the receive time — so clients compute age themselves.
+ *
+ * Which is exactly why `backfill` has to be on the frame. A replayed sample
+ * carries the capture time it had during the outage, so a cloud that measures
+ * lag from every arriving frame reads a two-hour disconnect as two hours of
+ * lag the moment the bridge reconnects — and reports a healthy link as the
+ * worst one it has ever seen. Only the bridge knows which frames came out of
+ * its buffer, so only the bridge can say.
  */
 export const datapointFrame = z.object({
     type: z.literal('datapoint'),
     slug,
     value: z.unknown(),
     timestamp_ms: z.number().int().nonnegative(),
+    backfill: z.boolean().optional().meta({ description: 'true when the sample was captured while the bridge was disconnected and is being replayed after the reconnect. The cloud keeps such a sample out of its lag measure; absent means live.' }),
 });
 /**
  * Latency probe, cloud → bridge. The cloud sends its own clock in `ts_ms`;
  * the bridge echoes it back untouched and the cloud derives the round-trip
  * latency shown as `bridge_state.latency_ms`.
+ *
+ * Sent every `pingIntervalMs`; the bridge answers with `pong`. Since protocol
+ * 3 it also carries what the cloud measured about this link, so the bridge
+ * can decide on its low-bandwidth mode with an end-to-end number: the
+ * round trip of the last pong, and the datapoint lag — the median over the
+ * last five seconds of (receive time − `timestamp_ms`) minus the minimum of
+ * the last ten minutes, which cancels the robot's clock offset. `null` until
+ * the cloud has a sample. A protocol-2 bridge reads only `ts_ms`.
  */
 export const cloudPing = z.object({
     type: z.literal('ping'),
     ts_ms: z.number().int().nonnegative(),
+    latency_ms: z.number().nonnegative().nullable().meta({ description: 'Round trip of the last pong in milliseconds; null before the first.' }),
+    lag_ms: z.number().nonnegative().nullable().meta({ description: 'Datapoint lag over the link: median of the last five seconds minus the ten-minute minimum, in milliseconds; null until a sample exists, and null again whenever no live sample arrived in the last five seconds, because a stale median would be a lie.' }),
 });
 /** Immediate bridge answer to a `CloudPing`, `ts_ms` echoed unchanged. */
 export const bridgePong = z.object({
     type: z.literal('pong'),
     ts_ms: z.number().int().nonnegative(),
 });
+/**
+ * The bridge's low-bandwidth mode changed. Sent on every transition and once
+ * after `hello_ok`, at tier 0 like the pong: the cloud folds it into
+ * `bridge_state.low_bandwidth`, and a frame that waited behind bulk would
+ * describe a state that is already over.
+ */
+export const bridgeLinkMode = z.object({
+    type: z.literal('link_mode'),
+    low_bandwidth: z.boolean().meta({ description: 'Whether the mode is active after this transition.' }),
+    reason: z.enum(['lag', 'dwell', 'forced', 'recovered']).meta({ description: '`lag`: the cloud-measured lag crossed the threshold; `dwell`: the bridge-measured queue dwell did; `forced`: `mode: on` or `off`; `recovered`: both measures stayed at or below the exit threshold.' }),
+    at_ms: z.number().int().nonnegative().meta({ description: 'Bridge time of the transition, epoch milliseconds.' }),
+});
 /**
  * The published configuration, cloud → bridge — the bridge applies the
  * published version. Sent right after `hello_ok` and again on every publish,
@@ -350,89 +480,16 @@ export const bridgeTypeDefinitions = z.object({
 /**
  * The built-in `bridge_state` datapoint every robot has: connection status
  * plus latency, the basis for offline-aware client UIs.
+ *
+ * `online` and `latency_ms` are cloud-observed (the socket, the pong);
+ * `low_bandwidth` is bridge-reported through `link_mode` and `false` for a
+ * bridge that never sends one.
  */
 export const bridgeState = z.object({
     online: z.boolean(),
     latency_ms: z.number().nonnegative().nullable(),
+    low_bandwidth: z.boolean().meta({ description: 'Whether the bridge is in its low-bandwidth mode: datapoints capped, cameras reduced or stopped. Bridge-reported.' }),
 });
-/** One tier's counters, `tiers` below carries six of these under string keys. */
-const bridgePressureTier = z.object({
-    sent: z.number().int().nonnegative(),
-    bytes: z.number().int().nonnegative(),
-    drops: z.number().int().nonnegative(),
-    high_water: z.number().int().nonnegative(),
-});
-/**
- * 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.
- */
-export const bridgePressure = z.object({
-    link: z.object({
-        /** bytes/s the socket demonstrably drains, from sends >= 64 KiB
-         *  only; null until the first large send of the session. */
-        rate_bps: z.number().nonnegative().nullable(),
-        /**
-         * the byte target snapshots are currently encoded to fit.
-         *
-         * `.nonnegative()`, not `.positive()`: the target is derived from
-         * `rate_bps`, and a link measured below 0.5 B/s floors to 0 here. A
-         * schema that rejects 0 does not prevent that link — it only makes the
-         * frame reporting it unparseable, and a console that cannot parse a
-         * pressure frame shows "no feed", i.e. reports a struggling robot as an
-         * *old* one. Zero is a legitimate reading and says something true.
-         */
-        snapshot_max_bytes: z.number().int().nonnegative(),
-    }),
-    /**
-     * String keys "0".."5" because JSON has no integer keys. Counters are
-     * cumulative per session and reset on reconnect; clients window by
-     * differencing two samples.
-     *
-     * **What this schema does not decide:** it does not guarantee all six
-     * keys are present (`z.record` over the six literals is exhaustive in
-     * zod 4 — tested here, it required every key and rejected none, the
-     * opposite of what a partial sample needs — so this is a
-     * `.strictObject().partial()` over the same six literal keys instead, a
-     * deliberate deviation from the originally sketched `z.record` shape with
-     * the same runtime behaviour). A missing tier key reads as zeros; the
-     * schema names what it cannot decide rather than implying a completeness
-     * it cannot check.
-     */
-    tiers: z
-        .strictObject({
-        '0': bridgePressureTier,
-        '1': bridgePressureTier,
-        '2': bridgePressureTier,
-        '3': bridgePressureTier,
-        '4': bridgePressureTier,
-        '5': bridgePressureTier,
-    })
-        .partial(),
-    video: z.object({
-        active_streams: z.number().int().nonnegative(),
-        bitrate_sum_kbps: z.number().int().nonnegative(),
-        /**
-         * The uplink budget the bridge was configured with
-         * (`FLEETLESS_UPLINK_KBPS`), or `null` when none was set.
-         *
-         * `.nonnegative()`, not `.positive()`: `FLEETLESS_UPLINK_KBPS=0` is a
-         * documented setting meaning "no video budget at all", and the bridge
-         * emits that 0 verbatim. `.positive()` made every frame from such a
-         * robot fail the console's `safeParse`, which renders an unparseable
-         * frame as "no pressure feed" — so the one robot that had *deliberately*
-         * turned video off was the one diagnosed as running a bridge too old to
-         * report pressure. A value the producer legitimately sends must parse;
-         * `null` is the only "not set" this field has.
-         */
-        uplink_kbps: z.number().int().nonnegative().nullable(),
-        override_kbps: z.number().int().nonnegative().nullable(),
-        video_budget_kbps: z.number().int().nonnegative().nullable(),
-        reserve_kbps: z.number().int().nonnegative(),
-    }),
-});
-export const PRESSURE_SLUG = 'bridge_pressure';
 /* ------------------------------------------------------------------------
  * Cameras.
  */