@fleetless/contracts 1.2.0 → 2.0.0

package/artifacts/openapi.json

@@ -5022,6 +5022,112 @@
         }
       }
     },
+    "/api/robots/{id}/token/rotate": {
+      "post": {
+        "operationId": "post_api_robots_id_token_rotate",
+        "summary": "Mints a new bridge token for the robot and invalidates the old one.",
+        "tags": [
+          "robots"
+        ],
+        "security": [
+          {
+            "developerSession": []
+          }
+        ],
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "description": "The robot's uuid, as returned by `POST /api/robots` or listed by `GET /api/robots`.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "201": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/robot-token-rotate-response"
+                }
+              }
+            }
+          },
+          "default": {
+            "description": "An error envelope. Codes this route is known to answer: `unauthorized`, `token_expired`, `token_revoked`, `tier_required`, `invalid_uuid`, `not_found`.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/api-error"
+                }
+              }
+            }
+          }
+        },
+        "description": "Owner tier, behind the org-scoped lookup, so a developer-tier admin sees the `404` a stranger would for a robot outside their org rather than a tier refusal that confirms the id exists. `token` is the only moment the new secret exists outside the caller's hands — the cloud stores a hash — so a caller who loses it rotates again. Audited as `robot.token_rotated`, with no `details`: the one interesting value here is the token. \n\n**It stops the bridge that is connected right now.** The old secret is gone the instant the hash is replaced, so the cloud closes that socket with `CLOSE_TOKEN_ROTATED` rather than leaving a bridge speaking on a credential nothing would accept again. A bridge that does not know the code reconnects and is refused at hello as `invalid_token`, which is the honest answer and ends the same way. **The robot is offline until somebody puts the new token on it** — this is a deliberate interruption, not a background rekey, and a fleet cannot be rotated without a visit to each robot."
+      }
+    },
+    "/api/robots/{id}/urdf/joint-state": {
+      "put": {
+        "operationId": "put_api_robots_id_urdf_joint_state",
+        "summary": "Chooses the datapoint whose joint positions move the robot's URDF, or clears it.",
+        "tags": [
+          "robots"
+        ],
+        "security": [
+          {
+            "developerSession": []
+          }
+        ],
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "description": "The robot's uuid, as returned by `POST /api/robots` or listed by `GET /api/robots`.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/joint-state-put-response"
+                }
+              }
+            }
+          },
+          "default": {
+            "description": "An error envelope. Codes this route is known to answer: `unauthorized`, `token_expired`, `token_revoked`, `invalid_uuid`, `not_found`, `validation_error`.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/api-error"
+                }
+              }
+            }
+          }
+        },
+        "description": "**What qualifies**: a datapoint of the **published** configuration whose ROS type is `sensor_msgs/msg/JointState` and which carries no `field` — the whole message, because positions and names arrive together and a single extracted field is half of a pose. Anything else is a `validation_error` naming that rule rather than a stored mapping that renders a battery reading as a robot. `{ \"slug\": null }` clears it, which is why the field is required and nullable rather than optional. \n\n**The mapping cannot outlive what it points at.** Every successful publish re-checks it against the new document and clears it when it no longer qualifies, recording `robot.joint_state_cleared` with the version that did it; a slug rename rewrites it like every other reference the editor already rewrites; deleting the robot takes it along. Every write through this route — a slug or `null` — is on the record too, as `robot.joint_state_set` with the actor and the slug, so a clear a person made is never mistaken for one a publish made. The stored value reads back on `GET /api/robots/:id/assets` as `joint_state_slug`, so a renderer fetches the URDF, the meshes and the mapping from one place.",
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/joint-state-put-request"
+              }
+            }
+          }
+        }
+      }
+    },
     "/api/robots/{id}": {
       "get": {
         "operationId": "get_api_robots_id",
@@ -7282,6 +7388,58 @@
           }
         },
         "description": "Needs the `assets` capability, refused as `403 capability_required` rather than a bare `forbidden`: the code says a capability is missing and the message says which, so a developer who switched the wrong toggle on is told what to switch. The capability is checked before existence, so a denied robot and an absent one read alike to a caller with no right to tell them apart. `urdf` reports whether a URDF is present and which of its mesh references have no stored asset."
