@fleetless/contracts 1.0.0 → 1.0.3

package/dist/config-issues.d.ts

@@ -1,19 +1,18 @@
+// SPDX-License-Identifier: Apache-2.0
 import { z } from 'zod';
 import type { ValidationIssue } from './config.js';
 /**
  * What is wrong with a configuration document, in one account.
  *
- * Everything here used to live in `cloud/src/validation.ts`. It is in
- * contracts because the console has to say **exactly** what the server says
- * about a document — same codes, same sentences, same paths — and the only
- * way that is true is if it is the same code. A console that reimplemented
- * this and then disagreed with the server about what is wrong would be worse
- * than a console that said nothing (spec D3).
- *
- * **The second door D3 forbids existed for one wave, and closed in wave 2
- * task 8** (cloud `a307e18`, 2026-09-03). The cloud cannot import a specifier
- * it has not pinned, so its own copy of `schemaIssues`, `refusal`, `slugOf`,
- * `formatPath` and `valueAt` stood from wave 1, when this module landed here,
+ * It lives in contracts because an editor has to say **exactly** what the
+ * server says about a document — same codes, same sentences, same paths — and
+ * the only way that is true is if it is the same code. An editor that
+ * reimplemented this and then disagreed with the server about what is wrong
+ * would be worse than one that said nothing.
+ *
+ * **A second implementation is the thing this module exists to prevent.** A
+ * server that cannot import this package keeps its own copy of `schemaIssues`,
+ * `refusal`, `slugOf`, `formatPath` and `valueAt`,
  * until that re-pin deleted them and imported these. The window is recorded
  * rather than dropped because it cost a live bug while it was open: the
  * cloud's own `formatPath` wrote a blank path segment as the empty string,
@@ -41,17 +40,16 @@ export declare const DOCUMENT_ROOT_PATH = "(document)";
  * `messages:` is deliberately not among them: its names are their own
  * namespace.
  *
- * `cloud/src/config-sections.ts` re-exports this constant and drives the
- * cloud's iteration over sections from it; the console reads it directly
- * (`useConfigRepairs.ts`). It was spelled out separately in all three until
- * wave 2 task 8 (cloud `a307e18`, 2026-09-03) — this is the only spelling
+ * The cloud re-exports this constant and drives its iteration over sections
+ * from it; an editor reads it directly. Spelling it out separately in each
+ * would be three copies — this is the only spelling
  * since.
  */
 export declare const EXPOSURE_SECTIONS: readonly ["datapoints", "actions", "services", "publishers", "cameras"];
 export type ExposureSection = (typeof EXPOSURE_SECTIONS)[number];
 /**
  * The refusals `robotConfigDoc` already made, reported as validation issues
- * with their FL-002 codes.
+ * with the format's own codes.
  *
  * **This maps; it does not re-decide.** Seven of the thirteen codes are
  * answered by the schema before a document ever becomes a `RobotConfigDoc`,
@@ -72,8 +70,8 @@ export type ExposureSection = (typeof EXPOSURE_SECTIONS)[number];
  *   sentence differs at the document root, where there is no key to remove:
  *   see `EMPTY_DOCUMENT_MESSAGE`.
  *
- * Everything else keeps zod's own code. Those are refusals with no FL-002
- * code — a reversed `min_value`/`max_value` pair, a section over its cap, a
+ * Everything else keeps zod's own code. Those are refusals the format names no
+ * code for — a reversed `min_value`/`max_value` pair, a section over its cap, a
  * key that is not a slug — and inventing a fourteenth code for them would put
  * a code on the wire that no table documents.
  */
