@workos/oagen-emitters 0.16.1 → 0.18.0

package/src/node/resources.ts

@@ -327,6 +327,18 @@ function isValidTypeIdentifier(name: string): boolean {
   return /^[A-Za-z_$][\w$]*$/.test(name);
 }
 
+/**
+ * Extract candidate named type references from a compound type expression such
+ * as `GetAccessTokenOptions & { provider: string }`. PascalCase tokens are type
+ * names worth importing; lowercase tokens are property keys or primitives and
+ * are skipped. The caller only imports the ones that resolve to a known source
+ * file, so unrecognized PascalCase tokens (e.g. `Date`, `Record`) are harmless.
+ */
+function extractNamedTypeRefs(typeExpr: string): string[] {
+  const matches = typeExpr.match(/\b[A-Z][A-Za-z0-9_$]*\b/g) ?? [];
+  return [...new Set(matches)];
+}
+
 function autoPaginatableItemType(returnType: string | undefined): string | undefined {
   // Match both AutoPaginatable<T> and the legacy List<T> pattern so baseline
   // item types are extracted even when the hand-written code predates AutoPaginatable.
@@ -933,6 +945,20 @@ function generateResourceClass(service: Service, ctx: EmitterContext): Generated
     lines.push("import { AutoPaginatable } from '../common/utils/pagination';");
     lines.push("import { fetchAndDeserialize } from '../common/utils/fetch-and-deserialize';");
   }
