@fleetless/contracts 5.0.0-next.1 → 5.0.0

package/CHANGELOG.md

@@ -9,6 +9,8 @@ version.
 
 ## [Unreleased]
 
+## [5.0.0] — 2026-09-30
+
 ### Added
 
 - **Protocol 5: `unknown` jobs, external goals, and a hard cut of protocols 3
@@ -29,13 +31,27 @@ version.
   `hello_error` for a bridge below protocol 5, naming bridge `6.0.0`; and
   `job_unknown_to_bridge`, the final `lost` reason when the bridge does not
   know a job and nothing it cannot attribute runs on the job's action.
+- **A cancel is answered with each goal's `CancelGoal` return code.**
+  `cancel` gains a required `request_id`; the bridge answers with the new
+  frame `cancel_result` (`bridgeCancelResult`, `bridgeCancelResultEntry`):
+  every goal the cancel reached, with its `job_id`, `goal_id` and
+  `return_code` (`CANCEL_RETURN_CODES`, `null` when the server did not
+  answer). A cancel naming a `job_id` the bridge does not hold cancels every
+  external goal on the action, never one of the bridge's own jobs. New error
+  code `cancel_rejected`: the server answered `ERROR_REJECTED`, and the
+  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
 
 - **Protocols 2, 3 and 4, and an origin-less `job`; this is why the release
   is a major.** A bridge below `6.0.0` is refused at `hello`, and a `job` or
   `job_update` literal without `origin` (or a `job_update` without
-  `goal_id`) no longer parses.
+  `goal_id`) no longer parses, nor does a `cancel` without `request_id`.
 
 ## [4.0.0] — 2026-09-29
 

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/bridge-cancel-result.schema.json

@@ -0,0 +1,86 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "type": {
+      "type": "string",
+      "const": "cancel_result"
+    },
+    "request_id": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 64
+    },
+    "slug": {
+      "type": "string",
+      "minLength": 2,
+      "maxLength": 63,
+      "pattern": "^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$"
+    },
+    "goals": {
+      "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"
+        ]
+      }
+    },
+    "error": {
+      "anyOf": [
+        {
+          "type": "object",
+          "properties": {
+            "code": {
+              "type": "string",
+              "minLength": 1
+            },
+            "message": {
+              "type": "string",
+              "minLength": 1
+            }
+          },
+          "required": [
+            "code",
+            "message"
+          ]
+        },
+        {
+          "type": "null"
+        }
+      ]
+    }
+  },
+  "required": [
+    "type",
+    "request_id",
+    "slug",
+    "goals",
+    "error"
+  ]
+}

package/artifacts/schema/bridge-hello.schema.json

@@ -41,7 +41,6 @@
             "type": "string",
             "enum": [
               "running",
-              "unknown",
               "succeeded",
               "failed",
               "cancelled",

package/artifacts/schema/bridge-job-status.schema.json

@@ -25,7 +25,6 @@
             "type": "string",
             "enum": [
               "running",
-              "unknown",
               "succeeded",
               "failed",
               "cancelled",

package/artifacts/schema/bridge-job-update.schema.json

@@ -21,7 +21,6 @@
       "type": "string",
       "enum": [
         "running",
-        "unknown",
         "succeeded",
         "failed",
         "cancelled",

package/artifacts/schema/cloud-cancel.schema.json

@@ -6,6 +6,11 @@
       "type": "string",
       "const": "cancel"
     },
+    "request_id": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 64
+    },
     "slug": {
       "type": "string",
       "minLength": 2,
@@ -27,6 +32,7 @@
   },
   "required": [
     "type",
+    "request_id",
     "slug",
     "job_id"
   ]

package/artifacts/schema-outgoing/bridge-cancel-result.schema.json

@@ -0,0 +1,89 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "type": {
+      "type": "string",
+      "const": "cancel_result"
+    },
+    "request_id": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 64
+    },
+    "slug": {
+      "type": "string",
+      "minLength": 2,
+      "maxLength": 63,
+      "pattern": "^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$"
+    },
+    "goals": {
+      "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
+      }
+    },
+    "error": {
+      "anyOf": [
+        {
+          "type": "object",
+          "properties": {
+            "code": {
+              "type": "string",
+              "minLength": 1
+            },
+            "message": {
+              "type": "string",
+              "minLength": 1
+            }
+          },
+          "required": [
+            "code",
+            "message"
+          ],
+          "additionalProperties": false
+        },
+        {
+          "type": "null"
+        }
+      ]
+    }
+  },
+  "required": [
+    "type",
+    "request_id",
+    "slug",
+    "goals",
+    "error"
+  ],
+  "additionalProperties": false
+}

