@fleetless/contracts 1.2.0 → 2.0.0

package/artifacts/routes.json

@@ -3052,6 +3052,66 @@
       "transport": "http",
       "notes": "`token` is the only moment the raw bridge token exists outside the caller's hands — the cloud stores a hash, so nothing can read it back and a caller who loses it rotates rather than recovers. Audited: this mints a credential that can speak for the org from anywhere, and the event carries no `details`, because the one interesting value here is the token. `max_robots` is checked before anything is created, which is only safe because robot deletion exists."
     },
+    {
+      "method": "POST",
+      "path": "/api/robots/:id/token/rotate",
+      "section": "robots",
+      "summary": "Mints a new bridge token for the robot and invalidates the old one.",
+      "audience": "developer",
+      "auth": "developer",
+      "rateLimited": false,
+      "ownerTier": true,
+      "status": 201,
+      "params": [
+        {
+          "name": "id",
+          "description": "The robot's uuid, as returned by `POST /api/robots` or listed by `GET /api/robots`."
+        }
+      ],
+      "query": null,
+      "request": null,
+      "response": "robot-token-rotate-response",
+      "errors": [
+        "unauthorized",
+        "token_expired",
+        "token_revoked",
+        "tier_required",
+        "invalid_uuid",
+        "not_found"
+      ],
+      "transport": "http",
+      "notes": "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."
+    },
+    {
+      "method": "PUT",
+      "path": "/api/robots/:id/urdf/joint-state",
+      "section": "robots",
+      "summary": "Chooses the datapoint whose joint positions move the robot's URDF, or clears it.",
+      "audience": "developer",
+      "auth": "developer",
+      "rateLimited": false,
+      "ownerTier": false,
+      "status": 200,
+      "params": [
+        {
+          "name": "id",
+          "description": "The robot's uuid, as returned by `POST /api/robots` or listed by `GET /api/robots`."
+        }
+      ],
+      "query": null,
+      "request": "joint-state-put-request",
+      "response": "joint-state-put-response",
+      "errors": [
+        "unauthorized",
+        "token_expired",
+        "token_revoked",
+        "invalid_uuid",
+        "not_found",
+        "validation_error"
+      ],
+      "transport": "http",
+      "notes": "**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."
+    },
     {
       "method": "GET",
       "path": "/api/robots",
@@ -4467,6 +4527,38 @@
       "transport": "http",
       "notes": "Developer sessions only, like starting a sync: the guard admits three caller kinds and the handler answers `401 unauthorized` to the other two. A sync belonging to another robot reads exactly like one that never existed, which is why the robot is resolved first."
     },
