@fleetless/contracts 1.0.0 → 1.0.3

package/dist/config.js

@@ -10,15 +10,14 @@ import { applyError, slug, rosName, rosTypeName, fieldPath, SLUG_RULE, ROS_NAME_
  */
 import { alertSeverity } from './alerts.js';
 /**
- * The exposure model (spec §4): what a developer configures per robot, how a
+ * The exposure model: what a developer configures per robot, how a
  * configuration moves from draft to published, and how the cloud reports what
  * it refuses.
  *
  * ## What this schema decides, and what it leaves to the cloud
  *
- * FL-002 names thirteen validation codes and this file implements some of
- * them. The line was drawn four times while the format was written and never
- * written down, so here it is.
+ * The format names thirteen validation codes and this file implements some of
+ * them. Here is where the line runs.
  *
  * **Decided here** — everything a single entry, plus its own declared types,
  * answers on its own: `unknown_key` (every object is this file's own
@@ -49,29 +48,26 @@ import { alertSeverity } from './alerts.js';
  * index. Splitting them would put one rule here and its three siblings there
  * — the shape this file has twice had to undo.
  *
- * **Every refusal that answers one of the spec's codes carries
+ * **Every refusal that answers one of the format's validation codes carries
  * `params: { code }`** with that code, which zod passes through `safeParse`
  * untouched. The cloud maps an issue to a code and its repair by reading that
  * field, never by matching the message prose — a join nobody notices
  * breaking.
  *
- * Read the sentence narrowly, because a wider reading is false and was
- * written here once. Plenty of refusals in this file carry no `params.code`,
- * and correctly: the section caps (`parameterMap`'s fifty, `messageMap`'s two
- * hundred), the camera device-path rules, and every refusal zod raises on its
- * own — `unrecognized_keys` behind `unknown_key`, `too_big` behind
- * `invalid_rate`. Those are not spec codes wearing a different hat; the cloud
- * reaches them through zod's own issue codes. The one *spec* code with no
- * `params` is a reversed pair of bounds — `min_value`/`max_value` on a
- * parameter, `y_min`/`y_max` on a chart: `invalid_range` was deleted with
- * `expected_range`, and no code replaced it.
+ * Read that sentence narrowly. Plenty of refusals in this file carry no
+ * `params.code`, and correctly: the section caps (`parameterMap`'s fifty,
+ * `messageMap`'s two hundred), the camera device-path rules, and every refusal
+ * zod raises on its own — `unrecognized_keys` behind `unknown_key`, `too_big`
+ * behind `invalid_rate`. Those are not validation codes wearing a different
+ * hat; a consumer reaches them through zod's own issue codes. The one named
+ * code with no `params` is a reversed pair of bounds — `min_value`/`max_value`
+ * on a parameter, `y_min`/`y_max` on a chart — for which no code exists.
  *
  * `robotConfigDoc` carries all six sections — messages, datapoints, actions,
- * services, publishers and cameras — plus, since FL-002, the alerts, the
- * chart bounds and the camera credentials that used to live outside it.
- * Everything configurable about a robot is in this document, and there is one
- * door to it. FL-002 rewrote the slug grammar (underscores, not dashes) and
- * keyed every section by name; draft/publish and versioning are unchanged.
+ * services, publishers and cameras — plus the alerts, the chart bounds and the
+ * camera credentials. Everything configurable about a robot is in this
+ * document, and there is one door to it. Every section is keyed by name, and
+ * the document moves from draft to published under a version.
  */
 /**
  * What every `pattern` in this document means, said in words.
@@ -93,16 +89,12 @@ import { alertSeverity } from './alerts.js';
  * which is a published artifact other tools validate against and which a person
  * reads. One constant with two readers, never two strings that happen to agree
  * — `config-zod-messages.test.ts` asserts the two readings are the same string
- * at all 24 pattern positions the document has, because under D3 nothing
- * consumes `patternErrorMessage` at runtime and an unwatched second spelling of
- * a live rule drifts word for word, forever and invisibly.
+ * at every pattern position the document has. An unwatched second spelling of a
+ * live rule drifts word for word, forever and invisibly.
  *
- * In the console `patternErrorMessage` is also the live pattern diagnostic
- * **until wave 3 lands**: `useMonacoYaml.ts` still passes `validate: true`, so
- * between task 7's artifacts and D3 these sentences are what monaco-yaml shows.
- * D3 then turns that validation off, and from there the message a developer
- * sees comes from this schema's own parser and from the cloud — the same
- * sentence, which is the point of there being one.
+ * An editor that validates against the published JSON Schema shows
+ * `patternErrorMessage`; one that does not shows whatever the server's parser
+ * says. They are the same sentence, which is the point of there being one.
  *
  * The tense matters because the two states look identical from inside this
  * file. Whoever reads it after wave 3 should find a claim that was true when
@@ -121,33 +113,27 @@ const DEVICE_PATH_RULE = 'A capture device is a path under `/dev/`, and the char
  *
  * **`slug` itself stays plain in `common.ts`, and the reason is blast radius.**
  * Not metadata loss: `.meta()` on a clone *merges* with the parent's entry per
- * key and resolves it lazily, measured against zod 4.4.3 and written up at
- * `messageBody`'s own `.meta()` below — a later `description` on a use of
- * `slug` would keep the sentence, not drop it.
- *
- * What that reach would cost was measured instead, by adding the one `.meta()`
- * line to `slug` in a copy of `src/` and re-exporting every artifact under each
- * schema's own `io`: **42 of the 159 published schema artifacts** would carry
- * it, `bridge-hello`, `datapoint-frame`, `snapshot-header` and
- * `bridge-camera-state` among them — protocol frames the bridge **vendors**
- * under `bridge/test/contracts/schema/`, so rewording one sentence would become
- * a re-vendor plus a `SOURCE.md` edit in another repo. As landed the same
- * search finds **7**, all config-derived.
- *
- * Whether `vscode-json-languageservice` honours `patternErrorMessage` on a
- * `propertyNames` schema at all is **not measured** — §1.3 measured a value
- * position, not a key one. It ships for the same reason as the rest: the
- * artifact is read by tools and by people.
+ * key and resolves it lazily — a later `description` on a use of `slug` keeps
+ * the sentence rather than dropping it.
+ *
+ * The cost is reach. Annotating `slug` itself puts the sentence into dozens of
+ * the published schema artifacts, protocol frames included, so rewording one
+ * sentence becomes a change to every consumer that vendors those. Annotating
+ * the key here reaches only the configuration schemas, which is where the
+ * sentence is useful.
+ *
+ * Whether a given YAML language service honours `patternErrorMessage` on a
+ * `propertyNames` schema is not something this package can promise. It ships
+ * for the same reason as the rest: the artifact is read by tools and by people.
  */
 const mapKey = slug.meta({ patternErrorMessage: SLUG_RULE });
 /**
  * One field, carrying the sentence it says when it is absent.
  *
- * **Three shapes of "this key is not here", and the first version of this
- * helper caught one of them.** A walk over every required key of a fully
- * populated document — `config-zod-messages.test.ts`, which is the guard that
- * found it — says the format has 52 required-key positions and that 14 were
- * still answering in zod's words:
+ * **Three shapes of "this key is not here", and a helper has to cover all
+ * three.** A walk over every required key of a fully populated document —
+ * `config-zod-messages.test.ts` — enumerates every required-key position in the
+ * format and asserts none of them still answers in zod's words:
  *
  * - `invalid_type`, the ordinary case: a string, a number, an object.
  * - `invalid_value` from a `z.literal` or a `z.enum`. A missing `fleetless:`
@@ -167,10 +153,10 @@ const mapKey = slug.meta({ patternErrorMessage: SLUG_RULE });
  * **`z.unknown()` needs a wrapper before it can be given a sentence at all.**
  * It accepts `undefined`, so zod marks the key required and raises its own
  * `expected nonoptional, received undefined` — an issue it attributes to
- * neither the field nor the object, so no error map of ours is consulted
- * (measured). `z.nonoptional` puts a schema there that can carry one. The JSON
- * Schema and the inferred type are byte-identical either way (measured, zod
- * 4.4.3), and a field that is genuinely optional is `.optional()` and is
+ * neither the field nor the object, so no error map of ours is consulted.
+ * `z.nonoptional` puts a schema there that can carry one. The JSON Schema and
+ * the inferred type are identical either way, and a field that is genuinely
+ * optional is `.optional()` and is
  * skipped here — but it is **not** behaviourally free, and that is the one
  * place this task changed what the format accepts: a required key *present*
  * holding `undefined` is now refused where zod's internal check accepted it.
@@ -186,11 +172,11 @@ const mapKey = slug.meta({ patternErrorMessage: SLUG_RULE });
  *
  * `clone` is the only way to add an `error` to a schema that is already built,
  * and **it drops the schema's registry entry** — its `description`, its
- * `examples`, every annotation this wave added, all of which live in
+ * `examples` and every other annotation, all of which live in
  * `z.globalRegistry` keyed by the schema instance rather than in its
- * definition. So the entry is read back and put on the clone. Measured on zod
- * 4.4.3: `z.globalRegistry.get` resolves the whole `.meta()` parent chain into
- * one object, so what is copied is what the export would have produced, and a
+ * definition. So the entry is read back and put on the clone.
+ * `z.globalRegistry.get` resolves the whole `.meta()` parent chain into one
+ * object, so what is copied is what the export would have produced, and a
  * later `.meta()` on the result merges with it as it did before. A wrapper that
  * silently emptied every hover in the format would be the worst available way
  * to improve one message.
@@ -241,8 +227,8 @@ const saysItIsMissing = (field) => {
  * The second arm is the discriminated union: zod hands its error map the whole
  * object and points the path at the discriminator, so `input` is not
  * `undefined` and the first arm cannot see it. `Object.hasOwn` rather than
- * `in`, on this project's own rule — a document's keys are chosen by a
- * developer, and `constructor` satisfies the slug grammar.
+ * `in`, because a document's keys are chosen by a developer and `constructor`
+ * satisfies the slug grammar.
  */
 const absent = (issue, key) => issue.input === undefined
     || (issue.code === 'invalid_union'
@@ -256,37 +242,28 @@ const namesItsAbsence = (shape) => Object.fromEntries(Object.entries(shape).map(
  * its own name when it is absent.
  *
  * **This is not `z.strictObject`** — it is this file's, wrapping it. The
- * difference is the second half: `Invalid input: expected object, received
- * undefined` was the whole of what a developer was told when a camera had no
- * `source:` (design §1.5), naming neither the key nor the fact that it was
- * required. monaco-yaml said `Missing property "source".` for the same
- * document, and was right to.
+ * difference is the second half. Plain zod tells a developer whose camera has
+ * no `source:` only `Invalid input: expected object, received undefined`,
+ * naming neither the key nor the fact that it was required. A YAML language
+ * service says `Missing property "source".` for the same document, and is right
+ * to.
  *
  * It has to be done a field at a time. zod attributes a missing key to the
  * **field's own** schema — an `invalid_type` whose input is `undefined` — and
- * an `error` on the containing object is never consulted for it; measured on
- * zod 4.4.3, an error map on the object saw no such issue at all. So the
+ * an `error` on the containing object is never consulted for it. So the
  * sentence is attached to every field of every shape, here, in one place,
- * rather than at the eighteen objects and hundred-odd fields it would
- * otherwise have to be remembered at.
- *
- * **How "every" is enforced, because the first version of this comment said
- * "every" and was wrong.** Six of the eighteen objects were written
- * `z\n  .strictObject({`, so `z.strictObject` never appeared on one line and a
- * `grep` for it returned only prose. Twelve conversions read as eighteen, and
- * eleven required keys — `datapoints.<slug>.topic` and `.type` among them,
- * which is the commonest entry in the whole format — went on reciting the
- * sentence §1.5 calls unusable. The claim was in the source, which is what the
- * next person reads.
- *
- * What makes it true now is not this paragraph. It is
+ * rather than at each of the objects and fields it would otherwise have to be
+ * remembered at.
+ *
+ * **How "every" is enforced.** Not by this paragraph: a claim in a comment is
+ * what the next person reads and not what holds. It is
  * `config-zod-messages.test.ts`'s *"a required key that is absent names
- * itself"*: a walk of the exported schema's `required` arrays against a
+ * itself"* — a walk of the exported schema's `required` arrays against a
  * fully-populated document, `oneOf` branches resolved by their discriminator,
- * deleting one key at a time and asserting the message names it. It reaches 52
- * positions across 19 objects, and the count comes out of the walk rather than
- * off a list — a required key added to the format later is swept the day it
- * exists, and an object that skips this helper is red before it is merged.
+ * deleting one key at a time and asserting the message names it. The count
+ * comes out of the walk rather than off a list, so a required key added to the
+ * format later is swept the day it exists, and an object that skips this helper
+ * is red before it is merged.
  */
 const strictObject = (shape) => z.strictObject(namesItsAbsence(shape));
 /**
@@ -343,8 +320,8 @@ const describeValues = (values, table) => values.map((value) => table[value]);
  *
  * The two syntaxes collide. `defaultSnippets` bodies are inserted as LSP
  * snippets, where `${1:front}` is a tab stop and `${speed}` is a *variable* —
- * and an unknown variable is not left alone. Measured against
- * monaco-editor 0.52.2's own `SnippetParser`, which is what the console runs:
+ * and an unknown variable is not left alone. Against monaco-editor's own
+ * `SnippetParser`:
  *
  * | body holds | the editor inserts |
  * |---|---|
@@ -367,52 +344,45 @@ const param = (name) => `\\\${${name}}`;
  * `{ battery: … }`, and `battery: ▮` offers the `…`. Both positions are real
  * and both were silent, but they are **one skeleton**, so each is authored once
  * as a `Snippet` constant and wrapped here for the section — never copied.
- * Two copies of one skeleton is the drift this wave caught three times in three
- * reviews: a body inventing a value its sibling had already answered, under a
- * label that still agreed. `config-snippets.test.ts` deep-compares the two
- * positions rather than trusting this.
+ * Two copies of one skeleton drift: a body invents a value its sibling had
+ * already answered, under a label that still agrees.
+ * `config-snippets.test.ts` deep-compares the two positions rather than
+ * trusting this.
  *
  * **The slug key belongs to the wrapper, not to the skeleton**, because it
  * differs per snippet — `battery_voltage` for a plain datapoint, `battery` for
  * the numeric one. It therefore takes tab stop `${1}`, and an entry body's own
  * stops are numbered from `${2}` throughout. At the entry position that leaves
- * no `${1}` at all, which costs nothing — measured against
- * monaco-editor 0.52.2's own `SnippetParser`, the version the console runs: it
+ * no `${1}` at all, which costs nothing: monaco-editor's `SnippetParser`
  * sorts placeholders by index and requires neither that they start at 1 nor
  * that they be contiguous, so a body of `a: ${2:x}` visits `2` first, and one
  * of `a: ${2:x}` / `b: ${5:y}` visits `2` then `5`.
  */
 const underSlug = (slugKey, snippet) => ({ ...snippet, body: { [slugKey]: snippet.body } });
 /**
- * What an exposed service *is*, in the developer's own words (§17).
+ * What an exposed service *is*, in the developer's own words.
  *
  * This is what `robot_describe` carries verbatim, so it is read by a model
  * that has never seen this robot and cannot ask a follow-up question.
  * `unit` and `range` already say what a number *is*; this says what it
  * *means*.
  *
- * **It lives on the configuration rather than on the app, and that was a
- * decision with a cost.** §17's own wording put the semantic descriptions in
- * the MCP app; André moved them here on 2026-08-18 so that a description is
- * written once per service and true for every app that reaches the robot,
- * beside the other metadata. What is given up is real and should not be
- * rediscovered as a bug: **two apps can no longer describe one service
- * differently for two audiences.** §17 was reworded in the same wave rather
- * than left contradicting this field.
+ * **It lives on the configuration rather than on the app, and that is a
+ * decision with a cost.** A description written here is written once per
+ * service and is true for every app that reaches the robot, beside the other
+ * metadata. What is given up is real and should not be rediscovered as a bug:
+ * **two apps cannot describe one service differently for two audiences.**
  *
  * **`.optional()` and not `.nullable().default(null)`, deliberately.** The
  * established shape in this file is a default — and every use of it has
  * added an instance to a known contradiction: `.default()` publishes the
  * field as **required** in the generated JSON Schema, because after parsing
- * it is always present. That is recorded four times over in
- * `scripts/export-schemas.ts`, whose fix (`io: 'input'`, applied per schema)
- * is a judgement call across roughly sixty schemas plus a re-vendor and a
- * re-pin in four repos. W7c's playbook said task 0 would do it; reading the
- * measured blast radius — 90 artifacts, 436 deletions for the blanket
- * version — said otherwise, at the start of a wave with five people blocked
- * on this pin. So the field simply does not create a fifth instance:
- * optional is optional in both modes, and *absent* is the single spelling of
- * "not described". `.min(1)` keeps the empty string from becoming a second.
+ * it is always present. That is recorded in `scripts/export-schemas.ts`, whose
+ * remedy (`io: 'input'`, applied per schema) is a judgement call across dozens
+ * of schemas and every consumer that vendors them. So this field simply does
+ * not add another instance: optional is optional in both modes, and *absent* is
+ * the single spelling of "not described". `.min(1)` keeps the empty string from
+ * becoming a second.
  */
 export const serviceDescription = z.string().min(1).max(2000).optional();
 /**
@@ -610,9 +580,9 @@ export const parameterSpec = strictObject({
      * A default must satisfy the same constraints a caller's value must.
      *
      * Without this, a default is the one way past bounds that are otherwise
-     * the enforcement point — the spec calls `min_value`/`max_value` "the
-     * speed limit that actually holds", enforced in the cloud before anything
-     * reaches the robot. But a caller who simply omits the parameter gets the
+     * the enforcement point. `min_value`/`max_value` are the speed limit that
+     * actually holds, enforced in the cloud before anything reaches the robot.
+     * But a caller who simply omits the parameter gets the
      * default, and the bridge fills it at the template walk without
      * re-checking bounds, deliberately: a second enforcement point there
      * would be the weaker of two policies. So `{min_value: -1, max_value: 1,
@@ -673,7 +643,7 @@ export const parameterMap = slugKeyed(parameterSpec)
     defaultSnippets: [underSlug('${1:speed}', PARAMETER_SNIPPET)],
 });
 /**
- * Slugs no configured entry may take (spec §4.3), across **all five exposure
+ * Slugs no configured entry may take, across **all five exposure
  * sections at once** — slugs are one namespace, so a name reserved here is
  * reserved everywhere.
  *
@@ -686,12 +656,12 @@ export const parameterMap = slugKeyed(parameterSpec)
  * name is the honest half of that: the alternative is a slug the format
  * accepts and one route silently cannot address.
  *
- * **This constant is the only list.** The cloud's `validation.ts` builds its
- * set from it and emits `reserved_slug`; `config-store.ts` reads it for the
- * rename target; the console reads it for slug suggestion and repairs. Nothing
- * copies the members. Note that it is NOT the enumeration of built-in
- * datapoints — the cloud keeps that separately, and it must, now that a
- * reserved name exists that no plane serves.
+ * **This constant is the only list.** The cloud builds its set from it and
+ * emits `reserved_slug`; the rename path reads it for the target; an editor
+ * reads it for slug suggestion and repairs. Nothing copies the members. Note
+ * that it is NOT the enumeration of built-in datapoints — those are kept
+ * separately, and must be, because a reserved name exists that nothing
+ * publishes.
  *
  * **What it does not do: `robotConfigDoc` does not enforce it.** Reservation is
  * a semantic check that belongs with the ones that need the robot's context,
@@ -809,10 +779,9 @@ export const datapointAlert = strictObject({
          * `getInsertTextForProperty` (`yaml.worker.js:8520`) takes
          * `defaultSnippets[0].body` only when a node carries **exactly one**
          * snippet, so accepting `condition` from the key list writes the bare key
-         * here where every other node this wave touched writes its whole block.
-         * The two stay anyway: the value position — a developer who has written
-         * `condition:` and pressed ⏎ — is where the question "what goes here?" is
-         * actually asked, and that is the position this wave exists to answer.
+         * here where every other node writes its whole block. The two stay anyway:
+         * the value position — a developer who has written `condition:` and pressed
+         * ⏎ — is where the question "what goes here?" is actually asked.
          * Merging them into one would buy back the key completion by deleting the
          * choice the schema deliberately does not name, which is the worse trade;
          * anyone tempted to make it should change the key-completion behaviour
@@ -984,9 +953,9 @@ const NUMERIC_DATAPOINT_SNIPPET = {
         /**
          * The quotes inside `unit` are part of the inserted text and are not
          * decoration. A body string is written into the document verbatim, and `%`
-         * is a YAML directive indicator: measured with `yaml` 2.9.0, `unit: %` is a
-         * **syntax error** ("Plain value cannot start with directive indicator
-         * character %") while `unit: "%"` parses to `%`. Nothing between here and
+         * is a YAML directive indicator: `unit: %` is a **syntax error** ("Plain
+         * value cannot start with directive indicator character %") while
+         * `unit: "%"` parses to `%`. Nothing between here and
          * the buffer quotes a scalar for us.
          */
         numeric: { scale: 100, unit: '"%"', decimals: 1 },
@@ -1166,10 +1135,9 @@ export const datapointConfig = strictObject({
  * `z.unknown()`, because a template can be any shape a ROS message can — so
  * nothing below the top of it is checked by the type at all.
  *
- * That gap was measured and missed once already: a top-level `message: null`
- * was refused while `message: { linear: { x: null } }` parsed clean, and a
- * check written to catch exactly this was deleted on the strength of six test
- * cases, none of which reached inside a body.
+ * The gap is easy to miss: a top-level `message: null` is refused while
+ * `message: { linear: { x: null } }` parses clean, and a test suite that never
+ * reaches inside a body cannot tell the two apart.
  *
  * Walked with an explicit stack and a seen-set, not recursion: a YAML anchor
  * can make a template both very deep and genuinely cyclic, and a developer can
@@ -1253,10 +1221,9 @@ export const messageBody = messageTemplate;
  * contract.** This runs inside `publisherConfig`'s failsafe refinement, so a
  * `RangeError: Maximum call stack size exceeded` did not stay here: it
  * propagated out of `safeParse`, which is specified to return a result and
- * not to throw. Measured on the recursive version — fine at 8 000 levels of
- * nesting, throwing at 20 000 — and a flow-style YAML one-liner reaches that
- * in about 120 KB of input. A draft PUT would have answered 500 where it
- * meant 400.
+ * not to throw. A recursive walk survives a few thousand levels of nesting and
+ * throws somewhere above that, which a flow-style YAML one-liner reaches in
+ * about 120 KB of input — so a draft PUT would answer 500 where it meant 400.
  *
  * `seen` is not an optimisation. YAML anchors can express a cycle
  * (`&a { b: *a }`), and the parser resolves an alias to the same object, so
@@ -1324,14 +1291,13 @@ const SHARED_MESSAGE_SNIPPET = {
  * that paragraph would be a second thing to keep true.
  *
  * **How the description gets here is zod behaviour, not something written
- * below.** Measured against zod 4.4.3: `.meta()` on an already-registered
- * schema merges rather than replaces, and the clone resolves the parent's entry
+ * below.** `.meta()` on an already-registered schema merges rather than
+ * replaces, and the clone resolves the parent's entry
  * *lazily* — a clone taken before the parent was registered at all still sees
  * the parent's description afterwards. So no spread is needed and there is no
- * evaluation-order hazard. This was first written as
- * `.meta({ ...messageTemplate.meta(), … })`; dropping the spread was measured
- * to change nothing in the export, and two mechanisms for one description is
- * the shape this file removes rather than adds.
+ * evaluation-order hazard. A defensive `.meta({ ...messageTemplate.meta(), … })`
+ * spread changes nothing in the export and is a second mechanism for one
+ * description, so it is deliberately absent.
  *
  * It is undocumented behaviour all the same, so `config-snippets.test.ts`
  * asserts this node still carries a description and that it is the same string
@@ -1366,7 +1332,7 @@ const ACTION_SNIPPET = {
     },
 };
 /**
- * An action the robot can be asked to perform (spec §4.2, §11.3). At most one
+ * An action the robot can be asked to perform. At most one
  * job runs per action slug; a second call is refused `busy`, and every
  * observer of the slug watches the same job.
  */
@@ -1406,7 +1372,7 @@ const SERVICE_SNIPPET = {
         description: '${4:Resets odometry to the origin.}',
     },
 };
-/** A ROS service call with validated parameters (spec §4.2). */
+/** A ROS service call with validated parameters. */
 export const serviceConfig = strictObject({
     ros_name: rosName.meta({
         description: 'The ROS service the robot answers on, as an absolute graph name. The call is one request and one reply with no progress in between, so whatever this service does has to finish inside that reply; anything long-running belongs in `actions`.',
@@ -1612,7 +1578,7 @@ export const cameraCredentials = strictObject({
         }],
 });
 /**
- * Where a camera's frames come from (spec §10 names four sources).
+ * Where a camera's frames come from — one of four sources.
  *
  * A discriminated union rather than optional fields, so an impossible camera
  * is **unrepresentable** rather than merely invalid — there is no way to
@@ -1620,8 +1586,8 @@ export const cameraCredentials = strictObject({
  * therefore no validation rule to forget.
  *
  * **Each branch carries its own `defaultSnippets`, rather than one list on the
- * union.** Both placements were measured and both work; this one keeps a
- * label beside the branch it names, so the two cannot drift, and it makes a
+ * union.** Both placements work; this one keeps a label beside the branch it
+ * names, so the two cannot drift, and it makes a
  * fifth source impossible to add without one — `config-snippets.test.ts`
  * walks the exported branches and fails on any that carries none.
  */
@@ -1659,15 +1625,14 @@ export const cameraSource = z.discriminatedUnion('kind', [
                  * `rosTypeName` accepts either, publish accepts either, no diagnostic
                  * fires anywhere, and the bridge then subscribes with the wrong type and
                  * delivers no frames. A snippet supplying a wrong answer where it could
-                 * have supplied a question is this project's *check that cannot fire*,
-                 * arriving through a hint the developer trusts.
+                 * have supplied a question is a defect arriving through a hint the
+                 * developer trusts.
                  *
                  * `kind: 'ros'` stays a literal, because the branch really does fix it.
                  *
-                 * Measured through the actual pipeline rather than assumed, because
-                 * choice syntax is the one construct here that three layers must each
+                 * Choice syntax is the one construct here that three layers must each
                  * pass through unharmed: yaml-language-server's `stringifyObject` emits
-                 * the body verbatim, and monaco-editor 0.52.2's `SnippetParser` parses
+                 * the body verbatim, and monaco-editor's `SnippetParser` parses
                  * `${2|a,b|}` into a placeholder carrying both options whose
                  * `toString()` — the text on the buffer before anyone chooses — is the
                  * first one. So a developer who tabs past this gets a document
@@ -1686,16 +1651,12 @@ export const cameraSource = z.discriminatedUnion('kind', [
             description: 'Selects the RTSP source: this camera then carries `url`, and optionally `transport` and `credentials`.',
         }),
         /**
-         * Scheme-constrained deliberately. The playbook drafted `z.string().url()`
-         * here and the shipped contract was `z.string().min(1).max(2048)` — nobody
-         * recorded the change, and the W6 review found the consequence: the bridge
-         * opens these with libraries that honour `file:` and `ftp:`, so an
-         * unconstrained URL turns a configuration document into an arbitrary
-         * local-file read on the robot, with the two distinct failure codes
-         * doubling as a file-existence oracle. Spec §7.6 is ROS-pure exposure with
-         * no shell or http features; that rule came back by omission rather than
-         * by intent. The bridge re-checks this too — a robot must not become a
-         * file server because a validator changed.
+         * Scheme-constrained deliberately. The bridge opens these with libraries
+         * that honour `file:` and `ftp:`, so an unconstrained URL turns a
+         * configuration document into an arbitrary local-file read on the robot,
+         * with the two distinct failure codes doubling as a file-existence oracle.
+         * The bridge re-checks this too — a robot must not become a file server
+         * because a validator changed.
          */
         url: z
             .string()
@@ -1743,8 +1704,8 @@ export const cameraSource = z.discriminatedUnion('kind', [
             /**
              * The host and the path this branch's own snippet body inserts, and the
              * URL its rule sentence names — one answer to "what goes here?", not a
-             * third. The sibling `rtsp` url had an `examples` from the first day and
-             * this position was the format's only silent URL (§1.1).
+             * third. Every URL position in the format carries an example; a silent
+             * one is the position a developer has to guess at.
              */
             examples: ['http://cam-1.plant.local/video.mjpg'],
         }),
@@ -1769,16 +1730,14 @@ export const cameraSource = z.discriminatedUnion('kind', [
          * on the robot, never by the cloud.
          *
          * Constrained to `/dev/` for the same reason the `rtsp` and `mjpeg` URLs
-         * are constrained to their schemes, and it was missed the first time
-         * (Momus, W6 verification). The device string reaches
+         * are constrained to their schemes. The device string reaches
          * `cv2.VideoCapture(device)` on the robot, and OpenCV does not restrict
-         * itself to devices: measured on cv2 4.5.4, an ordinary local video file
-         * opens and its pixels are published to the cloud, and so does
-         * `http://127.0.0.1:8899/secret.jpg`. Unconstrained, this field is an
-         * arbitrary local-file read *and* an outbound fetch from inside the robot
-         * — the §7.6 violation closed for the other two source kinds, reachable
-         * through the fourth, because "it is just a device path" read like a
-         * reason not to check.
+         * itself to devices: an ordinary local video file opens and its pixels are
+         * published to the cloud, and so does an `http://` URL pointing back inside
+         * the robot's own network. Unconstrained, this field is an arbitrary
+         * local-file read *and* an outbound fetch from inside the robot — the same
+         * hole closed for the other two source kinds, reachable through the fourth,
+         * because "it is just a device path" reads like a reason not to check.
          *
          * Narrower than the URL hole in one respect worth recording: a non-media
          * file and a missing file both fail to open, so this branch never worked
@@ -1823,9 +1782,9 @@ export const cameraSource = z.discriminatedUnion('kind', [
  *
  * The bound lives here once, and `rest.ts`'s `cameraDescriptor` reuses it —
  * the same treatment `rateThrottleHz` got, and for the same reason: the
- * descriptor used to say `snapshot_interval_ms` while the document said
- * seconds, so the cloud converted on one descriptor and not its sibling, with
- * nothing in either file saying so.
+ * two spellings of one interval — milliseconds in a descriptor, seconds in the
+ * document — mean a server converting on one and not the other, with nothing in
+ * either file saying so.
  */
 export const snapshotIntervalSeconds = z.number().int().min(1).max(3600);
 /**
@@ -1851,14 +1810,14 @@ const CAMERA_SNIPPET = {
     },
 };
 /**
- * A camera the robot exposes (spec §10).
+ * A camera the robot exposes.
  *
- * `width`/`height`/`fps`/`bitrate_kbps` are not cosmetic: §10 makes them the
+ * `width`/`height`/`fps`/`bitrate_kbps` are not cosmetic: they are the
  * developer's control over **the robot's own bandwidth**, which is why they
  * live in the configuration rather than in a viewer's request. A viewer never
  * gets to make a robot send more.
  *
- * The two modes are deliberately independent (§10):
+ * The two modes are deliberately independent:
  *
  * - **Snapshot** runs always, at `snapshot_interval_seconds`, whether or not
  *   anyone is watching live. The cloud caches the one frame and serves every
@@ -1913,7 +1872,7 @@ const capped = (entry, max, what) => slugKeyed(entry).refine((m) => Object.keys(
  * their own name. A duplicate name is then a YAML syntax error rather than a
  * rule somebody has to write, and the name reads as the entry's heading.
  *
- * Slugs remain ONE namespace across all five exposure sections (§4.1), which
+ * Slugs remain ONE namespace across all five exposure sections, which
  * is what lets a role grant say `{robot, slug}` without naming a kind. That
  * check spans sections and therefore lives in the cloud, not here.
  */
@@ -1950,12 +1909,12 @@ export const robotConfigDoc = strictObject({
     }).optional(),
 });
 /**
- * One thing the cloud has to say about a configuration (spec §11.5: field +
- * violated rule).
+ * One thing the cloud has to say about a configuration: the field, and the
+ * rule it violates.
  *
  * `error` blocks the publish. `warning` does not — an unknown topic is a
- * warning on purpose, because configuring a robot that has never been
- * connected must stay possible (spec §4.1).
+ * warning on purpose, because configuring a robot that has never been connected
+ * must stay possible.
  */
 export const validationIssue = z.object({
     path: z.string().min(1),
@@ -1966,8 +1925,7 @@ export const validationIssue = z.object({
 });
 /**
  * Where a robot's configuration stands — the material for the console's
- * "draft newer than published", "published v2 · applied v1 · bridge offline"
- * (spec §15.2, robot tab 1).
+ * "draft newer than published", "published v2 · applied v1 · bridge offline".
  */
 export const configState = z.object({
     published_version: z.number().int().positive().nullable(),