@workos/oagen-emitters 0.18.3 → 0.18.4

package/dist/{plugin-1ckLMpgo.mjs → plugin-Cciic50q.mjs}

@@ -3637,6 +3637,29 @@ function isHandOwnedType(ctx, name) {
 	if (!configured || configured.length === 0) return false;
 	return configured.includes(name);
 }
+/**
+* Resolve the Node operation override for an operation, keyed by "METHOD /path".
+*/
+function operationOverrideFor$1(ctx, op) {
+	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.
+*/
+function planOperationFor(op, ctx) {
+	const plan = planOperation(op);
+	const responseModel = operationOverrideFor$1(ctx, op)?.responseModel;
+	if (responseModel && responseModel !== plan.responseModelName) return {
+		...plan,
+		responseModelName: responseModel,
+		isModelResponse: true
+	};
+	return plan;
+}
 //#endregion
 //#region src/node/live-surface.ts
 const SRC_DIR = "src";
@@ -4913,7 +4936,7 @@ function serializerHasBaselineIncompatibility(model, baselineResponse, baselineD
 	const irDomainFields = /* @__PURE__ */ new Set();
 	for (const field of model.fields) {
 		irWireFields.add(wireFieldName(field.name));
-		irDomainFields.add(fieldName$6(field.name));
+		irDomainFields.add(fieldName$6(field.domainName ?? field.name));
 	}
 	for (const [wireField2, fieldDef] of Object.entries(baselineResponse.fields)) {
 		if (fieldDef.optional) continue;
@@ -4957,7 +4980,7 @@ function serializerHasBaselineIncompatibility(model, baselineResponse, baselineD
 	return false;
 }
 function planDeserializeField(field, baselineDomain, baselineResponse, skipFormatFields, ctx) {
-	const domain = fieldName$6(field.name);
+	const domain = fieldName$6(field.domainName ?? field.name);
 	const wireAccess = `response.${wireFieldName(field.name)}`;
 	const skip = skipFormatFields.has(field.name);
 	const baselineDomainField = baselineDomain?.fields?.[domain];
@@ -4993,7 +5016,7 @@ function planDeserializeGuard(field, expr, wireAccess, effectivelyOptional, isNe
 }
 function planSerializeField(field, baselineDomain, baselineResponse, skipFormatFields, ctx) {
 	const wire = wireFieldName(field.name);
-	const domain = fieldName$6(field.name);
+	const domain = fieldName$6(field.domainName ?? field.name);
 	const domainAccess = `model.${domain}`;
 	const skip = skipFormatFields.has(field.name);
 	const baselineWireField = baselineResponse?.fields?.[wire];
@@ -5533,9 +5556,6 @@ function existingInterfaceBarrelExports(ctx, serviceDir, stem) {
 	const escapedStem = stem.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 	return new RegExp(`export\\s+(?:type\\s+)?(?:\\*|\\{[^}]+\\})\\s+from\\s+['"]\\./${escapedStem}['"]`).test(content);
 }
-function operationOverrideFor$1(ctx, op) {
-	return nodeOptions(ctx).operationOverrides?.[`${op.httpMethod.toUpperCase()} ${op.path}`];
-}
 function baselineMethodFor$1(service, method, ctx) {
 	const serviceClass = resolveResourceClassName$3(service, ctx);
 	return ctx.apiSurface?.classes?.[serviceClass]?.methods?.[method]?.[0];
@@ -5561,10 +5581,11 @@ function optionsObjectParam$1(method) {
 	const [param] = method.params;
 	if (param.name !== "options") return void 0;
 	if (param.passingStyle && param.passingStyle !== "options_object") return void 0;
-	if (!param.type || /^(Record|object|any|unknown)\b/.test(param.type)) return void 0;
+	const type = param.type?.replace(/(?:\s*\|\s*(?:undefined|null))+\s*$/, "").trim();
+	if (!type || /^(Record|object|any|unknown)\b/.test(type)) return void 0;
 	return {
 		name: "options",
-		type: param.type,
+		type,
 		optional: param.optional === true,
 		generated: false
 	};
@@ -5765,14 +5786,14 @@ function generateOptionsInterfaces(service, ctx, specEnumNames) {
 	const resolvedLookup = buildResolvedLookup(ctx);
 	const plans = service.operations.map((op) => ({
 		op,
-		plan: planOperation(op),
+		plan: planOperationFor(op, ctx),
 		method: resolveMethodName$6(op, service, ctx)
 	}));
 	for (const { op, plan, method } of plans) {
 		const resolvedOp = lookupResolved(op, resolvedLookup);
 		const optionInfo = optionsObjectInfo(service, method, op, plan, ctx, baselineMethodFor$1(service, method, ctx), resolvedOp);
 		if (!optionInfo?.generated) continue;
-		if (baselineTypeSourceFile(ctx, optionInfo.type)) continue;
+		if (op.pathParams.length === 0 && baselineTypeSourceFile(ctx, optionInfo.type)) continue;
 		const optionsName = optionInfo.type;
 		const optionFileStem = `${fileName$3(optionsName)}.interface`;
 		const filePath = `src/${serviceDir}/interfaces/${optionFileStem}.ts`;
@@ -5815,7 +5836,8 @@ function generateOptionsInterfaces(service, ctx, specEnumNames) {
 			}
 			headerParts.push(`  ${name}${opt}: ${type};`);
 		};
-		for (const param of op.pathParams) pushField(fieldName$6(param.name), true, mapParamType(param.type, specEnumNames), param.description, param.deprecated);
+		const optionsPathFieldMap = operationOverrideFor$1(ctx, op)?.pathFieldMap;
+		for (const param of op.pathParams) pushField(optionsPathFieldMap?.[fieldName$6(param.name)] ?? fieldName$6(param.name), true, mapParamType(param.type, specEnumNames), param.description, param.deprecated);
 		for (const param of visibleQueryParamsForOptions(op, plan, resolvedOp)) pushField(fieldName$6(param.name), param.required, mapParamType(param.type, specEnumNames), param.description, param.deprecated);
 		if (bodyInfo?.kind === "model") {
 			const bodyModel = ctx.spec.models.find((m) => m.name === bodyInfo.name);
@@ -5887,7 +5909,7 @@ function generateResourceClass(service, ctx) {
 	const resourcePath = `src/${serviceDir}/${fileName$3(resolvedName)}.ts`;
 	let plans = service.operations.map((op) => ({
 		op,
-		plan: planOperation(op),
+		plan: planOperationFor(op, ctx),
 		method: resolveMethodName$6(op, service, ctx)
 	}));
 	deduplicateMethodNames(plans, ctx);
@@ -5996,6 +6018,7 @@ function generateResourceClass(service, ctx) {
 	const hasCustomEncoding = plans.some((p) => p.op.requestBodyEncoding && p.op.requestBodyEncoding !== "json" && p.plan.hasBody);
 	if (hasIdempotentPost || hasCustomEncoding) lines.push("import type { PostOptions } from '../common/interfaces/post-options.interface';");
 	const importedTypeNames = /* @__PURE__ */ new Set();
+	if (needsPaginationOptionsImport) importedTypeNames.add("PaginationOptions");
 	for (const optionType of optionObjectTypes) {
 		if (isValidTypeIdentifier(optionType)) {
 			if (importedTypeNames.has(optionType)) continue;
@@ -6554,7 +6577,14 @@ function renderOptionsObjectMethod(lines, op, plan, method, service, ctx, modelM
 		lines.push("  }");
 		return true;
 	}
-	return false;
+	{
+		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, pathBindings, restName) {
 	if (pathBindings.length > 0 && restName) lines.push(`    const { ${pathBindings.join(", ")}, ...${restName} } = options;`);
@@ -6574,7 +6604,8 @@ function bodyArgExprWithParam(bodyExpr, paramName) {
 	return paramName === "payload" ? bodyExpr : bodyExpr.replace(/\bpayload\b/g, paramName);
 }
 function buildOptionsObjectPathBindings(op, optionType, ctx) {
-	return op.pathParams.map((param) => resolveOptionsObjectField$1(fieldName$6(param.name), optionType, ctx));
+	const pathFieldMap = operationOverrideFor$1(ctx, op)?.pathFieldMap;
+	return op.pathParams.map((param) => resolveOptionsObjectField$1(fieldName$6(param.name), optionType, ctx, pathFieldMap));
 }
 /**
 * Map spec path-param names (e.g. `omId`) to the SDK field name exposed on
@@ -6585,14 +6616,17 @@ function buildOptionsObjectPathBindings(op, optionType, ctx) {
 */
 function buildOptionsObjectPathParamMap(op, optionType, ctx) {
 	const map = /* @__PURE__ */ new Map();
+	const pathFieldMap = operationOverrideFor$1(ctx, op)?.pathFieldMap;
 	for (const param of op.pathParams) {
 		const localName = fieldName$6(param.name);
-		const sdkField = resolveOptionsObjectField$1(localName, optionType, ctx);
+		const sdkField = resolveOptionsObjectField$1(localName, optionType, ctx, pathFieldMap);
 		if (sdkField !== localName) map.set(param.name, sdkField);
 	}
 	return map;
 }
-function resolveOptionsObjectField$1(localName, optionType, ctx) {
+function resolveOptionsObjectField$1(localName, optionType, ctx, pathFieldMap) {
+	const mapped = pathFieldMap?.[localName];
+	if (mapped) return mapped;
 	const fields = ctx.apiSurface?.interfaces?.[optionType]?.fields;
 	if (!fields) return localName;
 	if (fields[localName]) return localName;
@@ -7548,7 +7582,7 @@ function generateModels$7(models, ctx, shared) {
 		else {
 			lines.push(`export interface ${domainName}${typeParams} {`);
 			for (const field of model.fields) {
-				const domainFieldName = fieldName$6(field.name);
+				const domainFieldName = fieldName$6(field.domainName ?? field.name);
 				if (seenDomainFields.has(domainFieldName)) continue;
 				seenDomainFields.add(domainFieldName);
 				if (field.description || field.deprecated || field.readOnly || field.writeOnly || field.default !== void 0) {
@@ -7565,7 +7599,10 @@ function generateModels$7(models, ctx, shared) {
 				const responseBaselineField = baselineResponse?.fields?.[domainWireField];
 				const domainResponseOptionalMismatch = baselineField && !baselineField.optional && responseBaselineField && responseBaselineField.optional;
 				const readonlyPrefix = field.readOnly ? "readonly " : "";
-				if (baselineField && !domainResponseOptionalMismatch && !hasDateTimeConversion(field.type) && baselineTypeResolvable(baselineField.type, importableNames) && baselineFieldCompatible(baselineField, field)) {
+				if (genericDefaults.has(model.name) && baselineField && typeReferencesUnresolvable(baselineField.type, unresolvableNames)) {
+					const opt = baselineField.optional ? "?" : "";
+					lines.push(`  ${readonlyPrefix}${domainFieldName}${opt}: ${substituteGenericParam(baselineField.type, unresolvableNames)};`);
+				} else if (baselineField && !domainResponseOptionalMismatch && !hasDateTimeConversion(field.type) && baselineTypeResolvable(baselineField.type, importableNames) && baselineFieldCompatible(baselineField, field)) {
 					const opt = baselineField.optional ? "?" : "";
 					lines.push(`  ${readonlyPrefix}${domainFieldName}${opt}: ${baselineField.type};`);
 				} else {
@@ -7588,7 +7625,10 @@ function generateModels$7(models, ctx, shared) {
 					if (seenWireFields.has(wireField)) continue;
 					seenWireFields.add(wireField);
 					const baselineField = baselineResponse?.fields?.[wireField];
-					if (baselineField && baselineTypeResolvable(baselineField.type, importableNames) && baselineFieldCompatible(baselineField, field)) {
+					if (genericDefaults.has(model.name) && baselineField && typeReferencesUnresolvable(baselineField.type, unresolvableNames)) {
+						const opt = baselineField.optional ? "?" : "";
+						lines.push(`  ${wireField}${opt}: ${substituteGenericParam(baselineField.type, unresolvableNames)};`);
+					} else if (baselineField && baselineTypeResolvable(baselineField.type, importableNames) && baselineFieldCompatible(baselineField, field)) {
 						const opt = baselineField.optional ? "?" : "";
 						lines.push(`  ${wireField}${opt}: ${baselineField.type};`);
 					} else {
@@ -8031,6 +8071,19 @@ function hasSpecificIRType(ref) {
 		default: return false;
 	}
 }
+/** 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, unresolvable) {
+	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, unresolvable) {
+	return type.replace(/\b[A-Z][a-zA-Z0-9]*\b/g, (name) => unresolvable.has(name) ? "GenericType" : name);
+}
 function renderTypeParams(model, genericDefaults) {
 	if (!model.typeParams?.length) {
 		if (genericDefaults?.has(model.name)) return "<GenericType extends Record<string, unknown> = Record<string, unknown>>";
@@ -8557,10 +8610,11 @@ function optionsObjectParam(method) {
 	const [param] = method.params;
 	if (param.name !== "options") return void 0;
 	if (param.passingStyle && param.passingStyle !== "options_object") return void 0;
-	if (!param.type || /^(Record|object|any|unknown)\b/.test(param.type)) return void 0;
+	const type = param.type?.replace(/(?:\s*\|\s*(?:undefined|null))+\s*$/, "").trim();
+	if (!type || /^(Record|object|any|unknown)\b/.test(type)) return void 0;
 	return {
 		name: param.name,
-		type: param.type
+		type
 	};
 }
 function configuredOptionsMethod(ctx, op) {
@@ -8625,6 +8679,7 @@ function generateTests$7(spec, ctx) {
 		};
 		const ops = isNodeOwnedService(ctx, mountName, resolveResourceClassName$3(mergedService, ctx)) ? operations : uncoveredOperations(mergedService, ctx);
 		if (ops.length === 0) continue;
+		const ignoredMethodNames = ignoredResourceMethodNames(ctx, `src/${resolveResourceDir(mergedService, ctx)}/${fileName$3(resolveResourceClassName$3(mergedService, ctx))}.ts`);
 		const propName = mountAccessors.get(mountName) ?? servicePropertyName$4(mountName);
 		if (ctx.apiSurface && baselineWorkOSProps.size > 0 && !baselineWorkOSProps.has(propName)) continue;
 		if (resolveResourceClassName$3(mergedService, ctx) !== mountName) continue;
@@ -8632,23 +8687,31 @@ function generateTests$7(spec, ctx) {
 			...mergedService,
 			operations: ops
 		} : mergedService;
-		files.push(generateServiceTest$3(testService, spec, ctx, modelMap, mountAccessors));
+		files.push(generateServiceTest$3(testService, spec, ctx, modelMap, mountAccessors, ignoredMethodNames));
 	}
 	const serializerTests = generateSerializerTests(spec, ctx);
 	for (const f of serializerTests) files.push(f);
 	return files;
 }
-function generateServiceTest$3(service, spec, ctx, modelMap, mountAccessors) {
+function generateServiceTest$3(service, spec, ctx, modelMap, mountAccessors, ignoredMethodNames = /* @__PURE__ */ new Set()) {
 	const resolvedName = resolveResourceClassName$3(service, ctx);
 	const serviceDir = resolveResourceDir(service, ctx);
 	const serviceClass = resolvedName;
 	const serviceProp = mountAccessors?.get(service.name) ?? servicePropertyName$4(resolveServiceName(service, ctx));
 	const testPath = `src/${serviceDir}/${fileName$3(resolvedName)}.spec.ts`;
-	const plans = service.operations.map((op) => ({
+	const allPlans = service.operations.map((op) => ({
 		op,
-		plan: planOperation(op),
+		plan: planOperationFor(op, ctx),
 		method: resolveMethodName$6(op, service, ctx)
 	}));
+	const resolvedLookup = buildResolvedLookup(ctx);
+	const preservedScopes = methodsWithPreservedTestBlocks(ctx, testPath);
+	const plans = allPlans.filter((p) => {
+		if (preservedScopes.has(p.method)) return true;
+		if (ignoredMethodNames.has(p.method)) return false;
+		if (lookupResolved(p.op, resolvedLookup)?.urlBuilder) return false;
+		return true;
+	});
 	if (ctx.overlayLookup?.methodByOperation) {
 		const methodOrder = /* @__PURE__ */ new Map();
 		let pos = 0;
@@ -8695,7 +8758,7 @@ function generateServiceTest$3(service, spec, ctx, modelMap, mountAccessors) {
 	lines.push("");
 	lines.push("const workos = new WorkOS('sk_test_Sz3IQjepeSWaI4cMS4ms4sMuU');");
 	lines.push("");
-	const { lines: helperLines, helpers: entityHelperNames } = generateEntityHelpers(plans, modelMap, ctx);
+	const { lines: helperLines, helpers: entityHelperNames } = generateEntityHelpers(service, allPlans, plans, existingTestIgnoreText(ctx, testPath), modelMap, ctx);
 	for (const line of helperLines) lines.push(line);
 	lines.push(`describe('${serviceClass}', () => {`);
 	lines.push("  beforeEach(() => fetch.resetMocks());");
@@ -8711,6 +8774,20 @@ function generateServiceTest$3(service, spec, ctx, modelMap, mountAccessors) {
 		lines.push("  });");
 	}
 	lines.push("});");
+	const body = lines.join("\n");
+	const enumImportLines = [];
+	for (const [name, info] of Object.entries(ctx.apiSurface?.enums ?? {})) {
+		if (!new RegExp(`\\b${name}\\.[A-Za-z_$]`).test(body)) continue;
+		if (new RegExp(`import\\b[^;]*\\b${name}\\b[^;]*from`).test(body)) continue;
+		const sourceFile = info.sourceFile;
+		const spec = sourceFile ? relativeImport(testPath, sourceFile).replace(/\.ts$/, "") : "./interfaces";
+		enumImportLines.push(`import { ${name} } from '${spec}';`);
+	}
+	if (enumImportLines.length > 0) {
+		const anchor = lines.indexOf("import { WorkOS } from '../workos';");
+		const at = anchor >= 0 ? anchor + 1 : 0;
+		lines.splice(at, 0, ...enumImportLines);
+	}
 	return {
 		path: testPath,
 		content: lines.join("\n"),
@@ -8729,11 +8806,81 @@ function pathParamTestValue(param, paramName) {
 	if (name) return `test_${fieldName$6(name)}`;
 	return "test_id";
 }
-function queryParamTestValue(param, modelMap) {
+/** Render an example value as a valid TS literal expression.
+*  Objects and nested arrays go through JSON.stringify so map-typed params
+*  (e.g. providerQueryParams) don't coerce to the literal text `[object Object]`.
+*/
+function renderExampleLiteral(value) {
+	if (typeof value === "string") return `'${value}'`;
+	if (Array.isArray(value)) return `[${value.map(renderExampleLiteral).join(", ")}]`;
+	if (value !== null && typeof value === "object") return JSON.stringify(value);
+	return String(value);
+}
+/** Resolve the enum members a query-param test value must satisfy. An enum is
+*  expressed several ways: an inline `EnumRef` with `values`, an `enum`/`model`
+*  ref by name, or — when the IR flattened the param to a bare string but the
+*  hand-written options interface still types the field as an enum — the
+*  baseline options field type (e.g. `ConnectionType`). */
+/** All valid values for an enum named `name`. The extracted SDK surface is
+*  consulted first: when an options field is typed with a hand-written enum
+*  (e.g. `ConnectionType` from `connection-type.enum.ts`), that enum — not a
+*  same-named IR enum that may carry extra members like `Pending` — is what
+*  the generated test must type-check against. Falls back to the IR spec. */
+function enumValuesByName(name, ctx) {
+	const members = ctx?.apiSurface?.enums?.[name]?.members;
+	if (members && Object.keys(members).length > 0) return Object.values(members);
+	const specValues = ctx?.spec.enums.find((e) => e.name === name)?.values;
+	if (specValues?.length) return specValues.map((v) => v.value);
+}
+function resolveParamEnumValues(param, optionFieldType, ctx) {
+	if (optionFieldType) {
+		const bare = optionFieldType.replace(/\[\]/g, "").replace(/\|\s*(undefined|null)/g, "").trim();
+		if (/^[A-Za-z_$][\w$]*$/.test(bare)) {
+			const values = enumValuesByName(bare, ctx);
+			if (values) return values;
+		}
+	}
+	if ((param.type.kind === "enum" || param.type.kind === "model") && param.type.name) {
+		const values = enumValuesByName(param.type.name, ctx);
+		if (values) return values;
+	}
+	if (param.type.kind === "enum" && param.type.values?.length) return param.type.values;
+}
+/** When an options field is typed with a real (nominal) TS `enum` from the SDK
+*  surface, a string literal won't type-check — the value must be a member
+*  reference (`ConnectionType.ADFSSAML`). Returns the enum's name + members so
+*  the caller can both render the reference and import the right declaration. */
+function resolveRealEnum(param, optionFieldType, ctx) {
+	const candidates = [];
+	if (optionFieldType) {
+		const bare = optionFieldType.replace(/\[\]/g, "").replace(/\|\s*(undefined|null)/g, "").trim();
+		if (/^[A-Za-z_$][\w$]*$/.test(bare)) candidates.push(bare);
+	}
+	if ((param.type.kind === "enum" || param.type.kind === "model") && param.type.name) candidates.push(param.type.name);
+	for (const name of candidates) {
+		const members = ctx?.apiSurface?.enums?.[name]?.members;
+		if (members && Object.keys(members).length > 0) return {
+			name,
+			members
+		};
+	}
+	return null;
+}
+function queryParamTestValue(param, modelMap, ctx, optionFieldType) {
+	const realEnum = resolveRealEnum(param, optionFieldType, ctx);
+	if (realEnum) {
+		const entries = Object.entries(realEnum.members);
+		const [memberKey] = (typeof param.example === "string" ? entries.find(([, v]) => v === param.example) : void 0) ?? entries[0];
+		return `${realEnum.name}.${memberKey}`;
+	}
+	const enumValues = resolveParamEnumValues(param, optionFieldType, ctx);
+	if (enumValues?.length) {
+		const valid = typeof param.example === "string" && enumValues.includes(param.example) ? param.example : enumValues[0];
+		return typeof valid === "string" ? `'${valid}'` : String(valid);
+	}
 	if (param.example !== void 0) {
-		if (Array.isArray(param.example)) return `[${param.example.map((v) => typeof v === "string" ? `'${v}'` : String(v)).join(", ")}]`;
 		if (param.type.kind === "primitive" && param.type.format === "date-time" && typeof param.example === "string") return `new Date('${param.example}')`;
-		return typeof param.example === "string" ? `'${param.example}'` : String(param.example);
+		return renderExampleLiteral(param.example);
 	}
 	return fixtureValueForType(param.type, param.name, "Options", modelMap) ?? "'test'";
 }
@@ -8899,9 +9046,10 @@ function buildOptionsObjectTestArg(op, plan, baselineMethod, modelMap, ctx) {
 	const optionParam = optionsObjectParam(baselineMethod);
 	if (!optionParam) return null;
 	const entries = [];
+	const pathFieldMap = ctx ? operationOverrideFor(ctx, op)?.pathFieldMap : void 0;
 	for (const param of op.pathParams) {
 		const localName = fieldName$6(param.name);
-		const optionField = resolveOptionsObjectField(localName, optionParam.type, ctx);
+		const optionField = resolveOptionsObjectField(localName, optionParam.type, ctx, pathFieldMap);
 		entries.push(`${optionField}: ${JSON.stringify(pathParamTestValue(param, localName))}`);
 	}
 	if (plan.isPaginated) entries.push("order: 'desc'");
@@ -8913,7 +9061,8 @@ function buildOptionsObjectTestArg(op, plan, baselineMethod, modelMap, ctx) {
 	].includes(param.name)) : op.queryParams).filter((param) => !param.deprecated);
 	for (const param of queryParams) {
 		const localName = fieldName$6(param.name);
-		const value = queryParamTestValue(param, modelMap);
+		const optionFieldType = ctx?.apiSurface?.interfaces?.[optionParam.type]?.fields?.[localName]?.type;
+		const value = queryParamTestValue(param, modelMap, ctx, optionFieldType);
 		entries.push(`${localName}: ${value}`);
 	}
 	if (plan.hasBody) {
@@ -8941,7 +9090,9 @@ function objectLiteralEntries(literal) {
 	const body = trimmed.slice(1, -1).trim();
 	return body ? body.split(",").map((entry) => entry.trim()) : [];
 }
-function resolveOptionsObjectField(localName, optionType, ctx) {
+function resolveOptionsObjectField(localName, optionType, ctx, pathFieldMap) {
+	const mapped = pathFieldMap?.[localName];
+	if (mapped) return mapped;
 	const fields = ctx?.apiSurface?.interfaces?.[optionType]?.fields;
 	if (!fields) return localName;
 	if (fields[localName]) return localName;
@@ -8956,20 +9107,85 @@ function resolveOptionsObjectField(localName, optionType, ctx) {
 * Generate per-entity assertion helper functions for models used in 2+ tests.
 * Returns { lines, helpers } where helpers is a Set of helper function names.
 */
-function generateEntityHelpers(plans, modelMap, ctx) {
-	const modelUsage = /* @__PURE__ */ new Map();
-	for (const { op, plan } of plans) {
-		let modelName = null;
+/** Describe-scope names (i.e. method names) that have an `@oagen-ignore` block
+*  nested inside them in the existing test file. Such a `describe` must keep
+*  being emitted even when the method is hand-owned — otherwise the engine has
+*  no `describe` to re-nest the preserved block under and orphans it to the top
+*  of the file (out of `beforeEach` scope), which hangs at runtime. Mirrors the
+*  engine's `findContainingDescribeScope`. */
+function methodsWithPreservedTestBlocks(ctx, relPath) {
+	const scopes = /* @__PURE__ */ new Set();
+	const root = ctx.outputDir ?? ctx.targetDir;
+	if (!root) return scopes;
+	let content;
+	try {
+		content = fs.readFileSync(path.join(root, relPath), "utf8");
+	} catch {
+		return scopes;
+	}
+	const lines = content.split("\n");
+	const indentOf = (l) => l.length - l.trimStart().length;
+	for (let i = 0; i < lines.length; i++) {
+		if (!lines[i].includes("@oagen-ignore-start")) continue;
+		if (/^\S/.test(lines[i])) continue;
+		const markerIndent = indentOf(lines[i]);
+		for (let j = i - 1; j >= 0; j--) {
+			if (indentOf(lines[j]) >= markerIndent) continue;
+			const m = lines[j].match(/^\s*describe\((['"`])(.+?)\1\s*,/);
+			if (m) {
+				scopes.add(m[2]);
+				break;
+			}
+			if (/^\s*(?:export\s+)?class\s+\w+/.test(lines[j])) break;
+		}
+	}
+	return scopes;
+}
+/** Concatenated text of the existing test file's `@oagen-ignore` regions, so
+*  helper generation can see which `expect<Model>()` helpers preserved
+*  hand-written test blocks still reference. */
+function existingTestIgnoreText(ctx, relPath) {
+	const root = ctx.outputDir ?? ctx.targetDir;
+	if (!root) return "";
+	let content;
+	try {
+		content = fs.readFileSync(path.join(root, relPath), "utf8");
+	} catch {
+		return "";
+	}
+	return [...content.matchAll(/@oagen-ignore-start[\s\S]*?@oagen-ignore-end/g)].map((m) => m[0]).join("\n");
+}
+function generateEntityHelpers(service, allPlans, renderedPlans, ignoreRegionText, modelMap, ctx) {
+	const responseModelOf = (entry) => {
+		const { op, plan } = entry;
 		if (plan.isPaginated && op.pagination?.itemType.kind === "model") {
-			modelName = op.pagination.itemType.name;
+			let modelName = op.pagination.itemType.name;
 			const rawModel = modelMap.get(modelName);
 			if (rawModel) {
 				const unwrapped = unwrapListModel$4(rawModel, modelMap);
 				if (unwrapped) modelName = unwrapped.name;
 			}
-		} else if (plan.responseModelName) modelName = plan.responseModelName;
+			return modelName;
+		}
+		return plan.responseModelName ?? null;
+	};
+	const modelUsage = /* @__PURE__ */ new Map();
+	for (const entry of allPlans) {
+		const modelName = responseModelOf(entry);
 		if (modelName) modelUsage.set(modelName, (modelUsage.get(modelName) ?? 0) + 1);
 	}
+	const renderedModels = /* @__PURE__ */ new Set();
+	for (const entry of renderedPlans) {
+		const modelName = responseModelOf(entry);
+		if (!modelName) continue;
+		if (entry.plan.isPaginated && entry.op.pagination?.itemType.kind === "model") {
+			const baselineMethod = optionsMethodFor(service, entry.method, entry.op, entry.plan, ctx);
+			const baselineItemType = autoPaginatableItemType(baselineMethod?.returnType);
+			const generatedItemType = resolveInterfaceName(modelName, ctx);
+			if (Boolean(baselineMethod?.returnType && !baselineItemType) || Boolean(baselineItemType && generatedItemType && baselineItemType !== generatedItemType)) continue;
+		}
+		renderedModels.add(modelName);
+	}
 	const lines = [];
 	const helpers = /* @__PURE__ */ new Set();
 	for (const [modelName, count] of modelUsage) {
@@ -8980,6 +9196,7 @@ function generateEntityHelpers(plans, modelMap, ctx) {
 		if (assertions.length === 0) continue;
 		const helperName = `expect${resolveInterfaceName(modelName, ctx)}`;
 		if (helpers.has(helperName)) continue;
+		if (!(renderedModels.has(modelName) || ignoreRegionText.includes(`${helperName}(`))) continue;
 		helpers.add(helperName);
 		lines.push(`function ${helperName}(result: any) {`);
 		for (const assertion of assertions) lines.push(`  ${assertion}`);
@@ -9009,7 +9226,7 @@ function buildFieldAssertions(model, accessor, modelMap) {
 	const assertions = [];
 	for (const field of model.fields) {
 		if (!field.required) continue;
-		const domainField = fieldName$6(field.name);
+		const domainField = fieldName$6(field.domainName ?? field.name);
 		const isDateTime = isDateTimeFieldType(field.type);
 		const fieldAccessor = isDateTime ? `${accessor}.${domainField}.toISOString()` : `${accessor}.${domainField}`;
 		if (field.example !== void 0) {
@@ -10075,6 +10292,21 @@ function withNodeOperationOverrides(ctx) {
 	return next;
 }
 //#endregion
+//#region src/shared/file-header.ts
+/**
+* Canonical "do not edit" banner text shared by every emitter's
+* `fileHeader()`. The text is comment-syntax agnostic — each emitter prefixes
+* it with the appropriate comment marker for its language (`//`, `#`, etc.).
+*
+* Keeping this in one place prevents the wording from drifting between
+* languages (Rust previously emitted a different banner).
+*
+* Go intentionally does NOT use this constant: its header must match the
+* standard `^// Code generated .* DO NOT EDIT\.$` marker that Go tooling
+* relies on to recognize generated files. See `src/go/index.ts`.
+*/
+const AUTOGEN_NOTICE = "This file is auto-generated by oagen. Do not edit.";
+//#endregion
 //#region src/node/index.ts
 /**
 * Cache live-surface per ctx — every emitter method receives the same ctx in
@@ -10620,7 +10852,7 @@ const nodeEmitter = {
 		return {};
 	},
 	fileHeader() {
-		return "// This file is auto-generated by oagen. Do not edit.";
+		return `// ${AUTOGEN_NOTICE}`;
 	},
 	formatCommand(targetDir) {
 		const hasPrettier = fs$1.existsSync(path$1.join(targetDir, ".prettierrc"));
@@ -10688,6 +10920,15 @@ function fieldName$5(name) {
 	return toSnakeCase(name);
 }
 /**
+* snake_case 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 (still derived from `field.name`) is
+* unaffected, so the API contract is preserved.
+*/
+function domainFieldName$5(field) {
+	return toSnakeCase(field.domainName ?? field.name);
+}
+/**
 * Python builtins that should not be shadowed by parameter names.
 * When a path/query param name collides, suffix with underscore.
 */
@@ -11585,7 +11826,7 @@ function generateModels$6(models, ctx) {
 		}
 		const seenFieldNames = /* @__PURE__ */ new Set();
 		const deduplicatedFields = model.fields.filter((f) => {
-			const pyName = fieldName$5(f.name);
+			const pyName = domainFieldName$5(f);
 			if (seenFieldNames.has(pyName)) return false;
 			seenFieldNames.add(pyName);
 			return true;
@@ -11647,7 +11888,7 @@ function generateModels$6(models, ctx) {
 			return typeStr;
 		};
 		for (const field of requiredFields) {
-			const pyFieldName = fieldName$5(field.name);
+			const pyFieldName = domainFieldName$5(field);
 			const pyType = rewriteDiscriminatorType(resolveModelFieldType(field.type));
 			if (field.description || field.deprecated) {
 				const parts = [];
@@ -11658,7 +11899,7 @@ function generateModels$6(models, ctx) {
 			} else lines.push(`    ${pyFieldName}: ${pyType}`);
 		}
 		for (const field of optionalFields) {
-			const pyFieldName = fieldName$5(field.name);
+			const pyFieldName = domainFieldName$5(field);
 			const pyType = `Optional[${rewriteDiscriminatorType(field.type.kind === "nullable" ? resolveModelFieldType(field.type.inner) : resolveModelFieldType(field.type))}]`;
 			if (field.description || field.deprecated) {
 				const parts = [];
@@ -11676,7 +11917,7 @@ function generateModels$6(models, ctx) {
 		const preludeLines = [];
 		const fieldAssignmentLines = [];
 		for (const field of [...requiredFields, ...optionalFields]) {
-			const pyFieldName = fieldName$5(field.name);
+			const pyFieldName = domainFieldName$5(field);
 			const wireKey = field.name;
 			const isRequired = !isOptionalField(model.name, field, ctx);
 			const discPrelude = renderDiscriminatedUnionPrelude(field, pyFieldName, wireKey, modelClassName, isRequired);
@@ -11704,7 +11945,7 @@ function generateModels$6(models, ctx) {
 		lines.push("        \"\"\"Serialize to a dictionary.\"\"\"");
 		lines.push("        result: Dict[str, Any] = {}");
 		for (const field of [...requiredFields, ...optionalFields]) {
-			const pyFieldName = fieldName$5(field.name);
+			const pyFieldName = domainFieldName$5(field);
 			const wireKey = field.name;
 			const isRequired = !isOptionalField(model.name, field, ctx);
 			const isNullable = field.type.kind === "nullable";
@@ -13580,7 +13821,7 @@ function generateModelFixture$4(model, modelMap, enumMap) {
 	const fixture = {};
 	const seenFieldNames = /* @__PURE__ */ new Set();
 	const deduplicatedFields = model.fields.filter((f) => {
-		const pyName = fieldName$5(f.name);
+		const pyName = domainFieldName$5(f);
 		if (seenFieldNames.has(pyName)) return false;
 		seenFieldNames.add(pyName);
 		return true;
@@ -14376,16 +14617,16 @@ function pickAssertableFields(modelName, spec, maxFields = 2) {
 		if (typeof val === "string") {
 			if (val.includes("\"") || val.includes("'") || val.includes("{") || val.includes("\\") || val.includes("\n")) continue;
 			results.push({
-				field: fieldName$5(f.name),
+				field: domainFieldName$5(f),
 				value: `"${val}"`
 			});
 		} else if (typeof val === "boolean") results.push({
-			field: fieldName$5(f.name),
+			field: domainFieldName$5(f),
 			value: val ? "True" : "False",
 			isBool: true
 		});
 		else if (typeof val === "number") results.push({
-			field: fieldName$5(f.name),
+			field: domainFieldName$5(f),
 			value: String(val)
 		});
 	}
@@ -14445,7 +14686,7 @@ function buildTestArgs$1(op, spec, hiddenParams) {
 		].includes(param.name)) continue;
 		if (plan.hasBody && op.requestBody?.kind === "model") {
 			const rbName = op.requestBody.name;
-			if (spec.models.find((m) => m.name === rbName)?.fields.some((f) => fieldName$5(f.name) === fieldName$5(param.name))) continue;
+			if (spec.models.find((m) => m.name === rbName)?.fields.some((f) => domainFieldName$5(f) === fieldName$5(param.name))) continue;
 		}
 		if (param.required && !pathParamNames.has(fieldName$5(param.name))) args.push(`${fieldName$5(param.name)}=${generateTestValue$1(param.type, param.name)}`);
 	}
@@ -14704,7 +14945,7 @@ function generateModelRoundTripTests(spec, ctx) {
 		if (model.discriminator) continue;
 		const seenFieldNames = /* @__PURE__ */ new Set();
 		const dedupFields = model.fields.filter((f) => {
-			const pyName = fieldName$5(f.name);
+			const pyName = domainFieldName$5(f);
 			if (seenFieldNames.has(pyName)) return false;
 			seenFieldNames.add(pyName);
 			return true;
@@ -14896,7 +15137,7 @@ const pythonEmitter = {
 		return buildOperationsMap$6(spec, ctx);
 	},
 	fileHeader() {
-		return "# This file is auto-generated by oagen. Do not edit.";
+		return `# ${AUTOGEN_NOTICE}`;
 	},
 	formatCommand(_targetDir) {
 		return {
@@ -14997,6 +15238,15 @@ function resolveMethodName$4(op, _service, ctx) {
 function fieldName$4(name) {
 	return toCamelCase(name);
 }
+/**
+* camelCase DOMAIN property name for a model field, honoring a `domainName`
+* override (set via the `fieldHints` config) so a wire field can surface under
+* a friendlier PHP property name. The wire key (see {@link wireName}) still
+* derives from `field.name`. No-op when `domainName` is unset.
+*/
+function domainFieldName$4(field) {
+	return fieldName$4(field.domainName ?? field.name);
+}
 /** snake_case name for fixtures and other snake_case contexts. */
 function snakeName(name) {
 	return toSnakeCase(stripUrnPrefix(name));
@@ -15131,14 +15381,14 @@ function generateModels$5(models, ctx) {
 		const optionalFields = model.fields.filter((f) => !f.required);
 		const seenNames = /* @__PURE__ */ new Set();
 		const allFields = [...requiredFields, ...optionalFields].filter((f) => {
-			const phpName = fieldName$4(f.name);
+			const phpName = domainFieldName$4(f);
 			if (seenNames.has(phpName)) return false;
 			seenNames.add(phpName);
 			return true;
 		});
 		for (let i = 0; i < allFields.length; i++) {
 			const field = allFields[i];
-			const phpName = fieldName$4(field.name);
+			const phpName = domainFieldName$4(field);
 			const phpType = mapTypeRef$5(field.type);
 			const isOptional = !field.required;
 			const comma = i < allFields.length - 1 ? "," : ",";
@@ -15165,7 +15415,7 @@ function generateModels$5(models, ctx) {
 		lines.push(`        return new self(`);
 		for (let i = 0; i < allFields.length; i++) {
 			const field = allFields[i];
-			const phpName = fieldName$4(field.name);
+			const phpName = domainFieldName$4(field);
 			const wireName = field.name;
 			const comma = i < allFields.length - 1 ? "," : ",";
 			const accessor = generateFromArrayAccessor(field.type, wireName, field.required);
@@ -15178,7 +15428,7 @@ function generateModels$5(models, ctx) {
 		lines.push("    {");
 		lines.push("        return [");
 		for (const field of allFields) {
-			const phpName = fieldName$4(field.name);
+			const phpName = domainFieldName$4(field);
 			const wireName = field.name;
 			const serialized = generateToArrayValue(field.type, `$this->${phpName}`, !field.required);
 			lines.push(`            '${wireName}' => ${serialized},`);
@@ -16602,7 +16852,7 @@ function emitFieldHydrationAssertions(lines, modelName, resultVar, fixtureVar, c
 	const assertFields = [candidates.find((f) => f.name === "id"), candidates.filter((f) => f.name !== "id")[0]].filter(Boolean);
 	for (const f of assertFields) {
 		if (!f) continue;
-		const phpProp = toCamelCase(f.name);
+		const phpProp = domainFieldName$4(f);
 		lines.push(`        $this->assertSame(${fixtureVar}['${f.name}'], ${resultVar}->${phpProp});`);
 	}
 }
@@ -16782,7 +17032,7 @@ const phpEmitter = {
 		return buildOperationsMap$5(spec, ctx);
 	},
 	fileHeader() {
-		return "<?php\n\ndeclare(strict_types=1);\n\n// This file is auto-generated by oagen. Do not edit.";
+		return `<?php\n\ndeclare(strict_types=1);\n\n// ${AUTOGEN_NOTICE}`;
 	},
 	formatCommand(targetDir) {
 		if (fs$1.existsSync(path$1.join(targetDir, ".php-cs-fixer.dist.php")) || fs$1.existsSync(path$1.join(targetDir, ".php-cs-fixer.php"))) return {
@@ -16845,6 +17095,15 @@ function methodName$3(name) {
 function fieldName$3(name) {
 	return applyAcronyms(toPascalCase(name));
 }
+/**
+* PascalCase 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 (the `json:"..."` struct tag) still derives
+* from `field.name`.
+*/
+function domainFieldName$3(field) {
+	return applyAcronyms(toPascalCase(field.domainName ?? field.name));
+}
 /** Lower-camel identifier with Go acronym conventions preserved. */
 function unexportedName(name) {
 	const exported = className$3(name);
@@ -17093,7 +17352,7 @@ function generateModels$4(models, ctx) {
 		lines.push(`type ${structName} struct {`);
 		const seenFieldNames = /* @__PURE__ */ new Set();
 		for (const field of model.fields) {
-			const goFieldName = fieldName$3(field.name);
+			const goFieldName = domainFieldName$3(field);
 			if (seenFieldNames.has(goFieldName)) continue;
 			seenFieldNames.add(goFieldName);
 			const goType = !field.required ? makeOptional$2(mapTypeRef$4(field.type)) : mapTypeRef$4(field.type);
@@ -17907,7 +18166,7 @@ function generateParamsStruct(mountName, method, op, plan, ctx, resolvedOp) {
 		if (bodyModel) for (const field of bodyModel.fields) {
 			if (hidden.has(field.name)) continue;
 			if (groupedParams.has(field.name)) continue;
-			const goField = fieldName$3(field.name);
+			const goField = domainFieldName$3(field);
 			if (emittedFields.has(goField)) continue;
 			emittedFields.add(goField);
 			const goType = !field.required ? makeOptional$1(mapTypeRef$4(field.type)) : mapTypeRef$4(field.type);
@@ -18245,7 +18504,7 @@ function emitHiddenParamsBodyStruct(lines, method, op, ctx, resolvedOp) {
 		if (hidden.has(field.name)) continue;
 		if (groupedParamNames.has(field.name)) continue;
 		if (!field.required) continue;
-		const goField = fieldName$3(field.name);
+		const goField = domainFieldName$3(field);
 		const goType = mapTypeRef$4(field.type);
 		lines.push(`\t${goField} ${goType} \`json:"${field.name}"\``);
 	}
@@ -18257,7 +18516,7 @@ function emitHiddenParamsBodyStruct(lines, method, op, ctx, resolvedOp) {
 		if (hidden.has(field.name)) continue;
 		if (groupedParamNames.has(field.name)) continue;
 		if (field.required) continue;
-		const goField = fieldName$3(field.name);
+		const goField = domainFieldName$3(field);
 		const goType = makeOptional$1(mapTypeRef$4(field.type));
 		lines.push(`\t${goField} ${goType} \`json:"${field.name},omitempty"\``);
 	}
@@ -18278,7 +18537,7 @@ function emitBodyWithHiddenParams(lines, op, pathExpr, plan, ctx, resolvedOp, pa
 	if (paramsType && bodyModel) for (const field of bodyModel.fields) {
 		if (hidden.has(field.name)) continue;
 		if (!field.required) continue;
-		const goField = fieldName$3(field.name);
+		const goField = domainFieldName$3(field);
 		lines.push(`\t\t${goField}: params.${goField},`);
 	}
 	lines.push("	}");
@@ -18289,7 +18548,7 @@ function emitBodyWithHiddenParams(lines, op, pathExpr, plan, ctx, resolvedOp, pa
 	if (paramsType && bodyModel) for (const field of bodyModel.fields) {
 		if (hidden.has(field.name)) continue;
 		if (field.required) continue;
-		const goField = fieldName$3(field.name);
+		const goField = domainFieldName$3(field);
 		lines.push(`\tbody.${goField} = params.${goField}`);
 	}
 	const queryArg = op.queryParams.filter((qp) => !hidden.has(qp.name)).length > 0 ? "params" : "nil";
@@ -18716,7 +18975,7 @@ function generateModelFixture$2(model, modelMap, enumMap) {
 	const fixture = {};
 	const seenFieldNames = /* @__PURE__ */ new Set();
 	const deduplicatedFields = model.fields.filter((f) => {
-		const goName = fieldName$3(f.name);
+		const goName = domainFieldName$3(f);
 		if (seenFieldNames.has(goName)) return false;
 		seenFieldNames.add(goName);
 		return true;
@@ -19456,6 +19715,15 @@ function methodName$2(name) {
 function fieldName$2(name) {
 	return toPascalCase(name);
 }
+/**
+* PascalCase domain property name for a model field, honoring a `domainName`
+* override (set via the `fieldHints` config) so a wire field can surface under
+* a friendlier C# property name. The wire/serialization key (the
+* `[JsonPropertyName("...")]` value) still derives from `field.name`.
+*/
+function domainFieldName$2(field) {
+	return toPascalCase(field.domainName ?? field.name);
+}
 function trimAsyncSuffix(name) {
 	return name.endsWith("Async") ? name.slice(0, -5) : name;
 }
@@ -19822,7 +20090,7 @@ function generateModels$3(models, ctx, discCtx) {
 			const baseClassName = modelClassName(model.name);
 			const fieldMap = /* @__PURE__ */ new Map();
 			for (const field of model.fields) {
-				let csName = fieldName$2(field.name);
+				let csName = domainFieldName$2(field);
 				if (csName === baseClassName) csName = `${csName}Value`;
 				fieldMap.set(csName, mapTypeRef$3(field.type));
 			}
@@ -19838,7 +20106,9 @@ function generateModels$3(models, ctx, discCtx) {
 		const fieldTypes = model.fields.map((f) => mapTypeRef$3(f.type));
 		const needsCollections = fieldTypes.some((t) => t.startsWith("List<") || t.startsWith("Dictionary<"));
 		const needsSystem = fieldTypes.some((t) => t.includes("DateTimeOffset"));
-		const needsJsonAttrs = model.fields.some((f) => fieldName$2(f.name) === csClassName) || model.fields.some((f) => f.required && isEnumRef(f.type));
+		const hasClassNameCollision = model.fields.some((f) => domainFieldName$2(f) === csClassName);
+		const hasDomainRename = model.fields.some((f) => domainFieldName$2(f) !== fieldName$2(f.name));
+		const needsJsonAttrs = hasClassNameCollision || hasDomainRename || model.fields.some((f) => f.required && isEnumRef(f.type));
 		lines.push(`namespace ${ctx.namespacePascal}`);
 		lines.push("{");
 		if (needsSystem) lines.push("    using System;");
@@ -19864,9 +20134,10 @@ function generateModels$3(models, ctx, discCtx) {
 		const dictObjectFields = [];
 		const seenFieldNames = /* @__PURE__ */ new Set();
 		for (const field of model.fields) {
-			let csFieldName = fieldName$2(field.name);
+			let csFieldName = domainFieldName$2(field);
 			const collidesWithClassName = csFieldName === csClassName;
 			if (collidesWithClassName) csFieldName = `${csFieldName}Value`;
+			const hasDomainOverride = domainFieldName$2(field) !== fieldName$2(field.name);
 			if (seenFieldNames.has(csFieldName)) continue;
 			seenFieldNames.add(csFieldName);
 			let useNewModifier = false;
@@ -19913,7 +20184,7 @@ function generateModels$3(models, ctx, discCtx) {
 			const isRequiredEnum = field.required && isEnumRef(field.type) && constInit === null;
 			lines.push(...emitJsonPropertyAttributes(field.name, {
 				isRequiredEnum,
-				explicitWireName: collidesWithClassName
+				explicitWireName: collidesWithClassName || hasDomainOverride
 			}));
 			const discriminatedUnionConverter = discriminatedUnionConverterName(field.type);
 			if (discriminatedUnionConverter) lines.push(`        [Newtonsoft.Json.JsonConverter(typeof(${discriminatedUnionConverter}))]`);
@@ -21219,7 +21490,7 @@ function generateModelFixture$1(model, modelMap, enumMap) {
 	const fixture = {};
 	const seenFieldNames = /* @__PURE__ */ new Set();
 	const deduplicatedFields = model.fields.filter((f) => {
-		const csName = fieldName$2(f.name);
+		const csName = domainFieldName$2(f);
 		if (seenFieldNames.has(csName)) return false;
 		seenFieldNames.add(csName);
 		return true;
@@ -21740,7 +22011,7 @@ function buildFixtureAssertions(model, spec) {
 		if (field.type.kind !== "primitive" || field.type.type !== "string") continue;
 		if (field.type.format === "date-time" || field.type.format === "date") continue;
 		if (field.type.format === "binary") continue;
-		const csField = fieldName$2(field.name);
+		const csField = domainFieldName$2(field);
 		const val = fixture[field.name];
 		if (typeof val === "string" && val.length > 0) assertions.push(`Assert.Equal(${csStringLiteral(val)}, result.${csField});`);
 		else assertions.push(`Assert.NotEmpty(result.${csField});`);
@@ -21999,7 +22270,7 @@ const dotnetEmitter = {
 		return buildOperationsMap$3(spec, fixNamespace(ctx));
 	},
 	fileHeader() {
-		return "// This file is auto-generated by oagen. Do not edit.";
+		return `// ${AUTOGEN_NOTICE}`;
 	},
 	formatCommand(targetDir) {
 		const workspace = findDotnetWorkspace(targetDir);
@@ -22062,6 +22333,16 @@ function propertyName(name) {
 	if (camel === "object") return "objectType";
 	return escapeReserved(camel);
 }
+/**
+* camelCase domain property 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 key (the `@JsonProperty("...")` argument) still
+* derives from `field.name`. No-op when `domainName` is unset, so it is also
+* safe on params. Only apply to model fields.
+*/
+function domainPropertyName(field) {
+	return propertyName(field.domainName ?? field.name);
+}
 /** Lower-case Kotlin package segment for a service / mount group. */
 function packageSegment(name) {
 	return toPascalCase(name).toLowerCase();
@@ -22764,7 +23045,7 @@ function renderFields(fields, overrideFields = /* @__PURE__ */ new Set()) {
 	const lines = [];
 	for (const rawField of fields) {
 		const field = promoteFieldType$1(rawField);
-		const kotlinName = propertyName(field.name);
+		const kotlinName = domainPropertyName(field);
 		if (seen.has(kotlinName)) continue;
 		seen.add(kotlinName);
 		const baseType = mapTypeRef$2(field.type);
@@ -24618,7 +24899,7 @@ function buildResponseAssertions(responseModelName, ctx) {
 	for (const field of model.fields) {
 		if (!field.required) continue;
 		if (assertions.length >= MAX_RESPONSE_ASSERTIONS) break;
-		const ktProp = propertyName(field.name);
+		const ktProp = domainPropertyName(field);
 		const type = field.type;
 		if (type.kind === "primitive") {
 			if (type.format === "date-time") continue;
@@ -25062,7 +25343,7 @@ const kotlinEmitter = {
 		return buildOperationsMap$2(spec, ctx);
 	},
 	fileHeader() {
-		return "// This file is auto-generated by oagen. Do not edit.";
+		return `// ${AUTOGEN_NOTICE}`;
 	},
 	formatCommand(targetDir) {
 		if (!fs.existsSync(path.join(targetDir, "gradlew"))) return null;
@@ -25114,6 +25395,15 @@ function fieldName$1(name) {
 	return toSnakeCase(name);
 }
 /**
+* snake_case 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 key (still derived from `field.name`) is what
+* gets sent/received over the wire — only the domain attr/accessor name changes.
+*/
+function domainFieldName$1(field) {
+	return toSnakeCase(field.domainName ?? field.name);
+}
+/**
 * Ruby reserved words that cannot be used as parameter names.
 * When a path/query param name collides, suffix with underscore.
 */
@@ -25344,7 +25634,7 @@ function generateModels$1(models, ctx) {
 		}
 		const seenFieldNames = /* @__PURE__ */ new Set();
 		const fields = model.fields.filter((f) => {
-			const n = fieldName$1(f.name);
+			const n = domainFieldName$1(f);
 			if (seenFieldNames.has(n)) return false;
 			seenFieldNames.add(n);
 			return true;
@@ -25358,7 +25648,7 @@ function generateModels$1(models, ctx) {
 		lines.push("    HASH_ATTRS = {");
 		for (let i = 0; i < fields.length; i++) {
 			const field = fields[i];
-			const fname = fieldName$1(field.name);
+			const fname = domainFieldName$1(field);
 			const sep = i === fields.length - 1 ? "" : ",";
 			lines.push(`      ${rubyHashLiteralKey(field.name)} :${fname}${sep}`);
 		}
@@ -25367,13 +25657,13 @@ function generateModels$1(models, ctx) {
 		if (deprecatedFields.length > 0) {
 			for (const f of deprecatedFields) {
 				const desc = f.description ? ` ${f.description.split("\n")[0].trim()}` : "";
-				lines.push(`    # @!attribute ${fieldName$1(f.name)}`);
+				lines.push(`    # @!attribute ${domainFieldName$1(f)}`);
 				lines.push(`    #   @deprecated${desc}`);
 			}
 			lines.push("");
 		}
 		if (accessorFields.length > 0) {
-			const attrs = accessorFields.map((f) => `:${fieldName$1(f.name)}`);
+			const attrs = accessorFields.map((f) => `:${domainFieldName$1(f)}`);
 			if (attrs.length === 1) lines.push(`    attr_accessor ${attrs[0]}`);
 			else {
 				lines.push(`    attr_accessor \\`);
@@ -25385,7 +25675,7 @@ function generateModels$1(models, ctx) {
 			lines.push("");
 		}
 		for (const f of deprecatedFields) {
-			const fname = fieldName$1(f.name);
+			const fname = domainFieldName$1(f);
 			lines.push(`    def ${fname}`);
 			lines.push(`      warn "[DEPRECATION] \\\`${fname}\\\` is deprecated and will be removed in a future version.", uplevel: 1`);
 			lines.push(`      @${fname}`);
@@ -25399,7 +25689,7 @@ function generateModels$1(models, ctx) {
 		lines.push("    def initialize(json)");
 		lines.push("      hash = self.class.normalize(json)");
 		for (const field of fields) {
-			const fname = fieldName$1(field.name);
+			const fname = domainFieldName$1(field);
 			const rawKey = field.name;
 			lines.push(`      ${deserializeAssignment(fname, rawKey, field.type, field.required, enumNames, modelNames)}`);
 		}
@@ -26895,7 +27185,7 @@ function generateModelRoundTripTest(spec) {
 		const dedupFields = /* @__PURE__ */ new Set();
 		for (const f of model.fields) {
 			const wireName = f.name;
-			const rubyFieldName = fieldName$1(f.name);
+			const rubyFieldName = domainFieldName$1(f);
 			if (dedupFields.has(rubyFieldName)) continue;
 			dedupFields.add(rubyFieldName);
 			const stub = roundTripStub(f.type, enumNames);
@@ -27224,7 +27514,7 @@ function generateRbiFiles(spec, ctx) {
 		lines.push("");
 		const seenFieldNames = /* @__PURE__ */ new Set();
 		for (const f of model.fields) {
-			const fname = fieldName$1(f.name);
+			const fname = domainFieldName$1(f);
 			if (seenFieldNames.has(fname)) continue;
 			seenFieldNames.add(fname);
 			const sorbetType = f.required ? mapSorbetType(f.type) : wrapNilable(mapSorbetType(f.type));
@@ -27501,7 +27791,7 @@ const rubyEmitter = {
 		return buildOperationsMap$1(spec, ctx);
 	},
 	fileHeader() {
-		return `# frozen_string_literal: true\n\n# This file is auto-generated by oagen. Do not edit.`;
+		return `# frozen_string_literal: true\n\n# ${AUTOGEN_NOTICE}`;
 	},
 	formatCommand(targetDir) {
 		return {
@@ -27587,6 +27877,15 @@ function methodName(name) {
 function fieldName(name) {
 	return escapeKeyword(toSnakeCase(name));
 }
+/**
+* snake_case 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 identifier. The wire name (and thus the `#[serde(rename = ...)]`
+* key) still derives from `field.name`.
+*/
+function domainFieldName(field) {
+	return escapeKeyword(toSnakeCase(field.domainName ?? field.name));
+}
 /** PascalCase enum variant. */
 function variantName(value) {
 	const pascal = toPascalCase(String(value));
@@ -27858,6 +28157,7 @@ function generateModels(models, ctx, registry) {
 	const files = [];
 	const moduleNames = [];
 	const seen = /* @__PURE__ */ new Set();
+	const taggedVariantFields = collectTaggedVariantFields(models);
 	for (const model of models) {
 		const mod = moduleName(model.name);
 		if (seen.has(mod)) continue;
@@ -27866,7 +28166,7 @@ function generateModels(models, ctx, registry) {
 		const path = ctx.overlayLookup?.fileBySymbol?.get(model.name) ?? `src/models/${mod}.rs`;
 		files.push({
 			path,
-			content: renderModel(model, registry),
+			content: renderModel(model, registry, taggedVariantFields.get(model.name)),
 			overwriteExisting: true
 		});
 	}
@@ -27878,7 +28178,43 @@ function generateModels(models, ctx, registry) {
 	});
 	return files;
 }
-function renderModel(model, registry) {
+/**
+* Walk every model field and record which models are arms of an
+* internally-tagged union, mapped to that union's discriminator property.
+*/
+function collectTaggedVariantFields(models) {
+	const out = /* @__PURE__ */ new Map();
+	const visit = (ref) => {
+		switch (ref.kind) {
+			case "union":
+				if (ref.discriminator?.property) for (const variant of ref.variants) {
+					const name = variantModelName(variant);
+					if (name) out.set(name, ref.discriminator.property);
+				}
+				ref.variants.forEach(visit);
+				break;
+			case "array":
+				visit(ref.items);
+				break;
+			case "nullable":
+				visit(ref.inner);
+				break;
+			case "map":
+				visit(ref.valueType);
+				break;
+			default: break;
+		}
+	};
+	for (const model of models) for (const field of model.fields) visit(field.type);
+	return out;
+}
+/** Resolve the underlying model name of a union arm, unwrapping a nullable. */
+function variantModelName(ref) {
+	if (ref.kind === "model") return ref.name;
+	if (ref.kind === "nullable") return variantModelName(ref.inner);
+	return null;
+}
+function renderModel(model, registry, tagField) {
 	const lines = [];
 	lines.push(HEADER_PLACEHOLDER);
 	lines.push("#[allow(unused_imports)]");
@@ -27890,7 +28226,7 @@ function renderModel(model, registry) {
 	if (model.description) lines.push(...docComment$1(model.description));
 	lines.push("#[derive(Debug, Clone, Serialize, Deserialize)]");
 	const resolvedNames = resolveFieldNames(model.fields);
-	const fieldLines = model.fields.map((f, i) => renderField(f, resolvedNames[i], model.name, registry));
+	const fieldLines = model.fields.map((f, i) => renderField(f, resolvedNames[i], model.name, registry, tagField));
 	if (fieldLines.length === 0) lines.push(`pub struct ${typeName(model.name)} {}`);
 	else {
 		lines.push(`pub struct ${typeName(model.name)} {`);
@@ -27900,17 +28236,20 @@ function renderModel(model, registry) {
 	return lines.filter((l) => l !== HEADER_PLACEHOLDER).join("\n") + "\n";
 }
 /**
-* Resolve unique Rust identifiers for struct fields. Multiple wire names can
-* collide after `fieldName()` snake-cases them (e.g. `integration_type` and
-* `integrationType` both become `integration_type`). Subsequent collisions get
-* a numeric suffix so the struct compiles; serde `rename` preserves the
-* original wire name in every case.
+* Resolve unique Rust identifiers for struct fields. The domain identifier
+* honors a `fieldHints` override (`domainName`, e.g. wire `connection_type` →
+* domain `type`); the wire name (and the `#[serde(rename = ...)]` key emitted
+* in `renderField`) still derives from `f.name`. Multiple names can collide
+* after snake-casing (e.g. `integration_type` and `integrationType` both
+* become `integration_type`). Subsequent collisions get a numeric suffix so
+* the struct compiles; serde `rename` preserves the original wire name in every
+* case.
 */
 function resolveFieldNames(fields) {
 	const used = /* @__PURE__ */ new Set();
 	const out = [];
 	for (const f of fields) {
-		const base = fieldName(f.name);
+		const base = domainFieldName(f);
 		let candidate = base;
 		let suffix = 2;
 		while (used.has(candidate)) {
@@ -27922,7 +28261,7 @@ function resolveFieldNames(fields) {
 	}
 	return out;
 }
-function renderField(field, rustField, modelName, registry) {
+function renderField(field, rustField, modelName, registry, tagField) {
 	const lines = [];
 	const hasDescription = !!field.description;
 	if (hasDescription) for (const c of docComment$1(field.description)) lines.push(`    ${c}`);
@@ -27937,8 +28276,13 @@ function renderField(field, rustField, modelName, registry) {
 	});
 	if ((!field.required || field.type.kind === "nullable") && !baseType.startsWith("Option<")) baseType = makeOptional(baseType);
 	baseType = applySecretRedaction(baseType, field.name);
-	if (rename) lines.push(`    #[serde(rename = "${rename}")]`);
-	if (baseType.startsWith("Option<")) lines.push("    #[serde(skip_serializing_if = \"Option::is_none\", default)]");
+	if (tagField === field.name) {
+		const args = rename ? `rename = "${rename}", default, skip_serializing` : "default, skip_serializing";
+		lines.push(`    #[serde(${args})]`);
+	} else {
+		if (rename) lines.push(`    #[serde(rename = "${rename}")]`);
+		if (baseType.startsWith("Option<")) lines.push("    #[serde(skip_serializing_if = \"Option::is_none\", default)]");
+	}
 	if (field.deprecated) lines.push("    #[deprecated]");
 	lines.push(`    pub ${rustField}: ${baseType},`);
 	return lines.join("\n");
@@ -28520,7 +28864,7 @@ function registerSyntheticBody(op, paramsName, bodyGroupParamNames, bodyGroupFie
 		if (!f.required && !rust.startsWith("Option<")) rust = makeOptional(rust);
 		rust = applySecretRedaction(rust, f.name);
 		return {
-			rustName: fieldName(f.name),
+			rustName: domainFieldName(f),
 			wireName: f.name,
 			rustType: rust,
 			required: !!f.required && !rust.startsWith("Option<"),
@@ -29875,7 +30219,7 @@ const rustEmitter = {
 		return buildOperationsMap(spec, ctx);
 	},
 	fileHeader() {
-		return "// Code generated by oagen. DO NOT EDIT.";
+		return `// ${AUTOGEN_NOTICE}`;
 	},
 	formatCommand(_targetDir) {
 		return {
@@ -29930,4 +30274,4 @@ const workosEmittersPlugin = {
 //#endregion
 export { fieldName$2 as A, servicePropertyName$2 as B, apiClassName as C, dotnetEmitter as D, propertyName as E, fieldName$3 as F, fieldName$5 as H, methodName$3 as I, trimMountedResourceFromMethod$2 as L, trimMountedResourceFromMethod$1 as M, goEmitter as N, appendAsyncSuffix as O, className$3 as P, phpEmitter as R, kotlinEmitter as S, packageSegment as T, safeParamName$1 as U, pythonEmitter as V, nodeEmitter as W, rubyEmitter as _, rustExtractor as a, resolveServiceTarget as b, pythonExtractor as c, rustEmitter as d, fieldName as f, typeName as g, resourceAccessorName as h, kotlinExtractor as i, methodName$2 as j, className$2 as k, rubyExtractor as l, moduleName as m, elixirExtractor as n, goExtractor as o, methodName as p, dotnetExtractor as r, phpExtractor as s, workosEmittersPlugin as t, nodeExtractor as u, buildExportedClassNameSet as v, methodName$1 as w, safeParamName as x, fieldName$1 as y, fieldName$4 as z };
 
-//# sourceMappingURL=plugin-1ckLMpgo.mjs.map
+//# sourceMappingURL=plugin-Cciic50q.mjs.map