@fleetless/contracts 1.0.0

package/dist/introspection.d.ts

@@ -0,0 +1,99 @@
+import { z } from 'zod';
+/**
+ * Introspection (spec §4.1, §4.5): 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.
+ *
+ * Introspection is an *enrichment*, never a precondition — a robot that has
+ * never been connected is still fully configurable.
+ */
+/** One entry of the ROS graph: a name and the types announced on it. */
+export declare const rosGraphEntry: z.ZodObject<{
+    name: z.ZodString;
+    types: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+export type RosGraphEntry = z.infer<typeof rosGraphEntry>;
+/**
+ * A snapshot of the graph. `captured_at_ms` is the bridge's clock at capture
+ * time, so the console can say how old the picture is.
+ */
+export declare const rosGraph: z.ZodObject<{
+    topics: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        types: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>>;
+    services: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        types: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>>;
+    actions: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        types: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>>;
+    captured_at_ms: z.ZodNumber;
+}, z.core.$strip>;
+export type RosGraph = z.infer<typeof rosGraph>;
+/**
+ * One field of a message type. `fields` is null for primitives and set for
+ * nested messages; `array` marks sequences of whatever `type` says.
+ */
+export interface TypeField {
+    name: string;
+    type: string;
+    array: boolean;
+    fields: TypeField[] | null;
+}
+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.
+ *
+ * W2 resolved messages only; W4 adds services and actions, 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.
+ *
+ * **Which tree a parameter resolves against** (the rule every consumer needs
+ * and none should re-derive):
+ *
+ * | config kind | type | parameters resolve against |
+ * |---|---|---|
+ * | `actionConfig`    | `pkg/action/T` | `goal`     |
+ * | `serviceConfig`   | `pkg/srv/T`    | `request`  |
+ * | `publisherConfig` | `pkg/msg/T`    | `fields`   |
+ *
+ * `result`/`feedback`/`response` are never parameter targets — nobody passes
+ * 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.
+ */
+export declare const typeDefinition: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    name: z.ZodString;
+    kind: z.ZodLiteral<"msg">;
+    fields: z.ZodArray<z.ZodType<TypeField, unknown, z.core.$ZodTypeInternals<TypeField, unknown>>>;
+}, z.core.$strip>, z.ZodObject<{
+    name: z.ZodString;
+    kind: z.ZodLiteral<"srv">;
+    request: z.ZodArray<z.ZodType<TypeField, unknown, z.core.$ZodTypeInternals<TypeField, unknown>>>;
+    response: z.ZodArray<z.ZodType<TypeField, unknown, z.core.$ZodTypeInternals<TypeField, unknown>>>;
+}, z.core.$strip>, z.ZodObject<{
+    name: z.ZodString;
+    kind: z.ZodLiteral<"action">;
+    goal: z.ZodArray<z.ZodType<TypeField, unknown, z.core.$ZodTypeInternals<TypeField, unknown>>>;
+    result: z.ZodArray<z.ZodType<TypeField, unknown, z.core.$ZodTypeInternals<TypeField, unknown>>>;
+    feedback: z.ZodArray<z.ZodType<TypeField, unknown, z.core.$ZodTypeInternals<TypeField, unknown>>>;
+}, z.core.$strip>], "kind">;
+export type TypeDefinition = z.infer<typeof typeDefinition>;
+/**
+ * The tree a message template resolves against, per the table above.
+ *
+ * What resolves against it is a **placeholder's position in the template** —
+ * the field the `${name}` sits on — and not the parameter's name.
+ * `parameterSpec` has no `name`; `parameters` is a record keyed by name, and
+ * the format decouples that name from the field path on purpose, so a
+ * parameter survives its field moving in the tree.
+ *
+ * One helper so cloud, console and SDK cannot each pick a different field.
+ */
+export declare function parameterFieldsOf(def: TypeDefinition): TypeField[];

package/dist/introspection.js

