@fleetless/contracts 6.0.0-next.1 → 6.0.0-next.3

package/CHANGELOG.md

@@ -90,6 +90,18 @@ version.
   `acceptTeamInviteRequest` takes an optional `display_name` and no
   password. The default invitation mail no longer asks the invitee to
   choose a password.
+- **`appInvitation.accept_url` is never `null`**: an app with no
+  `invite_url` gets the hosted invitation page's link.
+- **`appMailTemplateListResponse.templates` holds up to four** (was three),
+  with `login_code`.
+- **The portal's identify step mails a sign-in code** (`POST
+  /console/oauth/identify`, `POST /mcp/oauth/identify`) instead of handing
+  back a password step, and answers the same for every address.
+- **A password reset and a password change are refused with `403
+  method_not_allowed`** while the app has the password method off — `POST
+  /api/client/password/reset`, `…/password/reset/confirm`,
+  `…/password/change` and the developer's `POST
+  /api/apps/:id/users/:userId/reset-password`.
 
 ### Removed
 
@@ -102,11 +114,49 @@ version.
   /console/oauth/login` and `POST /mcp/oauth/login`. Fleetless users sign
   in by emailed code or passkey; the portal sign-up is the one way to
   create an organisation. `passwordChangeRequest` stays, for `POST
-  /api/client/password/change`. Together with the newly required fields
-  above (`appUser.two_factor`, `org.require_two_factor`,
+  /api/client/password/change`. The newly required fields above
+  (`appUser.two_factor`, `org.require_two_factor`,
   `fleetlessUser.two_factor`, `clientIdentity.two_factor_enabled`,
   `clientProviderListResponse.sign_in_methods`) and the narrowed `mcp`
-  slice, this is why the release is a major.
+  slice break existing readers as well.
+
+## [5.3.0] — 2026-10-02
+
+### Added
+
+- **`feedbackRequest` and `feedbackResponse`** (`FeedbackRequest`,
+  `FeedbackResponse`) for the new `POST /api/feedback`: a developer's
+  message to the people who build Fleetless, `{ kind, message, page }` with
+  `kind` one of `FEEDBACK_KINDS` (`idea`, `problem`, `question`, `other`), a
+  trimmed message of at most `FEEDBACK_MESSAGE_MAX` (5000) characters and
+  the console path it was sent from. The route answers `202` with
+  `{ id, mail }`: the message is stored before any mail is tried, so `mail`
+  (`sent`, `failed`, `not_configured`) never means it was lost. Rate
+  limited to 10 per developer per hour. Published as the artifacts
+  `feedback-request` and `feedback-response`.
+- **`jobActor.name`**: the person's display name when the job started,
+  required and nullable — `null` for a server key, a person without a name
+  and runs recorded before this version; show `label` then. `jobActor`
+  stays non-strict, so a consumer on 5.2.0 strips the new key rather than
+  refusing the run. Changes the artifacts `job-actor`, `job-run` and
+  `job-run-list-response`.
+- **`roleRenameRequest`, `roleDeleteQuery` and `roleInUseDetails`**
+  (`RoleRenameRequest`, `RoleDeleteQuery`, `RoleInUseDetails`) for the new
+  `PATCH` and `DELETE /api/apps/:id/roles/:roleId`: rename a role
+  (`409 role_name_taken` on a clash), or delete it, moving its app users,
+  pending invitations and default-role status to `move_to`. Without
+  `move_to` a held role answers `409 role_in_use` with
+  `{ users, invitations, is_default }`; the app's only role answers
+  `409 last_role`. The three codes join `ERROR_CODES`. `role.builtin` no
+  longer says built-in roles cannot be renamed or deleted, and the create
+  route's note now states the 60-character limit `role.name` always had.
+  Published as the artifacts `role-rename-request`, `role-delete-query`
+  and `role-in-use-details`.
+- **`auditQuery.target_id`**: only the events about one target — for a
+  robot also those that name it in `details.robot_id`, so a robot's log
+  includes what was started on it. A string, since target ids are not all
+  uuids. `GET /api/audit/export` takes it too. Changes the artifact
+  `audit-query`.
 
 ## [5.2.0] — 2026-09-30
 

package/artifacts/openapi.json

@@ -732,6 +732,17 @@
               "maxLength": 40
             }
           },
+          {
+            "name": "target_id",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "description": "Events whose target is this id; for a robot also the events that name it in `details.robot_id` (`action.invoked`, `service.called`, …), so a robot's events include what was started on it.",
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 200
+            }
+          },
           {
             "name": "from_ms",
             "in": "query",
@@ -883,6 +894,17 @@
               "maxLength": 40
             }
           },
+          {
+            "name": "target_id",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "description": "Events whose target is this id; for a robot also the events that name it in `details.robot_id` (`action.invoked`, `service.called`, …), so a robot's events include what was started on it.",
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 200
+            }
+          },
           {
             "name": "from_ms",
             "in": "query",
@@ -1265,7 +1287,7 @@
             }
           }
         },
-        "description": "The body is `{ \"name\": string }` — non-empty, trimmed, at most 120 characters — and is deliberately not a contract shape: contracts define the `role` this answers with, not this one trivial request. **The answer is a bare `role`, not an envelope**, unlike the listing beside it."
+        "description": "The body is `{ \"name\": string }` — non-empty, trimmed, at most 60 characters as on `role.name` — and is deliberately not a contract shape: contracts define the `role` this answers with, not this one trivial request. **The answer is a bare `role`, not an envelope**, unlike the listing beside it."
       },
       "get": {
         "operationId": "get_api_apps_id_roles",
@@ -1492,6 +1514,132 @@
         "description": "Built by the same builder the MCP server's own `robot_describe` uses, so the two cannot drift. It answers what the role *would* be offered and consults nothing about any user's actual MCP entitlement. A robot the role grants nothing on still appears, with an empty `exposures` — dropping it would read as \"not attached\", which is a different fact."
       }
     },
