@fleetless/contracts 1.0.4 → 1.0.5

package/CHANGELOG.md

@@ -5,6 +5,62 @@ 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.5] — 2026-09-07
+
+The guard was rebuilt around the set of bytes that become public rather than
+around three directory names, and it found 190 things the old shape could not
+see. **No wire shape changes**: two `notes` sentences are repaired and nothing
+else in `artifacts/` moves.
+
+### Fixed
+
+- **Two sentences an earlier sweep broke, in the published API reference.**
+  `POST /mcp/:appIdentifier` ended "one answer for two states, which is one
+  answer for two states", a tautology left behind when a clause was removed;
+  `GET /api/robots/:id/jobs/history` read "`history` is a syntactically valid
+  slug and The router matches a static segment first", a mid-sentence capital
+  left behind when a product name was replaced. Both are in `routes.json` and
+  `openapi.json`, so both were in every client generated from 1.0.4 and on the
+  public reference page.
+- **Six internal schedule references on exported schemas**, in `alerts.ts`,
+  `config.ts`, `config-issues.ts`, `errors.ts` and `identity.ts`. They ship in
+  the declarations, so an editor showed them on hover to anyone who installed
+  the package. A private repository path in an `errors.ts` comment went with
+  them.
+- **`test/` and `scripts/` were outside the guard entirely**, and both mirror
+  in full. 160 further references swept: internal decision labels, schedule
+  labels, citations of two repositories that stay private and of the
+  maintainer-only files, the reference robot's name in two fixtures, and
+  internal task ids.
+
+### Changed
+
+- **The scanned set is computed, not named.** It is the union of what `npm
+  pack` reports, what `git ls-files` reports and a walk of every directory in
+  `files`. A file in none of the three is out of scope; a file in any of them
+  is scanned. The predecessor named `src`, `dist`, `artifacts` and five
+  markdown files, which left `package.json`, `.gitlab-ci.yml`, the tsconfigs
+  and both other trees unswept.
+- **Only the German scan strips anything**, and only URLs and single-token code
+  spans. Stripping links and backticks before every class made the shipped
+  documents blind to an internal hostname inside a markdown link.
+- **Eighteen detectors, each carrying its own fixtures.** Suffixed decision
+  labels (`D3a` never matched), bare review codenames, schedule labels in the
+  three spellings this codebase writes, dotfile and bare two-segment paths into
+  a sibling repository, task ids and CI pipeline numbers. A floor over the
+  count makes deleting a detector red.
+- **`scripts/verify-pack.mjs`** now reads the *packed* manifest rather than the
+  one on disk, checks every dependency section rather than `dependencies`
+  alone, runs the marker detectors over that manifest, asserts each published
+  file declares exactly **one** SPDX identifier rather than reading its first
+  line, and verifies that every relative link in every shipped document
+  resolves inside the tarball.
+
+### Added
+
+- **`scripts/verify-commit-messages.mjs`**, wired into the verify job. A commit
+  message is public the moment it is pushed, and this history mirrors.
+
 ## [1.0.4] — 2026-09-07
 
 Two things a grep over the published 1.0.3 tarball found that the guard was not
@@ -12,7 +68,7 @@ looking for. **No wire shape changes**; `artifacts/` is byte-identical to 1.0.3.
 
 ### Fixed
 
-- **A published `dist/` comment cited `CLAUDE.md`** and two internal server
+- **A published `dist/` comment cited a maintainer-only file** and two internal server
   symbols by name. Rewritten to say what the rule is rather than where it is
   written down.
 - **The markdown this package ships was outside the guard.** `README.md`,

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 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 two differ: 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 one answer for two states. 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 two differ: 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* — so an unregistered verb and an unknown app would answer identically. 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",
@@ -6406,7 +6406,7 @@
             }
           }
         },
-        "description": "Needs the `action_history` capability, and **this route is what makes that switch mean something** — it was unkeepable while nothing durable recorded what had run. Two residuals worth stating rather than implying away. `history` is a syntactically valid slug and The router matches a static segment first, so a robot with a service literally slugged `history` can no longer be **read** through `GET /api/robots/:id/jobs/:slug`; invoking, cancelling and the listing are unaffected. And a run row names its actor by email address, so an end user holding this capability learns which other people have been driving the machine. `robot_id` in the query is shared with the org-wide read; a *different* one here is refused rather than quietly answered about the robot in the path."
+        "description": "Needs the `action_history` capability, and **this route is what makes that switch mean something** — it was unkeepable while nothing durable recorded what had run. Two residuals worth stating rather than implying away. `history` is a syntactically valid slug, and a static segment matches before a parameter, so a robot with a service literally slugged `history` can no longer be **read** through `GET /api/robots/:id/jobs/:slug`; invoking, cancelling and the listing are unaffected. And a run row names its actor by email address, so an end user holding this capability learns which other people have been driving the machine. `robot_id` in the query is shared with the org-wide read; a *different* one here is refused rather than quietly answered about the robot in the path."
       }
     },
     "/api/robots/{id}/jobs/{slug}": {

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 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 two differ: 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 one answer for two states. 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 two differ: 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* — so an unregistered verb and an unknown app would answer identically. 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",
@@ -3788,7 +3788,7 @@
         "validation_error"
       ],
       "transport": "http",
