@fleetless/contracts 1.0.0

package/dist/assets.d.ts

@@ -0,0 +1,434 @@
+import { z } from 'zod';
+/**
+ * The asset store (spec §4.6, W7).
+ *
+ * An **asset is an immutable file belonging to a robot**. It has a uuid and is
+ * fetched by it. There are no org-level assets and no public retrieval: every
+ * read is authenticated and role-checked (`assets`, §3.3).
+ *
+ * **One authorization model — the `Authorization` header.** Not a signed URL,
+ * not a cookie, not a token in a query string. The reason is not ergonomics
+ * but the number of mechanisms: a second credential would carry its own
+ * lifetime, its own renewal, its own rotation, and in every log the question
+ * of which token that was. Directus solves the same problem with a cookie and
+ * an `access_token` query parameter, and the cookie half does not transfer —
+ * Fleetless has no interface of its own (§1), so the consumers of a robot's
+ * assets sit on other origins.
+ *
+ * **The consequence, said out loud: this is not a CDN.** A shared cache must
+ * not store a response to a request carrying `Authorization`. Assets are
+ * immutable, so `Cache-Control: private, immutable` is correct and the
+ * browser's own cache works fully; nothing edge-caches. Calling it a CDN would
+ * promise something that does not happen. Signed URLs stay **additive** later —
+ * a second endpoint, not a migration — precisely because assets are immutable
+ * and uuid-addressed.
+ *
+ * ---
+ *
+ * **`texture` is its own member of `assetKind` and not `other` (W7a, D2).**
+ *
+ * Filing textures under `other` would be the catch-all this project has
+ * already split five times, and it costs a real capability: a client that
+ * renders a robot must know, from the asset list alone and before fetching
+ * anything, which bytes it has to pre-fetch. Every load in the browser goes
+ * through the SDK with the bearer token — there is no lazy second fetch a
+ * renderer can make on its own account — so "what must be in memory before
+ * anything renders" is a question the list has to be able to answer.
+ *
+ * A `texture` is an image referenced by the URDF's own `<material><texture>`
+ * **or** by a mesh file internally (a `.dae`'s `<init_from>`). Both are
+ * surfaces; neither is geometry; both must be resolvable by name.
+ */
+export declare const assetKind: z.ZodEnum<{
+    urdf: "urdf";
+    mesh: "mesh";
+    texture: "texture";
+    other: "other";
+}>;
+export type AssetKind = z.infer<typeof assetKind>;
+/**
+ * The `name` a URDF asset carries.
+ *
+ * A mesh names itself — its `package://` URI is the only string anyone can
+ * match against a workspace. A URDF has no such natural name, so producers
+ * agree on one: `robot_description`, after the topic it comes from.
+ *
+ * **Its job changed once the store stopped overwriting it.** It was pinned
+ * because the bridge and the cloud had settled on a value in conversation, and
+ * conversations drift — then the gate found the cloud renaming every URDF to
+ * `robot.urdf` regardless of what arrived, so the pinned value was decorative
+ * and the contract looked authoritative while being ignored. The store now
+ * keeps `asset.name` verbatim, which is what `asset.name`'s own comment
+ * already promised.
+ *
+ * So this is now a **convention among producers**, not an agreement the store
+ * enforces: it exists so two different bridges do not name the same thing two
+ * ways and leave a developer looking at an inconsistent fleet. Nothing
+ * validates it, and that is deliberate — the store's job is to record what it
+ * was told.
+ *
+ * Consumers must not match on it. `kind === 'urdf'` is the reliable test; the
+ * cloud identifies a robot's URDF row by kind alone, so a producer that sends
+ * a different string updates the same singleton rather than orphaning a second.
+ */
+export declare const URDF_ASSET_NAME = "robot_description";
+export declare const asset: z.ZodObject<{
+    id: z.ZodUUID;
+    robot_id: z.ZodUUID;
+    kind: z.ZodEnum<{
+        urdf: "urdf";
+        mesh: "mesh";
+        texture: "texture";
+        other: "other";
+    }>;
+    name: z.ZodString;
+    media_type: z.ZodString;
+    size_bytes: z.ZodNumber;
+    sha256: z.ZodString;
+    created_at: z.ZodISODateTime;
+}, z.core.$strip>;
+export type Asset = z.infer<typeof asset>;
+/**
+ * Whether a URDF can actually be rendered, which is not the same as whether it
+ * was uploaded.
+ *
+ * `missing` carries **the reference, verbatim, that no asset answers** — for
+ * a `package://` mesh the URI the bridge could not resolve in the workspace,
+ * and since W7's security fix also the absolute paths and bare relative paths
+ * a URDF may carry, which the extractor sees and the sync deliberately never
+ * offers. The sentence used to say "the `package://` URIs" and the field
+ * carried three kinds of string (Momus-W7); it is widened here rather than
+ * narrowed, because a developer whose URDF names `/opt/meshes/arm.stl` is
+ * entitled to be told that nothing will ever fetch it.
+ *
+ * The spec's example is "2 Meshes fehlen" and that number alone is a dead
+ * end: it tells a developer to go looking through a workspace by hand. The
+ * references are what they can act on, so the references travel.
+ *
+ * **Every entry must be actionable, and that is a constraint on the
+ * producers, not on this field (W7a).** An entry a developer cannot make
+ * disappear by fixing what it names is a defect in whoever put it there: for
+ * a whole wave `<texture>` references were listed here and no sync would ever
+ * offer them, so the honest instruction behind the list was "fix this, it
+ * will not help".
+ */
+export declare const urdfCompleteness: z.ZodObject<{
+    present: z.ZodBoolean;
+    mesh_count: z.ZodNumber;
+    missing: z.ZodArray<z.ZodObject<{
+        uri: z.ZodString;
+        element: z.ZodEnum<{
+            mesh: "mesh";
+            texture: "texture";
+        }>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type UrdfCompleteness = z.infer<typeof urdfCompleteness>;
+/**
+ * A sync is long-running and is therefore answered with something to watch,
+ * never with a status that was true at the moment of asking.
+ *
+ * **`source` has one value, and that is deliberate.** §4.6 also names a manual
+ * zip upload, and the first version of this shape had `'upload'` in the enum —
+ * with **no body defined for the bytes**. An enum value with no producer and
+ * no payload invites every consumer to guess a shape, and each guesses
+ * differently; that is a defect this project has deliberately refused to
+ * introduce before, when an error code was proposed whose payload had moved.
+ * The zip path stays a condition rather than sitting in the wire as a
+ * promise.
+ *
+ * A single-member enum rather than dropping the field: the second source is a
+ * question of when, not whether, and a caller that already names its source
+ * does not change shape when the second one arrives.
+ *
+ * Caught by Eve-W7 asking what body `'upload'` takes, rather than building
+ * against a guess.
+ */
+export declare const assetSyncRequest: z.ZodObject<{
+    source: z.ZodEnum<{
+        bridge: "bridge";
+    }>;
+}, z.core.$strict>;
+/**
+ * **And the route must read it (W7a).** Through W7 it did not: `{source:
+ * 'bridge'}`, `{source:'upload'}`, `{nonsense:1}` and `{}` all behaved
+ * identically, so the argument above — that a caller naming its source does
+ * not change shape when the second one arrives — was true of the document and
+ * false of the system. A shape with no consumer is not a contract; it is a
+ * comment with a type.
+ *
+ * The decision is to keep the shape and **validate it, `.strict()`**, rather
+ * than delete it. Deleting removes the record of why the enum has one member,
+ * and the zip path is a question of when. Validation is what makes the single
+ * member mean something: a caller who sends `'upload'` today learns that it
+ * does not exist yet, instead of silently getting a bridge sync.
+ */
+export type AssetSyncRequest = z.infer<typeof assetSyncRequest>;
+export declare const assetSyncResponse: z.ZodObject<{
+    sync_id: z.ZodUUID;
+}, z.core.$strip>;
+export type AssetSyncResponse = z.infer<typeof assetSyncResponse>;
+/**
+ * Progress of one sync.
+ *
+ * `failed` names the URIs that could not be resolved, and it is required
+ * rather than optional: a sync that drops three meshes and reports success is
+ * worse than one that fails outright, because the failure surfaces later, in a
+ * renderer, as a robot with missing limbs and no explanation.
+ *
+ * **`failed` carries per-reference facts and `reason` carries the sync's own,
+ * and that split is what M7 bought.** Three different kinds of string used to
+ * reach `failed`: unresolvable `package://` URIs (the documented meaning), the
+ * literal `robot_description` when a URDF *upload* failed, and English
+ * sentences written by the cloud — "the robot disconnected mid-sync". The
+ * console printed the array under *"these meshes could not be resolved"*, so a
+ * developer whose robot dropped was told to go find a mesh named *the robot
+ * disconnected mid-sync* (Momus-W7, M7).
+ *
+ * **Two of those three were defects and the third was not, which this
+ * paragraph used to get wrong** (Argus-W7a, W7a review, reading the file top to
+ * bottom). The cloud's English sentences do not belong here — that is what
+ * `reason` is for. But `robot_description` is a **legitimate** entry: the URDF
+ * is an asset that can fail to upload like any other, and W7a made that
+ * explicit rather than removing it — see `assetFailure.reference`, which says
+ * in as many words that not every entry is a mesh URI and a consumer must not
+ * assume one. Read together with the old sentence *"`failed` is URIs and
+ * nothing else"*, this file told a consumer the same value was both a defect
+ * and a documented case.
+ *
+ * So the rule is: **anything that is not about one specific reference goes in
+ * `reason`** — one human-readable sentence
+ * about why the sync ended as it did, `null` when the outcome speaks for
+ * itself. It also carries the distinction `bridgeAssetProgress.state` makes
+ * and this shape could not — a sync **refused** because another was in flight
+ * is not a sync that tried and failed.
+ *
+ * **`assetSyncState` was deliberately not widened to carry that.** Consumers
+ * switch on it, a new member silently changes what every existing switch
+ * covers, and "refused" is a *reason* for a terminal outcome rather than a
+ * different one. Adding a field is additive; adding an enum member is not.
+ */
+/**
+ * **Der Deckel, den beide Seiten kennen müssen (W9b).**
+ *
+ * Bis hierher hatte die Bridge eine eigene Zahl und die Cloud eine eigene, und
+ * die Registerzeile dazu nannte die der Bridge beim Namen: *„a guess … chosen
+ * as a starting number with no measurement behind it"* (DEF-127). Eine Grenze,
+ * die der Sender rät und der Empfänger durchsetzt, ist keine Grenze — sie ist
+ * zwei Zahlen, die zufällig übereinstimmen, bis eine von beiden sich ändert.
+ *
+ * Hier steht sie einmal. Die Bridge liest sie, **bevor** sie eine Datei in den
+ * Speicher liest; die Cloud setzt sie durch. Ohne das kann die Bridge gar nicht
+ * ablehnen, ohne 194 MB zu puffern — was am 2026-08-18 auf rx1 genau so passiert
+ * ist (DEF-148).
+ *
+ * **Sie gilt je Datei, nicht je Sync**, und das steht hier, weil DEF-127 es
+ * ausdrücklich verlangt hat: acht Meshes zu je 30 MiB passen durch, eine Datei
+ * zu 65 MiB nicht. Wer sie für eine Obergrenze der Übertragung hält, rechnet
+ * mit einer Schranke, die es nicht gibt — die Summe eines Syncs bindet das
+ * Speicherkontingent der Organisation, und das ist eine andere Zahl an einer
+ * anderen Stelle.
+ *
+ * **Die Zahl ist bewusst unverändert, und die Begründung hat zwei Fassungen
+ * gebraucht — die Korrektur ist hier mehr wert als das Ergebnis.**
+ *
+ * Zuerst stand hier: *„rx1s echte Meshes sind gemessen — `base.dae`
+ * 193.886.766 Bytes, also das 2,9-fache"*, im Präsens, als stünde das über
+ * der heute laufenden Beschreibung. Gemessen am 2026-08-19 gegen die
+ * **laufende** `robot_description`: acht `package://`-Referenzen, zusammen
+ * 89.379.096 Bytes, die größte `RX1.dae` mit 38.229.621 — **keine über dem
+ * Deckel.**
+ *
+ * Daraus habe ich dann geschlossen, `base.dae` werde *von keiner* rx1-URDF
+ * referenziert. **Auch das war falsch, und zwar weil ich nur den aktuellen
+ * Workspace geprüft hatte.** `src.old-20260730/rx1` und `.../rx1_linac`
+ * referenzieren beide `base.dae` **und** `base.stl` und kennen `RX1.dae`
+ * nicht — das ist die Beschreibung, die rx1 am 2026-08-18 lief, als DEF-148
+ * gemessen wurde. Die Beobachtung von damals war korrekt und ihre Erklärung
+ * auch.
+ *
+ * Was heute gilt: **welche Beschreibung rx1 fährt, entscheidet, ob der Deckel
+ * reicht** — die aktuelle passt mit Abstand hinein, die vorherige um das
+ * 2,9-fache nicht. Das ist keine Vertragsfrage, sondern eine über Speicher,
+ * Übertragungszeit und Kontingente, und sie liegt bei André. Sie blockiert
+ * nichts: W9bs Gate-Schritt 6 ist gegen die heute laufende Beschreibung
+ * erreichbar, ohne dass jemand eine Zahl anfasst.
+ */
+export declare const ASSET_UPLOAD_MAX_BYTES: number;
+export declare const assetTooLargeDetails: z.ZodObject<{
+    limit_bytes: z.ZodNumber;
+    size_bytes: z.ZodNumber;
+}, z.core.$strip>;
+export type AssetTooLargeDetails = z.infer<typeof assetTooLargeDetails>;
+/**
+ * Why one reference did not make it into the store.
+ *
+ * Three kinds because three things were already happening and only one word
+ * was available for them:
+ *
+ * - **`unresolvable`** — the reference names nothing the producer can find, or
+ *   nothing it is allowed to read (a `package://` URI absent from the
+ *   workspace, an absolute path, a `.dae`-internal reference escaping its own
+ *   package). **Permanent.** No retry changes it, and it is the only kind a
+ *   reconciliation may treat as gone.
+ * - **`upload_failed`** — the bytes exist and the transfer did not succeed.
+ *   **Transient.** The asset is still wanted; a later sync will carry it.
+ * - **`refused`** — never attempted, because a producer-side ceiling was hit
+ *   (R9: a `.dae` with more internal references than one file or one sync will
+ *   report). **Transient in the same sense**: nothing is known to be missing,
+ *   only unexamined.
+ *
+ * A consumer that cannot act on the distinction may still print `reference`
+ * alone and lose nothing it had before.
+ */
+export declare const assetFailureKind: z.ZodEnum<{
+    unresolvable: "unresolvable";
+    upload_failed: "upload_failed";
+    refused: "refused";
+    too_large: "too_large";
+}>;
+export type AssetFailureKind = z.infer<typeof assetFailureKind>;
+export declare const assetFailure: z.ZodObject<{
+    reference: z.ZodString;
+    kind: z.ZodEnum<{
+        unresolvable: "unresolvable";
+        upload_failed: "upload_failed";
+        refused: "refused";
+        too_large: "too_large";
+    }>;
+    details: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        limit_bytes: z.ZodNumber;
+        size_bytes: z.ZodNumber;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type AssetFailure = z.infer<typeof assetFailure>;
+export declare const assetSyncState: z.ZodEnum<{
+    failed: "failed";
+    running: "running";
+    succeeded: "succeeded";
+}>;
+export type AssetSyncState = z.infer<typeof assetSyncState>;
+export declare const assetSyncStatus: z.ZodObject<{
+    sync_id: z.ZodUUID;
+    robot_id: z.ZodUUID;
+    state: z.ZodEnum<{
+        failed: "failed";
+        running: "running";
+        succeeded: "succeeded";
+    }>;
+    done: z.ZodNumber;
+    total: z.ZodNumber;
+    failed: z.ZodArray<z.ZodObject<{
+        reference: z.ZodString;
+        kind: z.ZodEnum<{
+            unresolvable: "unresolvable";
+            upload_failed: "upload_failed";
+            refused: "refused";
+            too_large: "too_large";
+        }>;
+        details: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+            limit_bytes: z.ZodNumber;
+            size_bytes: z.ZodNumber;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>;
+    reason: z.ZodNullable<z.ZodString>;
+    started_at: z.ZodISODateTime;
+    updated_at: z.ZodISODateTime;
+}, z.core.$strip>;
+export type AssetSyncStatus = z.infer<typeof assetSyncStatus>;
+export declare const assetListResponse: z.ZodObject<{
+    assets: z.ZodArray<z.ZodObject<{
+        id: z.ZodUUID;
+        robot_id: z.ZodUUID;
+        kind: z.ZodEnum<{
+            urdf: "urdf";
+            mesh: "mesh";
+            texture: "texture";
+            other: "other";
+        }>;
+        name: z.ZodString;
+        media_type: z.ZodString;
+        size_bytes: z.ZodNumber;
+        sha256: z.ZodString;
+        created_at: z.ZodISODateTime;
+    }, z.core.$strip>>;
+    active_sync: z.ZodNullable<z.ZodObject<{
+        sync_id: z.ZodUUID;
+        robot_id: z.ZodUUID;
+        state: z.ZodEnum<{
+            failed: "failed";
+            running: "running";
+            succeeded: "succeeded";
+        }>;
+        done: z.ZodNumber;
+        total: z.ZodNumber;
+        failed: z.ZodArray<z.ZodObject<{
+            reference: z.ZodString;
+            kind: z.ZodEnum<{
+                unresolvable: "unresolvable";
+                upload_failed: "upload_failed";
+                refused: "refused";
+                too_large: "too_large";
+            }>;
+            details: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+                limit_bytes: z.ZodNumber;
+                size_bytes: z.ZodNumber;
+            }, z.core.$strip>>>;
+        }, z.core.$strip>>;
+        reason: z.ZodNullable<z.ZodString>;
+        started_at: z.ZodISODateTime;
+        updated_at: z.ZodISODateTime;
+    }, z.core.$strip>>;
+    urdf: z.ZodObject<{
+        present: z.ZodBoolean;
+        mesh_count: z.ZodNumber;
+        missing: z.ZodArray<z.ZodObject<{
+            uri: z.ZodString;
+            element: z.ZodEnum<{
+                mesh: "mesh";
+                texture: "texture";
+            }>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+    urdf_available: z.ZodNullable<z.ZodBoolean>;
+}, z.core.$strip>;
+export type AssetListResponse = z.infer<typeof assetListResponse>;
+/**
+ * The query of `GET /api/robots/:id/assets/missing`, the placeholder a
+ * rewritten URDF points at for a mesh Fleetless does not hold.
+ *
+ * **The route answers `404` either way** — this parameter changes the sentence,
+ * never the outcome. It is echoed back into the refusal message so a developer
+ * reading a failed mesh load learns *which* reference did not resolve; absent,
+ * the message says `unknown`. Echoing it discloses nothing, since it is what
+ * the caller itself sent.
+ */
+export declare const missingAssetQuery: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type MissingAssetQuery = z.infer<typeof missingAssetQuery>;
+/**
+ * What an `asset_too_large` refusal tells the caller — the same discipline as
+ * `publisher_busy` and `job_queue_full`: a refusal that names a state and no
+ * number leaves the caller unable to decide anything.
+ */
+/**
+ * Was eine `busy`-Absage beim Asset-Sync mitgeben muss (W9b, DEF-147).
+ *
+ * Vorher antwortete die Cloud *„Robot <id> already has a sync in progress"* —
+ * eine Absage, die einen **Zustand** benennt, aber nicht das **Ding** in diesem
+ * Zustand. Der laufende Sync ist serverseitig beobachtbar und über
+ * `GET .../assets/sync/<id>` abfragbar, nur erreichte ihn niemand mehr, der die
+ * id nicht aufgehoben hatte. Genau die Form, die W6b eine ganze Welle lang
+ * ausgeräumt hat: ein Abbruch ohne Job-Id, eine Freigabe ohne Session-Id.
+ *
+ * **Das allein genügt nicht**, und deshalb steht daneben `activeSync` auf der
+ * Asset-Liste: Diese Details helfen nur dem, der den Knopf noch einmal drückt.
+ * Wer die Seite neu lädt — der Fall, den André am 2026-08-18 hatte —, drückt
+ * gar nichts und braucht den laufenden Sync im ersten `GET`.
+ */
+export declare const assetSyncBusyDetails: z.ZodObject<{
+    sync_id: z.ZodUUID;
+    started_at_ms: z.ZodNumber;
+}, z.core.$strip>;
+export type AssetSyncBusyDetails = z.infer<typeof assetSyncBusyDetails>;