@fleetless/contracts 1.1.0 → 2.0.0

package/artifacts/schema/cloud-config.schema.json

@@ -117,6 +117,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": [
@@ -437,7 +442,7 @@
               }
             ]
           },
-          "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.",
           "defaultSnippets": [
             {
               "label": "a datapoint",
@@ -685,7 +690,7 @@
               }
             ]
           },
-          "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.",
           "defaultSnippets": [
             {
               "label": "an action",
@@ -906,7 +911,7 @@
               }
             ]
           },
-          "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.",
           "defaultSnippets": [
             {
               "label": "a service",
@@ -1214,7 +1219,7 @@
               }
             ]
           },
-          "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.",
           "defaultSnippets": [
             {
               "label": "a publisher, with its parameters and its failsafe",
@@ -1598,7 +1603,7 @@
               }
             ]
           },
-          "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.",
           "defaultSnippets": [
             {
               "label": "a camera",
@@ -1619,6 +1624,86 @@
               }
             }
           ]
+        },
+        "low_bandwidth": {
+          "description": "Overrides for the bridge's low-bandwidth mode; see the section schema.",
+          "defaultSnippets": [
+            {
+              "label": "low-bandwidth mode, tuned",
+              "description": "Enters after ten seconds above two seconds of lag, caps every datapoint to 1 Hz and lets running streams continue at a reduced bitrate.",
+              "body": {
+                "enter_lag_ms": 2000,
+                "datapoint_max_hz": 1,
+                "camera": "reduce"
+              }
+            }
+          ],
+          "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.",
+              "enumDescriptions": [
+                "The bridge enters and leaves the mode on its own, from the lag the cloud reports and the dwell it measures in its own send queue. The setting to leave alone.",
+                "The mode is held on, whatever the link is doing. For a robot on a link known to be poor, and for a test that would otherwise have to wait for a real one.",
+                "The mode never engages, whatever the link is doing. The robot then sends at its configured rates over a link that cannot carry them, which is a choice and not a default."
+              ],
+              "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.",
+              "enumDescriptions": [
+                "A running stream is re-encoded at `camera_bitrate_kbps` and keeps running. A viewer sees a worse picture rather than none.",
+                "A running stream ends and the viewer is told why. The uplink is then free for datapoints, which is the right trade where video is the nice-to-have."
+              ],
+              "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": [

package/artifacts/schema/cloud-hello-ok.schema.json

@@ -10,6 +10,51 @@
       "type": "string",
       "format": "uuid",
       "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
+    },
+    "protocol": {
+      "description": "The cloud's verdict on the announced protocol version; absent from an older cloud.",
+      "type": "object",
+      "properties": {
+        "status": {
+          "type": "string",
+          "enum": [
+            "current",
+            "deprecated"
+          ],
+          "description": "`current` or `deprecated` — never `unsupported`, which is a `hello_error`."
+        },
+        "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 a deprecated version stops being served; `null` when current."
+        }
+      },
+      "required": [
+        "status",
+        "sunset_at"
+      ]
+    },
+    "bridge": {
+      "description": "What the cloud knows about bridge packages; absent from an older cloud.",
+      "type": "object",
+      "properties": {
+        "latest_version": {
+          "type": "string",
+          "minLength": 1,
+          "description": "The newest published fleetless-bridge package version, for the bridge's own upgrade hint."
+        }
+      },
+      "required": [
+        "latest_version"
+      ]
     }
   },
   "required": [

package/artifacts/schema/cloud-ping.schema.json

@@ -10,10 +10,36 @@
       "type": "integer",
       "minimum": 0,
       "maximum": 9007199254740991
+    },
+    "latency_ms": {
+      "anyOf": [
+        {
+          "type": "number",
+          "minimum": 0
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Round trip of the last pong in milliseconds; null before the first."
+    },
+    "lag_ms": {
+      "anyOf": [
+        {
+          "type": "number",
+          "minimum": 0
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "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."
     }
   },
   "required": [
     "type",
-    "ts_ms"
+    "ts_ms",
+    "latency_ms",
+    "lag_ms"
   ]
 }

package/artifacts/schema/config-draft-response.schema.json

@@ -110,6 +110,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": [
@@ -430,7 +435,7 @@
                   }
                 ]
               },
-              "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.",
               "defaultSnippets": [
                 {
                   "label": "a datapoint",
@@ -678,7 +683,7 @@
                   }
                 ]
               },
-              "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.",
               "defaultSnippets": [
                 {
                   "label": "an action",
@@ -899,7 +904,7 @@
                   }
                 ]
               },
-              "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.",
               "defaultSnippets": [
                 {
                   "label": "a service",
@@ -1207,7 +1212,7 @@
                   }
                 ]
               },
-              "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.",
               "defaultSnippets": [
                 {
                   "label": "a publisher, with its parameters and its failsafe",
@@ -1591,7 +1596,7 @@
                   }
                 ]
               },
-              "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.",
               "defaultSnippets": [
                 {
                   "label": "a camera",
@@ -1612,6 +1617,86 @@
                   }
                 }
               ]