+      },
+      "delete": {
+        "operationId": "delete_api_robots_id_assets",
+        "summary": "Empties a robot's asset store: every URDF, mesh and texture, gone at once.",
+        "tags": [
+          "assets"
+        ],
+        "security": [
+          {
+            "developerSession": []
+          },
+          {
+            "clientToken": []
+          },
+          {
+            "serverKey": []
+          }
+        ],
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "description": "The robot's uuid, as returned by `POST /api/robots` or listed by `GET /api/robots`.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/assets-clear-response"
+                }
+              }
+            }
+          },
+          "default": {
+            "description": "An error envelope. Codes this route is known to answer: `unauthorized`, `token_expired`, `token_revoked`, `forbidden`, `tier_required`, `invalid_uuid`, `not_found`, `busy`.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/api-error"
+                }
+              }
+            }
+          }
+        },
+        "description": "The store's escape hatch: a full store is never a dead end, and this is the blunt third of the three answers to it — the URDF upload is exempt from the gate, reconcile after a sync already frees what the new URDF stopped referencing, and this route lets an Owner clear the robot outright. Owner tier, unconditionally, like starting a sync. Removes every asset of the robot and resets its store to `0`; the next sync fills it again. It does not touch the bridge's availability report — `urdf_available` still answers from the connected robot, unrelated to what this cloud happens to have stored. A clear while a sync is running is `409 busy` naming that sync's details, the same refusal starting a second sync gets, because deleting under a running upload would leave the store counter wrong."
       }
     },
     "/api/robots/{id}/assets/{assetId}": {
@@ -9244,10 +9402,9 @@
                   "enum": [
                     "urdf",
                     "mesh",
-                    "texture",
-                    "other"
+                    "texture"
                   ],
-                  "description": "What the file is: the `urdf` itself, a `mesh` it references, a `texture` a mesh or the URDF paints with, or `other`. A renderer decides from this alone, before fetching anything, what to pre-fetch."
+                  "description": "What the file is: the `urdf` itself, a `mesh` it references, or a `texture` a mesh or the URDF paints with. A renderer decides from this alone, before fetching anything, what to pre-fetch."
                 },
                 "name": {
                   "type": "string",
@@ -9348,32 +9505,38 @@
                           "enum": [
                             "unresolvable",
                             "upload_failed",
-                            "refused",
-                            "too_large"
+                            "refused"
                           ],
-                          "description": "Why it failed. `unresolvable` means the reference names nothing the producer can find or may read, and is **permanent** — the only kind reconciliation may treat as gone. `upload_failed` means the bytes exist and the transfer did not succeed, `refused` means it was never attempted because a producer-side ceiling was hit, and `too_large` means it exceeds the upload limit and carries both numbers in `details`."
+                          "description": "Why it failed. `unresolvable` means the reference names nothing the producer can find or may read, and is **permanent** — the only kind reconciliation may treat as gone. `upload_failed` means the bytes exist and the transfer did not succeed, and `refused` means it was never attempted, either because the robot's asset store had no room — then `details` carries the three numbers — or because a producer-side ceiling was hit."
                         },
                         "details": {
-                          "description": "The two numbers behind a `too_large` failure, and absent for every other kind — a forced `null` on every `unresolvable` entry buys nothing. The pairing is enforced, not merely described.",
+                          "description": "The three numbers behind a `refused` entry the robot's store had no room for, and absent for every other kind — a forced `null` on every `unresolvable` entry buys nothing. A `refused` entry may also carry no details: the producer's own ceiling is the other half of that kind, and no store number describes it.",
                           "anyOf": [
                             {
                               "type": "object",
                               "properties": {
-                                "limit_bytes": {
+                                "store_bytes": {
                                   "type": "integer",
                                   "exclusiveMinimum": 0,
                                   "maximum": 9007199254740991,
-                                  "description": "The upload ceiling, in bytes."
+                                  "description": "The robot's store, in bytes."
+                                },
+                                "used_bytes": {
+                                  "type": "integer",
+                                  "minimum": 0,
+                                  "maximum": 9007199254740991,
+                                  "description": "Bytes the robot's assets occupy before this upload."
                                 },
                                 "size_bytes": {
                                   "type": "integer",
                                   "exclusiveMinimum": 0,
                                   "maximum": 9007199254740991,
-                                  "description": "How large the refused file is, in bytes. With `limit_bytes` beside it a developer can tell whether to shrink the mesh or raise the limit; \"too large\" alone answers neither."
+                                  "description": "The refused upload, in bytes."
                                 }
                               },
                               "required": [
-                                "limit_bytes",
+                                "store_bytes",
+                                "used_bytes",
                                 "size_bytes"
                               ],
                               "additionalProperties": false
@@ -9404,6 +9567,25 @@
                     ],
                     "description": "Why the sync ended as it did, when that is not a per-reference fact. `null` when `failed` already says everything there is to say."
                   },
+                  "stored": {
+                    "anyOf": [
+                      {
+                        "type": "integer",
+                        "minimum": 0,
+                        "maximum": 9007199254740991
+                      },
+                      {
+                        "type": "null"
+                      }
+                    ],
+                    "description": "How many of the announced files the cloud's store actually holds. Counted once, after the robot reports the sync done, and `null` until then — nobody has looked yet. Read it against `announced`: `state` is what the robot reported, this is what arrived."
+                  },
+                  "announced": {
+                    "type": "integer",
+                    "minimum": 0,
+                    "maximum": 9007199254740991,
+                    "description": "How many files the robot announced for this sync — the URDF, if it has one, plus every mesh URI its description references. `0` when the robot announced nothing, and also `0` until it has answered at all: read it beside `stored`, which stays `null` until the terminal frame."
+                  },
                   "started_at": {
                     "type": "string",
                     "format": "date-time",
@@ -9425,6 +9607,8 @@
                   "total",
                   "failed",
                   "reason",
+                  "stored",
+                  "announced",
                   "started_at",
                   "updated_at"
                 ],
@@ -9496,13 +9680,52 @@
               }
             ],
             "description": "What the connected bridge says it *could* transfer — deliberately separate from what has been transferred. `null` when no bridge is connected, distinct from `false`: \"no robot is online to ask\" and \"the robot has no URDF\" send a developer to different places. After a publisher is killed rather than shut down this can read `true` for some seconds, on the underlying DDS liveliness timeout rather than on any check made here."
