@fleetless/contracts 1.0.4 → 1.0.6

package/dist/errors.js

@@ -18,10 +18,10 @@ export const apiError = z.object({
  * console renders a third, and each is right in its own tests.
  *
  * `field` is the **flat key exactly as the caller sent it** — the same string
- * as the `parameterSpec.name` it violated. That is the entire justification
- * for the flat parameter form: a refusal has to name something the caller can
- * find in what they typed, and a console can attach the error to that one
- * input rather than to the form.
+ * as the `parameterSpec.name` it violated. That is why the parameter form
+ * stays flat: a refusal has to name something the caller can find in what
+ * they typed, and a console can attach the error to that one input rather
+ * than to the form.
  */
 export const parameterViolation = z.object({
     field: z.string().min(1),
@@ -81,11 +81,10 @@ export const ERROR_CODES = [
     'invalid_credentials',
     'token_expired',
     'token_revoked',
-    /* `invite_expired` and `invite_used` were removed on 2026-09-05, by the same
-     * reasoning that removed `not_a_member` and with the same evidence: a `grep`
-     * across contracts, cloud, sdk, console and bridge found their own entries
-     * here and one test asserting those entries existed. Nothing has ever emitted
-     * either.
+    /* `invite_expired` and `invite_used` were removed on 2026-09-05 — same
+     * reasoning and evidence as `not_a_member`: a `grep` across contracts, cloud,
+     * sdk, console and bridge found only their own entries here and one test
+     * asserting those entries existed. Nothing has ever emitted either.
      *
      * They were written for `POST /api/client/invitations/accept`, to tell an
      * expired invitation from an already-accepted one. That route answers `410
@@ -420,14 +419,14 @@ export const ERROR_CODES = [
      * no producer is not harmless, because a reader arriving at it takes it for
      * a live refusal. Say which it is, and say when it changes.
      *
-     * **It has one producer already, one train early**: `POST /mcp` answers it to
-     * an `mcp_session` token whose subject is an app user, because the central
-     * endpoint serves the team only. No client can hold such a token yet — only
-     * a test mints one — and the per-app train adds the
-     * `appAuthConfig.mcp_enabled` gate this comment describes.
+     * **It has one producer already, ahead of the gate it describes**: `POST
+     * /mcp` answers it to an `mcp_session` token whose subject is an app user,
+     * because the central endpoint serves the team only. No client can hold such
+     * a token yet — only a test mints one — and the `appAuthConfig.mcp_enabled`
+     * gate arrives with the per-app endpoint.
      *
      * `tool_not_available` below still has no producer — `grep` finds it nowhere
-     * in `cloud/src`. Named as unproduced, for the same reason.
+     * in the cloud's source. Named as unproduced, for the same reason.
      */
     'mcp_disabled',
     /**
@@ -536,7 +535,7 @@ export const ERROR_CODES = [
     // what the cloud actually sends.
     //
     // They are listed in one block, with their producer named, rather than filed
-    // among the waves that introduced them — the honest record is *when this list
+    // by the release that introduced each — the honest record is *when this list
     // learned about them*, not when the cloud started sending them.
     /**
      * `409` from the configuration routes: the draft parses as YAML but its root

package/dist/identity.d.ts

@@ -19,11 +19,10 @@ import { z } from 'zod';
  *
  * **What that deleted, with no successor**: groups and the Org Admins
  * group, app assignments, impersonation, the per-user MCP override and the
- * org-level federation policy. The 2026-08-29 model had put developers and end
- * users into one pool per org and connected them with all of the above; in use
- * it turned out to model the wrong thing — the two populations have different
- * lifecycles, and every mechanism joining them was cost without a product
- * reason.
+ * org-level federation policy. The 2026-08-29 model pooled developers and end
+ * users per org and joined them with all of the above. In use, wrong model:
+ * the two populations have different lifecycles, and every joining mechanism
+ * was cost without a product reason.
  *
  * What did **not** change: the password rules, the session and token shapes,
  * and the enumeration-oracle reasoning on password reset. None of those was
@@ -502,8 +501,8 @@ export type IdpIssuer = z.infer<typeof idpIssuer>;
  * The per-app OIDC vocabulary is `clientOidcErrorCode` in `client-auth.ts`: a
  * different list, for a different flow, redirected to the developer's own page
  * rather than rendered by Fleetless. Two callback error enums coexisting is how
- * the wrong one gets picked up by the train that adds per-app OIDC, which is
- * why this one is deleted rather than left standing for it.
+ * the wrong one gets picked up when per-app OIDC arrives, which is why this
+ * one is deleted rather than left standing for it.
  */
 /**
  * `GET /api/auth/me` — named so the console can validate it.

package/dist/identity.js

@@ -19,11 +19,10 @@ import { z } from 'zod';
  *
  * **What that deleted, with no successor**: groups and the Org Admins
  * group, app assignments, impersonation, the per-user MCP override and the
- * org-level federation policy. The 2026-08-29 model had put developers and end
- * users into one pool per org and connected them with all of the above; in use
- * it turned out to model the wrong thing — the two populations have different
- * lifecycles, and every mechanism joining them was cost without a product
- * reason.
+ * org-level federation policy. The 2026-08-29 model pooled developers and end
+ * users per org and joined them with all of the above. In use, wrong model:
+ * the two populations have different lifecycles, and every joining mechanism
+ * was cost without a product reason.
  *
  * What did **not** change: the password rules, the session and token shapes,
  * and the enumeration-oracle reasoning on password reset. None of those was
@@ -78,7 +77,7 @@ export const org = z.object({
 /** What `PATCH /api/org` answers: the org as it now stands. */
 export const patchOrgResponse = z.object({
     org: org.meta({
-        description: 'The organisation as it now stands, after the patch was applied. The whole resource comes back, not only the fields that changed.',
+        description: 'The organisation as it now stands, after the patch. The whole resource comes back, not only the changed fields.',
     }),
 });
 /**
@@ -104,7 +103,7 @@ export const fleetlessUser = z.object({
         description: 'The Fleetless user in the API, assigned by the cloud and stable for the life of the account.',
     }),
     org_id: z.uuid().meta({
-        description: 'The organisation this person belongs to. Every developer route is already scoped to the caller\'s org, so this confirms what a client is looking at rather than being a filter it applies.',
+        description: 'The organisation this person belongs to. Every developer route is already scoped to the caller\'s org, so this confirms what a client is looking at, not a filter it applies.',
     }),
     email: z.email().meta({
         description: 'The address the account is identified by, **globally unique** across every organisation. Immutable after creation: it is what every invitation, reset link and audit line names.',
@@ -113,7 +112,7 @@ export const fleetlessUser = z.object({
         description: 'Optional human name, shown by the console instead of the address where present. Self-service through `PATCH /api/auth/me`; never used for authentication. `null` when the person never supplied one.',
     }),
     tier: orgAdminTier.meta({
-        description: 'The console powers this person holds. **Required** — every Fleetless user is a member of the team and has a tier; the optional version of this field existed only while the org also held people with no console powers to grade, and that pool is gone.',
+        description: 'The console powers this person holds. **Required** — every Fleetless user has a tier; it was optional only while the org also held people with no console powers to grade, and that pool is gone.',
     }),
     created_at: z.iso.datetime().meta({
         description: 'When the account was created, as an ISO 8601 timestamp.',
@@ -479,8 +478,8 @@ export const idpIssuer = z
  * The per-app OIDC vocabulary is `clientOidcErrorCode` in `client-auth.ts`: a
  * different list, for a different flow, redirected to the developer's own page
  * rather than rendered by Fleetless. Two callback error enums coexisting is how
- * the wrong one gets picked up by the train that adds per-app OIDC, which is
- * why this one is deleted rather than left standing for it.
+ * the wrong one gets picked up when per-app OIDC arrives, which is why this
+ * one is deleted rather than left standing for it.
  */
 /**
  * `GET /api/auth/me` — named so the console can validate it.

package/dist/index.d.ts

@@ -15,7 +15,7 @@ export type { ParameterType, ParameterSpec, ActionConfig, ServiceConfig, Publish
 /**
  * The one account of what is wrong with a configuration document, shared by
  * every layer that reports on one. See `config-issues.ts`'s header for why a
- * second copy of this vocabulary is a defect rather than a convenience.
+ * second copy of this vocabulary is a defect, not a convenience.
  */
 export { DOCUMENT_ROOT_PATH, EXPOSURE_SECTIONS, schemaIssues, formatPath, splitFormatPath, configSchemaHash, } from './config-issues.js';
 export type { SchemaIssue, ExposureSection } from './config-issues.js';

package/dist/index.js

@@ -16,7 +16,7 @@ cameraSource, cameraCredentials, } from './config.js';
 /**
  * The one account of what is wrong with a configuration document, shared by
  * every layer that reports on one. See `config-issues.ts`'s header for why a
- * second copy of this vocabulary is a defect rather than a convenience.
+ * second copy of this vocabulary is a defect, not a convenience.
  */
 export { DOCUMENT_ROOT_PATH, EXPOSURE_SECTIONS, schemaIssues, formatPath, splitFormatPath, configSchemaHash, } from './config-issues.js';
 export { rosGraphEntry, rosGraph, typeField, typeDefinition, parameterFieldsOf } from './introspection.js';

package/dist/jobs.js

@@ -21,17 +21,17 @@ import { slug, wireSeqCursor, wireTimestampMs } from './common.js';
 export const jobState = z.enum(['running', 'succeeded', 'failed', 'cancelled', 'lost']);
 export const job = z.object({
     id: z.uuid().meta({
-        description: 'The job\'s id, minted by the cloud when the invocation is accepted. Informative: state is observed by slug, and this id is what a cancel names when a caller wants to stop one specific job rather than whatever is running.',
+        description: 'The job\'s id, minted by the cloud when the invocation is accepted. Informative — state is observed by slug; a cancel names this id to stop one specific job rather than whatever is running.',
     }),
     robot_id: z.uuid().meta({ description: 'The robot this job is running on.' }),
     slug: slug.meta({
         description: 'The action or service this job is running, as the published configuration exposes it. One slug carries one job at a time, so every observer of that slug sees the same one.',
     }),
     state: jobState.meta({
-        description: 'Where the job stands: `running`, `succeeded`, `failed`, `cancelled` or `lost`. `lost` is a real outcome — the bridge restarted mid-job and the result is gone — and is said out loud rather than left reading `running` because nobody contradicted it.',
+        description: 'Where the job stands: `running`, `succeeded`, `failed`, `cancelled` or `lost`. `lost` is a real outcome — the bridge restarted mid-job and the result is gone — stated rather than left reading `running` by default.',
     }),
     started_at: z.iso.datetime().meta({
-        description: 'When the cloud minted this job, as an ISO 8601 timestamp. For a job adopted from a reconnecting bridge it is **adoption time**, not the real start, because the cloud never minted it and has no honest alternative.',
+        description: 'When the cloud minted this job, as an ISO 8601 timestamp. For a job adopted from a reconnecting bridge, this is **adoption time**, not the real start — the cloud never minted it.',
     }),
     updated_at: z.iso.datetime().meta({
         description: 'When this job last changed, as an ISO 8601 timestamp.',
@@ -176,7 +176,7 @@ export const JOB_RUN_RETENTION_DAYS = 90;
  */
 export const jobActor = z.object({
     kind: z.enum(['developer', 'end_user', 'app_user', 'server_key']).meta({
-        description: 'What the caller was acting as: a `developer` in the console, an `app_user` of one app, or a `server_key` used by server-side code. A bridge invokes nothing, so it is deliberately not a case here. `end_user` appears only on runs recorded before app users replaced the organisation-wide user pool — it is kept so a history page can still render them, and nothing writes it any more.',
+        description: 'What the caller was acting as: a `developer` in the console, an `app_user` of one app, or a `server_key` used by server-side code. A bridge invokes nothing, so it is deliberately not a case here. `end_user` appears only on runs recorded before app users replaced the organisation-wide user pool — kept so old runs still render; nothing writes it now.',
     }),
     id: z.uuid().meta({
         description: 'The id of the Fleetless user, app user or server key that invoked the run.',
@@ -200,7 +200,7 @@ export const jobRunKind = z.enum(['action', 'service']);
  */
 export const jobRun = z.object({
     id: z.uuid().meta({
-        description: 'The run\'s id, which is the same id the invocation was answered with — so a caller that kept a job id can find its durable record here later.',
+        description: 'The run\'s id — the same id the invocation was answered with, so a caller that kept a job id can find its durable record here later.',
     }),
     robot_id: z.uuid().meta({ description: 'The robot the run happened on.' }),
     slug: slug.meta({

package/dist/mcp.d.ts

@@ -8,8 +8,8 @@ import { z } from 'zod';
  * **This file describes the seam, not the protocol.** The MCP messages
  * themselves (`initialize`, `tools/list`, `tools/call`) are defined by the
  * Model Context Protocol and implemented with its official SDK — writing our
- * own zod copies of them would create a second source of truth for somebody
- * else's specification, which is the one thing this package exists to avoid.
+ * own zod copies of them would duplicate somebody else's specification, the
+ * one thing this package exists to avoid.
  * What lives here is what *Fleetless* decides: which revision we speak, where
  * the endpoint is, how a tool is named, and what the console is shown before
  * an end user ever connects.
@@ -94,12 +94,9 @@ export declare function mcpAppEndpointPath(appIdentifier: string): string;
  * ever fetch. Writing them here is what keeps that reading from being made
  * twice.
  *
- * **These are paths, not URLs.** Append them to `PUBLIC_API_BASE_URL`, for the
- * reason `mcpAppEndpointPath` states: the cloud mints every issuer, resource
- * and `aud` from the canonical base and compares a token's `aud` against that
- * string, never against the request's `Host`. The friendly alias is a proxy in
- * front of the same cloud, and a URL built on it hands a client an audience
- * the token endpoint will refuse.
+ * **These are paths, not URLs.** Append them to `PUBLIC_API_BASE_URL`, not the
+ * friendly `mcp.fleetless.dev` alias — see `mcpAppEndpointPath` for why: a URL
+ * built on the alias carries an audience the token endpoint refuses.
  *
  * Named in the shape `OAUTH_PATHS` had, and deliberately a **function** rather
  * than the object that constant was: there is one set of these per app, and a

package/dist/mcp.js

@@ -9,8 +9,8 @@ import { slug } from './common.js';
  * **This file describes the seam, not the protocol.** The MCP messages
  * themselves (`initialize`, `tools/list`, `tools/call`) are defined by the
  * Model Context Protocol and implemented with its official SDK — writing our
- * own zod copies of them would create a second source of truth for somebody
- * else's specification, which is the one thing this package exists to avoid.
+ * own zod copies of them would duplicate somebody else's specification, the
+ * one thing this package exists to avoid.
  * What lives here is what *Fleetless* decides: which revision we speak, where
  * the endpoint is, how a tool is named, and what the console is shown before
  * an end user ever connects.

package/dist/oauth.d.ts

@@ -14,8 +14,8 @@ import { z } from 'zod';
  * and per app for an app's users — and the console's own OAuth portal, which
  * answers `oauthRedirectResponse` at its login and sign-up steps.
  *
- * The client model this file was written to get right is still the important
- * part, and it survived the cut intact: an MCP client **registers itself**
+ * The client model this file was written to get right survived the cut
+ * intact: an MCP client **registers itself**
  * (RFC 7591) because the person only ever pastes a URL into an AI tool.
  * Nobody vetted it, its redirect URIs arrive from the client itself, and the
  * tools it will call move a physical robot. That is why consent names the
@@ -37,10 +37,9 @@ import { z } from 'zod';
  * app's auth settings — are ordinary console API and use `apiError` with
  * `ERROR_CODES` like everything else.
  *
- * So: **two shapes, split by audience, not by accident.** Written down here
- * because the natural instinct on finding two error formats in one server is
- * to unify them, and doing so silently removes the reason the standard one is
- * there.
+ * So: **two shapes, split by audience, not by accident.** Written down
+ * because two error formats in one server invite unifying them — which would
+ * silently erase the reason the standard one exists.
  *
  * **The split is by audience and the path prefix will mislead you.**
  * `/mcp/oauth/consent` sits under an `/oauth/` segment and is nevertheless an
@@ -198,10 +197,9 @@ export type DynamicClientRegistrationResponse = z.infer<typeof dynamicClientRegi
  * from a client we are about to trust, where an unknown key is a caller
  * assuming a feature into existence, while a token request comes from any
  * RFC-compliant client, which may legitimately send parameters this server
- * does not read. Refusing those would be a conformance bug. The consequence
- * is worth stating because it bit the test for this very schema: unknown keys
- * are **stripped**, so `safeParse().success` cannot tell a present field from
- * an absent one. Assert on the parsed value.
+ * does not read. Refusing those would be a conformance bug. Unknown keys are
+ * **stripped**, which bit the test for this schema: `safeParse().success`
+ * cannot tell a present field from an absent one. Assert on the parsed value.
  */
 export declare const oauthTokenRequest: z.ZodObject<{
     grant_type: z.ZodLiteral<"authorization_code">;

package/dist/oauth.js

@@ -14,8 +14,8 @@ import { z } from 'zod';
  * and per app for an app's users — and the console's own OAuth portal, which
  * answers `oauthRedirectResponse` at its login and sign-up steps.
  *
- * The client model this file was written to get right is still the important
- * part, and it survived the cut intact: an MCP client **registers itself**
+ * The client model this file was written to get right survived the cut
+ * intact: an MCP client **registers itself**
  * (RFC 7591) because the person only ever pastes a URL into an AI tool.
  * Nobody vetted it, its redirect URIs arrive from the client itself, and the
  * tools it will call move a physical robot. That is why consent names the
@@ -37,10 +37,9 @@ import { z } from 'zod';
  * app's auth settings — are ordinary console API and use `apiError` with
  * `ERROR_CODES` like everything else.
  *
- * So: **two shapes, split by audience, not by accident.** Written down here
- * because the natural instinct on finding two error formats in one server is
- * to unify them, and doing so silently removes the reason the standard one is
- * there.
+ * So: **two shapes, split by audience, not by accident.** Written down
+ * because two error formats in one server invite unifying them — which would
+ * silently erase the reason the standard one exists.
  *
  * **The split is by audience and the path prefix will mislead you.**
  * `/mcp/oauth/consent` sits under an `/oauth/` segment and is nevertheless an
@@ -180,10 +179,10 @@ export const MCP_DCR_MAX_REDIRECT_URIS = 5;
 export const dynamicClientRegistrationRequest = z
     .object({
     redirect_uris: z.array(redirectUri).min(1).max(MCP_DCR_MAX_REDIRECT_URIS).meta({
-        description: `Where the authorization code may be returned, and the one field a registration cannot omit. Each must be an \`https\` URL, or \`http\` on an explicit loopback address for a native app that cannot hold a certificate, and none may carry a fragment. There must be between \`1\` and \`${MCP_DCR_MAX_REDIRECT_URIS}\` of them; duplicates are collapsed rather than counted twice. Matched **exactly** at the authorize step against what was registered here.`,
+        description: `Where the authorization code may be returned, and the one field a registration cannot omit. Each must be an \`https\` URL, or \`http\` on an explicit loopback address for a native app that cannot hold a certificate, and none may carry a fragment. Between \`1\` and \`${MCP_DCR_MAX_REDIRECT_URIS}\` of them; duplicates are collapsed rather than counted twice. Matched **exactly** at the authorize step against what was registered here.`,
     }),
     client_name: z.string().min(1).max(200).optional().meta({
-        description: 'The name the client calls itself. Optional — a registration without one is recorded under a default name, per RFC 7591\'s making every metadata field optional. It is **not** vouched for by Fleetless and must never be rendered as if it were: a self-registered client chooses this string, and one has called itself *"Fleetless Official Helper"*.',
+        description: 'The name the client calls itself. Optional: RFC 7591 makes every metadata field optional, so a registration without one is recorded under a default name. It is **not** vouched for by Fleetless and must never be rendered as if it were: a self-registered client chooses this string, and one has called itself *"Fleetless Official Helper"*.',
     }),
     token_endpoint_auth_method: z.enum(['none']).optional().meta({
         description: '`none`, RFC 7591\'s value for a public client, and the only value either server registers. Any other value is **refused rather than silently downgraded**: a client that believes it holds a secret and does not has a wrong mental model of its own security. There is no client secret to hold — mandatory PKCE (`S256`) is the defence.',
@@ -257,10 +256,9 @@ export const dynamicClientRegistrationResponse = z.object({
  * from a client we are about to trust, where an unknown key is a caller
  * assuming a feature into existence, while a token request comes from any
  * RFC-compliant client, which may legitimately send parameters this server
- * does not read. Refusing those would be a conformance bug. The consequence
- * is worth stating because it bit the test for this very schema: unknown keys
- * are **stripped**, so `safeParse().success` cannot tell a present field from
- * an absent one. Assert on the parsed value.
+ * does not read. Refusing those would be a conformance bug. Unknown keys are
+ * **stripped**, which bit the test for this schema: `safeParse().success`
+ * cannot tell a present field from an absent one. Assert on the parsed value.
  */
 export const oauthTokenRequest = z
     .object({
@@ -280,7 +278,7 @@ export const oauthTokenRequest = z
         description: 'The PKCE verifier whose `S256` hash was sent as the challenge at the authorize step. Between `43` and `128` unreserved characters, per RFC 7636 §4.1 — it is compared rather than parsed, so a length nobody checks is a length an attacker chooses. PKCE is mandatory for every client under OAuth 2.1.',
     }),
     resource: z.url().optional().meta({
-        description: 'The resource the token is being requested for, per RFC 8707. It must match the audience the code was authorized for, or the answer is `invalid_target`; omitted, the code\'s own audience stands. It becomes the token\'s `aud`, and a resource refuses a token whose audience names something else — which is what keeps a token minted for one app out of another app\'s endpoint.',
+        description: 'The resource the token is requested for, per RFC 8707. It must match the audience the code was authorized for, or the answer is `invalid_target`; omitted, the code\'s own audience stands. It becomes the token\'s `aud`, and a resource refuses a token whose audience names something else — which is what keeps a token minted for one app out of another app\'s endpoint.',
     }),
 })
     .meta({
@@ -325,7 +323,7 @@ export const authorizationServerMetadata = z.object({
         description: 'The issuer identifier of this authorization server, per RFC 8414 §2. It is what a client checks a token\'s `iss` against.',
     }),
     authorization_endpoint: z.url().meta({
-        description: 'The URL a client sends the user to in order to authorize.',
+        description: 'Where a client sends the user to authorize.',
     }),
     token_endpoint: z.url().meta({
         description: 'The URL where a client exchanges an authorization code, or a refresh token, for tokens.',
@@ -438,7 +436,7 @@ export const oauthAuthorizeQuery = z
         description: 'One of the client\'s registered redirect URIs, compared **exactly** — string equality against the registered list, never a prefix or a host match. Both the shape (`redirectUri`) and the registration are checked, and a failure of either is a `400 invalid_request` with no redirect.',
     }),
     code_challenge: z.string().min(1).meta({
-        description: 'The PKCE challenge; the verifier is presented at the token endpoint. Only non-emptiness is checked here — length and alphabet are not — since the verifier is what actually has to match.',
+        description: 'The PKCE challenge; the verifier is presented at the token endpoint. Only non-emptiness is checked here — length and alphabet are not — since the verifier is what has to match.',
     }),
     code_challenge_method: z.literal('S256').meta({
         description: 'Only `S256`. `plain` is refused: a challenge equal to its verifier defends against nothing.',

package/dist/protocol.d.ts

@@ -4,8 +4,8 @@ import { z } from 'zod';
  * Bridge <-> cloud protocol, version 2.
  *
  * The version is exchanged in the hello handshake; the cloud refuses an
- * incompatible bridge with a clear message: `protocol_mismatch`, which names
- * both versions and reaches the robot's detail view as `last_hello_error`.
+ * incompatible bridge: `protocol_mismatch`, which names both versions and
+ * reaches the robot's detail view as `last_hello_error`.
  *
  * **2 (2026-08-21):** `config_applied.errors` entries gained `kind` and `code`
  * beside `message`. The check is `!==`, not a floor, so a bridge that is not
@@ -72,12 +72,11 @@ export { slug } from './common.js';
  *
  * It carries the **slug and the state**, not only the id, because the cloud's
  * reconciliation needs both and had neither. Reading `active_job_ids` as bare
- * uuids, a restarted cloud could answer exactly one question — "is this job
- * still alive?" — for jobs it already knew about. It could not name what the
- * robot is doing, could not tell a job that is still `running` from one that
- * finished while the cloud was down, and had nothing at all to say about a
- * job it never recorded because it crashed between minting the id and writing
- * the row.
+ * uuids, a restarted cloud could only ask "is this job still alive?" for jobs
+ * it already knew about — not what the robot is doing, not whether a
+ * `running` job had actually finished while the cloud was down, and nothing
+ * at all about a job it never recorded because it crashed between minting the
+ * id and writing the row.
  *
  * `state` is the bridge's own current answer, not a history. A bridge that
  * has a terminal result still in hand reports it here and the cloud writes it

package/dist/protocol.js

@@ -10,8 +10,8 @@ import { rosTypeName } from './common.js';
  * Bridge <-> cloud protocol, version 2.
  *
  * The version is exchanged in the hello handshake; the cloud refuses an
- * incompatible bridge with a clear message: `protocol_mismatch`, which names
- * both versions and reaches the robot's detail view as `last_hello_error`.
+ * incompatible bridge: `protocol_mismatch`, which names both versions and
+ * reaches the robot's detail view as `last_hello_error`.
  *
  * **2 (2026-08-21):** `config_applied.errors` entries gained `kind` and `code`
  * beside `message`. The check is `!==`, not a floor, so a bridge that is not
@@ -78,12 +78,11 @@ export { slug } from './common.js';
  *
  * It carries the **slug and the state**, not only the id, because the cloud's
  * reconciliation needs both and had neither. Reading `active_job_ids` as bare
- * uuids, a restarted cloud could answer exactly one question — "is this job
- * still alive?" — for jobs it already knew about. It could not name what the
- * robot is doing, could not tell a job that is still `running` from one that
- * finished while the cloud was down, and had nothing at all to say about a
- * job it never recorded because it crashed between minting the id and writing
- * the row.
+ * uuids, a restarted cloud could only ask "is this job still alive?" for jobs
+ * it already knew about — not what the robot is doing, not whether a
+ * `running` job had actually finished while the cloud was down, and nothing
+ * at all about a job it never recorded because it crashed between minting the
+ * id and writing the row.
  *
  * `state` is the bridge's own current answer, not a history. A bridge that
  * has a terminal result still in hand reports it here and the cloud writes it
@@ -103,22 +102,21 @@ export const bridgeHello = z.object({
     /**
      * Every job this bridge still knows about, right now.
      *
-     * A reconnect and a restart look **identical** on the wire otherwise: same
-     * token, same version, same frame. But they must end differently — after a
-     * dropped connection the running jobs are still running, after a restart
-     * their results are gone forever. Asking the bridge to enumerate what it
-     * still has settles it without either side guessing: the cloud marks every
-     * job it believes is running on this robot and that is *not* named here as
-     * `lost`.
+     * A reconnect and a restart look **identical** on the wire — same token,
+     * same version, same frame — but must end differently: after a dropped
+     * connection the running jobs are still running, after a restart their
+     * results are gone forever. Enumerating what the bridge still has settles
+     * it without either side guessing: the cloud marks every job it believed
+     * running that is *not* named here as `lost`.
      *
-     * This deliberately needs no persistence at the bridge. A live process
-     * lists its live jobs; a process that just started lists none, because it
-     * has none — which is exactly the truth the cloud needs. A breadcrumb file
-     * would only add a window in which the crash beat the write.
+     * Deliberately needs no persistence at the bridge: a live process lists its
+     * live jobs, a process that just started lists none — exactly the truth
+     * the cloud needs. A breadcrumb file would only add a window in which the
+     * crash beat the write.
      *
-     * Defaulted, so a bridge that sends no such field still parses; a bridge
-     * with no jobs and a bridge that does not report them both mean the cloud
-     * has nothing to keep alive.
+     * Defaulted, so a bridge that sends no such field still parses; no jobs
+     * and no report both mean the same thing to the cloud: nothing to keep
+     * alive.
      */
     active_jobs: z.array(activeJob).max(500).default([]),
 });

package/dist/realtime.js

@@ -324,10 +324,10 @@ export const liveSessionEvent = z.object({
     /**
      * **Classified text the cloud produced, never text the robot sent.**
      *
-     * It is **not** the robot's own words. Nothing sanitises
-     * `bridgeCameraState.error.message`, and a camera password reaches a
-     * developer surface through exactly that route — which is why the cloud maps
-     * a robot's diagnosis to fixed strings rather than forwarding it.
+     * Nothing sanitises `bridgeCameraState.error.message`, and a camera
+     * password reaches a developer surface through exactly that route — which
+     * is why the cloud maps a robot's diagnosis to fixed strings rather than
+     * forwarding it.
      *
      * So: `null` unless the cloud itself has something classified to say. If a
      * developer needs the robot's own diagnosis later, it arrives as a mapped

package/dist/rest.js

@@ -23,7 +23,7 @@ export const robot = z.object({
 /** What `PATCH /api/robots/:id` answers: the robot as it now stands. */
 export const patchRobotResponse = z.object({
     robot: robot.meta({
-        description: 'The robot as it now stands, after the patch was applied. The whole resource comes back, not only the fields that changed.',
+        description: 'The robot as it now stands, after the patch. The whole resource comes back, not only the changed fields.',
     }),
 });
 export const createRobotRequest = z.object({
@@ -85,10 +85,10 @@ export const robotListResponse = z.object({
 export const datapointValue = z.object({
     slug: slug.meta({ description: 'The datapoint this value belongs to.' }),
     value: z.unknown().meta({
-        description: 'The value itself, shaped by the datapoint: a number, a boolean, a string, or the whole ROS message where the configuration names no field inside it. Any `scale` and `offset` the configuration declares have already been applied, at the robot.',
+        description: 'The value, shaped by the datapoint: a number, a boolean, a string, or the whole ROS message where the configuration names no field inside it. Any `scale` and `offset` the configuration declares have already been applied, at the robot.',
     }),
     timestamp_ms: z.number().int().nonnegative().meta({
-        description: 'When the value was captured, as a unix timestamp in milliseconds. This is the **bridge\'s capture time**, never the time the cloud received it — the one exception is the built-in `bridge_state`, which the cloud observes by construction.',
+        description: 'When the value was captured, as a unix timestamp in milliseconds. The **bridge\'s capture time**, never the time the cloud received it — the one exception is the built-in `bridge_state`, which the cloud observes by construction.',
     }),
 });
 /* ------------------------------------------------------------------------
@@ -396,7 +396,7 @@ export const invokeResponse = z.object({
 /** A service call answers with its result directly — no job to observe. */
 export const serviceCallResponse = z.object({
     result: z.unknown().meta({
-        description: 'What the service returned, shaped by the ROS service itself. A service call is awaited to completion, so there is no job to observe afterwards and no id to hold on to.',
+        description: 'What the service returned, shaped by the ROS service. A service call is awaited to completion, so there is no job to observe afterwards and no id to hold on to.',
     }),
 });
 /**

package/dist/routes.js

@@ -509,7 +509,7 @@ export const ROUTES = [
         params: [
             { name: 'id', description: 'The app\'s uuid, as returned by `POST /api/apps` or listed by `GET /api/apps`.' },
             { name: 'userId', description: 'The app user\'s uuid, from `GET /api/apps/:id/users`; a user of another app answers `404`.' },
-            { name: 'clientId', description: 'The MCP client, as `GET /api/apps/:id/users/:userId/mcp-grants` reports its `client_id`. Not a uuid — it is the identifier the dynamic registration issued.' },
+            { name: 'clientId', description: 'The MCP client, as `GET /api/apps/:id/users/:userId/mcp-grants` reports its `client_id`. Not a uuid — the identifier dynamic registration issued.' },
         ],
         query: null, request: null, response: null,
         errors: [...DEVELOPER_GUARD, 'invalid_uuid', 'not_found'], transport: 'http',
@@ -1175,8 +1175,8 @@ export const ROUTES = [
             '\n\n**The `405` is this cloud\'s own answer, not the SDK\'s**, and the two differ: MCP SDK 1.30.0 opens an SSE stream on ' +
             '`GET` (`handleGetRequest`) and answers `200` on `DELETE` (`handleDeleteRequest`), neither of which a stateless server has any ' +
             'business doing, so the cloud writes the `405` itself in the transport\'s own JSON-RPC error shape with `Allow: POST`. \n\n**The row exists so that the `405` is not a `404`.** An unregistered verb answers ' +
-            '`404`, and at a path whose last segment is an app identifier a `404` already means *no such app* — one answer for two states, which is ' +
-            'one answer for two states. Registering the verb lets the endpoint say "this app\'s server is here; this verb is not ' +
+            '`404`, and at a path whose last segment is an app identifier a `404` already means *no such app* — so an unregistered verb and an ' +
+            'unknown app would answer identically. Registering the verb lets the endpoint say "this app\'s server is here; this verb is not ' +
             'part of it". The central `/mcp` registers neither verb and does not need to: its path takes no parameter, so nothing can misread its ' +
             '`404`. \n\n**The `405` body is the transport\'s JSON-RPC error object, not the `apiError` envelope.** The three codes above are the ' +
             'refusals that come *first* — the app, its switch, then the bearer, in the order `POST` describes — and they are `apiError` because ' +
@@ -1628,7 +1628,7 @@ export const ROUTES = [
         method: 'DELETE', path: '/api/client/mcp/grants/:clientId', section: 'client-auth',
         summary: 'Withdraws the signed-in app user\'s consent to one MCP client.',
         audience: 'client', auth: 'developer_or_client', rateLimited: false, ownerTier: false, status: 204,
-        params: [{ name: 'clientId', description: 'The MCP client, as `GET /api/client/mcp/grants` reports its `client_id`. Not a uuid — it is the identifier the dynamic registration issued.' }],
+        params: [{ name: 'clientId', description: 'The MCP client, as `GET /api/client/mcp/grants` reports its `client_id`. Not a uuid — the identifier dynamic registration issued.' }],
         query: null, request: null, response: null, errors: [...CLIENT_GUARD], transport: 'http',
         notes: 'The person\'s own door, beside the developer\'s `DELETE /api/apps/:id/users/:userId/mcp-grants/:clientId`. It acts on the bearer\'s ' +
             'own account and on no other — the path carries a client and never a subject — so there is no user for a caller to name and none to ' +
@@ -1934,8 +1934,8 @@ export const ROUTES = [
         query: jobRunQuery, request: null, response: jobRunListResponse,
         errors: [...CLIENT_GUARD, 'invalid_uuid', 'not_found', 'capability_required', 'validation_error'], transport: 'http',
         notes: 'Needs the `action_history` capability, and **this route is what makes that switch mean something** — it was unkeepable while nothing ' +
-            'durable recorded what had run. Two residuals worth stating rather than implying away. `history` is a syntactically valid slug and ' +
-            'The router matches a static segment first, so a robot with a service literally slugged `history` can no longer be **read** through ' +
+            'durable recorded what had run. Two residuals worth stating rather than implying away. `history` is a syntactically valid slug, and ' +
+            'a static segment matches before a parameter, so a robot with a service literally slugged `history` can no longer be **read** through ' +
             '`GET /api/robots/:id/jobs/:slug`; invoking, cancelling and the listing are unaffected. And a run row names its actor by email address, ' +
             'so an end user holding this capability learns which other people have been driving the machine. `robot_id` in the query is shared with ' +
             'the org-wide read; a *different* one here is refused rather than quietly answered about the robot in the path.',
@@ -1946,7 +1946,7 @@ export const ROUTES = [
         audience: 'client', auth: 'developer_or_client', rateLimited: false, ownerTier: false, status: 202,
         params: [
             { name: 'id', description: 'The robot\'s uuid; an end user reaches it through an app that attaches it.' },
-            { name: 'slug', description: 'The action or service slug from the published configuration; the cloud already knows which kind it is.' },
+            { name: 'slug', description: 'The action or service slug from the published configuration — the cloud already knows which kind.' },
         ],
         query: null, request: invokeRequest, response: invokeOrServiceResponse,
         errors: [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fleetless/contracts",
-  "version": "1.0.4",
+  "version": "1.0.6",
   "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",
@@ -52,6 +52,7 @@
     "test": "vitest run",
     "artifacts": "tsx scripts/export-schemas.ts",
     "test:pack": "node scripts/verify-pack.mjs",
+    "verify:commits": "node scripts/verify-commit-messages.mjs",
     "prepublishOnly": "node scripts/refuse-manual-publish.mjs"
   },
   "dependencies": {