+            },
+            "low_bandwidth": {
+              "description": "Overrides for the bridge's low-bandwidth mode; see the section schema.",
+              "defaultSnippets": [
+                {
+                  "label": "low-bandwidth mode, tuned",
+                  "description": "Enters after ten seconds above two seconds of lag, caps every datapoint to 1 Hz and lets running streams continue at a reduced bitrate.",
+                  "body": {
+                    "enter_lag_ms": 2000,
+                    "datapoint_max_hz": 1,
+                    "camera": "reduce"
+                  }
+                }
+              ],
+              "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.",
+                  "enumDescriptions": [
+                    "The bridge enters and leaves the mode on its own, from the lag the cloud reports and the dwell it measures in its own send queue. The setting to leave alone.",
+                    "The mode is held on, whatever the link is doing. For a robot on a link known to be poor, and for a test that would otherwise have to wait for a real one.",
+                    "The mode never engages, whatever the link is doing. The robot then sends at its configured rates over a link that cannot carry them, which is a choice and not a default."
+                  ],
+                  "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.",
+                  "enumDescriptions": [
+                    "A running stream is re-encoded at `camera_bitrate_kbps` and keeps running. A viewer sees a worse picture rather than none.",
+                    "A running stream ends and the viewer is told why. The uplink is then free for datapoints, which is the right trade where video is the nice-to-have."
+                  ],
+                  "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": [

package/artifacts/schema/config-state.schema.json

@@ -77,7 +77,8 @@
                   "action",
                   "service",
                   "publisher",
-                  "camera"
+                  "camera",
+                  "low_bandwidth"
                 ]
               },
               "code": {

package/artifacts/schema/config-version-response.schema.json

@@ -118,6 +118,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": [
@@ -438,7 +443,7 @@
               }
             ]
           },
-          "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.",
           "defaultSnippets": [
             {
               "label": "a datapoint",
@@ -686,7 +691,7 @@
               }
             ]
           },
-          "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.",
           "defaultSnippets": [
             {
               "label": "an action",
@@ -907,7 +912,7 @@
               }
             ]
           },
-          "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.",
           "defaultSnippets": [
             {
               "label": "a service",
@@ -1215,7 +1220,7 @@
               }
             ]
           },
-          "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.",
           "defaultSnippets": [
             {
               "label": "a publisher, with its parameters and its failsafe",
@@ -1599,7 +1604,7 @@
               }
             ]
           },
-          "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.",
           "defaultSnippets": [
             {
               "label": "a camera",
@@ -1620,6 +1625,86 @@
               }
             }
           ]
+        },
+        "low_bandwidth": {
+          "description": "Overrides for the bridge's low-bandwidth mode; see the section schema.",
+          "defaultSnippets": [
+            {
+              "label": "low-bandwidth mode, tuned",
+              "description": "Enters after ten seconds above two seconds of lag, caps every datapoint to 1 Hz and lets running streams continue at a reduced bitrate.",
+              "body": {
+                "enter_lag_ms": 2000,
+                "datapoint_max_hz": 1,
+                "camera": "reduce"
+              }
+            }
+          ],
+          "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.",
+              "enumDescriptions": [
+                "The bridge enters and leaves the mode on its own, from the lag the cloud reports and the dwell it measures in its own send queue. The setting to leave alone.",
+                "The mode is held on, whatever the link is doing. For a robot on a link known to be poor, and for a test that would otherwise have to wait for a real one.",
+                "The mode never engages, whatever the link is doing. The robot then sends at its configured rates over a link that cannot carry them, which is a choice and not a default."
+              ],
+              "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.",
+              "enumDescriptions": [
+                "A running stream is re-encoded at `camera_bitrate_kbps` and keeps running. A viewer sees a worse picture rather than none.",
+                "A running stream ends and the viewer is told why. The uplink is then free for datapoints, which is the right trade where video is the nice-to-have."
+              ],
+              "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": [

package/artifacts/schema/datapoint-config.schema.json

@@ -44,6 +44,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": [

package/artifacts/schema/datapoint-frame.schema.json

@@ -17,6 +17,10 @@
       "type": "integer",
       "minimum": 0,
       "maximum": 9007199254740991
+    },
+    "backfill": {
+      "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.",
+      "type": "boolean"
     }
   },
   "required": [

package/artifacts/schema/datapoint-list-response.schema.json

@@ -16,7 +16,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": [
@@ -51,7 +51,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": [

package/artifacts/schema/dynamic-client-registration-request.schema.json

@@ -27,7 +27,7 @@
       ]
     },
     "grant_types": {
-      "description": "Accepted for conformance with RFC 7591 and then **ignored**. What comes back is what was actually granted, which §3.2.1 permits a server to substitute: `authorization_code` and nothing else, so a client that asks for `refresh_token` is registered and told plainly that it did not get one.",
+      "description": "Accepted for conformance with RFC 7591 and then **ignored**: both MCP authorization servers grant `authorization_code` and `refresh_token` to every registration, and the answer states what was granted (§3.2.1) rather than what was asked.",
       "type": "array",
       "items": {
         "type": "string",

package/artifacts/schema/dynamic-client-registration-response.schema.json

@@ -28,7 +28,7 @@
       "items": {
         "type": "string"
       },
-      "description": "The grants this client may use. Always exactly `[\"authorization_code\"]` — a client that asked for `refresh_token` is registered and told here that it did not get one, which is the substitution RFC 7591 §3.2.1 permits."
+      "description": "The grants this client may use. Always exactly `[\"authorization_code\", \"refresh_token\"]` — an exchange mints a refresh token and the token endpoint rotates it."
     },
     "response_types": {
       "type": "array",