+          },
+          "store": {
+            "type": "object",
+            "properties": {
+              "bytes": {
+                "type": "integer",
+                "exclusiveMinimum": 0,
+                "maximum": 9007199254740991,
+                "description": "The robot's asset store, `ROBOT_ASSET_STORE_BYTES`."
+              },
+              "used_bytes": {
+                "type": "integer",
+                "minimum": 0,
+                "maximum": 9007199254740991,
+                "description": "Bytes its assets occupy."
+              }
+            },
+            "required": [
+              "bytes",
+              "used_bytes"
+            ],
+            "additionalProperties": false,
+            "description": "How full this robot's store is."
+          },
+          "joint_state_slug": {
+            "anyOf": [
+              {
+                "type": "string",
+                "minLength": 2,
+                "maxLength": 63,
+                "pattern": "^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "The whole-message `sensor_msgs/msg/JointState` datapoint that drives the console's URDF viewer; null when none is chosen or a publish removed it. Set through `PUT /api/robots/:id/urdf/joint-state`."
           }
         },
         "required": [
           "assets",
           "active_sync",
           "urdf",
-          "urdf_available"
+          "urdf_available",
+          "store",
+          "joint_state_slug"
         ],
         "additionalProperties": false
       },
@@ -9590,32 +9813,38 @@
                   "enum": [
                     "unresolvable",
                     "upload_failed",
-                    "refused",
-                    "too_large"
+                    "refused"
                   ],
-                  "description": "Why it failed. `unresolvable` means the reference names nothing the producer can find or may read, and is **permanent** — the only kind reconciliation may treat as gone. `upload_failed` means the bytes exist and the transfer did not succeed, `refused` means it was never attempted because a producer-side ceiling was hit, and `too_large` means it exceeds the upload limit and carries both numbers in `details`."
+                  "description": "Why it failed. `unresolvable` means the reference names nothing the producer can find or may read, and is **permanent** — the only kind reconciliation may treat as gone. `upload_failed` means the bytes exist and the transfer did not succeed, and `refused` means it was never attempted, either because the robot's asset store had no room — then `details` carries the three numbers — or because a producer-side ceiling was hit."
                 },
                 "details": {
-                  "description": "The two numbers behind a `too_large` failure, and absent for every other kind — a forced `null` on every `unresolvable` entry buys nothing. The pairing is enforced, not merely described.",
+                  "description": "The three numbers behind a `refused` entry the robot's store had no room for, and absent for every other kind — a forced `null` on every `unresolvable` entry buys nothing. A `refused` entry may also carry no details: the producer's own ceiling is the other half of that kind, and no store number describes it.",
                   "anyOf": [
                     {
                       "type": "object",
                       "properties": {
-                        "limit_bytes": {
+                        "store_bytes": {
                           "type": "integer",
                           "exclusiveMinimum": 0,
                           "maximum": 9007199254740991,
-                          "description": "The upload ceiling, in bytes."
+                          "description": "The robot's store, in bytes."
+                        },
+                        "used_bytes": {
+                          "type": "integer",
+                          "minimum": 0,
+                          "maximum": 9007199254740991,
+                          "description": "Bytes the robot's assets occupy before this upload."
                         },
                         "size_bytes": {
                           "type": "integer",
                           "exclusiveMinimum": 0,
                           "maximum": 9007199254740991,
-                          "description": "How large the refused file is, in bytes. With `limit_bytes` beside it a developer can tell whether to shrink the mesh or raise the limit; \"too large\" alone answers neither."
+                          "description": "The refused upload, in bytes."
                         }
                       },
                       "required": [
-                        "limit_bytes",
+                        "store_bytes",
+                        "used_bytes",
                         "size_bytes"
                       ],
                       "additionalProperties": false
@@ -9646,6 +9875,25 @@
             ],
             "description": "Why the sync ended as it did, when that is not a per-reference fact. `null` when `failed` already says everything there is to say."
           },
+          "stored": {
+            "anyOf": [
+              {
+                "type": "integer",
+                "minimum": 0,
+                "maximum": 9007199254740991
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "How many of the announced files the cloud's store actually holds. Counted once, after the robot reports the sync done, and `null` until then — nobody has looked yet. Read it against `announced`: `state` is what the robot reported, this is what arrived."
+          },
+          "announced": {
+            "type": "integer",
+            "minimum": 0,
+            "maximum": 9007199254740991,
+            "description": "How many files the robot announced for this sync — the URDF, if it has one, plus every mesh URI its description references. `0` when the robot announced nothing, and also `0` until it has answered at all: read it beside `stored`, which stays `null` until the terminal frame."
+          },
           "started_at": {
             "type": "string",
             "format": "date-time",
@@ -9667,11 +9915,35 @@
           "total",
           "failed",
           "reason",
+          "stored",
+          "announced",
           "started_at",
           "updated_at"
         ],
         "additionalProperties": false
       },
+      "assets-clear-response": {
+        "type": "object",
+        "properties": {
+          "deleted": {
+            "type": "integer",
+            "minimum": 0,
+            "maximum": 9007199254740991,
+            "description": "How many assets — URDF, meshes and textures together — were removed."
+          },
+          "bytes_freed": {
+            "type": "integer",
+            "minimum": 0,
+            "maximum": 9007199254740991,
+            "description": "The bytes the robot's store got back."
+          }
+        },
+        "required": [
+          "deleted",
+          "bytes_freed"
+        ],
+        "additionalProperties": false
+      },
       "audit-list-response": {
         "type": "object",
         "properties": {
@@ -10535,11 +10807,16 @@
                           "type": "null"
                         }
                       ]
+                    },
+                    "low_bandwidth": {
+                      "type": "boolean",
+                      "description": "Whether the bridge is in its low-bandwidth mode: datapoints capped, cameras reduced or stopped. Bridge-reported."
                     }
                   },
                   "required": [
                     "online",
-                    "latency_ms"
+                    "latency_ms",
+                    "low_bandwidth"
                   ],
                   "additionalProperties": false,
                   "description": "The built-in `bridge_state` datapoint as the cloud observes it right now: whether the bridge is connected, and its latency when it is."
@@ -10665,6 +10942,11 @@
                             0.5
                           ]
                         },
