@fleetless/contracts 5.0.0-next.2 → 5.1.0-next.1

package/CHANGELOG.md

@@ -11,6 +11,19 @@ version.
 
 ### Added
 
+- **`cancelRejectedDetails`** (`CancelRejectedDetails`): the `details` of a
+  `cancel_rejected` refusal, `{ goals }` with at least one `{ job_id,
+  goal_id, return_code }` — every goal the cancel reached, accepted ones
+  included, with its `CancelGoal` return code (`CANCEL_RETURN_CODES`, or
+  `null` when that goal's server did not answer). A consumer parses the
+  refusal instead of reading its shape from prose. Published as the
+  artifact `cancel-rejected-details`. The wire does not change: the cloud
+  already sends this shape.
+
+## [5.0.0] — 2026-09-30
+
+### Added
+
 - **Protocol 5: `unknown` jobs, external goals, and a hard cut of protocols 3
   and 4.** `PROTOCOL_VERSION` is 5 and the only version served: protocols 2,
   3 and 4 are unsupported from this release on, with no sunset window, and
@@ -40,6 +53,9 @@ version.
   caller is refused, not told the cancel succeeded. `reportedJobState`, every
   state but `unknown`, is what `job_update`, `job_status` entries and
   `hello.active_jobs` accept, so a bridge claiming `unknown` fails validation.
+  `POST /api/robots/:id/jobs/:slug/cancel` lists the answers this adds:
+  `409 cancel_rejected`, `504 bridge_timeout`, and `502` with the bridge's
+  own code (`unknown_slug`, `action_server_lost`, `internal_error`).
 
 ### Removed
 

package/artifacts/openapi.json

@@ -7003,7 +7003,7 @@
             }
           },
           "default": {
-            "description": "An error envelope. Codes this route is known to answer: `unauthorized`, `token_expired`, `token_revoked`, `forbidden`, `invalid_uuid`, `not_found`, `validation_error`, `not_cancellable`, `robot_offline`.",
+            "description": "An error envelope. Codes this route is known to answer: `unauthorized`, `token_expired`, `token_revoked`, `forbidden`, `invalid_uuid`, `not_found`, `validation_error`, `not_cancellable`, `robot_offline`, `cancel_rejected`, `bridge_timeout`, `unknown_slug`, `action_server_lost`, `internal_error`.",
             "content": {
               "application/json": {
                 "schema": {
@@ -7013,7 +7013,7 @@
             }
           }
         },
-        "description": "The body is optional: a bodyless `POST` was every caller's shape before `job_id` existed, and absent or `job_id: null` both mean \"cancel whatever is running\". A named `job_id` that is **not** what is running cancels nothing and answers `404` — the caller named an id and thereby ruled the other one out. An `external` job is cancelled the same way, through its goal id. Cancelling an `unknown` job also cancels every external goal on its action, since one of them may be that job. A service is `422 not_cancellable`: a service call has no goal to cancel. Nothing running is a `200` with `job: null`.",
+        "description": "The body is optional: a bodyless `POST` was every caller's shape before `job_id` existed, and absent or `job_id: null` both mean \"cancel whatever is running\". A named `job_id` that is **not** what is running cancels nothing and answers `404` — the caller named an id and thereby ruled the other one out. An `external` job is cancelled the same way, through its goal id. Cancelling an `unknown` job also cancels every external goal on its action, since one of them may be that job. A service is `422 not_cancellable`: a service call has no goal to cancel. Nothing running is a `200` with `job: null`. The answer waits for the bridge's `cancel_result`: a `200` means the action server accepted the cancel request, not that the goal has ended — the job's end arrives as its own update. Any goal answered `ERROR_REJECTED` makes it `409 cancel_rejected`, with every goal and its `return_code` in `details.goals`; no answer within `JOB_HEARTBEAT_TIMEOUT_MS` is `504 bridge_timeout`; a cancel the bridge could not send at all is `502` carrying the bridge's own code (`unknown_slug`, `action_server_lost`, `internal_error`).",
         "requestBody": {
           "required": false,
           "content": {

package/artifacts/routes.json

@@ -4147,10 +4147,15 @@
         "not_found",
         "validation_error",
         "not_cancellable",
-        "robot_offline"
+        "robot_offline",
+        "cancel_rejected",
+        "bridge_timeout",
+        "unknown_slug",
+        "action_server_lost",
+        "internal_error"
       ],
       "transport": "http",
-      "notes": "The body is optional: a bodyless `POST` was every caller's shape before `job_id` existed, and absent or `job_id: null` both mean \"cancel whatever is running\". A named `job_id` that is **not** what is running cancels nothing and answers `404` — the caller named an id and thereby ruled the other one out. An `external` job is cancelled the same way, through its goal id. Cancelling an `unknown` job also cancels every external goal on its action, since one of them may be that job. A service is `422 not_cancellable`: a service call has no goal to cancel. Nothing running is a `200` with `job: null`."
+      "notes": "The body is optional: a bodyless `POST` was every caller's shape before `job_id` existed, and absent or `job_id: null` both mean \"cancel whatever is running\". A named `job_id` that is **not** what is running cancels nothing and answers `404` — the caller named an id and thereby ruled the other one out. An `external` job is cancelled the same way, through its goal id. Cancelling an `unknown` job also cancels every external goal on its action, since one of them may be that job. A service is `422 not_cancellable`: a service call has no goal to cancel. Nothing running is a `200` with `job: null`. The answer waits for the bridge's `cancel_result`: a `200` means the action server accepted the cancel request, not that the goal has ended — the job's end arrives as its own update. Any goal answered `ERROR_REJECTED` makes it `409 cancel_rejected`, with every goal and its `return_code` in `details.goals`; no answer within `JOB_HEARTBEAT_TIMEOUT_MS` is `504 bridge_timeout`; a cancel the bridge could not send at all is `502` carrying the bridge's own code (`unknown_slug`, `action_server_lost`, `internal_error`)."
     },
     {
       "method": "POST",

package/artifacts/schema/cancel-rejected-details.schema.json

@@ -0,0 +1,46 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "goals": {
+      "minItems": 1,
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "job_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)$"
+          },
+          "goal_id": {
+            "type": "string",
+            "minLength": 1
+          },
+          "return_code": {
+            "anyOf": [
+              {
+                "type": "integer",
+                "minimum": 0,
+                "maximum": 3
+              },
+              {
+                "type": "null"
+              }
+            ]
+          }
+        },
+        "required": [
+          "job_id",
+          "goal_id",
+          "return_code"
+        ],
+        "additionalProperties": false
+      }
+    }
+  },
+  "required": [
+    "goals"
+  ],
+  "additionalProperties": false
+}

