@fleetless/contracts 1.0.0 → 1.0.3

package/dist/assets.d.ts

@@ -1,10 +1,11 @@
+// SPDX-License-Identifier: Apache-2.0
 import { z } from 'zod';
 /**
- * The asset store (spec §4.6, W7).
+ * The asset store.
  *
  * 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).
+ * read is authenticated and checked against the `assets` role.
  *
  * **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
@@ -12,7 +13,7 @@ import { z } from 'zod';
  * 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
+ * Fleetless has no end-user interface of its own, 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
@@ -25,10 +26,9 @@ import { z } from 'zod';
  *
  * ---
  *
- * **`texture` is its own member of `assetKind` and not `other` (W7a, D2).**
+ * **`texture` is its own member of `assetKind` and not `other`.**
  *
- * 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
+ * Filing textures under `other` 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
@@ -94,23 +94,18 @@ export type Asset = z.infer<typeof asset>;
  *
  * `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".
+ * and also the absolute paths and bare relative paths a URDF may carry, which
+ * the extractor sees and the sync deliberately never offers. A developer whose
+ * URDF names `/opt/meshes/arm.stl` is entitled to be told that nothing will
+ * ever fetch it.
+ *
+ * A bare count of what is missing 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.** An entry a developer cannot make disappear by fixing
+ * what it names is a defect in whoever put it there.
  */
 export declare const urdfCompleteness: z.ZodObject<{
     present: z.ZodBoolean;
@@ -128,21 +123,14 @@ 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.
+ * **`source` has one value, and that is deliberate.** A manual upload path is
+ * planned but has no body defined for the bytes yet. An enum value with no
+ * producer and no payload invites every consumer to guess a shape, and each
+ * guesses differently, so it stays out of the wire until it is real.
  *
- * A single-member enum rather than dropping the field: the second source is a
+ * A single-member enum rather than no field at all: 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<{
@@ -150,18 +138,11 @@ export declare const assetSyncRequest: z.ZodObject<{
     }>;
 }, 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.
+ * **And the route reads it.** The body is `.strict()`, so `{source:'upload'}`
+ * and `{nonsense:1}` are refusals rather than silent bridge syncs. A shape no
+ * route validates is not a contract; it is a comment with a type. Validation
+ * is what makes the single member mean something: a caller who names a source
+ * that does not exist yet learns that, instead of getting a different one.
  */
 export type AssetSyncRequest = z.infer<typeof assetSyncRequest>;
 export declare const assetSyncResponse: z.ZodObject<{
@@ -176,83 +157,43 @@ export type AssetSyncResponse = z.infer<typeof assetSyncResponse>;
  * 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.
+ * **`failed` carries per-reference facts and `reason` carries the sync's
+ * own.** 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. A whole-sync condition written into `failed`
+ * reaches a developer as a mesh they are told to go and find.
+ *
+ * Not every `failed` entry is a mesh URI. A URDF upload can fail like any
+ * other asset, and it appears under the name `robot_description`; see
+ * `assetFailure.reference`. A consumer must not assume every entry is a
+ * `package://` URI.
+ *
+ * **`assetSyncState` is deliberately not widened to carry the reason.**
+ * Consumers switch on it, and a new member silently changes what every
+ * existing switch covers. A sync refused because another was in flight is
+ * still a terminal outcome with a reason, not a different state. 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.
+ * **The upload ceiling both sides read.**
  *
- * **Die Zahl ist bewusst unverändert, und die Begründung hat zwei Fassungen
- * gebraucht — die Korrektur ist hier mehr wert als das Ergebnis.**
+ * It is stated once, here, rather than once in the producer and once in the
+ * cloud. A limit the sender guesses and the receiver enforces is not a limit;
+ * it is two numbers that agree until one of them changes.
  *
- * 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.**
+ * The bridge reads it **before** it reads a file into memory, and the cloud
+ * enforces it. Without a shared number a producer cannot refuse an oversized
+ * mesh without first buffering the whole of it.
  *
- * 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.
+ * **It applies per file, not per sync.** Eight meshes of 30 MiB each pass; one
+ * file of 65 MiB does not. Reading it as a ceiling on a whole transfer means
+ * planning against a bound that does not exist — the total of a sync counts
+ * against the organisation's storage quota, which is a different number in a
+ * different place.
  *
- * 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.
+ * A robot whose meshes exceed this is not a contract question but a question
+ * about storage, transfer time and quota, and it is answered by raising the
+ * number here, in one place, for both sides.
  */
 export declare const ASSET_UPLOAD_MAX_BYTES: number;
 export declare const assetTooLargeDetails: z.ZodObject<{
@@ -274,9 +215,9 @@ export type AssetTooLargeDetails = z.infer<typeof assetTooLargeDetails>;
  * - **`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.
+ *   (for example a `.dae` carrying 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.
@@ -413,19 +354,16 @@ export type MissingAssetQuery = z.infer<typeof missingAssetQuery>;
  * number leaves the caller unable to decide anything.
  */
 /**
- * Was eine `busy`-Absage beim Asset-Sync mitgeben muss (W9b, DEF-147).
+ * What a `busy` refusal on an asset sync has to carry.
  *
- * 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.
+ * A refusal that names a **state** — "a sync is already in progress" — and not
+ * the **thing** in that state leaves the caller with nothing to look at. The
+ * running sync is observable under `GET .../assets/sync/<id>`, but only to
+ * someone who kept its 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`.
+ * These details serve the caller that presses the button again. A client that
+ * reloads instead presses nothing, which is why `active_sync` sits on the
+ * asset list as well.
  */
 export declare const assetSyncBusyDetails: z.ZodObject<{
     sync_id: z.ZodUUID;