@fleetless/contracts 1.1.0 → 2.0.0

package/dist/rest.js

@@ -38,6 +38,42 @@ export const createRobotResponse = z.object({
     robot,
     token: robotToken,
 });
+/**
+ * What a rotation hands back: the new token, once.
+ *
+ * The same shape as the creation response minus the robot, because nothing
+ * about the robot changed — only its credential. `createRobotResponse`'s own
+ * rule applies unchanged: the cloud stores a hash, so this is the only moment
+ * the raw token exists outside the caller's hands.
+ */
+export const robotTokenRotateResponse = z.object({
+    token: robotToken.meta({
+        description: 'The robot\'s new bridge token. Returned exactly once; the previous token stops working at the bridge\'s next hello.',
+    }),
+});
+/**
+ * Which datapoint drives the joints of this robot's URDF, or none.
+ *
+ * `null` is the clearing value, which is why `slug` is required rather than
+ * optional: an absent field and a cleared mapping would be the same request
+ * and mean different things, and the one a client sends by accident is the
+ * first.
+ *
+ * The cloud refuses a slug that is not a whole-message
+ * `sensor_msgs/msg/JointState` datapoint of the **published** document — a
+ * mapping that may point anywhere is a viewer animating a battery reading.
+ */
+export const jointStatePutRequest = z.object({
+    slug: slug.nullable().meta({
+        description: 'The datapoint to read joint positions from, or `null` to choose none. It must name a whole-message `sensor_msgs/msg/JointState` datapoint of the published configuration; anything else is a `validation_error` naming the rule.',
+    }),
+});
+/** The mapping as it now stands — the same field `GET /api/robots/:id/assets` reports. */
+export const jointStatePutResponse = z.object({
+    joint_state_slug: slug.nullable().meta({
+        description: 'The stored mapping after the call, `null` when none is chosen. The same value `assetListResponse.joint_state_slug` carries.',
+    }),
+});
 /**
  * How many things a robot exposes, per kind.
  *
@@ -47,18 +83,17 @@ export const createRobotResponse = z.object({
  *
  * **Counted from the published configuration, and excluding the built-ins.**
  * `GET /api/robots/:id/exposures` answers *which* slugs and prepends the
- * three built-in datapoints — `bridge_state`, `robot_details` and
- * `bridge_pressure` — as `builtin: true`; this answers *how many* and counts
- * only what somebody configured. So a robot with an empty published config
- * reports `datapoints: 0` here and three entries there. That is intentional,
- * and it is written on both sides so the disagreement is never mistaken for a
- * bug.
- *
- * The number is "three" and not "two" as of `bridge_pressure`; the cloud
- * builds that prefix from `PLANE_BUILTIN_DATAPOINTS` rather than a literal,
- * so a further built-in moves this count again. Read the count off that set,
- * not off this sentence, before filing the bug this comment exists to
- * prevent.
+ * built-in datapoints — `bridge_state` and `robot_details` — as
+ * `builtin: true`; this answers *how many* and counts only what somebody
+ * configured. So a robot with an empty published config reports
+ * `datapoints: 0` here and two entries there. That is intentional, and it is
+ * written on both sides so the disagreement is never mistaken for a bug.
+ *
+ * The number was "three" while `bridge_pressure` existed and is "two" since
+ * protocol 3 dropped it; the cloud builds that prefix from its own built-in
+ * set rather than a literal, so the next built-in moves this count again.
+ * Read the count off that set, not off this sentence, before filing the bug
+ * this comment exists to prevent.
  */
 export const exposureCounts = z.object({
     datapoints: z.number().int().nonnegative(),
@@ -67,12 +102,22 @@ export const exposureCounts = z.object({
     publishers: z.number().int().nonnegative(),
     cameras: z.number().int().nonnegative(),
 });
+/**
+ * Where a robot's bridge stands against the protocol window.
+ * `refused`: its last hello was refused for its version — it is offline
+ * until upgraded. Computed by the cloud from `protocol_version` and
+ * `last_hello_error`, never stored.
+ */
+export const protocolStatusValue = z.enum(['current', 'deprecated', 'refused']);
 /** A robot as listed, with its current built-in `bridge_state`. */
 export const robotListItem = z.object({
     ...robot.shape,
     bridge_state: bridgeState,
     /** Required, not optional: "we did not look" and "it exposes nothing" must not render the same. */
     exposes: exposureCounts,
+    protocol_status: protocolStatusValue.optional().meta({
+        description: 'Where this robot\'s bridge stands against the protocol window: `current`, `deprecated` (still served, sunset date on the detail), or `refused` (its last hello was refused for its version; offline until upgraded). Absent from a cloud older than 0.21.0; read absence as `current`.',
+    }),
 });
 export const robotListResponse = z.object({
     robots: z.array(robotListItem),
@@ -103,6 +148,18 @@ export const datapointValue = z.object({
 export const robotDetailResponse = z.object({
     ...robotListItem.shape,
     bridge_version: z.string().min(1).nullable(),
+    protocol_version: z.number().int().positive().nullable().optional().meta({
+        description: 'The protocol version the bridge announced in its last accepted hello; `null` before the first. Absent from a cloud older than 0.21.0.',
+    }),
+    protocol: z
+        .object({
+        status: protocolStatusValue.meta({ description: 'Same values as `protocol_status`.' }),
+        sunset_at: z.iso.date().nullable().meta({
+            description: 'ISO date the announced version stops being served; `null` when current or unknown.',
+        }),
+    })
+        .optional()
+        .meta({ description: 'The window verdict for `protocol_version`.' }),
     /**
      * Cleared (set back to null) by the next successful hello from this
      * robot's bridge — a warning that outlives the condition it warns
@@ -232,7 +289,7 @@ export const fetchTypesResponse = z.object({
 export const datapointDescriptor = z.object({
     slug: slug.meta({ description: 'The name a client reads this datapoint by.' }),
     builtin: z.boolean().meta({
-        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: z.string().nullable().meta({
         description: 'The unit the value carries **after** any scale and offset, shown beside the number so nobody has to guess whether `15` means percent, volts or minutes. `null` when the configuration names none.',
@@ -250,7 +307,7 @@ export const datapointDescriptor = z.object({
 });
 export const datapointListResponse = z.object({
     datapoints: z.array(datapointDescriptor).meta({
-        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.',
     }),
 });
 /**
@@ -801,22 +858,21 @@ export const ASSET_UPLOAD_HEADERS = {
     nameEncoded: 'x-fleetless-asset-name-encoded',
     syncId: 'x-fleetless-sync-id',
     /**
-     * **The announced size, and it is what makes `asset_too_large` reachable at
-     * all.**
+     * **The announced size, and it is what makes a structured store refusal
+     * reachable at all.**
      *
      * A server-side body limit is applied by the content-type parser, before the
-     * handler runs, so an oversized upload can only be refused with a bare
-     * `413` carrying neither `limit_bytes` nor `size_bytes` — and the structured
-     * refusal `assetTooLargeDetails` describes would have no producer.
+     * handler runs, so an upload with no room left can only be refused with a
+     * bare `413` carrying none of the three numbers — and the refusal
+     * `assetStoreRefusedDetails` describes would have no producer.
      *
-     * With the size announced in a header the refusal can be made where it can
-     * say something: before a byte is buffered, with both numbers. It also lets
-     * a producer discover its own limit without first reading the whole file
-     * into memory.
+     * With the size announced in a header the cloud can check `used + size`
+     * against `ROBOT_ASSET_STORE_BYTES` where it can still say something: before
+     * a byte is buffered, with all three numbers.
      *
      * The header is an **announcement, not a proof**: a sender can lie. The
-     * ceiling still applies to the body — this does not replace enforcement, it
-     * only makes the refusal answerable.
+     * store still applies to the bytes that arrive — this does not replace
+     * enforcement, it only makes the refusal answerable.
      */
     size: 'x-fleetless-asset-size',
 };
@@ -1233,22 +1289,25 @@ export const robotDeletionSummary = z.object({
     bytes_freed: z.number().int().nonnegative(),
     cameras: z.array(slug),
     /**
-     * Assets destroyed with the robot, and **`asset_bytes_freed` is what
-     * this org actually gets back** — not the sum of the assets' sizes.
+     * Assets destroyed with the robot, and **`asset_bytes_freed` is what the
+     * robot's own store gives back** — every distinct mesh or texture blob it
+     * holds, counted once, URDF excluded.
      *
-     * Storage is content-addressed, so a mesh two robots share survives the
-     * deletion of one of them and frees nothing. Reporting the total would tell
-     * a developer they are about to recover 400 MB and hand back 4, on the one
-     * screen whose entire justification is naming what an irreversible click
-     * destroys. Same reasoning that keeps `cameras` out of `slug_count`: this
-     * summary is read aloud to a human, and a number that is nearly right is
-     * worse here than an absent one.
+     * Storage is content-addressed, but the store and its 1 GB ceiling are now
+     * per robot: a blob another robot also references stays in the object
+     * store but is still credited here, because each robot's counter carries
+     * it regardless of what else points at the same bytes. Same reasoning that
+     * keeps `cameras` out of `slug_count`: this summary is read aloud to a
+     * human, and a number that is nearly right is worse here than an absent
+     * one.
      *
      * `asset_count` is the plain count of the robot's asset rows, all of which
      * do go away.
      */
     asset_count: z.number().int().nonnegative(),
-    asset_bytes_freed: z.number().int().nonnegative(),
+    asset_bytes_freed: z.number().int().nonnegative().meta({
+        description: 'What the robot\'s store gives back: every distinct mesh or texture blob it holds, counted once, URDF excluded; a blob another robot also references stays in the object store but is still credited here, because each robot\'s counter carries it.',
+    }),
     /**
      * How many rows of run history go with the robot — every recorded
      * invocation of one of its actions or services, up to
@@ -1460,31 +1519,6 @@ export const orgQuotas = z.object({
     max_retention_bytes: z.number().int().nonnegative(),
     max_retention_writes_per_minute: z.number().int().nonnegative(),
     max_realtime_connections: z.number().int().positive(),
-    /**
-     * Asset storage — **its own dial, not part of `max_retention_bytes`.** A
-     * sync grows storage in jumps and time series grow steadily; one dial would
-     * let the first crowd out the second, and the org that hit its limit would be
-     * told to look at the wrong thing.
-     *
-     * **Counted per distinct blob *this org references* — not per asset row, and
-     * not per object the platform stores on its behalf.** The two readings are
-     * indistinguishable from the number alone and a customer is entitled to know
-     * which one they are being charged for.
-     *
-     * Within an org, sharing is free: two robots referencing the same mesh cost
-     * one copy, which is what dedup means to a customer, and anything else
-     * charges an org twice for a fleet of identical robots — the normal case.
-     *
-     * **Across orgs, sharing is not free.** Storage stays globally
-     * content-addressed (one object per sha256; that efficiency is real), but
-     * accounting is per-org: an org is charged for each distinct blob it
-     * references and credited when its own last reference goes, whether or not
-     * the blob survives for somebody else. Global refcounting would make the
-     * first org to sync a blob pay for it forever while every later org stored it
-     * free — a quota evadable by anyone whose mesh someone else had already
-     * uploaded, and an org's own number would depend on who got there first.
-     */
-    max_asset_storage_bytes: z.number().int().nonnegative(),
 });
 /**
  * What an org is **actually using**, per quota.
@@ -1506,7 +1540,6 @@ export const orgQuotaUsageCounts = z.object({
     max_apps: z.number().int().nonnegative(),
     max_end_users: z.number().int().nonnegative(),
     max_retention_bytes: z.number().int().nonnegative(),
-    max_asset_storage_bytes: z.number().int().nonnegative(),
     max_retention_writes_per_minute: z.number().int().nonnegative(),
     max_realtime_connections: z.number().int().nonnegative(),
 }).partial();
@@ -1685,11 +1718,10 @@ export const USAGE_WINDOW_MAX_DAYS = 366;
 /**
  * The five things the meter records.
  *
- * Storage is two metrics and not one summed byte count, for
- * `org_quotas.max_asset_storage_bytes`'s own reason applied to billing: a sync
- * grows storage in jumps and time series grow steadily, and one number would
- * let the first crowd out the second on the invoice the same way it would on
- * the quota.
+ * Storage is two metrics and not one summed byte count: a sync grows storage
+ * in jumps and time series grow steadily, and one number would let the first
+ * crowd out the second on the invoice. The org that outgrew its bill would be
+ * told to look at the wrong thing.
  */
 export const usageMetric = z.enum(['api_calls', 'live_session_ms', 'retention_bytes', 'asset_bytes', 'robot_online_ms']);
 /**

package/dist/routes.js

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: Apache-2.0
 import { appListResponse, createAppRequest, createServerKeyResponse, app as appSchema, role, roleListResponse, rolePermissions, serverKeyListResponse, updateAppRequest, } from './apps.js';
 import { alertListResponse, orgAlertsQuery, orgFiringAlertsResponse } from './alerts.js';
-import { asset, assetListResponse, assetSyncRequest, assetSyncResponse, assetSyncStatus, missingAssetQuery } from './assets.js';
+import { asset, assetListResponse, assetsClearResponse, assetSyncRequest, assetSyncResponse, assetSyncStatus, missingAssetQuery } from './assets.js';
 import { auditListResponse, auditQuery } from './audit.js';
 import { CLIENT_OIDC_CALLBACK_PATH, clientAcceptInvitationRequest, clientIdentity, clientLoginRequest, clientLogoutRequest, clientMcpInteraction, clientMcpInteractionDecisionResponse, clientOidcCallbackQuery, clientOidcExchangeRequest, clientOidcStartQuery, clientPasswordResetConfirmRequest, clientPasswordResetRequest, clientProviderListQuery, clientProviderListResponse, clientRefreshRequest, clientRegisterRequest, clientResendVerificationRequest, clientVerifyEmailRequest, mcpConsentGrantListResponse, } from './client-auth.js';
 import { clientRobotListResponse } from './client-robots.js';
@@ -10,7 +10,7 @@ import { acceptTeamInviteRequest, authMeResponse, createTeamInviteRequest, fleet
 import { jobRunListResponse, jobRunQuery, jobRunSummary, jobRunSummaryQuery } from './jobs.js';
 import { MCP_APP_PATHS, mcpRobotDatasheet, mcpRolePreviewResponse } from './mcp.js';
 import { authorizationServerMetadata, dynamicClientRegistrationRequest, dynamicClientRegistrationResponse, oauthAuthorizeQuery, oauthRedirectResponse, oauthTokenRequest, oauthTokenResponse, protectedResourceMetadata, } from './oauth.js';
-import { cameraListResponse, cancelRequest, configDraftResponse, configVersionResponse, configVersionsResponse, createRobotRequest, createRobotResponse, datapointListResponse, datapointValue, exposureListResponse, fetchTypesRequest, fetchTypesResponse, historyQuery, historyResponse, introspectionResponse, invokeOrServiceResponse, invokeRequest, jobResponse, liveSessionResponse, orgHealthQuery, orgLatencyQuery, orgLatencyResponse, orgQuotaUsage, orgUsageQuery, orgUsageResponse, patchRobotRequest, patchRobotResponse, publishConfigResponse, publishRequest, putConfigDraftRequest, putRobotDetailsRequest, putRobotDetailsResponse, releaseLiveQuery, renameSlugRequest, renameSlugResponse, robotDeleteQuery, resourceHealthListResponse, robotDeletionSummary, robotDetailResponse, robotJobsResponse, robotListResponse, slugUsageResponse, snapshotMetaResponse, typesResponse, } from './rest.js';
+import { cameraListResponse, cancelRequest, configDraftResponse, configVersionResponse, configVersionsResponse, createRobotRequest, createRobotResponse, datapointListResponse, datapointValue, exposureListResponse, fetchTypesRequest, fetchTypesResponse, historyQuery, historyResponse, introspectionResponse, invokeOrServiceResponse, invokeRequest, jobResponse, liveSessionResponse, orgHealthQuery, orgLatencyQuery, orgLatencyResponse, orgQuotaUsage, orgUsageQuery, orgUsageResponse, patchRobotRequest, patchRobotResponse, publishConfigResponse, publishRequest, putConfigDraftRequest, putRobotDetailsRequest, putRobotDetailsResponse, robotTokenRotateResponse, jointStatePutRequest, jointStatePutResponse, releaseLiveQuery, renameSlugRequest, renameSlugResponse, robotDeleteQuery, resourceHealthListResponse, robotDeletionSummary, robotDetailResponse, robotJobsResponse, robotListResponse, slugUsageResponse, snapshotMetaResponse, typesResponse, } from './rest.js';
 export const ROUTE_SECTIONS = [
     { id: 'health', title: 'Health' },
     { id: 'developer-auth', title: 'Developer auth' },
@@ -948,8 +948,8 @@ export const ROUTES = [
             'caller earned. The shape is deliberately **not** strict, which is the schema agreeing with §3.1 rather than a gap in it — a conforming ' +
             'client sends `client_uri`, `logo_uri` and `software_id`, and both the schema and the server ignore them. `client_name` and ' +
             '`redirect_uris` are the two fields read; `grant_types`, `response_types` and `scope` are accepted and ignored. What comes back is what ' +
-            'was actually granted, which §3.2.1 allows a server to substitute — this authorization server issues `authorization_code` only, so a ' +
-            'client that asked for `refresh_token` is registered and told plainly that it did not get one. The registration carries a TTL. Refusals ' +
+            'was actually granted, which §3.2.1 allows a server to substitute — this authorization server grants `authorization_code` and ' +
+            '`refresh_token` to every registration. The registration carries a TTL. Refusals ' +
             'are `oauthError`; the rate limiter answers `apiError`.',
     },
     {
@@ -1023,10 +1023,11 @@ export const ROUTES = [
         audience: 'client', auth: 'none', rateLimited: false, ownerTier: false, status: 200,
         params: [], query: null, request: oauthTokenRequest, response: oauthTokenResponse,
         errors: [], transport: 'http',
-        notes: 'Only `authorization_code` is supported — there is no refresh grant here, so a session ends when its token expires and the client signs ' +
-            'in again. Refusals are RFC 6749 §5.2\'s `oauthError`, so this route emits none of the codes in this reference. The response carries no ' +
-            '`refresh_token`; the shape is the same `oauthTokenResponse` the app flow answers, whose refresh field is optional. The code is ' +
-            'single-use, PKCE-verified, and its `resource` must match the audience it was authorized for.',
+        notes: '`authorization_code` mints an `mcp_session` access token bound to the central resource and a refresh token; `refresh_token` rotates that pair, ' +
+            'and the presented refresh token is consumed — a second presentation revokes the session, as on `/api/auth/refresh`. The refresh token lives ninety days ' +
+            'from its last use and is bound to the `client_id` it was issued to. A refresh re-reads the Fleetless user, so a removed account cannot refresh. ' +
+            'Refusals are RFC 6749 §5.2\'s `oauthError`, so this route emits none of the codes in this reference. The code is single-use, PKCE-verified, and its ' +
+            '`resource` must match the audience it was authorized for; a `resource` on a refresh must match the session\'s audience, and is checked before the token is consumed.',
     },
     /* ------------------------------- developer auth (the console\'s OAuth portal) */
     {
@@ -1248,8 +1249,8 @@ export const ROUTES = [
             'accepts rather than what it parses, for the reason that row gives: §3.2.2 needs two distinguishable refusals and one `safeParse` ' +
             'failure offers one. `client_name` and `redirect_uris` are read; `grant_types`, `response_types` and `scope` are accepted and ignored, ' +
             'and what comes back is what was actually ' +
-            'granted, which §3.2.1 allows — `authorization_code` only, so a client that asked for `refresh_token` is registered and told plainly ' +
-            'that it did not get one. The registration carries a TTL. \n\n**The registration is scoped to this app.** A `client_id` minted here ' +
+            'granted, which §3.2.1 allows — this authorization server grants `authorization_code` and `refresh_token` to every registration. ' +
+            'The registration carries a TTL. \n\n**The registration is scoped to this app.** A `client_id` minted here ' +
             'authorizes at this app\'s endpoint and nowhere else, so a client registered against one app cannot walk into another\'s authorize with ' +
             'it, and a developer who switches MCP off is not left with strangers\' registrations valid somewhere adjacent. \n\nRefusals are ' +
             '`oauthError`; the rate limiter and `404 not_found` answer `apiError`. That `404` covers an unknown identifier **and** an app with the ' +
@@ -1288,9 +1289,8 @@ export const ROUTES = [
         audience: 'client', auth: 'none', rateLimited: false, ownerTier: false, status: 200,
         params: [APP_IDENTIFIER], query: null, request: oauthTokenRequest, response: oauthTokenResponse,
         errors: [], transport: 'http',
-        notes: 'Only `authorization_code`, PKCE-verified and single-use. There is no refresh grant here either, so a session ends when its token ' +
-            'expires and the client signs in again; the shape is the same `oauthTokenResponse` the central endpoint answers, whose refresh field is ' +
-            'optional and stays empty. **The `aud` is this app\'s endpoint URL on the canonical public base**, and the code\'s `resource` must match ' +
+        notes: '`authorization_code`, PKCE-verified and single-use, and `refresh_token`, which rotates the pair the exchange minted; the refresh token lives ninety days from its last use, is bound to its client and to this app, and a refresh re-reads the app user\'s status and their standing consent to the client, so a block or a withdrawn consent ends the session at its next refresh at the latest. ' +
+            '**The `aud` is this app\'s endpoint URL on the canonical public base**, and the code\'s `resource` must match ' +
             'it — that is the whole of what stops a token minted for one app being spent at another\'s endpoint. \n\n**Every refusal is RFC 6749 ' +
             '§5.2\'s `oauthError`, so this route emits none of the codes in this reference — including the ones about the app.** An unknown ' +
             'identifier and a switched-off app are `invalid_client` here, not the `404` and `403` the authorize route beside it answers. The ' +
@@ -1664,6 +1664,40 @@ export const ROUTES = [
             '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: robotTokenRotateResponse,
+        errors: [...DEVELOPER_GUARD, '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: jointStatePutRequest, response: jointStatePutResponse,
+        errors: [...DEVELOPER_GUARD, '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', section: 'robots',
         summary: "Lists the org's robots with their connection state and exposure counts.",
@@ -2233,6 +2267,20 @@ export const ROUTES = [
         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: assetsClearResponse,
+        errors: [...CLIENT_GUARD, '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.',
+    },
     /* ------------------------------------------------ org (quotas and fleet reads) */
     {
         method: 'GET', path: '/api/org/quotas', section: 'org',
@@ -2306,15 +2354,16 @@ export const ROUTES = [
         summary: 'Takes one asset file from a robot during a sync.',
         audience: 'internal', auth: 'robot_upload', rateLimited: false, ownerTier: false, status: 201,
         params: [], query: null, request: null, response: asset,
-        errors: ['unauthorized', 'rate_limited', 'asset_too_large', 'validation_error', 'not_found', 'quota_exceeded', 'bad_request'], transport: 'http',
+        errors: ['unauthorized', 'rate_limited', '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.',
+            '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.',
     },
     /* ------------------------------------ realtime and bridge transports */
     {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fleetless/contracts",
-  "version": "1.1.0",
+  "version": "2.0.0",
   "description": "Fleetless wire contracts: the bridge-cloud protocol, the REST API schemas and the error codes, as zod schemas with generated JSON Schema and OpenAPI artifacts.",
   "license": "Apache-2.0",
   "author": "Dehne Robotik GmbH",