@fleetless/contracts 4.0.0 → 5.0.0-next.1

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,42 @@ export declare const jobState: z.ZodEnum<{
     lost: "lost";
 }>;
 export type JobState = z.infer<typeof jobState>;
+/**
+ * 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 +96,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 +125,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 +137,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 +249,7 @@ export declare const jobRun: z.ZodObject<{
         service: "service";
     }>;
     state: z.ZodEnum<{
+        unknown: "unknown";
         failed: "failed";
         running: "running";
         succeeded: "succeeded";
@@ -239,6 +286,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 +311,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,35 @@ 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']);
+/**
+ * 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 +49,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 +71,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 +109,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 +135,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 +239,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 +307,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.',

package/dist/protocol.d.ts

@@ -1,15 +1,29 @@
 // SPDX-License-Identifier: Apache-2.0
 import { z } from 'zod';
 /**
- * Bridge <-> cloud protocol, version 4.
+ * Bridge <-> cloud protocol, version 5.
  *
  * The version is exchanged in the hello handshake. Since 2026-09 the cloud
  * serves a **window** of versions, not one: every entry of
  * `PROTOCOL_VERSIONS` whose sunset has not passed. A version is deprecated
  * by the cloud release that supersedes it and sunset `PROTOCOL_SUNSET_DAYS`
- * later. Outside the window the cloud refuses with `protocol_mismatch`,
- * which names the window and reaches the robot's detail view as
- * `last_hello_error`.
+ * later. Outside the window the cloud refuses the hello, and the refusal
+ * reaches the robot's detail view as `last_hello_error`: `bridge_too_old`,
+ * naming the bridge version to install, for a version below the window.
+ *
+ * **5 (2026-09-29):** a hard cut, not a window — protocols 2, 3 and 4 are
+ * unsupported from this release on, with no sunset (André, 2026-09-29: "we
+ * are still building up and need not take care"), so `PROTOCOL_VERSIONS`
+ * holds one entry. The bridge tracks every goal on a published action by
+ * goal id — its own and anyone else's — and reports them through
+ * `job_update`, which gains a required `origin` and `goal_id`: a goal it did
+ * not send arrives as `origin: 'external'` under a job id the bridge derives
+ * itself. `jobState` gains `unknown`, the cloud's non-terminal "I lost sight
+ * of it" (`bridge_disconnected`, `bridge_timeout`) that replaces settling
+ * `lost` on a guess; `lost` is final. While connected, the cloud asks about
+ * specific jobs with `job_query` and the bridge answers `job_status`. Goal
+ * state is reported once per `JOB_HEARTBEAT_INTERVAL_MS`, newest only; the
+ * end of a Fleetless job goes at once.
  *
  * **4 (2026-09-29):** the bridge sends a `job_update` heartbeat at
  * `JOB_HEARTBEAT_INTERVAL_MS` for every running job, whether or not the
@@ -36,7 +50,7 @@ import { z } from 'zod';
  * **2 (2026-08-21):** `config_applied.errors` entries gained `kind` and `code`
  * beside `message`.
  */
