@nanobpm/urban 0.37.0 → 0.38.0

package/src/openapi/spec.ts

@@ -122,6 +122,15 @@ export interface OpenApiDoc {
 export const HTTP_METHODS = ["get", "put", "post", "delete", "patch", "options", "head"] as const;
 export type HttpMethodLower = (typeof HTTP_METHODS)[number];
 
+/** A single documented response: its status code ("200"), status range ("2XX"), or "default", and
+ *  its JSON body schema when it documents one. `schema` is absent when the response is documented
+ *  but carries no JSON body — recorded so an exact-status match can suppress the `default` fallback
+ *  rather than mis-validating a bodyless status against the default (typically error) schema. */
+export interface ResponseSchemaEntry {
+  status: string;
+  schema?: OpenApiSchema;
+}
+
 /** One resolved operation: its id, method, path, parameters, request body schema, and responses.
  *  This is the shared unit both the deriver (→ types) and the runtime (→ routes) consume. */
 export interface OperationInfo {
@@ -132,8 +141,10 @@ export interface OperationInfo {
   parameters: OpenApiParameter[];
   requestBodySchema?: OpenApiSchema;
   requestBodyRequired: boolean;
-  /** Schema of the first 2xx (else default) JSON response, when declared. */
-  responseSchema?: OpenApiSchema;
+  /** Every documented JSON response, keyed by status code ("200","400",…,"default"), in a stable
+   *  order. The type layer unions these into the operation's response type; the runtime validates a
+   *  handler result against the entry matching its status (else "default"). */
+  responseSchemas: ResponseSchemaEntry[];
   /** Effective security requirements (op-level if declared — including an explicit empty list —
    *  else the document-level default, else `[]`). An empty list means the operation is open. */
   security: OpenApiSecurityRequirement[];
@@ -255,7 +266,7 @@ export function collectOperations(doc: OpenApiDoc): OperationInfo[] {
         parameters,
         requestBodySchema,
         requestBodyRequired: requestBody?.required === true,
-        responseSchema: firstSuccessSchema(responses),
+        responseSchemas: collectResponseSchemas(responses),
         security,
         eject: opRaw["x-urban-eject"] === true,
         summary: typeof opRaw.summary === "string" ? opRaw.summary : undefined,
@@ -533,15 +544,41 @@ function normalizeParameters(raw: unknown[]): OpenApiParameter[] {
   return order.map((k) => byKey.get(k)!);
 }
 
-function firstSuccessSchema(responses: Record<string, unknown>): OpenApiSchema | undefined {
-  const codes = Object.keys(responses)
-    .filter((c) => /^2\d\d$/.test(c))
-    .sort();
-  const code = codes[0] ?? (isRecord(responses.default) ? "default" : undefined);
-  if (!code) return undefined;
-  const resp = responses[code];
-  if (!isRecord(resp)) return undefined;
-  return firstJsonSchema(isRecord(resp.content) ? resp.content : undefined);
+/** Every documented response, in a stable order: numeric status codes ascending, then status
+ *  ranges ("1XX".."5XX"), then "default" last. A response with no JSON body schema is still
+ *  recorded (with `schema` undefined) so an exact-status match suppresses the `default` fallback
+ *  instead of the bodyless status being mis-validated against the default (error) schema. */
+function collectResponseSchemas(responses: Record<string, unknown>): ResponseSchemaEntry[] {
+  const isExact = (c: string) => /^\d{3}$/.test(c);
+  const isRange = (c: string) => /^[1-5]XX$/i.test(c);
+  const keys = Object.keys(responses).filter((c) => isExact(c) || isRange(c) || c === "default");
+  const rank = (c: string) => (c === "default" ? 2 : isRange(c) ? 1 : 0);
+  keys.sort((a, b) => rank(a) - rank(b) || (a < b ? -1 : a > b ? 1 : 0));
+  const out: ResponseSchemaEntry[] = [];
+  for (const key of keys) {
+    const resp = responses[key];
+    if (!isRecord(resp)) continue;
+    const status = isRange(key) ? key.toUpperCase() : key;
+    const schema = firstJsonSchema(isRecord(resp.content) ? resp.content : undefined);
+    out.push(schema ? { status, schema } : { status });
+  }
+  return out;
+}
+
+/** Select the response schema to validate a handler result against: exact status → status range
+ *  ("2XX") → "default". A documented-but-bodyless exact status (or range) returns undefined (no
+ *  validation) and does NOT fall through to `default` — the status IS documented, it just carries no
+ *  JSON body, so validating it against an unrelated (e.g. error `default`) schema would be wrong. An
+ *  UNdocumented status falls back to the `default` entry when present, else undefined. */
+export function responseSchemaForStatus(
+  entries: ResponseSchemaEntry[],
+  status: number,
+): OpenApiSchema | undefined {
+  const exact = entries.find((e) => e.status === String(status));
+  if (exact) return exact.schema;
+  const range = entries.find((e) => e.status === `${Math.floor(status / 100)}XX`);
+  if (range) return range.schema;
+  return entries.find((e) => e.status === "default")?.schema;
 }
 
 /** Turn an OpenAPI path template ("/invoices/{id}") into a matcher under `base` ("/app/api"):

package/src/runtime/core/modules/api.test.ts

@@ -317,10 +317,46 @@ test("repeated query keys are all validated (extra values don't bypass validatio
     { "/app/operations/listItems": { default: () => ({ body: { ok: true } }) } },
     arraySpec,
   );
-  // First value valid, second (0) violates minimum:1 — must still be caught.
+  // A repeated scalar (non-array) param can't be forwarded as the single schema-typed scalar the
+  // delegate expects, so it's rejected outright (400) — extra values never reach the delegate.
   const res = await router(req("GET", "/app/api/items", { query: "n=5&n=0" }));
   assert.equal(res.status, 400);
   assert.match(JSON.parse(res.body!).error, /validation failed/);
+  assert.match(JSON.stringify(JSON.parse(res.body!).issues), /expected a single value/);
+});
+
+test("a declared but schemaless query param preserves raw wire semantics (repeats allowed)", async () => {
+  const schemalessSpec = JSON.stringify({
+    openapi: "3.0.0",
+    paths: {
+      "/items": {
+        get: {
+          operationId: "listItems",
+          parameters: [{ name: "x", in: "query" }], // no schema → raw wire `string | string[]`
+          responses: { "200": {} },
+        },
+      },
+    },
+  });
+  let got: unknown;
+  const { router } = build(
+    { spec: "openapi.json" },
+    { "/app/operations/listItems": { default: (i: { query: Record<string, unknown> }) => { got = i.query.x; return { body: { ok: true } }; } } },
+    schemalessSpec,
+  );
+  // Repeated key must NOT be rejected as a scalar-repeat — it's forwarded as the raw string[].
+  const res = await router(req("GET", "/app/api/items", { query: "x=a&x=b" }));
+  assert.equal(res.status, 200);
+  assert.deepEqual(got, ["a", "b"]);
+  // A single value stays the raw string.
+  let got1: unknown;
+  const b2 = build(
+    { spec: "openapi.json" },
+    { "/app/operations/listItems": { default: (i: { query: Record<string, unknown> }) => { got1 = i.query.x; return { body: { ok: true } }; } } },
+    schemalessSpec,
+  );
+  await b2.router(req("GET", "/app/api/items", { query: "x=solo" }));
+  assert.equal(got1, "solo");
 });
 
 test("array-typed query params validate the whole array (items + array constraints)", async () => {
@@ -349,6 +385,120 @@ test("array-typed query params validate the whole array (items + array constrain
   assert.equal((await build2("tag=a&tag=c")).status, 400); // "c" not in enum
 });
 
+test("params/query are coerced to their schema type before reaching the delegate", async () => {
+  const coerceSpec = JSON.stringify({
+    openapi: "3.0.0",
+    paths: {
+      "/things/{id}": {
+        get: {
+          operationId: "getThing",
+          parameters: [
+            { name: "id", in: "path", required: true, schema: { type: "integer" } },
+            { name: "verbose", in: "query", schema: { type: "boolean" } },
+            { name: "tags", in: "query", schema: { type: "array", items: { type: "string" } } },
+          ],
+          responses: { "200": {} },
+        },
+      },
+    },
+  });
+  let got: { params: Record<string, unknown>; query: Record<string, unknown> } | undefined;
+  const { router } = build(
+    { spec: "openapi.json" },
+    {
+      "/app/operations/getThing": {
+        default: (i: { params: Record<string, unknown>; query: Record<string, unknown> }) => {
+          got = { params: i.params, query: i.query };
+          return { body: { ok: true } };
+        },
+      },
+    },
+    coerceSpec,
+  );
+  const res = await router(req("GET", "/app/api/things/42", { query: "verbose=true&tags=x&tags=y" }));
+  assert.equal(res.status, 200);
+  // integer path param → number, boolean query → boolean, array query → string[] (all coerced).
+  assert.deepEqual(got, { params: { id: 42 }, query: { verbose: true, tags: ["x", "y"] } });
+});
+
+test("a typeless numeric const/enum query param coerces (so its number-literal type is satisfiable)", async () => {
+  const enumSpec = JSON.stringify({
+    openapi: "3.1.0",
+    paths: {
+      "/pick": {
+        get: {
+          operationId: "pick",
+          parameters: [
+            { name: "v", in: "query", required: true, schema: { enum: [1, 2, 3] } }, // no `type`
+            { name: "k", in: "query", required: true, schema: { const: 7 } }, // no `type`
+          ],
+          responses: { "200": {} },
+        },
+      },
+    },
+  });
+  let got: { query: Record<string, unknown> } | undefined;
+  const { router } = build(
+    { spec: "openapi.json" },
+    {
+      "/app/operations/pick": {
+        default: (i: { query: Record<string, unknown> }) => {
+          got = { query: i.query };
+          return { body: { ok: true } };
+        },
+      },
+    },
+    enumSpec,
+  );
+  // A valid enum/const value coerces to a number and passes validation (would 400 if left a string).
+  const ok = await router(req("GET", "/app/api/pick", { query: "v=2&k=7" }));
+  assert.equal(ok.status, 200);
+  assert.deepEqual(got, { query: { v: 2, k: 7 } });
+  // An out-of-set value still fails validation (coercion doesn't loosen the constraint).
+  const bad = await router(req("GET", "/app/api/pick", { query: "v=9&k=7" }));
+  assert.equal(bad.status, 400);
+});
+
+test("response validation is status-keyed: a documented error body validates against ITS schema", async () => {
+  const respSpec = JSON.stringify({
+    openapi: "3.0.0",
+    components: {
+      schemas: {
+        Ok: { type: "object", properties: { ok: { type: "boolean" } }, required: ["ok"], additionalProperties: false },
+        Err: { type: "object", properties: { error: { type: "string" } }, required: ["error"], additionalProperties: false },
+      },
+    },
+    paths: {
+      "/do": {
+        post: {
+          operationId: "doIt",
+          responses: {
+            "200": { content: { "application/json": { schema: { $ref: "#/components/schemas/Ok" } } } },
+            "400": { content: { "application/json": { schema: { $ref: "#/components/schemas/Err" } } } },
+          },
+        },
+      },
+    },
+  });
+  const runWith = (result: { status: number; body: unknown }) => {
+    const b = build(
+      { spec: "openapi.json", validateResponses: "always" },
+      { "/app/operations/doIt": { default: () => result } },
+      respSpec,
+    );
+    return { call: b.router(req("POST", "/app/api/do", { body: "{}" })), logs: b.logs };
+  };
+  // A valid documented 400 error body must NOT warn — the pre-fix code validated it against the 200
+  // success schema and warned. Now it's checked against the 400 schema and passes.
+  const okErr = runWith({ status: 400, body: { error: "bad ref" } });
+  await okErr.call;
+  assert.equal(okErr.logs.some((l) => l.msg.includes("response failed schema validation")), false);
+  // A body that violates the 400 schema DOES warn (proves it's validated against Err, not Ok).
+  const badErr = runWith({ status: 400, body: { oops: 1 } });
+  await badErr.call;
+  assert.equal(badErr.logs.some((l) => l.msg.includes("response failed schema validation")), true);
+});
+
 test("a failed initial spec load is retried, not cached as a permanent 500", async () => {
   let attempts = 0;
   const host: HostContext = {

package/src/runtime/core/modules/api.ts

@@ -28,6 +28,7 @@ import {
   operationsWithUnsafeId,
   parseSpec,
   resolveSchema,
+  responseSchemaForStatus,
   toRouteMatcher,
   undeclaredPathParams,
   undeclaredSecuritySchemes,
@@ -102,13 +103,17 @@ export interface OperationContract {
   body?: unknown;
 }
 
-/** The loose contract an untyped delegate sees (strings on the wire; unknown JSON body). `body` is
- *  optional so a raw (untyped) delegate typed `OperationHandler<DefaultContract>` still satisfies the
- *  generated registry's per-operation `OperationHandler<ReqFor<K>>` slot — an op whose request body
- *  is optional/absent must be a subtype of the default contract (handler args are contravariant). */
+/** The loose contract an untyped delegate sees. Params/query values are `unknown` (coerced to their
+ *  declared schema type before the delegate runs — the runtime validates then forwards the coerced
+ *  value — but a schemaless/undeclared key, or any param of an ejected op, is forwarded raw, hence
+ *  `unknown` rather than the coerced type); the JSON body is `unknown`. `body` is optional so a raw
+ *  (untyped) delegate typed `OperationHandler<DefaultContract>` still satisfies the generated
+ *  registry's per-operation `OperationHandler<ReqFor<K>>` slot — an op whose request body is
+ *  optional/absent must be a subtype of the default contract (handler args are contravariant), and a
+ *  schema-typed param object (e.g. `{ count: number }`) must be assignable to it. */
 export interface DefaultContract {
-  params: Record<string, string>;
-  query: Record<string, string | string[] | undefined>;
+  params: Record<string, unknown>;
+  query: Record<string, unknown>;
   body?: unknown;
 }
 
@@ -239,16 +244,29 @@ export function apiDocsPath(manifest: unknown): string | undefined {
 }
 
 /** Coerce a wire string to the type its parameter schema declares, so numeric/boolean bounds
- *  validate. A value that will not coerce is left as-is and fails the type check with a clear
- *  message. The delegate still receives the original string(s). */
+ *  validate and the delegate receives the coerced value (not the raw string). A value that will not
+ *  coerce is left as-is and fails the type check with a clear message. */
 function coerceParam(doc: OpenApiDoc, schema: OpenApiSchema | undefined, raw: string): unknown {
   const s = resolveSchema(doc, schema);
   if (!s) return raw;
-  if (s.type === "integer" || s.type === "number") {
+  // Effective scalar type: the explicit `type`, else inferred from a typeless `const`/`enum` whose
+  // values are all numbers or all booleans. Without this, a typeless numeric/boolean const/enum
+  // param (whose generated type is a number/boolean literal) could never be satisfied by the wire
+  // string — every request would 400 against a type the runtime otherwise never produces.
+  let t = s.type;
+  if (t === undefined) {
+    if (typeof s.const === "number") t = "number";
+    else if (typeof s.const === "boolean") t = "boolean";
+    else if (Array.isArray(s.enum) && s.enum.length > 0) {
+      if (s.enum.every((v) => typeof v === "number")) t = "number";
+      else if (s.enum.every((v) => typeof v === "boolean")) t = "boolean";
+    }
+  }
+  if (t === "integer" || t === "number") {
     const n = Number(raw);
     return raw.trim() !== "" && !Number.isNaN(n) ? n : raw;
   }
-  if (s.type === "boolean") {
+  if (t === "boolean") {
     if (raw === "true") return true;
     if (raw === "false") return false;
   }
@@ -501,6 +519,11 @@ export function mountApi(ctx: RuntimeContext, app: AppApi): ApiHandle {
       const all = req.query.getAll(key);
       query[key] = all.length > 1 ? all : all[0];
     }
+    // What the delegate actually receives: params/query coerced to their declared schema type. Seed
+    // from the raw wire values (used verbatim for ejected ops and for undeclared/schemaless keys);
+    // the validation loop below overwrites each declared parameter with its coerced value.
+    const coercedParams: Record<string, unknown> = { ...params };
+    const coercedQuery: Record<string, unknown> = { ...query };
 
     // Parse the JSON body (empty body → undefined). Invalid JSON is a 400 unless the op is ejected
     // (then the delegate reads the raw request itself).
@@ -530,27 +553,41 @@ export function mountApi(ctx: RuntimeContext, app: AppApi): ApiHandle {
             if (p.required) issues.push({ path: `params/${p.name}`, message: "is required" });
             continue;
           }
-          issues.push(...validateValue(d, p.schema, coerceParam(d, p.schema, val), `params/${p.name}`));
+          // Coerce once, forward the coerced value to the delegate (so a `count` param is a number
+          // in the delegate's typed input, matching the generated schema type), and validate it.
+          const coerced = coerceParam(d, p.schema, val);
+          coercedParams[p.name] = coerced;
+          issues.push(...validateValue(d, p.schema, coerced, `params/${p.name}`));
         } else if (p.in === "query") {
           const val = query[p.name];
           if (val === undefined) {
             if (p.required) issues.push({ path: `query/${p.name}`, message: "is required" });
             continue;
           }
+          // A declared but schemaless query param has no shape to coerce/validate against — its
+          // generated type is the raw wire `string | string[]`, so preserve raw semantics
+          // (including repeated keys) and forward the value verbatim (already seeded in coercedQuery
+          // from the raw wire). Don't route it through the scalar-repeat rejection below.
+          if (!p.schema) continue;
           const values = Array.isArray(val) ? val : [val];
           const ps = resolveSchema(d, p.schema);
           if (ps?.type === "array") {
             // Repeated keys (?tag=a&tag=b) form the array; coerce + validate each item, then the
-            // whole array against the schema's array constraints (minItems, items, ...).
+            // whole array against the schema's array constraints (minItems, items, ...). The coerced
+            // array is what the delegate receives.
             const items = ps.items ? values.map((v) => coerceParam(d, ps.items, v)) : values;
+            coercedQuery[p.name] = items;
             issues.push(...validateValue(d, ps, items, `query/${p.name}`));
+          } else if (values.length > 1) {
+            // A scalar (non-array) param that's repeated (?x=a&x=b) can't be forwarded as the
+            // single schema-typed scalar the delegate's generated type expects — reject it (400)
+            // rather than hand the delegate an array the type says is impossible.
+            issues.push({ path: `query/${p.name}`, message: "expected a single value" });
           } else {
-            // Scalar param: validate EVERY provided value, not just the first, so extra repeated
-            // values can't bypass validation.
-            values.forEach((v, i) => {
-              const at = values.length > 1 ? `query/${p.name}[${i}]` : `query/${p.name}`;
-              issues.push(...validateValue(d, p.schema, coerceParam(d, p.schema, v), at));
-            });
+            // Scalar param: coerce the single value, forward it, and validate it.
+            const coerced = coerceParam(d, p.schema, values[0]);
+            coercedQuery[p.name] = coerced;
+            issues.push(...validateValue(d, p.schema, coerced, `query/${p.name}`));
           }
         }
       }
@@ -604,14 +641,21 @@ export function mountApi(ctx: RuntimeContext, app: AppApi): ApiHandle {
     // a body-less type.
     const handlerBody = op.requestBodySchema !== undefined || op.requestBodyRequired ? body : undefined;
     try {
-      const result = await handler({ req, params, query, body: handlerBody }, app);
+      const result = await handler({ req, params: coercedParams, query: coercedQuery, body: handlerBody }, app);
       if (!result) return { status: 204 };
+      const status = result.status ?? 200;
       // Optional response validation (dev by default): warn-only, never blocks the response.
       const mode = binding.validateResponses ?? "dev";
       const doValidate =
         mode === "always" || (mode === "dev" && ctx.host.env("NODE_ENV") !== "production");
-      if (doValidate && op.responseSchema && result.body !== undefined) {
-        const rIssues = validateValue(d, op.responseSchema, result.body, "response");
+      // Validate against the response schema for THIS status — exact status, else a matching status
+      // range ("2XX"), else the "default" entry — so a documented error body (e.g. a 400 `{ error }`)
+      // is checked against its own schema, not spuriously against the success response. A
+      // documented-but-bodyless status carries no schema, so it (like a status with no `default`
+      // fallback) is left unvalidated.
+      const responseSchema = responseSchemaForStatus(op.responseSchemas, status);
+      if (doValidate && responseSchema && result.body !== undefined) {
+        const rIssues = validateValue(d, responseSchema, result.body, "response");
         if (rIssues.length > 0) {
           ctx.host.log("warn", "operation response failed schema validation (ADR 0058)", {
             operationId: op.operationId,
@@ -620,7 +664,7 @@ export function mountApi(ctx: RuntimeContext, app: AppApi): ApiHandle {
         }
       }
       return {
-        status: result.status ?? 200,
+        status,
         headers: { "content-type": "application/json", ...(result.headers ?? {}) },
         body: result.body === undefined ? undefined : JSON.stringify(result.body),
       };

package/src/toolkit/derivers/api.test.ts

@@ -139,10 +139,167 @@ test("required query params aren't undefined-widened; optional ones use the ? mo
     },
   };
   const out = emitApiBindings(qdoc);
-  assert.match(out, /"q": string \| string\[\]/); // required → present, not optional
+  assert.match(out, /"q": string/); // required scalar string → present, coerced to its schema type
   assert.doesNotMatch(out, /"q"\?:/); // not optional
-  assert.doesNotMatch(out, /"q": string \| string\[\] \| undefined/); // not undefined-widened
-  assert.match(out, /"page"\?: string \| string\[\]/); // optional → ? modifier
+  assert.doesNotMatch(out, /"q": string \| undefined/); // not undefined-widened
+  assert.match(out, /"page"\?: string/); // optional → ? modifier
+});
+
+test("params are typed by their schema (coerced), not the raw wire string", () => {
+  const pdoc: OpenApiDoc = {
+    openapi: "3.0.0",
+    paths: {
+      "/things/{id}": {
+        get: {
+          operationId: "getThing",
+          parameters: [
+            { name: "id", in: "path", required: true, schema: { type: "integer" } },
+            { name: "verbose", in: "query", schema: { type: "boolean" } },
+            { name: "tags", in: "query", schema: { type: "array", items: { type: "string" } } },
+            { name: "raw", in: "query" }, // no schema → raw wire type
+          ],
+          responses: { "200": {} },
+        },
+      },
+    },
+  };
+  const out = emitApiBindings(pdoc);
+  assert.match(out, /"id": number/); // integer path param → number, not string
+  assert.match(out, /"verbose"\?: boolean/); // boolean query → boolean
+  assert.match(out, /"tags"\?: Array<string>/); // array query → Array<item>
+  assert.match(out, /"raw"\?: string \| string\[\]/); // schemaless query → raw wire type
+});
+
+test("the response type unions every documented JSON response body (success + error)", () => {
+  const rdoc: OpenApiDoc = {
+    openapi: "3.0.0",
+    components: {
+      schemas: {
+        Ok: { type: "object", properties: { ok: { type: "boolean" } }, additionalProperties: false },
+        Err: { type: "object", properties: { error: { type: "string" } }, additionalProperties: false },
+      },
+    },
+    paths: {
+      "/do": {
+        post: {
+          operationId: "doIt",
+          responses: {
+            "200": { content: { "application/json": { schema: { $ref: "#/components/schemas/Ok" } } } },
+            "400": { content: { "application/json": { schema: { $ref: "#/components/schemas/Err" } } } },
+          },
+        },
+      },
+    },
+  };
+  const out = emitApiBindings(rdoc);
+  assert.match(out, /export type DoItResponse = Ok \| Err;/); // both bodies in the union
+});
+
+test("an ejected operation keeps raw wire param/query types + an unknown body (runtime skips coercion)", () => {
+  const edoc: OpenApiDoc = {
+    openapi: "3.0.0",
+    paths: {
+      "/raw/{id}": {
+        post: {
+          operationId: "rawOp",
+          "x-urban-eject": true,
+          parameters: [
+            { name: "id", in: "path", required: true, schema: { type: "integer" } },
+            { name: "n", in: "query", schema: { type: "integer" } },
+          ],
+          requestBody: {
+            required: true,
+            content: { "application/json": { schema: { type: "object", properties: { a: { type: "string" } } } } },
+          },
+          responses: { "200": {} },
+        },
+      },
+    },
+  };
+  const out = emitApiBindings(edoc);
+  assert.match(out, /"id": string/); // ejected integer path param stays a raw wire string
+  assert.match(out, /"n"\?: string \| string\[\]/); // ejected query param stays raw wire
+  assert.match(out, /body: unknown;/); // ejected body is unvalidated → unknown
+});
+
+test("whole-surface eject (manifest api.eject) types every op as ejected (raw params, unknown body)", () => {
+  const sdoc: OpenApiDoc = {
+    openapi: "3.0.0",
+    paths: {
+      "/thing/{id}": {
+        post: {
+          operationId: "doThing",
+          parameters: [
+            { name: "id", in: "path", required: true, schema: { type: "integer" } },
+            { name: "q", in: "query", required: true, schema: { type: "integer" } },
+          ],
+          requestBody: {
+            required: true,
+            content: { "application/json": { schema: { type: "object", properties: { a: { type: "string" } } } } },
+          },
+          responses: { "200": {} },
+        },
+      },
+    },
+  };
+  // Without the surface flag the op is fully typed…
+  const typed = emitApiBindings(sdoc, false);
+  assert.match(typed, /"id": number/);
+  assert.match(typed, /"q": number/);
+  // …with whole-surface eject it degrades to raw wire + unknown body, matching the runtime.
+  const ejected = emitApiBindings(sdoc, true);
+  assert.match(ejected, /"id": string/); // raw wire path param
+  assert.match(ejected, /"q"\?: string \| string\[\]/); // required query param becomes optional + raw
+  assert.match(ejected, /body: unknown;/);
+});
+
+test("an ejected required query param is typed optional (runtime does not enforce presence)", () => {
+  const edoc: OpenApiDoc = {
+    openapi: "3.0.0",
+    paths: {
+      "/raw": {
+        get: {
+          operationId: "rawReq",
+          "x-urban-eject": true,
+          parameters: [{ name: "req", in: "query", required: true, schema: { type: "integer" } }],
+          responses: { "200": {} },
+        },
+      },
+    },
+  };
+  const out = emitApiBindings(edoc);
+  assert.match(out, /"req"\?: string \| string\[\]/); // required-but-ejected → optional raw wire
+});
+
+test("a component or operationId colliding with a fixed generated name fails the drift gate", () => {
+  const cdoc: OpenApiDoc = {
+    openapi: "3.0.0",
+    components: { schemas: { ApiOperations: { type: "string" } } },
+    paths: { "/z": { get: { operationId: "getZ", responses: { "200": {} } } } },
+  };
+  assert.throws(() => emitApiBindings(cdoc), /duplicate TypeScript type "ApiOperations"/);
+});
+
+test("a documented-but-bodyless status is excluded from the response union", () => {
+  const rdoc: OpenApiDoc = {
+    openapi: "3.1.0",
+    components: {
+      schemas: { Err: { type: "object", properties: { error: { type: "string" } }, additionalProperties: false } },
+    },
+    paths: {
+      "/x": {
+        get: {
+          operationId: "getX",
+          responses: {
+            "204": {}, // documented, no JSON body → not in the union
+            default: { content: { "application/json": { schema: { $ref: "#/components/schemas/Err" } } } },
+          },
+        },
+      },
+    },
+  };
+  const out = emitApiBindings(rdoc);
+  assert.match(out, /export type GetXResponse = Err;/); // only the schema'd default body
 });
 
 test("request body optionality follows requestBody.required (runtime passes undefined when absent)", () => {