+    "/api/apps/{id}/roles/{roleId}": {
+      "patch": {
+        "operationId": "patch_api_apps_id_roles_roleId",
+        "summary": "Renames a role; its users keep it.",
+        "tags": [
+          "apps"
+        ],
+        "security": [
+          {
+            "developerSession": []
+          }
+        ],
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "description": "The app's uuid, as returned by `POST /api/apps` or listed by `GET /api/apps`.",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "roleId",
+            "in": "path",
+            "required": true,
+            "description": "The role's uuid, from `GET /api/apps/:id/roles`; a role of another app answers `404`.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/role"
+                }
+              }
+            }
+          },
+          "default": {
+            "description": "An error envelope. Codes this route is known to answer: `unauthorized`, `token_expired`, `token_revoked`, `invalid_uuid`, `not_found`, `validation_error`, `role_name_taken`.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/api-error"
+                }
+              }
+            }
+          }
+        },
+        "description": "Names are unique per app, compared exactly as stored after trimming. Built-in roles can be renamed.",
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/role-rename-request"
+              }
+            }
+          }
+        }
+      },
+      "delete": {
+        "operationId": "delete_api_apps_id_roles_roleId",
+        "summary": "Deletes a role, moving its users, pending invitations and default-role status to another role.",
+        "tags": [
+          "apps"
+        ],
+        "security": [
+          {
+            "developerSession": []
+          }
+        ],
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "description": "The app's uuid, as returned by `POST /api/apps` or listed by `GET /api/apps`.",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "roleId",
+            "in": "path",
+            "required": true,
+            "description": "The role's uuid, from `GET /api/apps/:id/roles`; a role of another app answers `404`.",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "move_to",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "description": "Another role of the same app that takes over the deleted role's app users, pending invitations and, when it applies, the app's default. The role itself or a role of another app answers `400 validation_error`.",
+              "type": "string",
+              "format": "uuid",
+              "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
+            }
+          }
+        ],
+        "responses": {
+          "204": {
+            "description": "Success."
+          },
+          "default": {
+            "description": "An error envelope. Codes this route is known to answer: `unauthorized`, `token_expired`, `token_revoked`, `invalid_uuid`, `not_found`, `validation_error`, `role_in_use`, `last_role`.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/api-error"
+                }
+              }
+            }
+          }
+        },
+        "description": "Without `move_to`, a role that app users or pending invitations hold, or that is the app's default, answers `409 role_in_use` with `{ users, invitations, is_default }`. With `move_to` — another role of the same app, else `400 validation_error` — one transaction moves `app_users.role_id`, pending invitations and `default_role_id`, then deletes the role and its permissions. The app's only role answers `409 last_role`. Built-in roles can be deleted like any other."
+      }
+    },
     "/api/apps/{id}/server-keys": {
       "post": {
         "operationId": "post_api_apps_id_server_keys",
@@ -2011,7 +2159,7 @@
             }
           },
           "default": {
-            "description": "An error envelope. Codes this route is known to answer: `unauthorized`, `token_expired`, `token_revoked`, `invalid_uuid`, `not_found`, `target_state_conflict`.",
+            "description": "An error envelope. Codes this route is known to answer: `unauthorized`, `token_expired`, `token_revoked`, `invalid_uuid`, `not_found`, `target_state_conflict`, `method_not_allowed`.",
             "content": {
               "application/json": {
                 "schema": {
@@ -2021,7 +2169,7 @@
             }
           }
         },
-        "description": "The support door beside `POST /api/client/password/reset`: the same one-hour token and the same link, triggered by a developer for a user who asked them rather than the form. **No enumeration discipline applies** — the caller is authenticated into the app and can read the user list — so this one answers what actually happened: `{ \"mail\": mailStatus }`, where `not_configured` is a deployment without a mailer and `failed` is the state worth somebody's attention. The link points at the app's `reset_url`, or at the hosted reset page when the app has configured none. `409 target_state_conflict` names `password` with rule `not_set` for an account that has none — an OIDC-only app user, whom a reset link would hand a second, quieter door — and `status` with rule `blocked` for a blocked one, since `POST /api/client/password/reset` mails a blocked account nothing and the two doors may not disagree. Setting the password directly is deliberately not offered; a developer who could would hold their customers' credentials."
+        "description": "The support door beside `POST /api/client/password/reset`, refused like it with `403 method_not_allowed` while the app has the password method off: the same one-hour token and the same link, triggered by a developer for a user who asked them rather than the form. **No enumeration discipline applies** — the caller is authenticated into the app and can read the user list — so this one answers what actually happened: `{ \"mail\": mailStatus }`, where `not_configured` is a deployment without a mailer and `failed` is the state worth somebody's attention. The link points at the app's `reset_url`, or at the hosted reset page when the app has configured none. `409 target_state_conflict` names `password` with rule `not_set` for an account that has none — an OIDC-only app user, whom a reset link would hand a second, quieter door — and `status` with rule `blocked` for a blocked one, since `POST /api/client/password/reset` mails a blocked account nothing and the two doors may not disagree. Setting the password directly is deliberately not offered; a developer who could would hold their customers' credentials."
       }
     },
     "/api/apps/{id}/users/{userId}/two-factor": {
@@ -3181,7 +3329,7 @@
             "name": "kind",
             "in": "path",
             "required": true,
-            "description": "Which of the three mails this template replaces — a `mailTemplateKind`: `invite`, `verify` or `reset`.",
+            "description": "Which of the four mails this template replaces — a `mailTemplateKind`: `invite`, `verify`, `reset` or `login_code`.",
             "schema": {
               "type": "string"
             }
@@ -3236,7 +3384,7 @@
             "name": "kind",
             "in": "path",
             "required": true,
-            "description": "Which of the three mails this template replaces — a `mailTemplateKind`: `invite`, `verify` or `reset`.",
+            "description": "Which of the four mails this template replaces — a `mailTemplateKind`: `invite`, `verify`, `reset` or `login_code`.",
             "schema": {
               "type": "string"
             }
@@ -3301,7 +3449,7 @@
             "name": "kind",
             "in": "path",
             "required": true,
-            "description": "Which of the three mails this template replaces — a `mailTemplateKind`: `invite`, `verify` or `reset`.",
+            "description": "Which of the four mails this template replaces — a `mailTemplateKind`: `invite`, `verify`, `reset` or `login_code`.",
             "schema": {
               "type": "string"
             }
@@ -3351,7 +3499,7 @@
             "name": "kind",
             "in": "path",
             "required": true,
-            "description": "Which of the three mails this template replaces — a `mailTemplateKind`: `invite`, `verify` or `reset`.",
+            "description": "Which of the four mails this template replaces — a `mailTemplateKind`: `invite`, `verify`, `reset` or `login_code`.",
             "schema": {
               "type": "string"
             }
@@ -3418,7 +3566,7 @@
             "name": "kind",
             "in": "path",
             "required": true,
-            "description": "Which of the three mails this template replaces — a `mailTemplateKind`: `invite`, `verify` or `reset`.",
+            "description": "Which of the four mails this template replaces — a `mailTemplateKind`: `invite`, `verify`, `reset` or `login_code`.",
             "schema": {
               "type": "string"
             }
@@ -4767,7 +4915,7 @@
             }
           }
         },
