@fleetless/contracts 1.0.0 → 1.0.2

package/dist/introspection.d.ts

@@ -1,6 +1,7 @@
+// SPDX-License-Identifier: Apache-2.0
 import { z } from 'zod';
 /**
- * Introspection (spec §4.1, §4.5): what the connected bridge can tell the
+ * Introspection: what the connected bridge can tell the
  * cloud about the robot's ROS graph, so the console can offer a quick pick
  * instead of a blank text field.
  *
@@ -45,10 +46,10 @@ export interface TypeField {
 }
 export declare const typeField: z.ZodType<TypeField>;
 /**
- * A resolved type of one robot. Custom types are per robot (spec §4.5): two
- * robots may define `custom_msgs/msg/Speed` differently and both are right.
+ * A resolved type of one robot. Custom types are per robot: two robots may
+ * define `custom_msgs/msg/Speed` differently and both are right.
  *
- * W2 resolved messages only; W4 adds services and actions, because a
+ * Messages, services and actions all appear here, because a
  * `parameterSpec.name` has to resolve against *something*, and an action has
  * no flat field list — it has a goal, a result and a feedback tree.
  *
@@ -65,8 +66,8 @@ export declare const typeField: z.ZodType<TypeField>;
  * a result in. They are carried so the console can show what an action will
  * report back, and so a client knows the shape of `job.result` in advance.
  *
- * The `msg` member keeps W2's exact shape, so every type already stored stays
- * valid without migration.
+ * The `msg` member is the flat field list a message resolves to; the other
+ * two carry one tree per part.
  */
 export declare const typeDefinition: z.ZodDiscriminatedUnion<[z.ZodObject<{
     name: z.ZodString;

package/dist/introspection.js

@@ -2,7 +2,7 @@
 import { z } from 'zod';
 import { rosName, rosTypeName } from './common.js';
 /**
- * Introspection (spec §4.1, §4.5): what the connected bridge can tell the
+ * Introspection: what the connected bridge can tell the
  * cloud about the robot's ROS graph, so the console can offer a quick pick
  * instead of a blank text field.
  *
@@ -31,10 +31,10 @@ export const typeField = z.lazy(() => z.object({
     fields: z.array(typeField).nullable(),
 }));
 /**
- * A resolved type of one robot. Custom types are per robot (spec §4.5): two
- * robots may define `custom_msgs/msg/Speed` differently and both are right.
+ * A resolved type of one robot. Custom types are per robot: two robots may
+ * define `custom_msgs/msg/Speed` differently and both are right.
  *
- * W2 resolved messages only; W4 adds services and actions, because a
+ * Messages, services and actions all appear here, because a
  * `parameterSpec.name` has to resolve against *something*, and an action has
  * no flat field list — it has a goal, a result and a feedback tree.
  *
@@ -51,8 +51,8 @@ export const typeField = z.lazy(() => z.object({
  * a result in. They are carried so the console can show what an action will
  * report back, and so a client knows the shape of `job.result` in advance.
  *
- * The `msg` member keeps W2's exact shape, so every type already stored stays
- * valid without migration.
+ * The `msg` member is the flat field list a message resolves to; the other
+ * two carry one tree per part.
  */
 export const typeDefinition = z.discriminatedUnion('kind', [
     z.object({

package/dist/jobs.d.ts

@@ -1,15 +1,16 @@
+// SPDX-License-Identifier: Apache-2.0
 import { z } from 'zod';
 /**
- * Jobs (spec §6.1, §11.3): one running unit of work on a robot — an action
+ * Jobs: one running unit of work on a robot — an action
  * goal or a service call — with an id both sides know, so bridge and cloud
  * stay in sync across a disconnect.
  *
  * Two rules shape everything here:
  *
- * 1. **State is observed by slug, not by id.** The id is informative (§11.3);
- *    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** (§6.1). Job state
+ * 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
@@ -49,8 +50,8 @@ export type Job = z.infer<typeof job>;
 /**
  * One update about a job, pushed to subscribers of its slug.
  *
- * `timestamp_ms` is the bridge's capture time, exactly as for a datapoint
- * (§6.3 says action feedback carries it too) — so a client computes the age
+ * `timestamp_ms` is the bridge's capture time, exactly as for a datapoint —
+ * action feedback carries it too — so a client computes the age
  * of a progress report the same way it computes the age of a sensor value,
  * and a burst of late-delivered feedback after a reconnect is visibly late
  * rather than looking current.
@@ -86,9 +87,8 @@ export declare const jobEvent: z.ZodObject<{
 }, z.core.$strip>;
 export type JobEvent = z.infer<typeof jobEvent>;
 /**
- * What a busy refusal tells the caller (spec §11.3: "inkl. Information, was
- * läuft"). A refusal that only says "busy" forces the caller to guess whether
- * to wait or to give up.
+ * 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.
  */
 export declare const busyDetails: z.ZodObject<{
     running: z.ZodObject<{
@@ -115,7 +115,7 @@ export declare const busyDetails: z.ZodObject<{
 }, z.core.$strip>;
 export type BusyDetails = z.infer<typeof busyDetails>;
 /**
- * What a `publisher_busy` refusal tells the caller (spec §6.4).
+ * What a `publisher_busy` refusal tells the caller.
  *
  * "Another caller is publishing and has not been quiet long enough" names a
  * state and no action: the caller does not know how much longer, because
@@ -133,7 +133,7 @@ export declare const publisherBusyDetails: z.ZodObject<{
 }, z.core.$strip>;
 export type PublisherBusyDetails = z.infer<typeof publisherBusyDetails>;
 /**
- * What a `job_queue_full` refusal tells the caller (W6b).
+ * What a `job_queue_full` refusal tells the caller.
  *
  * Both numbers, not just the limit: `limit` alone says how big the queue is
  * and nothing about whether waiting will help, and `queued` alone cannot be

package/dist/jobs.js

@@ -2,16 +2,16 @@
 import { z } from 'zod';
 import { slug, wireSeqCursor, wireTimestampMs } from './common.js';
 /**
- * Jobs (spec §6.1, §11.3): one running unit of work on a robot — an action
+ * Jobs: one running unit of work on a robot — an action
  * goal or a service call — with an id both sides know, so bridge and cloud
  * stay in sync across a disconnect.
  *
  * Two rules shape everything here:
  *
- * 1. **State is observed by slug, not by id.** The id is informative (§11.3);
- *    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** (§6.1). Job state
+ * 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
@@ -37,17 +37,17 @@ export const job = z.object({
         description: 'When this job last changed, as an ISO 8601 timestamp.',
     }),
     /**
-     * A monotonic counter, ascending in mint order (W7), and the **named**
-     * tiebreaker for any listing that claims an order.
+     * A monotonic counter, ascending in mint order, and the **named** tiebreaker
+     * for any listing that claims an order.
      *
      * `started_at` is not a total order: two jobs minted in the same millisecond
      * sort against each other arbitrarily, and arbitrarily means *differently on
      * each query* — so `GET /api/robots/:id/jobs`, which documents "newest
-     * first", can show one twice and the other not at all. Exactly the defect
-     * `auditEvent.seq` was added for in W6b, in a route the same wave shipped.
+     * first", can show one twice and the other not at all. `auditEvent.seq`
+     * exists for the same reason on the audit log.
      *
      * **Scoped honestly: per cloud process, per run.** Job state lives in memory
-     * (§6.1 — that is why `lost` exists at all), so this counter restarts when
+     * — that is why `lost` exists 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.
@@ -62,14 +62,10 @@ export const job = z.object({
      * Present on `failed`; a human message, plus a code where one exists.
      *
      * `details` exists because a refusal that carries only prose forces every
-     * consumer to parse it. W6b shipped `job_queue_full` with a documented
-     * `{limit, queued}` payload and **nowhere to put it**: the bridge reports a
-     * full queue as a job error, this shape had no `details`, and so the numbers
-     * were formatted into the message and lost. The console then rendered a
-     * "wait for one of N to finish" alert from a shape nothing in the system
-     * produced, and its test built that shape by hand — three repos agreeing
-     * with each other about a payload none of them exchanged (Momus, W6b
-     * review).
+     * consumer to parse it. A documented payload with nowhere to put it — the
+     * bridge reports a full queue as a job error — ends up formatted into the
+     * message and lost, and every consumer then builds the structured shape by
+     * hand from its own assumption.
      *
      * Optional, because most job errors have nothing structured to add. Where a
      * code has a documented payload — `job_queue_full` has
@@ -95,8 +91,8 @@ export const job = z.object({
 /**
  * One update about a job, pushed to subscribers of its slug.
  *
- * `timestamp_ms` is the bridge's capture time, exactly as for a datapoint
- * (§6.3 says action feedback carries it too) — so a client computes the age
+ * `timestamp_ms` is the bridge's capture time, exactly as for a datapoint —
+ * action feedback carries it too — so a client computes the age
  * of a progress report the same way it computes the age of a sensor value,
  * and a burst of late-delivered feedback after a reconnect is visibly late
  * rather than looking current.
@@ -113,15 +109,14 @@ export const jobEvent = z.object({
     timestamp_ms: z.number().int().nonnegative(),
 });
 /**
- * What a busy refusal tells the caller (spec §11.3: "inkl. Information, was
- * läuft"). A refusal that only says "busy" forces the caller to guess whether
- * to wait or to give up.
+ * 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.
  */
 export const busyDetails = z.object({
     running: job,
 });
 /**
- * What a `publisher_busy` refusal tells the caller (spec §6.4).
+ * What a `publisher_busy` refusal tells the caller.
  *
  * "Another caller is publishing and has not been quiet long enough" names a
  * state and no action: the caller does not know how much longer, because
@@ -140,7 +135,7 @@ export const publisherBusyDetails = z.object({
     retry_after_ms: z.number().int().nonnegative(),
 });
 /**
- * What a `job_queue_full` refusal tells the caller (W6b).
+ * What a `job_queue_full` refusal tells the caller.
  *
  * Both numbers, not just the limit: `limit` alone says how big the queue is
  * and nothing about whether waiting will help, and `queued` alone cannot be

package/dist/mcp.d.ts

@@ -1,9 +1,9 @@
+// SPDX-License-Identifier: Apache-2.0
 import { z } from 'zod';
 /**
- * The MCP server of §17: **one** remote MCP endpoint for the whole platform,
- * whose tools are the exposed services and datapoints the signed-in user's
- * roles permit. The per-app `/mcp/<identifier>` servers this file once
- * described were deleted by the org-central identity redesign (D5/D6).
+ * The MCP server: **one** remote MCP endpoint for the whole platform, whose
+ * tools are the exposed services and datapoints the signed-in user's roles
+ * permit. There is no per-app endpoint.
  *
  * **This file describes the seam, not the protocol.** The MCP messages
  * themselves (`initialize`, `tools/list`, `tools/call`) are defined by the
@@ -15,8 +15,8 @@ import { z } from 'zod';
  * an end user ever connects.
  */
 /**
- * The protocol revision W7c speaks. Chosen with André on 2026-08-18 over the
- * newer `2026-07-28`.
+ * The protocol revision this server speaks, chosen over the newer
+ * `2026-07-28`.
  *
  * This is the latest revision the **stable** MCP TypeScript SDK ships, and it
  * negotiates down to `2024-11-05`, so it covers the AI tools that exist today.
@@ -24,11 +24,10 @@ import { z } from 'zod';
  * Streamable HTTP's session ids, the standalone SSE channel and resumability,
  * and servers speaking only it answer `405` to GET and DELETE.
  *
- * **Which is why this server is stateless anyway.** Building sessions we would
- * have to delete again is work in the wrong direction, and a per-process
- * session map is the assumption that breaks at the second cloud instance —
- * the register already carries one row of exactly that shape
- * (`max_realtime_connections`), and W8 is where a second instance appears.
+ * **Which is why this server is stateless anyway.** Building sessions that a
+ * later revision removes is work in the wrong direction, and a per-process
+ * session map is an assumption that breaks the moment a second cloud instance
+ * exists.
  */
 export declare const MCP_PROTOCOL_VERSION: "2025-11-25";
 /**
@@ -144,7 +143,7 @@ export declare const MCP_TOOL_NAME_MAX = 128;
 export declare const mcpToolNamePattern: RegExp;
 /**
  * One exposure of a robot, as `robot_describe` and the console's per-role
- * preview list it (FL-006). Every exposure the role grants is listed —
+ * preview list it. Every exposure the role grants is listed —
  * a missing `description` is shown as `null`, never used to hide the entry.
  *
  * `input_schema` is a JSON Schema document generated from an action's,

package/dist/mcp.js

@@ -2,10 +2,9 @@
 import { z } from 'zod';
 import { slug } from './common.js';
 /**
- * The MCP server of §17: **one** remote MCP endpoint for the whole platform,
- * whose tools are the exposed services and datapoints the signed-in user's
- * roles permit. The per-app `/mcp/<identifier>` servers this file once
- * described were deleted by the org-central identity redesign (D5/D6).
+ * The MCP server: **one** remote MCP endpoint for the whole platform, whose
+ * tools are the exposed services and datapoints the signed-in user's roles
+ * permit. There is no per-app endpoint.
  *
  * **This file describes the seam, not the protocol.** The MCP messages
  * themselves (`initialize`, `tools/list`, `tools/call`) are defined by the
@@ -17,8 +16,8 @@ import { slug } from './common.js';
  * an end user ever connects.
  */
 /**
- * The protocol revision W7c speaks. Chosen with André on 2026-08-18 over the
- * newer `2026-07-28`.
+ * The protocol revision this server speaks, chosen over the newer
+ * `2026-07-28`.
  *
  * This is the latest revision the **stable** MCP TypeScript SDK ships, and it
  * negotiates down to `2024-11-05`, so it covers the AI tools that exist today.
@@ -26,11 +25,10 @@ import { slug } from './common.js';
  * Streamable HTTP's session ids, the standalone SSE channel and resumability,
  * and servers speaking only it answer `405` to GET and DELETE.
  *
- * **Which is why this server is stateless anyway.** Building sessions we would
- * have to delete again is work in the wrong direction, and a per-process
- * session map is the assumption that breaks at the second cloud instance —
- * the register already carries one row of exactly that shape
- * (`max_realtime_connections`), and W8 is where a second instance appears.
+ * **Which is why this server is stateless anyway.** Building sessions that a
+ * later revision removes is work in the wrong direction, and a per-process
+ * session map is an assumption that breaks the moment a second cloud instance
+ * exists.
  */
 export const MCP_PROTOCOL_VERSION = '2025-11-25';
 /**
@@ -97,7 +95,7 @@ export const MCP_TOOL_NAME_MAX = 128;
 export const mcpToolNamePattern = /^[a-z0-9][a-z0-9_-]*$/;
 /**
  * One exposure of a robot, as `robot_describe` and the console's per-role
- * preview list it (FL-006). Every exposure the role grants is listed —
+ * preview list it. Every exposure the role grants is listed —
  * a missing `description` is shown as `null`, never used to hide the entry.
  *
  * `input_schema` is a JSON Schema document generated from an action's,

package/dist/oauth.d.ts

@@ -1,3 +1,4 @@
+// SPDX-License-Identifier: Apache-2.0
 import { z } from 'zod';
 /**
  * **OAuth 2.1, and it remains only for MCP** (2026-09-05 app-user-auth, D8).
@@ -82,15 +83,11 @@ export type OauthError = z.infer<typeof oauthError>;
 /**
  * A redirect URI, and the rule is stricter than "a URL".
  *
- * **The defence for this was already written down in this codebase, twice.**
- * `config.ts` validates a V4L2 device path from the wire with a prefix rule
- * *and* an explicit refusal of `..` segments, tested, with the reasoning
- * recorded; W7's review then found a `package://` traversal in the bridge
- * that the same rule would have prevented, and the finding that mattered was
- * not the traversal but that **the rule existed one file over and was never
- * carried across.** A redirect URI is the same shape of problem from a less
- * trusted source: an attacker-supplied string that decides where a credential
- * is sent.
+ * **The same defence is written down elsewhere in this package.** `config.ts`
+ * validates a capture-device path from the wire with a prefix rule *and* an
+ * explicit refusal of `..` segments. A redirect URI is the same shape of
+ * problem from a less trusted source: an attacker-supplied string that decides
+ * where a credential is sent.
  *
  * Matching at the server is **exact string comparison against a registered
  * value** — never a prefix, never a wildcard host, never "starts with". A
@@ -124,7 +121,7 @@ export declare const MCP_DCR_MAX_REDIRECT_URIS = 5;
  * authorization servers understand**, central and per-app.
  *
  * **Not `.strict()`, and that is the schema agreeing with the server rather
- * than a gap in it.** §3.1 obliges a registration endpoint to ignore metadata
+ * than a gap in it.** RFC 7591 §3.1 obliges a registration endpoint to ignore metadata
  * it does not understand, and real MCP clients send `client_uri`, `logo_uri`,
  * `software_id` and `contacts`. A strict shape here would describe a `400`
  * that no conforming client ever earns, and would take the whole
@@ -132,9 +129,8 @@ export declare const MCP_DCR_MAX_REDIRECT_URIS = 5;
  * are therefore stripped by this schema and ignored by the server, which is
  * the same answer said twice.
  *
- * **The server still reads the body field by field** (`registerMcpDynamicClient`
- * in `cloud/src/mcp-oauth-core.ts`), and the reason is the error vocabulary,
- * not the shape: §3.2.2 distinguishes `invalid_redirect_uri` from
+ * **The server still reads the body field by field**, and the reason is the
+ * error vocabulary, not the shape: RFC 7591 §3.2.2 distinguishes `invalid_redirect_uri` from
  * `invalid_client_metadata`, and one `safeParse` failure cannot say which of
  * the two a caller earned. So this schema is what the endpoint *accepts*, and
  * the handler is what turns a miss into the right RFC code.
@@ -262,11 +258,10 @@ export type AuthorizationServerMetadata = z.infer<typeof authorizationServerMeta
 /**
  * RFC 9728 — what a *resource* publishes about who may authorize for it.
  *
- * W7b mints tokens bound to a resource that W7c builds. **A minting mechanism
- * with no validator is the failure mode this project has now met twelve times
- * in one wave: a check that cannot fail.** So W7b also ships a resource that
- * *rejects* a token whose audience names something else, and the gate measures
- * the rejection rather than the presence of the claim.
+ * Tokens are minted bound to a resource. **A minting mechanism with no
+ * validator is a check that cannot fail**, so the resource itself *rejects* a
+ * token whose audience names something else, and that rejection is what a check
+ * measures rather than the presence of the claim.
  */
 export declare const protectedResourceMetadata: z.ZodObject<{
     resource: z.ZodURL;

package/dist/oauth.js

@@ -89,15 +89,11 @@ export const oauthError = z.object({
 /**
  * A redirect URI, and the rule is stricter than "a URL".
  *
- * **The defence for this was already written down in this codebase, twice.**
- * `config.ts` validates a V4L2 device path from the wire with a prefix rule
- * *and* an explicit refusal of `..` segments, tested, with the reasoning
- * recorded; W7's review then found a `package://` traversal in the bridge
- * that the same rule would have prevented, and the finding that mattered was
- * not the traversal but that **the rule existed one file over and was never
- * carried across.** A redirect URI is the same shape of problem from a less
- * trusted source: an attacker-supplied string that decides where a credential
- * is sent.
+ * **The same defence is written down elsewhere in this package.** `config.ts`
+ * validates a capture-device path from the wire with a prefix rule *and* an
+ * explicit refusal of `..` segments. A redirect URI is the same shape of
+ * problem from a less trusted source: an attacker-supplied string that decides
+ * where a credential is sent.
  *
  * Matching at the server is **exact string comparison against a registered
  * value** — never a prefix, never a wildcard host, never "starts with". A
@@ -133,7 +129,7 @@ export const redirectUri = z
     // yields `"["` for `[::1]:8080`, because an IPv6 literal is *made of*
     // colons. So `[::1]` never matched the allow-list it is named in, in any
     // spelling, while two developer-facing messages went on saying it was
-    // permitted. Found by Momus-W7b, reproduced against the live server.
+    // permitted.
     // `hostname` already strips the port and keeps the brackets.
     if (url.protocol === 'http:')
         return ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname);
@@ -162,7 +158,7 @@ export const MCP_DCR_MAX_REDIRECT_URIS = 5;
  * authorization servers understand**, central and per-app.
  *
  * **Not `.strict()`, and that is the schema agreeing with the server rather
- * than a gap in it.** §3.1 obliges a registration endpoint to ignore metadata
+ * than a gap in it.** RFC 7591 §3.1 obliges a registration endpoint to ignore metadata
  * it does not understand, and real MCP clients send `client_uri`, `logo_uri`,
  * `software_id` and `contacts`. A strict shape here would describe a `400`
  * that no conforming client ever earns, and would take the whole
@@ -170,9 +166,8 @@ export const MCP_DCR_MAX_REDIRECT_URIS = 5;
  * are therefore stripped by this schema and ignored by the server, which is
  * the same answer said twice.
  *
- * **The server still reads the body field by field** (`registerMcpDynamicClient`
- * in `cloud/src/mcp-oauth-core.ts`), and the reason is the error vocabulary,
- * not the shape: §3.2.2 distinguishes `invalid_redirect_uri` from
+ * **The server still reads the body field by field**, and the reason is the
+ * error vocabulary, not the shape: RFC 7591 §3.2.2 distinguishes `invalid_redirect_uri` from
  * `invalid_client_metadata`, and one `safeParse` failure cannot say which of
  * the two a caller earned. So this schema is what the endpoint *accepts*, and
  * the handler is what turns a miss into the right RFC code.
@@ -359,11 +354,10 @@ export const authorizationServerMetadata = z.object({
 /**
  * RFC 9728 — what a *resource* publishes about who may authorize for it.
  *
- * W7b mints tokens bound to a resource that W7c builds. **A minting mechanism
- * with no validator is the failure mode this project has now met twelve times
- * in one wave: a check that cannot fail.** So W7b also ships a resource that
- * *rejects* a token whose audience names something else, and the gate measures
- * the rejection rather than the presence of the claim.
+ * Tokens are minted bound to a resource. **A minting mechanism with no
+ * validator is a check that cannot fail**, so the resource itself *rejects* a
+ * token whose audience names something else, and that rejection is what a check
+ * measures rather than the presence of the claim.
  */
 export const protectedResourceMetadata = z.object({
     resource: z.url().meta({