@fleetless/contracts 1.0.0 → 1.0.3

package/dist/assets.js

@@ -1,11 +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
@@ -13,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
@@ -26,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
@@ -79,7 +78,7 @@ export const asset = z.object({
      * against their own workspace, and matching is the whole job when a sync
      * comes back incomplete.
      *
-     * **The naming rule for a file nothing in the URDF names (W7a, D2).** A
+     * **The naming rule for a file nothing in the URDF names.** A
      * `.dae` carries its own image references — `<init_from>textures/skin.png`
      * — resolved by the renderer against *the `.dae`'s own directory*, and no
      * `package://` URI for them appears anywhere in the URDF. The rule is:
@@ -87,12 +86,11 @@ export const asset = z.object({
      *     name = the .dae's package:// URI, directory part,
      *            joined with the internal reference, normalized.
      *
-     * So `package://rx1_description/meshes/arm.dae` referencing
+     * So `package://robot_description/meshes/arm.dae` referencing
      * `textures/skin.png` uploads as
-     * `package://rx1_description/meshes/textures/skin.png`.
+     * `package://robot_description/meshes/textures/skin.png`.
      *
-     * **This is the design's single point of failure and it is stated before
-     * anything is built against it.** three.js resolves that internal reference
+     * **Renderers depend on this rule holding.** three.js resolves that internal reference
      * relative to wherever it loaded the `.dae` from and asks the loading
      * manager for the result; the client can only answer if the asset's name
      * still carries the same **relative tail** (`textures/skin.png`) that the
@@ -103,9 +101,8 @@ export const asset = z.object({
      *
      * A reference that escapes its package (`../../etc/passwd`) is **not**
      * renamed into something harmless — it is refused at the producer, by the
-     * same containment check W7's K2 fix applied to `package://` resolution.
-     * Two identical rules, one of which is enforced and one of which is
-     * documented, is how W7's traversal happened in the first place.
+     * same containment check that guards `package://` resolution. Two identical
+     * rules, one enforced and one only documented, is how a traversal gets in.
      */
     name: z.string().min(1).max(500).meta({
         description: 'What the robot called it — for a mesh, the `package://` URI the URDF references, verbatim, which is the only string a developer can match against their own workspace. A file the URDF never names (an image a `.dae` loads for itself) is named by joining the mesh\'s own directory with that internal reference.',
@@ -137,23 +134,18 @@ export const asset = z.object({
  *
  * `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 const urdfCompleteness = z.object({
     present: z.boolean().meta({
@@ -163,18 +155,17 @@ export const urdfCompleteness = z.object({
         description: 'How many distinct meshes the URDF references.',
     }),
     /**
-     * **Was fehlt, und wovon (W9b, DEF-081).**
+     * **What is missing, and what kind of thing it was.**
      *
-     * Vorher ein blankes `string[]`. Die Console meldete daraufhin *„N meshes
-     * missing from the workspace"* — auch für eine fehlende **Textur**, während
-     * `mesh_count` daneben eine andere Zahl nannte: zwei Angaben über denselben
-     * Gegenstand, die einander widersprechen.
+     * Each entry carries its element rather than only its URI. Without that a
+     * client can only report every entry as a missing mesh, which contradicts
+     * `mesh_count` printed beside it — two statements about the same subject
+     * that disagree.
      *
-     * Die Cloud wusste es die ganze Zeit: `extractReferencesByElement` markiert
-     * jede Referenz mit ihrem Element und `buildAssetListResponse` warf die
-     * Markierung wieder weg. **Die Antwort im Client zu raten wäre genau die
-     * „neue Kopie", die die Registerzeile ausdrücklich ablehnt** — eine zweite
-     * Herleitung derselben Tatsache, die von der ersten abweichen kann.
+     * The producer knows the element when it extracts the reference, so it
+     * travels with it. A client that re-derived it from the file extension
+     * would be a second derivation of the same fact, free to diverge from the
+     * first.
      */
     missing: z.array(z.object({
         uri: z.string().min(1).max(500).meta({
@@ -191,21 +182,14 @@ export const urdfCompleteness = z.object({
  * 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 const assetSyncRequest = z.object({
     source: z.enum(['bridge']).meta({
@@ -225,83 +209,43 @@ export const assetSyncResponse = z.object({
  * 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).**
+ * **The upload ceiling both sides read.**
  *
- * 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.
+ * 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.
  *
- * 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).
+ * 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.
  *
- * **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.
+ * **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.
  *
- * **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.
+ * 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 const ASSET_UPLOAD_MAX_BYTES = 64 * 1024 * 1024;
 export const assetTooLargeDetails = z.object({
@@ -326,9 +270,9 @@ export const assetTooLargeDetails = z.object({
  * - **`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.
@@ -349,31 +293,28 @@ export const assetFailure = z.object({
         description: 'Why it failed. `unresolvable` means the reference names nothing the producer can find or may read, and is **permanent** — the only kind reconciliation may treat as gone. `upload_failed` means the bytes exist and the transfer did not succeed, `refused` means it was never attempted because a producer-side ceiling was hit, and `too_large` means it exceeds the upload limit and carries both numbers in `details`.',
     }),
     /**
-     * **Die zwei Zahlen, und warum `too_large` eine eigene Art ist (W9b).**
+     * **The two numbers, and why `too_large` is a kind of its own.**
      *
-     * `refused` bedeutet *„nie versucht, weil eine Decke des Erzeugers erreicht
-     * wurde"* — das passt auf eine Datei, die wegen ihrer Größe gar nicht erst
-     * gelesen wurde, **und ebenso auf die Sammel-Sentinel**, mit der ein Sync
-     * aufhört, einzelne Fehler zu benennen. Beides unter eine Art zu legen wäre
-     * derselbe Fehler, den W9a eine Welle zuvor ausgeräumt hat: zwei Fakten auf
-     * einem Schlüssel, von denen jeder den anderen überschreibt.
+     * `refused` means *never attempted, because a producer-side ceiling was
+     * hit*. That fits a file skipped for its size **and** the single collective
+     * entry a sync emits when it stops naming individual failures. Filing both
+     * under one kind puts two facts on one key, each overwriting the other.
      *
-     * Und ein Grund ohne Zahlen ist kein Grund, mit dem jemand etwas anfangen
-     * kann. *„Zu groß"* beantwortet nicht, ob das Mesh zu verkleinern ist oder
-     * die Grenze zu heben — `limit_bytes` und `size_bytes` tun es.
+     * A reason without numbers is not one a caller can act on. *"Too large"*
+     * does not answer whether to shrink the mesh or raise the limit;
+     * `limit_bytes` and `size_bytes` do.
      *
-     * Abwesend für jede andere Art — ein erzwungenes `details: null` auf jedem
-     * `unresolvable` kauft nichts. Die Paarung ist unten **erzwungen**, nicht
-     * beschrieben: ein Feld, dessen Regel nur im Kommentar steht, ist eine
-     * Bitte.
+     * Absent for every other kind — a forced `details: null` on every
+     * `unresolvable` buys nothing. The pairing is **enforced** below, not merely
+     * described: a field whose rule lives only in a comment is a request.
      */
     details: assetTooLargeDetails.nullish().meta({
         description: 'The two numbers behind a `too_large` failure, and absent for every other kind — a forced `null` on every `unresolvable` entry buys nothing. The pairing is enforced, not merely described.',
     }),
 }).superRefine((f, ctx) => {
-    // **Erzwungen, nicht beschrieben.** Eine Regel, die nur im Kommentar steht,
-    // ist eine Bitte — und dieses Projekt hat mehrfach erlebt, dass ein Feld,
-    // dessen Bedeutung nur daneben stand, mit etwas anderem gefüllt wurde.
+    // **Enforced, not merely described.** A rule that lives only in a comment is
+    // a request, and a field whose meaning sits beside it rather than in it gets
+    // filled with something else.
     if (f.kind === 'too_large' && f.details == null) {
         ctx.addIssue({ code: 'custom', path: ['details'], message: '`too_large` without limit_bytes/size_bytes says nothing a developer can act on' });
     }
@@ -395,48 +336,28 @@ export const assetSyncStatus = z.object({
         description: 'How many files this sync set out to transfer. It is `0` until the producer has finished working out what there is.',
     }),
     /**
-     * **Every entry says *why*, because reconciliation could not work without
-     * it and a developer could not read it without it** (W7a review, André's
-     * decision to fix rather than defer).
+     * **Every entry says *why*.**
      *
-     * It was a flat `string[]`, and **six producers wrote three different facts
-     * into it indistinguishably**: a reference that resolves to nothing in the
-     * workspace, a file that exists and whose transfer failed, and — since R9's
-     * ceiling — one that was never attempted at all. The cost was paid twice
-     * over. Reconciliation cannot tell *"no longer referenced"* from
-     * *"referenced and not delivered"*, so N14 had to decline reconciling **any**
-     * partial sync, leaving legitimately-removed assets stored and charged until
-     * the next clean one. And the console prints the whole array under *"these
-     * meshes could not be resolved"*, so a URDF upload failure — which arrives
-     * as the literal `robot_description` — is shown to a developer as a mesh
-     * they should go and find.
+     * A flat `string[]` cannot carry three different facts distinguishably: a
+     * reference that resolves to nothing in the workspace, a file that exists
+     * and whose transfer failed, and one that was never attempted at all.
      *
-     * `unresolvable` is the only kind reconciliation may drop: it is the only
-     * one that means *this will not come back*. `upload_failed` and `refused`
-     * both mean *we meant to provide this and did not*, which is the distinction
-     * the union needs and the field could not carry.
+     * The distinction is what makes reconciliation possible. `unresolvable` is
+     * the only kind that means *this will not come back*, so it is the only kind
+     * an unreferenced-asset sweep may act on. `upload_failed` and `refused` both
+     * mean *this was meant to be provided and was not*, and dropping the asset
+     * on either would delete something still wanted.
      *
-     * **Bounded, and the bound is a rule this file already wrote down one field
-     * over** (Kassandra-W7a, W7a review). `asset.name` is `max(500)`; the same
-     * names travelling here had no per-entry cap and no array cap at all.
+     * **Bounded, per entry and in total.** One mesh reference can expand into a
+     * list bounded only by the text of the `.dae` it points at, and the whole
+     * status travels in one WebSocket frame with a maximum payload. Without a
+     * cap the outcome is not a dropped frame but the robot's socket closed
+     * mid-sync by a file in its own workspace. At most 1000 entries of at most
+     * 500 bytes is about 0.5 MiB of names, comfortably inside that frame.
      *
-     * Why it matters became reachable in W7a. Before R6 an unresolvable
-     * reference was silently dropped, so this array could only grow with files
-     * that existed and failed to upload — bounded by the workspace. Once a
-     * `.dae`'s internal references are reported, **one mesh reference expands
-     * into a list bounded only by that file's own text.** Measured: a
-     * 2,120,745-byte `.dae` with 17,331 unresolvable `<init_from>` refs produces
-     * a terminal frame of 2,097,184 bytes — **32 bytes over
-     * `MAX_WS_PAYLOAD_BYTES`** — and `ws` enforces `maxPayload` before the frame
-     * is delivered, so the outcome is not a dropped frame but **the robot's
-     * socket closed, mid-sync, by a file in its own workspace.**
-     *
-     * A producer that hits its own ceiling reports **one** entry saying so
-     * rather than growing the list — the discipline gate step 5 already demands
-     * of the upload rate limit: *fail naming the limit, rather than silently
-     * reporting resolvable meshes as missing.*
-     *
-     * 1000 x 500 bytes is ~0.5 MiB of names, comfortably inside a 2 MiB frame.
+     * A producer that reaches its own ceiling reports **one** entry saying so
+     * rather than growing the list: fail naming the limit, rather than silently
+     * reporting resolvable meshes as missing.
      */
     failed: z.array(assetFailure).max(1000).meta({
         description: 'What could not be provided, one entry per reference, each saying why. Required rather than optional: a sync that quietly drops three meshes and reports success moves the failure into somebody\'s renderer, where it shows up as a robot with missing limbs and no cause. At most `1000` entries — a producer at its own ceiling reports one entry saying so rather than growing the list.',
@@ -456,14 +377,13 @@ export const assetListResponse = z.object({
         description: 'Every asset stored for this robot: the URDF, the meshes it references, and the textures those paint with.',
     }),
     /**
-     * Der gerade laufende Sync, oder `null` (W9b, DEF-147).
+     * The sync running right now, or `null`.
      *
-     * **Der Fall, für den das hier steht, ist der Neuladen-Fall.** Die Console
-     * hielt die `sync_id` nur im Speicher; ein Reload verlor die Fortschritts-
-     * anzeige, und der Zustand war serverseitig da, über
-     * `GET .../assets/sync/<id>` abfragbar — nur erreichte ihn niemand mehr, der
-     * die id nicht aufgehoben hatte. Eine Seite, die frisch lädt, drückt keinen
-     * Knopf; sie fragt diese Liste. Also muss die Liste es sagen.
+     * **This field exists for the reload case.** A client that holds the
+     * `sync_id` only in memory loses its progress display on a refresh, and the
+     * state is still there server-side under `GET .../assets/sync/<id>` —
+     * unreachable to anyone who did not keep the id. A page that loads fresh
+     * presses no button; it asks this list, so this list has to say.
      */
     active_sync: assetSyncStatus.nullable().meta({
         description: 'The sync running right now, or `null`. It is on this list so a page that reloads and has lost the sync id can still show progress — a freshly loaded page presses no button, it asks this list.',
@@ -473,30 +393,20 @@ export const assetListResponse = z.object({
     }),
     /**
      * What the connected bridge says it *could* transfer, which is deliberately
-     * separate from what has been transferred (§4.6: the bridge "meldet nur
-     * Verfügbarkeit"). `null` when no bridge is connected — distinct from
-     * `false`, because "no robot is online to ask" and "the robot has no URDF"
-     * send a developer to two different places.
-     *
-     * **All three states are reachable as of W7a (R7).** They were not: the bridge
-     * used to report availability from a subscription callback, which fires only
-     * when a publisher *sends* something, so it could notice presence and never
-     * absence — a robot that lost its URDF left the cloud holding the last thing
-     * it heard, forever, and `true` was sticky. The fix is an **active**
-     * `count_publishers` query on the bridge's own timer.
+     * separate from what has been transferred. `null` when no bridge is
+     * connected — distinct from `false`, because "no robot is online to ask" and
+     * "the robot has no URDF" send a developer to two different places.
      *
-     * **What a consumer still needs to know is the clock, not the gap.** An
-     * ungraceful loss — the publisher process killed rather than shut down — is
-     * noticed on **DDS's liveliness timeout**, not on the bridge's check
-     * interval. Measured against a real bridge: ~1.6 s when the publisher calls
-     * `destroy_node()`, **~19 s when it is `SIGKILL`ed**. So `true` can outlive
-     * the truth by some seconds after a crash, and no amount of polling on our
-     * side shortens it.
+     * The bridge answers by actively counting publishers on its own timer, so
+     * both the appearance and the disappearance of a robot description are
+     * noticed. A callback-driven answer can only see presence.
      *
-     * The sticky-`true` gap was found by Rosie-W7 checking her own work against
-     * the camera-health row of identical shape; the DDS clock was measured by
-     * Rosie-W7a closing it, and this comment was still describing the gap a wave
-     * after it was fixed (Momus-W7a, W7a review).
+     * **What a consumer needs to know is the clock.** An ungraceful loss — the
+     * publisher process killed rather than shut down — is noticed on DDS's
+     * liveliness timeout, not on the bridge's check interval. A clean
+     * `destroy_node()` is visible in a second or two; a killed process can take
+     * around twenty. So `true` can outlive the truth by some seconds after a
+     * crash, and no amount of polling shortens it.
      */
     urdf_available: z.boolean().nullable().meta({
         description: 'What the connected bridge says it *could* transfer, which is deliberately separate from what has been transferred. `null` when no bridge is connected — distinct from `false`, because "no robot is online to ask" and "the robot has no URDF" send a developer to two different places. After a publisher is killed rather than shut down this can read `true` for some seconds, on the underlying DDS liveliness timeout rather than on any check made here.',
@@ -525,22 +435,19 @@ export const missingAssetQuery = z
  * 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 const assetSyncBusyDetails = z.object({
     sync_id: z.uuid(),
-    /** Wann er begann — damit „läuft noch" von „hängt seit einer Stunde" unterscheidbar ist. */
+    /** When it started, so "still running" is distinguishable from "stuck for an hour". */
     started_at_ms: z.number().int().nonnegative(),
 });

package/dist/audit.d.ts

@@ -1,12 +1,13 @@
+// SPDX-License-Identifier: Apache-2.0
 import { z } from 'zod';
 /**
- * Audit (spec §16). Every state-changing interaction is recorded and **every
- * entry carries its actor — never anonymous** (§16.2). Reads are not audited.
+/**
+ * Audit. Every state-changing interaction is recorded and **every entry carries
+ * its actor — never anonymous**. Reads are not audited.
  *
- * W3 writes the events that exist once identities do: logins, failed logins,
- * end-user management, config publishes, bridge connect/disconnect. The view
- * with filters, CSV export and the 90-day retention window is W6 (André,
- * 2026-08-10) — same shape of work as the history API.
+ * What is written: logins, failed logins, user management, configuration
+ * publishes, bridge connect and disconnect. The log is filterable, exportable
+ * as CSV, and kept for ninety days.
  */
 /**
  * The kinds of actor the platform knows. `label` is what a human reads in the
@@ -14,7 +15,7 @@ import { z } from 'zod';
  * resolve four different id kinds to render a row.
  *
  * **`end_user` stays, and it stays for the rows already written.** The
- * two-space cut (2026-09-05, D1) replaced the org's one user pool with
+ * split into two identity spaces replaced the org's one user pool with
  * Fleetless users and per-app app users; every new row an app user writes
  * carries `app_user`. But an audit log is the one thing this platform must
  * never rewrite, and there are stored rows whose `kind` is `end_user`. Dropping
@@ -22,9 +23,8 @@ import { z } from 'zod';
  * cannot be read back is worse than one carrying a retired word.
  *
  * So this enum is deliberately **wider than what any producer emits**: nothing
- * writes `end_user` any more, and nothing may start again. That is the kind of
- * claim this repository has been wrong about before by leaving it unsaid, so it
- * is said here rather than inferred from a `grep` somebody runs in a year.
+ * writes `end_user` any more, and nothing may start again. That is said here
+ * rather than left to be inferred from a search somebody runs in a year.
  *
  * `developer` is a Fleetless user. It kept its name through both redesigns
  * because it was always right about what it named: the person who configures
@@ -107,7 +107,7 @@ export declare const auditListResponse: z.ZodObject<{
 }, z.core.$strip>;
 export type AuditListResponse = z.infer<typeof auditListResponse>;
 /**
- * **What a CSV export of this log looks like (DEF-123, spec §16.3).**
+ * **What a CSV export of this log looks like.**
  *
  * The column order lives here because otherwise the cloud and the console
  * would each carry their own, and nobody would notice them drifting apart
@@ -120,10 +120,9 @@ export type AuditListResponse = z.infer<typeof auditListResponse>;
  */
 export declare const AUDIT_CSV_COLUMNS: readonly ["seq", "at", "actor_kind", "actor_id", "action", "target_kind", "target_id", "target_label", "details"];
 /**
- * Spec §16.3: the audit log is kept for **90 days**.
+ * The audit log is kept for **90 days**.
  *
- * A constant here so the cloud does not derive it a second time — the same
- * reasoning as `ASSET_UPLOAD_MAX_BYTES`, and the same register row that found
- * there is no purge touching audit rows at all.
+ * A constant here so no consumer derives it a second time — the same reasoning
+ * as `ASSET_UPLOAD_MAX_BYTES`.
  */
 export declare const AUDIT_RETENTION_DAYS = 90;