-        "description": "**`202` and an empty body for every request the policy allows**, in status, body and timing, whether or not the address names an active account of this app — a decoy like `POST /api/client/resend-verification`, so this is no enumeration oracle. A mail goes out only for an account that may sign in. The code is six digits, valid ten minutes, takes five wrong attempts, and a new request expires the previous one for the same address; a request within sixty seconds of the last sends no second mail. The address is trimmed and compared case-insensitively. `404 not_found` is the **app identifier**, never the address; `403 method_not_allowed` when the app has the email-code method off. Limited per app, address and IP, so it cannot be used to mail somebody repeatedly.",
+        "description": "**`202` and an empty body for every request the policy allows**, in status, body and timing, whether or not the address names an active account of this app — a decoy like `POST /api/client/resend-verification`, so this is no enumeration oracle. A mail goes out for an `active` account and for one still `pending_verification` — spending the code proves the address, as the verification link would — and never for a `blocked` one or an unknown address. The code is six digits, valid ten minutes, takes five wrong attempts, and a new request expires the previous one for the same address; a request within sixty seconds of the last sends no second mail. The address is trimmed and compared case-insensitively. `404 not_found` is the **app identifier**, never the address; `403 method_not_allowed` when the app has the email-code method off. Limited per app, address and IP, so it cannot be used to mail somebody repeatedly.",
         "requestBody": {
           "required": true,
           "content": {
@@ -4956,7 +5104,7 @@
             "description": "Success."
           },
           "default": {
-            "description": "An error envelope. Codes this route is known to answer: `rate_limited`, `validation_error`, `not_found`.",
+            "description": "An error envelope. Codes this route is known to answer: `rate_limited`, `validation_error`, `not_found`, `method_not_allowed`.",
             "content": {
               "application/json": {
                 "schema": {
@@ -4966,7 +5114,7 @@
             }
           }
         },
-        "description": "The pair of app identifier and address is the identifier: an app user's address is unique only within their app. Status, body and timing are identical for a known and an unknown address. An account with no password — one created through an identity provider — is mailed nothing and still answers `202`. `404 not_found` is the **app identifier**, never the address. The link points at the app's `reset_url`, or at the hosted reset page when the app has configured none.",
+        "description": "The pair of app identifier and address is the identifier: an app user's address is unique only within their app. `403 method_not_allowed` when the app has the password method off — a reset link whose confirmation would be refused is not mailed; the code names the app's policy, not a person. Status, body and timing are identical for a known and an unknown address. An account with no password — one created through an identity provider — is mailed nothing and still answers `202`. `404 not_found` is the **app identifier**, never the address. The link points at the app's `reset_url`, or at the hosted reset page when the app has configured none.",
         "requestBody": {
           "required": true,
           "content": {
@@ -5179,7 +5327,7 @@
             }
           },
           "default": {
-            "description": "An error envelope. Codes this route is known to answer: `unauthorized`, `token_expired`, `token_revoked`, `forbidden`, `validation_error`, `invalid_credentials`, `target_state_conflict`.",
+            "description": "An error envelope. Codes this route is known to answer: `unauthorized`, `token_expired`, `token_revoked`, `forbidden`, `validation_error`, `invalid_credentials`, `target_state_conflict`, `method_not_allowed`.",
             "content": {
               "application/json": {
                 "schema": {
@@ -5189,7 +5337,7 @@
             }
           }
         },
-        "description": "The guard admits all three caller kinds, but a password belongs to an app user specifically — a developer bearer or a server key reaching this is `401 unauthorized`. Every other session of the account ends; the answer is the replacement pair, so the tab that made the change stays signed in. An app user belongs to one app, so \"every session\" is this app's. An account that has **no password** — an OIDC-only app user, which the schema admits — answers `409 target_state_conflict` naming the `password` field with rule `not_set`, not `401`: the session is live and the token is fine, it is the account that has nothing to change, and telling such a caller to sign in again sends them round a loop that ends here.",
+        "description": "`403 method_not_allowed` when the app has the password method off: a stored password stays stored but is not in use, so it is not changed either. The guard admits all three caller kinds, but a password belongs to an app user specifically — a developer bearer or a server key reaching this is `401 unauthorized`. Every other session of the account ends; the answer is the replacement pair, so the tab that made the change stays signed in. An app user belongs to one app, so \"every session\" is this app's. An account that has **no password** — an OIDC-only app user, which the schema admits — answers `409 target_state_conflict` naming the `password` field with rule `not_set`, not `401`: the session is live and the token is fine, it is the account that has nothing to change, and telling such a caller to sign in again sends them round a loop that ends here.",
         "requestBody": {
           "required": true,
           "content": {
@@ -5326,9 +5474,9 @@
             }
           }
         },
-        "description": "**Two ways in, decided in the handler.** During sign-in the body carries the `two_factor_setup_required` challenge, and that is the credential; from the app's own account settings the app user's bearer is, with no challenge. Neither is `401 unauthorized`, and a dead challenge is `410 token_spent`. `409 target_state_conflict` names `two_factor` with rule `off` when the app's policy is `off`. The secret is not in use until `POST /api/client/two-factor/setup/confirm` accepts a code from it; a second call replaces a pending secret, and an account that already has an authenticator keeps it until the new one is confirmed.",
+        "description": "**Two ways in, decided in the handler.** During sign-in the body carries the `two_factor_setup_required` challenge, and that is the credential; from the app's own account settings the app user's bearer is, with no challenge and an empty or missing body. Neither is `401 unauthorized`, and a dead challenge is `410 token_spent`. `409 target_state_conflict` names `two_factor` with rule `off` when the app's policy is `off`. The secret is not in use until `POST /api/client/two-factor/setup/confirm` accepts a code from it; a second call replaces a pending secret, and an account that already has an authenticator keeps it until the new one is confirmed.",
         "requestBody": {
-          "required": true,
+          "required": false,
           "content": {
             "application/json": {
               "schema": {
@@ -9254,6 +9402,54 @@
         },
         "description": "A window longer than `USAGE_WINDOW_MAX_DAYS` is refused naming the field, not silently capped: a caller who asked for more than the platform will answer is owed a refusal, not a shorter answer they will mistake for the whole picture. `from_day <= to_day` is a cross-field rule no JSON Schema can express and is enforced here. The window is echoed back."
       }
+    },
+    "/api/feedback": {
+      "post": {
+        "operationId": "post_api_feedback",
+        "summary": "Sends a message from a developer to the people who build Fleetless.",
+        "tags": [
+          "org"
+        ],
+        "security": [
+          {
+            "developerSession": []
+          }
+        ],
+        "parameters": [],
+        "responses": {
+          "202": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/feedback-response"
+                }
+              }
+            }
+          },
+          "default": {
+            "description": "An error envelope. Codes this route is known to answer: `unauthorized`, `token_expired`, `token_revoked`, `validation_error`, `rate_limited`.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/api-error"
+                }
+              }
+            }
+          }
+        },
+        "description": "The message is stored before any mail is tried, so `202` means it is kept whatever `mail` says: `sent`, `failed`, or `not_configured` when this cloud has no feedback address. At most 10 messages per developer per hour; the 11th answers `429 rate_limited` with `retry_after_ms`. Replies come by mail, to the sender's address.",
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/feedback-request"
+              }
+            }
+          }
+        }
+      }
     }
   },
   "components": {
@@ -9853,17 +10049,10 @@
             "description": "When the token stops working. Seven days from issue; an expired token answers exactly as an unknown one does."
           },
           "accept_url": {
-            "anyOf": [
-              {
-                "type": "string",
-                "maxLength": 500,
-                "format": "uri"
-              },
-              {
-                "type": "null"
-              }
-            ],
-            "description": "The link to give the invitee: the app's `invite_url` with the token substituted for `{token}`, or the Fleetless-hosted invitation page when the app has configured none. Bounded like every other URL that gets mailed, logged and rendered. Nullable for readers of the earlier shape; the cloud always fills it."
+            "type": "string",
+            "maxLength": 500,
+            "format": "uri",
+            "description": "The link to give the invitee: the app's `invite_url` with the token substituted for `{token}`, or the Fleetless-hosted invitation page when the app has configured none. Bounded like every other URL that gets mailed, logged and rendered."
           },
           "mail": {
             "type": "string",
@@ -15511,6 +15700,65 @@
         ],
         "additionalProperties": false
       },