-      "notes": "Needs the `action_history` capability, and **this route is what makes that switch mean something** — it was unkeepable while nothing durable recorded what had run. Two residuals worth stating rather than implying away. `history` is a syntactically valid slug and The router matches a static segment first, so a robot with a service literally slugged `history` can no longer be **read** through `GET /api/robots/:id/jobs/:slug`; invoking, cancelling and the listing are unaffected. And a run row names its actor by email address, so an end user holding this capability learns which other people have been driving the machine. `robot_id` in the query is shared with the org-wide read; a *different* one here is refused rather than quietly answered about the robot in the path."
+      "notes": "Needs the `action_history` capability, and **this route is what makes that switch mean something** — it was unkeepable while nothing durable recorded what had run. Two residuals worth stating rather than implying away. `history` is a syntactically valid slug, and a static segment matches before a parameter, so a robot with a service literally slugged `history` can no longer be **read** through `GET /api/robots/:id/jobs/:slug`; invoking, cancelling and the listing are unaffected. And a run row names its actor by email address, so an end user holding this capability learns which other people have been driving the machine. `robot_id` in the query is shared with the org-wide read; a *different* one here is refused rather than quietly answered about the robot in the path."
     },
     {
       "method": "POST",

package/dist/alerts.d.ts

@@ -53,7 +53,7 @@ import { z } from 'zod';
  * derives it from the document (`alert-definitions.ts`'s `toRowCondition`) and
  * derives it nowhere else.
  *
- * **It was renamed for a wave 4 deletion that did not happen**, and the name
+ * **It was renamed for a deletion that did not happen**, and the name
  * is kept because the distinction it draws is still needed: two condition
  * shapes coexist, and only one of them is authored. Nothing is stored under
  * this shape any more — the database keeps runtime state only — so read `Row`

package/dist/alerts.js

@@ -54,7 +54,7 @@ import { slug } from './common.js';
  * derives it from the document (`alert-definitions.ts`'s `toRowCondition`) and
  * derives it nowhere else.
  *
- * **It was renamed for a wave 4 deletion that did not happen**, and the name
+ * **It was renamed for a deletion that did not happen**, and the name
  * is kept because the distinction it draws is still needed: two condition
  * shapes coexist, and only one of them is authored. Nothing is stored under
  * this shape any more — the database keeps runtime state only — so read `Row`

package/dist/config-issues.d.ts

@@ -150,8 +150,8 @@ 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
+ * A 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

package/dist/config-issues.js

@@ -293,8 +293,8 @@ function valueAt(root, path) {
  * 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
+ * A 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

package/dist/config.d.ts

@@ -74,7 +74,7 @@ export type ParameterType = z.infer<typeof parameterType>;
  *
  * There is no `required` field. A placeholder cannot be left unfilled, so
  * "required" is exactly "has no `default`" — a second spelling of one fact
- * is the defect this file has spent two waves removing.
+ * is the defect this file has been removing a spelling at a time.
  */
 export declare const parameterSpec: z.ZodObject<{
     type: z.ZodEnum<{

package/dist/config.js

@@ -5,8 +5,8 @@ import { applyError, slug, rosName, rosTypeName, fieldPath, SLUG_RULE, ROS_NAME_
  * `alertSeverity` is identical for the stored row and this document-nested
  * definition — `z.enum(['warning', 'error'])`, nothing more to say twice —
  * so it is imported rather than redefined. Not re-exported from here: the
- * barrel already carries it from `alerts.ts`, and wave 4 moves the
- * definition itself into this file once `alerts.ts` retires.
+ * barrel already carries it from `alerts.ts`, and the definition itself moves
+ * into this file once `alerts.ts` retires.
  */
 import { alertSeverity } from './alerts.js';
 /**
@@ -97,8 +97,8 @@ import { alertSeverity } from './alerts.js';
  * says. They are the same sentence, which is the point of there being one.
  *
  * The tense matters because the two states look identical from inside this
- * file. Whoever reads it after wave 3 should find a claim that was true when
- * written and stayed true, not one that quietly became false.
+ * file. Whoever reads it later should find a claim that was true when written
+ * and stayed true, not one that quietly became false.
  *
  * Each one states the rule in words and gives one example, and none of them
  * quotes its own regex — `config-messages.test.ts` asserts that over every
@@ -474,7 +474,7 @@ const PARAMETER_SNIPPET = {
  *
  * There is no `required` field. A placeholder cannot be left unfilled, so
  * "required" is exactly "has no `default`" — a second spelling of one fact
- * is the defect this file has spent two waves removing.
+ * is the defect this file has been removing a spelling at a time.
  */
 export const parameterSpec = strictObject({
     type: parameterType.meta({

package/dist/errors.js

@@ -420,14 +420,14 @@ export const ERROR_CODES = [
      * no producer is not harmless, because a reader arriving at it takes it for
      * a live refusal. Say which it is, and say when it changes.
      *
-     * **It has one producer already, one train early**: `POST /mcp` answers it to
-     * an `mcp_session` token whose subject is an app user, because the central
-     * endpoint serves the team only. No client can hold such a token yet — only
-     * a test mints one — and the per-app train adds the
-     * `appAuthConfig.mcp_enabled` gate this comment describes.
+     * **It has one producer already, ahead of the gate it describes**: `POST
+     * /mcp` answers it to an `mcp_session` token whose subject is an app user,
+     * because the central endpoint serves the team only. No client can hold such
+     * a token yet — only a test mints one — and the `appAuthConfig.mcp_enabled`
+     * gate arrives with the per-app endpoint.
      *
      * `tool_not_available` below still has no producer — `grep` finds it nowhere
-     * in `cloud/src`. Named as unproduced, for the same reason.
+     * in the cloud's source. Named as unproduced, for the same reason.
      */
     'mcp_disabled',
     /**
@@ -536,7 +536,7 @@ export const ERROR_CODES = [
     // what the cloud actually sends.
     //
     // They are listed in one block, with their producer named, rather than filed
-    // among the waves that introduced them — the honest record is *when this list
+    // by the release that introduced each — the honest record is *when this list
     // learned about them*, not when the cloud started sending them.
     /**
      * `409` from the configuration routes: the draft parses as YAML but its root

package/dist/identity.d.ts

@@ -502,8 +502,8 @@ export type IdpIssuer = z.infer<typeof idpIssuer>;
  * The per-app OIDC vocabulary is `clientOidcErrorCode` in `client-auth.ts`: a
  * different list, for a different flow, redirected to the developer's own page
  * rather than rendered by Fleetless. Two callback error enums coexisting is how
- * the wrong one gets picked up by the train that adds per-app OIDC, which is
- * why this one is deleted rather than left standing for it.
+ * the wrong one gets picked up when per-app OIDC arrives, which is why this
+ * one is deleted rather than left standing for it.
  */
 /**
  * `GET /api/auth/me` — named so the console can validate it.

package/dist/identity.js

@@ -479,8 +479,8 @@ export const idpIssuer = z
  * The per-app OIDC vocabulary is `clientOidcErrorCode` in `client-auth.ts`: a
  * different list, for a different flow, redirected to the developer's own page
  * rather than rendered by Fleetless. Two callback error enums coexisting is how
- * the wrong one gets picked up by the train that adds per-app OIDC, which is
- * why this one is deleted rather than left standing for it.
+ * the wrong one gets picked up when per-app OIDC arrives, which is why this
+ * one is deleted rather than left standing for it.
  */
 /**
  * `GET /api/auth/me` — named so the console can validate it.

package/dist/routes.js

@@ -1175,8 +1175,8 @@ export const ROUTES = [
             '\n\n**The `405` is this cloud\'s own answer, not the SDK\'s**, and the two differ: 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 ' +
-            'one answer for two states. Registering the verb lets the endpoint say "this app\'s server is here; this verb is not ' +
+            '`404`, and at a path whose last segment is an app identifier a `404` already means *no such app* — so an unregistered verb and an ' +
+            'unknown app would answer identically. 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 ' +
@@ -1934,8 +1934,8 @@ export const ROUTES = [
         query: jobRunQuery, request: null, response: jobRunListResponse,
         errors: [...CLIENT_GUARD, 'invalid_uuid', 'not_found', 'capability_required', 'validation_error'], transport: 'http',
         notes: 'Needs the `action_history` capability, and **this route is what makes that switch mean something** — it was unkeepable while nothing ' +
-            'durable recorded what had run. Two residuals worth stating rather than implying away. `history` is a syntactically valid slug and ' +
-            'The router matches a static segment first, so a robot with a service literally slugged `history` can no longer be **read** through ' +
+            'durable recorded what had run. Two residuals worth stating rather than implying away. `history` is a syntactically valid slug, and ' +
+            'a static segment matches before a parameter, so a robot with a service literally slugged `history` can no longer be **read** through ' +
             '`GET /api/robots/:id/jobs/:slug`; invoking, cancelling and the listing are unaffected. And a run row names its actor by email address, ' +
             'so an end user holding this capability learns which other people have been driving the machine. `robot_id` in the query is shared with ' +
             'the org-wide read; a *different* one here is refused rather than quietly answered about the robot in the path.',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fleetless/contracts",
-  "version": "1.0.4",
+  "version": "1.0.5",
   "description": "Fleetless wire contracts: the bridge-cloud protocol, the REST API schemas and the error codes, as zod schemas with generated JSON Schema and OpenAPI artifacts.",
   "license": "Apache-2.0",
   "author": "Dehne Robotik GmbH",
@@ -52,6 +52,7 @@
     "test": "vitest run",
     "artifacts": "tsx scripts/export-schemas.ts",
     "test:pack": "node scripts/verify-pack.mjs",
+    "verify:commits": "node scripts/verify-commit-messages.mjs",
     "prepublishOnly": "node scripts/refuse-manual-publish.mjs"
   },
   "dependencies": {