@fleetless/contracts 1.2.0 → 3.0.0

package/CHANGELOG.md

@@ -5,7 +5,45 @@ follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the
 project uses [semantic versioning](https://semver.org/spec/v2.0.0.html) over
 the wire shapes.
 
-## [Unreleased]
+## [3.0.0] — 2026-09-22
+
+The protocol window carries over unchanged: `LATEST_BRIDGE_VERSION` is still `4.0.0`, and protocol 2 still sunsets 2026-12-21. Everything below is the REST surface.
+
+### Added
+
+- **Auth-config as three slices, not one document.** `putAppAuthRegistrationRequest` (`self_registration`, `allowed_domains`, `allowed_origins`), `putAppAuthUrlsRequest` (`invite_url`, `verify_url`, `reset_url`) and `putAppAuthMcpRequest` (`mcp_enabled`, `mcp_login_url`) are three `.strict()` replaces behind three new routes — `PUT /api/apps/:id/auth-config/registration`, `/urls` and `/mcp` — each merged server-side against the stored row, so a write to one slice can no longer clear a field it never showed. `GET /api/apps/:id/auth-config` is unchanged and still answers the whole document.
+- **A deletion preview and a delete.** `appDeletionSummary` — six independent counts (`user_count`, `role_count`, `server_key_count`, `invitation_count`, `oidc_provider_count`, `mail_template_count`), deliberately not summed — is what `GET /api/apps/:id/deletion-preview` (`200`) answers and what the `app.deleted` audit event carries, computed by the same function so the confirmation dialog and the eventual receipt cannot quietly disagree. `DELETE /api/apps/:id` (Owner tier, `204`) runs the cascade: an app's users, roles, server keys, invitations, OIDC configuration and mail templates all go; its robots do not, since they belong to the org, not the app. **No `force` parameter** — unlike the robot deletion pair this is modelled on, an app has no open-session state to force past, and inventing one would be a guess wearing a guard's clothes.
+
+### Removed
+
+- **`putAppAuthConfigRequest` and `PUT /api/apps/:id/auth-config`.** Replaced by the three slice requests and routes above — `PUT /api/apps/:id/auth-config/registration`, `PUT /api/apps/:id/auth-config/urls` and `PUT /api/apps/:id/auth-config/mcp`. This is the break that makes this release a major: a caller still sending the old whole-document body finds no route left to send it to.
+
+## [2.0.0] — 2026-09-22
+
+### Added
+
+- **A robot's own asset store.** `ROBOT_ASSET_STORE_BYTES` (1 GB) is what every robot gets, in `constants.json` too, so the bridge reads the same number the cloud enforces. `assetStoreRefusedDetails` carries `store_bytes`, `used_bytes` and `size_bytes` behind the `409 quota_exceeded` an upload with no room left answers, and rides on a `refused` entry in `assetFailure.details`. `assetListResponse` gains `store { bytes, used_bytes }`, so the page that lists a robot's assets can say how full it is without asking a second endpoint about the organisation.
+- **A full store is never a dead end.** `DELETE /api/robots/:id/assets` (Owner tier, `200`, `assetsClearResponse { deleted, bytes_freed }`) removes every URDF, mesh and texture of a robot and resets its store to zero, refusing `409 busy` while a sync is running; the next sync fills it again, and the bridge's own availability report is untouched. It is the blunt third answer alongside the URDF upload's exemption from the store gate and reconcile freeing what a new URDF no longer references.
+- **Two robot-detail routes.** `POST /api/robots/:id/token/rotate` (Owner tier, `201`, `robotTokenRotateResponse`) mints a new bridge token and stops the socket speaking on the old one; `CLOSE_TOKEN_ROTATED` (4005) is the code it closes with, distinct from `CLOSE_ROBOT_DELETED` because the robot very much still exists. `PUT /api/robots/:id/urdf/joint-state` (`jointStatePutRequest`/`jointStatePutResponse`) chooses the whole-message `sensor_msgs/msg/JointState` datapoint that moves the URDF's joints, or clears it; `assetListResponse.joint_state_slug` reads it back.
+- **A sync says what the store holds, not only what the robot claimed.** `assetSyncStatus` gains the required pair `stored` and `announced`: how many of the announced files — the URDF and every mesh URI the description references — the cloud's store actually holds — counted once after the robot's terminal frame, and `null` until then — against how many the robot announced. `state` alone was the bridge's terminal frame, so a stack whose object store answered `500` to every upload still reported `succeeded`; the cloud counts after that frame now, and a `succeeded` sync over an empty store ends `failed` with an `upload_failed` entry naming what is not there.
+- **`applyErrorKind` gains `low_bandwidth`.** A `low_bandwidth` section that does not resolve on the robot is reported under its own kind, slug `low_bandwidth`, instead of borrowing `datapoint` with slug `*`.
+
+### Changed
+
+- **Protocol 3 — the bridge decides its own low-bandwidth mode.** `cloudPing` carries `latency_ms` and `lag_ms`; the bridge sends `link_mode`; `bridge_state` gains `low_bandwidth`. `fleetless.yaml` gains an optional top-level `low_bandwidth` section and a per-datapoint `low_bandwidth: keep`; `LOW_BANDWIDTH_DEFAULTS` ships in `constants.json`. `datapointFrame` gains an optional `backfill` flag, so a replayed sample carrying its original capture time is not read as lag on the link. Protocol 2 is deprecated as of this release and served until 2026-12-21; its cloud adapter owes it two translations on the way in — it drops the pressure datapoints, and it rewrites an `asset_progress` failure of kind `too_large` (a kind protocol 3 no longer has) to `refused` with `details: null`.
+- **Required, not merely present.** `assetListResponse.store`, `assetListResponse.joint_state_slug` and `bridgeState.low_bandwidth` are required keys now, not optional-by-absence; `cloudPing.latency_ms` and `cloudPing.lag_ms` are required (nullable) on protocol 3. `LATEST_BRIDGE_VERSION` is `4.0.0`. Deploy the cloud before any consumer pins `2.0.0` — a response from a 0.2x cloud no longer parses these shapes.
+
+### Removed
+
+- **The per-file upload ceiling, and the organisation's storage dial.** `ASSET_UPLOAD_MAX_BYTES`, `assetTooLargeDetails`, the error code `asset_too_large` and the `assetFailureKind` member `too_large` are gone: nothing is refused for its own size any more, only for the robot's store. `orgQuotas.max_asset_storage_bytes` and its usage twin go with them — a robot has 1 GB; the organisation dial is gone.
+- **`assetKind` member `other`.** No producer ever sent it. The bridge classifies what it uploads and has only `urdf`, `mesh` and `texture` to choose from, so `other` was a slot for a file nobody had that every consumer still had to branch on.
+- **`bridge_pressure`.** The datapoint, `bridgePressure`, `PRESSURE_SLUG` and the reserved slug are gone; an app that read it reads `bridge_state.low_bandwidth` instead. This is the break that makes this release a major.
+
+## [1.3.0] — 2026-09-21
+
+### Added
+
+- **A protocol version window.** `PROTOCOL_VERSIONS` lists every protocol version with the bridge that introduced it and the date it was deprecated; `PROTOCOL_SUNSET_DAYS` (90) says how long a deprecated version is still served; `LATEST_BRIDGE_VERSION` names the newest bridge package. `protocolStatus()` and `minimumProtocolVersion()` answer for a date. All four reach `constants.json` for the bridge. `cloudHelloOk` may now carry `protocol { status, sunset_at }` and `bridge { latest_version }`. `robotListItem` gains `protocol_status`; `robotDetailResponse` gains `protocol_version` and `protocol`. All three are optional in this release, so a response from an older cloud still parses; a consumer reads their absence as `current`. Protocol 2 stays current; nothing previously valid becomes invalid.
 
 ## [1.2.0] — 2026-09-18
 

package/artifacts/constants.json

@@ -1,5 +1,22 @@
 {
   "AUDIT_RETENTION_DAYS": 90,
+  "PROTOCOL_VERSION": 3,
+  "PROTOCOL_VERSIONS": [
+    {
+      "version": 2,
+      "bridge_from": "3.0.0",
+      "deprecated_at": "2026-09-22"
+    },
+    {
+      "version": 3,
+      "bridge_from": "4.0.0",
+      "deprecated_at": null
+    }
+  ],
+  "PROTOCOL_SUNSET_DAYS": 90,
+  "LATEST_BRIDGE_VERSION": "4.0.0",
+  "CLOSE_ROBOT_DELETED": 4004,
+  "CLOSE_TOKEN_ROTATED": 4005,
   "ASSET_UPLOAD_HEADERS": {
     "kind": "x-fleetless-asset-kind",
     "name": "x-fleetless-asset-name",
@@ -7,7 +24,7 @@
     "syncId": "x-fleetless-sync-id",
     "size": "x-fleetless-asset-size"
   },
-  "ASSET_UPLOAD_MAX_BYTES": 67108864,
+  "ROBOT_ASSET_STORE_BYTES": 1000000000,
   "SNAPSHOT_HEADERS": {
     "ageMs": "x-fleetless-age-ms",
     "timestampMs": "x-fleetless-timestamp-ms",
@@ -18,7 +35,16 @@
   "ASSET_KINDS": [
     "urdf",
     "mesh",
-    "texture",
-    "other"
-  ]
+    "texture"
+  ],
+  "LOW_BANDWIDTH_DEFAULTS": {
+    "mode": "auto",
+    "enter_lag_ms": 2000,
+    "enter_after_s": 10,
+    "exit_lag_ms": 500,
+    "exit_after_s": 60,
+    "datapoint_max_hz": 1,
+    "camera": "reduce",
+    "camera_bitrate_kbps": 300
+  }
 }