typespec-http-zod 0.1.0

package/dist/src/registry.js

@@ -0,0 +1,421 @@
+import { getVisibilitySuffix, Visibility } from "@typespec/http";
+import { reportDiagnostic } from "./lib.js";
+import { propertyToTs, typeToTsBody, withTsRefResolver } from "./types.js";
+import { captureBackEdges, currentVisibility, isTransformedBy, noteBackEdge, propertyToZod, typeToZodBody, withRefResolver, withSyntheticDeclarations, } from "./zod.js";
+/**
+ * Assigns each named TypeSpec model/enum a single Zod declaration, emitted in dependency order.
+ *
+ * Without this, a model used by twelve operations is inlined twelve times: the generated file grows
+ * quadratically, and — worse — the *type* it infers is a fresh structural type at each site, so
+ * `apps/web` gets twelve `Company`s that are only accidentally the same. One declaration per model
+ * is what makes the emitted types usable as a shared vocabulary rather than as twelve coincidences.
+ */
+/**
+ * A cycle that reaches a declaration through nothing that can defer it.
+ *
+ * ⚠️ **A recursive model is NOT this.** `model InnerModel { children?: InnerModel[] }` is an ordinary
+ * tree — `@typespec/openapi3` publishes a self-`$ref` for it and the document is valid — so it is
+ * emitted as a reference, made lazy by a getter on the property that closes the loop (see
+ * `modelToZod`). This placeholder is only for a cycle with no property on its path: a named **union**
+ * whose variant refers back to a model that is still being rendered has nowhere to hang a getter, so
+ * the reference cannot be deferred and the declaration would read itself while initialising.
+ *
+ * Reported rather than thrown, so the walk names every such cycle instead of dying inside the first.
+ */
+const CYCLE_PLACEHOLDER_SCHEMA = "z.never()";
+function reportCycle(program, type, name) {
+    reportDiagnostic(program, { code: "circular-model", target: type, format: { name } });
+}
+/**
+ * The name an ANONYMOUS payload model inherits from the single model it spreads.
+ *
+ * ⚠️ **`@typespec/http` hands back a synthesised model for a body whose declaration carried
+ * metadata**, and it has no name — so `@error model InvalidAuth { @statusCode _: 403; error: string }`
+ * reached the registry as `{error}` with `name: ""`, was inlined at its use site, and produced **no
+ * validator at all** for a component the document publishes as `InvalidAuth`. Four authentication
+ * scenarios, each with an unvalidated 403.
+ *
+ * `@typespec/openapi3` never meets that model: it works from the TypeSpec type and strips metadata
+ * itself, which is why its component keeps the original name. This recovers the same name from
+ * `sourceModels`, so both artefacts call the shape the same thing.
+ *
+ * ⚠️ **Only a PURE spread of one named model.** `{...A, extra: string}` is a different shape and must
+ * not claim `A`'s name — so every property has to come from the source. Metadata-stripping removes
+ * properties and never adds them, which is exactly the asymmetry this tests for. A collision would be
+ * caught by the differential's `component-name-collision` arm regardless.
+ */
+function spreadSourceOf(type, seen = new Set(), 
+/**
+ * The properties the ORIGINAL type has, carried down the chain rather than re-derived.
+ *
+ * ⚠️ **Re-deriving them at each link is what blocked `Alias.InnerModel`.** The intermediate model
+ * an operation builds holds the spread body's properties AND the operation's own `@path` and
+ * `@header` parameters, so checking THAT set against the named ancestor fails on properties the
+ * body never had. The question is whether every property of the shape being named comes from the
+ * ancestor — `{name}` does — not whether some intermediate did.
+ *
+ * The guard is unchanged in what it refuses: `{...A, extra}` still fails, because `extra` is in
+ * the original set and not in `A`.
+ */
+required = [...type.properties.keys()]) {
+    if (seen.has(type))
+        return undefined;
+    const sources = type.sourceModels;
+    if (sources.length !== 1)
+        return undefined;
+    const source = sources[0];
+    if (source === undefined || source.usage !== "spread")
+        return undefined;
+    const model = source.model;
+    if (model.templateMapper !== undefined)
+        return undefined;
+    for (const property of required) {
+        if (!model.properties.has(property))
+            return undefined;
+    }
+    /**
+     * ⚠️ **Follow the chain through ANONYMOUS links.** TypeSpec puts an unnamed model between an
+     * operation's parameter model and the model that was spread into it, so stopping at the first
+     * source finds `""` and gives up — measured: the bodies for `Alias.InnerModel` and
+     * `Model.CompositeRequestMix` both reported `sources: [{ usage: "spread", name: "" }]` while the
+     * document published both as components, and the one case that already worked
+     * (`Model.BodyParameter`) was the one whose source happened to be named directly.
+     *
+     * Terminating on an unnamed source with no named ancestor is what keeps a spread ALIAS inline:
+     * OpenAPI names a component for a spread model and not for an alias, and following the chain
+     * reproduces that distinction rather than asserting it.
+     */
+    return model.name === "" ? spreadSourceOf(model, new Set([...seen, type]), required) : model;
+}
+const spreadSourceName = (type) => spreadSourceOf(type)?.name;
+/** A type earns a name when the spec gave it one — anonymous shapes stay inline where they are used. */
+function declaredNameOf(type) {
+    if (type.kind === "Enum")
+        return type.name;
+    /**
+     * A named union earns a declaration too.
+     *
+     * Without this a union request body is inlined at its use site, so it exports no type — and
+     * `backend/contract.ts` and the wire assertions both pair a model with a schema **by name**. A
+     * cross-field rule modelled as a discriminated union (which is how `@refine` is being replaced)
+     * would silently stop being checked at the boundary.
+     */
+    if (type.kind === "Union")
+        return type.name === undefined ? undefined : type.name;
+    if (type.kind !== "Model")
+        return undefined;
+    // `Array`/`Record` are TypeSpec's built-in generic containers, not names worth exporting.
+    if (type.name === "Array" || type.name === "Record")
+        return undefined;
+    if (type.name === "")
+        return spreadSourceName(type);
+    /**
+     * ⚠️ **A template INSTANTIATION carries the template's name, and it is not a declaration.**
+     *
+     * `PublicSuccess<PublicCompanyDetail>` and `PublicSuccess<PublicOfficers>` are both called
+     * `PublicSuccess`, so naming them would export eleven consts called `publicSuccessSchema` — the
+     * file does not compile, and if it did, one shape would validate every response. `@typespec/openapi3`
+     * inlines instantiations for the same reason (the public document has no `PublicSuccess*`
+     * component), so both artefacts agree about what has a name and what does not.
+     *
+     * Invisible until a spec uses a template; a paged-response envelope is the usual first one.
+     */
+    if (type.templateMapper !== undefined)
+        return undefined;
+    return type.name;
+}
+const lowerFirst = (value) => value.charAt(0).toLowerCase() + value.slice(1);
+/**
+ * One model can need MORE THAN ONE declaration.
+ *
+ * ⚠️ **Keyed on `(type, visibility)`, because a model is not one shape.** `@visibility` and HTTP
+ * metadata both mean the same declaration projects differently by position: `@typespec/openapi3`
+ * emits `VisibilityModel` and `VisibilityModelCreate` as separate components for exactly this
+ * reason. Keyed on the type alone, whichever position was walked first won and every other position
+ * silently got its shape — measured on the corpus, one strict model carrying all six lifecycle
+ * properties, so a create request was required to send read-only fields.
+ *
+ * The suffix rule is openapi3's: canonical (`Read`) keeps the bare name, and another visibility only
+ * earns a suffix when the model is actually TRANSFORMED at it. Same rule, so the identifiers line up
+ * with the component names the document publishes.
+ */
+function keyFor(type, visibility) {
+    /**
+     * ⚠️ **Keyed on the SPREAD SOURCE where there is one, or one component gets two declarations.**
+     *
+     * `@typespec/http` synthesises a fresh anonymous model per position, so two operations taking the
+     * same body produce two distinct types that both resolve to the name `BodyModel` — and
+     * `parameters/body-optionality` emitted `export const bodyModelSchema` twice, a file that does not
+     * parse. The document has exactly one `BodyModel` component; collapsing onto the source is what
+     * makes the two artefacts agree about how many things there are.
+     */
+    const canonical = canonicalTypeFor(type);
+    return `${String(visibility)}\u0000${String(canonical.name ?? "")}\u0000${identityOf(canonical)}`;
+}
+/** The model an anonymous payload stands for, so every projection of it shares one declaration. */
+function canonicalTypeFor(type) {
+    if (type.kind !== "Model" || type.name !== "")
+        return type;
+    return spreadSourceOf(type) ?? type;
+}
+/** A stable per-type identity, since two models can share a name across namespaces. */
+const identities = new WeakMap();
+let nextIdentity = 0;
+function identityOf(type) {
+    const existing = identities.get(type);
+    if (existing !== undefined)
+        return existing;
+    nextIdentity += 1;
+    identities.set(type, nextIdentity);
+    return nextIdentity;
+}
+export class SchemaRegistry {
+    #program;
+    #declarations = new Map();
+    #order = [];
+    /** Key → the identifier it is *going* to bind, so a back edge can name a declaration in flight. */
+    #inProgress = new Map();
+    constructor(program) {
+        this.#program = program;
+    }
+    /**
+     * The Zod expression for a type — a bare identifier once the type has a declaration, otherwise
+     * inline source. Declaring is depth-first so a model's dependencies are emitted above it, which is
+     * what lets the generated file be plain `const` declarations with no forward references.
+     */
+    expressionFor(type) {
+        const bare = declaredNameOf(type);
+        if (bare === undefined)
+            return this.#inline(type);
+        /**
+         * ⚠️ **A type not reshaped at this visibility IS the canonical declaration — not a copy of it.**
+         *
+         * Keying on the requested visibility while only suffixing transformed types produced two cache
+         * entries sharing one identifier, and the emitted file stopped parsing:
+         * `Identifier 'approvalTierSchema' has already been declared`. An enum is the same enum in a
+         * request and a response. Collapsing onto `Read` first is what makes the key and the name agree,
+         * and it is the same collapse openapi3 performs before naming a component.
+         */
+        const requested = currentVisibility();
+        const at = type.kind === "Model" &&
+            requested !== Visibility.Read &&
+            isTransformedBy(this.#program, type, requested)
+            ? requested
+            : Visibility.Read;
+        const key = keyFor(type, at);
+        const existing = this.#declarations.get(key);
+        if (existing !== undefined)
+            return existing.identifier;
+        /**
+         * ⚠️ **A declaration already in flight is REFERENCED, not re-entered.**
+         *
+         * Returning the identifier is what turns a recursive model into the self-`$ref` the document
+         * publishes. The back edge is noted so the enclosing object knows to defer it behind a getter —
+         * and if nothing does, {@link captureBackEdges} below still sees it and the cycle is named.
+         */
+        const pending = this.#inProgress.get(key);
+        if (pending !== undefined) {
+            noteBackEdge();
+            return pending;
+        }
+        const name = `${bare}${at === Visibility.Read ? "" : getVisibilitySuffix(at, Visibility.Read)}`;
+        const identifier = `${lowerFirst(name)}Schema`;
+        this.#inProgress.set(key, identifier);
+        const rendered = captureBackEdges(() => this.#inline(type));
+        this.#inProgress.delete(key);
+        /**
+         * A back edge that survived the whole body reached this declaration by a path with no object
+         * property on it — a named union variant, or a dictionary value — so nothing could make it
+         * lazy and the emitted `const` would read itself while initialising.
+         */
+        if (rendered.deferred)
+            reportCycle(this.#program, type, bare);
+        const source = rendered.deferred ? CYCLE_PLACEHOLDER_SCHEMA : rendered.value;
+        const declaration = {
+            identifier,
+            typeName: name,
+            source,
+        };
+        this.#declarations.set(key, declaration);
+        this.#order.push(declaration);
+        this.#declareRelatives(type);
+        return declaration.identifier;
+    }
+    /**
+     * Declare the BASE CHAIN a component's own declaration implies.
+     *
+     * ⚠️ **Reachability from an operation is not the same set the document publishes.** openapi3 emits
+     * a component for every base in an `allOf` chain whether or not an operation names it, so `Pet` and
+     * `Cat` — bases of a `Siamese` that IS named — had no validator at all while the document declared
+     * them.
+     *
+     * ⚠️ **Subtypes are deliberately NOT walked here, because nothing would be walking them.** A
+     * discriminated base renders as `z.discriminatedUnion` over its subtypes, and rendering that
+     * already asks the registry for each one. A loop here looked load-bearing and was measured not to
+     * be: removing it left all 23 polymorphism and differential arms green.
+     *
+     * ⚠️ **Wrapped in {@link captureBackEdges} and the result discarded.** This call can land on a
+     * declaration still in flight — a subtype's base is, by construction, the model that asked for it —
+     * and that is not a reference in anyone's emitted expression. Letting the back edge escape would
+     * have the enclosing declaration report a cycle it does not have and emit `z.never()`.
+     */
+    #declareRelatives(type) {
+        if (type.kind !== "Model" || type.baseModel === undefined)
+            return;
+        const base = type.baseModel;
+        captureBackEdges(() => this.expressionFor(base));
+    }
+    /**
+     * The Zod for a single property, constraints and optionality included.
+     *
+     * Used for path/query parameters, which are `ModelProperty`s that belong to no model — so they
+     * need the property-level walk rather than the type-level one, or `@minLength` on a path param
+     * would be documented and never enforced.
+     */
+    expressionForProperty(property) {
+        return withRefResolver((candidate) => {
+            if (declaredNameOf(candidate) === undefined)
+                return undefined;
+            return this.expressionFor(candidate);
+        }, () => propertyToZod(this.#program, property));
+    }
+    /**
+     * A declaration for a shape the spec never wrote, under a name the document publishes.
+     *
+     * `@discriminated` with an envelope has no TypeSpec type for its wrapper — openapi3 synthesises
+     * one and publishes it as `PetWithEnvelopeCat`, so there is a component with no `Type` to key on.
+     * Keyed by name instead, and pushed in the same dependency-first order as everything else, so the
+     * envelope declarations land above the union that references them.
+     *
+     * `declareNamed` exposes the same seam to the route emitter, which needs it for a **multipart**
+     * body: the document publishes `MultiPartRequest` as a component, and there is no walkable type
+     * for it — the parts have to be assembled from `@typespec/http`'s own view of the payload.
+     */
+    declareNamed(name, build) {
+        return this.#declareSynthetic(name, build);
+    }
+    #declareSynthetic(name, build) {
+        const key = `synthetic\u0000${name}`;
+        const existing = this.#declarations.get(key);
+        if (existing !== undefined)
+            return existing.identifier;
+        const identifier = `${lowerFirst(name)}Schema`;
+        if (this.#inProgress.has(key))
+            return identifier;
+        this.#inProgress.set(key, identifier);
+        const source = build();
+        this.#inProgress.delete(key);
+        const declaration = { identifier, typeName: name, source };
+        this.#declarations.set(key, declaration);
+        this.#order.push(declaration);
+        return identifier;
+    }
+    /**
+     * Render `type` without consulting its own declaration, but letting nested types use theirs.
+     *
+     * ⚠️ **The "not itself" rule belongs to the TOP of the walk, not to every depth.** It used to live
+     * in the resolver, which is asked at every node — so a model reaching itself through a property
+     * was inlined again, and again: `type/array` and `type/dictionary` in the conformance corpus both
+     * declare `children?: InnerModel[]` and both died with
+     * `RangeError: Maximum call stack size exceeded`. Skipping the resolver once, here, is what makes
+     * a nested occurrence resolve to the identifier while the body still renders as a body.
+     */
+    #inline(type) {
+        return withRefResolver((candidate) => {
+            if (declaredNameOf(candidate) === undefined)
+                return undefined;
+            return this.expressionFor(candidate);
+        }, () => withSyntheticDeclarations((name, build) => this.#declareSynthetic(name, build), () => typeToZodBody(this.#program, type)));
+    }
+    /** Every declaration, dependencies first. */
+    declarations() {
+        return this.#order;
+    }
+}
+/**
+ * The same walk as {@link SchemaRegistry}, emitting plain TypeScript instead of Zod.
+ *
+ * Kept as a separate class rather than a mode on the schema registry because the two produce
+ * different *kinds* of declaration — an `interface` versus a `const` — and their reference resolvers
+ * hand back different text. Sharing {@link declaredNameOf} is the part that matters: a model named in
+ * one artefact is named the same way in the other, so the emitted assertion can pair them by name.
+ */
+export class TypeRegistry {
+    #program;
+    #declarations = new Map();
+    #order = [];
+    #inProgress = new Set();
+    constructor(program) {
+        this.#program = program;
+    }
+    expressionFor(type) {
+        const name = declaredNameOf(type);
+        if (name === undefined)
+            return this.#inline(type);
+        const existing = this.#declarations.get(type);
+        if (existing !== undefined)
+            return existing.name;
+        /**
+         * ⚠️ **No laziness is needed on this side, and no refusal either.** A TypeScript `interface`
+         * may refer to itself — `interface InnerModel { children?: InnerModel[] }` is the ordinary way
+         * to write a tree — so the name alone is the whole answer. The Zod registry has to defer the
+         * same edge behind a getter only because a `const` cannot read itself while initialising.
+         */
+        if (this.#inProgress.has(type))
+            return name;
+        this.#inProgress.add(type);
+        const source = this.#inline(type);
+        this.#inProgress.delete(type);
+        const declaration = {
+            name,
+            /**
+             * Only a plain object literal can be an `interface`. A permissive response is
+             * `{ …pinned } & Record<string, unknown>`, and `export interface X { … } & …` does not parse —
+             * so an intersection is emitted as a type alias instead.
+             */
+            isObject: source.startsWith("{") && !source.includes("} & "),
+            /**
+             * ⚠️ **A vocabulary alias is NOT exported.**
+             *
+             * It restates a vocabulary enum's members from the spec, and the vocabularies artefact already
+             * exports the same 27 names derived from the runtime tuples — exporting both collides on
+             * every one of them the moment the package re-exports this file.
+             *
+             * Restating rather than referencing is deliberate, and it is what makes the drift visible:
+             * the emitted **Zod** defers to the runtime tuple while this type says what the spec
+             * *declares*, so the two disagreeing is exactly the lie the document is telling. Referencing
+             * the contracts type instead would make every assertion pass and publish the lie unchecked —
+             * which is how `FilingState` came to advertise a `failed` state that cannot occur while
+             * omitting the generated one a consumer actually uses.
+             */
+            isVocabulary: type.kind === "Enum",
+            source,
+        };
+        this.#declarations.set(type, declaration);
+        this.#order.push(declaration);
+        return declaration.name;
+    }
+    /**
+     * The Zod-free type for a single property — used for path and query parameters, which are
+     * `ModelProperty`s belonging to no model. Without routing them through the registry a named model
+     * or enum in a parameter position is inlined rather than referenced.
+     */
+    expressionForProperty(property) {
+        return withTsRefResolver((candidate) => {
+            if (declaredNameOf(candidate) === undefined)
+                return undefined;
+            return this.expressionFor(candidate);
+        }, () => propertyToTs(this.#program, property));
+    }
+    #inline(type) {
+        return withTsRefResolver((candidate) => {
+            if (declaredNameOf(candidate) === undefined)
+                return undefined;
+            return this.expressionFor(candidate);
+        }, () => typeToTsBody(this.#program, type));
+    }
+    /** Every declaration, dependencies first. */
+    declarations() {
+        return this.#order;
+    }
+}

package/dist/src/runtime.d.ts

@@ -0,0 +1,84 @@
+import type { ZodType } from "zod";
+/**
+ * **What generated code imports at run time — and the only thing this package puts in its output.**
+ *
+ * ⚠️ **Kept deliberately tiny, and deliberately free of every TypeSpec import.** The main entry point
+ * is an emitter: it pulls in `@typespec/compiler` and exists at build time. This module is what an
+ * *application* touches — an Express or Fastify service reading the arms this emitter wrote — and
+ * making it reach the compiler would put a build-time dependency into a server's runtime graph for
+ * the sake of two declarations. `test/packaging.test.ts` asserts the separation rather than trusting
+ * it.
+ *
+ * A consumer may substitute this entirely: the `runtime-module` option decides the specifier the
+ * generated files import from, so an application that wants its own declarations points at its own
+ * module and re-declares these names.
+ */
+/**
+ * One status an operation may answer with, and the schema the document publishes for it.
+ *
+ * `when` is present only where an operation declares two success arms discriminated by a property of
+ * the result — the application reads that property, because only it knows how to see inside its own
+ * result envelope. Everything else about the choice is decided at generation time.
+ *
+ * ⚠️ **Failure arms are here too, and for a while they were not.** The document declares what an
+ * error response looks like, and the generated server passed on only the success statuses — so an
+ * application could not check what it sends when something goes wrong, because the schema never
+ * arrived. Measured on one service: `401` and two `default` responses declared, zero emitted.
+ *
+ * ⚠️ **The arms arrive in OpenAPI's precedence order, so the FIRST match is the right one.** An exact
+ * code, then a range, then the catch-all. That ordering is not a convention invented here: the
+ * Responses Object says "if a response is defined using an explicit code, the explicit code
+ * definition takes precedence over the range definition for that code", and `default` means every
+ * status not otherwise listed. Sorting once at generation time is what keeps every application from
+ * re-deriving the rule — and from getting it silently wrong when a `404` and a `4XX` both apply.
+ *
+ * ⚠️ **`schema: undefined` is a statement, not an absence.** A response the document says carries no
+ * body has no validator, and that is the truthful answer. It is also why the generated arms are
+ * annotated with `satisfies readonly ResponseArm[]` rather than `as const`: measured, `as const`
+ * catches a wrong `status` but is **blind** to a misspelled or omitted `schema`, because a bodyless
+ * arm is legitimate — so the typo produces a valid-looking arm that validates nothing.
+ */
+export interface ResponseArm {
+    /**
+     * The status this arm answers with: an exact code, a `4XX`-style range, or the catch-all.
+     *
+     * ⚠️ **`"default"` is carried as itself, not resolved to a number.** OpenAPI's `default` response
+     * means "any status not listed", and an emitter picking one would be answering a question the
+     * contract deliberately left to the application. The application maps its own failure to a status;
+     * this says which schema the body must match once it has.
+     *
+     * ⚠️ **A range is carried as itself for the same reason, and it used to be dropped entirely.**
+     * `@minValue(400) @maxValue(499) @statusCode _: int32` is a `4XX` entry in the document; the
+     * emitter handled `"*"` and exact numbers and emitted nothing at all for the third case, so a
+     * service could publish a whole class of failures with no arm to check them against. Expanding
+     * `4XX` to a hundred arms would be inventing statuses the contract never listed — the range IS
+     * what the document says, and matching against it is the application's to do, once, here.
+     */
+    readonly status: number | "default" | `${1 | 2 | 3 | 4 | 5}XX`;
+    readonly schema: ZodType | undefined;
+    readonly when?: {
+        readonly property: string;
+        readonly value: boolean | string;
+    };
+}
+/**
+ * The arm that governs a status — **the rule the OpenAPI specification states, applied once here.**
+ *
+ * An application knows which status it is answering with; the document knows which schema that status
+ * has to match. Joining the two means resolving an overlap, because `404`, `4XX` and `default` can
+ * all be declared on one operation and all three describe a 404. The Responses Object settles it: a
+ * range MAY be given as an uppercase `X` wildcard, and "if a response is defined using an explicit
+ * code, the explicit code definition takes precedence over the range definition for that code".
+ * `default` is by definition every status not otherwise listed, so it is last.
+ *
+ * ⚠️ **Shipped beside the arms rather than left to the caller, because this is where it goes wrong.**
+ * Left to applications it gets written as "the first arm with a status ≥ 400" — which is literally
+ * what one consumer's wiring did before ranges existed, and which silently skips every range arm
+ * while looking correct. A package that emits an array containing `4XX` and `default` and does not
+ * ship the rule for reading it has shipped a footgun.
+ *
+ * The emitter already sorts the arms into this order, so the scan is a formality on generated input.
+ * It is written to be independent of that anyway: an ordering assumption that only one side knows
+ * about is a coupling nobody can see.
+ */
+export declare function armFor(arms: readonly ResponseArm[], status: number): ResponseArm | undefined;

package/dist/src/runtime.js

@@ -0,0 +1,25 @@
+/**
+ * The arm that governs a status — **the rule the OpenAPI specification states, applied once here.**
+ *
+ * An application knows which status it is answering with; the document knows which schema that status
+ * has to match. Joining the two means resolving an overlap, because `404`, `4XX` and `default` can
+ * all be declared on one operation and all three describe a 404. The Responses Object settles it: a
+ * range MAY be given as an uppercase `X` wildcard, and "if a response is defined using an explicit
+ * code, the explicit code definition takes precedence over the range definition for that code".
+ * `default` is by definition every status not otherwise listed, so it is last.
+ *
+ * ⚠️ **Shipped beside the arms rather than left to the caller, because this is where it goes wrong.**
+ * Left to applications it gets written as "the first arm with a status ≥ 400" — which is literally
+ * what one consumer's wiring did before ranges existed, and which silently skips every range arm
+ * while looking correct. A package that emits an array containing `4XX` and `default` and does not
+ * ship the rule for reading it has shipped a footgun.
+ *
+ * The emitter already sorts the arms into this order, so the scan is a formality on generated input.
+ * It is written to be independent of that anyway: an ordering assumption that only one side knows
+ * about is a coupling nobody can see.
+ */
+export function armFor(arms, status) {
+    return (arms.find((arm) => arm.status === status) ??
+        arms.find((arm) => arm.status === `${Math.floor(status / 100)}XX`) ??
+        arms.find((arm) => arm.status === "default"));
+}

package/dist/src/streams.d.ts

@@ -0,0 +1,40 @@
+import type { Program, Type } from "@typespec/compiler";
+/**
+ * Optional support for `@typespec/streams`.
+ *
+ * ⚠️ **Lazily imported, and absent is a normal answer.** It is a separate library most specs never
+ * install, so a static import would make this emitter unusable without it. The structure follows
+ * `@typespec/openapi3`'s own `sse-module.js` — an optional peer dependency, a guarded `import()`,
+ * and `undefined` when it is missing — because an emitter that resolves it differently from the
+ * reference implementation will disagree with it about which specs it can serve. openapi3 needs
+ * `@typespec/events` and `@typespec/sse` as well, to build the per-event `itemSchema` OpenAPI 3.2
+ * carries; this emitter only needs to know WHAT is streamed, so one is enough.
+ *
+ * **Why this exists at all.** An SSE operation returns `SSEStream<UnnamedEvents>`, and under
+ * OpenAPI 3.1 its response body is `{"type": "string"}` — the event stream itself. The event
+ * PAYLOADS (`Unnamed.Info`, `Named.ResponseCreated`, …) are published as components that no path
+ * references: openapi3 builds `itemSchema` describing them for OpenAPI 3.2, and under 3.1 emits the
+ * components as a by-product. Measured: the 3.1 document mentions neither `itemSchema` nor
+ * `contentSchema`, yet declares all five payload models.
+ *
+ * They are still part of the published vocabulary, and reachable in the TypeSpec graph even though
+ * the 3.1 paths do not reach them — `getStreamOf` hands back whatever the stream carries, an
+ * `@events` union for SSE and the item model for JSON Lines. So the payloads get validators, and a
+ * consumer streaming events has something to check each `data:` against.
+ */
+export interface StreamModule {
+    /** The type a stream carries — an `@events` union for SSE, the item model for JSON Lines. */
+    readonly streamOf: (program: Program, type: Type) => Type | undefined;
+}
+export declare function resolveStreamModule(): Promise<StreamModule | undefined>;
+export declare function withStreamModule<T>(module: StreamModule | undefined, run: () => T): T;
+/**
+ * What an operation streams, or `undefined` when it streams nothing — which is every operation in a
+ * spec that does not use these libraries, and every ordinary operation in one that does.
+ *
+ * ⚠️ **Whatever the stream carries, not only an `@events` union.** The first cut required
+ * `isEvents`, which fixed SSE and left `JsonlStream<Info>` behind: JSON Lines carries the item model
+ * directly. The guard bought nothing — the streamed type is the published vocabulary in both cases —
+ * and dropping it removed a second optional dependency along with the special case.
+ */
+export declare function streamedTypeOf(program: Program, returnType: Type): Type | undefined;

package/dist/src/streams.js

@@ -0,0 +1,40 @@
+export async function resolveStreamModule() {
+    let streams;
+    try {
+        streams = (await import("@typespec/streams"));
+    }
+    catch {
+        return undefined;
+    }
+    return {
+        streamOf: (program, type) => type.kind === "Model" ? streams.getStreamOf(program, type) : undefined,
+    };
+}
+/**
+ * Scoped rather than threaded through the walk, matching the idiom the rest of this emitter uses for
+ * cross-cutting context (`withVisibility`, `withSealedObjects`, `withRefResolver`). Resolving the
+ * module is asynchronous and the walk is not, so it is resolved once in `$onEmit` and read here.
+ */
+let current;
+export function withStreamModule(module, run) {
+    const previous = current;
+    current = module;
+    try {
+        return run();
+    }
+    finally {
+        current = previous;
+    }
+}
+/**
+ * What an operation streams, or `undefined` when it streams nothing — which is every operation in a
+ * spec that does not use these libraries, and every ordinary operation in one that does.
+ *
+ * ⚠️ **Whatever the stream carries, not only an `@events` union.** The first cut required
+ * `isEvents`, which fixed SSE and left `JsonlStream<Info>` behind: JSON Lines carries the item model
+ * directly. The guard bought nothing — the streamed type is the published vocabulary in both cases —
+ * and dropping it removed a second optional dependency along with the special case.
+ */
+export function streamedTypeOf(program, returnType) {
+    return current?.streamOf(program, returnType);
+}

package/dist/src/tsp-index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * What TypeSpec's compiler loads for this library.
+ *
+ * ⚠️ **There is deliberately no `$decorators` export.** This emitter's ancestor defined four —
+ * `@trimmed`, `@loose`, `@externalValues` and `@refine` — and every one of them let the spec state
+ * something `@typespec/openapi3` could not publish, so the emitted validator enforced a rule no
+ * caller reading the contract could see. A decorator here is not a convenience; it is a second
+ * contract. If a spec needs to say something, it says it in a way the document carries.
+ *
+ * That is asserted as a class, not left to discipline: see `test/vocabulary.test.ts`.
+ */
+export { $lib } from "./lib.js";

package/dist/src/tsp-index.js

@@ -0,0 +1,12 @@
+/**
+ * What TypeSpec's compiler loads for this library.
+ *
+ * ⚠️ **There is deliberately no `$decorators` export.** This emitter's ancestor defined four —
+ * `@trimmed`, `@loose`, `@externalValues` and `@refine` — and every one of them let the spec state
+ * something `@typespec/openapi3` could not publish, so the emitted validator enforced a rule no
+ * caller reading the contract could see. A decorator here is not a convenience; it is a second
+ * contract. If a spec needs to say something, it says it in a way the document carries.
+ *
+ * That is asserted as a class, not left to discipline: see `test/vocabulary.test.ts`.
+ */
+export { $lib } from "./lib.js";

package/dist/src/types.d.ts

@@ -0,0 +1,10 @@
+import { type ModelProperty, type Program, type Type } from "@typespec/compiler";
+/** A property line, including its optionality marker. */
+export declare function propertyToTs(program: Program, property: ModelProperty): string;
+export declare function withTsRefResolver<T>(resolver: (type: Type) => string | undefined, run: () => T): T;
+export declare function typeToTs(program: Program, type: Type): string;
+/**
+ * The same walk, except that `type` is never resolved to its own name — see `SchemaRegistry.#inline`
+ * for why the "not itself" rule has to sit at the top of the walk rather than inside the resolver.
+ */
+export declare function typeToTsBody(program: Program, type: Type): string;