@workos/oagen-emitters 0.18.3 → 0.19.0

package/src/kotlin/resources.ts

@@ -34,7 +34,7 @@ import {
 import {
   buildResolvedLookup,
   lookupResolved,
-  groupByMount,
+  scopedMountGroups,
   buildHiddenParams,
   getOpDefaults,
   getOpInferFromClient,
@@ -97,7 +97,7 @@ function promoteFieldType(f: Field): Field {
 export function generateResources(services: Service[], ctx: EmitterContext): GeneratedFile[] {
   if (services.length === 0) return [];
 
-  const mountGroups = groupByMount(ctx);
+  const mountGroups = scopedMountGroups(ctx);
   if (mountGroups.size === 0) return [];
 
   const files: GeneratedFile[] = [];

package/src/kotlin/tests.ts

@@ -17,11 +17,12 @@ import {
   ktStringLiteral,
   className,
   propertyName,
+  domainPropertyName,
   buildExportedClassNameSet,
 } from './naming.js';
 import { mapTypeRef } from './type-map.js';
 import {
-  groupByMount,
+  scopedMountGroups,
   lookupResolved,
   buildResolvedLookup,
   buildHiddenParams,
@@ -75,7 +76,7 @@ function promoteIso8601TypeRef(type: TypeRef, description: string | undefined):
  */
 export function generateTests(spec: ApiSpec, ctx: EmitterContext): GeneratedFile[] {
   const files: GeneratedFile[] = [];
-  const mountGroups = groupByMount(ctx);
+  const mountGroups = scopedMountGroups(ctx);
   const resolvedLookup = buildResolvedLookup(ctx);
 
   const exportedClasses = buildExportedClassNameSet(ctx);
@@ -713,7 +714,10 @@ function buildResponseAssertions(
   for (const field of model.fields) {
     if (!field.required) continue;
     if (assertions.length >= MAX_RESPONSE_ASSERTIONS) break;
-    const ktProp = propertyName(field.name);
+    // DOMAIN identifier: the property accessor on the deserialized model.
+    // Honors a `domainName` override; the synthesized JSON above keys off
+    // `field.name` (the wire key).
+    const ktProp = domainPropertyName(field);
     const type = field.type;
     if (type.kind === 'primitive') {
       if (type.format === 'date-time') continue;

package/src/node/enums.ts

@@ -5,6 +5,7 @@ import { docComment, assignModelsToEmittableServices } from './utils.js';
 import { isInlineEnum } from './type-map.js';
 import { isNodeOwnedService } from './options.js';
 import { liveSurfaceConstEnumMembers, liveSurfaceInterfacePath } from './live-surface.js';
+import { isEnumInScope } from '../shared/resolved-ops.js';
 
 export function generateEnums(enums: Enum[], ctx: EmitterContext): GeneratedFile[] {
   if (enums.length === 0) return [];
@@ -120,11 +121,13 @@ export function generateEnums(enums: Enum[], ctx: EmitterContext): GeneratedFile
       lines.push(`  (typeof ${enumDef.name})[keyof typeof ${enumDef.name}];`);
     }
 
-    files.push({
-      path: `src/${dirName}/interfaces/${fileName(enumDef.name)}.interface.ts`,
-      content: lines.join('\n'),
-      skipIfExists: !hasNewValues,
-    });
+    if (isEnumInScope(enumDef.name, ctx)) {
+      files.push({
+        path: `src/${dirName}/interfaces/${fileName(enumDef.name)}.interface.ts`,
+        content: lines.join('\n'),
+        skipIfExists: !hasNewValues,
+      });
+    }
   }
 
   return files;

package/src/node/field-plan.ts

@@ -388,7 +388,7 @@ export function serializerHasBaselineIncompatibility(
   const irDomainFields = new Set<string>();
   for (const field of model.fields) {
     irWireFields.add(wireFieldName(field.name));
-    irDomainFields.add(fieldName(field.name));
+    irDomainFields.add(fieldName(field.domainName ?? field.name));
   }
 
   for (const [wireField2, fieldDef] of Object.entries(baselineResponse.fields)) {
@@ -463,7 +463,7 @@ export function planDeserializeField(
   skipFormatFields: Set<string>,
   ctx: EmitterContext,
 ): { line: string; skip: boolean } {
-  const domain = fieldName(field.name);
+  const domain = fieldName(field.domainName ?? field.name);
   const wire = wireFieldName(field.name);
   const wireAccess = `response.${wire}`;
   const skip = skipFormatFields.has(field.name);
@@ -543,7 +543,7 @@ export function planSerializeField(
   ctx: EmitterContext,
 ): { line: string; skip: boolean } {
   const wire = wireFieldName(field.name);
-  const domain = fieldName(field.name);
+  const domain = fieldName(field.domainName ?? field.name);
   const domainAccess = `model.${domain}`;
   const skip = skipFormatFields.has(field.name);
 

package/src/node/index.ts

@@ -40,6 +40,7 @@ import { withNodeOperationOverrides } from './node-overrides.js';
 import { isNodeOwnedService, nodeOptions } from './options.js';
 import { setInlineEnumUnions, setDomainNameResolver } from './type-map.js';
 import { groupByMount } from '../shared/resolved-ops.js';
+import { AUTOGEN_NOTICE } from '../shared/file-header.js';
 import { assignModelsToServices, createServiceDirResolver, relativeImport } from './utils.js';
 import { fileName } from './naming.js';
 
@@ -869,7 +870,7 @@ export const nodeEmitter: Emitter = {
   },
 
   fileHeader(): string {
-    return '// This file is auto-generated by oagen. Do not edit.';
+    return `// ${AUTOGEN_NOTICE}`;
   },
 
   formatCommand(targetDir: string): FormatCommand | null {

package/src/node/models.ts

@@ -45,7 +45,7 @@ import {
 import { liveSurfaceHasExistingSdk, liveSurfaceHasManagedFile, liveSurfaceInterfacePath } from './live-surface.js';
 import { isNodeOwnedService, isHandOwnedType } from './options.js';
 import { unwrapListModel } from './fixtures.js';
-import { groupByMount, buildResolvedLookup, lookupResolved } from '../shared/resolved-ops.js';
+import { groupByMount, buildResolvedLookup, lookupResolved, isModelInScope } from '../shared/resolved-ops.js';
 import { resolveWrapperParams } from '../shared/wrapper-utils.js';
 import { collectWrapperResponseModels } from './wrappers.js';
 import { resolveResourceClassName } from './resources.js';
@@ -308,11 +308,13 @@ export function generateModels(models: Model[], ctx: EmitterContext, shared?: Sh
       const aliasLines = importSymbols
         ? [`import type { ${importSymbols} } from '${canonRelPath}';`, '', ...aliasExports]
         : [...aliasExports];
-      files.push({
-        path: aliasPath,
-        content: aliasLines.join('\n'),
-        overwriteExisting: true,
-      });
+      if (isModelInScope(model.name, ctx)) {
+        files.push({
+          path: aliasPath,
+          content: aliasLines.join('\n'),
+          overwriteExisting: true,
+        });
+      }
       continue;
     }
 
@@ -527,7 +529,9 @@ export function generateModels(models: Model[], ctx: EmitterContext, shared?: Sh
     } else {
       lines.push(`export interface ${domainName}${typeParams} {`);
       for (const field of model.fields) {
-        const domainFieldName = fieldName(field.name);
+        // Domain identifier honors a `fieldHints` override (e.g. connection_type
+        // → type); the wire name below still derives from `field.name`.
+        const domainFieldName = fieldName(field.domainName ?? field.name);
         if (seenDomainFields.has(domainFieldName)) continue;
         seenDomainFields.add(domainFieldName);
         if (field.description || field.deprecated || field.readOnly || field.writeOnly || field.default !== undefined) {
@@ -546,6 +550,19 @@ export function generateModels(models: Model[], ctx: EmitterContext, shared?: Sh
           baselineField && !baselineField.optional && responseBaselineField && responseBaselineField.optional;
         const readonlyPrefix = field.readOnly ? 'readonly ' : '';
         if (
+          genericDefaults.has(model.name) &&
+          baselineField &&
+          typeReferencesUnresolvable(baselineField.type, unresolvableNames)
+        ) {
+          // Baseline typed this field with the model's generic param (e.g.
+          // `customAttributes?: CustomAttributesType`). The emitted interface
+          // renames the param to `GenericType`; remap the field so the param is
+          // actually used — otherwise it trips TS6133 (declared, never read).
+          const opt = baselineField.optional ? '?' : '';
+          lines.push(
+            `  ${readonlyPrefix}${domainFieldName}${opt}: ${substituteGenericParam(baselineField.type, unresolvableNames)};`,
+          );
+        } else if (
           baselineField &&
           !domainResponseOptionalMismatch &&
           !hasDateTimeConversion(field.type) &&
@@ -597,6 +614,15 @@ export function generateModels(models: Model[], ctx: EmitterContext, shared?: Sh
           seenWireFields.add(wireField);
           const baselineField = baselineResponse?.fields?.[wireField];
           if (
+            genericDefaults.has(model.name) &&
+            baselineField &&
+            typeReferencesUnresolvable(baselineField.type, unresolvableNames)
+          ) {
+            // Mirror the domain side: keep the generic param wired on the
+            // response interface so `GenericType` is used, not orphaned.
+            const opt = baselineField.optional ? '?' : '';
+            lines.push(`  ${wireField}${opt}: ${substituteGenericParam(baselineField.type, unresolvableNames)};`);
+          } else if (
             baselineField &&
             baselineTypeResolvable(baselineField.type, importableNames) &&
             baselineFieldCompatible(baselineField, field)
@@ -721,11 +747,13 @@ export function generateModels(models: Model[], ctx: EmitterContext, shared?: Sh
       }
     }
 
-    files.push({
-      path: filePath,
-      content: pruneUnusedImports(lines).join('\n'),
-      overwriteExisting: true,
-    });
+    if (isModelInScope(model.name, ctx)) {
+      files.push({
+        path: filePath,
+        content: pruneUnusedImports(lines).join('\n'),
+        overwriteExisting: true,
+      });
+    }
   }
 
   return files;
@@ -919,11 +947,13 @@ export function generateSerializers(
           parts.push(`serialize${canonDomainName} as serialize${domainName}`);
         }
         const reexportContent = `export { ${parts.join(', ')} } from '${rel}';`;
-        files.push({
-          path: serializerPath,
-          content: reexportContent,
-          overwriteExisting: true,
-        });
+        if (isModelInScope(model.name, ctx)) {
+          files.push({
+            path: serializerPath,
+            content: reexportContent,
+            overwriteExisting: true,
+          });
+        }
         continue;
       }
       // The alias is response-reachable, but the canonical model is
@@ -973,11 +1003,13 @@ export function generateSerializers(
       ),
     ];
 
-    files.push({
-      path: serializerPath,
-      content: pruneUnusedImports(lines).join('\n'),
-      overwriteExisting: true,
-    });
+    if (isModelInScope(model.name, ctx)) {
+      files.push({
+        path: serializerPath,
+        content: pruneUnusedImports(lines).join('\n'),
+        overwriteExisting: true,
+      });
+    }
   }
 
   (ctx as any)._skippedSerializeModels = skippedSerializeModels;
@@ -1301,6 +1333,21 @@ function hasSpecificIRType(ref: TypeRef): boolean {
   }
 }
 
+/** True when a baseline field type references one of the model's generic
+ *  param identifiers (collected as `unresolvableNames` — bare type names that
+ *  resolve to nothing importable, which for a generic model are its params). */
+function typeReferencesUnresolvable(type: string, unresolvable: Set<string>): boolean {
+  if (unresolvable.size === 0) return false;
+  const names = type.match(/\b[A-Z][a-zA-Z0-9]*\b/g);
+  return !!names && names.some((n) => unresolvable.has(n));
+}
+
+/** Rewrite a baseline field type so references to the model's (renamed)
+ *  generic param resolve to the emitted `GenericType` param. */
+function substituteGenericParam(type: string, unresolvable: Set<string>): string {
+  return type.replace(/\b[A-Z][a-zA-Z0-9]*\b/g, (name) => (unresolvable.has(name) ? 'GenericType' : name));
+}
+
 function renderTypeParams(model: Model, genericDefaults?: Map<string, string>): string {
   if (!model.typeParams?.length) {
     if (genericDefaults?.has(model.name)) {

package/src/node/naming.ts

@@ -32,6 +32,16 @@ export function fieldName(name: string): string {
   return toCamelCase(name);
 }
 
+/**
+ * camelCase domain field name for a model field, honoring a `domainName`
+ * override (set via the `fieldHints` config) so a wire field can surface under
+ * a friendlier name. The wire name (see {@link wireFieldName}) still derives
+ * from `field.name`.
+ */
+export function domainFieldName(field: { name: string; domainName?: string }): string {
+  return toCamelCase(field.domainName ?? field.name);
+}
+
 /** snake_case field name for wire/response interfaces. */
 export function wireFieldName(name: string): string {
   return toSnakeCase(name);

package/src/node/options.ts

@@ -1,14 +1,35 @@
-import type { EmitterContext } from '@workos/oagen';
+import type { EmitterContext, Operation, OperationPlan } from '@workos/oagen';
+import { planOperation } from '@workos/oagen';
 
 export interface OperationOverride {
   methodName?: string;
   mountOn?: string;
   optionsType?: string;
   bodyFieldMap?: Record<string, string>;
+  /**
+   * Rename spec path parameters to the SDK options-object field they should be
+   * exposed as. Keys are the camelCase identifier the param resolves to via
+   * `fieldName(param.name)` — NOT the raw (possibly snake_case) spec key — since
+   * the lookup is keyed on that camelCase form (e.g. `{ resourceId: 'targetId' }`,
+   * even for a `resource_id` spec param). Applied to the destructure, the URL
+   * template binding, and generated tests so a published SDK field name can
+   * diverge from the spec path-param name without a global spec rewrite (which
+   * would ripple across every language).
+   */
+  pathFieldMap?: Record<string, string>;
   returnType?: string;
   returnDataProperty?: string;
   returnTypeImports?: string[];
   returnExpression?: string;
+  /**
+   * Override the response model the operation deserializes, by model name.
+   * Replaces the spec-derived response model so the resource (and its test)
+   * reference a different wire type / deserializer — e.g. mapping
+   * Authorization's role responses to the full `OrganizationRole` instead of
+   * the slim `Role`/`RoleResponse` shape shared with SSO and UserManagement.
+   * Node-only; never affects the global spec or other SDKs.
+   */
+  responseModel?: string;
 }
 
 export interface NodeEmitterOptions {
@@ -90,3 +111,26 @@ export function isHandOwnedType(ctx: EmitterContext, name: string | undefined):
   if (!configured || configured.length === 0) return false;
   return configured.includes(name);
 }
+
+/**
+ * Resolve the Node operation override for an operation, keyed by "METHOD /path".
+ */
+export function operationOverrideFor(ctx: EmitterContext, op: Operation): OperationOverride | undefined {
+  return nodeOptions(ctx).operationOverrides?.[`${op.httpMethod.toUpperCase()} ${op.path}`];
+}
+
+/**
+ * `planOperation` plus the Node `responseModel` override. When an operation
+ * override supplies `responseModel`, the resolved response model name is
+ * replaced so the resource and its generated test reference the desired wire
+ * type and deserializer. Use this everywhere the Node emitter would otherwise
+ * call `planOperation(op)` directly so resource and test stay in lockstep.
+ */
+export function planOperationFor(op: Operation, ctx: EmitterContext): OperationPlan {
+  const plan = planOperation(op);
+  const responseModel = operationOverrideFor(ctx, op)?.responseModel;
+  if (responseModel && responseModel !== plan.responseModelName) {
+    return { ...plan, responseModelName: responseModel, isModelResponse: true };
+  }
+  return plan;
+}

package/src/node/resources.ts

@@ -11,7 +11,7 @@ import type {
   Model,
   ResolvedOperation,
 } from '@workos/oagen';
-import { planOperation, toPascalCase, toCamelCase } from '@workos/oagen';
+import { toPascalCase, toCamelCase } from '@workos/oagen';
 import type { OperationPlan } from '@workos/oagen';
 import { mapTypeRef, isInlineEnum } from './type-map.js';
 import {
@@ -78,13 +78,14 @@ import {
   buildResolvedLookup,
   lookupResolved,
   groupByMount,
+  isMountInScope,
   getOpDefaults,
   getOpInferFromClient,
 } from '../shared/resolved-ops.js';
 import { generateWrapperMethods, collectWrapperResponseModels } from './wrappers.js';
 import { buildNodePathExpression } from './path-expression.js';
 import { resolveWrapperParams } from '../shared/wrapper-utils.js';
-import { isNodeOwnedService, nodeOptions } from './options.js';
+import { isNodeOwnedService, operationOverrideFor, planOperationFor } from './options.js';
 
 /**
  * Check whether the baseline (hand-written) class has a constructor compatible
@@ -202,16 +203,12 @@ function existingInterfaceBarrelExports(ctx: EmitterContext, serviceDir: string,
   return new RegExp(`export\\s+(?:type\\s+)?(?:\\*|\\{[^}]+\\})\\s+from\\s+['"]\\./${escapedStem}['"]`).test(content);
 }
 
-function operationOverrideFor(ctx: EmitterContext, op: Operation) {
-  return nodeOptions(ctx).operationOverrides?.[`${op.httpMethod.toUpperCase()} ${op.path}`];
-}
-
 function baselineMethodFor(service: Service, method: string, ctx: EmitterContext): BaselineMethod | undefined {
   const serviceClass = resolveResourceClassName(service, ctx);
   return ctx.apiSurface?.classes?.[serviceClass]?.methods?.[method]?.[0] as BaselineMethod | undefined;
 }
 
-function ignoredResourceMethodNames(ctx: EmitterContext, resourcePath: string): Set<string> {
+export function ignoredResourceMethodNames(ctx: EmitterContext, resourcePath: string): Set<string> {
   const root = ctx.outputDir ?? ctx.targetDir;
   if (!root) return new Set();
 
@@ -242,8 +239,13 @@ function optionsObjectParam(method: BaselineMethod | undefined): OptionsObjectPa
   const [param] = method.params;
   if (param.name !== 'options') return undefined;
   if (param.passingStyle && param.passingStyle !== 'options_object') return undefined;
-  if (!param.type || /^(Record|object|any|unknown)\b/.test(param.type)) return undefined;
-  return { name: 'options', type: param.type, optional: param.optional === true, generated: false };
+  // An optional param's surface type is `Options | undefined`; the optionality
+  // is carried by `param.optional`, so strip the nullable arm to recover the
+  // bare type NAME (used for `serialize${type}` + imports). Leaving it in emits
+  // `serializeOptions | undefined` — a syntax error.
+  const type = param.type?.replace(/(?:\s*\|\s*(?:undefined|null))+\s*$/, '').trim();
+  if (!type || /^(Record|object|any|unknown)\b/.test(type)) return undefined;
+  return { name: 'options', type, optional: param.optional === true, generated: false };
 }
 
 function methodOptionsName(method: string, resolvedServiceName: string): string {
@@ -568,7 +570,7 @@ function generateOptionsInterfaces(service: Service, ctx: EmitterContext, specEn
 
   const plans = service.operations.map((op) => ({
     op,
-    plan: planOperation(op),
+    plan: planOperationFor(op, ctx),
     method: resolveMethodName(op, service, ctx),
   }));
 
@@ -577,7 +579,13 @@ function generateOptionsInterfaces(service: Service, ctx: EmitterContext, specEn
     const baselineMethod = baselineMethodFor(service, method, ctx);
     const optionInfo = optionsObjectInfo(service, method, op, plan, ctx, baselineMethod, resolvedOp);
     if (!optionInfo?.generated) continue;
-    if (baselineTypeSourceFile(ctx, optionInfo.type)) continue;
+    // A baseline type of the same name normally means "hand-owned / preserved —
+    // do not regenerate" (guards the alias-feedback loop). But when the op has
+    // path params, the modernized resource folds them INTO the options object
+    // (`const { organizationId, ...payload } = options`), so a body-only
+    // baseline interface (from a legacy `(pathParam, options)` signature) is
+    // definitionally incompatible. Regenerate it to include the path params.
+    if (op.pathParams.length === 0 && baselineTypeSourceFile(ctx, optionInfo.type)) continue;
 
     const optionsName = optionInfo.type;
     const optionFileStem = `${fileName(optionsName)}.interface`;
@@ -645,9 +653,10 @@ function generateOptionsInterfaces(service: Service, ctx: EmitterContext, specEn
       headerParts.push(`  ${name}${opt}: ${type};`);
     };
 
+    const optionsPathFieldMap = operationOverrideFor(ctx, op)?.pathFieldMap;
     for (const param of op.pathParams) {
       pushField(
-        fieldName(param.name),
+        optionsPathFieldMap?.[fieldName(param.name)] ?? fieldName(param.name),
         true,
         mapParamType(param.type, specEnumNames),
         param.description,
@@ -710,11 +719,18 @@ export function generateResources(services: Service[], ctx: EmitterContext): Gen
   // multiple IR services mount to the same resource class.
   const mountGroups = groupByMount(ctx);
   const mergedServices: Service[] =
-    mountGroups.size > 0 ? [...mountGroups].map(([name, group]) => ({ name, operations: group.operations })) : services;
+    mountGroups.size > 0 || ctx.scopedServices?.size
+      ? [...mountGroups].map(([name, group]) => ({ name, operations: group.operations }))
+      : services;
 
   const topLevelEnumNames = new Set(ctx.spec.enums.map((e) => e.name));
 
   for (const service of mergedServices) {
+    // Scope gate: in a scoped (`--services`) run, only emit per-service resource
+    // files for the selected post-mount names. `service.name` is the mount-group
+    // key (the POST-MOUNT name that matches `ctx.scopedServices`). Applied as an
+    // additional early continue ahead of the node-owned/coverage skip logic.
+    if (!isMountInScope(service.name, ctx)) continue;
     const isOwnedService = isNodeOwnedService(ctx, service.name, resolveResourceClassName(service, ctx));
     if (!isOwnedService && isServiceCoveredByExisting(service, ctx)) {
       if (!hasMethodsAbsentFromBaseline(service, ctx)) {
@@ -762,6 +778,9 @@ export function generateResources(services: Service[], ctx: EmitterContext): Gen
   // stable.  Placing them under `interfaces/` lets the per-service barrel
   // pick them up automatically.
   for (const service of mergedServices) {
+    // Scope gate: keep the per-service options interfaces aligned with the
+    // resource files emitted above — only the selected post-mount names.
+    if (!isMountInScope(service.name, ctx)) continue;
     const isOwnedService = isNodeOwnedService(ctx, service.name, resolveResourceClassName(service, ctx));
     if (!isOwnedService && isServiceCoveredByExisting(service, ctx) && !hasMethodsAbsentFromBaseline(service, ctx))
       continue;
@@ -779,7 +798,7 @@ function generateResourceClass(service: Service, ctx: EmitterContext): Generated
 
   let plans = service.operations.map((op) => ({
     op,
-    plan: planOperation(op),
+    plan: planOperationFor(op, ctx),
     method: resolveMethodName(op, service, ctx),
   }));
 
@@ -1038,6 +1057,10 @@ function generateResourceClass(service: Service, ctx: EmitterContext): Generated
   }
 
   const importedTypeNames = new Set<string>();
+  // `PaginationOptions` is already imported once above when any method
+  // paginates; a method whose options type IS `PaginationOptions` would
+  // otherwise re-import it here (TS2300 duplicate identifier).
+  if (needsPaginationOptionsImport) importedTypeNames.add('PaginationOptions');
   for (const optionType of optionObjectTypes) {
     if (isValidTypeIdentifier(optionType)) {
       if (importedTypeNames.has(optionType)) continue;
@@ -1954,7 +1977,20 @@ function renderOptionsObjectMethod(
     return true;
   }
 
-  return false;
+  // Body-less, response-less mutation with path params and/or query folded into
+  // the options object (e.g. POST /feature-flags/{slug}/targets/{targetId} -> 204).
+  // The DELETE equivalent is handled above; this covers POST/PUT/PATCH (and any
+  // other verb) that returns no content. Without this branch such operations
+  // fall through to the positional renderVoidMethod, which is inconsistent with
+  // the options-object surface the rest of an owned service uses.
+  {
+    lines.push(`  async ${method}(${renderOptionsParam(optionParam)}): Promise<void> {`);
+    renderOptionsObjectDestructure(lines, pathBindings);
+    const emptyBodyArg = httpMethodNeedsBody(op.httpMethod) ? ', {}' : '';
+    lines.push(`    await this.workos.${op.httpMethod}(${pathStr}${emptyBodyArg}${queryOptionsArg});`);
+    lines.push('  }');
+    return true;
+  }
 }
 
 function renderOptionsObjectDestructure(lines: string[], pathBindings: string[], restName?: string): void {
@@ -1988,7 +2024,8 @@ function buildOptionsObjectPathBindings(op: Operation, optionType: string, ctx:
   // Return resolved SDK field names directly — the URL template uses these
   // names too (via the param-name map threaded into buildNodePathExpression),
   // so the destructure no longer needs `optionField: localName` renames.
-  return op.pathParams.map((param) => resolveOptionsObjectField(fieldName(param.name), optionType, ctx));
+  const pathFieldMap = operationOverrideFor(ctx, op)?.pathFieldMap;
+  return op.pathParams.map((param) => resolveOptionsObjectField(fieldName(param.name), optionType, ctx, pathFieldMap));
 }
 
 /**
@@ -2000,15 +2037,27 @@ function buildOptionsObjectPathBindings(op: Operation, optionType: string, ctx:
  */
 function buildOptionsObjectPathParamMap(op: Operation, optionType: string, ctx: EmitterContext): Map<string, string> {
   const map = new Map<string, string>();
+  const pathFieldMap = operationOverrideFor(ctx, op)?.pathFieldMap;
   for (const param of op.pathParams) {
     const localName = fieldName(param.name);
-    const sdkField = resolveOptionsObjectField(localName, optionType, ctx);
+    const sdkField = resolveOptionsObjectField(localName, optionType, ctx, pathFieldMap);
     if (sdkField !== localName) map.set(param.name, sdkField);
   }
   return map;
 }
 
-function resolveOptionsObjectField(localName: string, optionType: string, ctx: EmitterContext): string {
+function resolveOptionsObjectField(
+  localName: string,
+  optionType: string,
+  ctx: EmitterContext,
+  pathFieldMap?: Record<string, string>,
+): string {
+  // Operation-override rename (Node-scoped) wins unconditionally: an explicit
+  // pathFieldMap is honored even when the (freshly generated) options interface
+  // isn't in the baseline surface yet — generateOptionsInterfaces applies the
+  // same map to the emitted field, so destructure and interface stay in lockstep.
+  const mapped = pathFieldMap?.[localName];
+  if (mapped) return mapped;
   const fields = ctx.apiSurface?.interfaces?.[optionType]?.fields;
   if (!fields) return localName;
   if (fields[localName]) return localName;