+                        "low_bandwidth": {
+                          "description": "`keep` exempts this datapoint from the low-bandwidth rate cap; its backfill still pauses.",
+                          "type": "string",
+                          "const": "keep"
+                        },
                         "description": {
                           "description": "Prose about what this value is, for whoever meets it in the console. It changes nothing the robot does, so a publish that touches only it pushes no configuration at all — but it is carried verbatim into `robot_describe`, where a model that has never seen this robot reads it. The datapoint is offered whenever the role grants it; without one it is offered with `description: null` and the model has less to go on, as for actions, services, publishers and cameras. Omission is the only way to say nothing; an empty string is refused, here and on all five.",
                           "examples": [
@@ -10862,7 +11144,7 @@
                       ],
                       "additionalProperties": false
                     },
-                    "description": "Values the robot publishes, each one field of one topic or a whole topic, and **never several topics**. Keys are slugs, one namespace across all five exposure sections, which is what lets a role grant say `{robot, slug}` without naming a kind; `bridge_state`, `robot_details` and `bridge_pressure` are built-in, and `history` is reserved because `GET …/jobs/history` would shadow an action of that name; all four are refused when the document is validated."
+                    "description": "Values the robot publishes, each one field of one topic or a whole topic, and **never several topics**. Keys are slugs, one namespace across all five exposure sections, which is what lets a role grant say `{robot, slug}` without naming a kind; `bridge_state` and `robot_details` are built-in, and `history` is reserved because `GET …/jobs/history` would shadow an action of that name; all three are refused when the document is validated."
                   },
                   "actions": {
                     "type": "object",
@@ -11012,7 +11294,7 @@
                       ],
                       "additionalProperties": false
                     },
-                    "description": "Things the robot does on request that take time, each reported as a job with progress. **At most one job runs per action slug**: a second call is refused `busy`, and every observer of that slug watches the same job. Keys are slugs, one namespace across all five exposure sections, which is what lets a role grant say `{robot, slug}` without naming a kind; `bridge_state`, `robot_details` and `bridge_pressure` are built-in, and `history` is reserved because `GET …/jobs/history` would shadow an action of that name; all four are refused when the document is validated."
+                    "description": "Things the robot does on request that take time, each reported as a job with progress. **At most one job runs per action slug**: a second call is refused `busy`, and every observer of that slug watches the same job. Keys are slugs, one namespace across all five exposure sections, which is what lets a role grant say `{robot, slug}` without naming a kind; `bridge_state` and `robot_details` are built-in, and `history` is reserved because `GET …/jobs/history` would shadow an action of that name; all three are refused when the document is validated."
                   },
                   "services": {
                     "type": "object",
@@ -11162,7 +11444,7 @@
                       ],
                       "additionalProperties": false
                     },
-                    "description": "ROS service calls the robot answers — one request, one reply. Unlike an action a service reports **no progress** and the call returns with its result already on the job, so there is nothing left to observe; a second concurrent call is still refused `busy`, exactly as for an action. Keys are slugs, one namespace across all five exposure sections, which is what lets a role grant say `{robot, slug}` without naming a kind; `bridge_state`, `robot_details` and `bridge_pressure` are built-in, and `history` is reserved because `GET …/jobs/history` would shadow an action of that name; all four are refused when the document is validated."
+                    "description": "ROS service calls the robot answers — one request, one reply. Unlike an action a service reports **no progress** and the call returns with its result already on the job, so there is nothing left to observe; a second concurrent call is still refused `busy`, exactly as for an action. Keys are slugs, one namespace across all five exposure sections, which is what lets a role grant say `{robot, slug}` without naming a kind; `bridge_state` and `robot_details` are built-in, and `history` is reserved because `GET …/jobs/history` would shadow an action of that name; all three are refused when the document is validated."
                   },
                   "publishers": {
                     "type": "object",
@@ -11348,7 +11630,7 @@
                       ],
                       "additionalProperties": false
                     },
