@fleetless/contracts 1.0.0

package/dist/common.d.ts

@@ -0,0 +1,186 @@
+import { z } from 'zod';
+/**
+ * Names shared by every layer: the Fleetless slug and the ROS names it is
+ * deliberately decoupled from (spec §4.1).
+ *
+ * They live here rather than in `protocol.ts` so the exposure model
+ * (`config.ts`) and the bridge protocol can both use them without importing
+ * each other.
+ *
+ * ## Each grammar's sentence lives beside its pattern
+ *
+ * A developer whose topic name was wrong used to be shown the regular
+ * expression that refused it. The four `*_RULE` constants below are the
+ * sentences that replace it — one per grammar rather than one per field,
+ * because the message explains why the *pattern* said no, and the same pattern
+ * says no for the same reason wherever it appears.
+ *
+ * Each is used **twice**: as the message zod itself produces, here, and as
+ * `patternErrorMessage` in `config.ts`'s exported JSON Schema, which is a
+ * published artifact that other tools validate against and that a person
+ * reads. Under FL-005 D3 nothing will consume `patternErrorMessage` at runtime
+ * **once wave 3 lands** — `useMonacoYaml.ts` still passes `validate: true`
+ * today, so until then this sentence IS the live diagnostic in the editor and
+ * zod's is the live one on the server. Either way it is a second spelling of a
+ * live rule, and an unwatched one would drift word for word,
+ * forever and invisibly — the shape that had `buildAcceptUrl` mailing one URL
+ * three ways. They are therefore one constant with two readers rather than two
+ * strings that happen to agree, and `config-zod-messages.test.ts` asserts the
+ * two readings are the same string at all 24 pattern positions the document
+ * has.
+ *
+ * **They are exported because the pattern and its sentence must not be able to
+ * move apart**, and the pattern is here while the schema annotation is in
+ * `config.ts`. The three grammars that exist only inside a configuration
+ * document — the two URL schemes and the capture-device path — are constants in
+ * `config.ts` beside their own patterns, on the same rule.
+ *
+ * **The blast radius of putting the sentence here was measured, and it is
+ * zero artifacts.** A `.meta()` on `slug` would reach 42 of the 159 published
+ * schema artifacts, the bridge's vendored protocol frames among them — which is
+ * why `mapKey` in `config.ts` carries the annotation and `slug` does not. A
+ * message on a `.regex()` check is a different thing: zod renders no error
+ * message into JSON Schema at all, so every artifact is byte-identical either
+ * way (measured across all 278 barrel schemas under both `io` modes,
+ * 2026-09-03). What it does reach is the sentence a *parser* produces, in every
+ * layer that parses one of these names — which is the improvement, not a cost.
+ */
+export declare const SLUG_RULE = "A name is lower-case: it starts with a letter, continues with letters and digits, and joins further words with a single underscore \u2014 `battery_voltage`. Capitals, dashes, dots, spaces, a leading digit and a doubled or trailing underscore are all refused.";
+/**
+ * A name: a slug for an exposed service or datapoint, a parameter name, a
+ * message name. Lowercase, underscore-separated, letter-initial, 2..63
+ * characters, no leading/trailing/doubled underscores.
+ *
+ * Names are stable and decoupled from ROS names (spec §4.1) — renaming a
+ * topic on the robot must never break a client app. The reverse also holds
+ * and costs more: changing a name breaks every client, role grant and MCP
+ * tool name that uses it.
+ */
+export declare const slug: z.ZodString;
+export declare const ROS_NAME_RULE = "A ROS graph name is absolute: it begins with a slash, and each segment after a slash starts with a letter or an underscore and continues with letters, digits and underscores \u2014 `/camera/image_raw`. A relative name, a trailing slash, a dash or a dot is refused.";
+/**
+ * A fully qualified ROS graph name: absolute, slash-separated, each segment
+ * letter- or underscore-initial. Relative names are refused — the bridge
+ * would have to resolve them against a namespace the cloud cannot see.
+ */
+export declare const rosName: z.ZodString;
+export declare const ROS_TYPE_NAME_RULE = "A ROS 2 type name has three segments: the package, then `msg`, `srv` or `action`, then the type \u2014 `sensor_msgs/msg/BatteryState`, `std_srvs/srv/Trigger`, `nav2_msgs/action/NavigateToPose`. The middle segment is the one usually left out. The package is lower-case with underscores; the type itself is letters and digits, conventionally CamelCase.";
+/**
+ * A ROS interface type as ROS 2 spells it: `pkg/msg/Type`, `pkg/srv/Type`,
+ * `pkg/action/Type`. W2 resolves field trees for `msg` only (§4.5); the
+ * other two are listed by the introspection browser and get their trees in
+ * W4, where action and service parameters exist.
+ */
+export declare const rosTypeName: z.ZodString;
+export declare const FIELD_PATH_RULE = "A field path is dotted and lower-case, and each segment may index at most one array level \u2014 `voltage`, `pose.position.x`, `ranges[0]`. ROS 2 has no nested arrays, so a second index on one segment could name nothing that exists.";
+/**
+ * A path into a message: dot-separated field names, each carrying **at most
+ * one** array index, e.g. `percentage`, `pose.position.x`, `ranges[0]`,
+ * `poses[0].pose.position.x`. `null` in a datapoint config means *the whole
+ * message* (spec §4.2: one field or one whole topic — never several topics).
+ *
+ * One index per segment is not a preference but the shape of the target: ROS 2
+ * IDL has `float64[]`, `float64[3]` and `float64[<=10]`, and no nested or
+ * multi-dimensional arrays at all. A second index on one segment — `a[0][1]` —
+ * could therefore denote nothing on any message that exists. The bridge has
+ * always refused it (`sampling.py`'s `FieldPathError`, *"ROS has no nested
+ * arrays"*); this grammar said otherwise until FL-004, so a hand-written or
+ * AI-generated document could pass the cloud and then fail at the robot as a
+ * `config_applied` error — the latest and worst place to learn it.
+ */
+export declare const fieldPath: z.ZodString;
+/**
+ * A unix-millisecond instant as a **query string** actually carries it, bounded
+ * to years 1..9999.
+ *
+ * The union's input branch **is the wire** — a `z.coerce` cannot be published,
+ * because zod renders the coercion's result in either `io` direction, so the
+ * artifact would describe a shape a query string can never carry (DEF-059).
+ *
+ * The year bound is borrowed rather than invented: `nonnegative()` alone let
+ * `253402300800000` through, where the Postgres bind path has no representation
+ * and the route answered 500 — measured either side of the edge,
+ * `253402300799000` -> 200 and `253402300800000` -> 500 (Argus-W9). This moved
+ * here from `audit.ts` when `jobRunQuery` needed the same guard; a second copy
+ * would have been a second policy for one decision.
+ */
+/**
+ * A `seq` cursor as a **query string** actually carries it.
+ *
+ * The regex admits 19 digits, which is wider than a JavaScript number can
+ * represent — `Number('9999999999999999999')` is `1e19`. That is safe, and
+ * for a reason worth writing down rather than re-deriving: **zod 4's `.int()`
+ * bounds the safe-integer range**, so such a value is refused here with a
+ * `too_big` issue and the route answers 400. It never reaches Postgres as an
+ * out-of-range `bigint`, and no extra `.max()` is needed — one that merely
+ * restated `.int()` would be a second policy for one decision.
+ *
+ * Lives here because `auditQuery` and `jobRunQuery` had this **twice**, which
+ * is how the newer copy ends up the weaker one.
+ *
+ * **What the published artifact does not say:** zod renders a
+ * `.transform().pipe()` from its *input* branch, so the JSON Schema shows the
+ * union and none of the constraints below it — a generated client reading it
+ * would believe `-5` is acceptable. The runtime is the authority for this
+ * field; the artifact describes only what the wire may carry.
+ */
+export declare const wireSeqCursor: z.ZodPipe<z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>, z.ZodTransform<number, string | number>>, z.ZodNumber>;
+export declare const wireTimestampMs: z.ZodPipe<z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>, z.ZodTransform<number, string | number>>, z.ZodNumber>;
+/**
+ * Which kind of exposure failed to apply. Known at every one of the bridge's five apply call sites.
+ *
+ * Lives here, not in `protocol.ts`, for the same reason `slug` and friends
+ * do: `config.ts`'s `configState.applied_errors` is the REST shape the
+ * console reads this same error through (spec `2026-08-21-exposure-and-revoke-design`
+ * D4), and `protocol.ts` already imports from `config.ts`
+ * (`credentialRef`, `robotConfigDoc`) — so `config.ts` importing back from
+ * `protocol.ts` would be a cycle. One definition, reachable from both
+ * without either importing the other.
+ */
+export declare const applyErrorKind: z.ZodEnum<{
+    datapoint: "datapoint";
+    action: "action";
+    service: "service";
+    publisher: "publisher";
+    camera: "camera";
+}>;
+export type ApplyErrorKind = z.infer<typeof applyErrorKind>;
+/**
+ * One thing that did not apply — carried on the wire by
+ * `protocol.ts`'s `bridgeConfigApplied.errors` and read back by the console
+ * through `config.ts`'s `configState.applied_errors`. **One definition**:
+ * `configState` used to declare its own narrower `{ slug, message }` copy,
+ * which silently stripped `kind`, `code` and `details` on every read —
+ * exactly the shape of bug this file's own module comment warns about,
+ * found only once the plan's console task tried to render the fields that
+ * were never there.
+ *
+ * `slug` is the exposure's slug, or `*` when a whole kind failed before any
+ * individual slug was reached (`client.py`'s `_apply_or_report` catch) — which
+ * means something different from every other error: not "this slug is wrong"
+ * but "this kind was not applied at all and its slugs are in an unknown state".
+ *
+ * **`code` is a bounded string and not a `z.enum`, deliberately**, following
+ * `cloudHelloError.code`. An enum would make every future bridge
+ * classification a protocol change on both sides; a string lets the bridge
+ * learn to classify without the cloud being taught first, and the cloud renders
+ * what it knows and passes the rest through. The codes the bridge produces
+ * today are `field_path_invalid`, `whole_kind_failed` and `unknown`.
+ *
+ * `details` carries whatever a classifier has to add. **Nothing redacts it** —
+ * the same rule `auditEvent.details` states.
+ */
+export declare const applyError: z.ZodObject<{
+    slug: z.ZodString;
+    kind: z.ZodEnum<{
+        datapoint: "datapoint";
+        action: "action";
+        service: "service";
+        publisher: "publisher";
+        camera: "camera";
+    }>;
+    code: z.ZodString;
+    message: z.ZodString;
+    details: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+export type ApplyError = z.infer<typeof applyError>;

package/dist/common.js

@@ -0,0 +1,199 @@
+// SPDX-License-Identifier: Apache-2.0
+import { z } from 'zod';
+/**
+ * Names shared by every layer: the Fleetless slug and the ROS names it is
+ * deliberately decoupled from (spec §4.1).
+ *
+ * They live here rather than in `protocol.ts` so the exposure model
+ * (`config.ts`) and the bridge protocol can both use them without importing
+ * each other.
+ *
+ * ## Each grammar's sentence lives beside its pattern
+ *
+ * A developer whose topic name was wrong used to be shown the regular
+ * expression that refused it. The four `*_RULE` constants below are the
+ * sentences that replace it — one per grammar rather than one per field,
+ * because the message explains why the *pattern* said no, and the same pattern
+ * says no for the same reason wherever it appears.
+ *
+ * Each is used **twice**: as the message zod itself produces, here, and as
+ * `patternErrorMessage` in `config.ts`'s exported JSON Schema, which is a
+ * published artifact that other tools validate against and that a person
+ * reads. Under FL-005 D3 nothing will consume `patternErrorMessage` at runtime
+ * **once wave 3 lands** — `useMonacoYaml.ts` still passes `validate: true`
+ * today, so until then this sentence IS the live diagnostic in the editor and
+ * zod's is the live one on the server. Either way it is a second spelling of a
+ * live rule, and an unwatched one would drift word for word,
+ * forever and invisibly — the shape that had `buildAcceptUrl` mailing one URL
+ * three ways. They are therefore one constant with two readers rather than two
+ * strings that happen to agree, and `config-zod-messages.test.ts` asserts the
+ * two readings are the same string at all 24 pattern positions the document
+ * has.
+ *
+ * **They are exported because the pattern and its sentence must not be able to
+ * move apart**, and the pattern is here while the schema annotation is in
+ * `config.ts`. The three grammars that exist only inside a configuration
+ * document — the two URL schemes and the capture-device path — are constants in
+ * `config.ts` beside their own patterns, on the same rule.
+ *
+ * **The blast radius of putting the sentence here was measured, and it is
+ * zero artifacts.** A `.meta()` on `slug` would reach 42 of the 159 published
+ * schema artifacts, the bridge's vendored protocol frames among them — which is
+ * why `mapKey` in `config.ts` carries the annotation and `slug` does not. A
+ * message on a `.regex()` check is a different thing: zod renders no error
+ * message into JSON Schema at all, so every artifact is byte-identical either
+ * way (measured across all 278 barrel schemas under both `io` modes,
+ * 2026-09-03). What it does reach is the sentence a *parser* produces, in every
+ * layer that parses one of these names — which is the improvement, not a cost.
+ */
+export const SLUG_RULE = 'A name is lower-case: it starts with a letter, continues with letters and digits, and joins further words with a single underscore — `battery_voltage`. Capitals, dashes, dots, spaces, a leading digit and a doubled or trailing underscore are all refused.';
+/**
+ * A name: a slug for an exposed service or datapoint, a parameter name, a
+ * message name. Lowercase, underscore-separated, letter-initial, 2..63
+ * characters, no leading/trailing/doubled underscores.
+ *
+ * Names are stable and decoupled from ROS names (spec §4.1) — renaming a
+ * topic on the robot must never break a client app. The reverse also holds
+ * and costs more: changing a name breaks every client, role grant and MCP
+ * tool name that uses it.
+ */
+export const slug = z
+    .string()
+    .min(2)
+    .max(63)
+    .regex(/^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$/, SLUG_RULE);
+export const ROS_NAME_RULE = 'A ROS graph name is absolute: it begins with a slash, and each segment after a slash starts with a letter or an underscore and continues with letters, digits and underscores — `/camera/image_raw`. A relative name, a trailing slash, a dash or a dot is refused.';
+/**
+ * A fully qualified ROS graph name: absolute, slash-separated, each segment
+ * letter- or underscore-initial. Relative names are refused — the bridge
+ * would have to resolve them against a namespace the cloud cannot see.
+ */
+export const rosName = z
+    .string()
+    .max(255)
+    .regex(/^\/[A-Za-z_][A-Za-z0-9_]*(?:\/[A-Za-z_][A-Za-z0-9_]*)*$/, ROS_NAME_RULE);
+export const ROS_TYPE_NAME_RULE = 'A ROS 2 type name has three segments: the package, then `msg`, `srv` or `action`, then the type — `sensor_msgs/msg/BatteryState`, `std_srvs/srv/Trigger`, `nav2_msgs/action/NavigateToPose`. The middle segment is the one usually left out. The package is lower-case with underscores; the type itself is letters and digits, conventionally CamelCase.';
+/**
+ * A ROS interface type as ROS 2 spells it: `pkg/msg/Type`, `pkg/srv/Type`,
+ * `pkg/action/Type`. W2 resolves field trees for `msg` only (§4.5); the
+ * other two are listed by the introspection browser and get their trees in
+ * W4, where action and service parameters exist.
+ */
+export const rosTypeName = z
+    .string()
+    .max(255)
+    .regex(/^[a-z][a-z0-9_]*\/(?:msg|srv|action)\/[A-Za-z][A-Za-z0-9]*$/, ROS_TYPE_NAME_RULE);
+export const FIELD_PATH_RULE = 'A field path is dotted and lower-case, and each segment may index at most one array level — `voltage`, `pose.position.x`, `ranges[0]`. ROS 2 has no nested arrays, so a second index on one segment could name nothing that exists.';
+/**
+ * A path into a message: dot-separated field names, each carrying **at most
+ * one** array index, e.g. `percentage`, `pose.position.x`, `ranges[0]`,
+ * `poses[0].pose.position.x`. `null` in a datapoint config means *the whole
+ * message* (spec §4.2: one field or one whole topic — never several topics).
+ *
+ * One index per segment is not a preference but the shape of the target: ROS 2
+ * IDL has `float64[]`, `float64[3]` and `float64[<=10]`, and no nested or
+ * multi-dimensional arrays at all. A second index on one segment — `a[0][1]` —
+ * could therefore denote nothing on any message that exists. The bridge has
+ * always refused it (`sampling.py`'s `FieldPathError`, *"ROS has no nested
+ * arrays"*); this grammar said otherwise until FL-004, so a hand-written or
+ * AI-generated document could pass the cloud and then fail at the robot as a
+ * `config_applied` error — the latest and worst place to learn it.
+ */
+export const fieldPath = z
+    .string()
+    .max(255)
+    .regex(/^[a-z_][a-z0-9_]*(?:\[\d+\])?(?:\.[a-z_][a-z0-9_]*(?:\[\d+\])?)*$/, FIELD_PATH_RULE);
+/**
+ * A unix-millisecond instant as a **query string** actually carries it, bounded
+ * to years 1..9999.
+ *
+ * The union's input branch **is the wire** — a `z.coerce` cannot be published,
+ * because zod renders the coercion's result in either `io` direction, so the
+ * artifact would describe a shape a query string can never carry (DEF-059).
+ *
+ * The year bound is borrowed rather than invented: `nonnegative()` alone let
+ * `253402300800000` through, where the Postgres bind path has no representation
+ * and the route answered 500 — measured either side of the edge,
+ * `253402300799000` -> 200 and `253402300800000` -> 500 (Argus-W9). This moved
+ * here from `audit.ts` when `jobRunQuery` needed the same guard; a second copy
+ * would have been a second policy for one decision.
+ */
+/**
+ * A `seq` cursor as a **query string** actually carries it.
+ *
+ * The regex admits 19 digits, which is wider than a JavaScript number can
+ * represent — `Number('9999999999999999999')` is `1e19`. That is safe, and
+ * for a reason worth writing down rather than re-deriving: **zod 4's `.int()`
+ * bounds the safe-integer range**, so such a value is refused here with a
+ * `too_big` issue and the route answers 400. It never reaches Postgres as an
+ * out-of-range `bigint`, and no extra `.max()` is needed — one that merely
+ * restated `.int()` would be a second policy for one decision.
+ *
+ * Lives here because `auditQuery` and `jobRunQuery` had this **twice**, which
+ * is how the newer copy ends up the weaker one.
+ *
+ * **What the published artifact does not say:** zod renders a
+ * `.transform().pipe()` from its *input* branch, so the JSON Schema shows the
+ * union and none of the constraints below it — a generated client reading it
+ * would believe `-5` is acceptable. The runtime is the authority for this
+ * field; the artifact describes only what the wire may carry.
+ */
+export const wireSeqCursor = z
+    .union([z.string().regex(/^\d{1,19}$/), z.number().int()])
+    .transform((v) => Number(v))
+    .pipe(z.number().int().positive());
+export const wireTimestampMs = z
+    .union([z.string().regex(/^\d{1,15}$/), z.number().int()])
+    .transform((v) => Number(v))
+    .pipe(z
+    .number()
+    .int()
+    .nonnegative()
+    .refine((ms) => {
+    const year = new Date(ms).getUTCFullYear();
+    return Number.isFinite(year) && year >= 1 && year <= 9999;
+}, 'must fall within years 1..9999'));
+/**
+ * Which kind of exposure failed to apply. Known at every one of the bridge's five apply call sites.
+ *
+ * Lives here, not in `protocol.ts`, for the same reason `slug` and friends
+ * do: `config.ts`'s `configState.applied_errors` is the REST shape the
+ * console reads this same error through (spec `2026-08-21-exposure-and-revoke-design`
+ * D4), and `protocol.ts` already imports from `config.ts`
+ * (`credentialRef`, `robotConfigDoc`) — so `config.ts` importing back from
+ * `protocol.ts` would be a cycle. One definition, reachable from both
+ * without either importing the other.
+ */
+export const applyErrorKind = z.enum(['datapoint', 'action', 'service', 'publisher', 'camera']);
+/**
+ * One thing that did not apply — carried on the wire by
+ * `protocol.ts`'s `bridgeConfigApplied.errors` and read back by the console
+ * through `config.ts`'s `configState.applied_errors`. **One definition**:
+ * `configState` used to declare its own narrower `{ slug, message }` copy,
+ * which silently stripped `kind`, `code` and `details` on every read —
+ * exactly the shape of bug this file's own module comment warns about,
+ * found only once the plan's console task tried to render the fields that
+ * were never there.
+ *
+ * `slug` is the exposure's slug, or `*` when a whole kind failed before any
+ * individual slug was reached (`client.py`'s `_apply_or_report` catch) — which
+ * means something different from every other error: not "this slug is wrong"
+ * but "this kind was not applied at all and its slugs are in an unknown state".
+ *
+ * **`code` is a bounded string and not a `z.enum`, deliberately**, following
+ * `cloudHelloError.code`. An enum would make every future bridge
+ * classification a protocol change on both sides; a string lets the bridge
+ * learn to classify without the cloud being taught first, and the cloud renders
+ * what it knows and passes the rest through. The codes the bridge produces
+ * today are `field_path_invalid`, `whole_kind_failed` and `unknown`.
+ *
+ * `details` carries whatever a classifier has to add. **Nothing redacts it** —
+ * the same rule `auditEvent.details` states.
+ */
+export const applyError = z.object({
+    slug: z.string(),
+    kind: applyErrorKind,
+    code: z.string().min(1).max(40),
+    message: z.string().min(1),
+    details: z.record(z.string(), z.unknown()).optional(),
+});

package/dist/config-issues.d.ts

@@ -0,0 +1,175 @@
+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,
+ * 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,
+ * which `validationIssue.path`'s `min(1)` refuses, so a draft containing
+ * `"": 3` rode a 200 whose whole body the console's `safeParse` then dropped.
+ * Anything else that lands in contracts ahead of its consumer's pin opens the
+ * same window.
+ */
+/**
+ * One zod issue.
+ *
+ * Zod's own issue union, not a structural restatement of it. The cloud's
+ * copy described the shape by hand because the cloud has no `zod` dependency
+ * of its own — it reaches every schema through this package. Here zod *is* a
+ * dependency, and a hand-written shape that drifts from the real one would
+ * be a second account of the same thing, on the module whose whole point is
+ * that there is one.
+ */
+export type SchemaIssue = z.core.$ZodIssue;
+/** What a path with no segments at all is called, since `path` may not be empty. */
+export declare const DOCUMENT_ROOT_PATH = "(document)";
+/**
+ * The five sections whose keys are slugs — one namespace across all of them,
+ * which is what lets a role grant say `{robot, slug}` without naming a kind.
+ * `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
+ * 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.
+ *
+ * **This maps; it does not re-decide.** Seven of the thirteen codes are
+ * answered by the schema before a document ever becomes a `RobotConfigDoc`,
+ * and `config.ts` attaches `params: { code }` at each site for exactly this —
+ * its header lists which codes it decides and which it defers. Reading
+ * `params.code` is also the only stable join: the prose of a message is not a
+ * contract and matching on it is a join nobody notices breaking.
+ *
+ * Two refusals carry no `params.code` and are recognised by zod's own issue
+ * code instead, which the same header says consumers should do:
+ *
+ * - `unrecognized_keys` is `unknown_key`. One issue per key, so the path
+ *   names the offending key rather than its parent.
+ * - `invalid_type` **where the value at that path is `null`** is
+ *   `explicit_null`. The condition is checked against the parsed value and
+ *   not against the message, which says "received null" — see above. Zod 4
+ *   does not carry the input on the issue, so the value is navigated to. The
+ *   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
+ * key that is not a slug — and inventing a fourteenth code for them would put
+ * a code on the wire that no table documents.
+ */
+export declare function schemaIssues(value: unknown, issues: readonly SchemaIssue[]): ValidationIssue[];
+/**
+ * `['datapoints','a','enum',0]` -> `datapoints.a.enum[0]`, the spelling every
+ * other path here uses.
+ *
+ * **A segment that would render as nothing is written quoted instead.** The
+ * last segment of an `unrecognized_keys` or `invalid_key` path is a key the
+ * *developer* wrote, and YAML lets that key be empty (`"": 3`), nothing but
+ * whitespace, or — see `isBlank` — nothing but characters that occupy no
+ * 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.
+ *
+ * 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
+ * YAML's double-quoted scalar syntax, so `""`, `" "` and `"\t"` are each a
+ * valid YAML spelling of exactly the key being complained about. The path is
+ * therefore text the developer can search their own file for — which is the
+ * bar this has to clear. It is also the same move `DOCUMENT_ROOT_PATH` makes
+ * for the no-segments case, one level down: give the invisible thing a name.
+ *
+ * **Only blank segments are quoted.** A segment containing `.` or `[` is
+ * still written bare, so it still cannot be read back — see
+ * `splitFormatPath`, which documents why escaping those was rejected. That
+ * decision is unchanged here on purpose: those paths are wrong for one
+ * console lookup, these were wrong on the wire.
+ */
+export declare function formatPath(path: readonly PropertyKey[]): string;
+/**
+ * `formatPath` read back — `datapoints.a.enum[0]` -> `['datapoints','a','enum',0]`.
+ *
+ * It exists because two console call sites split an issue path on `.` alone
+ * while the cloud writes sequence indices in brackets, so `ranges[0]` reached
+ * a document lookup as one segment that matches no key.
+ *
+ * **It is not the inverse of `formatPath`, and must not be read as one.**
+ * `formatPath` writes `.` and `[n]` as structure and escapes nothing, so a
+ * name that contains either is indistinguishable afterwards from the
+ * structure it looks like. This is reachable, not theoretical: an
+ * `unrecognized_keys` path ends in a key the **developer** chose, and YAML
+ * lets that key be `a.b` or `ranges[0]`.
+ *
+ * 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.
+ *
+ * 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
+ * path is not the single segment `(document)`.** Outside that, the split is a
+ * best guess. What it costs is bounded — the console uses the result to find
+ * a line to put a marker on, so a wrong split finds no line and the marker is
+ * not placed. It never makes the console assert something false about the
+ * document.
+ *
+ * A **blank** segment is inside that property rather than outside it, and
+ * that is new. `formatPath` used to drop an empty first segment entirely
+ * (`formatPath(['', 'a'])` was `'a'`, a path naming a different key) and to
+ * write a nested one as a trailing `.`; at the root it produced the empty
+ * string, which `validationIssue.path`'s `min(1)` refuses outright. It now
+ * quotes blank segments, and `unquoteBlank` reads them back, so `['']`,
+ * `[' ']` and `['datapoints', 'battery_soc', '']` all round-trip. The single
+ * new non-round-trip that buys is a key literally spelled with quote marks
+ * around whitespace.
+ */
+export declare function splitFormatPath(path: string): Array<string | number>;
+/**
+ * A stable hash of a schema object, for asking *is the thing running the one
+ * I think it is?*
+ *
+ * Wave 5's browser sweep enumerates positions against a schema it holds and
+ * has to know that the editor is running the same one; the manifest that
+ * makes a schema-side change announce itself uses the same number as its
+ * baseline. Both are the same question, so there is one implementation of it:
+ * a second one on the sweep side would drift, and the gate would then go red
+ * for the drift rather than for the schema.
+ *
+ * Canonical JSON first — object keys sorted at every depth, so a re-ordered
+ * `meta()` block is not a change — then FNV-1a over the result, 64 bits as
+ * 16 hex characters. Sorting is done through the `JSON.stringify` replacer,
+ * which also means a cyclic input throws the engine's own "converting
+ * circular structure" TypeError rather than hanging.
+ *
+ * **Named residual: this is a change detector, not a digest.** FNV-1a is not
+ * a cryptographic hash and a collision can be constructed on purpose. It is
+ * asked *did this object change since the baseline was recorded*, by the
+ * people who wrote both; nothing here defends against someone choosing the
+ * input. `crypto.subtle` would be the answer to the other question and is
+ * async, which a `data-` attribute rendered during setup cannot be.
+ */
+export declare function configSchemaHash(schema: unknown): string;