@@ -89,10 +87,10 @@ export declare function schemaIssues(value: unknown, issues: readonly SchemaIssu
  * width. Rendered bare, such a key produced a path a reader cannot act
  * on — and at the root it produced the empty string, which
  * `validationIssue.path` (`z.string().min(1)`) refuses. That was the cloud
- * publishing a finding that fails the cloud's own contract for findings, and
- * after D2 stored the draft it cost the whole `configDraftResponse`, not one
- * issue: the console's `safeParse` dropped the response and handed the editor
- * nothing, for two characters typed.
+ * publishing a finding that fails its own contract for findings, and because a
+ * draft that does not parse is stored rather than refused it costs the whole
+ * `configDraftResponse`, not one issue: a client's `safeParse` drops the
+ * response and hands the editor nothing, for two characters typed.
  *
  * The quoted spelling is the segment's JSON string literal, and that is the
  * whole of the reason for choosing it: JSON's string syntax is a subset of
@@ -125,9 +123,9 @@ export declare function formatPath(path: readonly PropertyKey[]): string;
  *
  * Escaping on the way out was the alternative and was rejected: `path` is a
  * wire field (`validationIssue.path`), it is rendered to developers as-is,
- * and every recorded expectation in this repo and the cloud's spells it
- * unescaped. Changing what the server says about every document to make one
- * console lookup total is the larger of the two costs.
+ * and every recorded expectation on both sides spells it unescaped. Changing
+ * what the server says about every document to make one client-side lookup
+ * total is the larger of the two costs.
  *
  * So the property this has, and the one its test asserts, is the narrow one:
  * **a path round-trips when no string segment contains `.` or `[`, and the

package/dist/config-issues.js

@@ -1,3 +1,4 @@
+// SPDX-License-Identifier: Apache-2.0
 /** What a path with no segments at all is called, since `path` may not be empty. */
 export const DOCUMENT_ROOT_PATH = '(document)';
 /**
@@ -6,16 +7,15 @@ export const DOCUMENT_ROOT_PATH = '(document)';
  * `messages:` is deliberately not among them: its names are their own
  * namespace.
  *
- * `cloud/src/config-sections.ts` re-exports this constant and drives the
- * cloud's iteration over sections from it; the console reads it directly
- * (`useConfigRepairs.ts`). It was spelled out separately in all three until
- * wave 2 task 8 (cloud `a307e18`, 2026-09-03) — this is the only spelling
+ * The cloud re-exports this constant and drives its iteration over sections
+ * from it; an editor reads it directly. Spelling it out separately in each
+ * would be three copies — this is the only spelling
  * since.
  */
 export const EXPOSURE_SECTIONS = ['datapoints', 'actions', 'services', 'publishers', 'cameras'];
 /**
  * The refusals `robotConfigDoc` already made, reported as validation issues
- * with their FL-002 codes.
+ * with the format's own codes.
  *
  * **This maps; it does not re-decide.** Seven of the thirteen codes are
  * answered by the schema before a document ever becomes a `RobotConfigDoc`,
@@ -36,8 +36,8 @@ export const EXPOSURE_SECTIONS = ['datapoints', 'actions', 'services', 'publishe
  *   sentence differs at the document root, where there is no key to remove:
  *   see `EMPTY_DOCUMENT_MESSAGE`.
  *
- * Everything else keeps zod's own code. Those are refusals with no FL-002
- * code — a reversed `min_value`/`max_value` pair, a section over its cap, a
+ * Everything else keeps zod's own code. Those are refusals the format names no
+ * code for — a reversed `min_value`/`max_value` pair, a section over its cap, a
  * key that is not a slug — and inventing a fourteenth code for them would put
  * a code on the wire that no table documents.
  */
@@ -69,9 +69,9 @@ const NULL_KEY_MESSAGE = 'This key is null. Omission is the only spelling of "no
  * a genuine `invalid_type` on `null` at the empty path, so the code is right —
  * but the sentence for a null *key* told the developer to remove a key that
  * does not exist, and "select all, delete" is the commonest way anybody gets
- * here. Since FL-005 D2 stores the draft rather than refusing it, that
- * sentence is what the FINDINGS panel shows persistently for an emptied
- * editor, where it used to ride a one-shot 422 nobody read.
+ * here. A draft that does not parse is stored rather than refused, so this
+ * sentence is what an editor's findings panel shows persistently for an emptied
+ * document rather than a one-shot refusal nobody reads.
  *
  * It names the smallest legal document rather than only saying what is wrong,
  * because at this path there is no line to jump to and no repair to offer —
@@ -106,10 +106,10 @@ function slugOf(path) {
  * width. Rendered bare, such a key produced a path a reader cannot act
  * on — and at the root it produced the empty string, which
  * `validationIssue.path` (`z.string().min(1)`) refuses. That was the cloud
- * publishing a finding that fails the cloud's own contract for findings, and
- * after D2 stored the draft it cost the whole `configDraftResponse`, not one
- * issue: the console's `safeParse` dropped the response and handed the editor
- * nothing, for two characters typed.
+ * publishing a finding that fails its own contract for findings, and because a
+ * draft that does not parse is stored rather than refused it costs the whole
+ * `configDraftResponse`, not one issue: a client's `safeParse` drops the
+ * response and hands the editor nothing, for two characters typed.
  *
  * The quoted spelling is the segment's JSON string literal, and that is the
  * whole of the reason for choosing it: JSON's string syntax is a subset of
@@ -198,9 +198,9 @@ function isBlank(segment) {
  *
  * Escaping on the way out was the alternative and was rejected: `path` is a
  * wire field (`validationIssue.path`), it is rendered to developers as-is,
- * and every recorded expectation in this repo and the cloud's spells it
- * unescaped. Changing what the server says about every document to make one
- * console lookup total is the larger of the two costs.
+ * and every recorded expectation on both sides spells it unescaped. Changing
+ * what the server says about every document to make one client-side lookup
+ * total is the larger of the two costs.
  *
  * So the property this has, and the one its test asserts, is the narrow one:
  * **a path round-trips when no string segment contains `.` or `[`, and the

package/dist/config.d.ts

@@ -1,34 +1,29 @@
+// SPDX-License-Identifier: Apache-2.0
 import { z } from 'zod';
 /**
- * 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 declare const serviceDescription: z.ZodOptional<z.ZodString>;
 /**
@@ -134,7 +129,7 @@ export declare const parameterMap: z.ZodRecord<z.ZodString, z.ZodObject<{
     description: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>>;
 /**
- * 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.
  *
@@ -147,12 +142,12 @@ export declare const parameterMap: z.ZodRecord<z.ZodString, z.ZodObject<{
  * 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,
@@ -367,10 +362,9 @@ export declare const messageBody: z.ZodUnknown;
  * 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
@@ -390,7 +384,7 @@ export declare function placeholderNames(node: unknown, found?: Set<string>): Se
  */
 export declare const messageMap: z.ZodRecord<z.ZodString, z.ZodUnknown>;
 /**
- * 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.
  */
@@ -426,7 +420,7 @@ export declare const actionConfig: z.ZodObject<{
     description: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>;
 export type ActionConfig = z.infer<typeof actionConfig>;
-/** A ROS service call with validated parameters (spec §4.2). */
+/** A ROS service call with validated parameters. */
 export declare const serviceConfig: z.ZodObject<{
     ros_name: z.ZodString;
     type: z.ZodString;
@@ -565,20 +559,20 @@ export type CameraSource = z.infer<typeof cameraSource>;
  *
  * 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 declare const snapshotIntervalSeconds: z.ZodNumber;
 /**
- * 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
@@ -635,7 +629,7 @@ export declare const FLEETLESS_FORMAT_VERSION = 1;
  * 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.
  */
@@ -816,12 +810,12 @@ export declare const robotConfigDoc: z.ZodObject<{
 }, z.core.$strict>;
 export type RobotConfigDoc = z.infer<typeof robotConfigDoc>;
 /**
- * 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 declare const validationIssue: z.ZodObject<{
     path: z.ZodString;
@@ -836,8 +830,7 @@ export declare const validationIssue: z.ZodObject<{
 export type ValidationIssue = z.infer<typeof validationIssue>;
 /**
  * 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 declare const configState: z.ZodObject<{
     published_version: z.ZodNullable<z.ZodNumber>;