+      "feedback-request": {
+        "type": "object",
+        "properties": {
+          "kind": {
+            "type": "string",
+            "enum": [
+              "idea",
+              "problem",
+              "question",
+              "other"
+            ],
+            "description": "What the message is: an `idea`, a `problem`, a `question` or `other`. It only sorts the inbox; it changes nothing about how the message is handled."
+          },
+          "message": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 5000,
+            "description": "What the developer wrote, trimmed. At most 5000 characters; a message that is only whitespace is refused."
+          },
+          "page": {
+            "type": "string",
+            "maxLength": 512,
+            "pattern": "^\\/.*",
+            "description": "The console path the message was sent from, e.g. `/robots/:id/jobs` with its real id. A path, never a full URL, so no host and no query string reach the inbox by accident."
+          }
+        },
+        "required": [
+          "kind",
+          "message",
+          "page"
+        ],
+        "additionalProperties": false
+      },
+      "feedback-response": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "string",
+            "format": "uuid",
+            "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
+            "description": "The stored message. It exists whatever `mail` says."
+          },
+          "mail": {
+            "type": "string",
+            "enum": [
+              "sent",
+              "not_requested",
+              "not_configured",
+              "failed"
+            ],
+            "description": "What happened to the notification mail: `sent`, `failed`, or `not_configured` when this cloud has no feedback address. The message is stored in every case, so a client shows success for all three."
+          }
+        },
+        "required": [
+          "id",
+          "mail"
+        ],
+        "additionalProperties": false
+      },
       "fetch-types-request": {
         "type": "object",
         "properties": {
@@ -16577,12 +16825,26 @@
                       "minLength": 1,
                       "maxLength": 200,
                       "description": "A display name taken at invoke time — the email for a Fleetless user or an app user, the key's own name for a server key. Storing it rather than joining is the point: renaming a key afterwards does not rewrite history."
+                    },
+                    "name": {
+                      "anyOf": [
+                        {
+                          "type": "string",
+                          "minLength": 1,
+                          "maxLength": 200
+                        },
+                        {
+                          "type": "null"
+                        }
+                      ],
+                      "description": "The person's display name when the job started: the Fleetless user's `display_name` for a developer, the app user's `display_name` for an app user. `null` for a server key, when the person had no name set, and for runs recorded before contracts 5.3.0. Show `label` when it is null."
                     }
                   },
                   "required": [
                     "kind",
                     "id",
-                    "label"
+                    "label",
+                    "name"
                   ],
                   "additionalProperties": false,
                   "description": "Who invoked the run, and what they were acting as at the time."
