@workos/oagen-emitters 0.16.0 → 0.17.0

package/src/node/live-surface.ts

@@ -324,6 +324,315 @@ const METHOD_KEYWORD_BLOCKLIST = new Set([
   'constructor', // tracked separately if needed
 ]);
 
+// ---------------------------------------------------------------------------
+// Partial-emission merge
+//
+// For a service that is NOT owned and NOT a missing-service adoption,
+// `resources.ts` intentionally emits a PARTIAL resource class: operations
+// already covered by the baseline class are filtered out, leaving only the
+// new methods. Overwriting the on-disk file with that partial class would
+// delete every existing public method (this deleted four methods from
+// workos-node's api-keys.ts when the spec gained one operation). The helpers
+// below let `applyLiveSurface` detect that case and merge instead: keep the
+// existing file text verbatim and append only the generated-only methods
+// (plus any imports they need).
+// ---------------------------------------------------------------------------
+
+interface ParsedClassLines {
+  name: string;
+  /** Line index of the `export class` declaration. */
+  declLine: number;
+  /** Line index of the line containing the class body's closing brace. */
+  closeLine: number;
+  /** Method names declared directly on the class body, in source order. */
+  methods: string[];
+}
+
+// Class members sit at exactly two-space indent in both generated output and
+// prettier-formatted SDK files; deeper-indented lines are method bodies.
+const CLASS_MEMBER_RE =
+  /^ {2}(?:(?:public|private|protected|readonly|static)\s+)*(?:async\s+)?([a-zA-Z_$][\w$]*)\s*(?:<[^>]*>)?\s*\(/;
+
+interface BraceScan {
+  /** Net code-brace balance accumulated so far. */
+  depth: number;
+  /** Whether any code `{` has been seen — distinguishes "not yet opened" from "balanced and closed". */
+  opened: boolean;
+  /** Whether we are mid `/* … *​/` block comment (spans lines). */
+  inBlockComment: boolean;
+  /**
+   * Interpolation-brace depth for each active template literal; a non-empty
+   * stack means we are inside a template, and the top being 0 means we are in
+   * its raw text (vs. inside a `${ … }` interpolation).
+   */
+  templates: number[];
+}
+
+/**
+ * Advance a brace-balance scan across one `line`, mutating `s`. Counts only
+ * braces that live in *code* — including template `${ … }` interpolation,
+ * whose braces are self-balancing — and ignores braces inside string/template
+ * text, line comments, and block comments. State threads across lines so block
+ * comments and multi-line template literals are tracked correctly.
+ *
+ * Naive character counting (the prior approach) would clip a method block at a
+ * `}` that merely sat inside a comment (`// returns when done }`) or a string
+ * (`'closing brace: }'`), appending a truncated, unbalanced body. Regex
+ * literals are intentionally not modelled: distinguishing `/` division from a
+ * regex needs full tokenization, and a regex whose braces are net-unbalanced
+ * does not occur in generated or hand-edited SDK code (`{n,m}` quantifiers are
+ * always balanced).
+ */
+function advanceBraceScan(line: string, s: BraceScan): void {
+  for (let i = 0; i < line.length; i++) {
+    const c = line[i];
+    if (s.inBlockComment) {
+      if (c === '*' && line[i + 1] === '/') {
+        s.inBlockComment = false;
+        i++;
+      }
+      continue;
+    }
+    const tdepth = s.templates.length;
+    if (tdepth > 0 && s.templates[tdepth - 1] === 0) {
+      // Raw template text: only an escape, a closing backtick, or the start of
+      // an interpolation matters; everything else (braces included) is literal.
+      if (c === '\\') {
+        i++;
+      } else if (c === '`') {
+        s.templates.pop();
+      } else if (c === '$' && line[i + 1] === '{') {
+        s.templates[tdepth - 1] = 1;
+        s.depth++;
+        s.opened = true;
+        i++;
+      }
+      continue;
+    }
+    // Code context: top level, or inside a template interpolation.
+    if (c === '/' && line[i + 1] === '/') break; // line comment runs to EOL
+    if (c === '/' && line[i + 1] === '*') {
+      s.inBlockComment = true;
+      i++;
+      continue;
+    }
+    if (c === "'" || c === '"') {
+      const quote = c;
+      i++;
+      while (i < line.length && line[i] !== quote) {
+        if (line[i] === '\\') i++;
+        i++;
+      }
+      continue;
+    }
+    if (c === '`') {
+      s.templates.push(0);
+      continue;
+    }
+    if (c === '{') {
+      s.depth++;
+      s.opened = true;
+      if (tdepth > 0) s.templates[tdepth - 1]++;
+    } else if (c === '}') {
+      s.depth--;
+      if (tdepth > 0) s.templates[tdepth - 1]--;
+    }
+  }
+}
+
+function parseClassesByLine(lines: string[]): ParsedClassLines[] {
+  const classes: ParsedClassLines[] = [];
+  for (let i = 0; i < lines.length; i++) {
+    const decl = lines[i].match(/^export\s+(?:abstract\s+)?class\s+([A-Z][\w$]*)/);
+    if (!decl) continue;
+
+    const scan: BraceScan = { depth: 0, opened: false, inBlockComment: false, templates: [] };
+    let closeLine = -1;
+    for (let j = i; j < lines.length; j++) {
+      advanceBraceScan(lines[j], scan);
+      if (scan.opened && scan.depth <= 0) {
+        closeLine = j;
+        break;
+      }
+    }
+    if (closeLine < 0) continue;
+
+    const methods: string[] = [];
+    for (let j = i + 1; j < closeLine; j++) {
+      const member = lines[j].match(CLASS_MEMBER_RE);
+      if (!member) continue;
+      const name = member[1];
+      if (name === 'constructor' || METHOD_KEYWORD_BLOCKLIST.has(name)) continue;
+      if (!methods.includes(name)) methods.push(name);
+    }
+    classes.push({ name: decl[1], declLine: i, closeLine, methods });
+    i = closeLine;
+  }
+  return classes;
+}
+
+/**
+ * Extract the full source block of `method` (attached comments included) from
+ * a parsed class. Returns null if the block cannot be delimited.
+ */
+function extractMethodBlock(lines: string[], cls: ParsedClassLines, method: string): string[] | null {
+  for (let j = cls.declLine + 1; j < cls.closeLine; j++) {
+    const member = lines[j].match(CLASS_MEMBER_RE);
+    if (!member || member[1] !== method) continue;
+
+    // Pull in the contiguous comment block directly above the signature.
+    let start = j;
+    while (start > cls.declLine + 1) {
+      const above = lines[start - 1].trim();
+      if (above.startsWith('//') || above.startsWith('/*') || above.startsWith('*')) start--;
+      else break;
+    }
+
+    // The member ends where the brace depth opened by its signature returns to
+    // zero. `advanceBraceScan` counts only code braces — ignoring those inside
+    // strings, template text, and comments — so it is robust to inner closures,
+    // object literals, and template interpolation nested at any indentation, as
+    // well as a stray `}` in a comment or string. The previous "first
+    // two-space-indented `}`" heuristic clipped the block at a nested brace at
+    // method-close indentation; raw character counting clipped it at a `}` that
+    // merely sat in a comment or string. Either appends a truncated body and
+    // orphans the real closing brace.
+    const scan: BraceScan = { depth: 0, opened: false, inBlockComment: false, templates: [] };
+    for (let end = j; end < cls.closeLine; end++) {
+      advanceBraceScan(lines[end], scan);
+      if (scan.opened && scan.depth <= 0) return lines.slice(start, end + 1);
+    }
+    return null;
+  }
+  return null;
+}
+
+// Multi-line tolerant: prettier wraps long named-import lists across lines.
+const IMPORT_STMT_RE =
+  /^import\s+(type\s+)?(?:([A-Za-z_$][\w$]*)\s*,?\s*)?(?:\{([\s\S]*?)\}\s*)?(?:\*\s+as\s+([A-Za-z_$][\w$]*)\s+)?from\s+['"]([^'"]+)['"];?/gm;
+
+function importLocalName(entry: string): string {
+  const asMatch = entry.match(/\s+as\s+([A-Za-z_$][\w$]*)\s*$/);
+  if (asMatch) return asMatch[1];
+  return entry.replace(/^type\s+/, '').trim();
+}
+
+function collectImportedLocalNames(text: string): Set<string> {
+  const names = new Set<string>();
+  for (const m of text.matchAll(IMPORT_STMT_RE)) {
+    if (m[2]) names.add(m[2]);
+    if (m[4]) names.add(m[4]);
+    for (const entry of (m[3] ?? '').split(',')) {
+      const trimmed = entry.trim();
+      if (trimmed) names.add(importLocalName(trimmed));
+    }
+  }
+  return names;
+}
+
+/** Import statements from `generatedText` whose names `existingText` lacks. */
+function missingImportStatements(existingText: string, generatedText: string): string[] {
+  const existingNames = collectImportedLocalNames(existingText);
+  const statements: string[] = [];
+  for (const m of generatedText.matchAll(IMPORT_STMT_RE)) {
+    const [stmt, typeOnly, defaultName, named, namespaceName, moduleSpec] = m;
+    if (defaultName || namespaceName) {
+      // Default/namespace imports: append verbatim when the local is missing.
+      const local = defaultName ?? namespaceName;
+      if (local && !existingNames.has(local)) statements.push(stmt.endsWith(';') ? stmt : `${stmt};`);
+      continue;
+    }
+    const missing = (named ?? '')
+      .split(',')
+      .map((entry) => entry.trim())
+      .filter((entry) => entry && !existingNames.has(importLocalName(entry)));
+    if (missing.length === 0) continue;
+    statements.push(`import ${typeOnly ? 'type ' : ''}{ ${missing.join(', ')} } from '${moduleSpec}';`);
+  }
+  return statements;
+}
+
+/**
+ * Merge a partial class emission into the existing on-disk file content.
+ *
+ * Acts only when a class declared in BOTH texts has methods on disk that the
+ * generated content drops — the signature of a "new operations only" partial
+ * emission. Returns the existing text with the generated-only methods appended
+ * to the class body (and missing imports added), preserving every existing
+ * method and import verbatim.
+ *
+ * Returns null when the generated content does not drop any existing method;
+ * callers should then proceed with their normal (overwrite) path so full
+ * regenerations keep propagating emitter improvements and spec renames.
+ */
+export function mergeGeneratedClassMethodsIntoExisting(existingText: string, generatedText: string): string | null {
+  const existingLines = existingText.split('\n');
+  const generatedLines = generatedText.split('\n');
+  const existingClasses = parseClassesByLine(existingLines);
+  if (existingClasses.length === 0) return null;
+  const generatedClasses = new Map(parseClassesByLine(generatedLines).map((cls) => [cls.name, cls]));
+
+  let dropsExistingMethod = false;
+  const insertions: Array<{ atLine: number; blocks: string[][] }> = [];
+  for (const existing of existingClasses) {
+    const generated = generatedClasses.get(existing.name);
+    if (!generated) continue;
+    const generatedMethods = new Set(generated.methods);
+    if (!existing.methods.some((method) => !generatedMethods.has(method))) continue;
+    dropsExistingMethod = true;
+
+    const existingMethods = new Set(existing.methods);
+    const blocks: string[][] = [];
+    for (const method of generated.methods) {
+      if (existingMethods.has(method)) continue;
+      const block = extractMethodBlock(generatedLines, generated, method);
+      if (block) blocks.push(block);
+    }
+    if (blocks.length > 0) insertions.push({ atLine: existing.closeLine, blocks });
+  }
+  if (!dropsExistingMethod) return null;
+
+  const merged = [...existingLines];
+  // Bottom-up so earlier insertions don't shift later line indices. Imports
+  // sit above every class body, so the import insertion point (computed on
+  // the original text) stays valid after these splices.
+  insertions.sort((a, b) => b.atLine - a.atLine);
+  for (const insertion of insertions) {
+    const blockLines: string[] = [];
+    for (const block of insertion.blocks) {
+      blockLines.push('', ...block);
+    }
+    merged.splice(insertion.atLine, 0, ...blockLines);
+  }
+
+  const importStatements = missingImportStatements(existingText, generatedText);
+  if (importStatements.length > 0) {
+    let lastImportLine = -1;
+    for (let i = 0; i < existingLines.length; i++) {
+      if (
+        /from\s+['"][^'"]+['"];?\s*$/.test(existingLines[i]) ||
+        /^import\s+['"][^'"]+['"];?\s*$/.test(existingLines[i])
+      ) {
+        lastImportLine = i;
+      }
+    }
+    if (lastImportLine >= 0) {
+      merged.splice(lastImportLine + 1, 0, ...importStatements);
+    } else {
+      // No imports yet: place them after the leading comment block.
+      let insertAt = 0;
+      while (insertAt < existingLines.length) {
+        const line = existingLines[insertAt].trim();
+        if (line === '' || line.startsWith('//') || line.startsWith('/*') || line.startsWith('*')) insertAt++;
+        else break;
+      }
+      merged.splice(insertAt, 0, ...importStatements, '');
+    }
+  }
+
+  return merged.join('\n');
+}
+
 /**
  * Given the start index of a class declaration, return the brace-delimited body
  * as a substring. Returns '' if the body cannot be located.

package/src/node/models.ts

@@ -41,7 +41,7 @@ import {
   emitSerializerBody,
   hasDateTimeConversion,
 } from './field-plan.js';
-import { liveSurfaceHasExistingSdk, liveSurfaceHasManagedFile } from './live-surface.js';
+import { liveSurfaceHasExistingSdk, liveSurfaceHasManagedFile, liveSurfaceInterfacePath } from './live-surface.js';
 import { isNodeOwnedService } from './options.js';
 import { unwrapListModel } from './fixtures.js';
 import { groupByMount, buildResolvedLookup, lookupResolved } from '../shared/resolved-ops.js';
@@ -370,7 +370,13 @@ export function generateModels(models: Model[], ctx: EmitterContext, shared?: Sh
             const eDir = resolveDir(eService);
             const bEnum = ctx.apiSurface?.enums?.[irEnumName];
             const bAlias = ctx.apiSurface?.typeAliases?.[irEnumName];
-            const bSrc = (bEnum as any)?.sourceFile ?? (bAlias as any)?.sourceFile;
+            // Same owned-service exception as the `deps.enums` loop below:
+            // `generateEnums` emits the canonical module for owned services
+            // even when the baseline declares the name elsewhere (usually in
+            // the very file being overwritten), so import planning must
+            // target the canonical path to agree with that emission.
+            const eEnumIsOwned = isNodeOwnedService(ctx, eService);
+            const bSrc = eEnumIsOwned ? undefined : ((bEnum as any)?.sourceFile ?? (bAlias as any)?.sourceFile);
             const gPath = `src/${eDir}/interfaces/${fileName(irEnumName)}.interface.ts`;
             const cPath = `src/${dirName}/interfaces/${fileName(model.name)}.interface.ts`;
             if (bSrc === cPath) {
@@ -446,8 +452,21 @@ export function generateModels(models: Model[], ctx: EmitterContext, shared?: Sh
 
       const baselineEnum = ctx.apiSurface?.enums?.[dep];
       const baselineAlias = ctx.apiSurface?.typeAliases?.[dep];
-      const baselineSrc = (baselineEnum as any)?.sourceFile ?? (baselineAlias as any)?.sourceFile;
       const depService = enumToService.get(dep);
+      const depEnumIsOwned = isNodeOwnedService(ctx, depService);
+      // Fall back to the live-surface declaration path: `generateEnums` skips
+      // emission when the enum is already declared elsewhere in the SDK (same
+      // fallback, see enums.ts), so the import must follow that declaration —
+      // the canonical per-service file will never exist.
+      //
+      // OWNED services are the exception, mirroring enums.ts: the on-disk
+      // declaration usually lives in a file this very regeneration
+      // overwrites, `generateEnums` emits the canonical module anyway, and
+      // the import must agree with that emission — otherwise the generated
+      // interface references a name that is declared nowhere.
+      const baselineSrc = depEnumIsOwned
+        ? undefined
+        : ((baselineEnum as any)?.sourceFile ?? (baselineAlias as any)?.sourceFile ?? liveSurfaceInterfacePath(dep));
       const depDir = resolveDir(depService);
       const generatedPath = `src/${depDir}/interfaces/${fileName(dep)}.interface.ts`;
       const currentFilePath = `src/${dirName}/interfaces/${fileName(model.name)}.interface.ts`;
@@ -602,6 +621,17 @@ export function generateModels(models: Model[], ctx: EmitterContext, shared?: Sh
             if (generatedNames.has(name)) continue;
             const sepPath = `src/${dirName}/interfaces/${fileName(name)}.interface.ts`;
             if (sepPath !== filePath && files.some((f) => f.path === sepPath)) continue;
+            // Owned-service enums get their canonical per-service module
+            // emitted by `generateEnums` this run, and this file imports the
+            // name (see the deps.enums loop above). Preserving the legacy
+            // inline declaration would collide with that import (TS2440).
+            if (
+              !isInlineEnum(name) &&
+              ctx.spec.enums.some((e) => e.name === name) &&
+              isNodeOwnedService(ctx, enumToService.get(name))
+            ) {
+              continue;
+            }
             inlineNames.add(name);
           }
         };
@@ -1164,6 +1194,16 @@ function baselineTypeResolvable(typeStr: string, importableNames: Set<string>):
 }
 
 function baselineFieldCompatible(baselineField: { type: string; optional: boolean }, irField: Field): boolean {
+  // A baseline `any` is the footprint of a previously-broken generation:
+  // api-surface extraction types a field as `any` when its import failed to
+  // resolve (e.g. the enum file hadn't been emitted yet in that run). Copying
+  // it forward would freeze the degradation — once `state: any` lands in the
+  // SDK, every later regen sees it as the baseline and re-emits it. When the
+  // IR knows the real model/enum name, always re-derive from the IR instead.
+  if (baselineTypeIsDegradedAny(baselineField.type) && hasNamedTypeReference(irField.type)) {
+    return false;
+  }
+
   const irNullable = irField.type.kind === 'nullable';
   const baselineHasNull = baselineField.type.includes('null');
 
@@ -1182,6 +1222,32 @@ function baselineFieldCompatible(baselineField: { type: string; optional: boolea
   return true;
 }
 
+/** `any`, `any[]`, `any | null`, … — shapes api-surface extraction degrades to. */
+function baselineTypeIsDegradedAny(typeStr: string): boolean {
+  const stripped = typeStr
+    .replace(/\s*\|\s*(?:null|undefined)\b/g, '')
+    .replace(/\[\]$/, '')
+    .trim();
+  return stripped === 'any';
+}
+
+/** Does the IR type reference a named model/enum anywhere (incl. arrays)? */
+function hasNamedTypeReference(ref: TypeRef): boolean {
+  switch (ref.kind) {
+    case 'model':
+    case 'enum':
+      return true;
+    case 'array':
+      return hasNamedTypeReference(ref.items);
+    case 'nullable':
+      return hasNamedTypeReference(ref.inner);
+    case 'union':
+      return ref.variants.some((v) => hasNamedTypeReference(v));
+    default:
+      return false;
+  }
+}
+
 function hasSpecificIRType(ref: TypeRef): boolean {
   switch (ref.kind) {
     case 'model':

package/src/node/naming.ts

@@ -61,6 +61,26 @@ export function setBaselineInterfaceNames(names: Set<string>): void {
   baselineInterfaceNames = names;
 }
 
+/**
+ * Every name DECLARED by the live SDK or baseline api-surface — interfaces
+ * AND type aliases. Exact-name declarations preempt structural renames in
+ * `resolveInterfaceName`: when the IR model's own name is already declared,
+ * the structural matcher must not re-point it at a different declaration.
+ *
+ * This matters for alias-form files (`export type X = Y;`): the engine's
+ * api-surface records X under `typeAliases` with no fields, so its
+ * exact-name pass cannot claim X and the Jaccard fallback "renames" IR
+ * model X to whatever interface looks similar. Propagating that rename
+ * emitted duplicate, renamed declarations whose form flip-flopped on every
+ * regeneration (workos-node ApiKeyOwner / UserManagement model files).
+ *
+ * Set by `index.ts` immediately after `getSurface(ctx)` runs.
+ */
+let baselineDeclaredNames: Set<string> = new Set();
+export function setBaselineDeclaredNames(names: Set<string>): void {
+  baselineDeclaredNames = names;
+}
+
 /**
  * IR models that belong to newly-adopted services should not be renamed by
  * structural baseline matches from unrelated hand-written services.
@@ -100,6 +120,178 @@ export function setStructurallyRenamedDomainNames(names: Set<string>): void {
   structurallyRenamedDomainNames = names;
 }
 
+/**
+ * The structural half of `resolveInterfaceName`, pre-injectivity: look up the
+ * engine's structurally-inferred match (`overlayLookup.modelNameByIR`), apply
+ * the adopted/discriminated/declared-name guards, and normalize legacy
+ * `Serialized*` / wire-shaped `*Response` matches down to the baseline domain
+ * name. Returns the candidate live name, or undefined when no structural
+ * match applies. Shared by `resolveInterfaceName` and the claims registry so
+ * both see the exact same candidate for every IR model.
+ */
+function inferStructuralRename(name: string, ctx: EmitterContext): string | undefined {
+  let inferred =
+    adoptedModelNames.has(name) || discriminatedModelNames.has(name)
+      ? undefined
+      : ctx.overlayLookup?.modelNameByIR?.get(name);
+  // Exact-name declarations preempt structural renames: when the live SDK
+  // already declares `name` (interface or type alias), a non-identity
+  // structural match is a misfire — the alias/typeAlias resolution in
+  // `resolveInterfaceName` (or the name itself) is the canonical answer. See
+  // `setBaselineDeclaredNames` for the alias-form feedback loop this breaks.
+  if (inferred && inferred !== name && baselineDeclaredNames.has(name)) {
+    return undefined;
+  }
+  if (!inferred) return undefined;
+  if (inferred.startsWith('Serialized')) {
+    const stripped = inferred.slice('Serialized'.length);
+    if (stripped && ctx.apiSurface?.interfaces?.[stripped]) {
+      inferred = stripped;
+    }
+  }
+  // Structural matchers tend to lock onto the wire-shaped baseline
+  // interface (`AuditLogSchemaResponse`) because the IR carries
+  // snake_case fields. Prefer the corresponding domain name (without
+  // the `Response` suffix) when both exist in baseline — domain refs
+  // belong on the domain side, the wire/serialize path picks up the
+  // `*Response` variant via `wireInterfaceName`.
+  if (inferred.endsWith('Response') && ctx.apiSurface?.interfaces) {
+    const stripped = inferred.slice(0, -'Response'.length);
+    if (stripped && ctx.apiSurface.interfaces[stripped]) {
+      inferred = stripped;
+    }
+  }
+  return inferred;
+}
+
+/**
+ * Per-run registry making structural name resolution INJECTIVE: live-surface
+ * name → the single IR model name allowed to claim it. Built lazily from
+ * `ctx.spec.models` on first use and cached per ctx.
+ *
+ * Cache-correctness invariant (relied on, not assumed): the `ctx` reaching
+ * this function is always the memoized `nodeCtx` from `withNodeOperationOverrides`
+ * — every emitter hook derives it as its first step and threads it through
+ * `getSurface`/`resolveInterfaceName`, and that helper returns one stable
+ * object per run. `nodeCtx.spec` is built once via spread and `spec.models` is
+ * never reassigned or mutated in place anywhere (enrichment pushes only onto a
+ * pre-enrichment local collector). So the cached value can never drift from
+ * the `spec.models` it was computed from. Do not begin mutating `spec.models`
+ * under a live ctx without invalidating this cache.
+ *
+ * Without it, the structural fallback could map two distinct IR models onto
+ * one live declaration. workos-node AuditLogs evidence: IR
+ * `AuditLogEventActor` and `AuditLogEventTarget` (near-identical shapes) both
+ * resolved to the hand-written `AuditLogActor`, so
+ * `audit-log-event-target.interface.ts` was emitted declaring
+ * `export interface AuditLogActor` (file stem and declaration disagree),
+ * with duplicate imports/`describe` blocks and two `serializeAuditLogActor`
+ * definitions downstream. The raw engine overlay is injective on its own
+ * names, but the resolver's `Serialized*`/`*Response` normalization below can
+ * collapse two distinct raw matches onto one bare name — the claims registry
+ * gates the final, post-normalization answer.
+ *
+ * Claim order:
+ *  1. Exact-name overrides (`overlayLookup.interfaceByName`) claim first.
+ *  2. Identity structural matches (IR name === live name) claim their own name.
+ *  3. Contested renames go to the claimant with the higher field-overlap
+ *     similarity; ties break toward the closer name (edit distance), then
+ *     lexicographically for determinism. Losers are NEVER unified — they keep
+ *     their canonical IR-derived names.
+ */
+const structuralClaimsCache = new WeakMap<EmitterContext, Map<string, string>>();
+
+/** Jaccard similarity between two normalized field-name sets. */
+function fieldJaccard(a: Set<string>, b: Set<string>): number {
+  if (a.size === 0 && b.size === 0) return 0;
+  let intersection = 0;
+  for (const item of a) if (b.has(item)) intersection++;
+  const union = a.size + b.size - intersection;
+  return union === 0 ? 0 : intersection / union;
+}
+
+/** Levenshtein distance over lowercased names (tie-break for contested claims). */
+function nameDistance(a: string, b: string): number {
+  const s = a.toLowerCase();
+  const t = b.toLowerCase();
+  if (s === t) return 0;
+  let prev = Array.from({ length: t.length + 1 }, (_, i) => i);
+  for (let i = 1; i <= s.length; i++) {
+    const curr = [i];
+    for (let j = 1; j <= t.length; j++) {
+      const cost = s[i - 1] === t[j - 1] ? 0 : 1;
+      curr[j] = Math.min(curr[j - 1] + 1, prev[j] + 1, prev[j - 1] + cost);
+    }
+    prev = curr;
+  }
+  return prev[t.length];
+}
+
+/** Normalized field-name signature of an IR model. */
+function irFieldSignature(model: { fields: { name: string }[] }): Set<string> {
+  return new Set(model.fields.map((f) => toSnakeCase(f.name)));
+}
+
+/** Normalized field-name signature of a live-surface interface, if known. */
+function liveFieldSignature(ctx: EmitterContext, liveName: string): Set<string> | undefined {
+  const iface = ctx.apiSurface?.interfaces?.[liveName] as { fields?: Record<string, unknown> } | undefined;
+  if (!iface?.fields) return undefined;
+  return new Set(Object.keys(iface.fields).map((f) => toSnakeCase(f)));
+}
+
+function getStructuralNameClaims(ctx: EmitterContext): Map<string, string> {
+  const cached = structuralClaimsCache.get(ctx);
+  if (cached) return cached;
+  const claims = new Map<string, string>();
+
+  // 1. Exact-name overrides claim first (mirrors resolveInterfaceName step 1).
+  for (const [irName, liveName] of ctx.overlayLookup?.interfaceByName ?? new Map<string, string>()) {
+    if (!claims.has(liveName)) claims.set(liveName, irName);
+  }
+
+  // 2. Identity matches claim their own name; renames queue up per live name.
+  const contested = new Map<string, string[]>();
+  const modelsByName = new Map<string, { fields: { name: string }[] }>();
+  for (const model of ctx.spec.models) {
+    modelsByName.set(model.name, model);
+    if (ctx.overlayLookup?.interfaceByName?.has(model.name)) continue;
+    const inferred = inferStructuralRename(model.name, ctx);
+    if (!inferred) continue;
+    if (inferred === model.name) {
+      if (!claims.has(inferred)) claims.set(inferred, model.name);
+      continue;
+    }
+    const group = contested.get(inferred);
+    if (group) group.push(model.name);
+    else contested.set(inferred, [model.name]);
+  }
+
+  // 3. Award each contested live name to exactly one structural claimant.
+  for (const [liveName, irNames] of contested) {
+    if (claims.has(liveName)) continue; // exact/identity claims preempt renames
+    let winner = irNames[0];
+    if (irNames.length > 1) {
+      const liveFields = liveFieldSignature(ctx, liveName);
+      const scoreOf = (irName: string): number => {
+        const model = modelsByName.get(irName);
+        if (!model || !liveFields) return 0;
+        return fieldJaccard(irFieldSignature(model), liveFields);
+      };
+      winner = [...irNames].sort((a, b) => {
+        const scoreDiff = scoreOf(b) - scoreOf(a);
+        if (scoreDiff !== 0) return scoreDiff;
+        const distDiff = nameDistance(a, liveName) - nameDistance(b, liveName);
+        if (distDiff !== 0) return distDiff;
+        return a < b ? -1 : a > b ? 1 : 0;
+      })[0];
+    }
+    claims.set(liveName, winner);
+  }
+
+  structuralClaimsCache.set(ctx, claims);
+  return claims;
+}
+
 /**
  * Wire/response interface name.
  *
@@ -224,7 +416,8 @@ export function resolveClassName(service: Service, ctx: EmitterContext): string
  *  1. `overlayLookup.interfaceByName` — exact-name overrides from the live SDK.
  *  2. `overlayLookup.modelNameByIR` — structurally-inferred matches (e.g., IR
  *     `ValidateApiKey` with one field `value: string` → live SDK interface
- *     `ValidateApiKeyOptions`).
+ *     `ValidateApiKeyOptions`), gated by the injective claims registry: each
+ *     live name goes to at most one IR model (see `getStructuralNameClaims`).
  *  3. Type-alias resolution (when an alias points to an interface).
  *  4. Suffix-fallback heuristic for the workos-node `*Options` convention:
  *     when the IR name `X` has no baseline match but `XOptions` does, use
@@ -236,30 +429,18 @@ export function resolveInterfaceName(name: string, ctx: EmitterContext, opts?: {
   const existing = ctx.overlayLookup?.interfaceByName?.get(name);
   if (existing) return existing;
 
-  let inferred =
-    adoptedModelNames.has(name) || discriminatedModelNames.has(name)
-      ? undefined
-      : ctx.overlayLookup?.modelNameByIR?.get(name);
-  if (inferred) {
-    if (inferred.startsWith('Serialized')) {
-      const stripped = inferred.slice('Serialized'.length);
-      if (stripped && ctx.apiSurface?.interfaces?.[stripped]) {
-        inferred = stripped;
-      }
-    }
-    // Structural matchers tend to lock onto the wire-shaped baseline
-    // interface (`AuditLogSchemaResponse`) because the IR carries
-    // snake_case fields. Prefer the corresponding domain name (without
-    // the `Response` suffix) when both exist in baseline — domain refs
-    // belong on the domain side, the wire/serialize path picks up the
-    // `*Response` variant via `wireInterfaceName`.
-    if (inferred.endsWith('Response') && ctx.apiSurface?.interfaces) {
-      const stripped = inferred.slice(0, -'Response'.length);
-      if (stripped && ctx.apiSurface.interfaces[stripped]) {
-        inferred = stripped;
+  let inferred = inferStructuralRename(name, ctx);
+  if (inferred !== undefined) {
+    // Injectivity gate: a structurally-renamed live name may be claimed by
+    // at most one IR model per run. When another model holds the claim, the
+    // rename is dropped and this model keeps its canonical IR-derived name.
+    if (inferred !== name) {
+      const claimant = getStructuralNameClaims(ctx).get(inferred);
+      if (claimant !== undefined && claimant !== name) {
+        inferred = undefined;
       }
     }
-    return inferred;
+    if (inferred !== undefined) return inferred;
   }
 
   if (!opts?.skipTypeAlias && ctx.apiSurface?.typeAliases) {