-export declare const PROTOCOL_VERSION = 4;
+export declare const PROTOCOL_VERSION = 5;
 /** Days between a version's deprecation and its sunset. */
 export declare const PROTOCOL_SUNSET_DAYS = 90;
 export interface ProtocolVersionEntry {
@@ -47,17 +61,24 @@ export interface ProtocolVersionEntry {
     deprecated_at: string | null;
 }
 /**
- * Every protocol version the cloud has served, oldest first. A test keeps
+ * Every protocol version the cloud serves, oldest first. A test keeps
  * exactly one entry current and equal to `PROTOCOL_VERSION`; `test/changelog.test.ts`
  * requires some CHANGELOG section — `[Unreleased]` or a dated one — to name
  * the newest `bridge_from` together with the previous entry's `sunsetOf(...)`
  * date, so the pull request that moves this window is the one that fails
  * without saying so; and `scripts/verify-version-tag.mjs` requires a dated
  * heading for the tag being released.
+ *
+ * **One entry since protocol 5**, which cut 2, 3 and 4 without a sunset
+ * rather than deprecating them. A version absent from the table is
+ * `unsupported`, which is exactly what a cut means, so the dropped entries
+ * are gone rather than kept with a past date. The changelog test's window
+ * check has no previous entry to read then; its hard-cut sibling holds the
+ * changelog to naming the cut instead.
  */
 export declare const PROTOCOL_VERSIONS: readonly ProtocolVersionEntry[];
 /** The newest bridge package. The cloud mails organisations still below it. */
-export declare const LATEST_BRIDGE_VERSION = "5.0.0";
+export declare const LATEST_BRIDGE_VERSION = "6.0.0";
 export interface ProtocolStatus {
     status: 'current' | 'deprecated' | 'unsupported';
     /** ISO date, or null for a current or unknown version. */
@@ -144,37 +165,43 @@ export declare const MAX_PATIENCE_MS = 120000;
  */
 export declare const MIN_PATIENCE_MS = 1000;
 /**
- * How often a protocol-4 bridge sends a `job_update` heartbeat for every
- * running job — the last known state, whether or not the action itself said
- * anything new. One second: often enough that `JOB_HEARTBEAT_TIMEOUT_MS`
+ * How often the bridge reports goal state: one `job_update` per active goal
+ * on a published action — its own and external ones — carrying the newest
+ * state and feedback, whether or not the action said anything new. Whatever
+ * happened in between is dropped, so an action that sends feedback at 100 Hz
+ * costs one frame a second; the end of a Fleetless job is the exception and
+ * goes at once. One second: often enough that `JOB_HEARTBEAT_TIMEOUT_MS`
  * can be a small multiple of it and still absorb a missed beat or two, rare
  * enough that it costs nothing next to the datapoint traffic a busy robot
  * already sends.
  */
 export declare const JOB_HEARTBEAT_INTERVAL_MS = 1000;
 /**
- * How long a protocol-4 job may go without a `job_update` — heartbeat or
- * real progress, either counts — before the cloud settles it `lost` with
+ * How long a running job may go without a `job_update` — heartbeat or real
+ * progress, either counts — before the cloud marks it `unknown` with
  * `bridge_timeout`, once the bridge is connected. Five heartbeats: enough
  * slack for an ordinary scheduling jitter, small next to `patience_ms`
- * because it no longer has to cover the acceptance gap too. `patience_ms`
- * bounds only the time from `invoke` to the *first* update on a protocol-4
- * job; every rearm after that uses this constant instead. A protocol-3
- * bridge sends no heartbeat, so this constant does not apply to it —
- * `patience_ms` keeps bounding the whole running job there, exactly as
- * before.
+ * because it does not have to cover the acceptance gap too. `patience_ms`
+ * bounds only the time from `invoke` to the *first* update; every rearm after
+ * that uses this constant instead.
+ *
+ * `unknown`, not `lost`: silence is the cloud's guess, not the bridge's
+ * statement. The cloud then asks with `job_query`, and asks again after the
+ * same interval for as long as no `job_status` answers and the bridge stays
+ * connected.
  */
 export declare const JOB_HEARTBEAT_TIMEOUT_MS = 5000;
 /**
  * How long a running job survives its robot going offline before the cloud
- * gives up and settles it `lost` with `bridge_disconnected`. Five minutes:
- * long enough that an ordinary Wi-Fi dead zone — the case this constant
- * exists for — never costs a job, since a robot with no safety layer of its
- * own (§ Fleetless is not a safety layer) keeps driving through one and the
- * result the cloud is waiting for is often still coming. A robot connected
- * the whole time never reaches this bound at all: while online, silence is
- * `JOB_HEARTBEAT_TIMEOUT_MS`'s question (protocol 4) or `patience_ms`'s
- * (protocol 3), never this one's.
+ * marks it `unknown` with `bridge_disconnected`. Five minutes: long enough
+ * that an ordinary Wi-Fi dead zone — the case this constant exists for —
+ * never touches a job, since a robot with no safety layer of its own
+ * (§ Fleetless is not a safety layer) keeps driving through one and the
+ * result the cloud is waiting for is often still coming. Past it the job is
+ * still not given up: `unknown` keeps the slug occupied until the
+ * reconnecting bridge says how the job stands. A robot connected the whole
+ * time never reaches this bound at all: while online, silence is
+ * `JOB_HEARTBEAT_TIMEOUT_MS`'s question, never this one's.
  */
 export declare const JOB_OFFLINE_GRACE_MS = 300000;
 /** Re-exported so consumers keep importing wire names from one place. */
@@ -193,11 +220,14 @@ export { slug } from './common.js';
  * `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
  * 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.
  */
 export declare const activeJob: z.ZodObject<{
     job_id: z.ZodUUID;
     slug: z.ZodString;
     state: z.ZodEnum<{
+        unknown: "unknown";
         failed: "failed";
         running: "running";
         succeeded: "succeeded";
@@ -216,6 +246,7 @@ export declare const bridgeHello: z.ZodObject<{
         job_id: z.ZodUUID;
         slug: z.ZodString;
         state: z.ZodEnum<{
+            unknown: "unknown";
             failed: "failed";
             running: "running";
             succeeded: "succeeded";
@@ -615,18 +646,38 @@ export type CloudPublish = z.infer<typeof cloudPublish>;
 /**
  * Progress on a job, bridge → cloud. `timestamp_ms` is capture time, so a
  * burst delivered late after a reconnect is visibly late.
+ *
+ * Since protocol 5 this frame reports **every goal active on a published
+ * action**, not only the ones the bridge sent. A goal the bridge cannot
+ * attribute to a job of its own arrives with `origin: 'external'` and a
+ * `job_id` the bridge derives from robot, slug and goal id, the same id on
+ * every report of that goal — the cloud mints an external job the first time
+ * it sees one and never recomputes the id itself. `goal_id` is the ROS 2
+ * goal id, so a cancel can name the goal; `null` for a service job, which
+ * has no goal.
+ *
+ * Sent once per `JOB_HEARTBEAT_INTERVAL_MS` per active goal, newest state
+ * only. The end of a Fleetless job is sent at once; an external goal's end at
+ * the next tick, and an external goal that started and ended between two
+ * ticks is never reported at all.
  */
 export declare const bridgeJobUpdate: z.ZodObject<{
     type: z.ZodLiteral<"job_update">;
     job_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";
+    }>;
+    goal_id: z.ZodNullable<z.ZodString>;
     feedback: z.ZodNullable<z.ZodUnknown>;
     progress: z.ZodNullable<z.ZodNumber>;
     result: z.ZodNullable<z.ZodUnknown>;
@@ -639,23 +690,20 @@ export declare const bridgeJobUpdate: z.ZodObject<{
 }, z.core.$strip>;
 export type BridgeJobUpdate = z.infer<typeof bridgeJobUpdate>;
 /**
- * Jobs the bridge can no longer account for **while connected** — a
- * tracker dropped, an action server that vanished mid-goal, anything where
- * the honest answer is "I lost this" rather than a state.
+ * The bridge's own, definite statement **while connected** that it no longer
+ * knows these jobs — an action server that vanished mid-goal, a goal the
+ * server no longer knows — where the honest answer is "I lost this" rather
+ * than a state. The cloud settles each named job `lost`, final.
  *
- * The restart case is not this frame's job: a restarted bridge has nothing
- * left to enumerate, so it is `hello.active_job_ids` that closes that gap.
- * Both paths end in the same place — the cloud publishes `lost` rather than
- * leaving a job reading "running" because nobody contradicted it.
+ * Only the bridge says `lost` now. The cloud's own guesses — offline past
+ * `JOB_OFFLINE_GRACE_MS`, silent past `JOB_HEARTBEAT_TIMEOUT_MS` — make a
+ * job `unknown` instead, and a restart is answered by `hello.active_jobs`.
  *
- * **`error` (since protocol 4) is optional and, when present, applies to
- * every job named in `job_ids`.** A vanished action server is discovered
- * once, by the bridge's own liveness check on that one goal, so a frame
- * naming several jobs at once — plausible if several goals shared the same
- * server — always shares the same cause. Absent means today's behaviour:
- * the cloud settles the job `lost` with no specific code, the same as a
- * protocol-3 bridge's frame, which carries no `error` at all and still
- * parses under this schema unchanged.
+ * **`error` is optional and, when present, applies to every job named in
+ * `job_ids`.** A vanished action server is discovered once, by the bridge's
+ * own liveness check on that one action, so a frame naming several jobs at
+ * once always shares the same cause. Absent, the cloud settles the job
+ * `lost` with no specific code.
  */
 export declare const bridgeJobLost: z.ZodObject<{
     type: z.ZodLiteral<"job_lost">;
@@ -666,6 +714,78 @@ export declare const bridgeJobLost: z.ZodObject<{
     }, z.core.$strip>>;
 }, z.core.$strip>;
 export type BridgeJobLost = z.infer<typeof bridgeJobLost>;
+/**
+ * The cloud asks the bridge how specific jobs stand, while connected;
+ * `request_id` correlates the `job_status` answer.
+ *
+ * Sent for a job that went `unknown` with `bridge_timeout`: the bridge is
+ * connected but the cloud has not heard about the job, so it asks instead of
+ * guessing. Unanswered within `JOB_HEARTBEAT_TIMEOUT_MS`, the job stays
+ * `unknown` and the cloud asks again after the same interval.
+ */
+export declare const cloudJobQuery: z.ZodObject<{
+    type: z.ZodLiteral<"job_query">;
+    request_id: z.ZodString;
+    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. */
+export declare const bridgeJobStatusEntry: z.ZodObject<{
+    job_id: z.ZodUUID;
+    state: z.ZodEnum<{
+        unknown: "unknown";
+        failed: "failed";
+        running: "running";
+        succeeded: "succeeded";
+        cancelled: "cancelled";
+        lost: "lost";
+    }>;
+    feedback: z.ZodNullable<z.ZodUnknown>;
+    progress: z.ZodNullable<z.ZodNumber>;
+    result: z.ZodNullable<z.ZodUnknown>;
+    error: z.ZodNullable<z.ZodObject<{
+        code: z.ZodString;
+        message: z.ZodString;
+        details: z.ZodOptional<z.ZodUnknown>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type BridgeJobStatusEntry = z.infer<typeof bridgeJobStatusEntry>;
+/**
+ * The bridge's answer to a `job_query`. Every queried id lands in exactly
+ * one of the two lists.
+ *
+ * `unknown_job_ids` is an answer, not a failure — the same stance
+ * `type_definitions.unresolved` takes. It names the queried jobs the bridge
+ * does not recognise at all; the cloud settles one `lost` with
+ * `job_unknown_to_bridge` once no goal the bridge cannot attribute is active
+ * on its action (one of those may be that very job), and at once for a
+ * service job.
+ */
+export declare const bridgeJobStatus: z.ZodObject<{
+    type: z.ZodLiteral<"job_status">;
+    request_id: z.ZodString;
+    jobs: z.ZodArray<z.ZodObject<{
+        job_id: z.ZodUUID;
+        state: z.ZodEnum<{
+            unknown: "unknown";
+            failed: "failed";
+            running: "running";
+            succeeded: "succeeded";
+            cancelled: "cancelled";
+            lost: "lost";
+        }>;
+        feedback: z.ZodNullable<z.ZodUnknown>;
+        progress: z.ZodNullable<z.ZodNumber>;
+        result: z.ZodNullable<z.ZodUnknown>;
+        error: z.ZodNullable<z.ZodObject<{
+            code: z.ZodString;
+            message: z.ZodString;
+            details: z.ZodOptional<z.ZodUnknown>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    unknown_job_ids: z.ZodArray<z.ZodUUID>;
+}, z.core.$strip>;
+export type BridgeJobStatus = z.infer<typeof bridgeJobStatus>;
 /** Cloud asks for a fresh ROS graph; `request_id` correlates the answer. */
 export declare const cloudIntrospectRequest: z.ZodObject<{
     type: z.ZodLiteral<"introspect_request">;