typespec-http-zod 0.1.0 → 0.3.0

package/README.md

@@ -1,24 +1,14 @@
 # typespec-http-zod
 
-Zod validators and framework-free contract types from a TypeSpec HTTP service — agreeing, keyword for
-keyword, with the OpenAPI document [`@typespec/openapi3`](https://typespec.io) publishes from the same
-source.
+Generate Zod validators and framework-free TypeScript types from a TypeSpec HTTP service.
 
-It is a **library and an emitter**. Use the emitter to generate validators for any server — Express,
-Fastify, Elysia, a Workers fetch handler, a typed client — or use the API to build an emitter of your
-own. [`typespec-hono`](https://github.com/bison-digital/typespec-hono) is the second kind, and is
-where the API is proved.
+The emitted validators agree, keyword for keyword, with the OpenAPI document
+[`@typespec/openapi3`](https://typespec.io) publishes from the same source. Use them with Express,
+Fastify, Elysia, a Workers fetch handler, a typed client, or a test suite. No server framework is
+required.
 
-## The governing rule
-
-**If the document cannot say it, the validator must not enforce it.**
-
-A validator that checks something the published contract never states is a rule no caller reading that
-contract can see. This package ships **zero decorators** for exactly that reason — four once existed,
-and every one let a spec state something `@typespec/openapi3` could not publish — and asserts the
-class is empty rather than trusting it. Where openapi3 decides something, its rule is read from its
-source and copied, refusals included: the same spec has to be representable by both emitters or by
-neither, or a differential between them means nothing.
+It is also a library. [`typespec-hono`](https://github.com/bison-digital/typespec-hono) is an emitter
+built on its API.
 
 ## Install
 
@@ -26,28 +16,58 @@ neither, or a differential between them means nothing.
 npm install typespec-http-zod
 ```
 
-⚠️ **A regular dependency, not a dev one, if your application calls `armFor`.** The emitter itself
-runs at build time, and the generated files import only `import type { ResponseArm }` — a type, which
-erases. But [`./runtime`](#answering-a-request) also exports `armFor`, a **function**, and it exists
-precisely so applications do not re-derive OpenAPI's response precedence by hand. An application that
-calls it and installed this package with `--save-dev` typechecks, builds, and runs in development,
-then fails on deploy:
+Install it as a regular dependency if your application calls `armFor`. If you use only the emitted
+validators, a dev dependency is enough. See [installing](docs/guides.md#installing).
+
+Peer dependencies: `@typespec/compiler`, `@typespec/http`, `@typespec/openapi`, and `zod`.
+`@typespec/versioning` and `@typespec/streams` are optional.
+
+## Quick start
 
 ```
-Error [ERR_MODULE_NOT_FOUND]: Cannot find package 'typespec-http-zod'
-    imported from dist/server.js
+main.tsp                  your API definition
+tspconfig.yaml            which emitters to run
+src/
+  generated/              written by `tsp compile`, never edited by hand
+    schemas.gen.ts
+  index.ts                your code
 ```
 
-Measured in a fresh project installed from a `pnpm pack` tarball: identical build output, `pnpm
-install --prod`, **exit 1**; the same bytes with the package in `dependencies`, **exit 0**. If you use
-only the emitted validators and never import `armFor`, `--save-dev` is sufficient.
+### `main.tsp`
+
+```tsp
+import "@typespec/http";
+
+using Http;
+
+@service(#{ title: "Widget API" })
+namespace WidgetApi;
+
+model Widget {
+  id: string;
+
+  @minLength(1)
+  name: string;
+
+  @minValue(0)
+  quantity: int32;
+}
+
+@error
+model NotFound {
+  @statusCode statusCode: 404;
+  code: string;
+  message: string;
+}
+
+@route("/widgets/{widgetId}")
+@get
+op readWidget(@path widgetId: int32): Widget | NotFound;
+```
 
-Peers: `@typespec/compiler`, `@typespec/http`, `@typespec/openapi`, and `zod` (the generated output
-imports it). `@typespec/versioning` and `@typespec/streams` are **optional** — they are resolved
-behind a guarded `import()`, so a spec declaring neither needs neither.
+### `tspconfig.yaml`
 
 ```yaml
-# tspconfig.yaml
 emit:
   - typespec-http-zod
 options:
@@ -55,70 +75,41 @@ options:
     emitter-output-dir: "{project-root}/src/generated"
 ```
 
-## What it emits
+Then run `tsp compile .`.
 
-⚠️ **Only `schemas.gen.ts` is emitted by the configuration above.** The other three are written only
-when `contracts-output-dir` names somewhere to put them — they are the framework-free contract types
-and the assertions that pair them against the validators, and a consumer that wants validators alone
-should not have them appear uninvited. Add it to get all four:
+### `src/generated/schemas.gen.ts` (generated)
 
-```yaml
-# tspconfig.yaml
-emit:
-  - typespec-http-zod
-options:
-  typespec-http-zod:
-    emitter-output-dir: "{project-root}/src/generated"
-    contracts-output-dir: "{project-root}/src/generated"
+```ts
+export const widgetSchema = z.object({
+	id: z.string(),
+	name: z.string().min(1),
+	quantity: z.number().int().min(0),
+});
+
+export const notFoundSchema = z.object({
+	code: z.string(),
+	message: z.string(),
+});
+
+export const readWidgetPath = z.object({
+	widgetId: z.preprocess(decodeNumber, z.number().int()),
+});
+
+export const readWidgetResponses = [
+	{ status: 200, schema: widgetSchema },
+	{ status: 404, schema: notFoundSchema },
+] satisfies readonly ResponseArm[];
 ```
 
-| file                   | what it is                                                                                                                                           | emitted when                     |
-| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- |
-| `schemas.gen.ts`       | every validator: the component schemas, **and** each operation's path, query, header, body and response validators, plus the arms it may answer with | always                           |
-| `requests.gen.ts`      | framework-free contract types — plain TypeScript, no imports, so they cross layers that must not see a validation library                            | `contracts-output-dir` is set    |
-| `vocabularies.gen.ts`  | each enum's members as a runtime tuple, because a generated type cannot be iterated                                                                  | `contracts-output-dir` is set    |
-| `wire-contract.gen.ts` | assertions pairing the emitted Zod against those types, so the two walks cannot disagree silently                                                    | that **and** `contracts-package` |
-
-Per operation you get `readWidgetPath`, `readWidgetQuery`, `readWidgetHeader`, `readWidgetBody`,
-`readWidgetResponse` and `readWidgetResponses` — named from **the operation id the document
-publishes**, which is not always the bare operation name.
-
-⚠️ **An operation inside a namespace is named after the whole id.** `op readWidget` inside
-`namespace Widgets` has operation id `Widgets_readWidget`, so the identifiers are
-`Widgets_readWidgetPath` and so on. Namespaces are the idiomatic way to group routes, so this is the
-common case rather than the exception — read the emitted file for the names rather than assuming
-them.
-
-⚠️ **A validator that is already a component gets no second name.** `readWidgetResponse` is emitted
-only when the response shape needs a name of its own; where the operation answers with a declared
-model the arm refers to that model's schema directly — `widgetSchema`, not `readWidgetResponse`. The
-same holds for a request body: `op createWidget(@body body: WidgetCreate)` is validated by
-`widgetCreateSchema`. The mapping from an operation to the schema that validates it is published
-through the [API](#building-an-emitter-on-this) as `EmittedService.schemaNames`; from the emitted file
-alone, an operation with no `…Body` const is one whose body is a named component.
-
-## Options
-
-| option                 | what it does                                                                                                                                                                                                                                                                                                                                         |
-| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `seal-object-schemas`  | whether a model closed in the spec REJECTS an undeclared property rather than stripping it. ⚠️ **Set this to whatever `@typespec/openapi3`'s option of the same name is set to** — the two emitters answer the same question about the same models and neither can read the other's configuration. Defaults to `false`, which is openapi3's default. |
-| `contracts-output-dir` | where the framework-free contract types go, when they should not sit beside the validators. Omitted, they are not emitted.                                                                                                                                                                                                                           |
-| `contracts-package`    | the specifier the emitted Zod imports shared types from. **No default** — it once defaulted to one repository's package name, so a consumer who configured nothing got validators importing from a package they had never heard of. With none named, enums are emitted inline and the output depends on nothing.                                     |
-| `key-vocabularies`     | models whose PROPERTY NAMES are also emitted as a runtime tuple. For a closed key set that is a contract fact but cannot be a `Record` key type. A name matching no model is reported, not ignored.                                                                                                                                                  |
-| `runtime-module`       | where the generated files import `ResponseArm` from. Defaults to `typespec-http-zod/runtime`.                                                                                                                                                                                                                                                        |
-| `services`             | per-`@service` overrides, keyed by namespace name, for a spec that publishes more than one surface.                                                                                                                                                                                                                                                  |
-
-## Answering a request
-
-No server framework appears below, because none is needed: the emitted validators are plain Zod and
-`./runtime` is two exports. Express, Fastify, Elysia or a bare `fetch` handler each supply the
-`params`/`query`/`body` this reads.
+Path and query values arrive as strings. The emitted validator decodes `"1"` to `1` before the
+schema runs, so hand the raw values straight in.
+
+### `src/index.ts`
 
 ```ts
 import { armFor, type ResponseArm } from "typespec-http-zod/runtime";
-import { Widgets_readWidgetPath, Widgets_readWidgetResponses } from "./generated/schemas.gen.js";
+import { readWidgetPath, readWidgetResponses } from "./generated/schemas.gen.js";
 
-/** Answer a status with a body the document says that status carries. */
 function respond(arms: readonly ResponseArm[], status: number, body: unknown) {
 	const arm = armFor(arms, status);
 	if (arm === undefined) throw new Error(`no declared arm for ${status}`);
@@ -126,143 +117,35 @@ function respond(arms: readonly ResponseArm[], status: number, body: unknown) {
 }
 
 export function readWidget(params: Record<string, unknown>, widget: unknown | undefined) {
-	const parsed = Widgets_readWidgetPath.safeParse(params);
+	const parsed = readWidgetPath.safeParse(params);
 	if (!parsed.success) return { status: 400, body: parsed.error.issues };
+
 	return widget === undefined
-		? respond(Widgets_readWidgetResponses, 404, { code: "not_found", message: "no such widget" })
-		: respond(Widgets_readWidgetResponses, 200, widget);
+		? respond(readWidgetResponses, 404, { code: "not_found", message: "no such widget" })
+		: respond(readWidgetResponses, 200, widget);
 }
 ```
 
-**`armFor` is the whole reason `./runtime` exists.** An operation can declare `404`, `4XX` and
-`default` at once and all three describe a 404. OpenAPI settles it — an explicit code beats a range,
-and `default` is every status not otherwise listed — and a package that emits arms containing `4XX`
-and `default` without shipping the rule for reading them has shipped a footgun. Measured against the
-arms emitted for such an operation:
+`armFor` resolves which arm governs a status, applying OpenAPI's precedence: an exact code first,
+then a range such as `4XX`, then `default`.
 
-| answered | arm chosen | body validated against |
-| -------- | ---------- | ---------------------- |
-| `200`    | `200`      | the success model      |
-| `404`    | `404`      | `NotFound`             |
-| `429`    | `4XX`      | `Throttled`            |
-| `500`    | `default`  | `Unexpected`           |
-
-⚠️ **A path or query value is a string on the wire, and the emitted validators already know.** A
-parameter the document types as `integer` is emitted wrapped in a `z.preprocess` that decodes `"1"`
-to `1` — and **decodes rather than coerces**, so `?limit=` stays empty and fails the schema instead of
-arriving as `0`. A flattened list (`?tags=a,b,c`) is split on the delimiter the document's `style`
-implies before the array schema runs. Hand the raw values straight in; do not pre-parse them.
+## What it emits
 
-## Building an emitter on this
+| file                   | contents                                                                                                  | emitted when                  |
+| ---------------------- | --------------------------------------------------------------------------------------------------------- | ----------------------------- |
+| `schemas.gen.ts`       | component schemas, per-operation path, query, header, body and response validators, and the response arms | always                        |
+| `requests.gen.ts`      | framework-free TypeScript types, with no imports                                                          | `contracts-output-dir` is set |
+| `vocabularies.gen.ts`  | each enum's members as a runtime tuple                                                                    | `contracts-output-dir` is set |
+| `wire-contract.gen.ts` | assertions pairing the emitted Zod against those types                                                    | that and `contracts-package`  |
 
-The exported API — `emitHttpZod`, `EmittedService`, `EmittedRoute`, `collectRoutes` and the rest — is
-what an emitter for another framework calls. `emitHttpZod` returns one `EmittedService` per
-`@service`, and `EmittedService.schemaNames` maps each operation id to the identifiers its validators
-were declared under, so a wrapping emitter imports names rather than agreeing about them.
+Identifiers are named from the operation id the document publishes. An operation inside a namespace
+carries the whole id, so `op readWidget` in `namespace Widgets` becomes `Widgets_readWidgetPath`.
 
-```ts
-const services = await emitHttpZod(context, { defaultRuntimeModule: "my-emitter/runtime" });
-for (const service of services) {
-	for (const route of service.routes) {
-		const names = service.schemaNames.get(route.operationId);
-		// names.path / names.query / names.header / names.body / names.response / names.responses
-	}
-}
-```
+## Docs
 
-⚠️ **`defaultRuntimeModule` is a default, not an override** — a consumer's `runtime-module` still
-wins. It exists so a wrapping emitter whose generated files import more than `ResponseArm` can point
-them at its own module.
-
-## What it refuses, and why
-
-Every refusal is a **diagnostic**, not a thrown error: it points at the offending declaration, carries
-a code you can search for, and does not stop the walk — so one compile names every problem rather
-than the first.
-
-| code                            | why                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
-| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `unsupported-scalar`            | a scalar with no known base and no `@encode`. Give it `extends`, or encode it.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
-| `unsupported-type`              | a construct with no runtime representation — `never` is the reachable case.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
-| `unsupported-default`           | a default value that is neither a scalar nor an empty collection.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
-| `empty-union`                   | a union with no representable variants has nothing to validate against.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
-| `circular-model`                | a cycle closing through a union variant or dictionary value, neither of which is a property a getter can sit on. Ordinary recursion through a model property is fully supported.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
-| `unknown-key-vocabulary`        | a `key-vocabularies` entry naming no model. Reported because the failure mode is silence: a missing vocabulary looks exactly like an empty one.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
-| `unsupported-status-code-range` | OpenAPI keys a range as `1XX`…`5XX`, so `@minValue(494) @maxValue(499)` has nowhere to go. ⚠️ **Refused because `@typespec/openapi3` refuses it**, with the same rule copied from its source. A range covering a bucket exactly — `@minValue(400) @maxValue(499)` — is supported.                                                                                                                                                                                                                                                                                                                                                                                                     |
-| `undeclared-discriminator`      | ⚠️ **Upstream, and not something you can fix with an emitter option.** `@discriminated(#{envelope: "none"})` puts the discriminator inside each variant on the wire, and openapi3 emits `oneOf` with a `discriminator` keyword while never adding that property to the variant schema — which OpenAPI 3.1 forbids ("the `discriminator` field MUST be a required field"). Tracked as [`microsoft/typespec#7141`](https://github.com/microsoft/typespec/issues/7141), open and maintainer-filed. **It is avoidable in your spec**: declare the discriminator on the variant (`model Cat { kind: "cat"; … }`) and openapi3 publishes it as required, with no divergence and no refusal. |
-
-## Known limits
-
-Stated here rather than left as numbers in a baseline file, because a number in a baseline is not a
-stated limitation once a package is published. Each is re-measured by the suite.
-
-- **`format` is deliberately not enforced, and that is now CHECKED rather than counted.** Under JSON
-  Schema 2020-12 `format` is an annotation, not a validation keyword, so turning one into a check
-  would enforce something the document does not assert. 136 annotations go unenforced, and
-  `test/vocabulary.test.ts` refuses any format-derived Zod call as a class — so turning it on breaks a
-  test rather than moving a number.
-- **4 negotiated response bodies cannot be attributed to a single arm.** OpenAPI lists one
-  body per media type against members that each carry their own, so there is no one arm to compare
-  them to. The status-to-body mapping is still graded for them.
-- **4 response bodies reduce to no readable kind on one side** — a stream, or a union. Counted, never
-  silently passed.
-- **A `@head` operation gets validators here and cannot be served by every router.** That is a fact
-  about the server, not about this package — see `typespec-hono`, which refuses it and says why.
-- **`int64` and `uint64` are validated as JavaScript numbers, so values above `2^53-1` are refused —
-  and `@encode(string)` is the fix.** The document publishes `type: integer` with `format: int64`,
-  which states no bound; the emitted `z.number().int()` refuses anything beyond
-  `Number.MAX_SAFE_INTEGER`. That is a constraint the document does not state, and it is kept anyway,
-  because it is imposed by the runtime rather than invented here — **above `2^53-1` an integer is no
-  longer uniquely representable as a JavaScript number**, so a validator cannot certify that the value
-  it holds is the value that was sent. Measured: `9007199254740993` reaches a handler as
-  `9007199254740992`, and int64's maximum as `9223372036854776000`, both through `JSON.parse` before
-  any validator runs. Accepting them would stamp "valid" on a number nobody sent, which is the one
-  answer a validator must never give. `z.int64()` is not an alternative: it is `bigint`-based and
-  `JSON.parse` never produces a `bigint`, so it would refuse every JSON body.
-
-  ⚠️ **TypeSpec's own remedy works and costs one decorator.** `@encode(string) value: int64` emits
-  `z.string()`, and openapi3 publishes `type: string` with `format: int64` — the two agree exactly, and
-  the digits survive the wire intact. Use it for any 64-bit integer whose values can exceed `2^53-1`:
-  identifiers, balances in minor units, timestamps in nanoseconds.
-
-- **The emitted output requires `zod`, not `zod/mini`.** The tree-shakeable variant has no chained
-  methods at all — measured on 4.4.3, `typeof z.string().optional`, `.nullable` and `.min` are each
-  `undefined` — and the emitted validators use `.optional()`, `.nullable()`, `.default()`, `.strict()`,
-  `.loose()` and `.catchall()`. A browser or Workers consumer therefore pays for the full `zod` build.
-  This is a property of the emitted spelling rather than of the schemas, so it is fixable; it is
-  recorded here as a measured fact rather than a plan.
-
-## How it is graded
-
-Nothing here is judged by fixtures we wrote alone.
-
-- **Conformance differential** — both emitters run from ONE compile of
-  [`@typespec/http-specs`](https://www.npmjs.com/package/@typespec/http-specs), Microsoft's own
-  scenario corpus, and the assertion is that the validators say what the document says. Components,
-  request parameters, declared statuses and response bodies. **0 divergences.**
-- **Round-trip against APIs nobody here designed** — the OpenAPI Initiative's teaching example and the
-  Swagger Petstore, converted to TypeSpec and compiled back out, then compared against the originals.
-  **22 operations, none lost, no shape disagreements.** Every other suite measures this emitter
-  against material that already knows about it; this one asks what a first adopter asks. The
-  documents are vendored with digests the suite asserts, never fetched.
-- **Request bodies are compared, and were compared by nothing at all** — 21 by shape and 36 by kind. Parameters were graded and responses were graded; what a caller may SEND, the largest surface of most APIs, had no arm.
-- **Response bodies are compared, not counted** — 24 inline bodies by SHAPE and
-  44 non-object bodies by KIND. This surface was a bare number for a long time, and closing it
-  immediately found three positions where the emitter required a string for a raw binary body the
-  document says nothing about.
-- **`content-type` and `accept` are compared** against the `content` keys that state them — 77
-  positions, no divergences. OpenAPI declares media types through `requestBody.content` and each
-  response's `content` rather than as parameters, so the parameter arm sets these aside; a separate
-  arm compares them where the document actually puts them.
-- **Depth fixtures** for what a protocol corpus does not contain: it declares **no constraints at
-  all**, so `test/reference/constraints.tsp` exercises every constraint keyword once, on the type it
-  is legal on.
-- **Every counting arm has a non-vacuity floor.** An arm that stops firing otherwise reports agreement
-  about nothing, which has happened here and is why the floors exist.
-- **The emitted output is compiled** by the real compiler under `strict` and
-  `exactOptionalPropertyTypes`, because "it emitted" is not "it works".
-- **The package is packed and its tarball inspected**, because `files` is a set of globs and a glob
-  that stops matching is indistinguishable from one that matches nothing.
+- [Guides](docs/guides.md): installing, validating a request, answering with the right body, content
+  types, and building an emitter on the API.
+- [Reference](docs/reference.md): every option, every diagnostic, and the known limits.
 
 ## Licence
 

package/dist/src/api.d.ts

@@ -2,13 +2,13 @@ import { type EmitContext, type Program, type Type } from "@typespec/compiler";
 import { type HttpOperation, type HttpService } from "@typespec/http";
 import { SchemaRegistry } from "./registry.js";
 /**
- * `typespec-http-zod` — Zod validators and framework-free contract types from a TypeSpec HTTP
+ * `typespec-http-zod` - Zod validators and framework-free contract types from a TypeSpec HTTP
  * service, agreeing with the OpenAPI document `@typespec/openapi3` publishes from the same source.
  *
  * **The governing rule: if the document cannot say it, the validator must not enforce it.** A
  * validator that checks something the published contract never states is a rule no caller reading
- * that contract can see. This package ships **zero decorators** for exactly that reason — four were
- * deleted, each of which let a spec state something openapi3 could not publish — and asserts the
+ * that contract can see. This package ships **zero decorators** for exactly that reason - four were
+ * deleted, each of which let a spec state something openapi3 could not publish - and asserts the
  * class is empty rather than trusting it. Where openapi3 decides something, its rule is read from its
  * source and copied, refusals included: the same spec has to be representable by both emitters or by
  * neither, or a differential between them means nothing.
@@ -17,9 +17,9 @@ import { SchemaRegistry } from "./registry.js";
  * self-describes as "highly experimental", and emits a Node.js `http` router. It also answers a
  * different question: this package emits no server at all. Validators are useful to Express, Fastify,
  * Elysia, a Workers fetch handler or a typed client, and a server generator is a thin consumer of
- * them — `typespec-hono` is one.
+ * them - `typespec-hono` is one.
  *
- * **Built on the stable 1.x surface only** — `$onEmit` plus `@typespec/http` — rather than on
+ * **Built on the stable 1.x surface only** - `$onEmit` plus `@typespec/http` - rather than on
  * `@typespec/emitter-framework` (pre-1.0) or `@typespec/asset-emitter`, which announces its own
  * replacement in its package description. Fewer moving parts under something that has to keep working.
  */
@@ -28,15 +28,15 @@ export { $lib } from "./lib.js";
  * The option contract, published so an emitter built on this library can **derive** its own rather
  * than restate it.
  *
- * ⚠️ **Two schemas that have to agree are two lists that will not.** A server generator adds its own
+ * **Two schemas that have to agree are two lists that will not.** A server generator adds its own
  * keys and forwards the rest; if it restates this one, an option added here is silently rejected as
  * unknown by the wrapper, or accepted and never passed on. Neither failure is visible in output.
  */
 export { EmitterOptionsSchema, type EmitterOptions } from "./lib.js";
 /**
- * How a property name is spelled as an object key — quoted only when it has to be.
+ * How a property name is spelled as an object key - quoted only when it has to be.
  *
- * ⚠️ **Published because a consumer emitting code beside these validators has to spell keys the
+ * **Published because a consumer emitting code beside these validators has to spell keys the
  * SAME way, and getting it wrong produces a file that does not parse.** An unquoted
  * `x-ms-test-header` is exactly that, and it happened: a corpus scenario declares one and the
  * emitted module stopped being loadable. This is not a style choice a second emitter may make
@@ -47,7 +47,7 @@ export { objectKey } from "./zod.js";
  * The success status a row registers.
  *
  * An operation declares exactly one success status. A range (`2XX`) or a wildcard is not a status a
- * handler can return, so it is not something this emitter can turn into a `respond()` call — an
+ * handler can return, so it is not something this emitter can turn into a `respond()` call - an
  * operation carrying only those is skipped rather than guessed at.
  */
 export declare function successStatusOf(operation: HttpOperation): number | undefined;
@@ -70,13 +70,13 @@ export type StatusKey = number | "default" | `${1 | 2 | 3 | 4 | 5}XX`;
 /**
  * The body every `@error` response in the service declares, when they all declare the same one.
  *
- * ⚠️ **The emitter does not know what a problem document is, and must not.** This is the general
- * capability — "a service may declare an error response; emit its validator so the runtime can check
- * what it sends" — which is what makes it reusable by any gateway built on this emitter rather than a
+ * **The emitter does not know what a problem document is, and must not.** This is the general
+ * capability - "a service may declare an error response; emit its validator so the runtime can check
+ * what it sends" - which is what makes it reusable by any gateway built on this emitter rather than a
  * CM-shaped special case. RFC 9457 happens to be what `cm-api` puts in that slot.
  *
- * ⚠️ **This used to be an INVARIANT the emitter enforced, and it is now merely an observation.** It
- * reported `mixed-error-bodies` — an error, aborting the compile — whenever a service declared two
+ * **This used to be an INVARIANT the emitter enforced, and it is now merely an observation.** It
+ * reported `mixed-error-bodies` - an error, aborting the compile - whenever a service declared two
  * catch-all bodies, or a specific status whose body neither was nor spread the catch-all one. That
  * was a real constraint while every failure arm carried this single schema; now each declared
  * response resolves its own, and a service answering `404` with `NotFoundError` and everything else
@@ -84,25 +84,25 @@ export type StatusKey = number | "default" | `${1 | 2 | 3 | 4 | 5}XX`;
  *
  * So the refusal is gone, and what remains is a convenience: the module-level `GENERATED_ERROR_SCHEMA`
  * the route table publishes, which exists precisely when the service has one such body. Where it does
- * not, the constant is not emitted — and a consumer importing it gets a missing export, named at the
+ * not, the constant is not emitted - and a consumer importing it gets a missing export, named at the
  * import, which is the honest report of "there is no such thing here".
  */
 export declare function errorBodyOf(program: Program, service: HttpService): Type | undefined;
 /**
  * Whether a body served under these media types is RAW BINARY rather than a JSON value.
  *
- * ⚠️ **The distinction decides whether a validator may say anything about it at all.** A `bytes`
+ * **The distinction decides whether a validator may say anything about it at all.** A `bytes`
  * body inside a JSON payload is base64 and the document publishes `type: "string"` with
  * `contentEncoding`; a `bytes` body served as `application/octet-stream` or `image/png` is the bytes
- * themselves, and `@typespec/openapi3` publishes a schema carrying only `contentMediaType` — which is
+ * themselves, and `@typespec/openapi3` publishes a schema carrying only `contentMediaType` - which is
  * an ANNOTATION under JSON Schema 2020-12, not an assertion. The document therefore states nothing
  * about the value, and a validator that requires a string enforces a rule no caller reading the
  * contract can see.
  *
- * ⚠️ **The same decision was already made for multipart and not for bodies**, which is how the two
+ * **The same decision was already made for multipart and not for bodies**, which is how the two
  * came to disagree: a binary PART is `z.unknown()` because openapi3 publishes `{}` for it, while a
  * binary BODY stayed `z.string()`. Found by grading response-body kinds, a surface that had been
- * counted and never compared — three positions in `encode/bytes`.
+ * counted and never compared - three positions in `encode/bytes`.
  */
 export declare function isRawBinaryMediaType(contentTypes: readonly string[]): boolean;
 export interface EmittedRoute {
@@ -111,35 +111,35 @@ export interface EmittedRoute {
     readonly path: string;
     readonly statusCode: number;
     readonly statusCodes: readonly number[];
-    /** Media types the success body can be served as — the basis for `Accept` negotiation. */
+    /** Media types the success body can be served as - the basis for `Accept` negotiation. */
     readonly responseContentTypes: readonly string[];
     /**
      * Media types the request body may be SENT as.
      *
-     * ⚠️ **This was missing entirely, and its absence was two live defects in the generated server.**
+     * **This was missing entirely, and its absence was two live defects in the generated server.**
      * The response side has carried `responseContentTypes` from the beginning; the request side carried
      * nothing, so a server built on this library had no way to ask what the incoming body actually is.
      * Both consequences were measured against a Petstore server under `wrangler dev`:
      *
      * - every request body was validated as JSON, so a `multipart/form-data` upload was handed to
-     *   `c.req.json()` — 17 such registrations in `payload/multipart` alone, and 11 of the 17 request
+     *   `c.req.json()` - 17 such registrations in `payload/multipart` alone, and 11 of the 17 request
      *   bodies in the Swagger Petstore are not JSON;
      * - a `bytes` body was read with `c.req.text()` whatever it was sent as, which UTF-8-decodes. An
      *   18-byte binary upload arrived at the handler as 23 code points with five bytes replaced by
-     *   U+FFFD — silently corrupted, answering **200**.
+     *   U+FFFD - silently corrupted, answering **200**.
      *
      * A server emitter needs the document's own answer to "what is on the wire", and this is it.
-     * What to DO about it — which validator target, which body reader — belongs to the emitter that
+     * What to DO about it - which validator target, which body reader - belongs to the emitter that
      * writes the server, exactly as `responseContentTypes` leaves negotiation to it.
      */
     readonly requestContentTypes: readonly string[];
     readonly summary: string | undefined;
     readonly requestSchema: string | undefined;
     /**
-     * The parameters, split by WHERE they arrive — see `parameterSchemasOf`.
+     * The parameters, split by WHERE they arrive - see `parameterSchemasOf`.
      *
-     * ⚠️ **A MERGED `paramsSchema` sat beside these and was deleted before 0.1.0 froze the surface.**
-     * It was written on every route and read by nothing — not `nameRouteSchemas`, which declares from
+     * **A MERGED `paramsSchema` sat beside these and was deleted before 0.1.0 froze the surface.**
+     * It was written on every route and read by nothing - not `nameRouteSchemas`, which declares from
      * the split forms, and not the one consumer. Worse, it was computed by a second function under
      * different rules, and both wire fixes the split forms received had been applied only there: it
      * never decoded a path or query value, so `z.number().int()` met `"1"` and refused it, and it keyed
@@ -157,10 +157,10 @@ export interface EmittedRoute {
         readonly value: string;
     } | undefined;
     /**
-     * `undefined` when the operation's success response carries no body — a `204`, or any `@delete`
+     * `undefined` when the operation's success response carries no body - a `204`, or any `@delete`
      * returning `void`.
      *
-     * ⚠️ **This used to be required, and requiring it silently deleted routes.** `collectRoutes`
+     * **This used to be required, and requiring it silently deleted routes.** `collectRoutes`
      * skipped any operation `successBodyOf` could not answer for, with no diagnostic: measured across
      * `@typespec/http-specs`, the document declared 540 operations and this emitter mounted 256, with
      * 282 of the 284 missing ones bodyless. `payload/multipart` produced `GENERATED_ROUTES = []`
@@ -186,7 +186,7 @@ export interface EmittedRoute {
     /**
      * No caller is established, so the operation receives no `ServiceContext`.
      *
-     * Whether a tenant exists follows from whether the request was authenticated — there is no user,
+     * Whether a tenant exists follows from whether the request was authenticated - there is no user,
      * account or membership to build one from otherwise. Reading it here is what lets a server
      * derive an operation's call shape rather than a hand-written table restating it per row.
      */
@@ -194,7 +194,7 @@ export interface EmittedRoute {
     /**
      * The OAuth scopes the operation requires, from `@useAuth`.
      *
-     * ⚠️ **Per operation, never per surface.** A resource-wide list means either one scope for
+     * **Per operation, never per surface.** A resource-wide list means either one scope for
      * everything (a read-only grant could write) or the union of them (a read-only grant could not
      * read), and neither is a grant a human would recognise from the consent screen. Emitted into the
      * row so a server applies the gate the DOCUMENT publishes, rather than a hand-written
@@ -214,7 +214,7 @@ export declare function collectRoutes(program: Program, registry: SchemaRegistry
 /**
  * The identifiers a route's validators are declared under, by what the DOCUMENT calls each one.
  *
- * ⚠️ **Keyed on request locations, not on a router's validator targets.** `@hono/zod-validator`
+ * **Keyed on request locations, not on a router's validator targets.** `@hono/zod-validator`
  * spells these `"param"`, `"query"`, `"header"`, `"json"`; another framework spells them differently
  * or not at all. The location is the contract fact and belongs here; the spelling is the server
  * emitter's, and translating one to the other is a two-line map in the package that knows.
@@ -228,7 +228,7 @@ export interface RouteSchemaNames {
     readonly response: string | undefined;
     readonly alternateResponse: string | undefined;
     /**
-     * The `readonly ResponseArm[]` const — what the operation may answer with, and with which body.
+     * The `readonly ResponseArm[]` const - what the operation may answer with, and with which body.
      *
      * Always present, because every operation declares at least its success status. An operation whose
      * every arm is bodyless still gets the const, carrying `schema: undefined` per arm, which is the
@@ -237,9 +237,9 @@ export interface RouteSchemaNames {
     readonly responses: string;
 }
 /**
- * One `@service`, emitted — and everything a server emitter needs to render a router over it.
+ * One `@service`, emitted - and everything a server emitter needs to render a router over it.
  *
- * ⚠️ **This is the shared seam, and it is deliberately narrow.** It carries no `SchemaRegistry`, no
+ * **This is the shared seam, and it is deliberately narrow.** It carries no `SchemaRegistry`, no
  * import collector, no error schema and no vocabulary map, because measurement said a server
  * generator reads none of them: the registry is never touched once the names are minted, the external
  * imports serve the very declarations that now live in `schemas.gen.ts`, the error schema fed a route
@@ -252,7 +252,7 @@ export interface EmittedService {
     readonly routes: readonly EmittedRoute[];
     /** The identifiers every per-operation validator was declared under, keyed by operation id. */
     readonly schemaNames: ReadonlyMap<string, RouteSchemaNames>;
-    /** Where this service's artefacts were written — a server emitter writes its own beside them. */
+    /** Where this service's artefacts were written - a server emitter writes its own beside them. */
     readonly outputDir: string;
     /** Already resolved through the per-service overrides, so a caller re-reads nothing. */
     readonly options: ResolvedServiceOptions;
@@ -270,13 +270,13 @@ export declare const DEFAULT_RUNTIME_MODULE = "typespec-http-zod/runtime";
 /**
  * What a WRAPPING emitter may change about this one, without changing what a consumer may set.
  *
- * ⚠️ **`defaultRuntimeModule` is a default, not an override.** A consumer's `runtime-module` still
+ * **`defaultRuntimeModule` is a default, not an override.** A consumer's `runtime-module` still
  * wins; this only decides what `schemas.gen.ts` and any file a wrapper emits beside it import from
  * when the consumer says nothing.
  *
- * ⚠️ **It exists because this package's own default is wrong for a wrapper, and shipped that way.**
+ * **It exists because this package's own default is wrong for a wrapper, and shipped that way.**
  * `typespec-hono` emits `import type { AppEnv, Awaitable, Ctx, Result, RouteDeps }` and
- * `import { selectContentType }` from whatever this resolves to. None of those six is exported here —
+ * `import { selectContentType }` from whatever this resolves to. None of those six is exported here -
  * this module exports `ResponseArm` and `armFor`, and nothing else. Worse, `typespec-http-zod` is a
  * TRANSITIVE dependency of a `typespec-hono` consumer, so under a strict `node_modules` the specifier
  * does not resolve at all whatever it exports. Measured in a fresh project installed from tarballs:
@@ -293,7 +293,7 @@ export interface EmitHttpZodOptions {
 /**
  * Emit this library's artefacts for every `@service` in the program, and hand back what was emitted.
  *
- * ⚠️ **The whole orchestration lives here, once.** The nesting below is load-bearing — a walk that
+ * **The whole orchestration lives here, once.** The nesting below is load-bearing - a walk that
  * runs outside `collectExternalImports` throws, vocabularies must be collected from what the service
  * DECLARES rather than from what the Zod walk happens to touch, and the error body has to be
  * registered inside the walk or its validator never reaches `schemas.gen.ts`. An emitter built on this