@fleetless/contracts 1.0.0 → 1.0.2

package/CHANGELOG.md

@@ -5,15 +5,81 @@ follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the
 project uses [semantic versioning](https://semver.org/spec/v2.0.0.html) over
 the wire shapes.
 
+## [1.0.2] — 2026-09-07
+
+A documentation and packaging release. (1.0.1 was tagged and never published:
+its `verify` job went red on a licence-header guard that swept the pipeline's
+own scratch file. The tag pattern is protected and cannot be moved, so the
+release carries the next number. Nothing was ever served as 1.0.1.)
+
+**No wire shape changes**, and nothing generated from a schema changes either — `artifacts/schema/` and
+`artifacts/schema-outgoing/` are byte-identical to 1.0.0. What changes is what
+the package says about itself.
+
+### Fixed
+
+- **The internal engineering prose is gone from the published bytes.** Doc
+  comments in the source were written for the people who built this and `tsc`
+  carries them into `dist/*.js` and `dist/*.d.ts`, so 1.0.0 shipped German
+  paragraphs, a reference robot's workspace paths, measured mesh sizes and
+  internal tracker ids to anyone who hovered a symbol in an editor. Every
+  comment that ships has been rewritten for a reader who has only this package.
+  A test now greps the built `dist/` and `artifacts/` for those markers and
+  fails on a hit.
+- **The `artifacts/` table in the README described `schema-outgoing/`
+  backwards.** It said those files were the messages the cloud sends to a
+  bridge. They are the opposite: the frames a bridge **sends**, rendered in
+  output mode, and validating incoming cloud frames against them fails on every
+  real frame. The table now says what each directory holds and why there are
+  two.
+- **The README claimed the robot-side bridge validates incoming frames against
+  `artifacts/schema/` at runtime with Python's `jsonschema`.** It does not. The
+  bridge does not depend on this package at all — it vendors its own copies —
+  and only its test harness imports `jsonschema`. There is no runtime validation
+  of incoming frames against these schemas.
+- **The security reporting address was in nothing the package served.**
+  `SECURITY.md` was not in `files`, and the README linked to it relatively.
+  `SECURITY.md`, `CONTRIBUTING.md` and `CODE_OF_CONDUCT.md` now ship, and the
+  address is written out in the README under its own heading rather than behind
+  a link.
+- **Twenty-two of the forty published files carried no SPDX header.**
+  Declaration emit drops a leading `//` comment and two `.js` files had theirs
+  elided, so more than half of what a licence scanner sees was unmarked. Every
+  file in `dist/` now carries `// SPDX-License-Identifier: Apache-2.0`, and the
+  pack check asserts it over the tarball's own bytes.
+- **The CHANGELOG's account of 1.0.0 was wrong about which server it matched**
+  — see the corrected note below.
+
+### Changed
+
+- `zod` moves from `^4.0.0` to `^4.4.3`. It stays a range on purpose, and the
+  README now says why: zod is a peer in everything but name, and an exact pin
+  forces a second copy on any consumer whose lockfile resolves a different
+  patch. `^4.4.3` is the floor these schemas are built, tested and exported
+  against, rather than a version nobody has run.
+- `bugs` gains an email address, so a report has somewhere to go from the npm
+  page.
+
 ## [1.0.0] — 2026-09-07
 
-The first published version. Nothing about the shapes changes with it: they are
-exactly the shapes the Fleetless cloud serves at release 0.17.0, and they have
+The first published version. Nothing about the shapes changes with it: they have
 been the contract between the cloud, the console, the SDK and the robot-side
 bridge for as long as those have existed. What changes is who can read them —
 until now this package was resolvable only from a private git URL, so nobody
 outside the project could build a Fleetless client from source.
 
+**Corrected in 1.0.2:** this entry originally said these were "exactly the
+shapes the Fleetless cloud serves at release 0.17.0". They are not. This package
+tracks the cloud's `main` branch, not its releases, and 1.0.0 was cut from a
+commit that already carried the MCP consent-withdrawal change — so the route
+notes and the OpenAPI description for
+`DELETE /api/client/mcp/grants/:clientId` and its developer twin state that
+withdrawal ends a session at the client's very next call, which the deployed
+0.17.0 does not do. On 0.17.0 a withdrawn client keeps working for the remaining
+lifetime of its access token, up to fifteen minutes. **A shape or a note here may
+precede the release that serves it**; check the platform's own release notes
+before treating one as an operational control.
+
 Consumers should pin an exact version. A range cannot express "compatible with
 the server you are talking to", and that is the only compatibility question
 these schemas answer. Any change that makes a previously valid message invalid

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,83 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at hello@fleetless.dev. All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior, harassment of an individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.1, available at [https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at [https://www.contributor-covenant.org/faq][FAQ]. Translations are available at [https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

package/CONTRIBUTING.md

@@ -0,0 +1,136 @@
+# Contributing to `@fleetless/contracts`
+
+This package is the single source of wire truth for Fleetless: every shape the
+API accepts or returns, and every message the robot-side bridge exchanges with
+the cloud, is written here once as a zod schema and exported as JSON Schema and
+OpenAPI for consumers that are not TypeScript.
+
+That makes a change here a cross-repository change. A schema is not a detail of
+one program; it is the agreement between several.
+
+## Setup
+
+Node 22 and pnpm (through corepack):
+
+```sh
+nvm use 22
+corepack enable
+pnpm install
+```
+
+There are no private dependencies. `pnpm install` works from a clean checkout
+with nothing but a network connection to the npm registry.
+
+## The checks
+
+| Command | What it does |
+|---|---|
+| `pnpm typecheck` | `tsc --noEmit` over `src/`, then again over `test/` with its own project. Both halves, always — the root project is `src`-only and says nothing about test files. |
+| `pnpm test` | The vitest suite. No network, no server. |
+| `pnpm build` | `tsc` into `dist/`. |
+| `pnpm artifacts` | Regenerates `artifacts/` from the zod schemas. |
+| `pnpm run test:pack` | Packs the tarball, asserts what is and is not inside it, then installs it into a scratch project and imports it for real. |
+
+To run one test file, use `pnpm vitest run test/<name>.test.ts`. Do **not**
+use `pnpm test -- <pattern>`: it does not filter, it runs the whole suite, and
+the exit code you read is the suite's.
+
+## Changing a schema
+
+1. Edit the zod schema in `src/`.
+2. Run `pnpm artifacts`. This regenerates `artifacts/`, which is **committed**.
+   A test fails if the committed artifacts are stale, and so does CI.
+3. Run `pnpm typecheck && pnpm test`.
+4. Commit the schema change and the regenerated artifacts together. A commit
+   that changes one without the other is a commit that publishes a lie to every
+   consumer validating against the artifact.
+
+Every source file carries the SPDX header `// SPDX-License-Identifier:
+Apache-2.0` as its first line. A test asserts this over the whole set — and the
+directory list is derived from the repository rather than written down, so a new
+top-level directory is swept the day it exists.
+
+The published files carry it too, which `tsc` does not do on its own:
+declaration emit drops a leading comment, so `scripts/stamp-dist.mjs` puts the
+header back on every file in `dist/` and `pnpm run test:pack` asserts it over
+the tarball's own bytes.
+
+**Nothing internal reaches the published bytes.** Doc comments in `src/` are
+carried into `dist/*.js` and `dist/*.d.ts` by `tsc`, and every
+`.meta({ description })` is copied into the JSON Schema and OpenAPI artifacts —
+so a comment written for the people who build this is a comment an editor shows
+to somebody who installed it. Write a description as what a field means to a
+caller, never as how the behaviour was found, on which machine, or under which
+internal ticket. `test/published-prose.test.ts` greps the built output and fails
+on German prose, an internal ticket id, a developer machine path or a
+first-name attribution.
+
+## Pull requests
+
+**Pull requests are welcome on GitHub**, at
+<https://github.com/fleetless/contracts>. Open an issue first for anything that
+changes an existing shape, so we can say what else has to move with it.
+
+**CI runs on GitLab.** This repository is mirrored from an internal GitLab
+instance, which is where the pipeline that verifies and publishes it lives. You
+will not see a check run on your GitHub pull request; a maintainer runs the
+same checks, and the result comes back as a review comment. Run `pnpm
+typecheck && pnpm test && pnpm artifacts` yourself before you open the pull
+request and you will have seen everything CI would tell you.
+
+## The CLA
+
+The first pull request you open will ask you to sign a Contributor Licence
+Agreement. It grants Dehne Robotik GmbH the right to license your contribution
+under terms other than Apache-2.0 in future — that is the whole of what it is
+for, and it is why the project can relicense its own code later without having
+to find every past contributor. It does not take your copyright away and it
+does not stop you from using your own contribution however you like.
+
+## Commit messages
+
+[Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/):
+`feat:`, `fix:`, `docs:`, `chore:`, `ci:`, `refactor:`, `test:`. A change that
+alters an existing wire shape is a breaking change; say so with a `!` and a
+`BREAKING CHANGE:` footer, because it decides the next version number.
+
+Everything in this repository is written in **English** — code, comments,
+commit messages, documentation.
+
+## Code of conduct
+
+By participating you agree to the [Code of Conduct](CODE_OF_CONDUCT.md).
+
+
+## Releasing (maintainers)
+
+The pipeline publishes, and `npm publish` from a working tree is refused by a
+`prepublishOnly` script — the rule has a mechanism rather than only a sentence.
+(The pipeline is unaffected: it publishes the tarball `verify` packed, and npm
+runs no prepare lifecycle for a tarball argument.)
+
+1. Update `CHANGELOG.md` and set the new version in `package.json`. **CI checks
+   both**, in `scripts/verify-version-tag.mjs`: `package.json` must equal the
+   tag without its `v`, and `CHANGELOG.md` must carry a dated heading reading
+   exactly `## [X.Y.Z] — YYYY-MM-DD`. `CHANGELOG.md` ships inside the tarball,
+   so a forgotten entry documents the wrong version to every consumer and npm
+   will not take a version back.
+
+   The same script refuses a release tag that would move npm's `latest`
+   backwards — a backported `v1.0.1` published while `latest` is `2.0.0` would
+   make `npm i @fleetless/contracts`, the command the README gives outsiders,
+   install a package a major version behind.
+2. Commit, push, and let the `verify` job go green on the branch.
+3. Tag `vX.Y.Z` (or `vX.Y.Z-beta.N` for a pre-release, which publishes to the
+   `next` dist-tag) and push the tag. The tag pipeline runs `verify` again and
+   then `publish`.
+
+`publish` needs an `NPM_TOKEN` variable, protected and masked. Protected means
+an unprotected ref receives an empty value rather than a missing one, so the
+tag pattern must be protected too; the job names that case before it can fail
+on it obliquely.
+
+**If the publish job goes red after `npm publish` has run, do not press
+retry.** npm refuses to republish a version, so a retry fails with a 403 that
+reads like a broken pipeline rather than like a release that already happened.
+Check `npm view @fleetless/contracts@<version>` first.

package/README.md

@@ -49,15 +49,28 @@ import openapi from '@fleetless/contracts/artifacts/openapi.json' with { type: '
 
 | Path | What it is |
 |---|---|
-| `artifacts/openapi.json` | The OpenAPI description of the REST API. |
-| `artifacts/routes.json` | Every route with its request and response schema names. |
-| `artifacts/schema/*.json` | One JSON Schema per wire shape, named after the shape. |
-| `artifacts/schema-outgoing/*.json` | The messages the cloud sends to a bridge. |
+| `artifacts/openapi.json` | The OpenAPI 3.1 description of the REST API, generated from the route manifest and the schemas. |
+| `artifacts/routes.json` | Every route with its request and response schema names, and the notes that explain each one. |
+| `artifacts/schema/*.json` | One JSON Schema per wire shape, named after the shape, rendered as **a receiver validates an incoming document**. |
+| `artifacts/schema-outgoing/*.json` | Twelve of those same shapes rendered again as **a sender must produce them** — the frames a robot's bridge sends to the cloud. |
 
-The robot-side bridge validates against `artifacts/schema/` with Python's
-`jsonschema`, which is why the artifacts are generated and committed rather
-than produced at install time: a consumer in another language needs them
-without running a TypeScript build.
+The two schema directories are the same shapes in zod's two rendering modes,
+and the difference matters if you are writing a bridge.
+
+`artifacts/schema/` is *input* mode: what a receiver accepts. Fleetless
+receivers strip unknown keys rather than refusing them, so these documents omit
+`additionalProperties: false`, and a field with a default is not marked
+required.
+
+`artifacts/schema-outgoing/` is *output* mode, for the twelve frames a bridge
+**sends**. There a relaxed schema points the wrong way: a misspelled key in an
+outgoing frame would pass an input-mode check and then be silently dropped by
+the server. Validate what you send against `schema-outgoing/`, and what you
+receive against `schema/`.
+
+The artifacts are generated and committed rather than produced at install time
+because a consumer in another language needs them without running a TypeScript
+build.
 
 ## Versioning
 
@@ -69,6 +82,13 @@ client may ignore, or a description is a minor or a patch.
 Pin an exact version. These shapes describe a running server, and "compatible
 with the server you are talking to" is not something a range can express.
 
+**The one dependency, `zod`, is deliberately a range and not a pin.** zod is a
+peer in everything but name: a consumer that imports both this package and zod
+must get one copy, or a schema from here fails an `instanceof` check against
+their own. An exact pin here forces a second copy on anyone whose lockfile
+resolves a different patch. The range floor is the version these schemas are
+built, tested and exported against, and a zod major is a major here too.
+
 ## Documentation
 
 The API reference at
@@ -76,12 +96,28 @@ The API reference at
 generated from these artifacts and is the place to read what a field means.
 This package is the place to read what it *is*.
 
-## Contributing and security
+## Reporting a security issue
+
+Email **security@fleetless.dev**. Please do not open a public issue for a
+security report.
+
+**A wrong schema is a security report.** If a schema here accepts a value that
+should never reach a server — an identifier that escapes its own grammar, a
+missing bound, a union that admits a shape the API does not expect — that is a
+vulnerability in this package, even though nothing in it executes anything. So
+is a generated artifact that disagrees with the zod schema it came from, because
+consumers that are not TypeScript validate against the artifact and never see
+the zod.
+
+`SECURITY.md` ships inside the published package and has the full policy: what
+is in scope, what is not, and the response times we hold ourselves to.
+
+## Contributing
 
-[CONTRIBUTING.md](CONTRIBUTING.md) has the setup, the checks and the pull
-request process. [SECURITY.md](SECURITY.md) has the reporting address and what
-counts as a security report here — a schema that lets a bad value through is
-one, even though nothing in this package executes it.
+`CONTRIBUTING.md` ships inside the published package and has the setup, the
+checks and the pull request process. In short: `pnpm install`, then `pnpm
+typecheck && pnpm test`; every schema change regenerates `artifacts/` with
+`pnpm artifacts` and commits it in the same commit.
 
 ## Licence
 

package/SECURITY.md

@@ -0,0 +1,55 @@
+# Security policy
+
+## Reporting a vulnerability
+
+Email **security@fleetless.dev**. Please do not open a public GitHub issue for
+a security report.
+
+Include what you found, the schema or artifact it concerns, and — if you have
+one — a value that the schema accepts and should not, or rejects and should
+not. A minimal reproduction against a published version of this package is the
+most useful thing you can send.
+
+We acknowledge every report within **3 working days** and follow up with
+either a fix or a written plan within **30 days**. If a report leads to a
+released fix, we credit you by name unless you ask us not to.
+
+## What is in scope
+
+This repository is a schema library. It defines the wire shapes of the
+Fleetless API and the bridge–cloud protocol as zod schemas, and exports them
+as JSON Schema and OpenAPI documents under `artifacts/`.
+
+**A wrong schema is a security report.** If a schema accepts a value that
+should never reach a server — an identifier that escapes its own grammar, a
+bound that is missing, a union that admits a shape the API does not expect, a
+field that a validator lets through unchecked — that is a vulnerability in
+this package, even though nothing here executes it. The same is true of a
+generated artifact that disagrees with the zod schema it came from, because
+non-TypeScript consumers validate against the artifact and never see the zod.
+
+So, in scope:
+
+- the zod schemas in `src/`;
+- the JSON Schema and OpenAPI artifacts in `artifacts/`, including any
+  disagreement between an artifact and its source schema;
+- the build and export tooling in `scripts/`;
+- the published npm package `@fleetless/contracts` and its contents.
+
+## What is not in scope
+
+**The Fleetless cloud is not in this repository.** A server that fails to
+enforce a schema, an authentication or authorisation flaw, a rate limit, a
+data leak from an API endpoint — none of those live here, and none of them can
+be fixed by a change to this package. Report them to the same address; say
+which service you were looking at, and we will route it. What we cannot do is
+treat this repository's issue tracker as the place where they are tracked.
+
+Also out of scope here: the Fleetless console, the bridge, the SDK, the
+documentation site, and any deployment of Fleetless operated by someone else.
+
+## Supported versions
+
+The latest published minor of `@fleetless/contracts` receives fixes. Older
+minors do not; a security fix is released as a new patch on the current minor,
+and consumers pin exact versions, so upgrading is the remedy.

package/artifacts/openapi.json

@@ -3643,7 +3643,7 @@
             }
           }
         },
-        "description": "MCP's Streamable HTTP gives this path three verbs: `POST` carries JSON-RPC, `GET` opens the server-initiated SSE stream, and `DELETE` ends a session. This server has no sessions — the argument is in `MCP_PROTOCOL_VERSION`'s own note, and W8's second cloud instance is where a per-process session map would break — so `GET` and `DELETE` answer `405`, which is what a client is built to fall back from. \n\n**The `405` is this cloud's own answer, not the SDK's**, and the difference was measured: MCP SDK 1.30.0 opens an SSE stream on `GET` (`handleGetRequest`) and answers `200` on `DELETE` (`handleDeleteRequest`), neither of which a stateless server has any business doing, so the cloud writes the `405` itself in the transport's own JSON-RPC error shape with `Allow: POST`. \n\n**The row exists so that the `405` is not a `404`.** An unregistered verb answers `404`, and at a path whose last segment is an app identifier a `404` already means *no such app* — one answer for two states, which is the failure this project keeps paying for. Registering the verb lets the endpoint say \"this app's server is here; this verb is not part of it\". The central `/mcp` registers neither verb and does not need to: its path takes no parameter, so nothing can misread its `404`. \n\n**The `405` body is the transport's JSON-RPC error object, not the `apiError` envelope.** The three codes above are the refusals that come *first* — the app, its switch, then the bearer, in the order `POST` describes — and they are `apiError` because they are answered before the transport is reached at all. If this server ever becomes stateful, this row and the `DELETE` beside it are where that lands, and the cloud's route-manifest test is what would make both repositories notice."
+        "description": "MCP's Streamable HTTP gives this path three verbs: `POST` carries JSON-RPC, `GET` opens the server-initiated SSE stream, and `DELETE` ends a session. This server has no sessions — the argument is in `MCP_PROTOCOL_VERSION`'s own note, and a per-process session map is what breaks at the second cloud instance — so `GET` and `DELETE` answer `405`, which is what a client is built to fall back from. \n\n**The `405` is this cloud's own answer, not the SDK's**, and the difference was measured: MCP SDK 1.30.0 opens an SSE stream on `GET` (`handleGetRequest`) and answers `200` on `DELETE` (`handleDeleteRequest`), neither of which a stateless server has any business doing, so the cloud writes the `405` itself in the transport's own JSON-RPC error shape with `Allow: POST`. \n\n**The row exists so that the `405` is not a `404`.** An unregistered verb answers `404`, and at a path whose last segment is an app identifier a `404` already means *no such app* — one answer for two states, which is the failure this project keeps paying for. Registering the verb lets the endpoint say \"this app's server is here; this verb is not part of it\". The central `/mcp` registers neither verb and does not need to: its path takes no parameter, so nothing can misread its `404`. \n\n**The `405` body is the transport's JSON-RPC error object, not the `apiError` envelope.** The three codes above are the refusals that come *first* — the app, its switch, then the bearer, in the order `POST` describes — and they are `apiError` because they are answered before the transport is reached at all. If this server ever becomes stateful, this row and the `DELETE` beside it are where that lands, and the cloud's route-manifest test is what would make both repositories notice."
       },
       "delete": {
         "operationId": "delete_mcp_appIdentifier",

package/artifacts/routes.json

@@ -2370,7 +2370,7 @@
         "forbidden"
       ],
       "transport": "http",
