@fleetless/contracts 1.0.5 → 1.1.0

package/dist/alerts.d.ts

@@ -1,24 +1,22 @@
 // SPDX-License-Identifier: Apache-2.0
 import { z } from 'zod';
-/**
 /**
  * Datapoint alerts and per-datapoint chart display config.
  *
- * An alert is a **state machine** (`ok ⇄ firing`), not a fire-once event. The
+ * An alert is a **state machine** (`ok ⇄ firing`), not a fire-once event: the
  * definition and the runtime state (`state`, `state_since`, `last_value`) are
- * read together, and the cloud evaluates the alert at ingest.
+ * read together, and the cloud evaluates it at ingest.
  *
  * **The definitions live in the configuration document.** The alert definition
  * is `config.ts`'s `datapointAlert`, nested under the datapoint it watches; the
- * chart bounds are `datapointChart`. They therefore take effect on publish
- * rather than immediately, and in exchange every change to them is versioned,
- * comparable and revertible. The runtime state stays in the database: it has no
- * business in a versioned document.
+ * chart bounds are `datapointChart`. They take effect on publish, not
+ * immediately — in exchange, every change is versioned, comparable, revertible.
+ * The runtime state stays in the database: it has no business in a versioned
+ * document.
  *
  * **What is here is the read surface.** `GET /api/robots/:id/alerts` and
- * `GET /api/org/alerts` answer with the definition joined to its state, and the
- * shapes below are what they answer with. No alert sends mail, so nothing here
- * describes one.
+ * `GET /api/org/alerts` answer with the definition joined to its state — the
+ * shapes below. No alert sends mail, so nothing here describes one.
  */
 /**
  * `above`/`below` compare the numeric sample value (already scale/offset
@@ -27,11 +25,11 @@ import { z } from 'zod';
  * threshold itself: `above` resolves at `value ≤ threshold −
  * resolve_hysteresis`, mirrored for `below`. Defaulted rather than left
  * `optional` so a parsed entity never makes a consumer re-derive "absent
- * means 0" — the cloud always sends an explicit resolve point, and every
- * reader gets the same number whether it was sent or not. `equals` compares
- * the raw value for equality — the shape for boolean/string datapoints a
- * threshold cannot describe ("Hindernis erkannt" = `equals true`) — and
- * carries no hysteresis, because equality has no direction to relax.
+ * means 0" — the cloud always sends an explicit resolve point. `equals`
+ * compares the raw value for equality — the shape for boolean/string
+ * datapoints a threshold cannot describe (an obstacle-detected flag as
+ * `equals true`) — and carries no hysteresis: equality has no direction to
+ * relax.
  *
  * A discriminated union on `kind` rather than one object with optional
  * fields: an `equals` alert carrying a stray `threshold` would otherwise
@@ -101,8 +99,8 @@ export type AlertState = z.infer<typeof alertState>;
  * cloud joins the two per request (`routes/alerts.ts`'s `toWire`).
  *
  * **There are no mail settings here.** The configuration format has no mail
- * fields, so no alert can be configured to send one, and a shape describing
- * recipients would describe a delivery path that does not exist.
+ * fields, so no alert can send one, and a shape describing recipients would
+ * describe a delivery path that does not exist.
  */
 export declare const datapointAlertRow: z.ZodObject<{
     id: z.ZodUUID;

package/dist/alerts.js

@@ -1,25 +1,23 @@
 // SPDX-License-Identifier: Apache-2.0
 import { z } from 'zod';
 import { slug } from './common.js';
-/**
 /**
  * Datapoint alerts and per-datapoint chart display config.
  *
- * An alert is a **state machine** (`ok ⇄ firing`), not a fire-once event. The
+ * An alert is a **state machine** (`ok ⇄ firing`), not a fire-once event: the
  * definition and the runtime state (`state`, `state_since`, `last_value`) are
- * read together, and the cloud evaluates the alert at ingest.
+ * read together, and the cloud evaluates it at ingest.
  *
  * **The definitions live in the configuration document.** The alert definition
  * is `config.ts`'s `datapointAlert`, nested under the datapoint it watches; the
- * chart bounds are `datapointChart`. They therefore take effect on publish
- * rather than immediately, and in exchange every change to them is versioned,
- * comparable and revertible. The runtime state stays in the database: it has no
- * business in a versioned document.
+ * chart bounds are `datapointChart`. They take effect on publish, not
+ * immediately — in exchange, every change is versioned, comparable, revertible.
+ * The runtime state stays in the database: it has no business in a versioned
+ * document.
  *
  * **What is here is the read surface.** `GET /api/robots/:id/alerts` and
- * `GET /api/org/alerts` answer with the definition joined to its state, and the
- * shapes below are what they answer with. No alert sends mail, so nothing here
- * describes one.
+ * `GET /api/org/alerts` answer with the definition joined to its state — the
+ * shapes below. No alert sends mail, so nothing here describes one.
  */
 /**
  * `above`/`below` compare the numeric sample value (already scale/offset
@@ -28,11 +26,11 @@ import { slug } from './common.js';
  * threshold itself: `above` resolves at `value ≤ threshold −
  * resolve_hysteresis`, mirrored for `below`. Defaulted rather than left
  * `optional` so a parsed entity never makes a consumer re-derive "absent
- * means 0" — the cloud always sends an explicit resolve point, and every
- * reader gets the same number whether it was sent or not. `equals` compares
- * the raw value for equality — the shape for boolean/string datapoints a
- * threshold cannot describe ("Hindernis erkannt" = `equals true`) — and
- * carries no hysteresis, because equality has no direction to relax.
+ * means 0" — the cloud always sends an explicit resolve point. `equals`
+ * compares the raw value for equality — the shape for boolean/string
+ * datapoints a threshold cannot describe (an obstacle-detected flag as
+ * `equals true`) — and carries no hysteresis: equality has no direction to
+ * relax.
  *
  * A discriminated union on `kind` rather than one object with optional
  * fields: an `equals` alert carrying a stray `threshold` would otherwise
@@ -98,8 +96,8 @@ export const alertState = z.enum(['ok', 'firing']);
  * cloud joins the two per request (`routes/alerts.ts`'s `toWire`).
  *
  * **There are no mail settings here.** The configuration format has no mail
- * fields, so no alert can be configured to send one, and a shape describing
- * recipients would describe a delivery path that does not exist.
+ * fields, so no alert can send one, and a shape describing recipients would
+ * describe a delivery path that does not exist.
  */
 export const datapointAlertRow = z.object({
     id: z.uuid(),

package/dist/app-users.d.ts

@@ -39,9 +39,9 @@ export declare const APP_USER_DISPLAY_NAME_MAX = 120;
  * buttons, where a hyphen is the conventional spelling — `azure-ad`, not
  * `azure_ad`.
  *
- * The two grammars are one character apart, which is exactly why this is its
- * own export with its own tests rather than a reuse: reusing the wrong one
- * would be invisible until a customer typed a hyphen.
+ * The two grammars are one character apart — why this is its own export with
+ * its own tests, not a reuse: reusing the wrong one would be invisible until
+ * a customer typed a hyphen.
  */
 export declare const providerSlug: z.ZodString;
 /**
@@ -338,9 +338,8 @@ export declare const APP_URL_PLACEHOLDERS: {
  * the mirror reason: it would mail every recipient the same link.
  *
  * **What it cannot check**: that the URL resolves, that the app serves that
- * path, or that the developer's page knows what to do with the token. Nothing
- * a schema can see says any of that, and a validator that looked sufficient
- * here would be read as an assurance.
+ * path, or that the developer's page knows what to do with the token — and a
+ * validator that looked sufficient here would be read as an assurance.
  */
 export declare function appUrlTemplate(placeholder: string): z.ZodString;
 /**

package/dist/app-users.js

@@ -40,14 +40,14 @@ export const APP_USER_DISPLAY_NAME_MAX = 120;
  * buttons, where a hyphen is the conventional spelling — `azure-ad`, not
  * `azure_ad`.
  *
- * The two grammars are one character apart, which is exactly why this is its
- * own export with its own tests rather than a reuse: reusing the wrong one
- * would be invisible until a customer typed a hyphen.
+ * The two grammars are one character apart — why this is its own export with
+ * its own tests, not a reuse: reusing the wrong one would be invisible until
+ * a customer typed a hyphen.
  */
 export const providerSlug = z
     .string()
     .max(40)
-    .regex(/^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/, 'a provider slug is lowercase and hyphen-separated, starting with a letter');
+    .regex(/^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/, 'must be lowercase and hyphen-separated, starting with a letter');
 /**
  * **The three states an app user can be in, and the order is the lifecycle.**
  *
@@ -95,10 +95,10 @@ export const appUser = z.object({
      * accepted — it does not mean blocked and it does not mean without access.
      */
     has_password: z.boolean().meta({
-        description: 'Whether this account has a Fleetless-held password at all. `false` is an identity-provider-only account, or an invitation not yet accepted — it does not mean blocked and it does not mean without access. No hash, no algorithm and no "last changed" travels here, and nothing on the wire can say whether a password is strong or already known to somebody else.',
+        description: 'Whether this account has a Fleetless-held password. `false` is an identity-provider-only account, or an invitation not yet accepted — it does not mean blocked and it does not mean without access. No hash, no algorithm and no "last changed" travels here, and nothing on the wire can say whether a password is strong or already known to somebody else.',
     }),
     providers: z.array(providerSlug).max(20).meta({
-        description: 'The slugs of the identity providers this account is linked to, empty for a password-only user. It is what lets a developer\'s user list say where an account came from without a second request.',
+        description: 'The slugs of the identity providers this account is linked to, empty for a password-only user. Lets a developer\'s user list say where an account came from without a second request.',
     }),
     last_login_at: z.iso.datetime().nullable().meta({
         description: 'When this user last signed in, or `null` if they never have. Required and nullable rather than optional, so *never logged in* stays distinguishable from *this field was not loaded*.',
@@ -269,7 +269,7 @@ export const appOidcProvider = z.object({
         description: 'Whether a federated login may join an **existing** app user with the same address. It needs the provider to assert `email_verified` as well: either condition alone is account takeover, since a provider that lets anyone type any address into a profile would otherwise hand over every matching account, and a developer who connects a provider for a subset of their users would otherwise silently merge strangers.',
     }),
     enabled: z.boolean().meta({
-        description: 'Whether this provider is offered at all. A disabled provider disappears from `GET /api/client/providers` and refuses a start with `provider_disabled`, without the row and its linked identities being deleted.',
+        description: 'Whether this provider is offered. A disabled provider disappears from `GET /api/client/providers` and refuses a start with `provider_disabled`, without the row and its linked identities being deleted.',
     }),
     created_at: z.iso.datetime().meta({ description: 'When the provider was configured, as an ISO 8601 timestamp.' }),
 }).strict();
@@ -371,9 +371,8 @@ export const APP_URL_PLACEHOLDERS = {
  * the mirror reason: it would mail every recipient the same link.
  *
  * **What it cannot check**: that the URL resolves, that the app serves that
- * path, or that the developer's page knows what to do with the token. Nothing
- * a schema can see says any of that, and a validator that looked sufficient
- * here would be read as an assurance.
+ * path, or that the developer's page knows what to do with the token — and a
+ * validator that looked sufficient here would be read as an assurance.
  */
 export function appUrlTemplate(placeholder) {
     return z

package/dist/apps.d.ts

@@ -5,7 +5,7 @@ import { z } from 'zod';
  *
  * The rule that shapes all of this: **roles are the only filter**. A robot
  * assigned to an app exposes every one of its services to that app; what a
- * role does not grant simply does not exist for that user. There is no second
+ * role does not grant does not exist for that user. There is no second
  * visibility mechanism, and adding one later would create two places to look
  * when someone cannot see something.
  */
@@ -15,8 +15,8 @@ import { z } from 'zod';
  *
  * **Globally unique, not per org.** `clientLoginRequest` carries only the
  * identifier, the email and the password — there is no org context to
- * disambiguate with, so a per-org identifier could not be resolved at login
- * at all. A collision is refused with `identifier_taken`.
+ * disambiguate with, so a per-org identifier could not be resolved at login.
+ * A collision is refused with `identifier_taken`.
  */
 export declare const appIdentifier: z.ZodString;
 export declare const app: z.ZodObject<{
@@ -129,9 +129,8 @@ export declare const createServerKeyResponse: z.ZodObject<{
 export type CreateServerKeyResponse = z.infer<typeof createServerKeyResponse>;
 /**
  * Every app starts with `observe` and `operate`; custom roles are allowed
- * too. `builtin` marks the two starting roles — they may be
- * edited like any other, the flag exists so the console can explain where
- * they came from.
+ * too. `builtin` marks the two starting roles — editable like any other,
+ * the flag only tells the console where they came from.
  */
 export declare const role: z.ZodObject<{
     id: z.ZodUUID;

package/dist/apps.js

@@ -6,7 +6,7 @@ import { slug } from './common.js';
  *
  * The rule that shapes all of this: **roles are the only filter**. A robot
  * assigned to an app exposes every one of its services to that app; what a
- * role does not grant simply does not exist for that user. There is no second
+ * role does not grant does not exist for that user. There is no second
  * visibility mechanism, and adding one later would create two places to look
  * when someone cannot see something.
  */
@@ -16,8 +16,8 @@ import { slug } from './common.js';
  *
  * **Globally unique, not per org.** `clientLoginRequest` carries only the
  * identifier, the email and the password — there is no org context to
- * disambiguate with, so a per-org identifier could not be resolved at login
- * at all. A collision is refused with `identifier_taken`.
+ * disambiguate with, so a per-org identifier could not be resolved at login.
+ * A collision is refused with `identifier_taken`.
  */
 export const appIdentifier = slug;
 export const app = z.object({
@@ -31,7 +31,7 @@ export const app = z.object({
         description: 'The display name, shown in the console and available to the developer\'s own pages through the `app.name` mail-template variable. Free text, changed through `PATCH /api/apps/:id`.',
     }),
     identifier: appIdentifier.meta({
-        description: 'The stable handle a client sends at login, lowercase and underscore-separated. **Globally unique, not per organisation** — `clientLoginRequest` carries no org context to disambiguate with, so a collision is refused with `identifier_taken`.',
+        description: 'The stable handle a client sends at login, lowercase and underscore-separated. **Globally unique, not per organisation** — `clientLoginRequest` carries no org context, so a collision is refused with `identifier_taken`.',
     }),
     /** Robots are referenced individually; tags never grant rights. */
     robot_ids: z.array(z.uuid()).meta({
@@ -49,7 +49,7 @@ export const app = z.object({
      * (`createAppUserRequest`, `createAppInvitationRequest`) rather than
      * pre-filling a form.
      *
-     * That is worth saying out loud because it changes what a wrong value costs.
+     * Worth saying: it changes what a wrong value costs.
      * A prefill somebody can see and correct became a default applied on the
      * server, and the obvious next question — should it be required instead? —
      * has a deliberate answer: no, because an invitation resolves the role at
@@ -66,7 +66,7 @@ export const app = z.object({
      * check that, so `PATCH /api/apps/:id` does.
      */
     default_role_id: z.uuid().nullable().meta({
-        description: 'The role an app user gets when they are created or invited without an explicit one. `null` means this app has not chosen a default, the normal state of an app created before its roles were configured — and then a create or invite that omits `role_id` is a `validation_error` rather than a user with no role. An invitation resolves the role when it is issued, so changing this never re-aims an outstanding one. The role must belong to this app, which `PATCH /api/apps/:id` checks and the schema cannot.',
+        description: 'The role an app user gets when created or invited without an explicit one. `null` means this app has not chosen a default, the normal state of an app created before its roles were configured — and then a create or invite that omits `role_id` gets `validation_error`, not a user with no role. An invitation resolves the role when issued, so changing this never re-aims an outstanding one. The role must belong to this app, which `PATCH /api/apps/:id` checks and the schema cannot.',
     }),
     created_at: z.iso.datetime().meta({
         description: 'When the app was created, as an ISO 8601 timestamp. `GET /api/apps` orders by this field.',
@@ -145,7 +145,7 @@ export const updateAppRequest = z.object({
 export const serverKeyToken = z.string().regex(/^flk_[0-9a-f]{32}$/);
 export const serverKey = z.object({
     id: z.uuid().meta({
-        description: 'The key row, and what the rotate and delete routes address. It is not the key: the secret itself is never carried by this shape.',
+        description: 'The key row, and what the rotate and delete routes address. It is not the key: this shape never carries the secret.',
     }),
     app_id: z.uuid().meta({
         description: 'The app whose full rights this key carries. A key is never shared between apps.',
@@ -164,7 +164,7 @@ export const serverKey = z.object({
 /** What `GET /api/apps/:id/server-keys` answers — metadata only; the raw secret exists once, in `createServerKeyResponse`, and never here. */
 export const serverKeyListResponse = z.object({
     server_keys: z.array(serverKey).meta({
-        description: 'The app\'s server keys as metadata, oldest first by `created_at`. The raw secret is not here and never will be: it exists once, in the answer to the request that created or rotated the key.',
+        description: 'The app\'s server keys as metadata, oldest first by `created_at`. The raw secret is not here and never will be: it exists once, in the response that created or rotated the key.',
     }),
 });
 export const createServerKeyResponse = z.object({
@@ -173,9 +173,8 @@ export const createServerKeyResponse = z.object({
 });
 /**
  * Every app starts with `observe` and `operate`; custom roles are allowed
- * too. `builtin` marks the two starting roles — they may be
- * edited like any other, the flag exists so the console can explain where
- * they came from.
+ * too. `builtin` marks the two starting roles — editable like any other,
+ * the flag only tells the console where they came from.
  */
 export const role = z.object({
     id: z.uuid().meta({
@@ -188,7 +187,7 @@ export const role = z.object({
         description: 'The role\'s name, shown wherever a user\'s access is chosen. The two roles every app starts with are named `observe` and `operate`.',
     }),
     builtin: z.boolean().meta({
-        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, because no route renames or deletes 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. It does not make them renamable or deletable — no route does that for any role.',
     }),
 });
 /** What `GET /api/apps/:id/roles` answers: the app's roles, builtin and custom alike. */

package/dist/assets.js

@@ -70,7 +70,7 @@ export const asset = z.object({
     id: z.uuid().meta({ description: 'The asset\'s id in the store.' }),
     robot_id: z.uuid().meta({ description: 'The robot this asset belongs to.' }),
     kind: assetKind.meta({
-        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 it has to pre-fetch.',
+        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.',
     }),
     /**
      * What the robot called it — for a mesh, the `package://` URI the URDF
@@ -105,7 +105,7 @@ export const asset = z.object({
      * rules, one enforced and one only documented, is how a traversal gets in.
      */
     name: z.string().min(1).max(500).meta({
-        description: 'What the robot called it — for a mesh, the `package://` URI the URDF references, verbatim, which is the only string a developer can match against their own workspace. A file the URDF never names (an image a `.dae` loads for itself) is named by joining the mesh\'s own directory with that internal reference.',
+        description: 'What the robot called it — for a mesh, the `package://` URI the URDF references, verbatim, the only string a developer can match against their own workspace. A file the URDF never names (an image a `.dae` loads for itself) is named by joining the mesh\'s own directory with that internal reference.',
     }),
     media_type: z.string().min(1).max(120).meta({
         description: 'The media type of the stored bytes, as the producer reported it.',
@@ -122,7 +122,7 @@ export const asset = z.object({
      * predictable failure of a store that hides it.
      */
     sha256: z.string().regex(/^[a-f0-9]{64}$/).meta({
-        description: 'The content hash, lowercase hex, and the reason two robots sharing a mesh cost one copy. It is exposed because it is the only way a client can tell "this is the same mesh I already have" across robots.',
+        description: 'The content hash, lowercase hex. Exposed because it is the only way a client can tell "this is the same mesh I already have" across robots — the reason two robots sharing a mesh cost one copy.',
     }),
     created_at: z.iso.datetime().meta({
         description: 'When the asset was first stored, as an ISO 8601 timestamp.',
@@ -169,13 +169,13 @@ export const urdfCompleteness = z.object({
      */
     missing: z.array(z.object({
         uri: z.string().min(1).max(500).meta({
-            description: 'The reference, verbatim, that no stored asset answers — a `package://` URI the workspace does not hold, or an absolute or bare relative path nothing will ever fetch. A developer whose URDF names one of the latter is entitled to be told so.',
+            description: 'The reference, verbatim, that no stored asset answers — a `package://` URI the workspace does not hold, or an absolute or bare relative path nothing will ever fetch.',
         }),
         element: z.enum(['mesh', 'texture']).meta({
             description: 'Which kind of reference it was: geometry the URDF names as a `mesh`, or a `texture` a surface paints with. Without it a client reports a missing texture as a missing mesh, contradicting `mesh_count` beside it.',
         }),
     })).meta({
-        description: 'The references nothing in the store answers, each with the element that asked for it. A bare count is a dead end that sends a developer hunting through a workspace by hand; the references are what they can act on, so the references travel.',
+        description: 'The references nothing in the store answers, each with the element that asked for it. A bare count would send a developer hunting through the workspace by hand; the references are what they can act on.',
     }),
 });
 /**
@@ -193,7 +193,7 @@ export const urdfCompleteness = z.object({
  */
 export const assetSyncRequest = z.object({
     source: z.enum(['bridge']).meta({
-        description: 'Where the bytes come from. `bridge` is the only value today: the connected bridge reads them from the robot\'s own workspace. It is validated rather than ignored, so a caller naming a source that does not exist yet learns that instead of silently getting a bridge sync.',
+        description: 'Where the bytes come from. `bridge` is the only value today: the connected bridge reads them from the robot\'s own workspace. Validated rather than ignored, so a caller naming an unknown source is told so instead of silently getting a bridge sync.',
     }),
 }).strict();
 export const assetSyncResponse = z.object({
@@ -253,7 +253,7 @@ export const assetTooLargeDetails = z.object({
         description: 'The upload ceiling, in bytes.',
     }),
     size_bytes: z.number().int().positive().meta({
-        description: 'How large the refused file actually 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: '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.',
     }),
 });
 /**
@@ -312,9 +312,8 @@ export const assetFailure = z.object({
         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.',
     }),
 }).superRefine((f, ctx) => {
-    // **Enforced, not merely described.** A rule that lives only in a comment is
-    // a request, and a field whose meaning sits beside it rather than in it gets
-    // filled with something else.
+    // Enforced here, not merely described above — a rule that lives only in a
+    // comment gets filled with something else.
     if (f.kind === 'too_large' && f.details == null) {
         ctx.addIssue({ code: 'custom', path: ['details'], message: '`too_large` without limit_bytes/size_bytes says nothing a developer can act on' });
     }
@@ -377,8 +376,6 @@ export const assetListResponse = z.object({
         description: 'Every asset stored for this robot: the URDF, the meshes it references, and the textures those paint with.',
     }),
     /**
-     * The sync running right now, or `null`.
-     *
      * **This field exists for the reload case.** A client that holds the
      * `sync_id` only in memory loses its progress display on a refresh, and the
      * state is still there server-side under `GET .../assets/sync/<id>` —
@@ -409,7 +406,7 @@ export const assetListResponse = z.object({
      * crash, and no amount of polling shortens it.
      */
     urdf_available: z.boolean().nullable().meta({
-        description: 'What the connected bridge says it *could* transfer, which is deliberately separate from what has been transferred. `null` when no bridge is connected — distinct from `false`, because "no robot is online to ask" and "the robot has no URDF" send a developer to two 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.',
+        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.',
     }),
 });
 /**

package/dist/audit.d.ts

@@ -14,21 +14,19 @@ import { z } from 'zod';
  * log — an email, a key name, a robot name — so the console never has to
  * resolve four different id kinds to render a row.
  *
- * **`end_user` stays, and it stays for the rows already written.** The
- * split into two identity spaces replaced the org's one user pool with
- * Fleetless users and per-app app users; every new row an app user writes
- * carries `app_user`. But an audit log is the one thing this platform must
- * never rewrite, and there are stored rows whose `kind` is `end_user`. Dropping
- * the member would leave those rows failing their own schema — a log that
- * cannot be read back is worse than one carrying a retired word.
+ * **`end_user` stays, for the rows already written.** The identity split
+ * replaced the org's one user pool with Fleetless users and per-app app
+ * users; new rows from an app user carry `app_user`. But an audit log must
+ * never be rewritten, and stored rows still have `kind: end_user` — dropping
+ * the member would fail their own schema. A log that can't be read back is
+ * worse than one carrying a retired word.
  *
- * So this enum is deliberately **wider than what any producer emits**: nothing
- * writes `end_user` any more, and nothing may start again. That is said here
- * rather than left to be inferred from a search somebody runs in a year.
+ * So the enum is deliberately **wider than what any producer emits**:
+ * nothing writes `end_user` any more, and nothing should start again — said
+ * here rather than left for a future search to infer.
  *
  * `developer` is a Fleetless user. It kept its name through both redesigns
- * because it was always right about what it named: the person who configures
- * robots.
+ * because it was always right: the person who configures robots.
  */
 export declare const auditActor: z.ZodObject<{
     kind: z.ZodEnum<{

package/dist/audit.js

@@ -15,21 +15,19 @@ import { wireSeqCursor, wireTimestampMs } from './common.js';
  * log — an email, a key name, a robot name — so the console never has to
  * resolve four different id kinds to render a row.
  *
- * **`end_user` stays, and it stays for the rows already written.** The
- * split into two identity spaces replaced the org's one user pool with
- * Fleetless users and per-app app users; every new row an app user writes
- * carries `app_user`. But an audit log is the one thing this platform must
- * never rewrite, and there are stored rows whose `kind` is `end_user`. Dropping
- * the member would leave those rows failing their own schema — a log that
- * cannot be read back is worse than one carrying a retired word.
+ * **`end_user` stays, for the rows already written.** The identity split
+ * replaced the org's one user pool with Fleetless users and per-app app
+ * users; new rows from an app user carry `app_user`. But an audit log must
+ * never be rewritten, and stored rows still have `kind: end_user` — dropping
+ * the member would fail their own schema. A log that can't be read back is
+ * worse than one carrying a retired word.
  *
- * So this enum is deliberately **wider than what any producer emits**: nothing
- * writes `end_user` any more, and nothing may start again. That is said here
- * rather than left to be inferred from a search somebody runs in a year.
+ * So the enum is deliberately **wider than what any producer emits**:
+ * nothing writes `end_user` any more, and nothing should start again — said
+ * here rather than left for a future search to infer.
  *
  * `developer` is a Fleetless user. It kept its name through both redesigns
- * because it was always right about what it named: the person who configures
- * robots.
+ * because it was always right: the person who configures robots.
  */
 export const auditActor = z.object({
     kind: z.enum(['developer', 'end_user', 'app_user', 'server_key', 'bridge']),
@@ -130,12 +128,11 @@ export const auditQuery = z.object({
      * Everything under a dotted prefix, e.g. `server_key.` for all three
      * server-key actions.
      *
-     * **A separate parameter, not a widening of `action`.** The sentence on
-     * `action` above — a filter that matches more than it says is not one —
-     * still stands; this is a different question with a name that says which
-     * one it is. Setting both is refused rather than resolved, because a query
+     * **A separate parameter, not a widening of `action`.** The rule on
+     * `action` above still stands; this is a different question with a name
+     * that says which one it is. Setting both is refused, not resolved —
      * naming an exact action *and* a prefix is a caller mistake, not a
-     * combination anyone should have to guess the meaning of.
+     * combination to guess the meaning of.
      *
      * **The published artifact cannot express that refusal**: a cross-field
      * `.refine()` has no JSON Schema rendering, so `audit-query.schema.json`

package/dist/client-auth.d.ts

@@ -48,13 +48,12 @@ export type ClientRefreshRequest = z.infer<typeof clientRefreshRequest>;
  *
  * **The route answers `204` and has no response shape.** It used to answer a
  * `clientLogoutResponse` reporting what was left of the session at the identity
- * provider — RP-initiated logout, an `end_session_endpoint` to redirect to,
- * four ways of saying "we cannot end that session". That whole apparatus
- * belonged to the hosted login flow, where Fleetless owned the browser. It does
- * not own it any more: the developer's app does, and an app that wants to end
- * a provider session redirects there itself, knowing its own provider, which
- * Fleetless never did better than it. Listed as a breaking change rather than
- * quietly kept as a field nobody fills.
+ * provider — RP-initiated logout, an `end_session_endpoint`, four ways of
+ * saying "we cannot end that session". That belonged to the hosted login flow,
+ * where Fleetless owned the browser; it doesn't any more. The developer's app
+ * does, and knows its own provider better than Fleetless ever did — ending a
+ * provider session is its own redirect to make. Listed as a breaking change,
+ * not quietly kept as a field nobody fills.
  */
 export declare const clientLogoutRequest: z.ZodObject<{
     refresh_token: z.ZodString;
@@ -110,8 +109,8 @@ export type ClientResendVerificationRequest = z.infer<typeof clientResendVerific
  * to be. An **app identifier** no app carries is the one refusal, `404
  * not_found`, because an identifier is public and an address is not.
  *
- * Moved here from `identity.ts`, where it sat because the client surface had no
- * file of its own for it. It is an app-user shape and belongs with them.
+ * Moved here from `identity.ts`, which predates a client-surface file — it's
+ * an app-user shape and belongs with them.
  */
 export declare const clientPasswordResetRequest: z.ZodObject<{
     app_identifier: z.ZodString;

package/dist/client-auth.js

@@ -37,7 +37,7 @@ import { password } from './identity.js';
 /* ------------------------------------------------------ password login -- */
 export const clientLoginRequest = z.object({
     app_identifier: appIdentifier.meta({
-        description: 'The app being logged in to, as its globally unique identifier — the lowercase, underscore-separated string the developer chose when the app was created. There is no organisation context at login, so this is what decides which app the credentials are checked for.',
+        description: 'The app being logged in to: its globally unique, lowercase, underscore-separated identifier, chosen by the developer at creation. There is no organisation context at login, so this is what decides which app the credentials are checked for.',
     }),
     email: z.email().meta({
         description: 'The app user\'s address. Addresses are unique **per app**, not across Fleetless: the same address may be an unrelated account in another app of the same organisation, so this pair is what identifies a person here.',
@@ -58,17 +58,16 @@ export const clientRefreshRequest = z.object({
  *
  * **The route answers `204` and has no response shape.** It used to answer a
  * `clientLogoutResponse` reporting what was left of the session at the identity
- * provider — RP-initiated logout, an `end_session_endpoint` to redirect to,
- * four ways of saying "we cannot end that session". That whole apparatus
- * belonged to the hosted login flow, where Fleetless owned the browser. It does
- * not own it any more: the developer's app does, and an app that wants to end
- * a provider session redirects there itself, knowing its own provider, which
- * Fleetless never did better than it. Listed as a breaking change rather than
- * quietly kept as a field nobody fills.
+ * provider — RP-initiated logout, an `end_session_endpoint`, four ways of
+ * saying "we cannot end that session". That belonged to the hosted login flow,
+ * where Fleetless owned the browser; it doesn't any more. The developer's app
+ * does, and knows its own provider better than Fleetless ever did — ending a
+ * provider session is its own redirect to make. Listed as a breaking change,
+ * not quietly kept as a field nobody fills.
  */
 export const clientLogoutRequest = z.object({
     refresh_token: z.string().min(1).meta({
-        description: 'Any refresh token of the session to end. The whole token family is revoked server-side, so a token stolen before this call stops working too — clearing a client-side store is a gesture, not a revocation. The answer is `204`: a token the server does not recognise gets it too, since the end state a caller asked for is the end state they get.',
+        description: 'Any refresh token of the session to end. The whole token family is revoked server-side, so a token stolen before this call stops working too — clearing a client-side store is a gesture, not a revocation. The answer is `204`: a token the server does not recognise gets it too, since that is the end state being asked for.',
     }),
 });
 /* ---------------------------------------------- registration and mails -- */
@@ -137,8 +136,8 @@ export const clientResendVerificationRequest = z
  * to be. An **app identifier** no app carries is the one refusal, `404
  * not_found`, because an identifier is public and an address is not.
  *
- * Moved here from `identity.ts`, where it sat because the client surface had no
- * file of its own for it. It is an app-user shape and belongs with them.
+ * Moved here from `identity.ts`, which predates a client-surface file — it's
+ * an app-user shape and belongs with them.
  */
 export const clientPasswordResetRequest = z
     .object({
@@ -373,7 +372,7 @@ export const clientMcpInteraction = z.object({
     app_id: z.uuid().meta({ description: 'The app this authorization is for. The approving token\'s `app_id` must match it — an interaction of one app cannot be approved with a session from another.' }),
     client_name: z.string().nullable().meta({ description: 'What the MCP client calls itself, or `null` if it named nothing. **Unverified** — see `client_name_verified`.' }),
     client_name_verified: z.literal(false).meta({
-        description: 'Always `false`. The client registered itself without authentication and chose this name about itself, so it must be rendered as a claim and never as an identity. There is no verified case, which is why this is a literal and not a boolean: a `true` branch would be dead code that looked like a safeguard.',
+        description: 'Always `false`. The client registered itself without authentication and named itself, so it must be rendered as a claim and never as an identity. There is no verified case, which is why this is a literal and not a boolean: a `true` branch would be dead code that looked like a safeguard.',
     }),
     scopes: z.array(z.string()).meta({ description: 'The scopes the client asked for, to show the person before they approve.' }),
     already_granted: z.boolean().meta({ description: 'Whether this user has already approved this client. It is a record of what they answered last time, and **this route makes no second use of it**: an app that skips its own consent screen when this is `true` is the only thing deciding that, and approve succeeds identically for a user who holds no grant at all. The standing grant is read elsewhere, on every request to the app\'s MCP endpoint. Withdrawing it is `DELETE /api/client/mcp/grants/:clientId` for the person themselves and `DELETE /api/apps/:id/users/:userId/mcp-grants/:clientId` for the developer. A withdrawal makes this `false` again at the next authorization **and stops the client at its very next MCP call**, unexpired access token and all — up to fifteen minutes of it — because the endpoint keys that check on the `client_id` the token carries.' }),
@@ -417,10 +416,10 @@ export const mcpConsentGrant = z.object({
         description: 'The MCP client this consent is for, as its dynamic registration was issued. It is the value the withdrawal routes take in their path, and it is the only stable handle on a client — the name beside it is not one.',
     }),
     client_name: z.string().nullable().meta({
-        description: 'What the client calls itself, or `null` when its registration is gone and there is no longer anything to have named. **Unverified** — see `client_name_verified`.',
+        description: 'What the client calls itself, or `null` once its registration is gone. **Unverified** — see `client_name_verified`.',
     }),
     client_name_verified: z.literal(false).meta({
-        description: 'Always `false`. The client registered itself without authentication and chose this name about itself, so it must be rendered as a claim and never as an identity. There is no verified case, which is why this is a literal and not a boolean: a `true` branch would be dead code that looked like a safeguard.',
+        description: 'Always `false`. The client registered itself without authentication and named itself, so it must be rendered as a claim and never as an identity. There is no verified case, which is why this is a literal and not a boolean: a `true` branch would be dead code that looked like a safeguard.',
     }),
     granted_at: z.iso.datetime().meta({
         description: 'When the consent was last given. A withdrawal followed by a fresh approval moves it, because the second approval is the agreement that stands — it is not a record of the first time anybody ever said yes.',
@@ -463,7 +462,7 @@ export const mcpConsentGrantListResponse = z.object({
  */
 export const clientIdentity = z.object({
     kind: z.enum(['developer', 'app_user', 'server_key']).meta({
-        description: 'Which of the three kinds of caller this is: a `developer` working through the console, an `app_user` holding a token from a client login, or a `server_key` used by server-side code. Stated outright rather than left to be inferred from which id happens to be set.',
+        description: 'Which of the three kinds of caller this is: a `developer` working through the console, an `app_user` holding a token from a client login, or a `server_key` used by server-side code. Stated outright, not inferred from which id is set.',
     }),
     developer_id: z.uuid().nullable().meta({
         description: 'The Fleetless user behind this session, or `null` when `kind` is not `developer`.',