package/artifacts/schema-outgoing/bridge-hello.schema.json

@@ -41,7 +41,6 @@
             "type": "string",
             "enum": [
               "running",
-              "unknown",
               "succeeded",
               "failed",
               "cancelled",

package/artifacts/schema-outgoing/bridge-job-status.schema.json

@@ -25,7 +25,6 @@
             "type": "string",
             "enum": [
               "running",
-              "unknown",
               "succeeded",
               "failed",
               "cancelled",

package/artifacts/schema-outgoing/bridge-job-update.schema.json

@@ -21,7 +21,6 @@
       "type": "string",
       "enum": [
         "running",
-        "unknown",
         "succeeded",
         "failed",
         "cancelled",

package/dist/errors.d.ts

@@ -49,5 +49,5 @@ export type ParameterInvalidDetails = z.infer<typeof parameterInvalidDetails>;
  * list is the shared vocabulary, not a closed set, so a new refusal never
  * needs a contracts release before it can be reported honestly.
  */
-export declare const ERROR_CODES: readonly ["not_found", "validation_error", "bad_request", "unknown_datapoint", "invalid_token", "protocol_mismatch", "bridge_too_old", "invalid_frame", "duplicate_slug", "reserved_slug", "unknown_slug", "unknown_field_path", "unknown_type", "unknown_topic", "invalid_rate", "invalid_range", "config_conflict", "no_data", "robot_offline", "bridge_timeout", "unauthorized", "forbidden", "invalid_credentials", "token_expired", "token_revoked", "email_taken", "identifier_taken", "weak_password", "account_blocked", "busy", "parameter_invalid", "job_lost", "job_unknown_to_bridge", "action_server_lost", "action_failed", "goal_rejected", "goal_send_failed", "result_failed", "goal_uncontrollable", "bridge_disconnected", "config_changed", "publisher_busy", "unknown_command", "not_subscribable", "camera_offline", "no_snapshot_yet", "live_unavailable", "wrong_kind", "not_recorded", "not_aggregatable", "quota_exceeded", "credential_in_use", "goal_timeout", "robot_in_use", "robot_deletion_partial", "job_queue_full", "invalid_uuid", "rate_limited", "tier_required", "token_spent", "service_timeout", "asset_missing", "dynamic_registration_disabled", "client_limit_reached", "idp_unavailable", "mcp_disabled", "tool_not_available", "capability_required", "last_owner", "target_state_conflict", "signup_closed", "draft_not_a_document", "internal_error", "not_cancellable", "unsupported_media_type", "wrong_browser", "invalid_yaml", "unstorable_yaml", "registration_closed", "domain_not_allowed", "email_unverified", "origin_not_allowed", "template_invalid", "provider_disabled", "provider_misconfigured", "invalid_redirect_uri", "interaction_expired"];
+export declare const ERROR_CODES: readonly ["not_found", "validation_error", "bad_request", "unknown_datapoint", "invalid_token", "protocol_mismatch", "bridge_too_old", "invalid_frame", "duplicate_slug", "reserved_slug", "unknown_slug", "unknown_field_path", "unknown_type", "unknown_topic", "invalid_rate", "invalid_range", "config_conflict", "no_data", "robot_offline", "bridge_timeout", "unauthorized", "forbidden", "invalid_credentials", "token_expired", "token_revoked", "email_taken", "identifier_taken", "weak_password", "account_blocked", "busy", "parameter_invalid", "cancel_rejected", "job_lost", "job_unknown_to_bridge", "action_server_lost", "action_failed", "goal_rejected", "goal_send_failed", "result_failed", "goal_uncontrollable", "bridge_disconnected", "config_changed", "publisher_busy", "unknown_command", "not_subscribable", "camera_offline", "no_snapshot_yet", "live_unavailable", "wrong_kind", "not_recorded", "not_aggregatable", "quota_exceeded", "credential_in_use", "goal_timeout", "robot_in_use", "robot_deletion_partial", "job_queue_full", "invalid_uuid", "rate_limited", "tier_required", "token_spent", "service_timeout", "asset_missing", "dynamic_registration_disabled", "client_limit_reached", "idp_unavailable", "mcp_disabled", "tool_not_available", "capability_required", "last_owner", "target_state_conflict", "signup_closed", "draft_not_a_document", "internal_error", "not_cancellable", "unsupported_media_type", "wrong_browser", "invalid_yaml", "unstorable_yaml", "registration_closed", "domain_not_allowed", "email_unverified", "origin_not_allowed", "template_invalid", "provider_disabled", "provider_misconfigured", "invalid_redirect_uri", "interaction_expired"];
 export type ErrorCode = (typeof ERROR_CODES)[number];

package/dist/errors.js

@@ -156,6 +156,14 @@ export const ERROR_CODES = [
     'busy',
     /** A parameter failed its declared rule; details name the field and the rule. */
     'parameter_invalid',
+    /**
+     * The action server refused a cancel request — `CancelGoal` answered
+     * `ERROR_REJECTED` (the bridge's `cancel_result`). The caller's cancel is
+     * refused with this code, never reported as success; `details.goals` carry
+     * each goal's `job_id`, `goal_id` and `return_code`. Whether the goal ends
+     * anyway is what its `job_update` says afterwards.
+     */
+    'cancel_rejected',
     /**
      * The bridge's own statement, while connected, that it lost track of a job
      * it still names — the vocabulary behind its `job_lost` frame. Distinct

package/dist/index.d.ts

@@ -3,10 +3,10 @@ export { SLUG_RULE, ROS_NAME_RULE, ROS_TYPE_NAME_RULE, FIELD_PATH_RULE, slug, ro
 export type { ApplyErrorKind, ApplyError } from './common.js';
 export { MCP_PROTOCOL_VERSION, MCP_ENDPOINT_PATH, mcpAppEndpointPath, MCP_APP_PATHS, MCP_TOOL_NAME_MAX, MCP_ASSET_LINK_PATH, MCP_ASSET_LINK_TTL_MS, mcpToolNamePattern, mcpToolKind, mcpExposure, mcpCapabilities, mcpRobotDatasheet, mcpRolePreviewResponse, } from './mcp.js';
 export type { McpAppPaths, McpToolKind, McpExposure, McpCapabilities, McpRobotDatasheet, McpRolePreviewResponse, } from './mcp.js';
-export { PROTOCOL_VERSION, PROTOCOL_VERSIONS, PROTOCOL_SUNSET_DAYS, LATEST_BRIDGE_VERSION, protocolStatus, minimumProtocolVersion, sunsetOf, statusFromTable, bridgeHello, cloudHelloOk, cloudHelloError, cloudPing, bridgePong, bridgeLinkMode, datapointFrame, bridgeState, cloudConfig, bridgeConfigApplied, cloudIntrospectRequest, bridgeIntrospect, cloudTypeRequest, bridgeTypeDefinitions, cloudInvoke, cloudCancel, cloudPublish, bridgeJobUpdate, bridgeJobLost, cloudJobQuery, bridgeJobStatusEntry, bridgeJobStatus, snapshotHeader, cloudCameraStart, cloudCameraStop, bridgeCameraState, SNAPSHOT_MAX_BYTES, CLOSE_ROBOT_DELETED, CLOSE_TOKEN_ROTATED, bridgeAssetsAvailable, cloudAssetRequest, bridgeAssetProgress, activeJob, DEFAULT_PATIENCE_MS, MAX_PATIENCE_MS, MIN_PATIENCE_MS, JOB_HEARTBEAT_INTERVAL_MS, JOB_HEARTBEAT_TIMEOUT_MS, JOB_OFFLINE_GRACE_MS, } from './protocol.js';
-export type { ProtocolVersionEntry, ProtocolStatus, BridgeHello, CloudHelloOk, CloudHelloError, CloudPing, BridgePong, BridgeLinkMode, DatapointFrame, BridgeState, CloudConfig, BridgeConfigApplied, CloudIntrospectRequest, BridgeIntrospect, CloudTypeRequest, BridgeTypeDefinitions, CloudInvoke, CloudCancel, CloudPublish, BridgeJobUpdate, BridgeJobLost, CloudJobQuery, BridgeJobStatusEntry, BridgeJobStatus, SnapshotHeader, CloudCameraStart, CloudCameraStop, BridgeCameraState, ActiveJob, BridgeAssetsAvailable, CloudAssetRequest, BridgeAssetProgress, } from './protocol.js';
-export { jobState, jobOrigin, job, jobEvent, busyDetails, publisherBusyDetails, jobQueueFullDetails } from './jobs.js';
-export type { JobState, JobOrigin, Job, JobEvent, BusyDetails, PublisherBusyDetails, JobQueueFullDetails, } from './jobs.js';
+export { PROTOCOL_VERSION, PROTOCOL_VERSIONS, PROTOCOL_SUNSET_DAYS, LATEST_BRIDGE_VERSION, protocolStatus, minimumProtocolVersion, sunsetOf, statusFromTable, bridgeHello, cloudHelloOk, cloudHelloError, cloudPing, bridgePong, bridgeLinkMode, datapointFrame, bridgeState, cloudConfig, bridgeConfigApplied, cloudIntrospectRequest, bridgeIntrospect, cloudTypeRequest, bridgeTypeDefinitions, cloudInvoke, cloudCancel, CANCEL_RETURN_CODES, cancelReturnCode, bridgeCancelResultEntry, bridgeCancelResult, cloudPublish, bridgeJobUpdate, bridgeJobLost, cloudJobQuery, bridgeJobStatusEntry, bridgeJobStatus, snapshotHeader, cloudCameraStart, cloudCameraStop, bridgeCameraState, SNAPSHOT_MAX_BYTES, CLOSE_ROBOT_DELETED, CLOSE_TOKEN_ROTATED, bridgeAssetsAvailable, cloudAssetRequest, bridgeAssetProgress, activeJob, DEFAULT_PATIENCE_MS, MAX_PATIENCE_MS, MIN_PATIENCE_MS, JOB_HEARTBEAT_INTERVAL_MS, JOB_HEARTBEAT_TIMEOUT_MS, JOB_OFFLINE_GRACE_MS, } from './protocol.js';
+export type { ProtocolVersionEntry, ProtocolStatus, BridgeHello, CloudHelloOk, CloudHelloError, CloudPing, BridgePong, BridgeLinkMode, DatapointFrame, BridgeState, CloudConfig, BridgeConfigApplied, CloudIntrospectRequest, BridgeIntrospect, CloudTypeRequest, BridgeTypeDefinitions, CloudInvoke, CloudCancel, CancelReturnCode, BridgeCancelResultEntry, BridgeCancelResult, CloudPublish, BridgeJobUpdate, BridgeJobLost, CloudJobQuery, BridgeJobStatusEntry, BridgeJobStatus, SnapshotHeader, CloudCameraStart, CloudCameraStop, BridgeCameraState, ActiveJob, BridgeAssetsAvailable, CloudAssetRequest, BridgeAssetProgress, } from './protocol.js';
+export { jobState, reportedJobState, jobOrigin, job, jobEvent, busyDetails, publisherBusyDetails, jobQueueFullDetails } from './jobs.js';
+export type { JobState, ReportedJobState, JobOrigin, Job, JobEvent, BusyDetails, PublisherBusyDetails, JobQueueFullDetails, } from './jobs.js';
 export { JOB_RUN_PAGE_MAX, JOB_RUN_RETENTION_DAYS, jobActor, jobRunKind, jobRun, jobRunQuery, jobRunListResponse, jobRunSummaryQuery, jobRunSummary, } from './jobs.js';
 export type { JobActor, JobRunKind, JobRun, JobRunQuery, JobRunListResponse, JobRunSummary } from './jobs.js';
 export { FLEETLESS_FORMAT_VERSION, RESERVED_SLUGS, parameterType, parameterSpec, parameterMap, serviceDescription, parameterDescription, messageTemplate, messageRef, messageBody, messageMap, PLACEHOLDER_RE, placeholderNames, actionConfig, serviceConfig, publisherConfig, cameraConfig, alertCondition, datapointAlert, rateThrottleHz, datapointNumeric, datapointRetention, datapointChart, datapointConfig, lowBandwidthSection, LOW_BANDWIDTH_DEFAULTS, robotConfigDoc, validationIssue, configState, snapshotIntervalSeconds, ALERT_SEVERITY_DEFAULT, ALERT_ENABLED_DEFAULT, RETENTION_INTERVAL_SECONDS_DEFAULT, CHART_WINDOW_MINUTES_DEFAULT, cameraSource, cameraCredentials, } from './config.js';

package/dist/index.js

@@ -1,12 +1,12 @@
 // SPDX-License-Identifier: Apache-2.0
 export { SLUG_RULE, ROS_NAME_RULE, ROS_TYPE_NAME_RULE, FIELD_PATH_RULE, slug, rosName, rosTypeName, fieldPath, wireSeqCursor, wireTimestampMs, applyErrorKind, applyError, } from './common.js';
 export { MCP_PROTOCOL_VERSION, MCP_ENDPOINT_PATH, mcpAppEndpointPath, MCP_APP_PATHS, MCP_TOOL_NAME_MAX, MCP_ASSET_LINK_PATH, MCP_ASSET_LINK_TTL_MS, mcpToolNamePattern, mcpToolKind, mcpExposure, mcpCapabilities, mcpRobotDatasheet, mcpRolePreviewResponse, } from './mcp.js';
-export { PROTOCOL_VERSION, PROTOCOL_VERSIONS, PROTOCOL_SUNSET_DAYS, LATEST_BRIDGE_VERSION, protocolStatus, minimumProtocolVersion, sunsetOf, statusFromTable, bridgeHello, cloudHelloOk, cloudHelloError, cloudPing, bridgePong, bridgeLinkMode, datapointFrame, bridgeState, cloudConfig, bridgeConfigApplied, cloudIntrospectRequest, bridgeIntrospect, cloudTypeRequest, bridgeTypeDefinitions, cloudInvoke, cloudCancel, cloudPublish, bridgeJobUpdate, bridgeJobLost, cloudJobQuery, bridgeJobStatusEntry, bridgeJobStatus, snapshotHeader, cloudCameraStart, cloudCameraStop, bridgeCameraState, SNAPSHOT_MAX_BYTES, CLOSE_ROBOT_DELETED, CLOSE_TOKEN_ROTATED, 
+export { PROTOCOL_VERSION, PROTOCOL_VERSIONS, PROTOCOL_SUNSET_DAYS, LATEST_BRIDGE_VERSION, protocolStatus, minimumProtocolVersion, sunsetOf, statusFromTable, bridgeHello, cloudHelloOk, cloudHelloError, cloudPing, bridgePong, bridgeLinkMode, datapointFrame, bridgeState, cloudConfig, bridgeConfigApplied, cloudIntrospectRequest, bridgeIntrospect, cloudTypeRequest, bridgeTypeDefinitions, cloudInvoke, cloudCancel, CANCEL_RETURN_CODES, cancelReturnCode, bridgeCancelResultEntry, bridgeCancelResult, cloudPublish, bridgeJobUpdate, bridgeJobLost, cloudJobQuery, bridgeJobStatusEntry, bridgeJobStatus, snapshotHeader, cloudCameraStart, cloudCameraStop, bridgeCameraState, SNAPSHOT_MAX_BYTES, CLOSE_ROBOT_DELETED, CLOSE_TOKEN_ROTATED, 
 // Assets.
 bridgeAssetsAvailable, cloudAssetRequest, bridgeAssetProgress, 
 // Addressing.
 activeJob, DEFAULT_PATIENCE_MS, MAX_PATIENCE_MS, MIN_PATIENCE_MS, JOB_HEARTBEAT_INTERVAL_MS, JOB_HEARTBEAT_TIMEOUT_MS, JOB_OFFLINE_GRACE_MS, } from './protocol.js';
-export { jobState, jobOrigin, job, jobEvent, busyDetails, publisherBusyDetails, jobQueueFullDetails } from './jobs.js';
+export { jobState, reportedJobState, jobOrigin, job, jobEvent, busyDetails, publisherBusyDetails, jobQueueFullDetails } from './jobs.js';
 export { JOB_RUN_PAGE_MAX, JOB_RUN_RETENTION_DAYS, jobActor, jobRunKind, jobRun, jobRunQuery, jobRunListResponse, jobRunSummaryQuery, jobRunSummary, } from './jobs.js';
 export { FLEETLESS_FORMAT_VERSION, RESERVED_SLUGS, parameterType, parameterSpec, parameterMap, serviceDescription, parameterDescription, messageTemplate, messageRef, messageBody, messageMap, PLACEHOLDER_RE, placeholderNames, actionConfig, serviceConfig, publisherConfig, cameraConfig, alertCondition, datapointAlert, rateThrottleHz, datapointNumeric, datapointRetention, datapointChart, datapointConfig, lowBandwidthSection, LOW_BANDWIDTH_DEFAULTS, robotConfigDoc, validationIssue, configState, snapshotIntervalSeconds, 
 // The defaults the format names, so nobody invents them twice.

package/dist/jobs.d.ts

@@ -31,6 +31,21 @@ export declare const jobState: z.ZodEnum<{
     lost: "lost";
 }>;
 export type JobState = z.infer<typeof jobState>;
+/**
+ * The states a bridge may state about a job: every `jobState` but `unknown`,
+ * which is the cloud's own word for not having heard. The bridge's
+ * `job_update`, `job_status` entries and `hello.active_jobs` use this, so a
+ * bridge claiming `unknown` fails validation instead of parking a job
+ * nobody will ever ask about.
+ */
+export declare const reportedJobState: z.ZodEnum<{
+    failed: "failed";
+    running: "running";
+    succeeded: "succeeded";
+    cancelled: "cancelled";
+    lost: "lost";
+}>;
+export type ReportedJobState = z.infer<typeof reportedJobState>;
 /**
  * Who started a job.
  *

package/dist/jobs.js

@@ -24,6 +24,14 @@ import { slug, wireSeqCursor, wireTimestampMs } from './common.js';
  *    back and says it finished.
  */
 export const jobState = z.enum(['running', 'unknown', 'succeeded', 'failed', 'cancelled', 'lost']);
+/**
+ * The states a bridge may state about a job: every `jobState` but `unknown`,
+ * which is the cloud's own word for not having heard. The bridge's
+ * `job_update`, `job_status` entries and `hello.active_jobs` use this, so a
+ * bridge claiming `unknown` fails validation instead of parking a job
+ * nobody will ever ask about.
+ */
+export const reportedJobState = jobState.exclude(['unknown']);
 /**
  * Who started a job.
  *

package/dist/protocol.d.ts

@@ -221,13 +221,18 @@ export { slug } from './common.js';
  * has a terminal result still in hand reports it here and the cloud writes it
  * down, instead of publishing `lost` over a job that in fact succeeded.
  * Never `unknown`: that is the cloud's word for not having heard, and a
- * bridge listing a job has, by definition, something to say about it.
+ * bridge listing a job has, by definition, something to say about it — the
+ * schema refuses it.
+ *
+ * Only the bridge's own jobs, never an external goal: this entry carries no
+ * `origin`, and a cloud adopting an external goal from it would take it for
+ * its own. An active external goal is reported by the next `job_update`
+ * tick, with its origin.
  */
 export declare const activeJob: z.ZodObject<{
     job_id: z.ZodUUID;
     slug: z.ZodString;
     state: z.ZodEnum<{
-        unknown: "unknown";
         failed: "failed";
         running: "running";
         succeeded: "succeeded";
@@ -246,7 +251,6 @@ export declare const bridgeHello: z.ZodObject<{
         job_id: z.ZodUUID;
         slug: z.ZodString;
         state: z.ZodEnum<{
-            unknown: "unknown";
             failed: "failed";
             running: "running";
             succeeded: "succeeded";
@@ -625,18 +629,79 @@ export type CloudInvoke = z.infer<typeof cloudInvoke>;
  * wire had nowhere to put it.
  *
  * `null` keeps today's meaning and must be read as exactly that: *cancel
- * whatever is running on this slug*. It is a real request — an operator
- * hitting stop wants the robot stopped, not a lecture about job identity —
- * and it stays available for that. A bridge given an id that does not match
- * what is running cancels **nothing** and says so; it must not fall back to
- * the slug, because a caller who named an id has ruled that out.
+ * every goal active on this slug's action*. It is a real request — an
+ * operator hitting stop wants the robot stopped, not a lecture about job
+ * identity — and it stays available for that.
+ *
+ * A `job_id` the bridge holds (its own job, or an external goal's derived
+ * id) cancels that goal alone. A `job_id` it does not hold is how the cloud
+ * cancels an `unknown` job: the bridge cancels every **external** goal
+ * active on the slug's action, since one of them may be that job, and never
+ * one of its own jobs, which the caller did not name.
+ *
+ * `request_id` correlates the bridge's `cancel_result`, which carries each
+ * goal's `CancelGoal` return code; the cloud answers its caller only from
+ * that.
  */
 export declare const cloudCancel: z.ZodObject<{
     type: z.ZodLiteral<"cancel">;
+    request_id: z.ZodString;
     slug: z.ZodString;
     job_id: z.ZodNullable<z.ZodUUID>;
 }, z.core.$strip>;
 export type CloudCancel = z.infer<typeof cloudCancel>;
+/**
+ * The ROS 2 `action_msgs/srv/CancelGoal` return codes: `0` `ERROR_NONE` (the
+ * server accepted the cancel request), `1` `ERROR_REJECTED` (it refused),
+ * `2` `ERROR_UNKNOWN_GOAL_ID`, `3` `ERROR_GOAL_TERMINATED` (the goal had
+ * already ended). An accepted request is not an ended goal: whether the goal
+ * ends, and how, is what the action's status reports afterwards, and reaches
+ * the cloud as the goal's `job_update`.
+ */
+export declare const CANCEL_RETURN_CODES: {
+    readonly none: 0;
+    readonly rejected: 1;
+    readonly unknown_goal_id: 2;
+    readonly goal_terminated: 3;
+};
+export declare const cancelReturnCode: z.ZodNumber;
+export type CancelReturnCode = z.infer<typeof cancelReturnCode>;
+/** One goal a `cancel` reached, and what its action server answered. */
+export declare const bridgeCancelResultEntry: z.ZodObject<{
+    job_id: z.ZodUUID;
+    goal_id: z.ZodString;
+    return_code: z.ZodNullable<z.ZodNumber>;
+}, z.core.$strip>;
+export type BridgeCancelResultEntry = z.infer<typeof bridgeCancelResultEntry>;
+/**
+ * The bridge's answer to a `cancel`, once every goal it sent a cancel request
+ * for has answered — or `error` when it could not ask. `goals` is empty when
+ * nothing matched (a `job_id` the bridge does not hold, with no external goal
+ * on the action; or nothing active on the slug): the cancel reached nothing,
+ * which is an answer, not a failure.
+ *
+ * A goal whose server did not answer the cancel request within the bridge's
+ * own bound is listed with `return_code: null`, not left out.
+ *
+ * The cloud reports `return_code` `1` (`ERROR_REJECTED`) to the caller as a
+ * refusal (`cancel_rejected`), never as success, and writes the audit event
+ * of a cancel of an external goal from this frame, return code included.
+ */
+export declare const bridgeCancelResult: z.ZodObject<{
+    type: z.ZodLiteral<"cancel_result">;
+    request_id: z.ZodString;
+    slug: z.ZodString;
+    goals: z.ZodArray<z.ZodObject<{
+        job_id: z.ZodUUID;
+        goal_id: z.ZodString;
+        return_code: z.ZodNullable<z.ZodNumber>;
+    }, z.core.$strip>>;
+    error: z.ZodNullable<z.ZodObject<{
+        code: z.ZodString;
+        message: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type BridgeCancelResult = z.infer<typeof bridgeCancelResult>;
 export declare const cloudPublish: z.ZodObject<{
     type: z.ZodLiteral<"publish">;
     slug: z.ZodString;
@@ -666,7 +731,6 @@ export declare const bridgeJobUpdate: z.ZodObject<{
     job_id: z.ZodUUID;
     slug: z.ZodString;
     state: z.ZodEnum<{
-        unknown: "unknown";
         failed: "failed";
         running: "running";
         succeeded: "succeeded";
@@ -729,11 +793,15 @@ export declare const cloudJobQuery: z.ZodObject<{
     job_ids: z.ZodArray<z.ZodUUID>;
 }, z.core.$strip>;
 export type CloudJobQuery = z.infer<typeof cloudJobQuery>;
-/** One job the bridge recognises, in a `job_status` answer. Same fields as `job_update`'s. */
+/**
+ * One job the bridge recognises, in a `job_status` answer: its state, feedback,
+ * progress, result and error, as a `job_update` would carry them. No `slug`,
+ * `origin`, `goal_id` or `timestamp_ms` — the cloud asked about a job it
+ * already holds, so it knows the first three, and the answer is current.
+ */
 export declare const bridgeJobStatusEntry: z.ZodObject<{
     job_id: z.ZodUUID;
     state: z.ZodEnum<{
-        unknown: "unknown";
         failed: "failed";
         running: "running";
         succeeded: "succeeded";
@@ -767,7 +835,6 @@ export declare const bridgeJobStatus: z.ZodObject<{
     jobs: z.ZodArray<z.ZodObject<{
         job_id: z.ZodUUID;
         state: z.ZodEnum<{
-            unknown: "unknown";
             failed: "failed";
             running: "running";
             succeeded: "succeeded";

package/dist/protocol.js

@@ -4,7 +4,7 @@ import { assetFailure } from './assets.js';
 import { applyError, slug } from './common.js';
 import { robotConfigDoc } from './config.js';
 import { rosGraph, typeDefinition } from './introspection.js';
-import { jobOrigin, jobState } from './jobs.js';
+import { jobOrigin, reportedJobState } from './jobs.js';
 import { rosTypeName } from './common.js';
 /**
  * Bridge <-> cloud protocol, version 5.
@@ -238,12 +238,18 @@ export { slug } from './common.js';
  * has a terminal result still in hand reports it here and the cloud writes it
  * down, instead of publishing `lost` over a job that in fact succeeded.
  * Never `unknown`: that is the cloud's word for not having heard, and a
- * bridge listing a job has, by definition, something to say about it.
+ * bridge listing a job has, by definition, something to say about it — the
+ * schema refuses it.
+ *
+ * Only the bridge's own jobs, never an external goal: this entry carries no
+ * `origin`, and a cloud adopting an external goal from it would take it for
+ * its own. An active external goal is reported by the next `job_update`
+ * tick, with its origin.
  */
 export const activeJob = z.object({
     job_id: z.uuid(),
     slug,
-    state: jobState,
+    state: reportedJobState,
 });
 /** First frame a bridge sends after the socket opens. */
 export const bridgeHello = z.object({
@@ -462,17 +468,67 @@ export const cloudInvoke = z.object({
  * wire had nowhere to put it.
  *
  * `null` keeps today's meaning and must be read as exactly that: *cancel
- * whatever is running on this slug*. It is a real request — an operator
- * hitting stop wants the robot stopped, not a lecture about job identity —
- * and it stays available for that. A bridge given an id that does not match
- * what is running cancels **nothing** and says so; it must not fall back to
- * the slug, because a caller who named an id has ruled that out.
+ * every goal active on this slug's action*. It is a real request — an
+ * operator hitting stop wants the robot stopped, not a lecture about job
+ * identity — and it stays available for that.
+ *
+ * A `job_id` the bridge holds (its own job, or an external goal's derived
+ * id) cancels that goal alone. A `job_id` it does not hold is how the cloud
+ * cancels an `unknown` job: the bridge cancels every **external** goal
+ * active on the slug's action, since one of them may be that job, and never
+ * one of its own jobs, which the caller did not name.
+ *
+ * `request_id` correlates the bridge's `cancel_result`, which carries each
+ * goal's `CancelGoal` return code; the cloud answers its caller only from
+ * that.
  */
 export const cloudCancel = z.object({
     type: z.literal('cancel'),
+    request_id: z.string().min(1).max(64),
     slug,
     job_id: z.uuid().nullable(),
 });
+/**
+ * The ROS 2 `action_msgs/srv/CancelGoal` return codes: `0` `ERROR_NONE` (the
+ * server accepted the cancel request), `1` `ERROR_REJECTED` (it refused),
+ * `2` `ERROR_UNKNOWN_GOAL_ID`, `3` `ERROR_GOAL_TERMINATED` (the goal had
+ * already ended). An accepted request is not an ended goal: whether the goal
+ * ends, and how, is what the action's status reports afterwards, and reaches
+ * the cloud as the goal's `job_update`.
+ */
+export const CANCEL_RETURN_CODES = { none: 0, rejected: 1, unknown_goal_id: 2, goal_terminated: 3 };
+export const cancelReturnCode = z.number().int().min(0).max(3);
+/** One goal a `cancel` reached, and what its action server answered. */
+export const bridgeCancelResultEntry = z.object({
+    /** The job the goal belongs to — the bridge's own, or an external goal's derived id. */
+    job_id: z.uuid(),
+    /** The ROS 2 goal id the cancel was sent for. */
+    goal_id: z.string().min(1),
+    /** `null` when the action server did not answer the cancel request within the bridge's own bound. */
+    return_code: cancelReturnCode.nullable(),
+});
+/**
+ * The bridge's answer to a `cancel`, once every goal it sent a cancel request
+ * for has answered — or `error` when it could not ask. `goals` is empty when
+ * nothing matched (a `job_id` the bridge does not hold, with no external goal
+ * on the action; or nothing active on the slug): the cancel reached nothing,
+ * which is an answer, not a failure.
+ *
+ * A goal whose server did not answer the cancel request within the bridge's
+ * own bound is listed with `return_code: null`, not left out.
+ *
+ * The cloud reports `return_code` `1` (`ERROR_REJECTED`) to the caller as a
+ * refusal (`cancel_rejected`), never as success, and writes the audit event
+ * of a cancel of an external goal from this frame, return code included.
+ */
+export const bridgeCancelResult = z.object({
+    type: z.literal('cancel_result'),
+    request_id: z.string().min(1).max(64),
+    slug,
+    goals: z.array(bridgeCancelResultEntry),
+    /** Set when the bridge could not send the cancel at all (no such slug, a service, the server gone). */
+    error: z.object({ code: z.string().min(1), message: z.string().min(1) }).nullable(),
+});
 export const cloudPublish = z.object({
     type: z.literal('publish'),
     slug,
@@ -511,7 +567,7 @@ export const bridgeJobUpdate = z.object({
     job_id: z.uuid(),
     slug,
     /** Never `unknown`: that is the cloud's word for not having heard. */
-    state: jobState,
+    state: reportedJobState,
     origin: jobOrigin,
     /** The ROS 2 goal id; `null` for a service job, which has no goal. */
     goal_id: z.string().min(1).nullable(),
@@ -559,11 +615,16 @@ export const cloudJobQuery = z.object({
     request_id: z.string().min(1).max(64),
     job_ids: z.array(z.uuid()).min(1),
 });
-/** One job the bridge recognises, in a `job_status` answer. Same fields as `job_update`'s. */
+/**
+ * One job the bridge recognises, in a `job_status` answer: its state, feedback,
+ * progress, result and error, as a `job_update` would carry them. No `slug`,
+ * `origin`, `goal_id` or `timestamp_ms` — the cloud asked about a job it
+ * already holds, so it knows the first three, and the answer is current.
+ */
 export const bridgeJobStatusEntry = z.object({
     job_id: z.uuid(),
     /** Never `unknown` — the bridge only ever states a definite fact about a job it recognises. */
-    state: jobState,
+    state: reportedJobState,
     feedback: z.unknown().nullable(),
     progress: z.number().min(0).max(1).nullable(),
     result: z.unknown().nullable(),

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.1",
+  "version": "5.0.0",
   "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",