@fleetless/contracts 1.0.2 → 1.0.4

package/dist/app-users.js

@@ -2,8 +2,7 @@
 import { z } from 'zod';
 import { idpIssuer, mailStatus, password } from './identity.js';
 /**
- * **App users: the per-app identity space** (spec `2026-09-05-app-user-auth`,
- * D1–D7).
+ * **App users: the per-app identity space.**
  *
  * The 2026-08-29 model put developers and end users into one pool per org,
  * tied apps to groups, and let an org admin enter an app only by
@@ -22,7 +21,7 @@ import { idpIssuer, mailStatus, password } from './identity.js';
  *   as unrelated accounts, and a Fleetless user who wants to use an app
  *   registers or is invited like anybody else.
  *
- * **Fleetless shows an app user no page** (D2). The developer's own UI owns
+ * **Fleetless shows an app user no page**. The developer's own UI owns
  * every screen and calls the JSON client-auth API (`client-auth.ts`). The one
  * Fleetless-rendered surface an app user can reach is the problem page for an
  * OIDC callback whose state no longer resolves to a redirect URI — every other
@@ -68,7 +67,7 @@ export const appUserStatus = z.enum(['pending_verification', 'active', 'blocked'
  * **A user of one app.** Not a user of the org: `app_id` is the whole scope,
  * and the uniqueness constraint the cloud enforces is `(app_id, lower(email))`
  * rather than a global one. The same person at two apps of one org is two
- * unrelated rows, by design (D1).
+ * unrelated rows, by design.
  */
 export const appUser = z.object({
     id: z.uuid().meta({
@@ -148,8 +147,8 @@ export const createAppUserRequest = z
  * offering it is a refusal rather than a silently dropped field.
  *
  * **`status` admits only `active` and `blocked`.** `pending_verification` is
- * reached once, by self-registration, and left by spending the mailed token
- * (D6). A developer able to set it back could void a verified address without
+ * reached once, by self-registration, and left by spending the mailed token.
+ * A developer able to set it back could void a verified address without
  * the user ever seeing a mail, and there is no route out of that state that
  * does not require a token nobody re-sent. So the narrower enum is the rule,
  * stated in the schema rather than left to a handler to remember.
@@ -196,7 +195,7 @@ export const createAppInvitationRequest = z
  * An app that has configured none has nowhere for it to point, so there is no
  * link to hand back — `null` says that outright, where an absent key would be
  * indistinguishable from a mapper that dropped the field and a fabricated
- * Fleetless-hosted URL would name a page this product does not serve (D2).
+ * Fleetless-hosted URL would name a page this product does not serve.
  */
 export const appInvitation = z.object({
     id: z.uuid().meta({ description: 'The invitation, as listed and revoked by the developer.' }),
@@ -231,7 +230,7 @@ export const appInvitationListResponse = z.object({
     }),
 });
 /**
- * **An app's OIDC provider, as read back** (D4). Any number per app, unlike
+ * **An app's OIDC provider, as read back**. Any number per app, unlike
  * the group provider this replaces — a developer serving two customers needs
  * two, and the old at-most-one rule was a property of groups rather than of
  * identity.
@@ -305,7 +304,7 @@ export const createAppOidcProviderRequest = z
         description: 'The client secret, **write-only**: it is stored encrypted and comes back through nothing — not the read, not this route\'s own answer, not an audit detail. Required on create, since a provider with no secret cannot exchange a code; the minimum length refuses a value that is a misconfiguration rather than a secret.',
     }),
     scopes: z.array(z.string().min(1).max(60)).min(1).max(20).default(['openid', 'email', 'profile']).meta({
-        description: 'The scopes to request. Defaults to `openid email profile`, which is what the linking rules in this design actually read: the subject, the address and its verified flag, and a name.',
+        description: 'The scopes to request. Defaults to `openid email profile`, which is what account linking actually reads: the subject, the address and its verified flag, and a name.',
     }),
     link_verified_emails: z.boolean().default(false).meta({
         description: 'Whether a federated login may join an existing app user by verified address. **Defaults to off**, because relaxing later is additive and admitting duplicates now and tightening afterwards is not.',
@@ -438,16 +437,15 @@ export const emailDomain = z
     .max(253)
     .regex(/^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$/, 'must be a lowercase domain name with at least two labels');
 /**
- * **The app's auth settings: one row per app, configured by a Fleetless user**
- * (D3).
+ * **The app's auth settings: one row per app, configured by a Fleetless user.**
  *
  * `self_registration` and `allowed_domains` are **one policy for one
  * decision** — they govern registration by password and registration through
- * an identity provider alike (D4). An invitation always bypasses both, because
+ * an identity provider alike. An invitation always bypasses both, because
  * a developer inviting somebody by hand has already made the decision the
  * whitelist automates.
  *
- * The four URLs are what makes D2 work: Fleetless mails a link, and the link
+ * The four URLs are what makes that work: Fleetless mails a link, and the link
  * points into the developer's app. An app that has configured none of them
  * still works for password login — it simply cannot send a mail that leads
  * anywhere, and `send_mail` is refused rather than silently sending a dead
@@ -494,7 +492,7 @@ export const putAppAuthConfigRequest = appAuthConfig
     .omit({ oidc_callback_url: true, updated_at: true })
     .strict();
 /**
- * The three mails a developer may replace with their own template (D5).
+ * The three mails a developer may replace with their own template.
  * Mails to *Fleetless* users — a team invitation, a console password reset —
  * stay Fleetless default and are deliberately not customisable: they are
  * about this platform, not about the developer's product.

package/dist/apps.js

@@ -124,7 +124,8 @@ export const updateAppRequest = z.object({
     name: z.string().min(1).max(120).optional(),
     robot_ids: z.array(z.uuid()).optional(),
     /**
-     * `app.default_role_id`'s write half — an app *setting*, which is where D1
+     * `app.default_role_id`'s write half — an app *setting*, which is where the
+   * two-identity-space model
      * put the default role, so it belongs on the app's own PATCH and not on a
      * route of its own.
      *

package/dist/audit.d.ts

@@ -15,7 +15,7 @@ import { z } from 'zod';
  * resolve four different id kinds to render a row.
  *
  * **`end_user` stays, and it stays for the rows already written.** The
- * two-space cut (2026-09-05, D1) replaced the org's one user pool with
+ * split into two identity spaces replaced the org's one user pool with
  * Fleetless users and per-app app users; every new row an app user writes
  * carries `app_user`. But an audit log is the one thing this platform must
  * never rewrite, and there are stored rows whose `kind` is `end_user`. Dropping
@@ -23,9 +23,8 @@ import { z } from 'zod';
  * cannot be read back is worse than one carrying a retired word.
  *
  * So this enum is deliberately **wider than what any producer emits**: nothing
- * writes `end_user` any more, and nothing may start again. That is the kind of
- * claim this repository has been wrong about before by leaving it unsaid, so it
- * is said here rather than inferred from a `grep` somebody runs in a year.
+ * writes `end_user` any more, and nothing may start again. That is said here
+ * rather than left to be inferred from a search somebody runs in a year.
  *
  * `developer` is a Fleetless user. It kept its name through both redesigns
  * because it was always right about what it named: the person who configures

package/dist/audit.js

@@ -16,7 +16,7 @@ import { wireSeqCursor, wireTimestampMs } from './common.js';
  * resolve four different id kinds to render a row.
  *
  * **`end_user` stays, and it stays for the rows already written.** The
- * two-space cut (2026-09-05, D1) replaced the org's one user pool with
+ * split into two identity spaces replaced the org's one user pool with
  * Fleetless users and per-app app users; every new row an app user writes
  * carries `app_user`. But an audit log is the one thing this platform must
  * never rewrite, and there are stored rows whose `kind` is `end_user`. Dropping
@@ -24,9 +24,8 @@ import { wireSeqCursor, wireTimestampMs } from './common.js';
  * cannot be read back is worse than one carrying a retired word.
  *
  * So this enum is deliberately **wider than what any producer emits**: nothing
- * writes `end_user` any more, and nothing may start again. That is the kind of
- * claim this repository has been wrong about before by leaving it unsaid, so it
- * is said here rather than inferred from a `grep` somebody runs in a year.
+ * writes `end_user` any more, and nothing may start again. That is said here
+ * rather than left to be inferred from a search somebody runs in a year.
  *
  * `developer` is a Fleetless user. It kept its name through both redesigns
  * because it was always right about what it named: the person who configures

package/dist/client-auth.d.ts

@@ -61,7 +61,7 @@ export declare const clientLogoutRequest: z.ZodObject<{
 }, z.core.$strip>;
 export type ClientLogoutRequest = z.infer<typeof clientLogoutRequest>;
 /**
- * **Self-registration** (D6) — and the account it creates cannot log in yet.
+ * **Self-registration** — and the account it creates cannot log in yet.
  *
  * `register` writes the user as `pending_verification` and mails the app's
  * `verify_url`. Without that step the domain whitelist would prove nothing:
@@ -221,7 +221,7 @@ export type ClientOidcStartQuery = z.infer<typeof clientOidcStartQuery>;
  * `state` is the one required field because it is the one Fleetless minted: it
  * resolves the `oidc_interactions` row that holds the app's `redirect_uri`,
  * and without it there is nowhere to send any answer, success or failure. That
- * is the single case where the cloud renders a page of its own (D2).
+ * is the single case where the cloud renders a page of its own.
  *
  * It exists as a schema rather than as four parameters read by hand because
  * the manifest forbids the second: a documented route whose prose names a
@@ -244,7 +244,7 @@ export type ClientOidcExchangeRequest = z.infer<typeof clientOidcExchangeRequest
 /**
  * **Why a federated sign-in ended without a session, in a code the app can
  * branch on** — carried back to the app's own `redirect_uri` as `error`, not
- * rendered by Fleetless (D2). The only Fleetless-rendered page in this flow is
+ * rendered by Fleetless. The only Fleetless-rendered page in this flow is
  * the one for a state that can no longer be resolved to a redirect URI, because
  * then there is nowhere to send the answer.
  *
@@ -293,7 +293,7 @@ export declare const clientOidcErrorCode: z.ZodEnum<{
 export type ClientOidcErrorCode = z.infer<typeof clientOidcErrorCode>;
 /**
  * **A pending MCP authorization, as the app's own consent screen reads it**
- * (D7). Fleetless renders no page here either: `authorize` redirects to the
+ * Fleetless renders no page here either: `authorize` redirects to the
  * app's `mcp_login_url` with an interaction id, the app authenticates the user
  * with its normal UI, shows this, and approves or denies through the API.
  *
@@ -388,7 +388,7 @@ export type McpConsentGrantListResponse = z.infer<typeof mcpConsentGrantListResp
  * quietest way for a cut like this to go wrong.
  *
  * **`act` is gone.** It named the org admin behind an impersonation (the RFC
- * 8693 pattern). Impersonation is deleted with no successor (D1), so a field
+ * 8693 pattern). Impersonation is deleted with no successor, so a field
  * that could still arrive would describe a delegation nothing can mint — and a
  * client rendering "you are acting as …" from it would be showing a state the
  * platform cannot enter.

package/dist/client-auth.js

@@ -73,7 +73,7 @@ export const clientLogoutRequest = z.object({
 });
 /* ---------------------------------------------- registration and mails -- */
 /**
- * **Self-registration** (D6) — and the account it creates cannot log in yet.
+ * **Self-registration** — and the account it creates cannot log in yet.
  *
  * `register` writes the user as `pending_verification` and mails the app's
  * `verify_url`. Without that step the domain whitelist would prove nothing:
@@ -271,7 +271,7 @@ export const clientOidcStartQuery = z.object({
  * `state` is the one required field because it is the one Fleetless minted: it
  * resolves the `oidc_interactions` row that holds the app's `redirect_uri`,
  * and without it there is nowhere to send any answer, success or failure. That
- * is the single case where the cloud renders a page of its own (D2).
+ * is the single case where the cloud renders a page of its own.
  *
  * It exists as a schema rather than as four parameters read by hand because
  * the manifest forbids the second: a documented route whose prose names a
@@ -306,7 +306,7 @@ export const clientOidcExchangeRequest = z
 /**
  * **Why a federated sign-in ended without a session, in a code the app can
  * branch on** — carried back to the app's own `redirect_uri` as `error`, not
- * rendered by Fleetless (D2). The only Fleetless-rendered page in this flow is
+ * rendered by Fleetless. The only Fleetless-rendered page in this flow is
  * the one for a state that can no longer be resolved to a redirect URI, because
  * then there is nowhere to send the answer.
  *
@@ -355,7 +355,7 @@ export const clientOidcErrorCode = z.enum([
 /* ------------------------------------------------ MCP, delegated login -- */
 /**
  * **A pending MCP authorization, as the app's own consent screen reads it**
- * (D7). Fleetless renders no page here either: `authorize` redirects to the
+ * Fleetless renders no page here either: `authorize` redirects to the
  * app's `mcp_login_url` with an interaction id, the app authenticates the user
  * with its normal UI, shows this, and approves or denies through the API.
  *
@@ -456,7 +456,7 @@ export const mcpConsentGrantListResponse = z.object({
  * quietest way for a cut like this to go wrong.
  *
  * **`act` is gone.** It named the org admin behind an impersonation (the RFC
- * 8693 pattern). Impersonation is deleted with no successor (D1), so a field
+ * 8693 pattern). Impersonation is deleted with no successor, so a field
  * that could still arrive would describe a delegation nothing can mint — and a
  * client rendering "you are acting as …" from it would be showing a state the
  * platform cannot enter.

package/dist/common.d.ts

@@ -123,8 +123,8 @@ export declare const wireTimestampMs: z.ZodPipe<z.ZodPipe<z.ZodUnion<readonly [z
  *
  * 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`
+ * console reads this same error through, 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.

package/dist/common.js

@@ -149,8 +149,8 @@ export const wireTimestampMs = z
  *
  * 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`
+ * console reads this same error through, 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.

package/dist/config-issues.d.ts

@@ -4,17 +4,15 @@ 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,
@@ -42,10 +40,9 @@ 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"];
@@ -90,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
@@ -126,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

@@ -7,10 +7,9 @@ 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'];
@@ -107,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
@@ -199,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

@@ -362,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
@@ -560,9 +559,9 @@ 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;
 /**