+    {
+      "method": "DELETE",
+      "path": "/api/robots/:id/assets",
+      "section": "assets",
+      "summary": "Empties a robot's asset store: every URDF, mesh and texture, gone at once.",
+      "audience": "client",
+      "auth": "developer_or_client",
+      "rateLimited": false,
+      "ownerTier": true,
+      "status": 200,
+      "params": [
+        {
+          "name": "id",
+          "description": "The robot's uuid, as returned by `POST /api/robots` or listed by `GET /api/robots`."
+        }
+      ],
+      "query": null,
+      "request": null,
+      "response": "assets-clear-response",
+      "errors": [
+        "unauthorized",
+        "token_expired",
+        "token_revoked",
+        "forbidden",
+        "tier_required",
+        "invalid_uuid",
+        "not_found",
+        "busy"
+      ],
+      "transport": "http",
+      "notes": "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."
+    },
     {
       "method": "GET",
       "path": "/api/org/quotas",
@@ -4622,14 +4714,13 @@
       "errors": [
         "unauthorized",
         "rate_limited",
-        "asset_too_large",
         "validation_error",
         "not_found",
         "quota_exceeded",
         "bad_request"
       ],
       "transport": "http",
-      "notes": "The body is the **raw file bytes**, not JSON, so it has no request schema; everything about the file — its kind, its name, its sync id and its announced size — rides in the `x-fleetless-asset-*` headers `ASSET_UPLOAD_HEADERS` names. The credential is a short-lived upload token minted by `POST /api/robots/:id/assets/sync`, verified in a `preParsing` hook so a refusal precedes the work rather than following it: a `preHandler` would already have buffered the whole file. The announced size is refused there too, before a single byte is read — it is an announcement and not a proof, so it only ever rejects early and never accepts early, and a body that lies small is still caught by the real length check. Past both, the server's own body limit answers a bare `413 bad_request` with neither ceiling nor size in it. Rate limited per robot inside that same hook, which is why `rateLimited` is `false`: there is no rate-limiting preHandler registered on this route."
+      "notes": "The body is the **raw file bytes**, not JSON, so it has no request schema; everything about the file — its kind, its name, its sync id and its announced size — rides in the `x-fleetless-asset-*` headers `ASSET_UPLOAD_HEADERS` names. The credential is a short-lived upload token minted by `POST /api/robots/:id/assets/sync`, verified in a `preParsing` hook so a refusal precedes the work rather than following it: a `preHandler` would already have buffered the whole file. **Nothing is refused for its own size** — the robot's asset store is the only limit, so the announced size is checked there against `ROBOT_ASSET_STORE_BYTES` and a file with no room left answers `409 quota_exceeded` carrying `store_bytes`, `used_bytes` and `size_bytes`, while the sync carries on with the next file. Past that, the server's own body limit answers a bare `413 bad_request` with none of those numbers in it. Rate limited per robot inside that same hook, which is why `rateLimited` is `false`: there is no rate-limiting preHandler registered on this route. The URDF itself is never refused for the store; only meshes and textures are charged against it."
     },
     {
       "method": "GET",

package/artifacts/schema/apply-error.schema.json

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

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

@@ -24,10 +24,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",
@@ -128,32 +127,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
@@ -184,6 +189,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",
@@ -205,6 +229,8 @@
             "total",
             "failed",
             "reason",
+            "stored",
+            "announced",
             "started_at",
             "updated_at"
           ],
@@ -276,13 +302,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
 }

package/artifacts/schema/asset-sync-status.schema.json

@@ -52,32 +52,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
@@ -108,6 +114,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",
@@ -129,6 +154,8 @@
     "total",
     "failed",
     "reason",
+    "stored",
+    "announced",
     "started_at",
     "updated_at"
   ],

package/artifacts/schema/asset.schema.json

@@ -19,10 +19,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",

package/artifacts/schema/assets-clear-response.schema.json

@@ -0,0 +1,23 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "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
+}

package/artifacts/schema/bridge-asset-progress.schema.json

@@ -38,32 +38,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"
                 ]
               },

package/artifacts/schema/bridge-config-applied.schema.json

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

package/artifacts/schema/bridge-link-mode.schema.json

@@ -0,0 +1,36 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "type": {
+      "type": "string",
+      "const": "link_mode"
+    },
+    "low_bandwidth": {
+      "type": "boolean",
+      "description": "Whether the mode is active after this transition."
+    },
+    "reason": {
+      "type": "string",
+      "enum": [
+        "lag",
+        "dwell",
+        "forced",
+        "recovered"
+      ],
+      "description": "`lag`: the cloud-measured lag crossed the threshold; `dwell`: the bridge-measured queue dwell did; `forced`: `mode: on` or `off`; `recovered`: both measures stayed at or below the exit threshold."
+    },
+    "at_ms": {
+      "type": "integer",
+      "minimum": 0,
+      "maximum": 9007199254740991,
+      "description": "Bridge time of the transition, epoch milliseconds."
+    }
+  },
+  "required": [
+    "type",
+    "low_bandwidth",
+    "reason",
+    "at_ms"
+  ]
+}

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

@@ -15,10 +15,15 @@
           "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"
   ]
 }

package/artifacts/schema/client-robot-list-item.schema.json

@@ -36,11 +36,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."

package/artifacts/schema/client-robot-list-response.schema.json

@@ -41,11 +41,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."