package/dist/errors.d.ts

@@ -44,6 +44,25 @@ export declare const parameterInvalidDetails: z.ZodObject<{
     }, z.core.$strip>>;
 }, z.core.$strip>;
 export type ParameterInvalidDetails = z.infer<typeof parameterInvalidDetails>;
+/**
+ * The `details` of a `cancel_rejected` refusal: every goal the cancel reached,
+ * accepted ones included, each with the `CancelGoal` return code its action
+ * server answered — compare `return_code` against `CANCEL_RETURN_CODES`
+ * (`none`, `rejected`, `unknown_goal_id`, `goal_terminated`); it is `null`
+ * when that goal's server did not answer within the bridge's bound. Always at
+ * least one goal: the cloud refuses a cancel only because a goal's server
+ * answered `ERROR_REJECTED`. Pinned here for the reason
+ * `parameterInvalidDetails` is: a caller parses it instead of reading the
+ * shape from prose.
+ */
+export declare const cancelRejectedDetails: z.ZodObject<{
+    goals: z.ZodArray<z.ZodObject<{
+        job_id: z.ZodUUID;
+        goal_id: z.ZodString;
+        return_code: z.ZodNullable<z.ZodNumber>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type CancelRejectedDetails = z.infer<typeof cancelRejectedDetails>;
 /**
  * The codes in use today. The wire deliberately allows any string — this
  * list is the shared vocabulary, not a closed set, so a new refusal never

package/dist/errors.js

@@ -1,5 +1,6 @@
 // SPDX-License-Identifier: Apache-2.0
 import { z } from 'zod';
+import { bridgeCancelResultEntry } from './protocol.js';
 /**
  * The one error shape of the REST and realtime APIs: a stable
  * machine-readable code plus a human message; validation errors name the
@@ -38,6 +39,20 @@ export const parameterViolation = z.object({
 export const parameterInvalidDetails = z.object({
     violations: z.array(parameterViolation).min(1),
 });
+/**
+ * The `details` of a `cancel_rejected` refusal: every goal the cancel reached,
+ * accepted ones included, each with the `CancelGoal` return code its action
+ * server answered — compare `return_code` against `CANCEL_RETURN_CODES`
+ * (`none`, `rejected`, `unknown_goal_id`, `goal_terminated`); it is `null`
+ * when that goal's server did not answer within the bridge's bound. Always at
+ * least one goal: the cloud refuses a cancel only because a goal's server
+ * answered `ERROR_REJECTED`. Pinned here for the reason
+ * `parameterInvalidDetails` is: a caller parses it instead of reading the
+ * shape from prose.
+ */
+export const cancelRejectedDetails = z.object({
+    goals: z.array(bridgeCancelResultEntry).min(1),
+});
 /**
  * The codes in use today. The wire deliberately allows any string — this
  * list is the shared vocabulary, not a closed set, so a new refusal never

package/dist/index.d.ts

@@ -45,8 +45,8 @@ export { auditActor, auditEvent, auditQuery, auditListResponse, AUDIT_CSV_COLUMN
 export type { AuditActor, AuditEvent, AuditQuery, AuditListResponse } from './audit.js';
 export { alertRowCondition, alertSeverity, alertState, datapointAlertRow, alertListResponse, orgFiringAlertsResponse, orgAlertsQuery, datapointDisplay, putDatapointDisplayRequest, } from './alerts.js';
 export type { AlertRowCondition, AlertSeverity, AlertState, DatapointAlertRow, AlertListResponse, OrgFiringAlertsResponse, OrgAlertsQuery, DatapointDisplay, PutDatapointDisplayRequest, } from './alerts.js';
-export { apiError, parameterViolation, parameterInvalidDetails, ERROR_CODES } from './errors.js';
-export type { ApiError, ParameterViolation, ParameterInvalidDetails, ErrorCode } from './errors.js';
+export { apiError, parameterViolation, parameterInvalidDetails, cancelRejectedDetails, ERROR_CODES } from './errors.js';
+export type { ApiError, ParameterViolation, ParameterInvalidDetails, CancelRejectedDetails, ErrorCode } from './errors.js';
 export { oauthErrorCode, oauthError, oauthRedirectResponse, oauthCodeTokenRequest, oauthRefreshTokenRequest, oauthTokenRequest, oauthTokenResponse, redirectUri, codeChallengeMethod, oauthAuthorizeQuery, dynamicClientRegistrationRequest, MCP_DCR_MAX_REDIRECT_URIS, dynamicClientRegistrationResponse, authorizationServerMetadata, protectedResourceMetadata, } from './oauth.js';
 export type { OauthErrorCode, OauthError, OauthRedirectResponse, OauthCodeTokenRequest, OauthRefreshTokenRequest, OauthTokenRequest, OauthTokenResponse, RedirectUri, OauthAuthorizeQuery, DynamicClientRegistrationRequest, DynamicClientRegistrationResponse, AuthorizationServerMetadata, ProtectedResourceMetadata, } from './oauth.js';
 export { ROUTES, ROUTE_SECTIONS, IN_HANDLER_ROUTES } from './routes.js';

package/dist/index.js

@@ -46,6 +46,6 @@ export { APP_USER_DISPLAY_NAME_MAX, APP_URL_PLACEHOLDERS, MAIL_TEMPLATE_VARIABLE
 export { assetKind, URDF_ASSET_NAME, asset, urdfCompleteness, assetListResponse, assetsClearResponse, missingAssetQuery, assetSyncRequest, assetSyncResponse, assetSyncState, assetSyncStatus, assetFailure, assetFailureKind, assetStoreRefusedDetails, assetSyncBusyDetails, ROBOT_ASSET_STORE_BYTES, } from './assets.js';
 export { auditActor, auditEvent, auditQuery, auditListResponse, AUDIT_CSV_COLUMNS, AUDIT_RETENTION_DAYS } from './audit.js';
 export { alertRowCondition, alertSeverity, alertState, datapointAlertRow, alertListResponse, orgFiringAlertsResponse, orgAlertsQuery, datapointDisplay, putDatapointDisplayRequest, } from './alerts.js';
-export { apiError, parameterViolation, parameterInvalidDetails, ERROR_CODES } from './errors.js';
+export { apiError, parameterViolation, parameterInvalidDetails, cancelRejectedDetails, ERROR_CODES } from './errors.js';
 export { oauthErrorCode, oauthError, oauthRedirectResponse, oauthCodeTokenRequest, oauthRefreshTokenRequest, oauthTokenRequest, oauthTokenResponse, redirectUri, codeChallengeMethod, oauthAuthorizeQuery, dynamicClientRegistrationRequest, MCP_DCR_MAX_REDIRECT_URIS, dynamicClientRegistrationResponse, authorizationServerMetadata, protectedResourceMetadata, } from './oauth.js';
 export { ROUTES, ROUTE_SECTIONS, IN_HANDLER_ROUTES } from './routes.js';

package/dist/routes.js

@@ -2112,12 +2112,19 @@ export const ROUTES = [
             { name: 'slug', description: 'The action slug from the published configuration; a service slug is refused.' },
         ],
         query: null, request: cancelRequest, requestOptional: true, response: jobResponse,
-        errors: [...CLIENT_GUARD, 'invalid_uuid', 'not_found', 'validation_error', 'not_cancellable', 'robot_offline'], transport: 'http',
+        errors: [
+            ...CLIENT_GUARD, 'invalid_uuid', 'not_found', 'validation_error', 'not_cancellable', 'robot_offline',
+            'cancel_rejected', 'bridge_timeout', 'unknown_slug', 'action_server_lost', 'internal_error',
+        ], transport: 'http',
         notes: 'The body is optional: a bodyless `POST` was every caller\'s shape before `job_id` existed, and absent or `job_id: null` both mean ' +
             '"cancel whatever is running". A named `job_id` that is **not** what is running cancels nothing and answers `404` — the caller named an ' +
             'id and thereby ruled the other one out. An `external` job is cancelled the same way, through its goal id. Cancelling an `unknown` job ' +
             'also cancels every external goal on its action, since one of them may be that job. A service is `422 not_cancellable`: a service call ' +
-            'has no goal to cancel. Nothing running is a `200` with `job: null`.',
+            'has no goal to cancel. Nothing running is a `200` with `job: null`. The answer waits for the bridge\'s `cancel_result`: a `200` means ' +
+            'the action server accepted the cancel request, not that the goal has ended — the job\'s end arrives as its own update. Any goal ' +
+            'answered `ERROR_REJECTED` makes it `409 cancel_rejected`, with every goal and its `return_code` in `details.goals`; no answer within ' +
+            '`JOB_HEARTBEAT_TIMEOUT_MS` is `504 bridge_timeout`; a cancel the bridge could not send at all is `502` carrying the bridge\'s own ' +
+            'code (`unknown_slug`, `action_server_lost`, `internal_error`).',
     },
     {
         method: 'POST', path: '/api/robots/:id/publishers/:slug', section: 'commands',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fleetless/contracts",
-  "version": "5.0.0-next.2",
+  "version": "5.1.0-next.1",
   "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",