@nanobpm/urban 0.36.0 → 0.38.0

package/dist/openapi/spec.d.ts

@@ -87,6 +87,14 @@ export interface OpenApiDoc {
 /** The HTTP methods we mount, lowercase as they appear as path-item keys. */
 export declare const HTTP_METHODS: readonly ["get", "put", "post", "delete", "patch", "options", "head"];
 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 {
@@ -97,8 +105,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[];
@@ -172,6 +182,12 @@ export declare function evaluateSecurity(doc: OpenApiDoc, op: OperationInfo, get
  *  components.securitySchemes — an app-drift the runtime rejects at request time (500) and the
  *  `--check` gate can surface ahead of time. */
 export declare function undeclaredSecuritySchemes(doc: OpenApiDoc): string[];
+/** 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 declare function responseSchemaForStatus(entries: ResponseSchemaEntry[], status: number): OpenApiSchema | undefined;
 /** Turn an OpenAPI path template ("/invoices/{id}") into a matcher under `base` ("/app/api"):
  *  a RegExp that captures each `{param}` positionally, plus the ordered path-parameter names. The
  *  runtime matches concrete request paths, so a templated segment becomes a single-segment capture. */

package/dist/openapi/spec.js

@@ -139,7 +139,7 @@ export function collectOperations(doc) {
                 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,
@@ -399,17 +399,40 @@ function normalizeParameters(raw) {
     }
     return order.map((k) => byKey.get(k));
 }
-function firstSuccessSchema(responses) {
-    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) {
+    const isExact = (c) => /^\d{3}$/.test(c);
+    const isRange = (c) => /^[1-5]XX$/i.test(c);
+    const keys = Object.keys(responses).filter((c) => isExact(c) || isRange(c) || c === "default");
+    const rank = (c) => (c === "default" ? 2 : isRange(c) ? 1 : 0);
+    keys.sort((a, b) => rank(a) - rank(b) || (a < b ? -1 : a > b ? 1 : 0));
+    const out = [];
+    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, status) {
+    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"):
  *  a RegExp that captures each `{param}` positionally, plus the ordered path-parameter names. The

package/dist/runtime/core/modules/api.d.ts

@@ -22,13 +22,17 @@ export interface OperationContract {
     query: unknown;
     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;
 }
 /** The input handed to an operation delegate: the raw request plus the parsed (and, unless ejected,

package/dist/runtime/core/modules/api.js

@@ -15,7 +15,7 @@ import { errorMessage } from "../guards.js";
 import { MODULE_EXTENSION_CANDIDATES } from "../module-path.js";
 import { html, json, normalizeRoutePath } from "../router.js";
 import { resolveAppPath } from "./datasource.js";
-import { collectOperations, isSafeOperationId, operationsWithoutId, operationsWithUnsafeId, parseSpec, resolveSchema, toRouteMatcher, undeclaredPathParams, undeclaredSecuritySchemes, evaluateSecurity, validateValue, } from "../../../openapi/spec.js";
+import { collectOperations, isSafeOperationId, operationsWithoutId, operationsWithUnsafeId, parseSpec, resolveSchema, responseSchemaForStatus, toRouteMatcher, undeclaredPathParams, undeclaredSecuritySchemes, evaluateSecurity, validateValue, } from "../../../openapi/spec.js";
 /** The canonical, non-configurable mount prefix for an app's OpenAPI operations. Operations always
  *  live under `/app/api` so page actions, links, and any `callRoute` can name an operation path as a
  *  stable framework constant (`/app/api/<op path>`) — there is no per-app `base` knob to drift. */
@@ -140,17 +140,34 @@ export function apiDocsPath(manifest) {
     return docsEnabled ? docsBase : 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, schema, raw) {
     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")
@@ -365,6 +382,11 @@ export function mountApi(ctx, app) {
             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 = { ...params };
+        const coercedQuery = { ...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).
         const raw = await req.text();
@@ -395,7 +417,11 @@ export function mountApi(ctx, app) {
                             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];
@@ -404,21 +430,33 @@ export function mountApi(ctx, app) {
                             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}`));
                     }
                 }
             }
@@ -470,14 +508,21 @@ export function mountApi(ctx, app) {
         // 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,
@@ -486,7 +531,7 @@ export function mountApi(ctx, app) {
                 }
             }
             return {
-                status: result.status ?? 200,
+                status,
                 headers: { "content-type": "application/json", ...(result.headers ?? {}) },
                 body: result.body === undefined ? undefined : JSON.stringify(result.body),
             };

package/dist/toolkit/derivers/api.d.ts

@@ -12,8 +12,10 @@ export { DEFAULT_OPERATIONS_DIR };
 /** Render a JSON-Schema (OpenAPI subset) as a TS type expression. Local component `$ref`s render as
  *  their component name (emitted as named interfaces); unknown shapes fall back to `unknown`. */
 export declare function schemaToTs(schema: OpenApiSchema | undefined, depth?: number): string;
-/** Emit `api-io.d.ts`: named component types + per-operation Request/Response + the id union. */
-export declare function emitApiBindings(doc: OpenApiDoc): string;
+/** Emit `api-io.d.ts`: named component types + per-operation Request/Response + the id union.
+ *  `surfaceEject` reflects the manifest's whole-surface `api.eject` (which the deriver otherwise
+ *  can't see): when set, EVERY operation is treated as ejected (raw params/query, `unknown` body). */
+export declare function emitApiBindings(doc: OpenApiDoc, surfaceEject?: boolean): string;
 /** Emit `operations.ts`: the typed `defineOperation` wrapper, keyed by operationId (mirrors the
  *  generated typed `defineWorker`). Written verbatim (it never changes with the spec) — it only
  *  re-types the runtime's `defineOperation`. */
@@ -34,9 +36,12 @@ export declare function emitApiBindingsRuntime(): string;
  */
 export declare function emitApiController(doc: OpenApiDoc, operationsDir?: string): string;
 /** Derive the api artifacts from a parsed OpenAPI document. `operationsDir` is the manifest's
- *  `api.dir` (default `operations/`) — the controller's static delegate imports resolve into it. */
-export declare function deriveApi(doc: OpenApiDoc, operationsDir?: string): DerivedArtifact[];
+ *  `api.dir` (default `operations/`) — the controller's static delegate imports resolve into it.
+ *  `surfaceEject` is the manifest's whole-surface `api.eject`: when set, every operation is typed as
+ *  ejected (raw params/query, `unknown` body) so the generated types match the runtime. */
+export declare function deriveApi(doc: OpenApiDoc, operationsDir?: string, surfaceEject?: boolean): DerivedArtifact[];
 export declare const apiDeriver: Deriver<{
     doc: OpenApiDoc;
     operationsDir?: string;
+    surfaceEject?: boolean;
 }>;

package/dist/toolkit/derivers/api.js

@@ -1,7 +1,8 @@
 // Deriver: an OpenAPI document → `api-io.d.ts` (the endpoint type map) + `operations.ts` (the typed
 // `defineOperation` wrapper). ADR 0058: the contract-first endpoint surface. This is the authoring
 // half — per `operationId` it emits a `Request`/`Response` type from the operation's parameters,
-// requestBody, and first success response, plus an `ApiOperationId` union — mirroring how
+// requestBody, and response (a union of every documented JSON response body), plus an
+// `ApiOperationId` union — mirroring how
 // `worker-io.d.ts` types `defineWorker` from the model (ADR 0033 §3). The runtime
 // (`runtime/core/modules/api.ts`) is the matching half: it validates + routes from the SAME spec via
 // the shared `openapi/spec.ts`, so types and runtime never drift.
@@ -102,23 +103,34 @@ function objectToTs(schema, depth) {
     // No declared properties and additionalProperties: false → a closed, empty object.
     return "Record<string, never>";
 }
-/** The `params`/`query` object type for an operation, from its parameters (strings on the wire). */
-function paramsTs(op, where) {
+/** The `params`/`query` object type for an operation, from its parameters. Values are coerced to
+ *  their declared schema type before the delegate receives them (the runtime coerces + validates,
+ *  then forwards the coerced value), so a param's type is its schema type — not the raw wire string.
+ *  A parameter with no schema, or ANY parameter of an ejected operation (whose runtime skips
+ *  coercion/validation and hands the delegate the raw request), keeps the raw wire type (`string`,
+ *  or `string | string[]` for query). Ejected query params are also made optional: the runtime does
+ *  not enforce presence for ejected ops, so a "required" query param may in fact be absent. */
+function paramsTs(op, where, ejected) {
     const ps = op.parameters.filter((p) => p.in === where);
     if (ps.length === 0)
         return "{}";
+    const rawWire = where === "query" ? "string | string[]" : "string";
     const fields = ps.map((p) => {
-        const opt = p.required ? "" : "?";
-        // Query values arrive as strings (or string[] for repeated keys); path params are single
-        // strings. Optionality is carried by the `?` modifier — don't fold `undefined` into the
-        // value type, or required query params would still accept undefined.
-        const t = where === "query" ? "string | string[]" : "string";
+        // Coerced to the schema type (number/boolean/array/enum/…); optionality is carried by the `?`
+        // modifier — don't fold `undefined` into the value type, or required params would still accept
+        // undefined. Schemaless params, and every param of an ejected op, fall back to the raw wire type.
+        // A required query param of an ejected op is nonetheless optional here (runtime skips presence);
+        // path params stay as declared (the route only matches when every path segment is present).
+        const opt = ejected && where === "query" ? "?" : p.required ? "" : "?";
+        const t = ejected || !p.schema ? rawWire : schemaToTs(p.schema);
         return `${JSON.stringify(p.name)}${opt}: ${t}`;
     });
     return `{ ${fields.join("; ")} }`;
 }
-/** Emit `api-io.d.ts`: named component types + per-operation Request/Response + the id union. */
-export function emitApiBindings(doc) {
+/** Emit `api-io.d.ts`: named component types + per-operation Request/Response + the id union.
+ *  `surfaceEject` reflects the manifest's whole-surface `api.eject` (which the deriver otherwise
+ *  can't see): when set, EVERY operation is treated as ejected (raw params/query, `unknown` body). */
+export function emitApiBindings(doc, surfaceEject = false) {
     const ops = collectOperations(doc);
     const components = doc.components?.schemas ?? {};
     // Fail-closed on TypeScript name collisions: typeStem is lossy (non-alphanumerics collapse), so
@@ -134,6 +146,11 @@ export function emitApiBindings(doc) {
         }
         emittedTypeNames.set(typeName, source);
     };
+    // Reserve the fixed generated declarations (the operation-id union + operations map) up front, so
+    // a component or operationId whose stem collapses onto one of them fails the drift gate with a
+    // clear rename message instead of silently emitting a duplicate, uncompilable declaration.
+    claimTypeName("ApiOperationId", "the generated operation-id union");
+    claimTypeName("ApiOperations", "the generated operations map");
     for (const name of Object.keys(components)) {
         claimTypeName(typeStem(name), `component schema "${name}"`);
     }
@@ -142,8 +159,9 @@ export function emitApiBindings(doc) {
         claimTypeName(`${typeStem(op.operationId)}Response`, `operationId "${op.operationId}"`);
     }
     const header = "// AUTO-GENERATED by @nanobpm/urban from the app's OpenAPI spec (ADR 0058).\n" +
-        "// The endpoint type map: each operationId maps to its typed request (path/query params +\n" +
-        "// JSON body) and success response, derived from the spec. Do not edit — regenerated from\n" +
+        "// The endpoint type map: each operationId maps to its typed request (coerced path/query params\n" +
+        "// + JSON body) and response (a union of every documented JSON response body), derived from the\n" +
+        "// spec. Do not edit — regenerated from\n" +
         "// the spec; erased to plain JS at compile.\n" +
         "// eslint-disable\n\n";
     const componentDecls = Object.entries(components)
@@ -153,21 +171,37 @@ export function emitApiBindings(doc) {
     const opDecls = ops
         .map((op) => {
         const stem = typeStem(op.operationId);
+        const ejected = surfaceEject || op.eject;
+        // An ejected operation (`x-urban-eject`, or the whole surface via manifest `api.eject`)
+        // bypasses the generated coercion/validation — its delegate reads the raw request — so its
+        // input is NOT schema-shaped at runtime: params/query stay raw wire types and the body is
+        // unvalidated (`unknown`). Typing it by the schema would claim guarantees the runtime doesn't
+        // make. (ADR 0059 documents the ejection exception.)
         // With a schema → the typed body. Required but no JSON schema → `unknown` (a body IS
         // required at runtime, just of an unknown shape). Otherwise (optional, absent) → `undefined`.
-        const bodyType = op.requestBodySchema
-            ? schemaToTs(op.requestBodySchema)
-            : op.requestBodyRequired
-                ? "unknown"
-                : "undefined";
+        const bodyType = ejected
+            ? "unknown"
+            : op.requestBodySchema
+                ? schemaToTs(op.requestBodySchema)
+                : op.requestBodyRequired
+                    ? "unknown"
+                    : "undefined";
         // An optional (or absent) request body is passed to the delegate as `undefined` at runtime,
         // so mark it optional in the type rather than forcing handlers to treat it as always-present.
         const bodyOpt = op.requestBodyRequired ? "" : "?";
-        const resp = op.responseSchema ? schemaToTs(op.responseSchema) : "unknown";
+        // Response type: a union of every documented JSON response body (success + errors), so a
+        // handler that returns a documented error body typechecks against its operation's response
+        // type. Bodyless documented statuses carry no schema and are skipped here. Deduped (identical
+        // schemas collapse), stable order. No documented JSON body → unknown.
+        const respSeen = new Set();
+        const respParts = op.responseSchemas
+            .flatMap((e) => (e.schema ? [schemaToTs(e.schema)] : []))
+            .filter((t) => (respSeen.has(t) ? false : (respSeen.add(t), true)));
+        const resp = respParts.length > 0 ? respParts.join(" | ") : "unknown";
         const summary = op.summary ? `/** ${op.summary.replace(/\*\//g, "*\\/")} */\n` : "";
         return (`${summary}export interface ${stem}Request {\n` +
-            `  params: ${paramsTs(op, "path")};\n` +
-            `  query: ${paramsTs(op, "query")};\n` +
+            `  params: ${paramsTs(op, "path", ejected)};\n` +
+            `  query: ${paramsTs(op, "query", ejected)};\n` +
             `  body${bodyOpt}: ${bodyType};\n` +
             `}\n` +
             `export type ${stem}Response = ${resp};`);
@@ -264,10 +298,12 @@ export function emitApiController(doc, operationsDir = DEFAULT_OPERATIONS_DIR) {
         `};\n`);
 }
 /** Derive the api artifacts from a parsed OpenAPI document. `operationsDir` is the manifest's
- *  `api.dir` (default `operations/`) — the controller's static delegate imports resolve into it. */
-export function deriveApi(doc, operationsDir = DEFAULT_OPERATIONS_DIR) {
+ *  `api.dir` (default `operations/`) — the controller's static delegate imports resolve into it.
+ *  `surfaceEject` is the manifest's whole-surface `api.eject`: when set, every operation is typed as
+ *  ejected (raw params/query, `unknown` body) so the generated types match the runtime. */
+export function deriveApi(doc, operationsDir = DEFAULT_OPERATIONS_DIR, surfaceEject = false) {
     return [
-        { path: `${GENERATED_DIR}/${API_BINDINGS_DTS}`, content: emitApiBindings(doc) },
+        { path: `${GENERATED_DIR}/${API_BINDINGS_DTS}`, content: emitApiBindings(doc, surfaceEject) },
         { path: `${GENERATED_DIR}/${API_BINDINGS_TS}`, content: emitApiBindingsRuntime() },
         { path: `${GENERATED_DIR}/${API_CONTROLLER_TS}`, content: emitApiController(doc, operationsDir) },
     ];
@@ -275,5 +311,5 @@ export function deriveApi(doc, operationsDir = DEFAULT_OPERATIONS_DIR) {
 export const apiDeriver = {
     id: "openapi->api-io",
     describe: "Derive api-io.d.ts (typed request/response per operationId) + the typed defineOperation + the delegate registry.",
-    derive: ({ doc, operationsDir }) => deriveApi(doc, operationsDir),
+    derive: ({ doc, operationsDir, surfaceEject }) => deriveApi(doc, operationsDir, surfaceEject),
 };

package/dist/toolkit/gen.js

@@ -101,7 +101,7 @@ async function collectAll(opts) {
         const opsDir = typeof manifest.api?.dir === "string" && manifest.api.dir.trim().length > 0
             ? manifest.api.dir.trim()
             : undefined;
-        artifacts.push(...deriveApi(parseSpec(specText), opsDir));
+        artifacts.push(...deriveApi(parseSpec(specText), opsDir, manifest.api?.eject === true));
     }
     return { artifacts: sortArtifacts(artifacts), derived };
 }

package/dist/toolkit/index.d.ts

@@ -27,6 +27,7 @@ export declare const DERIVERS: readonly [import("./artifact.ts").Deriver<import(
 }>, import("./artifact.ts").Deriver<{
     doc: import("../openapi/spec.ts").OpenApiDoc;
     operationsDir?: string;
+    surfaceEject?: boolean;
 }>];
 export { collectArtifacts, runGen, joinPath, readModels, expandPattern, previewModels } from "./gen.ts";
 export type { GenIO, GenOptions, GenResult } from "./gen.ts";

package/dist/toolkit/scaffold/workers.d.ts

@@ -26,7 +26,7 @@ export interface WorkerStubPlan {
     stub: string;
     manifestEntry: StubManifestEntry;
 }
-export type SkipReason = "already-wired" | "orchestrator" | "duplicate";
+export type SkipReason = "already-wired" | "orchestrator" | "duplicate" | "external";
 export interface SkippedWorker {
     taskType: string;
     reason: SkipReason;
@@ -41,8 +41,10 @@ export declare function slugifyTaskType(taskType: string): string;
 export declare function renderWorkerStub(taskType: string, typedIn: boolean, typedOut: boolean): string;
 /**
  * Plan write-once handler stubs from the models. A stub is planned for each service-task
- * `taskType` that is NOT already wired in the manifest, NOT the imperative orchestrator, and
- * not a duplicate of one already planned. `declaredTypeIds` are the manifest `types` ids — an
- * envelope `in`/`out` is typed only when it names one (matching the worker-io deriver).
+ * `taskType` that is NOT already wired in the manifest, NOT the imperative orchestrator, NOT
+ * declared external (serviced by an out-of-process worker), and not a duplicate of one already
+ * planned. `declaredTypeIds` are the manifest `types` ids — an envelope `in`/`out` is typed only
+ * when it names one (matching the worker-io deriver). `externalTaskTypes` are the manifest's
+ * declared external task types, which the app owns the model for but deliberately does not host.
  */
-export declare function planWorkerScaffold(models: ModelSource[], workers?: ScaffoldWorker[], declaredTypeIds?: Iterable<string>): WorkerScaffoldPlan;
+export declare function planWorkerScaffold(models: ModelSource[], workers?: ScaffoldWorker[], declaredTypeIds?: Iterable<string>, externalTaskTypes?: Iterable<string>): WorkerScaffoldPlan;

package/dist/toolkit/scaffold/workers.js

@@ -57,15 +57,18 @@ export function renderWorkerStub(taskType, typedIn, typedOut) {
 }
 /**
  * Plan write-once handler stubs from the models. A stub is planned for each service-task
- * `taskType` that is NOT already wired in the manifest, NOT the imperative orchestrator, and
- * not a duplicate of one already planned. `declaredTypeIds` are the manifest `types` ids — an
- * envelope `in`/`out` is typed only when it names one (matching the worker-io deriver).
+ * `taskType` that is NOT already wired in the manifest, NOT the imperative orchestrator, NOT
+ * declared external (serviced by an out-of-process worker), and not a duplicate of one already
+ * planned. `declaredTypeIds` are the manifest `types` ids — an envelope `in`/`out` is typed only
+ * when it names one (matching the worker-io deriver). `externalTaskTypes` are the manifest's
+ * declared external task types, which the app owns the model for but deliberately does not host.
  */
-export function planWorkerScaffold(models, workers = [], declaredTypeIds = []) {
+export function planWorkerScaffold(models, workers = [], declaredTypeIds = [], externalTaskTypes = []) {
     const wired = new Set(workers
         .map((w) => w?.taskType)
         .filter((t) => typeof t === "string" && t.length > 0));
     const declared = new Set(declaredTypeIds);
+    const external = new Set(externalTaskTypes);
     const plans = [];
     const skipped = [];
     const seenTaskTypes = new Set();
@@ -77,6 +80,10 @@ export function planWorkerScaffold(models, workers = [], declaredTypeIds = []) {
                 skipped.push({ taskType, reason: "orchestrator" });
                 continue;
             }
+            if (external.has(taskType)) {
+                skipped.push({ taskType, reason: "external" });
+                continue;
+            }
             if (wired.has(taskType)) {
                 skipped.push({ taskType, reason: "already-wired" });
                 continue;

package/dist/toolkit/scaffold.js

@@ -15,7 +15,7 @@ export async function scaffoldWorkers(opts) {
     const manifest = JSON.parse(await io.readText(manifestPath));
     const models = await readModels(root, io, manifest);
     const declaredTypeIds = Object.keys(manifest.types ?? {});
-    const { plans, skipped } = planWorkerScaffold(models, manifest.workers ?? [], declaredTypeIds);
+    const { plans, skipped } = planWorkerScaffold(models, manifest.workers ?? [], declaredTypeIds, manifest.externalTaskTypes ?? []);
     const outcomes = [];
     const wired = [];
     for (const plan of plans) {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nanobpm/urban",
-	"version": "0.36.0",
+	"version": "0.38.0",
 	"description": "Urban: build and run code-first apps on Nano — runtime, derivation toolkit, and CLI in one. Author durable processes with @nanobpm/workflow (defineFlow), a typed datasource, forms, triggers and surfaces from a nano.app.json manifest, on Node or Deno.",
 	"license": "Apache-2.0",
 	"type": "module",
@@ -62,7 +62,7 @@
 		"test:deno": "deno test -A --no-check src/"
 	},
 	"dependencies": {
-		"@nanobpm/nano-app-schema": "^0.4.0",
+		"@nanobpm/nano-app-schema": "^0.5.0",
 		"@nanobpm/nano-sdk": "^1.2.3",
 		"@nanobpm/workflow": "^0.8.0",
 		"bpmn-auto-layout": "^2.0.0-alpha.2",

package/src/openapi/spec.test.ts

@@ -11,6 +11,7 @@ import {
   operationsWithUnsafeId,
   parseSpec,
   resolveSchema,
+  responseSchemaForStatus,
   toRouteMatcher,
   undeclaredPathParams,
   undeclaredSecuritySchemes,
@@ -517,3 +518,46 @@ test("evaluateSecurity: alternative requirements are OR (any one satisfied autho
   // Neither presented → 401.
   assert.equal(evaluateSecurity(doc, op, noHeader, noQuery, env).status, 401);
 });
+
+test("responseSchemaForStatus: a documented-but-bodyless status suppresses the default fallback", () => {
+  const ops = collectOperations({
+    openapi: "3.1.0",
+    paths: {
+      "/x": {
+        get: {
+          operationId: "getX",
+          responses: {
+            "204": {}, // documented, no JSON body
+            default: { content: { "application/json": { schema: { type: "object" } } } },
+          },
+        },
+      },
+    },
+  });
+  const entries = ops[0].responseSchemas;
+  // 204 IS documented (just bodyless) → no validation, and it must NOT fall through to `default`.
+  assert.equal(responseSchemaForStatus(entries, 204), undefined);
+  // 500 is undocumented → falls through to `default`.
+  assert.equal(responseSchemaForStatus(entries, 500)?.type, "object");
+});
+
+test("responseSchemaForStatus: a status-range ('2XX') covers concrete statuses in its class", () => {
+  const ops = collectOperations({
+    openapi: "3.1.0",
+    paths: {
+      "/y": {
+        get: {
+          operationId: "getY",
+          responses: {
+            "2XX": { content: { "application/json": { schema: { type: "string" } } } },
+            default: { content: { "application/json": { schema: { type: "object" } } } },
+          },
+        },
+      },
+    },
+  });
+  const entries = ops[0].responseSchemas;
+  assert.equal(entries.map((e) => e.status).join(","), "2XX,default"); // ranges before default
+  assert.equal(responseSchemaForStatus(entries, 200)?.type, "string"); // 2XX class → range schema
+  assert.equal(responseSchemaForStatus(entries, 404)?.type, "object"); // outside 2XX → default
+});