-      "notes": "MCP's Streamable HTTP gives this path three verbs: `POST` carries JSON-RPC, `GET` opens the server-initiated SSE stream, and `DELETE` ends a session. This server has no sessions — the argument is in `MCP_PROTOCOL_VERSION`'s own note, and W8's second cloud instance is where a per-process session map would break — so `GET` and `DELETE` answer `405`, which is what a client is built to fall back from. \n\n**The `405` is this cloud's own answer, not the SDK's**, and the difference was measured: MCP SDK 1.30.0 opens an SSE stream on `GET` (`handleGetRequest`) and answers `200` on `DELETE` (`handleDeleteRequest`), neither of which a stateless server has any business doing, so the cloud writes the `405` itself in the transport's own JSON-RPC error shape with `Allow: POST`. \n\n**The row exists so that the `405` is not a `404`.** An unregistered verb answers `404`, and at a path whose last segment is an app identifier a `404` already means *no such app* — one answer for two states, which is the failure this project keeps paying for. Registering the verb lets the endpoint say \"this app's server is here; this verb is not part of it\". The central `/mcp` registers neither verb and does not need to: its path takes no parameter, so nothing can misread its `404`. \n\n**The `405` body is the transport's JSON-RPC error object, not the `apiError` envelope.** The three codes above are the refusals that come *first* — the app, its switch, then the bearer, in the order `POST` describes — and they are `apiError` because they are answered before the transport is reached at all. If this server ever becomes stateful, this row and the `DELETE` beside it are where that lands, and the cloud's route-manifest test is what would make both repositories notice."
+      "notes": "MCP's Streamable HTTP gives this path three verbs: `POST` carries JSON-RPC, `GET` opens the server-initiated SSE stream, and `DELETE` ends a session. This server has no sessions — the argument is in `MCP_PROTOCOL_VERSION`'s own note, and a per-process session map is what breaks at the second cloud instance — so `GET` and `DELETE` answer `405`, which is what a client is built to fall back from. \n\n**The `405` is this cloud's own answer, not the SDK's**, and the difference was measured: MCP SDK 1.30.0 opens an SSE stream on `GET` (`handleGetRequest`) and answers `200` on `DELETE` (`handleDeleteRequest`), neither of which a stateless server has any business doing, so the cloud writes the `405` itself in the transport's own JSON-RPC error shape with `Allow: POST`. \n\n**The row exists so that the `405` is not a `404`.** An unregistered verb answers `404`, and at a path whose last segment is an app identifier a `404` already means *no such app* — one answer for two states, which is the failure this project keeps paying for. Registering the verb lets the endpoint say \"this app's server is here; this verb is not part of it\". The central `/mcp` registers neither verb and does not need to: its path takes no parameter, so nothing can misread its `404`. \n\n**The `405` body is the transport's JSON-RPC error object, not the `apiError` envelope.** The three codes above are the refusals that come *first* — the app, its switch, then the bearer, in the order `POST` describes — and they are `apiError` because they are answered before the transport is reached at all. If this server ever becomes stateful, this row and the `DELETE` beside it are where that lands, and the cloud's route-manifest test is what would make both repositories notice."
     },
     {
       "method": "DELETE",

package/dist/alerts.d.ts

@@ -1,28 +1,24 @@
+// SPDX-License-Identifier: Apache-2.0
 import { z } from 'zod';
 /**
- * Datapoint alerts and per-datapoint chart display config (spec
- * `2026-08-28-alerts-and-datapoint-modal-design`, D1/D2/D5).
+/**
+ * Datapoint alerts and per-datapoint chart display config.
  *
- * An alert is a **state machine** (`ok ⇄ firing`), not a fire-once event —
- * the definition (this file's request/entity shapes) and the runtime state
- * (`state`, `state_since`, `last_value`) share one row, evaluated by the
- * cloud at ingest.
+ * An alert is a **state machine** (`ok ⇄ firing`), not a fire-once event. The
+ * definition and the runtime state (`state`, `state_since`, `last_value`) are
+ * read together, and the cloud evaluates the alert at ingest.
  *
- * **Both tables moved into `robotConfigDoc` in FL-002.** The alert definition
- * is `config.ts`'s `datapointAlert`, nested under the datapoint it watches;
- * the chart bounds are `datapointChart`. They therefore take effect on
- * publish rather than immediately, and in exchange every change to them is
- * versioned, comparable and revertible. The runtime state stays wherever the
- * definition goes: it belongs in the database and has no business in a
- * versioned document.
+ * **The definitions live in the configuration document.** The alert definition
+ * is `config.ts`'s `datapointAlert`, nested under the datapoint it watches; the
+ * chart bounds are `datapointChart`. They therefore take effect on publish
+ * rather than immediately, and in exchange every change to them is versioned,
+ * comparable and revertible. The runtime state stays in the database: it has no
+ * business in a versioned document.
  *
- * **What is left here is the read surface**, which FL-002 wave 4 kept rather
- * than deleted: `GET /api/robots/:id/alerts` and `GET /api/org/alerts` still
- * answer with the definition joined to its state, and the shapes below are
- * what they answer with. What wave 4 did remove is the mail path — the fields
- * `cooldown_minutes`, `recipients` and `notify_on_resolve`, and the two
- * bounds that guarded them. No alert can send mail, so nothing here describes
- * one.
+ * **What is here is the read surface.** `GET /api/robots/:id/alerts` and
+ * `GET /api/org/alerts` answer with the definition joined to its state, and the
+ * shapes below are what they answer with. No alert sends mail, so nothing here
+ * describes one.
  */
 /**
  * `above`/`below` compare the numeric sample value (already scale/offset
@@ -104,10 +100,9 @@ export type AlertState = z.infer<typeof alertState>;
  * document and the runtime state out of `datapoint_alert_state`, and the
  * cloud joins the two per request (`routes/alerts.ts`'s `toWire`).
  *
- * **It carried three mail settings — `cooldown_minutes`, `recipients` and
- * `notify_on_resolve` — and FL-002 wave 4 removed them with the mail path.**
- * The format has no mail fields, so no alert could be configured to send one;
- * the three had nothing behind them well before they were deleted.
+ * **There are no mail settings here.** The configuration format has no mail
+ * fields, so no alert can be configured to send one, and a shape describing
+ * recipients would describe a delivery path that does not exist.
  */
 export declare const datapointAlertRow: z.ZodObject<{
     id: z.ZodUUID;

package/dist/alerts.js

@@ -2,29 +2,24 @@
 import { z } from 'zod';
 import { slug } from './common.js';
 /**
- * Datapoint alerts and per-datapoint chart display config (spec
- * `2026-08-28-alerts-and-datapoint-modal-design`, D1/D2/D5).
+/**
+ * Datapoint alerts and per-datapoint chart display config.
  *
- * An alert is a **state machine** (`ok ⇄ firing`), not a fire-once event —
- * the definition (this file's request/entity shapes) and the runtime state
- * (`state`, `state_since`, `last_value`) share one row, evaluated by the
- * cloud at ingest.
+ * An alert is a **state machine** (`ok ⇄ firing`), not a fire-once event. The
+ * definition and the runtime state (`state`, `state_since`, `last_value`) are
+ * read together, and the cloud evaluates the alert at ingest.
  *
- * **Both tables moved into `robotConfigDoc` in FL-002.** The alert definition
- * is `config.ts`'s `datapointAlert`, nested under the datapoint it watches;
- * the chart bounds are `datapointChart`. They therefore take effect on
- * publish rather than immediately, and in exchange every change to them is
- * versioned, comparable and revertible. The runtime state stays wherever the
- * definition goes: it belongs in the database and has no business in a
- * versioned document.
+ * **The definitions live in the configuration document.** The alert definition
+ * is `config.ts`'s `datapointAlert`, nested under the datapoint it watches; the
+ * chart bounds are `datapointChart`. They therefore take effect on publish
+ * rather than immediately, and in exchange every change to them is versioned,
+ * comparable and revertible. The runtime state stays in the database: it has no
+ * business in a versioned document.
  *
- * **What is left here is the read surface**, which FL-002 wave 4 kept rather
- * than deleted: `GET /api/robots/:id/alerts` and `GET /api/org/alerts` still
- * answer with the definition joined to its state, and the shapes below are
- * what they answer with. What wave 4 did remove is the mail path — the fields
- * `cooldown_minutes`, `recipients` and `notify_on_resolve`, and the two
- * bounds that guarded them. No alert can send mail, so nothing here describes
- * one.
+ * **What is here is the read surface.** `GET /api/robots/:id/alerts` and
+ * `GET /api/org/alerts` answer with the definition joined to its state, and the
+ * shapes below are what they answer with. No alert sends mail, so nothing here
+ * describes one.
  */
 /**
  * `above`/`below` compare the numeric sample value (already scale/offset
@@ -102,10 +97,9 @@ export const alertState = z.enum(['ok', 'firing']);
  * document and the runtime state out of `datapoint_alert_state`, and the
  * cloud joins the two per request (`routes/alerts.ts`'s `toWire`).
  *
- * **It carried three mail settings — `cooldown_minutes`, `recipients` and
- * `notify_on_resolve` — and FL-002 wave 4 removed them with the mail path.**
- * The format has no mail fields, so no alert could be configured to send one;
- * the three had nothing behind them well before they were deleted.
+ * **There are no mail settings here.** The configuration format has no mail
+ * fields, so no alert can be configured to send one, and a shape describing
+ * recipients would describe a delivery path that does not exist.
  */
 export const datapointAlertRow = z.object({
     id: z.uuid(),

package/dist/app-users.d.ts

@@ -1,3 +1,4 @@
+// SPDX-License-Identifier: Apache-2.0
 import { z } from 'zod';
 /**
  * **App users: the per-app identity space** (spec `2026-09-05-app-user-auth`,
@@ -47,12 +48,12 @@ export declare const providerSlug: z.ZodString;
 /**
  * **The three states an app user can be in, and the order is the lifecycle.**
  *
- * - `pending_verification` — self-registered, mail sent, cannot log in yet
- *   (D6). Without this state the domain whitelist would prove nothing: anybody
- *   could claim any address at an allowed domain.
+ * - `pending_verification` — self-registered, mail sent, cannot log in yet.
+ *   Without this state a domain allow-list would prove nothing: anybody could
+ *   claim any address at an allowed domain.
  * - `active` — may log in.
  * - `blocked` — may not, and every refusal is the same `invalid_credentials`
- *   a wrong password gets (§4). A block that announced itself would be an
+ *   a wrong password gets. A block that announced itself would be an
  *   account-enumeration oracle with an extra step.
  *
  * `pending_verification` is reached exactly once and left only by spending the
@@ -442,7 +443,7 @@ export type MailTemplateKind = z.infer<typeof mailTemplateKind>;
  */
 export declare const MAIL_TEMPLATE_VARIABLES: readonly ["app.name", "org.name", "user.email", "user.display_name", "role.name", "link", "expires_in_hours"];
 /**
- * **The Fleetless default text for the three app mails** (spec D5, §6).
+ * **The Fleetless default text for the three app mails.**
  *
  * It lives here rather than in the cloud because two products send the same
  * words: the cloud renders these when an app has no template of its own, and
@@ -476,7 +477,7 @@ export declare const MAIL_TEMPLATE_VARIABLES: readonly ["app.name", "org.name",
  * that one is written by an authenticated developer about somebody they
  * invited.
  *
- * **`expires_in_hours` is the only lifetime variable the spec offers**, and
+ * **`expires_in_hours` is the only lifetime variable a template gets**, and
  * the three values are 1, 24 and 168. "The next 168 hours" is not how a person
  * says a week, so each default converts: 48 and up reads in days, exactly one
  * reads "1 hour", everything else reads in hours. The conversion is in the