@fleetless/contracts 1.0.0 → 1.0.3

package/dist/jobs.js

@@ -2,16 +2,16 @@
 import { z } from 'zod';
 import { slug, wireSeqCursor, wireTimestampMs } from './common.js';
 /**
- * Jobs (spec §6.1, §11.3): one running unit of work on a robot — an action
+ * Jobs: one running unit of work on a robot — an action
  * goal or a service call — with an id both sides know, so bridge and cloud
  * stay in sync across a disconnect.
  *
  * Two rules shape everything here:
  *
- * 1. **State is observed by slug, not by id.** The id is informative (§11.3);
- *    a client watches `robot × slug` and sees whatever job is running there,
- *    which is also why every observer of a slug sees the same job.
- * 2. **`lost` is a real outcome and must be said out loud** (§6.1). Job state
+ * 1. **State is observed by slug, not by id.** The id is informative; a client
+ *    watches `robot × slug` and sees whatever job is running there, which is
+ *    also why every observer of a slug sees the same job.
+ * 2. **`lost` is a real outcome and must be said out loud.** Job state
  *    lives only in the bridge's memory; if it restarts mid-job, the results
  *    are gone. The cloud then marks the job `lost` — never leaves it reading
  *    "running" because nobody contradicted it. A system that reports a
@@ -37,17 +37,17 @@ export const job = z.object({
         description: 'When this job last changed, as an ISO 8601 timestamp.',
     }),
     /**
-     * A monotonic counter, ascending in mint order (W7), and the **named**
-     * tiebreaker for any listing that claims an order.
+     * A monotonic counter, ascending in mint order, and the **named** tiebreaker
+     * for any listing that claims an order.
      *
      * `started_at` is not a total order: two jobs minted in the same millisecond
      * sort against each other arbitrarily, and arbitrarily means *differently on
      * each query* — so `GET /api/robots/:id/jobs`, which documents "newest
-     * first", can show one twice and the other not at all. Exactly the defect
-     * `auditEvent.seq` was added for in W6b, in a route the same wave shipped.
+     * first", can show one twice and the other not at all. `auditEvent.seq`
+     * exists for the same reason on the audit log.
      *
      * **Scoped honestly: per cloud process, per run.** Job state lives in memory
-     * (§6.1 — that is why `lost` exists at all), so this counter restarts when
+     * — that is why `lost` exists at all — so this counter restarts when
      * the cloud does, alongside the jobs it orders. Sound, because it only ever
      * orders jobs that coexist in one registry — and stated, because a reader
      * who assumed `auditEvent.seq`'s durable semantics would be wrong.
@@ -62,14 +62,10 @@ export const job = z.object({
      * Present on `failed`; a human message, plus a code where one exists.
      *
      * `details` exists because a refusal that carries only prose forces every
-     * consumer to parse it. W6b shipped `job_queue_full` with a documented
-     * `{limit, queued}` payload and **nowhere to put it**: the bridge reports a
-     * full queue as a job error, this shape had no `details`, and so the numbers
-     * were formatted into the message and lost. The console then rendered a
-     * "wait for one of N to finish" alert from a shape nothing in the system
-     * produced, and its test built that shape by hand — three repos agreeing
-     * with each other about a payload none of them exchanged (Momus, W6b
-     * review).
+     * consumer to parse it. A documented payload with nowhere to put it — the
+     * bridge reports a full queue as a job error — ends up formatted into the
+     * message and lost, and every consumer then builds the structured shape by
+     * hand from its own assumption.
      *
      * Optional, because most job errors have nothing structured to add. Where a
      * code has a documented payload — `job_queue_full` has
@@ -95,8 +91,8 @@ export const job = z.object({
 /**
  * One update about a job, pushed to subscribers of its slug.
  *
- * `timestamp_ms` is the bridge's capture time, exactly as for a datapoint
- * (§6.3 says action feedback carries it too) — so a client computes the age
+ * `timestamp_ms` is the bridge's capture time, exactly as for a datapoint —
+ * action feedback carries it too — so a client computes the age
  * of a progress report the same way it computes the age of a sensor value,
  * and a burst of late-delivered feedback after a reconnect is visibly late
  * rather than looking current.
@@ -113,15 +109,14 @@ export const jobEvent = z.object({
     timestamp_ms: z.number().int().nonnegative(),
 });
 /**
- * What a busy refusal tells the caller (spec §11.3: "inkl. Information, was
- * läuft"). A refusal that only says "busy" forces the caller to guess whether
- * to wait or to give up.
+ * What a busy refusal tells the caller: what is already running. A refusal that
+ * only says "busy" forces the caller to guess whether to wait or to give up.
  */
 export const busyDetails = z.object({
     running: job,
 });
 /**
- * What a `publisher_busy` refusal tells the caller (spec §6.4).
+ * What a `publisher_busy` refusal tells the caller.
  *
  * "Another caller is publishing and has not been quiet long enough" names a
  * state and no action: the caller does not know how much longer, because
@@ -140,7 +135,7 @@ export const publisherBusyDetails = z.object({
     retry_after_ms: z.number().int().nonnegative(),
 });
 /**
- * What a `job_queue_full` refusal tells the caller (W6b).
+ * What a `job_queue_full` refusal tells the caller.
  *
  * Both numbers, not just the limit: `limit` alone says how big the queue is
  * and nothing about whether waiting will help, and `queued` alone cannot be
@@ -171,7 +166,7 @@ export const JOB_RUN_RETENTION_DAYS = 90;
  * invites every reader to handle it.
  *
  * **`app_user` is what a client-app caller writes now, and `end_user` stays**
- * (app-user auth, D1). The seam this comment used to describe — two names for
+ * identity spaces. The seam this comment used to describe — two names for
  * two ways into one merged pool — is settled: the two identity spaces are
  * separate tables again, and `app_user` is a row in `app_users`, belonging to
  * exactly one app. `end_user` is kept for the same reason `auditActor.kind`
@@ -197,10 +192,10 @@ export const jobActor = z.object({
 });
 export const jobRunKind = z.enum(['action', 'service']);
 /**
- * One durable record of one invocation (spec `2026-08-20-timeseries-and-run-history`,
- * D2). One row per run, never one per event: the per-event timeline's write rate
+ * One durable record of one invocation. One row per run, never one per event:
+ * the per-event timeline's write rate
  * is set by the bridge, and a throttled log that cannot say it was throttled is
- * the instrument this codebase refuses everywhere else. The live timeline is
+ * an instrument that cannot say what it does not know. The live timeline is
  * delivered in full by realtime, for as long as somebody is watching.
  */
 export const jobRun = z.object({

package/dist/mcp.d.ts

@@ -1,9 +1,9 @@
+// SPDX-License-Identifier: Apache-2.0
 import { z } from 'zod';
 /**
- * The MCP server of §17: **one** remote MCP endpoint for the whole platform,
- * whose tools are the exposed services and datapoints the signed-in user's
- * roles permit. The per-app `/mcp/<identifier>` servers this file once
- * described were deleted by the org-central identity redesign (D5/D6).
+ * The MCP server: **one** remote MCP endpoint for the whole platform, whose
+ * tools are the exposed services and datapoints the signed-in user's roles
+ * permit. There is no per-app endpoint.
  *
  * **This file describes the seam, not the protocol.** The MCP messages
  * themselves (`initialize`, `tools/list`, `tools/call`) are defined by the
@@ -15,8 +15,8 @@ import { z } from 'zod';
  * an end user ever connects.
  */
 /**
- * The protocol revision W7c speaks. Chosen with André on 2026-08-18 over the
- * newer `2026-07-28`.
+ * The protocol revision this server speaks, chosen over the newer
+ * `2026-07-28`.
  *
  * This is the latest revision the **stable** MCP TypeScript SDK ships, and it
  * negotiates down to `2024-11-05`, so it covers the AI tools that exist today.
@@ -24,11 +24,10 @@ import { z } from 'zod';
  * Streamable HTTP's session ids, the standalone SSE channel and resumability,
  * and servers speaking only it answer `405` to GET and DELETE.
  *
- * **Which is why this server is stateless anyway.** Building sessions we would
- * have to delete again is work in the wrong direction, and a per-process
- * session map is the assumption that breaks at the second cloud instance —
- * the register already carries one row of exactly that shape
- * (`max_realtime_connections`), and W8 is where a second instance appears.
+ * **Which is why this server is stateless anyway.** Building sessions that a
+ * later revision removes is work in the wrong direction, and a per-process
+ * session map is an assumption that breaks the moment a second cloud instance
+ * exists.
  */
 export declare const MCP_PROTOCOL_VERSION: "2025-11-25";
 /**
@@ -37,7 +36,7 @@ export declare const MCP_PROTOCOL_VERSION: "2025-11-25";
  *
  * **Not parameterised, and that is now a statement rather than the absence of
  * one.** The central endpoint serves the org's team with the console tool
- * family (2026-09-05, D7); an app's users reach a different endpoint, whose
+ * family; an app's users reach a different endpoint, whose
  * path `mcpAppEndpointPath` builds. Two constants for two audiences, so a call
  * site says which it means instead of an argument deciding it.
  *
@@ -49,7 +48,7 @@ export declare const MCP_PROTOCOL_VERSION: "2025-11-25";
  */
 export declare const MCP_ENDPOINT_PATH: "/mcp";
 /**
- * The path of **one app's** MCP server (D7) — what an app user pastes into
+ * The path of **one app's** MCP server — what an app user pastes into
  * their AI tool, served only while the app's `appAuthConfig.mcp_enabled` is on.
  *
  * A helper rather than a template literal at four call sites, for
@@ -73,7 +72,7 @@ export declare const MCP_ENDPOINT_PATH: "/mcp";
 export declare function mcpAppEndpointPath(appIdentifier: string): string;
 /**
  * **Every path one app's MCP server answers on, built from its identifier
- * once** (D7).
+ * once**.
  *
  * Six strings, and each of them is spelled in at least three places that
  * cannot see one another: the cloud registers the route, the console renders a
@@ -144,7 +143,7 @@ export declare const MCP_TOOL_NAME_MAX = 128;
 export declare const mcpToolNamePattern: RegExp;
 /**
  * One exposure of a robot, as `robot_describe` and the console's per-role
- * preview list it (FL-006). Every exposure the role grants is listed —
+ * preview list it. Every exposure the role grants is listed —
  * a missing `description` is shown as `null`, never used to hide the entry.
  *
  * `input_schema` is a JSON Schema document generated from an action's,

package/dist/mcp.js

@@ -2,10 +2,9 @@
 import { z } from 'zod';
 import { slug } from './common.js';
 /**
- * The MCP server of §17: **one** remote MCP endpoint for the whole platform,
- * whose tools are the exposed services and datapoints the signed-in user's
- * roles permit. The per-app `/mcp/<identifier>` servers this file once
- * described were deleted by the org-central identity redesign (D5/D6).
+ * The MCP server: **one** remote MCP endpoint for the whole platform, whose
+ * tools are the exposed services and datapoints the signed-in user's roles
+ * permit. There is no per-app endpoint.
  *
  * **This file describes the seam, not the protocol.** The MCP messages
  * themselves (`initialize`, `tools/list`, `tools/call`) are defined by the
@@ -17,8 +16,8 @@ import { slug } from './common.js';
  * an end user ever connects.
  */
 /**
- * The protocol revision W7c speaks. Chosen with André on 2026-08-18 over the
- * newer `2026-07-28`.
+ * The protocol revision this server speaks, chosen over the newer
+ * `2026-07-28`.
  *
  * This is the latest revision the **stable** MCP TypeScript SDK ships, and it
  * negotiates down to `2024-11-05`, so it covers the AI tools that exist today.
@@ -26,11 +25,10 @@ import { slug } from './common.js';
  * Streamable HTTP's session ids, the standalone SSE channel and resumability,
  * and servers speaking only it answer `405` to GET and DELETE.
  *
- * **Which is why this server is stateless anyway.** Building sessions we would
- * have to delete again is work in the wrong direction, and a per-process
- * session map is the assumption that breaks at the second cloud instance —
- * the register already carries one row of exactly that shape
- * (`max_realtime_connections`), and W8 is where a second instance appears.
+ * **Which is why this server is stateless anyway.** Building sessions that a
+ * later revision removes is work in the wrong direction, and a per-process
+ * session map is an assumption that breaks the moment a second cloud instance
+ * exists.
  */
 export const MCP_PROTOCOL_VERSION = '2025-11-25';
 /**
@@ -39,7 +37,7 @@ export const MCP_PROTOCOL_VERSION = '2025-11-25';
  *
  * **Not parameterised, and that is now a statement rather than the absence of
  * one.** The central endpoint serves the org's team with the console tool
- * family (2026-09-05, D7); an app's users reach a different endpoint, whose
+ * family; an app's users reach a different endpoint, whose
  * path `mcpAppEndpointPath` builds. Two constants for two audiences, so a call
  * site says which it means instead of an argument deciding it.
  *
@@ -51,7 +49,7 @@ export const MCP_PROTOCOL_VERSION = '2025-11-25';
  */
 export const MCP_ENDPOINT_PATH = '/mcp';
 /**
- * The path of **one app's** MCP server (D7) — what an app user pastes into
+ * The path of **one app's** MCP server — what an app user pastes into
  * their AI tool, served only while the app's `appAuthConfig.mcp_enabled` is on.
  *
  * A helper rather than a template literal at four call sites, for
@@ -97,7 +95,7 @@ export const MCP_TOOL_NAME_MAX = 128;
 export const mcpToolNamePattern = /^[a-z0-9][a-z0-9_-]*$/;
 /**
  * One exposure of a robot, as `robot_describe` and the console's per-role
- * preview list it (FL-006). Every exposure the role grants is listed —
+ * preview list it. Every exposure the role grants is listed —
  * a missing `description` is shown as `null`, never used to hide the entry.
  *
  * `input_schema` is a JSON Schema document generated from an action's,

package/dist/oauth.d.ts

@@ -1,6 +1,7 @@
+// SPDX-License-Identifier: Apache-2.0
 import { z } from 'zod';
 /**
- * **OAuth 2.1, and it remains only for MCP** (2026-09-05 app-user-auth, D8).
+ * **OAuth 2.1, and it remains only for MCP.**
  *
  * This file used to describe two front doors: an app's end users signing in
  * through a Fleetless-hosted, app-branded login page, and MCP clients signing
@@ -82,15 +83,11 @@ export type OauthError = z.infer<typeof oauthError>;
 /**
  * A redirect URI, and the rule is stricter than "a URL".
  *
- * **The defence for this was already written down in this codebase, twice.**
- * `config.ts` validates a V4L2 device path from the wire with a prefix rule
- * *and* an explicit refusal of `..` segments, tested, with the reasoning
- * recorded; W7's review then found a `package://` traversal in the bridge
- * that the same rule would have prevented, and the finding that mattered was
- * not the traversal but that **the rule existed one file over and was never
- * carried across.** A redirect URI is the same shape of problem from a less
- * trusted source: an attacker-supplied string that decides where a credential
- * is sent.
+ * **The same defence is written down elsewhere in this package.** `config.ts`
+ * validates a capture-device path from the wire with a prefix rule *and* an
+ * explicit refusal of `..` segments. A redirect URI is the same shape of
+ * problem from a less trusted source: an attacker-supplied string that decides
+ * where a credential is sent.
  *
  * Matching at the server is **exact string comparison against a registered
  * value** — never a prefix, never a wildcard host, never "starts with". A
@@ -124,7 +121,7 @@ export declare const MCP_DCR_MAX_REDIRECT_URIS = 5;
  * authorization servers understand**, central and per-app.
  *
  * **Not `.strict()`, and that is the schema agreeing with the server rather
- * than a gap in it.** §3.1 obliges a registration endpoint to ignore metadata
+ * than a gap in it.** RFC 7591 §3.1 obliges a registration endpoint to ignore metadata
  * it does not understand, and real MCP clients send `client_uri`, `logo_uri`,
  * `software_id` and `contacts`. A strict shape here would describe a `400`
  * that no conforming client ever earns, and would take the whole
@@ -132,9 +129,8 @@ export declare const MCP_DCR_MAX_REDIRECT_URIS = 5;
  * are therefore stripped by this schema and ignored by the server, which is
  * the same answer said twice.
  *
- * **The server still reads the body field by field** (`registerMcpDynamicClient`
- * in `cloud/src/mcp-oauth-core.ts`), and the reason is the error vocabulary,
- * not the shape: §3.2.2 distinguishes `invalid_redirect_uri` from
+ * **The server still reads the body field by field**, and the reason is the
+ * error vocabulary, not the shape: RFC 7591 §3.2.2 distinguishes `invalid_redirect_uri` from
  * `invalid_client_metadata`, and one `safeParse` failure cannot say which of
  * the two a caller earned. So this schema is what the endpoint *accepts*, and
  * the handler is what turns a miss into the right RFC code.
@@ -176,10 +172,9 @@ export type DynamicClientRegistrationResponse = z.infer<typeof dynamicClientRegi
  * **The MCP token endpoint's request — one grant, because the servers serve
  * one.**
  *
- * Both authorization servers, central and per-app, exchange through
- * `exchangeMcpAuthorizationCode` (`cloud/src/mcp-oauth-core.ts`), whose first
- * act is to refuse anything but `authorization_code` before a single lookup
- * happens. There is no refresh grant here: a session ends when its token
+ * Both authorization servers, central and per-app, exchange through one
+ * implementation, whose first act is to refuse anything but
+ * `authorization_code` before a single lookup happens. There is no refresh grant here: a session ends when its token
  * expires and the client signs in again.
  *
  * **This was a `discriminatedUnion` with a `refresh_token` branch, and that
@@ -262,11 +257,10 @@ export type AuthorizationServerMetadata = z.infer<typeof authorizationServerMeta
 /**
  * RFC 9728 — what a *resource* publishes about who may authorize for it.
  *
- * W7b mints tokens bound to a resource that W7c builds. **A minting mechanism
- * with no validator is the failure mode this project has now met twelve times
- * in one wave: a check that cannot fail.** So W7b also ships a resource that
- * *rejects* a token whose audience names something else, and the gate measures
- * the rejection rather than the presence of the claim.
+ * Tokens are minted bound to a resource. **A minting mechanism with no
+ * validator is a check that cannot fail**, so the resource itself *rejects* a
+ * token whose audience names something else, and that rejection is what a check
+ * measures rather than the presence of the claim.
  */
 export declare const protectedResourceMetadata: z.ZodObject<{
     resource: z.ZodURL;
@@ -307,7 +301,7 @@ export type OauthRedirectResponse = z.infer<typeof oauthRedirectResponse>;
  * shape and the documentation, not the error path.
  *
  * **Four route entries point at it**: `GET /mcp/oauth/authorize` and
- * `GET /mcp/:appIdentifier/oauth/authorize` (D7), which read the same wire.
+ * `GET /mcp/:appIdentifier/oauth/authorize`, which read the same wire.
  * They spent a release naming nothing — the app-level `/oauth/authorize` this
  * was written for was deleted, and `query: null` was read as "there is no
  * query here" rather than as "the handler reads it by hand" — and the eight
@@ -330,10 +324,10 @@ export type OauthAuthorizeQuery = z.infer<typeof oauthAuthorizeQuery>;
  *
  * It carried one parameter, `app_identifier`, on the argument that RFC 7591's
  * registration body has no field for it and one endpoint could serve every
- * app. It was kept — explicitly, in its own doc comment — "for the per-app MCP
- * registration the MCP train adds (D7), which needs exactly this parameter".
+ * app. It was kept — explicitly, in its own doc comment — for a per-app MCP
+ * registration that was said to need exactly this parameter.
  *
- * **That train shipped and needed no such parameter.** `POST
+ * **That registration shipped and needed no such parameter.** `POST
  * /mcp/:appIdentifier/oauth/register` puts the app in the **path**, built by
  * `MCP_APP_PATHS`, and `resolveAppMcpTarget` reads it from `request.params`;
  * `registerMcpDynamicClient` never looks at a query at all. So the one reason

package/dist/oauth.js

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: Apache-2.0
 import { z } from 'zod';
 /**
- * **OAuth 2.1, and it remains only for MCP** (2026-09-05 app-user-auth, D8).
+ * **OAuth 2.1, and it remains only for MCP.**
  *
  * This file used to describe two front doors: an app's end users signing in
  * through a Fleetless-hosted, app-branded login page, and MCP clients signing
@@ -77,8 +77,8 @@ export const oauthError = z.object({
      * makes the two indistinguishable to the caller, and *a field that cannot
      * express a distinction produces a workaround somewhere else*. Answering in
      * `apiError` instead would keep the distinction and hand an RFC-compliant
-     * client a body it cannot parse — which is the conformance this wave exists
-     * to provide.
+     * client a body it cannot parse, which is the conformance this dialect
+     * exists to provide.
      *
      * So both: `error` is what a standard client reads, `fleetless_code` is what
      * our own tooling switches on. RFC 6749 §5.2 permits additional members, and
@@ -89,15 +89,11 @@ export const oauthError = z.object({
 /**
  * A redirect URI, and the rule is stricter than "a URL".
  *
- * **The defence for this was already written down in this codebase, twice.**
- * `config.ts` validates a V4L2 device path from the wire with a prefix rule
- * *and* an explicit refusal of `..` segments, tested, with the reasoning
- * recorded; W7's review then found a `package://` traversal in the bridge
- * that the same rule would have prevented, and the finding that mattered was
- * not the traversal but that **the rule existed one file over and was never
- * carried across.** A redirect URI is the same shape of problem from a less
- * trusted source: an attacker-supplied string that decides where a credential
- * is sent.
+ * **The same defence is written down elsewhere in this package.** `config.ts`
+ * validates a capture-device path from the wire with a prefix rule *and* an
+ * explicit refusal of `..` segments. A redirect URI is the same shape of
+ * problem from a less trusted source: an attacker-supplied string that decides
+ * where a credential is sent.
  *
  * Matching at the server is **exact string comparison against a registered
  * value** — never a prefix, never a wildcard host, never "starts with". A
@@ -111,8 +107,7 @@ export const redirectUri = z
     .refine((v) => {
     // Parsed, not prefix-matched. `startsWith('https://')` alone accepts the
     // literal string `https://` and anything else that merely opens with
-    // those characters — a shape check standing in for a value check, which
-    // is the failure this project keeps meeting under other names.
+    // those characters — a shape check standing in for a value check.
     let url;
     try {
         url = new URL(v);
@@ -133,7 +128,7 @@ export const redirectUri = z
     // yields `"["` for `[::1]:8080`, because an IPv6 literal is *made of*
     // colons. So `[::1]` never matched the allow-list it is named in, in any
     // spelling, while two developer-facing messages went on saying it was
-    // permitted. Found by Momus-W7b, reproduced against the live server.
+    // permitted.
     // `hostname` already strips the port and keeps the brackets.
     if (url.protocol === 'http:')
         return ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname);
@@ -162,7 +157,7 @@ export const MCP_DCR_MAX_REDIRECT_URIS = 5;
  * authorization servers understand**, central and per-app.
  *
  * **Not `.strict()`, and that is the schema agreeing with the server rather
- * than a gap in it.** §3.1 obliges a registration endpoint to ignore metadata
+ * than a gap in it.** RFC 7591 §3.1 obliges a registration endpoint to ignore metadata
  * it does not understand, and real MCP clients send `client_uri`, `logo_uri`,
  * `software_id` and `contacts`. A strict shape here would describe a `400`
  * that no conforming client ever earns, and would take the whole
@@ -170,9 +165,8 @@ export const MCP_DCR_MAX_REDIRECT_URIS = 5;
  * are therefore stripped by this schema and ignored by the server, which is
  * the same answer said twice.
  *
- * **The server still reads the body field by field** (`registerMcpDynamicClient`
- * in `cloud/src/mcp-oauth-core.ts`), and the reason is the error vocabulary,
- * not the shape: §3.2.2 distinguishes `invalid_redirect_uri` from
+ * **The server still reads the body field by field**, and the reason is the
+ * error vocabulary, not the shape: RFC 7591 §3.2.2 distinguishes `invalid_redirect_uri` from
  * `invalid_client_metadata`, and one `safeParse` failure cannot say which of
  * the two a caller earned. So this schema is what the endpoint *accepts*, and
  * the handler is what turns a miss into the right RFC code.
@@ -237,10 +231,9 @@ export const dynamicClientRegistrationResponse = z.object({
  * **The MCP token endpoint's request — one grant, because the servers serve
  * one.**
  *
- * Both authorization servers, central and per-app, exchange through
- * `exchangeMcpAuthorizationCode` (`cloud/src/mcp-oauth-core.ts`), whose first
- * act is to refuse anything but `authorization_code` before a single lookup
- * happens. There is no refresh grant here: a session ends when its token
+ * Both authorization servers, central and per-app, exchange through one
+ * implementation, whose first act is to refuse anything but
+ * `authorization_code` before a single lookup happens. There is no refresh grant here: a session ends when its token
  * expires and the client signs in again.
  *
  * **This was a `discriminatedUnion` with a `refresh_token` branch, and that
@@ -359,11 +352,10 @@ export const authorizationServerMetadata = z.object({
 /**
  * RFC 9728 — what a *resource* publishes about who may authorize for it.
  *
- * W7b mints tokens bound to a resource that W7c builds. **A minting mechanism
- * with no validator is the failure mode this project has now met twelve times
- * in one wave: a check that cannot fail.** So W7b also ships a resource that
- * *rejects* a token whose audience names something else, and the gate measures
- * the rejection rather than the presence of the claim.
+ * Tokens are minted bound to a resource. **A minting mechanism with no
+ * validator is a check that cannot fail**, so the resource itself *rejects* a
+ * token whose audience names something else, and that rejection is what a check
+ * measures rather than the presence of the claim.
  */
 export const protectedResourceMetadata = z.object({
     resource: z.url().meta({
@@ -404,14 +396,13 @@ export const oauthRedirectResponse = z.object({
  * differently, and it worked — but every path it held belonged to the app-level
  * OAuth flow (`authorize`, `token`, `register`, `consent`, `login`,
  * `impersonate`, `idpCallback`) or to the stub resource's metadata documents,
- * and OAuth 2.1 now remains only for MCP (D8). The MCP authorization server
- * builds its own paths in `cloud/src/routes/mcp-oauth.ts`, where they are read
- * by one file rather than by two repositories.
+ * and OAuth 2.1 now remains only for MCP. The MCP authorization server builds
+ * its own paths, where they are read by one file rather than by two.
  *
- * Deleted rather than left with the four entries whose routes this train also
- * removes, because that is precisely the defect this constant was created after
- * and then reproduced: its `idpStart` entry named a route the cloud had deleted
- * and stood for months with nothing noticing. A constant whose every value
+ * Deleted rather than left holding entries whose routes are gone, which is the
+ * defect it was created to prevent and then reproduced: an entry naming a route
+ * the server had deleted stood for months with nothing noticing. A constant
+ * whose every value
  * names a deleted route is that failure at full size.
  */
 /**
@@ -427,7 +418,7 @@ export const oauthRedirectResponse = z.object({
  * shape and the documentation, not the error path.
  *
  * **Four route entries point at it**: `GET /mcp/oauth/authorize` and
- * `GET /mcp/:appIdentifier/oauth/authorize` (D7), which read the same wire.
+ * `GET /mcp/:appIdentifier/oauth/authorize`, which read the same wire.
  * They spent a release naming nothing — the app-level `/oauth/authorize` this
  * was written for was deleted, and `query: null` was read as "there is no
  * query here" rather than as "the handler reads it by hand" — and the eight
@@ -461,10 +452,9 @@ export const oauthAuthorizeQuery = z
     // **No `scope`, because this authorization server issues none.** The field
     // was here describing itself as "carried onto the interaction and read
     // again at consent"; neither authorize handler reads it, the interaction
-    // row has no column for it, and the consent screen answers `scopes: []`
-    // from a comment that says so in as many words
-    // (`cloud/src/routes/client-mcp-interactions.ts`). A parameter documented
-    // as carried and in fact dropped is worse than one that is absent.
+    // row has no column for it, and the consent screen answers `scopes: []`.
+    // A parameter documented as carried and in fact dropped is worse than one
+    // that is absent.
 })
     .meta({
     description: 'The authorization request an MCP client sends, per RFC 6749 §4.1.1 with mandatory PKCE. The handler reads it parameter by parameter rather than through one parse, because the answers differ: `client_id` and `redirect_uri` are refused flat, with no redirect, since until both are confirmed there is no trusted target to bounce a browser to, and everything after them is reported to the client\'s own callback as query parameters.',
@@ -474,10 +464,10 @@ export const oauthAuthorizeQuery = z
  *
  * It carried one parameter, `app_identifier`, on the argument that RFC 7591's
  * registration body has no field for it and one endpoint could serve every
- * app. It was kept — explicitly, in its own doc comment — "for the per-app MCP
- * registration the MCP train adds (D7), which needs exactly this parameter".
+ * app. It was kept — explicitly, in its own doc comment — for a per-app MCP
+ * registration that was said to need exactly this parameter.
  *
- * **That train shipped and needed no such parameter.** `POST
+ * **That registration shipped and needed no such parameter.** `POST
  * /mcp/:appIdentifier/oauth/register` puts the app in the **path**, built by
  * `MCP_APP_PATHS`, and `resolveAppMcpTarget` reads it from `request.params`;
  * `registerMcpDynamicClient` never looks at a query at all. So the one reason