@fleetless/contracts 4.0.0 → 5.0.0-next.2

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,6 +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 — 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;
@@ -594,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;
@@ -615,6 +711,20 @@ 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">;
@@ -627,6 +737,11 @@ export declare const bridgeJobUpdate: z.ZodObject<{
         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 +754,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 +778,81 @@ 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: 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<{
+        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<{
+            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">;