typespec-hono 0.21.0 → 0.23.0

package/dist/src/emitter.d.ts

@@ -8,8 +8,8 @@ import { type EmitContext } from "@typespec/compiler";
  * forced it to be a `dependency` and made `--save-dev` fail at deploy and nowhere earlier. Emitting
  * the runtime removes the choice rather than documenting it.
  *
- * `typespec-hono/runtime` is still exported, for an application that points `runtime-module` at it
- * deliberately. It is no longer what the generated code reaches for by default.
+ * **Always this module.** `runtime-module` used to replace it, and that made an application own a
+ * copy of generated logic - see the `runtime-module-removed` diagnostic.
  */
-export declare const DEFAULT_RUNTIME_MODULE = "./runtime.gen.js";
+export { DEFAULT_RUNTIME_MODULE } from "./app.js";
 export declare function $onEmit(context: EmitContext): Promise<void>;

package/dist/src/emitter.js

@@ -1,10 +1,9 @@
-import { emitFile, resolvePath } from "@typespec/compiler";
+import { emitFile, NoTarget, resolvePath } from "@typespec/compiler";
 import { readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { emitHttpZod } from "typespec-http-zod";
 import { renderApp } from "./app.js";
 import { resolveBasePath } from "./base-path.js";
-import { securityFor } from "./security.js";
 import { reportDiagnostic } from "./lib.js";
 /**
  * This emitter's entry point. **the whole of `typespec-http-zod`, plus one file**.
@@ -40,27 +39,6 @@ function operationFor(emitted, verb, path) {
 function targetFor(emitted, verb, path) {
     return operationFor(emitted, verb, path)?.operation ?? emitted.service.namespace;
 }
-/**
- * What the generated files import their runtime contract from when the consumer sets nothing.
- *
- * **THIS package's runtime, not the library's, and the distinction is the whole of a defect that
- * shipped.** `app.gen.ts` names `AppEnv`, `Awaitable`, `Ctx`, `Result`, `RouteDeps` and
- * `selectContentType`; every one of them is declared in `src/runtime.ts` here. The library's runtime
- * exports `ResponseArm` and `armFor` and nothing else, and it is a TRANSITIVE dependency of a
- * consumer of this package, so under a strict `node_modules` its specifier does not resolve from
- * consumer code at all.
- *
- * Pointing at `typespec-hono/runtime` fixes both halves at once, because this module RE-EXPORTS
- * `ResponseArm` and `armFor` (see `runtime.ts`), which is what `schemas.gen.ts` imports. One
- * specifier, present in the consumer's own dependency, carrying every name both generated files
- * reference.
- *
- * **Measured in a fresh project installed from `pnpm pack` tarballs, because no test could see it:**
- * every compile in both harnesses sets `runtime-module` explicitly, so the default branch was ungraded
- * across 240 tests. `tsp compile` succeeded with zero diagnostics and `tsc` then reported two
- * `TS2307`s (`Cannot find module 'typespec-http-zod/runtime'`) one in each generated file.
- * `test/adopter.test.ts` is the arm that now opens that branch.
- */
 /** The header the emitted runtime carries, matching every other generated file. */
 function generatedRuntimeBanner(hint) {
     const second = hint === undefined
@@ -68,7 +46,6 @@ function generatedRuntimeBanner(hint) {
         : `// Regenerate with: ${hint}`;
     return `// GENERATED by typespec-hono. DO NOT EDIT.
 ${second}
-// Point \`runtime-module\` at a module of your own to replace it.
 `;
 }
 /**
@@ -80,27 +57,49 @@ ${second}
  * forced it to be a `dependency` and made `--save-dev` fail at deploy and nowhere earlier. Emitting
  * the runtime removes the choice rather than documenting it.
  *
- * `typespec-hono/runtime` is still exported, for an application that points `runtime-module` at it
- * deliberately. It is no longer what the generated code reaches for by default.
+ * **Always this module.** `runtime-module` used to replace it, and that made an application own a
+ * copy of generated logic - see the `runtime-module-removed` diagnostic.
  */
-export const DEFAULT_RUNTIME_MODULE = "./runtime.gen.js";
+export { DEFAULT_RUNTIME_MODULE } from "./app.js";
 /** Where this package's own runtime source lives, to be copied beside the generated code. */
 const RUNTIME_SOURCE = fileURLToPath(new URL("../../src/runtime.ts", import.meta.url));
+/**
+ * The options with `runtime-module` refused and removed, at the top level and per service.
+ *
+ * **Removed, not only reported**, because the library validates nothing about a key it no longer
+ * declares, and a wrapper passing options through should not hand it one.
+ */
+function withoutRuntimeModule(context) {
+    const options = context.options;
+    const refuse = (value) => {
+        reportDiagnostic(context.program, {
+            code: "runtime-module-removed",
+            format: { value: String(value) },
+            target: NoTarget,
+        });
+    };
+    const { "runtime-module": topLevel, services, ...rest } = options;
+    if (topLevel !== undefined)
+        refuse(topLevel);
+    const kept = services === undefined
+        ? undefined
+        : Object.fromEntries(Object.entries(services).map(([name, service]) => {
+            const { "runtime-module": perService, ...others } = service;
+            if (perService !== undefined)
+                refuse(perService);
+            return [name, others];
+        }));
+    return {
+        ...context,
+        options: kept === undefined ? rest : { ...rest, services: kept },
+    };
+}
 export async function $onEmit(context) {
-    for (const emitted of await emitHttpZod(context, {
-        defaultRuntimeModule: DEFAULT_RUNTIME_MODULE,
-    })) {
-        /**
-         * Written only when the generated code actually points at it. An application that sets
-         * `runtime-module` has supplied its own module and must not have a file it did not ask for
-         * appear in its output directory.
-         */
-        if (emitted.options.runtimeModule === DEFAULT_RUNTIME_MODULE) {
-            await emitFile(context.program, {
-                path: resolvePath(emitted.outputDir, "runtime.gen.ts"),
-                content: `${generatedRuntimeBanner(emitted.options.regenerateHint)}${readFileSync(RUNTIME_SOURCE, "utf8")}`,
-            });
-        }
+    for (const emitted of await emitHttpZod(withoutRuntimeModule(context))) {
+        await emitFile(context.program, {
+            path: resolvePath(emitted.outputDir, "runtime.gen.ts"),
+            content: `${generatedRuntimeBanner(emitted.options.regenerateHint)}${readFileSync(RUNTIME_SOURCE, "utf8")}`,
+        });
         /**
          * **The path the DOCUMENT says this service is served under.** An OpenAPI path is relative to
          * its server, so `@server("/api/v1")` plus `/accounts` publishes `/api/v1/accounts`. Mounting at
@@ -136,6 +135,17 @@ export async function $onEmit(context) {
                         target: targetFor(emitted, route.verb, route.path),
                     });
                 },
+                unvalidatedResponseMediaType: (route, status, types) => {
+                    reportDiagnostic(context.program, {
+                        code: "unvalidated-response-media-type",
+                        format: {
+                            operationId: route.operationId,
+                            status: String(status),
+                            types: types.join(", "),
+                        },
+                        target: targetFor(emitted, route.verb, route.path),
+                    });
+                },
                 unvalidatableMediaType: (route, types) => {
                     reportDiagnostic(context.program, {
                         code: "unvalidatable-media-type",
@@ -143,10 +153,7 @@ export async function $onEmit(context) {
                         target: targetFor(emitted, route.verb, route.path),
                     });
                 },
-            }, base.basePaths, (verb, path) => {
-                const operation = operationFor(emitted, verb, path);
-                return operation === undefined ? [] : securityFor(context.program, operation);
-            }),
+            }, base.basePaths),
         });
     }
 }

package/dist/src/lib.d.ts

@@ -13,12 +13,14 @@ import { type EmitterOptions as HttpZodOptions } from "typespec-http-zod";
  * accepted and silently dropped, which produces output that is wrong in a way no test of either
  * package would see. `test/options.test.ts` asserts the forwarding as a CLASS.
  *
- * There is currently nothing to add: `runtime-module` belongs to the library, because the library is
- * what emits the annotated response arms that need it. This type exists as the seam rather than
- * because it carries anything today. The moment a Hono-only option appears it goes here, and the
- * derivation keeps the rest honest.
+ * **`runtime-module` is declared here only to be REFUSED** (`runtime-module-removed`). The library no
+ * longer has the option, and a schema without the key would report only "must NOT have additional
+ * properties", which tells a consumer upgrading from a version that documented the option neither why
+ * nor what to do instead.
  */
 export type EmitterOptions = HttpZodOptions & {
+    /** Refused. See `runtime-module-removed`. */
+    "runtime-module"?: string;
     /**
      * Per-service overrides this emitter adds on top of the library's.
      *
@@ -27,6 +29,7 @@ export type EmitterOptions = HttpZodOptions & {
      */
     services?: Record<string, {
         "emit-server"?: boolean;
+        "runtime-module"?: string;
     }>;
 };
 /**
@@ -54,12 +57,18 @@ declare const EmitterOptionsSchema: JSONSchemaType<EmitterOptions>;
  * exists only in the arrangement that BUILDS the package, and would ship silently.
  */
 type Diagnostics = {
+    "runtime-module-removed": {
+        readonly default: CallableMessage<["value"]>;
+    };
     "unsupported-path-template": {
         readonly default: CallableMessage<["template", "name"]>;
     };
     "unvalidatable-media-type": {
         readonly default: CallableMessage<["operationId", "types"]>;
     };
+    "unvalidated-response-media-type": {
+        readonly default: CallableMessage<["operationId", "status", "types"]>;
+    };
 };
 /**
  * **Annotated rather than inferred, and the reason is a packaging fact rather than a style

package/dist/src/lib.js

@@ -8,9 +8,13 @@ import { EmitterOptionsSchema as httpZodOptions, } from "typespec-http-zod";
  *, never by copying the list.
  */
 const EmitterOptionsSchema = {
-    ...httpZodOptions,
+    type: "object",
+    additionalProperties: false,
+    required: [],
     properties: {
         ...httpZodOptions.properties,
+        // Accepted by the schema so that setting it reaches `runtime-module-removed`.
+        "runtime-module": { type: "string", nullable: true },
         /**
          * **Spread from the library's own entry rather than restated**, so a per-service option added
          * there still validates here. Only `emit-server` is added.
@@ -23,6 +27,7 @@ const EmitterOptionsSchema = {
                 properties: {
                     ...httpZodOptions.properties.services.additionalProperties.properties,
                     "emit-server": { type: "boolean", nullable: true },
+                    "runtime-module": { type: "string", nullable: true },
                 },
                 required: [],
             },
@@ -73,6 +78,41 @@ const diagnostics = {
             default: paramMessage `'${"operationId"}' declares request media types this emitter cannot validate (${"types"}). Requests carrying them are refused rather than validated. Declare a media type with a parser -- JSON, multipart or urlencoded -- or handle the body yourself with '@body body: bytes'.`,
         },
     },
+    /**
+     * `runtime-module` is set, and this emitter no longer substitutes its runtime.
+     *
+     * **The option made an application OWN a copy of generated logic**, because the generated server
+     * imported the application's types from the same module as content negotiation, the HEAD guard and
+     * arm selection. So every consumer that needed its own caller context or result shape copied those
+     * too, and the copies aged: one gateway ran a runtime eleven releases behind the emitter, carrying a
+     * negotiation defect long since fixed.
+     *
+     * Nothing the option was for needs it now. The caller context is inferred from `deps.context`, the
+     * Hono environment is an interface an application augments, and what a handler returns is the union
+     * of the responses the document declares. **An error rather than a warning**, because the option's
+     * value is ignored, and an emitter that silently ignores a setting produces output its author did
+     * not ask for.
+     */
+    "runtime-module-removed": {
+        severity: "error",
+        messages: {
+            default: paramMessage `'runtime-module' is set to '${"value"}', and typespec-hono no longer substitutes its runtime: 'runtime.gen.ts' is always emitted. Remove the option and delete the module it pointed at. The caller context is inferred from 'deps.context', the Hono environment is augmented with 'declare module "./runtime.gen.js" { interface AppEnv { ... } }', and a handler returns '{ status, body, headers }' for any response the document declares. See the Upgrading section of docs/guides.md.`,
+        },
+    },
+    /**
+     * A response the handler supplies as text, served without being checked against its schema.
+     *
+     * A model declared under a media type that is not JSON - a `Pet` as `application/xml` - has no
+     * serialisation this emitter can derive from the document, so the handler returns the text and the
+     * route serves it as is. Reported for the same reason as its request-side twin: a route should not
+     * look validated when it is not.
+     */
+    "unvalidated-response-media-type": {
+        severity: "warning",
+        messages: {
+            default: paramMessage `'${"operationId"}' answers ${"status"} as ${"types"}, which this emitter cannot serialise from the schema. The handler returns that body as text and it is served without being validated. Declare a JSON media type, or a string body, to have it checked.`,
+        },
+    },
     "unsupported-path-template": {
         severity: "warning",
         messages: {

package/dist/src/runtime.d.ts

@@ -1,5 +1,5 @@
 import type { Context, Env, Input, MiddlewareHandler } from "hono";
-import type { ZodType } from "zod";
+import type { output, ZodError, ZodType } from "zod";
 /**
  * One arm of an operation's declared response set, as the document publishes it.
  *
@@ -13,39 +13,17 @@ export interface ResponseArm {
     readonly status: number | "default" | `${1 | 2 | 3 | 4 | 5}XX`;
     readonly schema: ZodType | undefined;
     /**
-     * The media types this response offers, where the document names MORE than one.
-     *
-     * Absent where it names one, which is what an application already assumes, so "one type" and
-     * "not carried" are the same state rather than two to tell apart. Present, it is the set to
-     * negotiate against: `selectContentType` takes the caller's `Accept` and these.
+     * Every media type this response offers, including a single one. Absent where there is no body.
      */
     readonly contentTypes?: readonly string[];
     /**
-     * The headers this response declares, as the document publishes them.
-     *
-     * **Two names, because two different things need them.** `name` is the WIRE name, which is what
-     * the response sets; `property` is the name on the value the handler returned, which is where the
-     * value is read from. `@header("x-correlation-id") correlationId: string` is `x-correlation-id`
-     * on the wire and `correlationId` in the result, and they differ for any header with a hyphen.
-     *
-     * Absent where the response declares none.
+     * The headers this response declares, by the WIRE name the response sets. `optional` is the
+     * document's `required: false`. Absent where the response declares none.
      */
     readonly headers?: readonly {
         readonly name: string;
-        readonly property: string;
+        readonly optional: boolean;
     }[];
-    readonly when?: {
-        readonly property: string;
-        /**
-         * **A number too, because a `@statusCode` union selects by the status itself.**
-         *
-         * `model Created { @statusCode statusCode: 200 | 201 }` names the property that chooses, and
-         * its values are the statuses. The discriminator case carries a boolean or string literal off
-         * the body instead; both are the same question - which arm did the handler mean - so both use
-         * this one field.
-         */
-        readonly value: boolean | number | string;
-    };
 }
 /**
  * The arm that applies to a status, preferring an exact code, then its `NXX` range, then `default`.
@@ -78,30 +56,38 @@ export type SecurityRequirement = Readonly<Record<string, readonly string[]>>;
  * assertion invented to put the guarantee back.
  *
  * What is left for the app to supply is genuinely app-specific: how a request becomes a caller's
- * context, and how a result becomes a response. Everything else, routing, validation, which
- * validator applies to which target, what status each arm answers, is generated.
+ * context, and what a refusal looks like. Everything else, routing, validation, which validator
+ * applies to which target, which statuses an operation may answer with and how each one is served,
+ * is generated.
  */
 /**
- * How an operation's return value is wrapped.
+ * The Hono environment the generated server mounts on.
  *
- * Identity by default, so an operation may simply return its value. An app with a result envelope
- * points `runtime-module` at its own module and re-declares this as, say, `ServiceResult<T>`, which
- * is what keeps the generated `Operations` interface concretely typed end to end instead of falling
- * back to `unknown` and reintroducing the cast this whole change exists to delete.
- */
-export type Result<T> = T;
-/**
- * The Hono environment the generated server mounts on, and the caller context its operations take.
+ * **An interface, so an application AUGMENTS it rather than replacing this module.**
+ *
+ * ```ts
+ * declare module "./generated/runtime.gen.js" {
+ * 	interface AppEnv {
+ * 		Bindings: { BACKEND: Service<Backend> };
+ * 		Variables: { principal: Principal };
+ * 	}
+ * }
+ * ```
  *
- * **Concrete on purpose.** Making `registerRoutes` generic over the environment does not work:
- * Hono narrows `Context` per route and its conditional types cannot reduce
- * `IfAnyThenEmptyObject<E extends Env ? ...>` while `E` is an unbound parameter, so nothing the app
- * supplies is ever assignable and every call site needs a cast. Naming the types here instead, an
- * app points `runtime-module` at its own module and re-declares them, keeps every generated call
- * site concrete and cast-free. Identity defaults, so an app with neither can ignore both.
+ * That is the idiom Hono itself uses for `ContextVariableMap`, and it is what lets this module be
+ * emitted beside the generated code on every compile instead of being copied into an application and
+ * aged there. A copy was the only other way to name an environment: a gateway ran a runtime from
+ * `0.10.1` while the emitter reached `0.21.0`, carrying a content-negotiation defect fixed eleven
+ * releases earlier.
+ *
+ * **Concrete rather than a type parameter of `registerRoutes`, and that was measured twice.** Hono
+ * narrows `Context` per route, and its conditional types cannot reduce
+ * `IfAnyThenEmptyObject<E extends Env ? ...>` while `E` is an unbound parameter, so nothing an
+ * application supplies is ever assignable and every call site needs a cast. Confirmed again on hono
+ * 4.13.1 with TypeScript 7.0.2: three `TS2345`s on a three-route probe.
  */
-export type AppEnv = Env;
-export type Ctx = unknown;
+export interface AppEnv extends Env {
+}
 /** Anything an operation may hand back: the value, or a promise of it. */
 export type Awaitable<T> = T | Promise<T>;
 /**
@@ -157,20 +143,76 @@ export declare function selectContentType(accept: string | undefined, offered: r
  */
 export declare const headOnly: MiddlewareHandler;
 /**
- * **The request-body middleware used to live here, and it moved into `app.gen.ts`.**
+ * **A route whose template writes a query string, `/items?fixed=true{&param}`, is only that route when
+ * the request carries it.** A router matches paths, so the pairs are checked here, and a request
+ * without them gets the 404 any unrouted request gets, through whatever `app.notFound()` the
+ * application has set. In the runtime for the same reason as {@link headOnly}.
+ */
+export declare const literalQuery: (pairs: readonly (readonly [string, string])[]) => MiddlewareHandler;
+/**
+ * A response body that does not match the schema the document publishes for its status.
  *
- * `byContentType` and `optionalBody` were exported from this module and imported by the generated
- * server, which made them part of a SECOND contract this package has: what an application that
- * points `runtime-module` at a module of its own must export. That contract is easy to break without
- * noticing, and it was the reason a required single-media-type body kept `zValidator` - whose
- * `HTTPException` on an unreadable body is a `text/plain` 400 raised before `deps.invalid`, escaping
- * the app's error envelope. Routing those through `byContentType` closed the gap in one line and
- * made that export mandatory for every substituting app: measured, 15 arms red.
+ * **Thrown, so an application decides what a contract failure answers with in `app.onError`**,
+ * which is where Hono puts that decision. Before this existed every consumer made the same check in
+ * its own `respond` and answered differently - a 500, a 502, a 502 with the issues in the body, a 502
+ * with them redacted - and only one of them checked failure bodies at all.
  *
- * Emitting the middleware instead closes the gap and SHRINKS the runtime contract by these two
- * names. Nothing generated imports them, so keeping them here would leave a second implementation of
- * body reading that nothing exercises - which is how two copies of one rule drift apart.
+ * `issues` are Zod's, so they carry paths and codes. They also carry the offending VALUES; an
+ * application that logs them should decide whether its responses may contain anything it would not
+ * log.
  */
+export declare class ResponseContractError extends Error {
+    readonly operationId: string;
+    readonly status: number;
+    readonly issues: ZodError["issues"];
+    constructor(operationId: string, status: number, issues: ZodError["issues"]);
+}
+/**
+ * A handler answered with a status its operation does not declare.
+ *
+ * **Unreachable from a typed handler.** The generated `Operations` interface types every result as
+ * the union of the declared statuses, so a literal outside it does not compile. This is what a CAST
+ * produces, or a result that crossed a boundary the type system cannot see into, such as untyped
+ * data from a service binding. Thrown rather than served, because serving it would publish a status
+ * the contract does not state.
+ */
+export declare class UndeclaredStatusError extends Error {
+    readonly operationId: string;
+    readonly result: unknown;
+    constructor(operationId: string, result: unknown);
+}
+/**
+ * The body a response SERVES: what the handler returned, parsed against the schema the document
+ * publishes for that status.
+ *
+ * **What is served is the PARSED value, not the one the handler returned.** A schema that strips
+ * undeclared keys therefore strips them from the wire too, which is how an internal field such as a
+ * tenant id is kept out of a response the document does not publish it in. Seven of the nine
+ * consumer surfaces surveyed relied on exactly that, each in its own hand-written `respond`.
+ *
+ * Synchronous, because nothing this emitter writes is asynchronous - `test/sync.test.ts` asserts it
+ * over the whole corpus - and the asynchronous path costs 2.6x per parse.
+ */
+export declare function servedBody<S extends ZodType>(schema: S, value: unknown, operationId: string, status: number): output<S>;
+/**
+ * Declared response headers, as the strings a response carries.
+ *
+ * An optional header the handler did not supply is omitted rather than sent as `"undefined"`, and a
+ * typed value - a `retry-after` declared `int32` - is written as its text. Hono's `HeaderRecord`
+ * refuses `undefined`, so dropping it here is also what keeps the generated call sites free of a
+ * conditional per header.
+ */
+export declare function headersOf(declared: Readonly<Record<string, unknown>>): Record<string, string>;
+/**
+ * Whether a media type a handler answers with lies inside a range the document offers.
+ *
+ * **A range is not a type a response can be sent as**, so where a status offers `image/*` the handler
+ * names the concrete type, and its result type already refuses one outside the range. This is what a
+ * CAST reaches, or data from a service binding: `text/html` under `image/*`, or `image/*` itself,
+ * would otherwise be served with a `Content-Type` the document does not permit. Type names compare
+ * case-insensitively (RFC 9110 section 8.3.1), and parameters such as `charset` are allowed.
+ */
+export declare function mediaTypeWithin(served: string, range: string): boolean;
 /**
  * What the app provides. One object, passed once, rather than a module the generated file imports by
  * path. A generated server that hard-codes `../../backend.js` is only usable by the project it was
@@ -181,26 +223,25 @@ export declare const headOnly: MiddlewareHandler;
  * so a hook typed against a single `Context<E>` is not assignable at any real call site. Making the
  * hooks generic lets the app write functions that ignore both, without a cast anywhere.
  *
- * **`E` and `C` are PARAMETERS, and they have to be.** The defaults keep the bare `RouteDeps` the
- * generated server writes working for an app that substitutes nothing. An app that substitutes
- * anything binds them once, `export type RouteDeps = BaseRouteDeps<AppEnv, Ctx>` in the module it
- * points `runtime-module` at, and every hook is then typed against its own environment and its own
- * caller context.
+ * **`C` is the caller context, and `registerRoutes` INFERS it from `context`.** An application that
+ * returns a `Caller` from `context` has handlers typed `(ctx: Caller, input)`, with nothing to
+ * declare. It used to be a type an application re-declared in a substituted copy of this module.
  *
- * Re-exporting this interface unparameterised instead does not work, and the reason is not obvious:
- * **Hono's `Context` is INVARIANT in its environment**, because `Context.set` takes `E` as an
- * argument. So `Context<AppEnv, ...>` is not assignable to `Context<Env, ...>` however plain the
- * substituted environment is, and every generated `deps.*` call site fails. Separately, `context`
- * would keep returning the identity `Ctx` (`unknown`) which the app's own handlers then reject.
- * Measured before this was parameterised: **19 errors on a four-operation service.**
+ * **Nothing here renders a successful response, and that is the point.** Which statuses an operation
+ * may answer with, which body each one carries and how it is serialised are all things the document
+ * states, so the generated route does them. A `respond` hook used to be handed every arm and the
+ * handler's result, and every application re-implemented the choice by hand: five status-mapping
+ * tables across the consumers surveyed, none consulting the arms, one sending a declared 404 as 400.
+ * What remains are the refusals that happen before a handler runs, whose envelope only the
+ * application knows.
  */
-export interface RouteDeps<E extends Env = AppEnv, C = Ctx> {
+export interface RouteDeps<E extends Env = AppEnv, C = unknown> {
     /**
      * The gate the DOCUMENT publishes, as middleware.
      *
      * **Which scopes an operation demands is a contract fact; how a token is verified is not.**
      * `@useAuth(OAuth2Auth<...>)` reaches OpenAPI as `security` per operation, so the requirement is
-     * generated and this implements the check. The same split as `context` and `respond`. Emitted
+     * generated and this implements the check. The same split as `context`. Emitted
      * only where the operation declares scopes, which is why an internal surface with none is
      * unaffected.
      *
@@ -222,9 +263,17 @@ export interface RouteDeps<E extends Env = AppEnv, C = Ctx> {
     /**
      * The caller's context, or `null` when there is none to establish.
      *
-     * `authentication` is what the DOCUMENT says, and only that: `"none"` where the operation
-     * declares `@useAuth(NoAuth)` (`security: []` in OpenAPI) and `"required"` otherwise. Deciding
-     * it at generation time is the point: the gate the document publishes is the gate that runs.
+     * `authentication` is what the DOCUMENT says, and only that:
+     *
+     * - `"none"`: no requirement asks for anything (`@useAuth(NoAuth)`, or no authentication at all);
+     * - `"optional"`: an anonymous alternative sits beside a real one (`NoAuth | BearerAuth`), so
+     *   `authorize` has admitted this caller either way and a presented credential should still be
+     *   read;
+     * - `"required"`: every alternative asks for something.
+     *
+     * **`"optional"` is new, and without it the middle case was reported as `"none"`**, so a caller
+     * with a valid token on an optional route was never established as a caller. Deciding it at
+     * generation time is the point: the gate the document publishes is the gate that runs.
      *
      * **It used to be `"none" | "account" | "resource"`, and the last two were an invention.** They
      * were chosen by whether the path had parameters, which no OpenAPI keyword expresses and which
@@ -232,7 +281,7 @@ export interface RouteDeps<E extends Env = AppEnv, C = Ctx> {
      * nothing published is the defect class this emitter exists to remove, so it is gone. An app that
      * needs the distinction can read the request, which is the one thing it definitely has.
      */
-    readonly context: <P extends string, I extends Input>(c: Context<E, P, I>, authentication: "none" | "required") => C | null;
+    readonly context: <P extends string, I extends Input>(c: Context<E, P, I>, authentication: "none" | "optional" | "required") => C | null;
     /** The response when `context` returns `null`. */
     readonly noContext: <P extends string, I extends Input>(c: Context<E, P, I>) => Response;
     /**
@@ -253,9 +302,4 @@ export interface RouteDeps<E extends Env = AppEnv, C = Ctx> {
     readonly invalid: <P extends string, I extends Input>(result: {
         readonly success: boolean;
     }, c: Context<E, P, I>) => Response | undefined;
-    /**
-     * Turn an operation's result into a response, checked against the schema the document publishes
-     * for the arm that applies. A bodyless success is an arm whose `schema` is `undefined`.
-     */
-    readonly respond: <P extends string, I extends Input>(c: Context<E, P, I>, arms: readonly ResponseArm[], result: unknown) => Awaitable<Response>;
 }