-                    "description": "Topics clients may send to, and where the format's whole safety story lives. The `message` template fixes every value a caller cannot change, and **`failsafe` is required**: once a client falls silent the bridge sends the failsafe message itself, so an operator whose window closed does not leave a robot driving. Keys are slugs, one namespace across all five exposure sections, which is what lets a role grant say `{robot, slug}` without naming a kind; `bridge_state`, `robot_details` and `bridge_pressure` are built-in, and `history` is reserved because `GET …/jobs/history` would shadow an action of that name; all four are refused when the document is validated."
+                    "description": "Topics clients may send to, and where the format's whole safety story lives. The `message` template fixes every value a caller cannot change, and **`failsafe` is required**: once a client falls silent the bridge sends the failsafe message itself, so an operator whose window closed does not leave a robot driving. Keys are slugs, one namespace across all five exposure sections, which is what lets a role grant say `{robot, slug}` without naming a kind; `bridge_state` and `robot_details` are built-in, and `history` is reserved because `GET …/jobs/history` would shadow an action of that name; all three are refused when the document is validated."
                   },
                   "cameras": {
                     "type": "object",
@@ -11596,7 +11878,67 @@
                       ],
                       "additionalProperties": false
                     },
-                    "description": "Video the robot streams, and the still frames the cloud serves from it. `width`, `height`, `fps` and `bitrate_kbps` are what **the bridge produces before sending**, not what the camera captures — they live in the configuration rather than in a viewer's request precisely so that no viewer can make a robot send more. Keys are slugs, one namespace across all five exposure sections, which is what lets a role grant say `{robot, slug}` without naming a kind; `bridge_state`, `robot_details` and `bridge_pressure` are built-in, and `history` is reserved because `GET …/jobs/history` would shadow an action of that name; all four are refused when the document is validated."
+                    "description": "Video the robot streams, and the still frames the cloud serves from it. `width`, `height`, `fps` and `bitrate_kbps` are what **the bridge produces before sending**, not what the camera captures — they live in the configuration rather than in a viewer's request precisely so that no viewer can make a robot send more. Keys are slugs, one namespace across all five exposure sections, which is what lets a role grant say `{robot, slug}` without naming a kind; `bridge_state` and `robot_details` are built-in, and `history` is reserved because `GET …/jobs/history` would shadow an action of that name; all three are refused when the document is validated."
+                  },
+                  "low_bandwidth": {
+                    "description": "Overrides for the bridge's low-bandwidth mode; see the section schema.",
+                    "type": "object",
+                    "properties": {
+                      "mode": {
+                        "description": "`auto` decides from the measured lag; `on` and `off` force the mode, for tests and for an operator who knows the link.",
+                        "type": "string",
+                        "enum": [
+                          "auto",
+                          "on",
+                          "off"
+                        ]
+                      },
+                      "enter_lag_ms": {
+                        "description": "Lag or queue dwell above this enters the mode. Checked against exit_lag_ms only when both are in this document; a lone key composes with the bridge's parameter or the default on the robot, and a crossed pair is refused there when the configuration is applied, so name both when you change either.",
+                        "type": "integer",
+                        "minimum": 100,
+                        "maximum": 9007199254740991
+                      },
+                      "enter_after_s": {
+                        "description": "The entry condition must hold this long.",
+                        "type": "integer",
+                        "minimum": 1,
+                        "maximum": 9007199254740991
+                      },
+                      "exit_lag_ms": {
+                        "description": "Lag and dwell both at or below this leave the mode. Must be at or below enter_lag_ms: a crossed pair is a mode that leaves as it arrives. Checked here only when both keys are present; a lone key is checked on the robot against the parameter or default it composes with.",
+                        "type": "integer",
+                        "minimum": 0,
+                        "maximum": 9007199254740991
+                      },
+                      "exit_after_s": {
+                        "description": "The exit condition must hold this long.",
+                        "type": "integer",
+                        "minimum": 1,
+                        "maximum": 9007199254740991
+                      },
+                      "datapoint_max_hz": {
+                        "description": "The long-run rate for every datapoint in the mode, unless the datapoint says `low_bandwidth: keep`. It is an average, not a minimum gap: after a quiet spell two samples may go out close together, and over any longer window the rate holds.",
+                        "type": "number",
+                        "exclusiveMinimum": 0,
+                        "maximum": 20
+                      },
+                      "camera": {
+                        "description": "What happens to a running stream in the mode. New streams are refused either way.",
+                        "type": "string",
+                        "enum": [
+                          "reduce",
+                          "stop"
+                        ]
+                      },
+                      "camera_bitrate_kbps": {
+                        "description": "Bitrate applied to running streams under `reduce`.",
+                        "type": "integer",
+                        "minimum": 50,
+                        "maximum": 20000
+                      }
+                    },
+                    "additionalProperties": false
                   }
                 },
                 "required": [
@@ -11762,6 +12104,11 @@
                         0.5
                       ]
                     },
+                    "low_bandwidth": {
+                      "description": "`keep` exempts this datapoint from the low-bandwidth rate cap; its backfill still pauses.",
+                      "type": "string",
+                      "const": "keep"
+                    },
                     "description": {
                       "description": "Prose about what this value is, for whoever meets it in the console. It changes nothing the robot does, so a publish that touches only it pushes no configuration at all — but it is carried verbatim into `robot_describe`, where a model that has never seen this robot reads it. The datapoint is offered whenever the role grants it; without one it is offered with `description: null` and the model has less to go on, as for actions, services, publishers and cameras. Omission is the only way to say nothing; an empty string is refused, here and on all five.",
                       "examples": [
@@ -11959,7 +12306,7 @@
                   ],
                   "additionalProperties": false
                 },