@@ -0,0 +1,97 @@
+// SPDX-License-Identifier: Apache-2.0
+import { z } from 'zod';
+import { rosName, rosTypeName } from './common.js';
+/**
+ * Introspection (spec §4.1, §4.5): 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.
+ *
+ * Introspection is an *enrichment*, never a precondition — a robot that has
+ * never been connected is still fully configurable.
+ */
+/** One entry of the ROS graph: a name and the types announced on it. */
+export const rosGraphEntry = z.object({
+    name: rosName,
+    types: z.array(rosTypeName).min(1),
+});
+/**
+ * A snapshot of the graph. `captured_at_ms` is the bridge's clock at capture
+ * time, so the console can say how old the picture is.
+ */
+export const rosGraph = z.object({
+    topics: z.array(rosGraphEntry),
+    services: z.array(rosGraphEntry),
+    actions: z.array(rosGraphEntry),
+    captured_at_ms: z.number().int().nonnegative(),
+});
+export const typeField = z.lazy(() => z.object({
+    name: z.string().min(1).max(128),
+    type: z.string().min(1).max(255),
+    array: z.boolean(),
+    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.
+ *
+ * W2 resolved messages only; W4 adds services and actions, 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.
+ *
+ * **Which tree a parameter resolves against** (the rule every consumer needs
+ * and none should re-derive):
+ *
+ * | config kind | type | parameters resolve against |
+ * |---|---|---|
+ * | `actionConfig`    | `pkg/action/T` | `goal`     |
+ * | `serviceConfig`   | `pkg/srv/T`    | `request`  |
+ * | `publisherConfig` | `pkg/msg/T`    | `fields`   |
+ *
+ * `result`/`feedback`/`response` are never parameter targets — nobody passes
+ * 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.
+ */
+export const typeDefinition = z.discriminatedUnion('kind', [
+    z.object({
+        name: rosTypeName,
+        kind: z.literal('msg'),
+        fields: z.array(typeField),
+    }),
+    z.object({
+        name: rosTypeName,
+        kind: z.literal('srv'),
+        request: z.array(typeField),
+        response: z.array(typeField),
+    }),
+    z.object({
+        name: rosTypeName,
+        kind: z.literal('action'),
+        goal: z.array(typeField),
+        result: z.array(typeField),
+        feedback: z.array(typeField),
+    }),
+]);
+/**
+ * The tree a message template resolves against, per the table above.
+ *
+ * What resolves against it is a **placeholder's position in the template** —
+ * the field the `${name}` sits on — and not the parameter's name.
+ * `parameterSpec` has no `name`; `parameters` is a record keyed by name, and
+ * the format decouples that name from the field path on purpose, so a
+ * parameter survives its field moving in the tree.
+ *
+ * One helper so cloud, console and SDK cannot each pick a different field.
+ */
+export function parameterFieldsOf(def) {
+    switch (def.kind) {
+        case 'msg':
+            return def.fields;
+        case 'srv':
+            return def.request;
+        case 'action':
+            return def.goal;
+    }
+}

package/dist/jobs.d.ts

@@ -0,0 +1,334 @@
+import { z } from 'zod';
+/**
+ * Jobs (spec §6.1, §11.3): 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
+ *    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.
+ */
+export declare const jobState: z.ZodEnum<{
+    failed: "failed";
+    running: "running";
+    succeeded: "succeeded";
+    cancelled: "cancelled";
+    lost: "lost";
+}>;
+export type JobState = z.infer<typeof jobState>;
+export declare const job: z.ZodObject<{
+    id: z.ZodUUID;
+    robot_id: z.ZodUUID;
+    slug: z.ZodString;
+    state: z.ZodEnum<{
+        failed: "failed";
+        running: "running";
+        succeeded: "succeeded";
+        cancelled: "cancelled";
+        lost: "lost";
+    }>;
+    started_at: z.ZodISODateTime;
+    updated_at: z.ZodISODateTime;
+    seq: 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 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
+ * 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.
+ */
+export declare const jobEvent: z.ZodObject<{
+    type: z.ZodLiteral<"job">;
+    robot_id: z.ZodUUID;
+    slug: z.ZodString;
+    job: z.ZodObject<{
+        id: z.ZodUUID;
+        robot_id: z.ZodUUID;
+        slug: z.ZodString;
+        state: z.ZodEnum<{
+            failed: "failed";
+            running: "running";
+            succeeded: "succeeded";
+            cancelled: "cancelled";
+            lost: "lost";
+        }>;
+        started_at: z.ZodISODateTime;
+        updated_at: z.ZodISODateTime;
+        seq: 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>;
+    feedback: z.ZodNullable<z.ZodUnknown>;
+    progress: z.ZodNullable<z.ZodNumber>;
+    timestamp_ms: z.ZodNumber;
+}, 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.
+ */
+export declare const busyDetails: z.ZodObject<{
+    running: z.ZodObject<{
+        id: z.ZodUUID;
+        robot_id: z.ZodUUID;
+        slug: z.ZodString;
+        state: z.ZodEnum<{
+            failed: "failed";
+            running: "running";
+            succeeded: "succeeded";
+            cancelled: "cancelled";
+            lost: "lost";
+        }>;
+        started_at: z.ZodISODateTime;
+        updated_at: z.ZodISODateTime;
+        seq: 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>;
+}, z.core.$strip>;
+export type BusyDetails = z.infer<typeof busyDetails>;
+/**
+ * What a `publisher_busy` refusal tells the caller (spec §6.4).
+ *
+ * "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
+ * `quiet_timeout_ms` lives in the configuration document, which a client app
+ * never reads. Without a number they busy-loop — on the one verb that moves
+ * a machine, on a platform with no rate limiting. So the refusal carries the
+ * wait itself.
+ *
+ * `holder` is deliberately absent: it would name another end user to a
+ * caller who may have no right to know they exist.
+ */
+export declare const publisherBusyDetails: z.ZodObject<{
+    quiet_timeout_ms: z.ZodNumber;
+    retry_after_ms: z.ZodNumber;
+}, z.core.$strip>;
+export type PublisherBusyDetails = z.infer<typeof publisherBusyDetails>;
+/**
+ * What a `job_queue_full` refusal tells the caller (W6b).
+ *
+ * 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
+ * read without knowing the bound. Together they are the only two facts a
+ * caller needs to decide between retrying and giving up.
+ */
+export declare const jobQueueFullDetails: z.ZodObject<{
+    limit: z.ZodNumber;
+    queued: z.ZodNumber;
+}, z.core.$strip>;
+export type JobQueueFullDetails = z.infer<typeof jobQueueFullDetails>;
+/** A page of run history is bounded; 200 is what one console screen can ever want. */
+export declare const JOB_RUN_PAGE_MAX = 200;
+/**
+ * Job runs keep the audit log's retention, and that is not a coincidence:
+ * every invoke already writes an `action.invoked` audit event. A different
+ * figure here creates a window in which the audit log shows a call whose
+ * outcome has already been deleted — a state no developer can be expected to
+ * read as anything but a bug.
+ */
+export declare const JOB_RUN_RETENTION_DAYS = 90;
+/**
+ * Who invoked a run.
+ *
+ * Deliberately **not** `auditActor`: that enum carries `bridge` as a fourth
+ * case, and a bridge invokes nothing. An enum that names an impossible case
+ * invites every reader to handle it.
+ *
+ * **`app_user` is what a client-app caller writes now, and `end_user` stays**
+ * (app-user auth, D1). The seam this comment used to describe — two names for
+ * two ways into one merged pool — is settled: the two identity spaces are
+ * separate tables again, and `app_user` is a row in `app_users`, belonging to
+ * exactly one app. `end_user` is kept for the same reason `auditActor.kind`
+ * keeps it: a job run is history, and every row written before the cut carries
+ * it. Removing the member would make the whole trail unparseable to a client
+ * that validates, which is the one thing a history shape must never do.
+ */
+export declare const jobActor: z.ZodObject<{
+    kind: z.ZodEnum<{
+        developer: "developer";
+        server_key: "server_key";
+        end_user: "end_user";
+        app_user: "app_user";
+    }>;
+    id: z.ZodUUID;
+    label: z.ZodString;
+}, z.core.$strip>;
+export type JobActor = z.infer<typeof jobActor>;
+export declare const jobRunKind: z.ZodEnum<{
+    action: "action";
+    service: "service";
+}>;
+export type JobRunKind = z.infer<typeof jobRunKind>;
+/**
+ * One durable record of one invocation (spec `2026-08-20-timeseries-and-run-history`,
+ * D2). One row per run, never one per event: the per-event timeline's write rate
+ * is set by the bridge, and a throttled log that cannot say it was throttled is
+ * the instrument this codebase refuses everywhere else. The live timeline is
+ * delivered in full by realtime, for as long as somebody is watching.
+ */
+export declare const jobRun: z.ZodObject<{
+    id: z.ZodUUID;
+    robot_id: z.ZodUUID;
+    slug: z.ZodString;
+    kind: z.ZodEnum<{
+        action: "action";
+        service: "service";
+    }>;
+    state: z.ZodEnum<{
+        failed: "failed";
+        running: "running";
+        succeeded: "succeeded";
+        cancelled: "cancelled";
+        lost: "lost";
+    }>;
+    started_at: z.ZodISODateTime;
+    ended_at: z.ZodNullable<z.ZodISODateTime>;
+    duration_ms: 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>>;
+    actor: z.ZodObject<{
+        kind: z.ZodEnum<{
+            developer: "developer";
+            server_key: "server_key";
+            end_user: "end_user";
+            app_user: "app_user";
+        }>;
+        id: z.ZodUUID;
+        label: z.ZodString;
+    }, z.core.$strip>;
+    seq: z.ZodNumber;
+    progress: z.ZodNullable<z.ZodNumber>;
+    feedback: z.ZodNullable<z.ZodUnknown>;
+}, z.core.$strip>;
+export type JobRun = z.infer<typeof jobRun>;
+export declare const jobRunQuery: z.ZodObject<{
+    before_seq: z.ZodOptional<z.ZodPipe<z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>, z.ZodTransform<number, string | number>>, z.ZodNumber>>;
+    limit: z.ZodOptional<z.ZodPipe<z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>, z.ZodTransform<number, string | number>>, z.ZodNumber>>;
+    robot_id: z.ZodOptional<z.ZodUUID>;
+    slug: z.ZodOptional<z.ZodString>;
+    state: z.ZodOptional<z.ZodEnum<{
+        failed: "failed";
+        running: "running";
+        succeeded: "succeeded";
+        cancelled: "cancelled";
+        lost: "lost";
+    }>>;
+    kind: z.ZodOptional<z.ZodEnum<{
+        action: "action";
+        service: "service";
+    }>>;
+    from_ms: z.ZodOptional<z.ZodPipe<z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>, z.ZodTransform<number, string | number>>, z.ZodNumber>>;
+    to_ms: z.ZodOptional<z.ZodPipe<z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>, z.ZodTransform<number, string | number>>, z.ZodNumber>>;
+}, z.core.$strict>;
+export type JobRunQuery = z.infer<typeof jobRunQuery>;
+export declare const jobRunListResponse: z.ZodObject<{
+    runs: z.ZodArray<z.ZodObject<{
+        id: z.ZodUUID;
+        robot_id: z.ZodUUID;
+        slug: z.ZodString;
+        kind: z.ZodEnum<{
+            action: "action";
+            service: "service";
+        }>;
+        state: z.ZodEnum<{
+            failed: "failed";
+            running: "running";
+            succeeded: "succeeded";
+            cancelled: "cancelled";
+            lost: "lost";
+        }>;
+        started_at: z.ZodISODateTime;
+        ended_at: z.ZodNullable<z.ZodISODateTime>;
+        duration_ms: 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>>;
+        actor: z.ZodObject<{
+            kind: z.ZodEnum<{
+                developer: "developer";
+                server_key: "server_key";
+                end_user: "end_user";
+                app_user: "app_user";
+            }>;
+            id: z.ZodUUID;
+            label: z.ZodString;
+        }, z.core.$strip>;
+        seq: z.ZodNumber;
+        progress: z.ZodNullable<z.ZodNumber>;
+        feedback: z.ZodNullable<z.ZodUnknown>;
+    }, z.core.$strip>>;
+    next_cursor: z.ZodNullable<z.ZodNumber>;
+}, z.core.$strip>;
+export type JobRunListResponse = z.infer<typeof jobRunListResponse>;
+/**
+ * The overview tile's three numbers, over a window **the caller names**.
+ *
+ * `since_ms` rather than "today": which day that is, only the browser knows. A
+ * cloud that picks its own day boundary shows a developer in another timezone a
+ * number they cannot reproduce. Echoed back so a rendered tile can say which
+ * window it is describing.
+ */
+/**
+ * `GET /api/org/jobs/summary`'s query: the window, and nothing else.
+ *
+ * **`since_ms` is required and has no default.** Which day "today" is, only
+ * the browser knows; a cloud that picked its own boundary would show a
+ * developer in another timezone a number they cannot reproduce from anything
+ * in front of them. The absence of a default is the contract here, not an
+ * omission — see `jobRunSummary`, which echoes the window back so a rendered
+ * tile can say what it is describing.
+ *
+ * Its own shape rather than a slice of `jobRunQuery`: pagination and filters
+ * mean nothing to an aggregate, and `.strict()` would refuse them anyway, so
+ * borrowing that schema would advertise seven parameters the route ignores.
+ *
+ * `.strict()` for `jobRunQuery`'s reason — a mistyped `since_mss` that is
+ * silently ignored answers `200` over a window nobody chose, which is worse
+ * than a refusal because it looks like data.
+ */
+export declare const jobRunSummaryQuery: z.ZodObject<{
+    since_ms: z.ZodPipe<z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>, z.ZodTransform<number, string | number>>, z.ZodNumber>;
+}, z.core.$strict>;
+export type JobRunSummaryQuery = z.infer<typeof jobRunSummaryQuery>;
+export declare const jobRunSummary: z.ZodObject<{
+    running: z.ZodNumber;
+    started: z.ZodNumber;
+    failed: z.ZodNumber;
+    since_ms: z.ZodNumber;
+}, z.core.$strip>;
+export type JobRunSummary = z.infer<typeof jobRunSummary>;