@@ -19271,7 +19533,7 @@
           },
           "builtin": {
             "type": "boolean",
-            "description": "`true` for the two roles every app starts with. Their **rights may be re-scoped** exactly like a custom role's, through `PUT /api/apps/:id/roles/:roleId/permissions` — the flag exists so the console can explain where they came from, not to protect them. It does not make them renamable or deletable — no route does that for any role."
+            "description": "`true` for the two roles every app starts with. Their **rights may be re-scoped** exactly like a custom role's, through `PUT /api/apps/:id/roles/:roleId/permissions` — the flag exists so the console can explain where they came from, not to protect them. Built-in roles can be renamed and deleted like any other; the flag only records that the cloud seeded them."
           }
         },
         "required": [
@@ -19310,7 +19572,7 @@
                 },
                 "builtin": {
                   "type": "boolean",
-                  "description": "`true` for the two roles every app starts with. Their **rights may be re-scoped** exactly like a custom role's, through `PUT /api/apps/:id/roles/:roleId/permissions` — the flag exists so the console can explain where they came from, not to protect them. It does not make them renamable or deletable — no route does that for any role."
+                  "description": "`true` for the two roles every app starts with. Their **rights may be re-scoped** exactly like a custom role's, through `PUT /api/apps/:id/roles/:roleId/permissions` — the flag exists so the console can explain where they came from, not to protect them. Built-in roles can be renamed and deleted like any other; the flag only records that the cloud seeded them."
                 }
               },
               "required": [
@@ -19389,6 +19651,21 @@
           "capabilities"
         ]
       },
+      "role-rename-request": {
+        "type": "object",
+        "properties": {
+          "name": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 60,
+            "description": "The new name, trimmed, 1 to 60 characters. Unique per app: another role of this app with the same name answers `409 role_name_taken`. The role's users keep it under its new name."
+          }
+        },
+        "required": [
+          "name"
+        ],
+        "additionalProperties": false
+      },
       "server-key-list-response": {
         "type": "object",
         "properties": {