-                "description": "Values the robot publishes, each one field of one topic or a whole topic, and **never several topics**. Keys are slugs, one namespace across all five exposure sections, which is what lets a role grant say `{robot, slug}` without naming a kind; `bridge_state`, `robot_details` and `bridge_pressure` are built-in, and `history` is reserved because `GET …/jobs/history` would shadow an action of that name; all four are refused when the document is validated."
+                "description": "Values the robot publishes, each one field of one topic or a whole topic, and **never several topics**. Keys are slugs, one namespace across all five exposure sections, which is what lets a role grant say `{robot, slug}` without naming a kind; `bridge_state` and `robot_details` are built-in, and `history` is reserved because `GET …/jobs/history` would shadow an action of that name; all three are refused when the document is validated."
               },
               "actions": {
                 "type": "object",
@@ -12109,7 +12456,7 @@
                   ],
                   "additionalProperties": false
                 },
-                "description": "Things the robot does on request that take time, each reported as a job with progress. **At most one job runs per action slug**: a second call is refused `busy`, and every observer of that slug watches the same job. Keys are slugs, one namespace across all five exposure sections, which is what lets a role grant say `{robot, slug}` without naming a kind; `bridge_state`, `robot_details` and `bridge_pressure` are built-in, and `history` is reserved because `GET …/jobs/history` would shadow an action of that name; all four are refused when the document is validated."
+                "description": "Things the robot does on request that take time, each reported as a job with progress. **At most one job runs per action slug**: a second call is refused `busy`, and every observer of that slug watches the same job. Keys are slugs, one namespace across all five exposure sections, which is what lets a role grant say `{robot, slug}` without naming a kind; `bridge_state` and `robot_details` are built-in, and `history` is reserved because `GET …/jobs/history` would shadow an action of that name; all three are refused when the document is validated."
               },
               "services": {
                 "type": "object",
@@ -12259,7 +12606,7 @@
                   ],
                   "additionalProperties": false
                 },
-                "description": "ROS service calls the robot answers — one request, one reply. Unlike an action a service reports **no progress** and the call returns with its result already on the job, so there is nothing left to observe; a second concurrent call is still refused `busy`, exactly as for an action. Keys are slugs, one namespace across all five exposure sections, which is what lets a role grant say `{robot, slug}` without naming a kind; `bridge_state`, `robot_details` and `bridge_pressure` are built-in, and `history` is reserved because `GET …/jobs/history` would shadow an action of that name; all four are refused when the document is validated."
+                "description": "ROS service calls the robot answers — one request, one reply. Unlike an action a service reports **no progress** and the call returns with its result already on the job, so there is nothing left to observe; a second concurrent call is still refused `busy`, exactly as for an action. Keys are slugs, one namespace across all five exposure sections, which is what lets a role grant say `{robot, slug}` without naming a kind; `bridge_state` and `robot_details` are built-in, and `history` is reserved because `GET …/jobs/history` would shadow an action of that name; all three are refused when the document is validated."
               },
               "publishers": {
                 "type": "object",
@@ -12445,7 +12792,7 @@
                   ],
                   "additionalProperties": false
                 },
-                "description": "Topics clients may send to, and where the format's whole safety story lives. The `message` template fixes every value a caller cannot change, and **`failsafe` is required**: once a client falls silent the bridge sends the failsafe message itself, so an operator whose window closed does not leave a robot driving. Keys are slugs, one namespace across all five exposure sections, which is what lets a role grant say `{robot, slug}` without naming a kind; `bridge_state`, `robot_details` and `bridge_pressure` are built-in, and `history` is reserved because `GET …/jobs/history` would shadow an action of that name; all four are refused when the document is validated."
+                "description": "Topics clients may send to, and where the format's whole safety story lives. The `message` template fixes every value a caller cannot change, and **`failsafe` is required**: once a client falls silent the bridge sends the failsafe message itself, so an operator whose window closed does not leave a robot driving. Keys are slugs, one namespace across all five exposure sections, which is what lets a role grant say `{robot, slug}` without naming a kind; `bridge_state` and `robot_details` are built-in, and `history` is reserved because `GET …/jobs/history` would shadow an action of that name; all three are refused when the document is validated."
               },
               "cameras": {
                 "type": "object",
@@ -12693,7 +13040,67 @@
                   ],
                   "additionalProperties": false
                 },
