@fleetless/contracts 4.0.0 → 5.0.0-next.2

package/dist/errors.js

@@ -51,6 +51,16 @@ export const ERROR_CODES = [
     'unknown_datapoint',
     'invalid_token',
     'protocol_mismatch',
+    /**
+     * The cloud's `hello_error` for a bridge whose `protocol_version` is below
+     * every version it serves — since protocol 5, anything below 5. Its message
+     * names the bridge release to install (`LATEST_BRIDGE_VERSION`, 6.0.0 at
+     * the cut), because "too old" alone leaves an operator guessing how far to
+     * upgrade. Distinct from `protocol_mismatch`, the generic refusal for a
+     * version the cloud cannot place: this one says which way the gap runs and
+     * what closes it. Reaches the robot's detail view as `last_hello_error`.
+     */
+    'bridge_too_old',
     'invalid_frame',
     // Configuration.
     'duplicate_slug',
@@ -74,9 +84,10 @@ export const ERROR_CODES = [
     /**
      * The cloud has heard nothing — heartbeat or real progress — from a
      * running job for longer than it tolerates while the bridge is connected:
-     * `patience_ms` for a protocol-3 bridge, `JOB_HEARTBEAT_TIMEOUT_MS` for a
-     * protocol-4 one once it has heard from the job at all. `job.error.code`
-     * on `lost`.
+     * `patience_ms` until the first report, `JOB_HEARTBEAT_TIMEOUT_MS` after
+     * it. `job.error.code` on `unknown`, not `lost`: silence is the cloud's
+     * guess, so it asks the bridge with `job_query` and the answer resolves the
+     * job — running again clears this code, an end replaces it.
      */
     'bridge_timeout',
     // Identity and rights. `forbidden` is deliberately the answer both
@@ -145,8 +156,34 @@ export const ERROR_CODES = [
     'busy',
     /** A parameter failed its declared rule; details name the field and the rule. */
     'parameter_invalid',
-    /** The bridge could not account for this job after a restart. */
+    /**
+     * 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
+     * from `job_unknown_to_bridge`, the cloud's conclusion about a job the
+     * bridge does not name at all.
+     */
     'job_lost',
+    /**
+     * The bridge does not know this job — its `hello.active_jobs` or a
+     * `job_status` answer leaves it out — and, for an action, no goal the
+     * bridge cannot attribute is active on the job's action any more, so none
+     * of them can be it. A `job.error.code` on `lost`, final: how an `unknown`
+     * job the bridge has no word about ends. A service job, which has no goals to look
+     * at, gets it as soon as the bridge does not know it; so does a job whose
+     * persisted goal the action server no longer knows (its result expired).
+     * Distinct from `job_lost`, the bridge's own statement about a job it
+     * still names, and from `bridge_disconnected`/`bridge_timeout`, the
+     * cloud's guesses that make a job `unknown` in the first place.
+     */
+    'job_unknown_to_bridge',
     /**
      * The robot's action server vanished mid-goal — the bridge's own liveness
      * check found `server_is_ready()` false for three seconds straight and
@@ -167,9 +204,11 @@ export const ERROR_CODES = [
     'goal_uncontrollable',
     /**
      * The robot stayed offline for longer than `JOB_OFFLINE_GRACE_MS` while a
-     * job was running. A late real outcome, if the robot reconnects and the
-     * bridge still has it, corrects this — it is not final the way a genuine
-     * bridge report is. `job.error.code` on `lost`.
+     * job was running. `job.error.code` on `unknown`, not `lost`: the cloud
+     * does not know how the job stands, and the reconnecting bridge's
+     * `hello.active_jobs` resolves it — running again clears this code, an end
+     * replaces it, and a job the bridge does not know becomes `lost` with
+     * `job_unknown_to_bridge`.
      */
     'bridge_disconnected',
     /**

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, 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, SnapshotHeader, CloudCameraStart, CloudCameraStop, BridgeCameraState, ActiveJob, BridgeAssetsAvailable, CloudAssetRequest, BridgeAssetProgress, } from './protocol.js';
-export { jobState, job, jobEvent, busyDetails, publisherBusyDetails, jobQueueFullDetails } from './jobs.js';
-export type { JobState, 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, 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, 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

@@ -10,14 +10,20 @@ import { z } from 'zod';
  * 1. **State is observed by slug, not by id.** The id is informative; a client
  *    watches `robot × slug` and sees whatever job is running there, which is
  *    also why every observer of a slug sees the same job.
- * 2. **`lost` is a real outcome and must be said out loud.** Job state
- *    lives only in the bridge's memory; if it restarts mid-job, the results
- *    are gone. The cloud then marks the job `lost` — never leaves it reading
- *    "running" because nobody contradicted it. A system that reports a
- *    machine is still working when it does not know is worse than one that
- *    admits it lost track.
+ * 2. **What the cloud does not know it calls `unknown`, and `lost` is final.**
+ *    A job whose robot went quiet — offline past `JOB_OFFLINE_GRACE_MS`, or
+ *    connected but silent past `JOB_HEARTBEAT_TIMEOUT_MS` — is `unknown`: not
+ *    terminal, the slug stays occupied, and only a statement of the bridge
+ *    resolves it (it is running, it ended, or the bridge does not know it and
+ *    nothing else runs on its action). `lost` is what that last statement
+ *    produces, and nothing ever leaves it. Neither is left reading "running"
+ *    because nobody contradicted it: a system that reports a machine is still
+ *    working when it does not know is worse than one that says so — and one
+ *    that declares work lost on a guess is wrong the moment the robot comes
+ *    back and says it finished.
  */
 export declare const jobState: z.ZodEnum<{
+    unknown: "unknown";
     failed: "failed";
     running: "running";
     succeeded: "succeeded";
@@ -25,17 +31,57 @@ 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.
+ *
+ * `fleetless` for every job the cloud minted from an invocation. `external`
+ * for a goal the bridge found active on a published action without having
+ * sent it — started by anyone else on the robot's ROS graph, or the bridge's
+ * own goal after its mapping was lost. An external job has the same shape,
+ * states, live stream and cancel as any other, but no parameters (ROS 2
+ * publishes a goal's request nowhere), no starter, and it lives in memory
+ * only: it is never written to `job_runs` and never counts towards quotas.
+ */
+export declare const jobOrigin: z.ZodEnum<{
+    fleetless: "fleetless";
+    external: "external";
+}>;
+export type JobOrigin = z.infer<typeof jobOrigin>;
+/**
+ * One job, as the cloud tells every client about it — a Fleetless job or an
+ * external goal alike, told apart only by `origin`.
+ */
 export declare const job: z.ZodObject<{
     id: z.ZodUUID;
     robot_id: z.ZodUUID;
     slug: z.ZodString;
     state: z.ZodEnum<{
+        unknown: "unknown";
         failed: "failed";
         running: "running";
         succeeded: "succeeded";
         cancelled: "cancelled";
         lost: "lost";
     }>;
+    origin: z.ZodEnum<{
+        fleetless: "fleetless";
+        external: "external";
+    }>;
     started_at: z.ZodISODateTime;
     updated_at: z.ZodISODateTime;
     seq: z.ZodNumber;
@@ -65,12 +111,17 @@ export declare const jobEvent: z.ZodObject<{
         robot_id: z.ZodUUID;
         slug: z.ZodString;
         state: z.ZodEnum<{
+            unknown: "unknown";
             failed: "failed";
             running: "running";
             succeeded: "succeeded";
             cancelled: "cancelled";
             lost: "lost";
         }>;
+        origin: z.ZodEnum<{
+            fleetless: "fleetless";
+            external: "external";
+        }>;
         started_at: z.ZodISODateTime;
         updated_at: z.ZodISODateTime;
         seq: z.ZodNumber;
@@ -89,6 +140,11 @@ export type JobEvent = z.infer<typeof jobEvent>;
 /**
  * What a busy refusal tells the caller: what is already running. A refusal that
  * only says "busy" forces the caller to guess whether to wait or to give up.
+ *
+ * `running` is whatever occupies the slug — a `running` job, an `unknown` one
+ * the robot has not accounted for yet, or an `external` goal someone else
+ * started — and its `state` and `origin` say which, so a caller can tell
+ * "wait for it" from "cancel what someone else started".
  */
 export declare const busyDetails: z.ZodObject<{
     running: z.ZodObject<{
@@ -96,12 +152,17 @@ export declare const busyDetails: z.ZodObject<{
         robot_id: z.ZodUUID;
         slug: z.ZodString;
         state: z.ZodEnum<{
+            unknown: "unknown";
             failed: "failed";
             running: "running";
             succeeded: "succeeded";
             cancelled: "cancelled";
             lost: "lost";
         }>;
+        origin: z.ZodEnum<{
+            fleetless: "fleetless";
+            external: "external";
+        }>;
         started_at: z.ZodISODateTime;
         updated_at: z.ZodISODateTime;
         seq: z.ZodNumber;
@@ -203,6 +264,7 @@ export declare const jobRun: z.ZodObject<{
         service: "service";
     }>;
     state: z.ZodEnum<{
+        unknown: "unknown";
         failed: "failed";
         running: "running";
         succeeded: "succeeded";
@@ -239,6 +301,7 @@ export declare const jobRunQuery: z.ZodObject<{
     robot_id: z.ZodOptional<z.ZodUUID>;
     slug: z.ZodOptional<z.ZodString>;
     state: z.ZodOptional<z.ZodEnum<{
+        unknown: "unknown";
         failed: "failed";
         running: "running";
         succeeded: "succeeded";
@@ -263,6 +326,7 @@ export declare const jobRunListResponse: z.ZodObject<{
             service: "service";
         }>;
         state: z.ZodEnum<{
+            unknown: "unknown";
             failed: "failed";
             running: "running";
             succeeded: "succeeded";

package/dist/jobs.js

@@ -11,14 +11,43 @@ import { slug, wireSeqCursor, wireTimestampMs } from './common.js';
  * 1. **State is observed by slug, not by id.** The id is informative; a client
  *    watches `robot × slug` and sees whatever job is running there, which is
  *    also why every observer of a slug sees the same job.
- * 2. **`lost` is a real outcome and must be said out loud.** Job state
- *    lives only in the bridge's memory; if it restarts mid-job, the results
- *    are gone. The cloud then marks the job `lost` — never leaves it reading
- *    "running" because nobody contradicted it. A system that reports a
- *    machine is still working when it does not know is worse than one that
- *    admits it lost track.
+ * 2. **What the cloud does not know it calls `unknown`, and `lost` is final.**
+ *    A job whose robot went quiet — offline past `JOB_OFFLINE_GRACE_MS`, or
+ *    connected but silent past `JOB_HEARTBEAT_TIMEOUT_MS` — is `unknown`: not
+ *    terminal, the slug stays occupied, and only a statement of the bridge
+ *    resolves it (it is running, it ended, or the bridge does not know it and
+ *    nothing else runs on its action). `lost` is what that last statement
+ *    produces, and nothing ever leaves it. Neither is left reading "running"
+ *    because nobody contradicted it: a system that reports a machine is still
+ *    working when it does not know is worse than one that says so — and one
+ *    that declares work lost on a guess is wrong the moment the robot comes
+ *    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.
+ *
+ * `fleetless` for every job the cloud minted from an invocation. `external`
+ * for a goal the bridge found active on a published action without having
+ * sent it — started by anyone else on the robot's ROS graph, or the bridge's
+ * own goal after its mapping was lost. An external job has the same shape,
+ * states, live stream and cancel as any other, but no parameters (ROS 2
+ * publishes a goal's request nowhere), no starter, and it lives in memory
+ * only: it is never written to `job_runs` and never counts towards quotas.
+ */
+export const jobOrigin = z.enum(['fleetless', 'external']);
+/**
+ * One job, as the cloud tells every client about it — a Fleetless job or an
+ * external goal alike, told apart only by `origin`.
  */
-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; a cancel names this id to stop one specific job rather than whatever is running.',
@@ -28,7 +57,10 @@ export const job = z.object({
         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 — stated rather than left reading `running` by default.',
+        description: 'Where the job stands: `running`, `unknown`, `succeeded`, `failed`, `cancelled` or `lost`. `unknown` is not an outcome — the robot went offline or silent and the cloud does not know yet; the slug stays occupied and the bridge\'s next statement resolves it, `error` naming why the cloud lost sight of it. `lost` is final: the bridge stated it does not know the job and nothing else runs on its action, or the action server vanished mid-goal.',
+    }),
+    origin: jobOrigin.meta({
+        description: "Who started this job. `fleetless` for everything minted by the cloud; `external` for a goal the bridge found active on a published action without having sent it — no parameters, no starter, never written to `job_runs`.",
     }),
     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, this is **adoption time**, not the real start — the cloud never minted it.',
@@ -47,7 +79,7 @@ export const job = z.object({
      * exists for the same reason on the audit log.
      *
      * **Scoped honestly: per cloud process, per run.** Job state lives in memory
-     * — that is why `lost` exists at all — so this counter restarts when
+     * — that is why `unknown` and `lost` exist at all — so this counter restarts when
      * the cloud does, alongside the jobs it orders. Sound, because it only ever
      * orders jobs that coexist in one registry — and stated, because a reader
      * who assumed `auditEvent.seq`'s durable semantics would be wrong.
@@ -85,7 +117,7 @@ export const job = z.object({
     })
         .nullable()
         .meta({
-        description: 'Why the job failed: a human `message`, a `code` where one exists, and `details` for the codes that carry a documented payload. `null` unless `state` is `failed`.',
+        description: 'Why the job failed, or why the cloud does not know how it stands: a human `message`, a `code` where one exists, and `details` for the codes that carry a documented payload. Set on `failed` and `lost`, and on `unknown` — where `code` is `bridge_disconnected` or `bridge_timeout`, the cloud\'s own reason for not knowing, cleared when the bridge reports the job running again.',
     }),
 });
 /**
@@ -111,6 +143,11 @@ export const jobEvent = z.object({
 /**
  * What a busy refusal tells the caller: what is already running. A refusal that
  * only says "busy" forces the caller to guess whether to wait or to give up.
+ *
+ * `running` is whatever occupies the slug — a `running` job, an `unknown` one
+ * the robot has not accounted for yet, or an `external` goal someone else
+ * started — and its `state` and `origin` say which, so a caller can tell
+ * "wait for it" from "cancel what someone else started".
  */
 export const busyDetails = z.object({
     running: job,
@@ -210,16 +247,16 @@ export const jobRun = z.object({
         description: 'Whether the slug was an `action` or a `service`.',
     }),
     state: jobState.meta({
-        description: 'How the run ended, or `running` while it is still going. `lost` means the bridge restarted mid-run and the outcome is unknowable rather than unknown.',
+        description: 'How the run ended, or `running` while it is still going. `unknown` while the robot has not accounted for it — offline or silent — and updated once the bridge says how it stands. `lost` is final: the bridge did not know the run and nothing else ran on its action, so the outcome is unknowable rather than unknown.',
     }),
     started_at: z.iso.datetime().meta({
         description: 'When the run started, as an ISO 8601 timestamp. Runs are listed and filtered by this instant.',
     }),
     ended_at: z.iso.datetime().nullable().meta({
-        description: 'When the run finished, as an ISO 8601 timestamp. `null` while it is still `running` — a run has an end only once it has one.',
+        description: 'When the run finished, as an ISO 8601 timestamp. `null` while it is still `running` or `unknown` — a run has an end only once it has one.',
     }),
     duration_ms: z.number().int().nonnegative().nullable().meta({
-        description: 'How long the run took, in milliseconds. `null` while it is still `running`, never `0` standing in for "nothing so far".',
+        description: 'How long the run took, in milliseconds. `null` while it is still `running` or `unknown`, never `0` standing in for "nothing so far".',
     }),
     result: z.unknown().nullable().meta({
         description: 'What the action or service returned once it succeeded, shaped by ROS itself. `null` otherwise.',
@@ -278,7 +315,7 @@ export const jobRunQuery = z
         description: 'Only runs of this action or service.',
     }),
     state: jobState.optional().meta({
-        description: 'Only runs in this state — `running`, `succeeded`, `failed`, `cancelled` or `lost`.',
+        description: 'Only runs in this state — `running`, `unknown`, `succeeded`, `failed`, `cancelled` or `lost`.',
     }),
     kind: jobRunKind.optional().meta({
         description: 'Only `action` runs, or only `service` runs.',