@fleetless/contracts 1.2.0 → 3.0.0

package/artifacts/routes.json

@@ -487,6 +487,65 @@
       "transport": "http",
       "notes": "A `default_role_id` naming a role of another app is refused: it is the one cross-app authorization check this shape can carry. Changing the robot set closes every live subscription the app's users hold, since a grant may no longer name a reachable robot."
     },
+    {
+      "method": "GET",
+      "path": "/api/apps/:id/deletion-preview",
+      "section": "apps",
+      "summary": "Reports what deleting the app would destroy, without destroying it.",
+      "audience": "developer",
+      "auth": "developer",
+      "rateLimited": false,
+      "ownerTier": false,
+      "status": 200,
+      "params": [
+        {
+          "name": "id",
+          "description": "The app's uuid, as returned by `POST /api/apps` or listed by `GET /api/apps`."
+        }
+      ],
+      "query": null,
+      "request": null,
+      "response": "app-deletion-summary",
+      "errors": [
+        "unauthorized",
+        "token_expired",
+        "token_revoked",
+        "invalid_uuid",
+        "not_found"
+      ],
+      "transport": "http",
+      "notes": "The same shape the delete's own audit event carries, computed by the same function on purpose: the confirmation dialog and the eventual receipt agree by construction, and any difference between them is real drift rather than two estimates that quietly disagree. \n\n**No `force` parameter, unlike the robot pair this is modelled on.** A robot's open live session is a single nameable state whose interruption is its own hazard, which is why that route makes the caller pass `force` explicitly. An app has no equivalent state to force past, and inventing one would be a guess wearing a guard's clothes — this preview is the guard."
+    },
+    {
+      "method": "DELETE",
+      "path": "/api/apps/:id",
+      "section": "apps",
+      "summary": "Deletes an app and everything it produced.",
+      "audience": "developer",
+      "auth": "developer",
+      "rateLimited": false,
+      "ownerTier": true,
+      "status": 204,
+      "params": [
+        {
+          "name": "id",
+          "description": "The app's uuid, as returned by `POST /api/apps` or listed by `GET /api/apps`."
+        }
+      ],
+      "query": null,
+      "request": null,
+      "response": null,
+      "errors": [
+        "unauthorized",
+        "token_expired",
+        "token_revoked",
+        "tier_required",
+        "invalid_uuid",
+        "not_found"
+      ],
+      "transport": "http",
+      "notes": "Owner tier, and the gate runs **after** the org-scoped lookup: a developer-tier admin therefore sees the same `404` a stranger would for an app outside their org, rather than a tier refusal that confirms the id exists. A full cascade — its users, roles, server keys, invitations, OIDC provider configuration and mail templates all go, recorded once as `app.deleted` carrying an `appDeletionSummary`. Its robots are untouched: they belong to the org, not to the app. \n\n**No `force` parameter** — see `GET /api/apps/:id/deletion-preview`."
+    },
     {
       "method": "POST",
       "path": "/api/apps/:id/roles",
@@ -1360,13 +1419,73 @@
         "not_found"
       ],
       "transport": "http",
-      "notes": "One row per app, created with the app and never absent — an app that has configured nothing reads back the defaults rather than a `404`. `oidc_callback_url` is in the answer and not in the request: it is minted by the cloud from its own public base URL, is the same for every app and every provider, and is the value a developer registers at their identity provider."
+      "notes": "One row per app, created with the app and never absent — an app that has configured nothing reads back the defaults rather than a `404`. `oidc_callback_url` is in the answer and not in the request: it is minted by the cloud from its own public base URL, is the same for every app and every provider, and is the value a developer registers at their identity provider. It stays read-only on every slice write below for a second reason: a writable callback URL would let a caller point the return leg of an OIDC sign-in, which carries an authorization code, at a host they own. `updated_at` is read-only for a duller one: the server stamps it on every write, and a client-supplied value would be a lie about when the row last changed."
     },
     {
       "method": "PUT",
-      "path": "/api/apps/:id/auth-config",
+      "path": "/api/apps/:id/auth-config/registration",
+      "section": "apps",
+      "summary": "Replaces who may self-register, and from where.",
+      "audience": "developer",
+      "auth": "developer",
+      "rateLimited": false,
+      "ownerTier": false,
+      "status": 200,
+      "params": [
+        {
+          "name": "id",
+          "description": "The app's uuid, as returned by `POST /api/apps` or listed by `GET /api/apps`."
+        }
+      ],
+      "query": null,
+      "request": "put-app-auth-registration-request",
+      "response": "app-auth-config",
+      "errors": [
+        "unauthorized",
+        "token_expired",
+        "token_revoked",
+        "invalid_uuid",
+        "validation_error",
+        "not_found"
+      ],
+      "transport": "http",
+      "notes": "**A replace, not a merge, and `.strict()`**: `self_registration`, `allowed_domains` and `allowed_origins` all arrive or the write is refused, so a client built against an older shape cannot silently clear a setting it does not know about. `oidc_callback_url` and `updated_at` are the server's, refused in this body as in every slice's — see `GET`'s notes for why. \n\n`400 validation_error` is where the two field rules land: an entry in `allowed_domains` must be lowercase, since a capitalised one can never match a lowercased address, and an entry in `allowed_origins` must be a bare scheme-host-port with no path, since a browser sends nothing longer in its `Origin` header. Each refuses at configuration time rather than failing silently later. \n\nThe merge is server-side against the stored row, so this write never disturbs the urls or mcp slice."
+    },
+    {
+      "method": "PUT",
+      "path": "/api/apps/:id/auth-config/urls",
+      "section": "apps",
+      "summary": "Replaces the three pages Fleetless's mails point at.",
+      "audience": "developer",
+      "auth": "developer",
+      "rateLimited": false,
+      "ownerTier": false,
+      "status": 200,
+      "params": [
+        {
+          "name": "id",
+          "description": "The app's uuid, as returned by `POST /api/apps` or listed by `GET /api/apps`."
+        }
+      ],
+      "query": null,
+      "request": "put-app-auth-urls-request",
+      "response": "app-auth-config",
+      "errors": [
+        "unauthorized",
+        "token_expired",
+        "token_revoked",
+        "invalid_uuid",
+        "validation_error",
+        "not_found"
+      ],
+      "transport": "http",
+      "notes": "**A replace, not a merge, and `.strict()`**: `invite_url`, `verify_url` and `reset_url` all arrive or the write is refused, so a client built against an older shape cannot silently clear a setting it does not know about. `oidc_callback_url` and `updated_at` are the server's, refused in this body as in every slice's — see `GET`'s notes for why. \n\n`400 validation_error` is where the field rule lands: a URL template must be https (or `http` on `localhost`) and carry its placeholder exactly once — a second occurrence leaves one literal in a mailed link, refused here rather than failing silently once the mail is sent. \n\nThe merge is server-side against the stored row, so this write never disturbs the registration or mcp slice."
+    },
+    {
+      "method": "PUT",
+      "path": "/api/apps/:id/auth-config/mcp",
       "section": "apps",
-      "summary": "Replaces the app's auth settings in one write.",
+      "summary": "Replaces the MCP switch and its login URL together.",
       "audience": "developer",
       "auth": "developer",
       "rateLimited": false,
@@ -1379,7 +1498,7 @@
         }
       ],
       "query": null,