-                "description": "Video the robot streams, and the still frames the cloud serves from it. `width`, `height`, `fps` and `bitrate_kbps` are what **the bridge produces before sending**, not what the camera captures — they live in the configuration rather than in a viewer's request precisely so that no viewer can make a robot send more. Keys are slugs, one namespace across all five exposure sections, which is what lets a role grant say `{robot, slug}` without naming a kind; `bridge_state`, `robot_details` and `bridge_pressure` are built-in, and `history` is reserved because `GET …/jobs/history` would shadow an action of that name; all four are refused when the document is validated."
+                "description": "Video the robot streams, and the still frames the cloud serves from it. `width`, `height`, `fps` and `bitrate_kbps` are what **the bridge produces before sending**, not what the camera captures — they live in the configuration rather than in a viewer's request precisely so that no viewer can make a robot send more. Keys are slugs, one namespace across all five exposure sections, which is what lets a role grant say `{robot, slug}` without naming a kind; `bridge_state` and `robot_details` are built-in, and `history` is reserved because `GET …/jobs/history` would shadow an action of that name; all three are refused when the document is validated."
+              },
+              "low_bandwidth": {
+                "description": "Overrides for the bridge's low-bandwidth mode; see the section schema.",
+                "type": "object",
+                "properties": {
+                  "mode": {
+                    "description": "`auto` decides from the measured lag; `on` and `off` force the mode, for tests and for an operator who knows the link.",
+                    "type": "string",
+                    "enum": [
+                      "auto",
+                      "on",
+                      "off"
+                    ]
+                  },
+                  "enter_lag_ms": {
+                    "description": "Lag or queue dwell above this enters the mode. Checked against exit_lag_ms only when both are in this document; a lone key composes with the bridge's parameter or the default on the robot, and a crossed pair is refused there when the configuration is applied, so name both when you change either.",
+                    "type": "integer",
+                    "minimum": 100,
+                    "maximum": 9007199254740991
+                  },
+                  "enter_after_s": {
+                    "description": "The entry condition must hold this long.",
+                    "type": "integer",
+                    "minimum": 1,
+                    "maximum": 9007199254740991
+                  },
+                  "exit_lag_ms": {
+                    "description": "Lag and dwell both at or below this leave the mode. Must be at or below enter_lag_ms: a crossed pair is a mode that leaves as it arrives. Checked here only when both keys are present; a lone key is checked on the robot against the parameter or default it composes with.",
+                    "type": "integer",
+                    "minimum": 0,
+                    "maximum": 9007199254740991
+                  },
+                  "exit_after_s": {
+                    "description": "The exit condition must hold this long.",
+                    "type": "integer",
+                    "minimum": 1,
+                    "maximum": 9007199254740991
+                  },
+                  "datapoint_max_hz": {
+                    "description": "The long-run rate for every datapoint in the mode, unless the datapoint says `low_bandwidth: keep`. It is an average, not a minimum gap: after a quiet spell two samples may go out close together, and over any longer window the rate holds.",
+                    "type": "number",
+                    "exclusiveMinimum": 0,
+                    "maximum": 20
+                  },
+                  "camera": {
+                    "description": "What happens to a running stream in the mode. New streams are refused either way.",
+                    "type": "string",
+                    "enum": [
+                      "reduce",
+                      "stop"
+                    ]
+                  },
+                  "camera_bitrate_kbps": {
+                    "description": "Bitrate applied to running streams under `reduce`.",
+                    "type": "integer",
+                    "minimum": 50,
+                    "maximum": 20000
+                  }
+                },
+                "additionalProperties": false
               }
             },
             "required": [
@@ -13102,7 +13509,7 @@
                 },
                 "builtin": {
                   "type": "boolean",
-                  "description": "`true` for the datapoints every robot has — `bridge_state`, `robot_details` and `bridge_pressure` — and `false` for everything the published configuration adds."
+                  "description": "`true` for the datapoints every robot has — `bridge_state` and `robot_details` — and `false` for everything the published configuration adds."
                 },
                 "unit": {
                   "anyOf": [
@@ -13137,7 +13544,7 @@
               ],
               "additionalProperties": false
             },
-            "description": "Everything a client may read on this robot: the three built-ins, plus every datapoint the published configuration exposes and the caller's role grants."
+            "description": "Everything a client may read on this robot: the two built-ins, plus every datapoint the published configuration exposes and the caller's role grants."
           }
         },
         "required": [
@@ -14452,6 +14859,51 @@
         ],
         "additionalProperties": false
       },
