@distilled.cloud/core 1.0.0-rc.1 → 1.0.0-rc.11

package/src/codegen/openapi-cli.ts

@@ -2,29 +2,29 @@
  * OpenAPI → Smithy pipeline helper (dev-time only, provider-agnostic).
  *
  * Owns the spec-side pipeline every OpenAPI-sourced provider shares: read the
- * spec file, apply the RFC-6902 patch chain to the OpenAPI document (v0
- * semantics: `*.patch.json` files in sorted name order, `{ description,
- * patches }` shape; stale targets warn+skip, malformed patches fail the run),
- * run the optional preprocess hook, convert with
- * {@link convertOpenApiToSmithy}, and write `.generated-specs/<name>.json`.
+ * spec file, apply OpenAPI RFC-6902 ops to the document, convert with
+ * {@link convertOpenApiToSmithy} (which owns verbNoun naming), apply Smithy
+ * RFC-6902 ops (`/shapes`, `/metadata`) to the model, and write
+ * `.generated-specs/<name>.json`. Stale targets fail unless
+ * `onStalePatch: "warn"`.
  *
- * A provider's `scripts/convert.ts` is: a `runOpenApiConvert` call. The
- * separate `scripts/generate.ts` (an SdkSpec + `runGeneratorCli`) then
- * compiles the written models. Note: providers whose OpenAPI patches live in
- * `patches/` should pass `patchesDir: false` to `runGeneratorCli` — the
- * patch chain applies HERE, to the OpenAPI document, not to the Smithy model.
+ * A provider's `scripts/convert.ts` is: a `runOpenApiConvert` call.
+ * `scripts/generate.ts` compiles the already-patched models and does not
+ * apply patches.
  */
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
-import {
-  applyOperation,
-  isStaleTargetError,
-  type PatchFile,
-} from "../json-patch.ts";
 import {
   convertOpenApiToSmithy,
   type OpenApiConvertOptions,
 } from "./openapi.ts";