-      "request": "put-app-auth-config-request",
+      "request": "put-app-auth-mcp-request",
       "response": "app-auth-config",
       "errors": [
         "unauthorized",
@@ -1390,7 +1509,7 @@
         "not_found"
       ],
       "transport": "http",
-      "notes": "**A replace, not a merge, and `.strict()`**: every field arrives or the write is refused, so a client built against an older shape cannot silently clear a setting it does not know about. `oidc_callback_url` and `updated_at` are refused in the body — a writable callback URL would let a caller point the return leg of an OIDC sign-in, which carries an authorization code, at a host they own. \n\n`400 validation_error` is where the three field rules land: a URL template must be https (or `http` on `localhost`) and carry its placeholder exactly once, an origin must be a bare scheme-host-port with no path, and a domain must be lowercase. Each refuses at configuration time because each would otherwise fail silently later — a second placeholder leaves one occurrence literal in a mailed link, an origin with a path can never equal a browser's `Origin` header, and a capitalised domain can never match a lowercased address."
+      "notes": "**A replace, not a merge, and `.strict()`**: `mcp_enabled` and `mcp_login_url` both arrive or the write is refused, so a client built against an older shape cannot silently clear a setting it does not know about. `oidc_callback_url` and `updated_at` are the server's, refused in this body as in every slice's — see `GET`'s notes for why. \n\n`mcp_login_url` answers to the same rule as the `urls` slice's three templates — https (or `http` on `localhost`), its placeholder exactly once — refused as `400 validation_error` rather than left to fail mid-OAuth, in a client's browser where no console screen is watching. \n\nThe merge is server-side against the stored row, so this write never disturbs the registration or urls slice."
     },
     {
       "method": "GET",
@@ -3052,6 +3171,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 +4646,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 +4833,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/app-deletion-summary.schema.json

@@ -0,0 +1,51 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "user_count": {
+      "type": "integer",
+      "minimum": 0,
+      "maximum": 9007199254740991,
+      "description": "App users deleted with the app. They are the developer's own customers, not Fleetless users, and exist in no other app."
+    },
+    "role_count": {
+      "type": "integer",
+      "minimum": 0,
+      "maximum": 9007199254740991,
+      "description": "Roles deleted with the app, each with its per-robot slug grants."
+    },
+    "server_key_count": {
+      "type": "integer",
+      "minimum": 0,
+      "maximum": 9007199254740991,
+      "description": "Server keys deleted with the app. A client still holding one is refused at its next request."
+    },
+    "invitation_count": {
+      "type": "integer",
+      "minimum": 0,
+      "maximum": 9007199254740991,
+      "description": "Outstanding invitations — unspent and unexpired — that will never be accepted."
+    },
+    "oidc_provider_count": {
+      "type": "integer",
+      "minimum": 0,
+      "maximum": 9007199254740991,
+      "description": "Identity providers configured for this app. The providers themselves are somebody else's; only this app's configuration of them goes."
+    },
+    "mail_template_count": {
+      "type": "integer",
+      "minimum": 0,
+      "maximum": 9007199254740991,
+      "description": "Custom mail templates, of at most three. A kind using the Fleetless default text is not counted — there is no row to lose."
+    }
+  },
+  "required": [
+    "user_count",
+    "role_count",
+    "server_key_count",
+    "invitation_count",
+    "oidc_provider_count",
+    "mail_template_count"
+  ],
+  "additionalProperties": false
+}

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
+}