@fleetless/contracts 1.0.0 → 1.0.2

package/dist/rest.d.ts

@@ -1,7 +1,8 @@
+// SPDX-License-Identifier: Apache-2.0
 import { z } from 'zod';
 /**
- * REST shapes of the robot resource (spec §11.1). W1 scope: create, list,
- * get, and the built-in `bridge_state` datapoint read.
+ * REST shapes of the robot resource: create, list, get, and the built-in
+ * `bridge_state` datapoint read.
  */
 export declare const robot: z.ZodObject<{
     id: z.ZodUUID;
@@ -23,8 +24,8 @@ export declare const createRobotRequest: z.ZodObject<{
 }, z.core.$strip>;
 export type CreateRobotRequest = z.infer<typeof createRobotRequest>;
 /**
- * The robot token binds one bridge to one robot (spec §5). It is returned
- * exactly once, here; the cloud stores only a hash of it.
+ * The robot token binds one bridge to one robot. It is returned exactly once,
+ * here; the cloud stores only a hash of it.
  */
 export declare const robotToken: z.ZodString;
 export declare const createRobotResponse: z.ZodObject<{
@@ -37,10 +38,10 @@ export declare const createRobotResponse: z.ZodObject<{
 }, z.core.$strip>;
 export type CreateRobotResponse = z.infer<typeof createRobotResponse>;
 /**
- * How many things a robot exposes, per kind (spec `2026-08-21-exposure-and-revoke-design` D1).
+ * How many things a robot exposes, per kind.
  *
- * **Five numbers, never a sum.** `robotDeletionSummary.slug_count` already made
- * this call and wrote down why: fold cameras in and the sentence "this deletes
+ * **Five numbers, never a sum.** `robotDeletionSummary.slug_count` makes the
+ * same call for the same reason: fold cameras in and the sentence "this deletes
  * N slugs and M cameras" counts them twice. A list row has the same problem.
  *
  * **Counted from the published configuration, and excluding the built-ins.**
@@ -105,7 +106,7 @@ export declare const robotListResponse: z.ZodObject<{
 export type RobotListResponse = z.infer<typeof robotListResponse>;
 /**
  * The REST read of one datapoint. For bridge-captured data `timestamp_ms`
- * is the capture time at the bridge (spec §6.3); for the cloud-observed
+ * is the capture time at the bridge; for the cloud-observed
  * built-in `bridge_state` it is the time the cloud observed the state.
  */
 export declare const datapointValue: z.ZodObject<{
@@ -117,7 +118,7 @@ export type DatapointValue = z.infer<typeof datapointValue>;
 /**
  * One robot in full: what the list shows, plus what only the detail view
  * needs — which bridge build is connected, why the last hello was refused,
- * and where the configuration stands (spec §15.2, tab 1).
+ * and where the configuration stands.
  */
 export declare const robotDetailResponse: z.ZodObject<{
     bridge_version: z.ZodNullable<z.ZodString>;
@@ -391,19 +392,16 @@ export type ConfigDraftResponse = z.infer<typeof configDraftResponse>;
  * the server parses it, and there is exactly one account of what the
  * configuration says.
  *
- * It also settles who owns parsing, and **FL-005 D2 moved that line**. The
- * sentence here used to read that the console refuses unparsable YAML before it
- * sends, so a syntax error never reaches the server. That is no longer the
- * rule: the **server** refuses text that is not valid YAML, with the line and
- * column, and stores everything else — including valid YAML that is not a
- * fleetless document, which comes back with `doc: null` and its issues. The
- * console checks as you type so the answer is immediate; the server checks
- * because it is the one that decides. Two checks of one question, and the
- * server's is the one that binds.
- *
- * The pair that used to be called a defect — a stored source that does not
- * parse to its stored document — is now a **represented state**: no document at
- * all. See `configDraftResponse` above.
+ * It also settles who owns parsing. The **server** refuses text that is not
+ * valid YAML, with the line and column, and stores everything else — including
+ * valid YAML that is not a fleetless document, which comes back with
+ * `doc: null` and its issues. An editor may check as you type so the answer is
+ * immediate; the server checks because it is the one that decides. Two checks
+ * of one question, and the server's is the one that binds.
+ *
+ * A stored source that does not parse to a document is therefore a
+ * **represented state**, not an error: no document at all. See
+ * `configDraftResponse` above.
  */
 export declare const putConfigDraftRequest: z.ZodObject<{
     source: z.ZodString;
@@ -683,11 +681,11 @@ export type FetchTypesResponse = z.infer<typeof fetchTypesResponse>;
 /**
  * What a client can read on this robot: the built-ins plus everything the
  * published configuration exposes. This is the seed of the generated
- * per-robot API (§11.2).
+ * per-robot API.
  *
- * **The OpenAPI rendering exists since the route manifest (`routes.ts`):
- * `artifacts/openapi.json`, derived from the manifest and these schemas by
- * `scripts/export-schemas.ts`.**
+ * **The OpenAPI rendering is `artifacts/openapi.json`**, derived from the
+ * route manifest in `routes.ts` and these schemas by
+ * `scripts/export-schemas.ts`.
  */
 export declare const datapointDescriptor: z.ZodObject<{
     slug: z.ZodString;
@@ -706,8 +704,8 @@ export declare const datapointListResponse: z.ZodObject<{
 }, z.core.$strip>;
 export type DatapointListResponse = z.infer<typeof datapointListResponse>;
 /**
- * The built-in `robot_details` datapoint (spec §4.3): static properties the
- * developer maintains. Bounded so one robot cannot become a document store.
+ * The built-in `robot_details` datapoint: static properties the developer
+ * maintains. Bounded so one robot cannot become a document store.
  */
 export declare const robotDetailsDoc: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodArray<z.ZodUnknown>, z.ZodRecord<z.ZodString, z.ZodUnknown>]>>;
 export type RobotDetailsDoc = z.infer<typeof robotDetailsDoc>;
@@ -721,7 +719,7 @@ export declare const putRobotDetailsRequest: z.ZodObject<{
 }, z.core.$strip>;
 export type PutRobotDetailsRequest = z.infer<typeof putRobotDetailsRequest>;
 /**
- * Invoke an action or call a service; parameters by field path (§4.4).
+ * Invoke an action or call a service; parameters by field path.
  *
  * Flat, keyed by `parameterSpec.name` — see `cloudInvoke.params` for why the
  * flat form is the one that makes a refusal legible.
@@ -732,55 +730,45 @@ export declare const invokeRequest: z.ZodObject<{
 }, z.core.$strip>;
 export type InvokeRequest = z.infer<typeof invokeRequest>;
 /**
- * The answer to an invoke. The job id is informative (§11.3): state is
- * observed by slug afterwards, over polling or a subscription.
+ * The answer to an invoke. The job id is informative: state is observed by
+ * slug afterwards, over polling or a subscription.
  */
 /**
- * The body of a cancel (W6b). **Every field optional, and the body itself may
- * be absent** — `POST .../cancel` was bodyless before this wave and every
- * existing caller still sends nothing.
- *
- * That is not politeness, it is the W5 defect: a bodyless `POST` carrying
- * `content-type: application/json` was rejected outright, which made
- * `cameras.live()` unreachable through the SDK and took `cancel`, publish,
- * restore, key rotation and member removal with it — unnoticed since W4. A
- * schema that demands a body would reintroduce it on the one verb that stops
- * a machine.
+ * The body of a cancel. **Every field optional, and the body itself may be
+ * absent** — `POST .../cancel` takes no body at all in its simplest form, and
+ * a schema that demanded one would break every caller on the one verb that
+ * stops a machine.
  *
  * **`.strict()`, and that is the whole point of the shape.** A plain object
  * strips unknown keys, so a caller who *means* to name a job and misspells the
  * field — `jobId` for `job_id` — has their id silently removed and gets the
  * **slug-wide** cancel instead: the most destructive reading of a request they
- * did not make. Measured in W6b's review: `{"jobId": "<some other job>"}`
- * answered `200` and stopped the job that was actually running, which nobody
- * had named. The `?force=true` precedent this route's design borrowed from
- * fails *safe* on a typo — a misspelled `force` simply does not force.
- * Stripping here fails unsafe, so unknown keys are refused instead.
+ * did not make. A `?force=true` flag fails *safe* on a typo, because a
+ * misspelled `force` simply does not force. Stripping here fails unsafe, so
+ * unknown keys are refused instead.
  *
  * `job_id` absent and `job_id: null` mean the **same** thing here, and that is
- * deliberate: over REST an absent body is how every caller written before this
- * wave says "cancel whatever is running". On the socket, `clientCancel.job_id`
- * is required-and-nullable instead, because a frame is assembled fresh by a
- * client that has already been updated — there, `null` is a decision and an
- * omission is a bug.
+ * deliberate: over REST an absent body is how a caller says "cancel whatever is
+ * running". On the socket, `clientCancel.job_id` is required-and-nullable
+ * instead, because a frame is assembled fresh by a client that knows this
+ * contract — there, `null` is a decision and an omission is a bug.
  */
 export declare const cancelRequest: z.ZodObject<{
     job_id: z.ZodOptional<z.ZodNullable<z.ZodUUID>>;
 }, z.core.$strict>;
 export type CancelRequest = z.infer<typeof cancelRequest>;
 /**
- * The query of a live release (W6b): `DELETE .../live?session_id=<uuid>`.
+ * The query of a live release: `DELETE .../live?session_id=<uuid>`.
  *
  * A query parameter rather than a body, following `?force=true` on robot
- * deletion — the precedent this repo already set for "a DELETE that needs one
- * more fact". A body on a DELETE is carried inconsistently by proxies and by
+ * deletion. A body on a DELETE is carried inconsistently by proxies and by
  * `fetch` itself, and this call runs from a browser tab that is often closing.
  *
  * **`.strict()`, for the reason `cancelRequest` is** — `?sessionid=` instead of
- * `?session_id=` was measured releasing **both** of an identity's holds and
- * stranding the other tab, which is precisely the defect this field was added
- * to remove. A refused typo costs a round trip; a stripped one stops a robot
- * somebody else is watching.
+ * `?session_id=` would release **every** one of an identity's holds and strand
+ * its other tabs, which is precisely what this field exists to prevent. A
+ * refused typo costs a round trip; a stripped one stops a robot somebody else
+ * is watching.
  *
  * Absent means today's meaning: release **all** of this identity's holds on
  * this camera. A client that has lost its id, or is going away entirely, still
@@ -882,14 +870,12 @@ export type PublishRequest = z.infer<typeof publishRequest>;
  * The **most recent** job on a slug — running or already finished — or null
  * only when nothing has ever run there.
  *
- * It said "the job currently running" until W4's review, and that quietly
- * made §11.3's first sentence false. The spec offers two equal ways to
- * observe a slug — *"Polling (REST) oder Subscription (Realtime)"* — but a
- * route that forgets a job the moment it settles lets a poller see only
- * `running`, then `null`. Succeeded, failed, cancelled, `lost` and
- * never-invoked all become the same answer, so §6.1's promise that a lost
- * job is *said out loud* held for subscribers and silently did not hold for
- * anyone polling. It is also the recovery `command_outcome_unknown` points
+ * A slug can be observed two equally valid ways, by polling this route or by
+ * subscribing. A route that forgot a job the moment it settled would let a
+ * poller see only `running`, then `null`: succeeded, failed, cancelled, `lost`
+ * and never-invoked would all become the same answer, and the promise that a
+ * lost job is said out loud would hold for subscribers and silently not hold
+ * for anyone polling. It is also the recovery `command_outcome_unknown` points
  * a caller to.
  *
  * Read `job.state` to tell a live job from a finished one; that is what the
@@ -921,20 +907,18 @@ export declare const jobResponse: z.ZodObject<{
 export type JobResponse = z.infer<typeof jobResponse>;
 /**
  * Every job the platform currently believes this robot has — `GET
- * /api/robots/:id/jobs` (W6b).
+ * /api/robots/:id/jobs`.
  *
  * `jobResponse` answers "what is on this slug", which requires knowing the
- * slug first. That was enough while a job could only exist on a slug the
- * published configuration named. W6b breaks that assumption twice: a
- * reconnecting bridge can name a job the cloud has **no row for** and the
- * cloud adopts it, and a configuration change can leave a job on a slug the
- * document no longer contains. Both are jobs nobody can ask about, because
- * asking requires already knowing what to ask for.
- *
- * So this route exists to answer the question the per-slug route cannot: not
- * "is something running here", but "what is this robot doing". A restarted
- * cloud that has just reconciled a robot's `hello.active_jobs` has exactly
- * this list and, until now, no way to say it out loud.
+ * slug first. Two kinds of job break that assumption: a reconnecting bridge
+ * can name a job the cloud has **no row for**, and the cloud adopts it; and a
+ * configuration change can leave a job on a slug the document no longer
+ * contains. Both are jobs nobody can ask about, because asking requires
+ * already knowing what to ask for.
+ *
+ * So this route answers the question the per-slug route cannot: not "is
+ * something running here", but "what is this robot doing". A cloud that has
+ * just reconciled a robot's `hello.active_jobs` has exactly this list.
  *
  * The array is ordered newest first and is **never null**: a robot doing
  * nothing answers `{ jobs: [] }`. "Nothing is running" and "we did not look"
@@ -942,14 +926,11 @@ export type JobResponse = z.infer<typeof jobResponse>;
  * distinction `robotDeletionSummary` was made all-required for.
  *
  * **At most one entry per slug: the current job there, exactly what
- * `jobResponse` would answer for that slug.** This is not a history endpoint
- * and must not become one. The first implementation returned every job the
- * registry still held — six rows and four complete Fibonacci results after a
- * few minutes of gate traffic, and unbounded in both count and payload for a
- * robot that has been working all day. The list would have grown until a
- * console page carried a robot's entire past, and the one thing it exists to
- * answer — *what is this robot doing* — would have been the first line of a
- * scroll.
+ * `jobResponse` would answer for that slug.** This is not a history endpoint.
+ * Returning every job a registry still holds is unbounded in both count and
+ * payload for a robot that has been working all day, and the one thing this
+ * route exists to answer — *what is this robot doing* — would be the first
+ * line of a scroll. The durable history has its own routes.
  *
  * A settled job stays visible as its slug's current entry until something
  * else runs there, which is what makes a job that just failed still findable.
@@ -957,7 +938,7 @@ export type JobResponse = z.infer<typeof jobResponse>;
  * `jobResponse`.
  */
 /**
- * What a `rate_limited` refusal tells the caller (W6c).
+ * What a `rate_limited` refusal tells the caller.
  *
  * One number, and it is the only one that matters: **when to come back.** A
  * limit that says "too many" without saying "in 800 ms" produces a client that
@@ -974,11 +955,10 @@ export declare const rateLimitDetails: z.ZodObject<{
 export type RateLimitDetails = z.infer<typeof rateLimitDetails>;
 /**
  * Every job this robot's registry currently holds, **ordered newest first by
- * `started_at`, with `seq` as the tiebreaker** (W7, register rows 2j and 2l).
+ * `started_at`, with `seq` as the tiebreaker**.
  *
- * The field is named because the previous version of this comment claimed an
- * order without saying what produced it, and the answer turned out to matter
- * twice over:
+ * The tiebreaker is named rather than left implicit, because it matters twice
+ * over:
  *
  * 1. **`started_at` alone is not a total order.** Two jobs minted in the same
  *    millisecond sorted against each other arbitrarily — differently on each
@@ -1021,9 +1001,9 @@ export type RobotJobsResponse = z.infer<typeof robotJobsResponse>;
 /**
  * Every slug of a robot that a role can be granted, **with its kind**.
  *
- * The roles matrix was built in W3 against the datapoint list, which was the
- * only kind that existed. With four kinds it needs one list that names them,
- * or the matrix silently cannot grant an action.
+ * A roles matrix built against the datapoint list alone cannot grant an
+ * action, a service or a publisher. One list that names every kind, with its
+ * kind, is what a matrix needs.
  */
 export declare const exposure: z.ZodObject<{
     slug: z.ZodString;
@@ -1072,36 +1052,27 @@ export declare const SNAPSHOT_HEADERS: {
     readonly height: "x-fleetless-height";
 };
 /**
- * The metadata an asset upload carries beside its raw body (W7).
+ * The metadata an asset upload carries beside its raw body.
  *
- * Here rather than as a convention documented on both sides, and the reason is
- * a scar. W5 shipped `x-fleetless-*` headers the CORS policy did not expose,
- * so `age_ms` was `null` in **every** browser while the SDK documented `null`
- * as "nothing captured yet" — a fresh frame reporting as no snapshot at all,
- * invisible to three test suites because none of them was a browser. And W6b
- * found the general form: three repos agreeing with each other about a payload
- * none of them exchanged, each right in its own tests.
- *
- * **A string shared by two repos and defined in both is a string that drifts.**
- * A zod schema cannot validate a header, which is an argument for writing the
- * names down once, not an argument for writing them down twice.
+ * Written here rather than left as a convention each side documents for
+ * itself. **A string shared by two implementations and defined in both is a
+ * string that drifts**, and a header is the easiest place for that to happen
+ * unnoticed: a zod schema cannot validate one, which is an argument for
+ * writing the names down once, not an argument for writing them down twice.
  *
  * `name` is the `package://` URI verbatim for a mesh — the same string
  * `asset.name` stores, and the same one `urdfCompleteness.missing` reports, so
  * a failed upload and a missing mesh can be matched by eye.
  */
 /**
- * **`name` travels percent-encoded, and that is a fix rather than a
- * convention** (W7a review, André's decision to fix rather than defer).
- *
- * HTTP header values are latin-1 (`http.client` in Python, and the same is
- * true on the other side). So a texture called `textures/日本語.png` raised a
- * `UnicodeEncodeError` **inside `urllib`** — a `ValueError`, caught by neither
- * `HTTPError` nor `URLError` — which propagated to the sync's broad handler
- * and marked **everything still remaining** as failed. One non-ASCII filename
- * cost a developer every mesh after it in that sync, with no cause on the
- * wire. R6 made it ordinary rather than exotic: `.dae` internal names come
- * from 3D-authoring tools, where non-ASCII is Tuesday.
+ * **`name` travels percent-encoded in a second header.**
+ *
+ * HTTP header values are latin-1. A texture called `textures/日本語.png` cannot
+ * be put in one at all: in Python it raises a `UnicodeEncodeError` inside
+ * `urllib` — a `ValueError`, caught by neither `HTTPError` nor `URLError` — so
+ * a single non-ASCII filename can fail an entire sync with no cause on the
+ * wire. Non-ASCII names are ordinary rather than exotic, because `.dae`
+ * internal names come from 3D-authoring tools.
  *
  * The encoding is not invented here. **`GET .../assets/missing?name=` already
  * carries this exact string percent-encoded**, because a query parameter is
@@ -1109,21 +1080,19 @@ export declare const SNAPSHOT_HEADERS: {
  * answered.
  *
  * **It is a SECOND header, and that is the whole design rather than a
- * detail.** The first version overloaded `name` itself: the producer would
- * encode, the store would `decodeURIComponent`. That decodes identically for
- * every name without a `%`, so an **older bridge and a newer cloud agree by
- * luck** — right up until a name contains `%2f`, which the store would then
- * silently turn into a `/`. A wire change whose breakage is invisible in the
- * common case and silent in the uncommon one is the worst of both (Argus-W7a,
- * reading the contract rather than the code).
+ * detail.** Overloading `name` itself — the producer encodes, the store
+ * decodes — decodes identically for every name without a `%`, so an older
+ * producer and a newer store agree by luck right up until a name contains
+ * `%2f`, which the store would then silently turn into a `/`. A wire change
+ * whose breakage is invisible in the common case and silent in the uncommon
+ * one is the worst of both.
  *
  * So `name` keeps meaning exactly what it always meant, and `nameEncoded`
  * carries the percent-encoded UTF-8 form. **The store prefers `nameEncoded`
  * when present and uses `name` otherwise**, so:
  *
- * - an older bridge sends only `name` and behaves exactly as before;
- * - a newer bridge sends both, and a name it cannot express in latin-1 travels
- *   intact for the first time;
+ * - a producer that sends only `name` behaves exactly as it always did;
+ * - a producer that sends both can carry a name latin-1 cannot express;
  * - no value is ever ambiguous about which encoding it is in.
  *
  * A producer that can send `nameEncoded` should send both, so a store older
@@ -1136,23 +1105,22 @@ export declare const ASSET_UPLOAD_HEADERS: {
     readonly nameEncoded: "x-fleetless-asset-name-encoded";
     readonly syncId: "x-fleetless-sync-id";
     /**
-     * **Die angekündigte Größe, und sie ist der Grund, warum `asset_too_large`
-     * überhaupt entstehen kann (W9b, DEF-116).**
+     * **The announced size, and it is what makes `asset_too_large` reachable at
+     * all.**
      *
-     * Fastifys `bodyLimit` greift im Content-Type-Parser, also **vor** dem
-     * Handler — eine zu große Datei bekam damit ein blankes `413 bad_request`
-     * ohne `limit_bytes` und ohne `size_bytes`, und der strukturierte Fehlercode,
-     * den `assetTooLargeDetails` beschreibt, hatte schlicht keinen erreichbaren
-     * Erzeuger (Momus-W7, M1, an den echten Routenoptionen reproduziert).
+     * A server-side body limit is applied by the content-type parser, before the
+     * handler runs, so an oversized upload can only be refused with a bare
+     * `413` carrying neither `limit_bytes` nor `size_bytes` — and the structured
+     * refusal `assetTooLargeDetails` describes would have no producer.
      *
-     * Mit einer angekündigten Größe im Kopf kann die Ablehnung dort entstehen,
-     * wo sie etwas sagen kann: bevor ein Byte gepuffert ist, mit beiden Zahlen.
-     * Und die Bridge erfährt ihre Grenze, ohne 194 MB zu lesen, um sie zu
-     * entdecken — was am 2026-08-18 auf rx1 genau so ausging (DEF-148).
+     * With the size announced in a header the refusal can be made where it can
+     * say something: before a byte is buffered, with both numbers. It also lets
+     * a producer discover its own limit without first reading the whole file
+     * into memory.
      *
-     * Der Kopf ist eine **Ankündigung, kein Beweis**: Ein Absender kann lügen.
-     * Der Deckel gilt weiterhin auch am Körper — dies ersetzt die Durchsetzung
-     * nicht, es macht die Absage nur beantwortbar.
+     * The header is an **announcement, not a proof**: a sender can lie. The
+     * ceiling still applies to the body — this does not replace enforcement, it
+     * only makes the refusal answerable.
      */
     readonly size: "x-fleetless-asset-size";
 };
@@ -1178,7 +1146,7 @@ export type CameraListResponse = z.infer<typeof cameraListResponse>;
  * What a viewer needs to join, and **what it costs them to hold**.
  *
  * `POST` takes a refcount hold and `DELETE` releases it; the first hold
- * starts the robot publishing and the last release stops it (§10). A client
+ * starts the robot publishing and the last release stops it. A client
  * that forgets to release keeps a robot streaming to nobody, so the SDK hands
  * back a `release()` rather than a bare token.
  *
@@ -1210,8 +1178,8 @@ export type LiveSessionResponse = z.infer<typeof liveSessionResponse>;
  * which polls continuously while a tab is open.
  *
  * `age_ms` is not a convenience: a cached frame served without its age is
- * indistinguishable from a live one, and §10 makes snapshots deliberately
- * cheap and therefore deliberately old. `null` values mean nothing has been
+ * indistinguishable from a live one, and snapshots are deliberately cheap and
+ * therefore deliberately old. `null` values mean nothing has been
  * captured yet — which is an answer, not an error.
  */
 export declare const snapshotMetaResponse: z.ZodObject<{
@@ -1224,28 +1192,23 @@ export declare const snapshotMetaResponse: z.ZodObject<{
 }, z.core.$strip>;
 export type SnapshotMetaResponse = z.infer<typeof snapshotMetaResponse>;
 /**
- * **Both history shapes answer the same boundary the same way: `[from, to)`
- * (W9d, DEF-062 — decision pre-made at the W6 boundary so no wave
- * re-litigates it).**
- *
- * They did not. `samples` was inclusive of `to`, `buckets` exclusive — same
- * range, same data, opposite answers for a point landing exactly on `to`, and
- * the buckets answer rendered as a gap tooltipped *"empty — no samples"*.
- * `sdk/README.md` documented the inclusive notation for the half-open path,
- * so it was wrong for one of the two whichever way you read it.
- *
- * Half-open wins because it is the only rule under which **adjacent windows
- * tile without overlap**: `[0,10)` then `[10,20)` covers every instant once.
- * With an inclusive upper bound a sample at exactly `10` belongs to both
- * windows, and any consumer summing them counts it twice.
- *
- * This is a statement about behaviour, not a field — nothing in the shapes
- * below can enforce it. It is written here because this is the one place both
- * shapes are defined together, and the cloud's `history-store` and the SDK's
- * README are the two places that have to agree with it.
+ * **Both history shapes answer the same boundary the same way: `[from, to)`.**
+ *
+ * Half-open, because it is the only rule under which **adjacent windows tile
+ * without overlap**: `[0,10)` then `[10,20)` covers every instant once. With an
+ * inclusive upper bound a sample at exactly `10` belongs to both windows, and
+ * any consumer summing them counts it twice.
+ *
+ * Two shapes that answered it differently would give opposite results for a
+ * point landing exactly on `to` — same range, same data — and the difference
+ * renders as a gap in one of the two.
+ *
+ * This is a statement about behaviour, not a field: nothing in the shapes below
+ * can enforce it. It is written here because this is the one place both shapes
+ * are defined together.
  */
 /**
- * A history query (§8). `from`/`to` accept **either** a relative expression
+ * A history query. `from`/`to` accept **either** a relative expression
  * (`now-30s`, `now-5m`, `now-1h`) **or** absolute unix milliseconds, because
  * a chart asks the first way and a report asks the second, and making a
  * client convert is making it guess our clock.
@@ -1268,7 +1231,7 @@ export declare const historyQuery: z.ZodObject<{
 }, z.core.$strip>;
 export type HistoryQuery = z.infer<typeof historyQuery>;
 /**
- * Raw samples. `timestamp_ms` is the **bridge's capture time** (§6.3) — the
+ * Raw samples. `timestamp_ms` is the **bridge's capture time** — the
  * same instant the live value carried, so a recorded point and a live one can
  * be placed on one axis without apology.
  *
@@ -1296,9 +1259,8 @@ export type HistorySamplesResponse = z.infer<typeof historySamplesResponse>;
  * inspection.
  *
  * `sample_count` exists because an empty bucket and a bucket whose average is
- * zero are different facts. W5 established at some cost what happens when two
- * facts share one representation, and a chart is the easiest place in this
- * product to draw a gap as a line.
+ * zero are different facts. When two facts share one representation, a chart
+ * is the easiest place to draw a gap as a line.
  */
 export declare const historyBucketsResponse: z.ZodObject<{
     slug: z.ZodString;
@@ -1365,7 +1327,7 @@ export declare const historyResponse: z.ZodUnion<readonly [z.ZodObject<{
 }, z.core.$strip>]>;
 export type HistoryResponse = z.infer<typeof historyResponse>;
 /**
- * W6a — deletion, and the one channel that reports health.
+ * Deletion, and the one channel that reports health.
  *
  * | Route | Body | Answer |
  * |---|---|---|
@@ -1391,24 +1353,17 @@ export type HistoryResponse = z.infer<typeof historyResponse>;
  * takes an optional `robot_id` filter rather than living at a per-robot
  * path.
  *
- * The first version of this table said the opposite, with a justification
- * that sounded right and was incomplete: it reasoned only from a page that
- * has just opened one robot. But the console shows health on the **robot
- * list** too, and a per-robot path makes that N requests to render one
- * screen — while the event that must keep it fresh arrives org-wide anyway.
- * A snapshot and a channel that disagree about scope are not two halves of
- * one thing; they are two things that have to be reconciled by every
- * consumer, separately, forever.
- *
- * So: same scope, one route, and `?robot_id=` for the narrow question. The
- * cloud owner proposed this while unblocking the console, and was right.
- *
- * This table was missing from the first W6a delta, and a teammate had to ask
- * three separate people for the paths — which is how a route becomes a fact
- * that lives only in an inbox.
+ * The per-robot reading is the tempting one and it is wrong: a health list is
+ * rendered for every robot at once, and a per-robot path makes that N requests
+ * to draw one screen — while the event that keeps it fresh arrives org-wide
+ * anyway. A snapshot and a channel that disagree about scope are not two halves
+ * of one thing; they are two things every consumer has to reconcile, separately,
+ * forever.
+ *
+ * So: same scope, one route, and `?robot_id=` for the narrow question.
  */
 /**
- * What a `robot.deleted` audit event carries (W6a).
+ * What a `robot.deleted` audit event carries.
  *
  * A deletion record that says only *that* something was destroyed is a
  * receipt for an unknown amount. This names it: how many configured slugs,
@@ -1452,41 +1407,36 @@ export declare const robotDeleteQuery: z.ZodObject<{
 }, z.core.$strip>;
 export type RobotDeleteQuery = z.infer<typeof robotDeleteQuery>;
 /**
- * The seven health states, declared **once** (W6a review).
+ * The seven health states, declared **once**.
  *
- * `resourceHealthState` and `resourceHealthEvent` are the snapshot and the
- * push of the same thing, and they had the same seven values written out
- * twice, linked by nothing — the artifacts published two independent copies
- * with no `$ref`. They agreed only because whoever added `unknown` remembered
- * to add it in both places, on the wave's last contract commit.
+ * `resourceHealthState` and `resourceHealthEvent` are the snapshot and the push
+ * of the same thing. Writing the values out twice publishes two independent
+ * artifacts with no `$ref` between them, kept in step only by whoever
+ * remembers to edit both.
  *
- * One concept rendering as two artifacts that nothing keeps in step is its
- * own class of artifact-versus-source defect, distinct from `.default()`
- * publishing as `required` and from `z.coerce`'s unrepresentable input.
+ * One concept rendering as two artifacts that nothing keeps in step is its own
+ * class of artifact-versus-source defect, distinct from `.default()` publishing
+ * as `required` and from a coercion's unrepresentable input.
  */
 export declare const RESOURCE_HEALTH_STATES: readonly ["ok", "unreachable", "auth_failed", "unreadable_credential", "credential_missing", "stopped_by_config_change", "publish_failed", "unknown"];
 /**
  * The health of one thing a developer configured, as the platform currently
- * sees it (W6a).
- *
- * This exists because four separate findings turned out to be one absence:
- * nothing carried the state of a camera, a source or a credential to a
- * developer who was not, at that exact moment, pressing a button. A publish
- * failure after the `201` never reached the viewer holding the token; a
- * source whose password was wrong failed at config-apply time with nobody
- * watching and stayed silent until someone pressed "Go live" days later; a
- * viewer could not learn *why* a stream ended, so the console had to offer
- * two possibilities and rank neither; and an undecryptable credential
- * reported as healthy.
- *
- * One shape, because four patches against four symptoms is how W5 nearly
- * wrote a failure report into `publishState` — a field the cloud writes and
- * reads in exactly one place, which would have been a dead end.
- *
- * `reason` is for a human and is **never** built from an exception message:
- * W6 found a camera password in a log through `log.exception`, and again in
- * `LiveStartError`'s message, which travels to the cloud on this very path.
- * Type names and fixed strings only.
+ * sees it.
+ *
+ * It exists because nothing else carries the state of a camera, a source or a
+ * credential to a developer who is not, at that exact moment, pressing a
+ * button. A publish failure after the `201` reaches no one; a source whose
+ * password is wrong fails at config-apply time with nobody watching and stays
+ * silent until someone presses "Go live" days later; a viewer cannot learn
+ * *why* a stream ended; an undecryptable credential reports as healthy.
+ *
+ * One shape rather than a field per symptom, because a failure written into a
+ * state field the platform writes and reads in one place is a dead end.
+ *
+ * `reason` is for a human and is **never** built from an exception message: a
+ * camera password reaches a log that way, and an exception message from a
+ * failing stream travels to the cloud on this very path. Type names and fixed
+ * strings only.
  */
 export declare const resourceHealthState: z.ZodObject<{
     robot_id: z.ZodUUID;
@@ -1515,14 +1465,8 @@ export type ResourceHealthState = z.infer<typeof resourceHealthState>;
 /**
  * The current state of everything in the **org**.
  *
- * This doc said "on one robot" until the W6a review found it: the route moved
- * to org scope in `2bb67c5` and the route table forty lines above spends a
- * paragraph explaining why the per-robot reading was wrong — while the schema
- * it describes still said the old thing. Cloud, console and SDK all implement
- * org-wide correctly; contracts was the only place still saying otherwise,
- * and it is the first place a fourth consumer reads.
- *
- * A channel with no snapshot cannot answer "what is the state now?" for a
+ * Org-wide, not per robot — the route table above explains why. A channel
+ * with no snapshot cannot answer "what is the state now?" for a
  * page that just loaded — it can only report the next change, which may be
  * hours away. Both halves or neither.
  */
@@ -1564,9 +1508,9 @@ export declare const orgHealthQuery: z.ZodObject<{
 }, z.core.$strip>;
 export type OrgHealthQuery = z.infer<typeof orgHealthQuery>;
 /**
- * Org protection quotas (§12.4) — generous, server-side adjustable, visible
- * in Settings. Protection against runaway use, not a business model; a later
- * one docks onto the same dials.
+ * Org protection quotas — generous, server-side adjustable, visible in
+ * settings. Protection against runaway use, not a business model; a later one
+ * docks onto the same dials.
  */
 export declare const orgQuotas: z.ZodObject<{
     max_robots: z.ZodNumber;
@@ -1586,8 +1530,7 @@ export type OrgQuotas = z.infer<typeof orgQuotas>;
  * `positive()` because a quota of zero would forbid everything, but a
  * **usage** of zero is the honest answer for every org on the day it signs
  * up. Reusing one schema for a limit and a measurement is the same mistake as
- * letting an empty bucket and a zero average share a representation, which
- * this wave spent a lot of care avoiding one layer up.
+ * letting an empty bucket and a zero average share a representation.
  *
  * Every field is optional because a quota we do not measure must be
  * **absent**, never reported as `0` — "not measured" and "measured as zero"
@@ -1649,11 +1592,9 @@ export declare const BRIDGE_LATENCY_RETENTION_DAYS = 7;
  * | `GET /api/org/latency` | `orgLatencyQuery` | `orgLatencyResponse` — one series per robot, truncation named |
  * | `GET /api/robots/:id/jobs/history` | `jobRunQuery` | `jobRunListResponse` — the same read, robot-scoped, developers **and** clients |
  *
- * **Written down here because the last time a delta shipped shapes without
- * their paths, a teammate had to ask three separate people** — see
- * `robotDeletionSummary`'s neighbouring table, which exists for exactly that
- * reason. The shapes landed one wave before the routes did, so this table is
- * the only place the two halves meet.
+ * The paths are written down beside the shapes, as in
+ * `robotDeletionSummary`'s neighbouring table: a shape whose route is not
+ * named here is a fact that lives only in somebody's memory.
  *
  * Three things about them are worth stating rather than inferring:
  *
@@ -1773,7 +1714,7 @@ export type OrgLatencyResponse = z.infer<typeof orgLatencyResponse>;
  */
 export declare const USAGE_WINDOW_MAX_DAYS = 366;
 /**
- * The five things the meter records (spec D1).
+ * The five things the meter records.
  *
  * Storage is two metrics and not one summed byte count, for
  * `org_quotas.max_asset_storage_bytes`'s own reason applied to billing: a sync
@@ -1815,7 +1756,7 @@ export type UsageMetric = z.infer<typeof usageMetric>;
 export declare const usageDay: z.ZodString;
 /**
  * **The window is inclusive at both ends**, unlike every millisecond window in
- * this file (`from_ms`/`to_ms`, half-open per DEF-062).
+ * this file (`from_ms`/`to_ms`, which are half-open).
  *
  * That inconsistency is deliberate and is stated here rather than left to be
  * discovered: a calendar day is a unit, not an instant, and a person asking for
@@ -1852,7 +1793,7 @@ export type OrgUsageQuery = z.infer<typeof orgUsageQuery>;
 /**
  * One day's reading for one metric.
  *
- * **`app_id` is `null` when the consumer is the org itself** (spec D2), and
+ * **`app_id` is `null` when the consumer is the org itself**, and
  * what that `null` means for billing depends on the *metric*, not on
  * `app_id` alone. `api_calls` and `live_session_ms` are attributable to an
  * app: a `null` app_id on those two is the developer console's own traffic,
@@ -1881,9 +1822,8 @@ export type OrgUsageQuery = z.infer<typeof orgUsageQuery>;
  * not hold at all: everything counted since the last successful flush is
  * held in memory, deliberately uncapped, and a `kill -9` loses all of it.
  * The trade is intentional (dropping billing data to bound process memory is
- * the worse half of it), but "at most one interval" describes a platform
- * whose writes are landing, not a guarantee that survives an outage. This
- * sentence used to say "never more", and it was false.
+ * the worse half of it), but "at most one interval" describes a platform whose
+ * writes are landing, not a guarantee that survives an outage.
  *
  * A row the database rejects **permanently** — most concretely one whose org
  * has been deleted since the count, since a usage row's `org_id` is `ON
@@ -1974,11 +1914,10 @@ export type RenameSlugResponse = z.infer<typeof renameSlugResponse>;
  * `GET /api/robots/:id/config/slug-usage/:slug` — what a rename would touch;
  * feeds the console's confirm dialog.
  *
- * `alert_count` (spec `2026-08-28-alerts-and-datapoint-modal-design`, D5)
- * joined the atomic rename transaction alongside grants and history: alerts
- * are keyed by `(robot_id, slug)` too, and a rename that silently moved the
- * alert row while the usage preview stayed silent about it would show a
- * developer a smaller blast radius than the rename actually has.
+ * `alert_count` is part of the atomic rename transaction alongside grants and
+ * history: alerts are keyed by `(robot_id, slug)` too, and a rename that
+ * silently moved the alert row while the usage preview stayed silent about it
+ * would show a developer a smaller blast radius than the rename actually has.
  */
 export declare const slugUsageResponse: z.ZodObject<{
     grant_count: z.ZodNumber;