+  // URL-builder methods serialize their query string client-side via toQueryString.
+  const needsQueryStringImport = plans.some((p) => {
+    const r = lookupResolved(p.op, resolvedLookup);
+    if (!r?.urlBuilder) return false;
+    const hidden = hiddenParamsFor(r);
+    return (
+      p.op.queryParams.some((qp) => !hidden.has(qp.name)) ||
+      Object.keys(getOpDefaults(r)).length > 0 ||
+      getOpInferFromClient(r).length > 0
+    );
+  });
+  if (needsQueryStringImport) {
+    lines.push("import { toQueryString } from '../common/utils/query-string';");
+  }
   const shouldEmitVaultCryptoHelpers =
     serviceClass === 'Vault' && !ignoredMethodNames.has('encrypt') && !ignoredMethodNames.has('decrypt');
   if (shouldEmitVaultCryptoHelpers) {
@@ -950,16 +976,28 @@ function generateResourceClass(service: Service, ctx: EmitterContext): Generated
 
   const importedTypeNames = new Set<string>();
   for (const optionType of optionObjectTypes) {
-    // Inline object-literal types from the baseline surface are rendered
-    // inline in the method signature — they have no importable name or file.
-    if (!isValidTypeIdentifier(optionType)) continue;
-    if (importedTypeNames.has(optionType)) continue;
-    importedTypeNames.add(optionType);
-    const sourceFile = baselineTypeSourceFile(ctx, optionType);
-    const relPath = sourceFile
-      ? relativeImport(resourcePath, sourceFile)
-      : `./interfaces/${fileName(optionType)}.interface`;
-    lines.push(`import type { ${optionType} } from '${relPath}';`);
+    if (isValidTypeIdentifier(optionType)) {
+      if (importedTypeNames.has(optionType)) continue;
+      importedTypeNames.add(optionType);
+      const sourceFile = baselineTypeSourceFile(ctx, optionType);
+      const relPath = sourceFile
+        ? relativeImport(resourcePath, sourceFile)
+        : `./interfaces/${fileName(optionType)}.interface`;
+      lines.push(`import type { ${optionType} } from '${relPath}';`);
+      continue;
+    }
+    // Compound option types (e.g. a baseline `GetAccessTokenOptions & { provider:
+    // string }`) keep their inline object literal inline, but the named type(s)
+    // they reference must still be imported. Only import names that resolve to a
+    // known source file — inline literals, primitives, and property keys have no
+    // importable source and are skipped.
+    for (const typeName of extractNamedTypeRefs(optionType)) {
+      if (importedTypeNames.has(typeName)) continue;
+      const sourceFile = baselineTypeSourceFile(ctx, typeName) ?? liveSurfaceInterfacePath(typeName);
+      if (!sourceFile) continue;
+      importedTypeNames.add(typeName);
+      lines.push(`import type { ${typeName} } from '${relativeImport(resourcePath, sourceFile)}';`);
+    }
   }
   for (const typeName of returnTypeImports) {
     if (importedTypeNames.has(typeName)) continue;
@@ -1333,6 +1371,16 @@ function renderMethod(
   const httpKey = `${op.httpMethod.toUpperCase()} ${op.path}`;
   const baselineClassMethod = baselineMethodFor(service, method, ctx);
   const optionInfo = optionsObjectInfo(service, method, op, plan, ctx, baselineClassMethod, resolvedOp);
+
+  // URL-builder operations (e.g. GET /sso/authorize) are spec-marked client-side
+  // URL constructors: emit a synchronous method that returns the request URL as
+  // a string without performing any I/O. This bypasses the HTTP method dispatch
+  // and the Promise-typed JSDoc below.
+  if (resolvedOp?.urlBuilder) {
+    renderUrlBuilderMethod(lines, op, method, pathStr, optionInfo, specEnumNames, resolvedOp);
+    return lines;
+  }
+
   const overlayMethod = ctx.overlayLookup?.methodByOperation?.get(httpKey) ?? baselineClassMethod;
   let validParamNames: Set<string> | null = null;
   if (optionInfo) {
@@ -2209,6 +2257,109 @@ function clientFieldExpression(field: string): string {
   }
 }
 
+/**
+ * Compose a `` `${this.workos.baseURL}<path>[?${query}]` `` template literal from
+ * a path expression produced by {@link buildPathStr}. The path expression is
+ * either a single-quoted static literal (`'/sso/authorize'`) or a backtick
+ * template with interpolated path params; either way its inner body is spliced
+ * into the URL template.
+ */
+function urlTemplateLiteral(pathExpr: string, hasQuery: boolean): string {
+  let inner: string;
+  if ((pathExpr.startsWith('`') && pathExpr.endsWith('`')) || (pathExpr.startsWith("'") && pathExpr.endsWith("'"))) {
+    inner = pathExpr.slice(1, -1);
+  } else {
+    inner = '${' + pathExpr + '}';
+  }
+  return '`${this.workos.baseURL}' + inner + (hasQuery ? '?${query}' : '') + '`';
+}
+
+/**
+ * Emit a URL-builder method for an operation marked with the `urlBuilder` hint
+ * (OAuth-style redirect endpoints such as `/sso/authorize`). The method is
+ * synchronous, returns the constructed URL as a string, and makes no HTTP call.
+ * Visible query params, constant `defaults`, and `inferFromClient` fields are
+ * serialized via `toQueryString` (wire-name keyed), matching the SDK's
+ * hand-written URL builders.
+ */
+function renderUrlBuilderMethod(
+  lines: string[],
+  op: Operation,
+  method: string,
+  pathStr: string,
+  optionInfo: OptionsObjectParam | undefined,
+  specEnumNames: Set<string> | undefined,
+  resolvedOp: ResolvedOperation | undefined,
+): void {
+  const hidden = hiddenParamsFor(resolvedOp);
+  const visibleQueryParams = op.queryParams.filter((p) => !hidden.has(p.name));
+  const hasQuery =
+    visibleQueryParams.length > 0 ||
+    Object.keys(getOpDefaults(resolvedOp)).length > 0 ||
+    getOpInferFromClient(resolvedOp).length > 0;
+
+  // Concise JSDoc — url builders return a string, not a Promise.
+  {
+    const docParts: string[] = [];
+    if (op.description) docParts.push(op.description);
+    docParts.push('@returns {string} The constructed URL.');
+    if (op.deprecated) docParts.push('@deprecated');
+    const allLines = docParts.flatMap((p) => p.split('\n'));
+    if (allLines.length === 1) {
+      lines.push(`  /** ${allLines[0]} */`);
+    } else {
+      lines.push('  /**');
+      for (const line of allLines) lines.push(line === '' ? '   *' : `   * ${line}`);
+      lines.push('   */');
+    }
+  }
+
+  if (optionInfo) {
+    // Options-object convention (matches the surrounding generated methods).
+    lines.push(`  ${method}(${renderOptionsParam(optionInfo)}): string {`);
+    if (hasQuery) {
+      const queryExpr = renderQueryExprWithOptions(visibleQueryParams, optionInfo.optional, resolvedOp);
+      lines.push(`    const query = toQueryString(${queryExpr});`);
+      lines.push(`    return ${urlTemplateLiteral(pathStr, true)};`);
+    } else {
+      lines.push(`    return ${urlTemplateLiteral(pathStr, false)};`);
+    }
+    lines.push('  }');
+    return;
+  }
+
+  // Positional convention (path-only url builders, possibly with injected fields).
+  // Invariant: any visible query param forces the options-object branch above
+  // (operationHasOptionsInput is true whenever one exists), so a positional
+  // builder never declares query params in its signature. Fail loudly if a
+  // future spec breaks that — its query value would have to come from an
+  // undeclared parameter. Past this guard the query is assembled solely from
+  // injected defaults and inferFromClient fields.
+  if (visibleQueryParams.length > 0) {
+    throw new Error(
+      `renderUrlBuilderMethod: positional url builder "${method}" has visible query params ` +
+        `(${visibleQueryParams.map((p) => p.name).join(', ')}) but no options object; they would be ` +
+        'referenced without being declared. Expected the options-object convention.',
+    );
+  }
+  const params = buildPathParams(op, specEnumNames);
+  lines.push(`  ${method}(${params}): string {`);
+  if (hasQuery) {
+    const queryParts: string[] = [];
+    for (const [key, value] of Object.entries(getOpDefaults(resolvedOp))) {
+      queryParts.push(`${key}: ${tsLiteral(value)}`);
+    }
+    for (const field of getOpInferFromClient(resolvedOp)) {
+      queryParts.push(`${field}: ${clientFieldExpression(field)}`);
+    }
+    lines.push(`    const query = toQueryString({ ${queryParts.join(', ')} });`);
+    lines.push(`    return ${urlTemplateLiteral(pathStr, true)};`);
+  } else {
+    lines.push(`    return ${urlTemplateLiteral(pathStr, false)};`);
+  }
+  lines.push('  }');
+}
+
 function renderVoidMethod(
   lines: string[],
   op: Operation,

package/src/rust/resources.ts

@@ -886,29 +886,40 @@ function renderAutoPagingMethod(
   // need a different stream wrapper.
   if (op.pagination.strategy !== 'cursor') return null;
   if (resolved.urlBuilder) return null;
-  if (op.response.kind !== 'model') return null;
-
-  const responseModel = ctx.spec.models.find((m) => m.name === (op.response as { name: string }).name);
-  if (!responseModel) return null;
 
   const cursorParam = op.pagination.param;
   const dataPath = op.pagination.dataPath ?? 'data';
-  const dataField = responseModel.fields.find((f) => f.name === dataPath);
-  if (!dataField || dataField.type.kind !== 'array') return null;
-  const listMetadataField = responseModel.fields.find((f) => f.name === 'list_metadata');
-  if (!listMetadataField || listMetadataField.type.kind !== 'model') return null;
-
-  // The response cursor lives on the list-metadata model under the same name
-  // as the request param. Bail if it doesn't — that would mean a spec/IR
-  // mismatch and a hand-written wrapper is safer than a broken generated one.
-  const metadataModel = ctx.spec.models.find((m) => m.name === (listMetadataField.type as { name: string }).name);
-  if (!metadataModel) return null;
-  if (!metadataModel.fields.some((f) => f.name === cursorParam)) return null;
-
-  // The IR's `pagination.itemType` is the response wrapper model (e.g.
-  // `OrganizationList`), so reach into the model's `data: Vec<T>` field to
-  // pull out the actual element type.
-  const itemType = mapTypeRef(dataField.type.items);
+  let itemType: string;
+
+  if (op.response.kind === 'model') {
+    const responseModel = ctx.spec.models.find((m) => m.name === (op.response as { name: string }).name);
+    if (!responseModel) return null;
+
+    const dataField = responseModel.fields.find((f) => f.name === dataPath);
+    if (!dataField || dataField.type.kind !== 'array') return null;
+    const listMetadataField = responseModel.fields.find((f) => f.name === 'list_metadata');
+    if (!listMetadataField || listMetadataField.type.kind !== 'model') return null;
+
+    // The response cursor lives on the list-metadata model under the same name
+    // as the request param. Bail if it doesn't — that would mean a spec/IR
+    // mismatch and a hand-written wrapper is safer than a broken generated one.
+    const metadataModel = ctx.spec.models.find((m) => m.name === (listMetadataField.type as { name: string }).name);
+    if (!metadataModel) return null;
+    if (!metadataModel.fields.some((f) => f.name === cursorParam)) return null;
+
+    // The IR's `pagination.itemType` is the response wrapper model (e.g.
+    // `OrganizationList`), so reach into the model's `data: Vec<T>` field to
+    // pull out the actual element type.
+    itemType = mapTypeRef(dataField.type.items);
+  } else if (isInlineEnvelopeList(op) && cursorParam === 'after') {
+    // Inline-envelope responses decode into `crate::pagination::Page<T>`,
+    // which declares `data` + `list_metadata.after` by construction — only
+    // the request-side cursor param needs to exist.
+    if (!op.queryParams.some((p) => p.name === cursorParam)) return null;
+    itemType = mapTypeRef((op.response as { items: TypeRef }).items);
+  } else {
+    return null;
+  }
 
   const cursorField = fieldName(cursorParam);
   const dataAccessor = fieldName(dataPath);
@@ -1144,19 +1155,27 @@ function renderWrapperMethod(
 
   sig.push(`        let method = http::Method::${op.httpMethod.toUpperCase()};`);
 
-  // Build the JSON body inline: defaults + inferFromClient (read from the
-  // client at request time) + each exposed param.
-  sig.push('        let body = serde_json::json!({');
+  // Build the JSON body inline: defaults + each exposed param. inferFromClient
+  // fields (read from the client at request time) are added afterwards, and
+  // only when non-empty — a client configured without an API key (e.g. a
+  // public client running a PKCE flow) must omit `client_secret` entirely
+  // rather than send `""`, which the API rejects. Mirrors the Go emitter's
+  // `omitempty` on inferred fields.
+  const inferredFields = wrapper.inferFromClient ?? [];
+  sig.push(`        let ${inferredFields.length > 0 ? 'mut ' : ''}body = serde_json::json!({`);
   for (const [k, v] of Object.entries(wrapper.defaults ?? {})) {
     sig.push(`            ${JSON.stringify(k)}: ${JSON.stringify(v)},`);
   }
-  for (const k of wrapper.inferFromClient ?? []) {
-    sig.push(`            ${JSON.stringify(k)}: ${clientFieldExpression(k)},`);
-  }
   for (const rp of params) {
     sig.push(`            ${JSON.stringify(rp.paramName)}: params.${fieldName(rp.paramName)},`);
   }
   sig.push('        });');
+  for (const k of inferredFields) {
+    const expr = clientFieldExpression(k);
+    sig.push(`        if !${expr}.is_empty() {`);
+    sig.push(`            body[${JSON.stringify(k)}] = serde_json::Value::String(${expr}.to_string());`);
+    sig.push('        }');
+  }
 
   sig.push('        #[derive(Serialize)]');
   sig.push('        struct EmptyQuery {}');
@@ -1170,8 +1189,11 @@ function renderWrapperMethod(
 
 /**
  * Rust expression for reading a client-config field at request time. Mirrors
- * the Go emitter's `clientFieldExpression`. Falls back to an empty literal
- * for unknown fields so the body still compiles.
+ * the Go emitter's `clientFieldExpression`. Throws on unknown fields rather
+ * than falling back to an empty literal: with the `if !expr.is_empty()` guard
+ * in `renderWrapperMethod`, an empty literal would silently drop the field from
+ * every request body (and emit dead `if !"".is_empty()` Rust). Failing loud at
+ * generation time surfaces a missing case instead of shipping a broken SDK.
  */
 function clientFieldExpression(field: string): string {
   switch (field) {
@@ -1180,7 +1202,10 @@ function clientFieldExpression(field: string): string {
     case 'client_secret':
       return 'self.client.api_key()';
     default:
-      return '""';
+      throw new Error(
+        `Rust emitter: no client-config accessor for inferFromClient field "${field}". ` +
+          'Add a case to clientFieldExpression.',
+      );
   }
 }
 
@@ -1266,9 +1291,33 @@ function methodDocLines(op: Operation): string[] {
 
 function renderResponseType(op: Operation): string {
   if (isEmptyResponse(op)) return '()';
+  if (isInlineEnvelopeList(op)) {
+    return `crate::pagination::Page<${mapTypeRef((op.response as { items: TypeRef }).items)}>`;
+  }
   return mapTypeRef(op.response!);
 }
 
+/**
+ * True when the spec declared this response as an inline pagination envelope
+ * (`{ object, data: [...], list_metadata }` without a named component). The IR
+ * models these as a bare array plus `pagination.dataPath`, but the wire format
+ * is still the envelope — decoding the body straight into `Vec<T>` fails, so
+ * these ops decode into the hand-maintained `crate::pagination::Page<T>`
+ * instead. Restricted to `data` because that's the field `Page<T>` declares.
+ *
+ * The `=== 'data'` is a strict equality on purpose — deliberately *not* the
+ * `?? 'data'` fallback used elsewhere. `dataPath` is the only signal that
+ * separates an inline envelope (decoded as `Page<T>`) from a genuine paginated
+ * bare array (decoded as `Vec<T>`, see the `responseKind === 'array'` branch in
+ * tests.ts). This therefore relies on the IR setting `dataPath: 'data'`
+ * explicitly for envelope responses and leaving it unset for bare arrays. If
+ * the IR ever omitted it for an envelope op, this would return `false` and the
+ * op would decode into `Vec<T>` and fail — so that invariant must hold upstream.
+ */
+export function isInlineEnvelopeList(op: Operation): boolean {
+  return op.response?.kind === 'array' && op.pagination?.dataPath === 'data';
+}
+
 /**
  * True when the operation has no usable response schema. We treat the IR's
  * `primitive: unknown` and missing-response cases the same way: the spec

package/src/rust/tests.ts

@@ -14,6 +14,7 @@ import { methodName, moduleName, typeName } from './naming.js';
 import { groupByMount } from '../shared/resolved-ops.js';
 import { exampleFor, generateFixtures } from './fixtures.js';
 import { resolveWrapperParams } from '../shared/wrapper-utils.js';
+import { isInlineEnvelopeList } from './resources.js';
 
 /**
  * Generate integration tests under `tests/`. Each mount group gets one
@@ -163,7 +164,11 @@ function renderRegularTest(
   const m = methodName(resolved.methodName);
   const literalPath = op.path.replace(/\{[^}]+\}/g, 'test_id');
   const httpMethod = op.httpMethod.toUpperCase();
-  const responseExpr = responseBodyExpr(op.response, modelMap, enumMap);
+  // Inline-envelope lists decode via crate::pagination::Page<T>, so the mock
+  // must serve the envelope even though the IR types the response as an array.
+  const responseExpr = isInlineEnvelopeList(op)
+    ? JSON.stringify('{"object":"list","data":[],"list_metadata":{"before":null,"after":null}}')
+    : responseBodyExpr(op.response, modelMap, enumMap);
   const isUrlBuilder = resolved.urlBuilder === true;
 
   const callArgs = buildCallArgs(op, resolved, crate, accessor, modelMap, enumMap).join(', ');
@@ -413,7 +418,12 @@ function emptyPageTest(op: Operation, shape: CallShape, accessor: string): strin
   const responseKind = op.response.kind;
   let body: string;
   let dataAccessor: string;
-  if (responseKind === 'array') {
+  if (isInlineEnvelopeList(op)) {
+    // Inline-envelope paginated response: SDK returns crate::pagination::Page<T>,
+    // so the mock must serve the envelope and assertions go through `.data`.
+    body = '{"object":"list","data":[],"list_metadata":{"before":null,"after":null}}';
+    dataAccessor = 'resp.data';
+  } else if (responseKind === 'array') {
     // Bare-array paginated response: SDK returns Vec<T>.
     body = '[]';
     dataAccessor = 'resp';
@@ -558,9 +568,10 @@ function encodesQueryParamsTest(
 /** Body expression for the encoding-test response (success, ignored). */
 function encodingResponseExpr(op: Operation, modelMap: Map<string, Model>, enumMap: Map<string, Enum>): string {
   // For paginated ops we serve an empty page so the call succeeds. Use the
-  // bare-array shape for `Vec<T>` responses, the wrapper shape otherwise.
+  // bare-array shape for `Vec<T>` responses, the wrapper shape for named
+  // wrapper models and inline envelopes (decoded via Page<T>).
   if (op.pagination) {
-    if (op.response.kind === 'array') return JSON.stringify('[]');
+    if (op.response.kind === 'array' && !isInlineEnvelopeList(op)) return JSON.stringify('[]');
     return JSON.stringify('{"object":"list","data":[],"list_metadata":{"before":null,"after":null}}');
   }
   return responseBodyExpr(op.response, modelMap, enumMap);

package/src/shared/union-flatten.ts

@@ -0,0 +1,201 @@
+import type { Model, Field, TypeRef, UnionType } from '@workos/oagen';
+
+/**
+ * Flatten field-level discriminated unions into a single superset model for
+ * the flat-emit languages (Go, Kotlin, Node) that have no native sum type.
+ *
+ * Background: a property like `ApiKey.owner` is a discriminated `oneOf` whose
+ * variants are inline objects — `{ type: 'organization', id }` and
+ * `{ type: 'user', id, organization_id }`. The IR represents this as a `union`
+ * TypeRef referencing two variant models (`ApiKeyOwner`, `UserApiKeyOwner`).
+ * Languages that render such a union as "the first variant" — Go's
+ * `unionResolverName`, Kotlin's `baseName` — silently drop every field that
+ * only exists on a later variant, so `organization_id` disappears for
+ * user-scoped keys. (See the SDK compat report's owner-field note.)
+ *
+ * This transform, applied only by the flat-emit emitters, merges every
+ * variant's fields into the first variant (the union's canonical model),
+ * marks any field not shared by all variants optional, widens the
+ * discriminator property to the union of its per-variant literal values, and
+ * rewrites the field to a plain model ref to that canonical model. The result
+ * is one flat struct/data class/interface that carries every variant field,
+ * with the discriminator property telling callers which variant they hold —
+ * exactly how these emitters already flatten `allOf [base, oneOf]`
+ * discriminated bases (see `enrichModelsFromSpec`).
+ *
+ * Returns a new models array; the input models are not mutated. Union-emitting
+ * languages (Python, PHP, Rust, Ruby, .NET) must NOT call this — they emit a
+ * real discriminated union and lose nothing.
+ */
+export function flattenDiscriminatedUnionFields(models: Model[]): Model[] {
+  const byName = new Map(models.map((m) => [m.name, m]));
+  // Canonical (first-variant) model name → its merged superset field list.
+  const mergedFieldsByCanonical = new Map<string, Field[]>();
+
+  /**
+   * Decide whether a union is a flat-flattenable discriminated union of inline
+   * object variants. When it is, record the merged field set for its canonical
+   * model and return that model's name; otherwise return null.
+   */
+  function planUnion(union: UnionType): string | null {
+    if (!union.discriminator) return null;
+
+    const variantNames = union.variants.map((v) => (v.kind === 'model' ? v.name : null));
+    // Require that *every* variant is a model ref (the inline-object oneOf
+    // shape). Untagged unions of primitives (e.g. AuditLogEvent actor
+    // metadata: string | number | boolean) carry no discriminator and never
+    // reach here, but guard anyway.
+    if (variantNames.length < 2 || variantNames.some((n) => n === null)) return null;
+
+    const variantModels = (variantNames as string[]).map((n) => byName.get(n));
+    // Every variant must resolve to a concrete data model — not a discriminator
+    // dispatcher (empty-field base with its own `discriminator`) and not a
+    // fieldless placeholder. This keeps event-style unions out of scope.
+    if (variantModels.some((m) => !m || (m as { discriminator?: unknown }).discriminator || m.fields.length === 0)) {
+      return null;
+    }
+
+    const canonical = (variantNames as string[])[0];
+    const merged = mergeVariantFields(variantModels as Model[], union.discriminator.property);
+
+    // The merge map is keyed by the first-variant model name. The same union
+    // referenced by several container fields re-plans to an identical merge
+    // (harmless). But two *distinct* unions that share a first variant would
+    // each want a different superset on that one model — pass 2 can apply only
+    // one, silently dropping the other's fields. Fail loudly instead; the spec
+    // must disambiguate (rename one union's leading variant).
+    const existing = mergedFieldsByCanonical.get(canonical);
+    if (existing && fieldListSignature(existing) !== fieldListSignature(merged)) {
+      throw new Error(
+        `flattenDiscriminatedUnionFields: model "${canonical}" is the first variant of two distinct ` +
+          'discriminated unions that merge to different field sets. Flattening both onto one model would ' +
+          'silently drop fields; disambiguate the variants in the spec (rename the leading variant of one union).',
+      );
+    }
+    mergedFieldsByCanonical.set(canonical, merged);
+    return canonical;
+  }
+
+  /** Rewrite a TypeRef, collapsing flattenable unions to a canonical model ref. */
+  function rewriteRef(ref: TypeRef): TypeRef {
+    switch (ref.kind) {
+      case 'union': {
+        const canonical = planUnion(ref);
+        return canonical ? { kind: 'model', name: canonical } : ref;
+      }
+      case 'nullable': {
+        // Preserve reference identity when nothing inside changed, so pass 1's
+        // `type === field.type` check doesn't flag (and rebuild) union-free fields.
+        const inner = rewriteRef(ref.inner);
+        return inner === ref.inner ? ref : { kind: 'nullable', inner };
+      }
+      case 'array': {
+        const items = rewriteRef(ref.items);
+        return items === ref.items ? ref : { kind: 'array', items };
+      }
+      default:
+        return ref;
+    }
+  }
+
+  // Pass 1: rewrite container fields, recording the merges to apply in pass 2.
+  const rewritten = models.map((model) => {
+    let changed = false;
+    const fields = model.fields.map((field) => {
+      const type = rewriteRef(field.type);
+      if (type === field.type) return field;
+      changed = true;
+      return { ...field, type };
+    });
+    return changed ? { ...model, fields } : model;
+  });
+
+  if (mergedFieldsByCanonical.size === 0) return models;
+
+  // Pass 2: replace each canonical variant model with its merged superset.
+  return rewritten.map((model) => {
+    const merged = mergedFieldsByCanonical.get(model.name);
+    return merged ? { ...model, fields: merged } : model;
+  });
+}
+
+/**
+ * Build the merged field list for a discriminated union's variant models.
+ *
+ * - A field is required only when present-and-required in *every* variant; a
+ *   field missing from some variant (e.g. the user variant's `organization_id`)
+ *   becomes optional.
+ * - The discriminator property is widened to the union of its per-variant
+ *   literal values (`'organization' | 'user'`) so it isn't pinned to the first
+ *   variant's constant. (Flat-emit type maps collapse a single-typed literal
+ *   union to a plain string, so this is a no-op for Go/Kotlin and a precise
+ *   `'organization' | 'user'` for Node.)
+ * - Field order follows the first variant, then newly-seen fields from later
+ *   variants.
+ */
+function mergeVariantFields(variants: Model[], discriminatorProp: string): Field[] {
+  const total = variants.length;
+  const order: string[] = [];
+  const defByName = new Map<string, Field>();
+  const presence = new Map<string, number>();
+  const requiredCount = new Map<string, number>();
+
+  for (const variant of variants) {
+    for (const field of variant.fields) {
+      const seen = defByName.get(field.name);
+      if (!seen) {
+        defByName.set(field.name, field);
+        order.push(field.name);
+      } else if (field.name !== discriminatorProp && !sameTypeRef(seen.type, field.type)) {
+        // Only the first-seen definition is kept, so a shared field whose type
+        // differs across variants would be merged with the wrong type for the
+        // other variants. The discriminator is exempt (it is widened below).
+        throw new Error(
+          `flattenDiscriminatedUnionFields: field "${field.name}" has conflicting types across variants ` +
+            'of a discriminated union; a flat superset model cannot represent both. Align the field type ' +
+            'across variants in the spec.',
+        );
+      }
+      presence.set(field.name, (presence.get(field.name) ?? 0) + 1);
+      if (field.required) requiredCount.set(field.name, (requiredCount.get(field.name) ?? 0) + 1);
+    }
+  }
+
+  return order.map((name) => {
+    const def = defByName.get(name)!;
+
+    if (name === discriminatorProp) {
+      const literals = dedupeLiteralTypes(
+        variants.map((v) => v.fields.find((f) => f.name === name)?.type).filter((t): t is TypeRef => t != null),
+      );
+      const type: TypeRef = literals.length > 1 ? { kind: 'union', variants: literals } : (literals[0] ?? def.type);
+      return { ...def, type, required: presence.get(name) === total };
+    }
+
+    const required = presence.get(name) === total && requiredCount.get(name) === total;
+    return required === def.required ? def : { ...def, required };
+  });
+}
+
+/** Structural equality of two TypeRefs (IR refs have a stable, deterministic shape). */
+function sameTypeRef(a: TypeRef, b: TypeRef): boolean {
+  return JSON.stringify(a) === JSON.stringify(b);
+}
+
+/** Stable signature of a merged field list, used to detect canonical collisions. */
+function fieldListSignature(fields: Field[]): string {
+  return JSON.stringify(fields.map((f) => [f.name, f.required, f.type]));
+}
+
+/** Deduplicate literal TypeRefs by value, preserving first-seen order. */
+function dedupeLiteralTypes(types: TypeRef[]): TypeRef[] {
+  const seen = new Set<string>();
+  const out: TypeRef[] = [];
+  for (const t of types) {
+    const key = t.kind === 'literal' ? `lit:${String(t.value)}` : JSON.stringify(t);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push(t);
+  }
+  return out;
+}