+import {
+  applyRfc6902Files,
+  finalizeConvert,
+  isSmithyPatchPath,
+  listRfc6902PatchFiles,
+} from "./patches.ts";
+import { resolveSpecPath } from "./spec-path.ts";
 
 export interface OpenApiSpecEntry {
   /** Output model name — written to `<outDir>/<name>.json`. */
@@ -35,7 +35,7 @@ export interface OpenApiSpecEntry {
    * Hook between patching and conversion (e.g. path prefixing, server
    * rewrites). May mutate the spec in place or return a replacement.
    */
-  readonly preprocess?: (spec: any) => unknown | void;
+  readonly preprocess?: (spec: any) => unknown | void | Promise<unknown | void>;
   /** Per-spec converter option overrides (merged over the shared options). */
   readonly options?: Partial<OpenApiConvertOptions>;
 }
@@ -46,9 +46,10 @@ export interface RunOpenApiConvertOptions {
   readonly specs: readonly OpenApiSpecEntry[];
   /**
    * RFC-6902 patch chain root, relative to `root`. Default `"patches"`;
-   * `false` disables. Layout: `<patchesDir>/<name>/*.patch.json` when the
+   * `false` disables. Layout: `<patchesDir>/<name>/*.json` when the
    * per-spec directory exists; for single-spec providers a flat
-   * `<patchesDir>/*.patch.json` also works.
+   * `<patchesDir>/*.json` also works. Ops under `/shapes` or `/metadata`
+   * apply to the Smithy model after conversion; the rest apply to OpenAPI.
    */
   readonly patchesDir?: string | false;
   /** Output directory, relative to `root`. Default `".generated-specs"`. */
@@ -60,6 +61,19 @@ export interface RunOpenApiConvertOptions {
   readonly parse?: (text: string, specPath: string) => unknown;
   /** Shared converter options (per-spec `options` merge over these). */
   readonly options: OpenApiConvertOptions;
+  /**
+   * What to do when a patch JSON pointer does not resolve. Default `"fail"`:
+   * silent skip is how a whole patch chain can vanish after an upstream path
+   * prefix change. `"warn"` restores the old skip-and-continue behaviour.
+   */
+  readonly onStalePatch?: "fail" | "warn";
+  /**
+   * Run {@link finalizeConvert} on the written models (reference check +
+   * finalized marker; naming already happened in the converter). Default
+   * true. Pass false when the caller finalizes once after several convert
+   * steps (Fly machines + sprites + addons).
+   */
+  readonly finalize?: boolean;
 }
 
 const exists = async (p: string): Promise<boolean> => {
@@ -81,6 +95,7 @@ export const runOpenApiConvert = async (
       ? undefined
       : path.resolve(o.root, o.patchesDir ?? "patches");
   const parse = o.parse ?? ((text: string) => JSON.parse(text));
+  const onStalePatch = o.onStalePatch ?? "fail";
 
   await fs.mkdir(outDir, { recursive: true });
 
@@ -88,10 +103,11 @@ export const runOpenApiConvert = async (
   console.log(`   Output: ${outDir}`);
 
   for (const entry of o.specs) {
-    const specPath = path.resolve(o.root, entry.specPath);
+    // Production path by default; `specs/.local` under DISTILLED_SPECS_LOCAL.
+    const specPath = resolveSpecPath(o.root, entry.specPath);
     let spec: any = parse(await fs.readFile(specPath, "utf8"), specPath);
 
-    // ---- RFC-6902 patch chain (applies to the OpenAPI document) ----
+    // ---- RFC-6902: OpenAPI ops before convert, Smithy ops after ----
     let patchDir: string | undefined;
     if (patchRoot && (await exists(patchRoot))) {
       const perSpec = path.join(patchRoot, entry.name);
@@ -101,66 +117,66 @@ export const runOpenApiConvert = async (
         patchDir = patchRoot;
       }
     }
-    let patchFileCount = 0;
-    let staleOps = 0;
-    const badPatches: string[] = [];
-    if (patchDir) {
-      const files = (await fs.readdir(patchDir))
-        .filter((f) => f.endsWith(".patch.json"))
-        .sort((a, b) => a.localeCompare(b));
-      for (const pf of files) {
-        const parsed = JSON.parse(
-          await fs.readFile(path.join(patchDir, pf), "utf8"),
-        ) as PatchFile;
-        for (const patchOp of parsed.patches ?? []) {
-          try {
-            applyOperation(spec, patchOp);
-          } catch (e) {
-            const msg = e instanceof Error ? e.message : String(e);
-            if (isStaleTargetError(msg)) {
-              // Spec drift — the patch target no longer exists upstream.
-              staleOps++;
-              console.warn(
-                `   ⚠️  stale: ${entry.name}/${pf} [${patchOp.op} ${patchOp.path}]`,
-              );
-            } else {
-              badPatches.push(
-                `${entry.name}/${pf} [${patchOp.op} ${patchOp.path}]: ${msg}`,
-              );
-            }
-          }
-        }
-        patchFileCount++;
-      }
-    }
-    if (badPatches.length) {
-      for (const b of badPatches) console.error(`❌ bad patch: ${b}`);
+    const patchFiles = patchDir ? await listRfc6902PatchFiles(patchDir) : [];
+    const patchLabel = (file: string) => `${entry.name}/${path.basename(file)}`;
+    const openapiPatches = await applyRfc6902Files(spec, patchFiles, {
+      onStalePatch,
+      include: (op) => !isSmithyPatchPath(op.path),
+      label: patchLabel,
+    });
+    if (openapiPatches.errors.length) {
+      for (const b of openapiPatches.errors)
+        console.error(`❌ bad patch: ${b}`);
       throw new Error(
-        `${badPatches.length} malformed patch operation(s) — fix or remove them`,
+        `${openapiPatches.errors.length} patch operation(s) failed — fix the pointers or delete the patch`,
       );
     }
 
     // ---- Preprocess hook ----
     if (entry.preprocess) {
-      const replaced = entry.preprocess(spec);
+      const replaced = await entry.preprocess(spec);
       if (replaced !== undefined) spec = replaced;
     }
 
-    // ---- Convert + write ----
+    // ---- Convert, Smithy patches, write ----
     const model = convertOpenApiToSmithy(spec, {
       ...o.options,
       ...entry.options,
     });
+    const smithyPatches = await applyRfc6902Files(model, patchFiles, {
+      onStalePatch,
+      include: (op) => isSmithyPatchPath(op.path),
+      label: patchLabel,
+    });
+    if (smithyPatches.errors.length) {
+      for (const b of smithyPatches.errors) console.error(`❌ bad patch: ${b}`);
+      throw new Error(
+        `${smithyPatches.errors.length} Smithy patch operation(s) failed — fix the pointers or delete the patch`,
+      );
+    }
     const opCount = Object.values(model.shapes).filter(
       (s: any) => s.type === "operation",
     ).length;
     const outPath = path.join(outDir, `${entry.name}.json`);
     await fs.writeFile(outPath, JSON.stringify(model, null, 2) + "\n");
+    const staleOps = openapiPatches.stale + smithyPatches.stale;
     console.log(
       `   ✅ ${entry.name}: ${opCount} operations, ${Object.keys(model.shapes).length} shapes` +
-        (patchFileCount
-          ? ` (${patchFileCount} patch file(s) applied${staleOps ? `, ${staleOps} stale op(s) skipped` : ""})`
+        (patchFiles.length
+          ? ` (${patchFiles.length} patch file(s) applied${staleOps ? `, ${staleOps} stale op(s) skipped` : ""})`
           : ""),
     );
   }
+
+  if (o.finalize !== false) {
+    const written = new Set(o.specs.map((s) => s.name));
+    await finalizeConvert({
+      root: o.root,
+      outDir,
+      // Patches and naming already ran above.
+      patchesDir: false,
+      operationNaming: "as-is",
+      include: (resource) => written.has(resource),
+    });
+  }
 };

package/src/codegen/openapi.ts

@@ -7,20 +7,28 @@
  * `generateService` compiler. Conversion fidelity follows distilled v0's
  * `generate-openapi.ts` feature matrix:
  *
- *   • one operation per (path × get/post/put/patch/delete), deprecated
- *     skipped by default; op shape name = PascalCase(operationId)
+ *   • one operation per (path × get/post/put/patch/delete — plus head/options
+ *     when a provider opts in via `extraHttpMethods`), deprecated skipped by
+ *     default; op shape name = PascalCase(operationId), or verbNoun
+ *     (`Apps_list` → `ListApps`) when {@link OpenApiConvertOptions.operationNaming}
+ *     is `"verbNoun"`
  *   • input `<Op>Request`: path params → `smithy.api#httpLabel` (+required),
- *     query params → `smithy.api#httpQuery`, header/cookie params dropped,
- *     body properties flattened alongside (labels win, then query, then body);
+ *     query params → `smithy.api#httpQuery`, header params →
+ *     `smithy.api#httpHeader` when `headerParams` is on (dropped otherwise,
+ *     as cookie params always are),
+ *     body properties flattened alongside
+ *     (labels win, then query, then headers, then body);
  *     non-object bodies become a sole `body` member with `smithy.api#httpPayload`
  *   • `$ref`s become NAMED shapes (`components/schemas/X` → `<ns>#X`), reused
  *     across operations; anonymous nested objects synthesize names from the
  *     parent + member path
- *   • responses: 200 → 201 → 204 precedence, `application/json` only; object
+ *   • responses: 200 → 201 → 204 precedence (`successStatuses` overrides),
+ *     `application/json` only; object
  *     results become `<Op>Response` structures (a sole `$ref` reuses the named
  *     shape); bare array/scalar results wrap in a structure whose single
  *     member carries `com.distilled.openapi#rawResponse` (the SdkSpec maps it
- *     to a root pipe); no schema → `smithy.api#Unit`
+ *     to a root pipe); no schema → `smithy.api#Unit`; `head` is always
+ *     `smithy.api#Unit`, whatever content the spec declares
  *   • nullability (3.0 `nullable`, 3.1 `type: [..., "null"]`, 2.0
  *     `x-nullable`, `oneOf`/`anyOf` null branches) → member-level
  *     `com.distilled.openapi#nullable` trait
@@ -36,6 +44,15 @@
  *     (with the non-standard `mode` member the core runtime dispatches on)
  */
 
+import {
+  isMechanicalOperationId,
+  isVerbatimRouteId,
+  pathToVerbNoun,
+  resolveOperationName,
+  toVerbNoun,
+  type OperationIdRewrite,
+} from "./rewrite-operation-ids.ts";
+
 // ============================================================================
 // Trait ids (the `com.distilled.openapi` vocabulary)
 // ============================================================================
@@ -122,6 +139,37 @@ export interface OpenApiConvertOptions {
   readonly defaultErrorStatuses?: Iterable<string>;
   /** Skip operations marked `deprecated: true`. Default true. */
   readonly skipDeprecated?: boolean;
+  /**
+   * HTTP methods to convert IN ADDITION to get/post/put/patch/delete —
+   * currently `"head"` and `"options"`. Opt-in, so a provider that models
+   * them (Vercel probes cache artifacts and sandbox files with HEAD) gets
+   * them without every other provider silently gaining operations.
+   *
+   * `head` operations always output `smithy.api#Unit` — see the output-shape
+   * comment in {@link convertOpenApiToSmithy} for why a declared response
+   * body on a HEAD can never arrive.
+   */
+  readonly extraHttpMethods?: readonly ("head" | "options")[];
+  /**
+   * Emit `in: header` parameters as `smithy.api#httpHeader` members instead
+   * of dropping them. Opt-in for the same reason as
+   * {@link extraHttpMethods}: turning it on adds input members to every
+   * operation whose spec declares a header parameter, and most providers
+   * declare ones the protocol already sends itself (Accept, Authorization,
+   * an API-version pin). Providers whose headers are real per-call inputs
+   * — Vercel's `x-Artifact-*` remote-cache metadata, `x-Vercel-Digest` —
+   * ask for them.
+   */
+  readonly headerParams?: boolean;
+  /**
+   * Response statuses to read the operation's output shape from, most
+   * preferred first. Default `["200", "201", "204"]`. Extend it for an API
+   * that answers asynchronous work with a body under another status — Vercel
+   * returns `202 Accepted` with a payload from nine endpoints (artifact
+   * upload, account deletion, VCR blob/manifest writes), which would
+   * otherwise generate as a `void` output.
+   */
+  readonly successStatuses?: readonly string[];
   /**
    * Azure-style fixed `api-version`: drops `api-version` query params and
    * stamps {@link API_VERSION_TRAIT} on every operation.
@@ -140,6 +188,29 @@ export interface OpenApiConvertOptions {
    * {@link ERROR_MATCHERS_TRAIT} traits; overrides are merged over it.
    */
   readonly errorShapes?: Readonly<Record<string, any>>;
+  /**
+   * How to turn an OpenAPI `operationId` into the Smithy/SDK operation name.
+   * This is a convert policy, not a spec patch — the OpenAPI document is
+   * left alone.
+   *
+   * - `"verbNoun"` (default): `Apps_list` / `ConfigsList` / `showContact` →
+   *   `listApps` / `listConfigs` / `getApp`. Already verb-first ids stay.
+   *   An operation with no `operationId`, or a mechanical one that only
+   *   restates the method and path (`get-api-card`, `post_v1_users`), is
+   *   named from the route instead: `GET /users` → `listUsers`,
+   *   `GET /users/{id}` → `getUser`, `POST /users/{id}/reset` →
+   *   `resetUser`.
+   * - `"as-is"`: `PascalCase(operationId)` (`Apps_list` → `AppsList`).
+   *
+   * {@link operationNames} overrides win (lookup by `"METHOD path"`, then
+   * operationId).
+   */
+  readonly operationNaming?: "as-is" | "verbNoun";
+  /**
+   * Per-operation name overrides for {@link operationNaming}. Use
+   * `"METHOD path"` keys when two methods share an `operationId`.
+   */
+  readonly operationNames?: OperationIdRewrite;
 }
 
 export interface SmithyModel {
@@ -177,6 +248,24 @@ const memberIdent = (name: string): string => {
   return out || "_";
 };
 
+/**
+ * Header name → member identifier (`x-Artifact-Tag` → `xArtifactTag`). The
+ * wire name is carried by the `smithy.api#httpHeader` trait, so the member
+ * can read like the rest of the input rather than like a header.
+ */
+const headerMemberName = (name: string): string => {
+  const parts = name.split(/[^A-Za-z0-9]+/).filter(Boolean);
+  if (parts.length === 0) return "_";
+  const out = parts
+    .map((p, i) =>
+      i === 0
+        ? p.charAt(0).toLowerCase() + p.slice(1)
+        : p.charAt(0).toUpperCase() + p.slice(1),
+    )
+    .join("");
+  return /^[0-9]/.test(out) ? `_${out}` : out;
+};
+
 const enumMemberName = (value: string): string => {
   let out = value
     .toUpperCase()
@@ -763,7 +852,14 @@ const convertSchema = (
     const item = convertSchema(ctx, def.items, `${hint}Item`, depth + 1, dir);
     return {
       target: emit(
-        { type: "list", member: { target: item.target }, traits: docTraits },
+        {
+          type: "list",
+          member: {
+            target: item.target,
+            ...(item.nullable ? { traits: { [NULLABLE_TRAIT]: {} } } : {}),
+          },
+          traits: docTraits,
+        },
         reservedId !== undefined ? hint : `${hint}List`,
       ),
       nullable,
@@ -800,7 +896,10 @@ const convertSchema = (
           {
             type: "map",
             key: { target: PRELUDE.String },
-            value: { target: value.target },
+            value: {
+              target: value.target,
+              ...(value.nullable ? { traits: { [NULLABLE_TRAIT]: {} } } : {}),
+            },
             traits: docTraits,
           },
           reservedId !== undefined ? hint : `${hint}Map`,
@@ -937,7 +1036,11 @@ const collectParams = (ctx: Ctx, pathItem: any, op: any): Param[] => {
     byKey.set(`${p.in}${p.name}`, p);
   }
   return [...byKey.values()].filter(
-    (p) => p.in === "path" || p.in === "query" || p.in === "body",
+    (p) =>
+      p.in === "path" ||
+      p.in === "query" ||
+      p.in === "body" ||
+      p.in === "header",
   );
 };
 
@@ -1001,12 +1104,13 @@ const opDoc = (op: any): string | undefined => {
 // Responses
 // ============================================================================
 
-/** 200 → 201 → 204 precedence; response-level `$ref` resolved; JSON only. */
+/** First declared status in `order` wins; response-level `$ref` resolved; JSON only. */
 const successSchema = (
   ctx: Ctx,
   responses: any,
+  order: readonly string[],
 ): { schema: any | undefined } => {
-  for (const code of ["200", "201", "204"]) {
+  for (const code of order) {
     const raw = responses?.[code];
     if (!raw) continue;
     const resp = raw.$ref ? resolvePointer(ctx.spec, raw.$ref) : raw;
@@ -1019,6 +1123,37 @@ const successSchema = (
   return { schema: undefined };
 };
 
+/**
+ * Whether the success body is a collection: an array, or an object whose
+ * array members outnumber its scalar ones (envelopes like `{ data: [] }`,
+ * `{ items: [], total }`). `undefined` when there is no body to judge.
+ */
+const responseIsCollection = (
+  ctx: Ctx,
+  responses: any,
+  order: readonly string[],
+): boolean | undefined => {
+  const { schema } = successSchema(ctx, responses, order);
+  if (!schema) return undefined;
+  const s = deref(ctx, schema);
+  if (!s || typeof s !== "object") return undefined;
+  if (s.type === "array" || s.items) return true;
+  const props = s.properties;
+  if (!props || typeof props !== "object") {
+    return s.allOf || s.oneOf || s.anyOf ? undefined : false;
+  }
+  let arrays = 0;
+  let others = 0;
+  for (const prop of Object.values(props)) {
+    const p = deref(ctx, prop);
+    if (p?.type === "array" || p?.items) arrays++;
+    else others++;
+  }
+  if (arrays === 0) return false;
+  // `{ data: [...] }`, `{ items, next_cursor }`, `{ results, count, page }`
+  return arrays >= 1 && others <= 3;
+};
+
 // ============================================================================
 // Pagination detection (v0 detectPagination)
 // ============================================================================
@@ -1099,6 +1234,14 @@ const detectPagination = (
 
 const HTTP_METHODS = ["get", "post", "put", "patch", "delete"] as const;
 
+/**
+ * Methods a spec may declare beyond {@link HTTP_METHODS}, opt-in via
+ * {@link OpenApiConvertOptions.extraHttpMethods} — a provider that models
+ * `head` (Vercel's cache-artifact and file existence probes) asks for it
+ * rather than every provider silently gaining operations on regeneration.
+ */
+const OPTIONAL_HTTP_METHODS = ["head", "options"] as const;
+
 const DEFAULT_STATUS_TO_ERROR_CLASS: Readonly<Record<string, string>> = {
   "400": "BadRequest",
   "403": "Forbidden",
@@ -1109,6 +1252,8 @@ const DEFAULT_STATUS_TO_ERROR_CLASS: Readonly<Record<string, string>> = {
 
 const DEFAULT_ERROR_STATUSES = ["401", "429", "500", "503"];
 
+const DEFAULT_SUCCESS_STATUSES = ["200", "201", "204"];
+
 export const convertOpenApiToSmithy = (
   spec: unknown,
   options: OpenApiConvertOptions,
@@ -1131,6 +1276,13 @@ export const convertOpenApiToSmithy = (
     options.defaultErrorStatuses ?? DEFAULT_ERROR_STATUSES,
   );
   const skipDeprecated = options.skipDeprecated ?? true;
+  const successStatuses = options.successStatuses ?? DEFAULT_SUCCESS_STATUSES;
+  const httpMethods = [
+    ...HTTP_METHODS,
+    ...OPTIONAL_HTTP_METHODS.filter((m) =>
+      options.extraHttpMethods?.includes(m),
+    ),
+  ];
 
   // Error class names and the service name are reserved up front so schema
   // components can never steal them.
@@ -1145,16 +1297,65 @@ export const convertOpenApiToSmithy = (
 
   for (const [rawPath, pathItem] of Object.entries(doc.paths ?? {})) {
     if (!pathItem || typeof pathItem !== "object") continue;
-    for (const method of HTTP_METHODS) {
+    for (const method of httpMethods) {
       const op = (pathItem as any)[method];
       if (!op || typeof op !== "object") continue;
       if (skipDeprecated && op.deprecated === true) continue;
 
-      const opName = pascal(
+      const rawOperationId =
         typeof op.operationId === "string" && op.operationId
           ? op.operationId
-          : `${method}_${rawPath}`,
-      );
+          : `${method}_${rawPath}`;
+      const idCtx = { path: rawPath, method };
+      const naming = options.operationNaming ?? "verbNoun";
+      let named =
+        options.operationNames !== undefined
+          ? resolveOperationName(options.operationNames, rawOperationId, idCtx)
+          : undefined;
+      if (named === undefined && naming === "verbNoun") {
+        // A mechanical id (`get-api-card`, or none at all) is named from
+        // the route. A hand-chosen one that merely starts with the method
+        // and reads the route in order (`get-feeds` on /feeds) keeps its
+        // own nouns; only the HTTP-method verb is normalised.
+        if (typeof op.operationId !== "string" || !op.operationId) {
+          // No id: everything comes from the route, including whether a
+          // GET on a collection route is `list` or `get`.
+          named = pathToVerbNoun(idCtx, {
+            returnsCollection: responseIsCollection(
+              ctx,
+              op.responses,
+              successStatuses,
+            ),
+          });
+        } else if (isMechanicalOperationId(op.operationId, idCtx)) {
+          // Method-prefixed and reading the route (`get-feeds`,
+          // `postV1AppsByAppIdPromote`, `deleteProjectJWKS`): keep the
+          // author's tokens and casing; normalise `post`/`patch`, drop
+          // parameter clauses (`ByAppId`, `ById`) and api/version roots.
+          named = pathToVerbNoun(idCtx, {
+            nouns: op.operationId,
+            verbatim: isVerbatimRouteId(op.operationId, idCtx),
+          });
+        } else {
+          named = toVerbNoun(rawOperationId);
+        }
+      }
+      let resolved: string = named ?? rawOperationId;
+      // Two routes can derive the same name (`/collections/{slug}` and
+      // `/collections/{slug}-{id}`); suffix the trailing parameter rather
+      // than a counter.
+      if (
+        naming === "verbNoun" &&
+        ctx.names.has(pascal(resolved)) &&
+        isMechanicalOperationId(
+          typeof op.operationId === "string" ? op.operationId : undefined,
+          idCtx,
+        )
+      ) {
+        const lastParam = /\{([^}]+)\}[^/]*$/.exec(rawPath)?.[1];
+        if (lastParam) resolved = `${resolved}By${pascal(lastParam)}`;
+      }
+      const opName = pascal(resolved);
 
       const params = collectParams(ctx, pathItem, op);
 
@@ -1212,6 +1413,32 @@ export const convertOpenApiToSmithy = (
         });
       }
 
+      // ---- Header params (opt-in) ----
+      if (options.headerParams) {
+        for (const p of params) {
+          if (p.in !== "header") continue;
+          const conv = convertSchema(
+            ctx,
+            p.schema,
+            `${opName}Request${pascal(p.name)}`,
+            0,
+            "in",
+          );
+          addMember(headerMemberName(p.name), {
+            target: conv.target,
+            traits: {
+              // The wire name rides on the trait, so the member is free to be
+              // a normal identifier.
+              "smithy.api#httpHeader": p.name,
+              ...(p.required ? { "smithy.api#required": {} } : {}),
+              ...(p.description
+                ? { "smithy.api#documentation": p.description }
+                : {}),
+            },
+          });
+        }
+      }
+
       // ---- Request body (json > form-urlencoded > multipart) ----
       let contentType: "form-urlencoded" | "multipart" | undefined;
       let bodySchema: any;
@@ -1289,7 +1516,19 @@ export const convertOpenApiToSmithy = (
           : PRELUDE.Unit;
 
       // ---- Output shape ----
-      const { schema: respSchema } = successSchema(ctx, op.responses);
+      // A HEAD response carries no content, and not merely by convention:
+      // HTTP/1.1 framing terminates it at the end of the header section
+      // "regardless of the header fields present in the message" (RFC 9112
+      // §6.3), so a declared `Content-Length` describes what a GET *would*
+      // return and no body can reach the client. Specs declare one anyway —
+      // Vercel mirrors the GET's schema onto two of its HEAD probes and
+      // gives the other two a bare `{"nullable": true}` — and honouring it
+      // generates an output struct with required members that then fails to
+      // decode against the empty body on every successful call.
+      const { schema: respSchema } =
+        method === "head"
+          ? { schema: undefined }
+          : successSchema(ctx, op.responses, successStatuses);
       let outputTarget: string = PRELUDE.Unit;
       if (respSchema !== undefined) {
         const flat = flattenObject(ctx, respSchema);