+      "joint-state-put-request": {
+        "type": "object",
+        "properties": {
+          "slug": {
+            "anyOf": [
+              {
+                "type": "string",
+                "minLength": 2,
+                "maxLength": 63,
+                "pattern": "^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "The datapoint to read joint positions from, or `null` to choose none. It must name a whole-message `sensor_msgs/msg/JointState` datapoint of the published configuration; anything else is a `validation_error` naming the rule."
+          }
+        },
+        "required": [
+          "slug"
+        ]
+      },
+      "joint-state-put-response": {
+        "type": "object",
+        "properties": {
+          "joint_state_slug": {
+            "anyOf": [
+              {
+                "type": "string",
+                "minLength": 2,
+                "maxLength": 63,
+                "pattern": "^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "The stored mapping after the call, `null` when none is chosen. The same value `assetListResponse.joint_state_slug` carries."
+          }
+        },
+        "required": [
+          "joint_state_slug"
+        ],
+        "additionalProperties": false
+      },
       "live-session-response": {
         "type": "object",
         "properties": {
@@ -15329,11 +15781,6 @@
                 "type": "integer",
                 "exclusiveMinimum": 0,
                 "maximum": 9007199254740991
-              },
-              "max_asset_storage_bytes": {
-                "type": "integer",
-                "minimum": 0,
-                "maximum": 9007199254740991
               }
             },
             "required": [
@@ -15342,8 +15789,7 @@
               "max_end_users",
               "max_retention_bytes",
               "max_retention_writes_per_minute",
-              "max_realtime_connections",
-              "max_asset_storage_bytes"
+              "max_realtime_connections"
             ],
             "additionalProperties": false
           },
@@ -15370,11 +15816,6 @@
                 "minimum": 0,
                 "maximum": 9007199254740991
               },
-              "max_asset_storage_bytes": {
-                "type": "integer",
-                "minimum": 0,
-                "maximum": 9007199254740991
-              },
               "max_retention_writes_per_minute": {
                 "type": "integer",
                 "minimum": 0,
@@ -16268,7 +16709,8 @@
           "asset_bytes_freed": {
             "type": "integer",
             "minimum": 0,
-            "maximum": 9007199254740991
+            "maximum": 9007199254740991,
+            "description": "What the robot's store gives back: every distinct mesh or texture blob it holds, counted once, URDF excluded; a blob another robot also references stays in the object store but is still credited here, because each robot's counter carries it."
           },
           "job_run_count": {
             "type": "integer",
@@ -16332,11 +16774,16 @@
                     "type": "null"
                   }
                 ]
+              },
+              "low_bandwidth": {
+                "type": "boolean",
+                "description": "Whether the bridge is in its low-bandwidth mode: datapoints capped, cameras reduced or stopped. Bridge-reported."
               }
             },
             "required": [
               "online",
-              "latency_ms"
+              "latency_ms",
+              "low_bandwidth"
             ],
             "additionalProperties": false
           },
@@ -16378,6 +16825,15 @@
             ],
             "additionalProperties": false
           },
+          "protocol_status": {
+            "description": "Where this robot's bridge stands against the protocol window: `current`, `deprecated` (still served, sunset date on the detail), or `refused` (its last hello was refused for its version; offline until upgraded). Absent from a cloud older than 0.21.0; read absence as `current`.",
+            "type": "string",
+            "enum": [
+              "current",
+              "deprecated",
+              "refused"
+            ]
+          },
           "bridge_version": {
             "anyOf": [
               {
@@ -16389,6 +16845,52 @@
               }
             ]
           },
+          "protocol_version": {
+            "description": "The protocol version the bridge announced in its last accepted hello; `null` before the first. Absent from a cloud older than 0.21.0.",
+            "anyOf": [
+              {
+                "type": "integer",
+                "exclusiveMinimum": 0,
+                "maximum": 9007199254740991
+              },
+              {
+                "type": "null"
+              }
+            ]
+          },
+          "protocol": {
+            "description": "The window verdict for `protocol_version`.",
+            "type": "object",
+            "properties": {
+              "status": {
+                "type": "string",
+                "enum": [
+                  "current",
+                  "deprecated",
+                  "refused"
+                ],
+                "description": "Same values as `protocol_status`."
+              },
+              "sunset_at": {
+                "anyOf": [
+                  {
+                    "type": "string",
+                    "format": "date",
+                    "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"
+                  },
+                  {
+                    "type": "null"
+                  }
+                ],
+                "description": "ISO date the announced version stops being served; `null` when current or unknown."
+              }
+            },
+            "required": [
+              "status",
+              "sunset_at"
+            ],
+            "additionalProperties": false
+          },
           "last_hello_error": {
             "anyOf": [
               {
@@ -16498,7 +17000,8 @@
                             "action",
                             "service",
                             "publisher",
-                            "camera"
+                            "camera",
+                            "low_bandwidth"
                           ]
                         },
                         "code": {
@@ -16716,11 +17219,16 @@
                           "type": "null"
                         }
                       ]
+                    },
+                    "low_bandwidth": {
+                      "type": "boolean",
+                      "description": "Whether the bridge is in its low-bandwidth mode: datapoints capped, cameras reduced or stopped. Bridge-reported."
                     }
                   },
                   "required": [
                     "online",
-                    "latency_ms"
+                    "latency_ms",
+                    "low_bandwidth"
                   ],
                   "additionalProperties": false
                 },
@@ -16761,6 +17269,15 @@
                     "cameras"
                   ],
                   "additionalProperties": false
+                },
+                "protocol_status": {
+                  "description": "Where this robot's bridge stands against the protocol window: `current`, `deprecated` (still served, sunset date on the detail), or `refused` (its last hello was refused for its version; offline until upgraded). Absent from a cloud older than 0.21.0; read absence as `current`.",
+                  "type": "string",
+                  "enum": [
+                    "current",
+                    "deprecated",
+                    "refused"
+                  ]
                 }
               },
               "required": [
@@ -16779,6 +17296,20 @@
         ],
         "additionalProperties": false
       },
+      "robot-token-rotate-response": {
+        "type": "object",
+        "properties": {
+          "token": {
+            "type": "string",
+            "pattern": "^frt_[0-9a-f]{32}$",
+            "description": "The robot's new bridge token. Returned exactly once; the previous token stops working at the bridge's next hello."
+          }
+        },
+        "required": [
+          "token"
+        ],
+        "additionalProperties": false
+      },
       "role": {
         "type": "object",
         "properties": {