@workos/oagen-emitters 0.15.2 → 0.16.1

package/test/node/live-surface.test.ts

@@ -3,8 +3,17 @@ import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
 import { execFileSync } from 'node:child_process';
+import type { ApiSpec, EmitterContext, Operation, Service } from '@workos/oagen';
+import { defaultSdkBehavior } from '@workos/oagen';
 
-import { buildLiveSurface, emptyLiveSurface, pathExists, shouldSkipPath } from '../../src/node/live-surface.js';
+import {
+  buildLiveSurface,
+  emptyLiveSurface,
+  mergeGeneratedClassMethodsIntoExisting,
+  pathExists,
+  shouldSkipPath,
+} from '../../src/node/live-surface.js';
+import { nodeEmitter } from '../../src/node/index.js';
 
 let tmpRoot: string;
 
@@ -238,3 +247,764 @@ describe('helpers', () => {
     expect(pathExists(surface, 'anything')).toBe(false);
   });
 });
+
+// ---------------------------------------------------------------------------
+// Partial emission must never delete existing methods (workos-node api-keys
+// regression): a NOT-owned, NOT-adopted service whose autogen-headed resource
+// file already exists gets a "new operations only" emission from resources.ts.
+// applyLiveSurface used to promote that partial file to a full overwrite,
+// replacing a 4-method class with a 1-method class.
+// ---------------------------------------------------------------------------
+
+const baseSpec: ApiSpec = {
+  name: 'Test',
+  version: '1.0.0',
+  baseUrl: '',
+  services: [],
+  models: [],
+  enums: [],
+  sdk: defaultSdkBehavior(),
+};
+
+const baseCtx: EmitterContext = {
+  namespace: 'workos',
+  namespacePascal: 'WorkOS',
+  spec: baseSpec,
+};
+
+function makeOp(name: string, httpMethod: Operation['httpMethod'], opPath: string): Operation {
+  return {
+    name,
+    httpMethod,
+    path: opPath,
+    pathParams: opPath.includes('{id}')
+      ? [{ name: 'id', type: { kind: 'primitive', type: 'string' }, required: true }]
+      : [],
+    queryParams: [],
+    headerParams: [],
+    response: { kind: 'primitive', type: 'unknown' },
+    errors: [],
+    injectIdempotencyKey: false,
+  };
+}
+
+const EXISTING_API_KEYS_CLASS = [
+  '// This file is auto-generated by oagen. Do not edit.',
+  '',
+  "import { WorkOS } from '../workos';",
+  'import {',
+  '  ValidateApiKeyOptions,',
+  '  ValidateApiKeyResponse,',
+  "} from './interfaces/validate-api-key.interface';",
+  '',
+  'export class ApiKeys {',
+  '  constructor(private readonly workos: WorkOS) {}',
+  '',
+  '  async createValidation(',
+  '    payload: ValidateApiKeyOptions,',
+  '  ): Promise<ValidateApiKeyResponse> {',
+  "    const { data } = await this.workos.post('/api_keys/validations', payload);",
+  '    return data;',
+  '  }',
+  '',
+  '  /**',
+  '   * Delete an API key',
+  '   */',
+  '  async deleteApiKey(id: string): Promise<void> {',
+  '    await this.workos.delete(`/api_keys/${id}`);',
+  '  }',
+  '',
+  '  async listOrganizationApiKeys(organizationId: string): Promise<unknown> {',
+  '    return this.workos.get(`/organizations/${organizationId}/api_keys`);',
+  '  }',
+  '',
+  '  async createOrganizationApiKey(organizationId: string): Promise<unknown> {',
+  '    return this.workos.post(`/organizations/${organizationId}/api_keys`, {});',
+  '  }',
+  '}',
+  '',
+].join('\n');
+
+function createApiKeysSdkRoot(): string {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'node-partial-overwrite-'));
+  fs.mkdirSync(path.join(root, 'src', 'api-keys'), { recursive: true });
+  fs.writeFileSync(path.join(root, 'src', 'workos.ts'), '// @oagen-ignore-file\nexport class WorkOS {}\n');
+  fs.writeFileSync(path.join(root, 'src', 'index.ts'), '// @oagen-ignore-file\n');
+  fs.writeFileSync(path.join(root, 'src', 'api-keys', 'api-keys.ts'), EXISTING_API_KEYS_CLASS);
+  execFileSync('git', ['init'], { cwd: root, stdio: 'ignore' });
+  execFileSync('git', ['add', 'src'], { cwd: root, stdio: 'ignore' });
+  return root;
+}
+
+function apiKeysBaselineSurface(): unknown {
+  const method = (name: string) => [{ name, params: [], returnType: 'Promise<unknown>', async: true }];
+  return {
+    classes: {
+      ApiKeys: {
+        methods: {
+          createValidation: method('createValidation'),
+          deleteApiKey: method('deleteApiKey'),
+          listOrganizationApiKeys: method('listOrganizationApiKeys'),
+          createOrganizationApiKey: method('createOrganizationApiKey'),
+        },
+      },
+    },
+  };
+}
+
+describe('mergeGeneratedClassMethodsIntoExisting', () => {
+  const existingFile = [
+    '// This file is auto-generated by oagen. Do not edit.',
+    '',
+    "import { WorkOS } from '../workos';",
+    'import {',
+    '  ValidateApiKeyOptions,',
+    "} from './interfaces/validate-api-key.interface';",
+    '',
+    'export class ApiKeys {',
+    '  constructor(private readonly workos: WorkOS) {}',
+    '',
+    '  async createValidation(payload: ValidateApiKeyOptions): Promise<unknown> {',
+    "    return this.workos.post('/api_keys/validations', payload);",
+    '  }',
+    '',
+    '  async deleteApiKey(id: string): Promise<void> {',
+    '    await this.workos.delete(`/api_keys/${id}`);',
+    '  }',
+    '}',
+    '',
+  ].join('\n');
+
+  const partialEmission = [
+    '// This file is auto-generated by oagen. Do not edit.',
+    '',
+    "import type { WorkOS } from '../workos';",
+    "import { deserializeApiKeyExpire } from './serializers/api-key-expire.serializer';",
+    '',
+    'export class ApiKeys {',
+    '  constructor(private readonly workos: WorkOS) {}',
+    '',
+    '  /** Expire an API key. */',
+    '  async createApiKeyExpire(id: string): Promise<void> {',
+    '    await this.workos.post(`/api_keys/${encodeURIComponent(id)}/expire`, {});',
+    '  }',
+    '}',
+    '',
+  ].join('\n');
+
+  it('returns null when the generated class covers every existing method', () => {
+    // Identical emission: nothing dropped → caller may overwrite.
+    expect(mergeGeneratedClassMethodsIntoExisting(existingFile, existingFile)).toBeNull();
+    // Superset emission (every existing method plus a new one): full
+    // regenerations must keep flowing through the overwrite path so spec
+    // renames and emitter improvements propagate.
+    const supersetEmission = existingFile.replace(
+      '  async deleteApiKey(id: string): Promise<void> {',
+      [
+        '  async createApiKeyExpire(id: string): Promise<void> {',
+        '    return;',
+        '  }',
+        '',
+        '  async deleteApiKey(id: string): Promise<void> {',
+      ].join('\n'),
+    );
+    expect(mergeGeneratedClassMethodsIntoExisting(existingFile, supersetEmission)).toBeNull();
+  });
+
+  it('returns null for files without classes (models, serializers)', () => {
+    const iface = 'export interface ApiKey {\n  id: string;\n}\n';
+    expect(mergeGeneratedClassMethodsIntoExisting(iface, 'export interface ApiKey {\n  name: string;\n}\n')).toBeNull();
+  });
+
+  it('appends generated-only methods and missing imports, preserving the rest verbatim', () => {
+    const merged = mergeGeneratedClassMethodsIntoExisting(existingFile, partialEmission);
+    expect(merged).not.toBeNull();
+    // Existing methods and their bodies survive byte-for-byte.
+    expect(merged).toContain('async createValidation(payload: ValidateApiKeyOptions): Promise<unknown> {');
+    expect(merged).toContain('await this.workos.delete(`/api_keys/${id}`);');
+    // The new method (with its doc comment) is appended inside the class.
+    expect(merged).toContain('/** Expire an API key. */');
+    expect(merged).toContain('async createApiKeyExpire(id: string): Promise<void> {');
+    expect(merged!.indexOf('createApiKeyExpire')).toBeGreaterThan(merged!.indexOf('deleteApiKey'));
+    // The class still closes exactly once after the appended method.
+    expect(merged!.trimEnd().endsWith('}')).toBe(true);
+    // Imports: the serializer import is added once; WorkOS is NOT re-imported
+    // even though the generated file used the `import type` form.
+    expect(merged!.match(/deserializeApiKeyExpire/g)).toHaveLength(1);
+    expect(merged!.match(/from '\.\.\/workos'/g)).toHaveLength(1);
+    // Multi-line existing import block is untouched.
+    expect(merged).toContain("} from './interfaces/validate-api-key.interface';");
+  });
+
+  it('extracts a generated method whose body has an inner brace at method-close indent', () => {
+    // The `};` closing the inner object literal sits at exactly two-space
+    // indent — the old "first two-space-indented `}`" heuristic clipped the
+    // method there, dropping the trailing statement and the real closing brace
+    // and appending a truncated, unbalanced block. Brace-depth tracking keeps
+    // the whole method.
+    const partialWithInnerBrace = [
+      '// This file is auto-generated by oagen. Do not edit.',
+      '',
+      "import type { WorkOS } from '../workos';",
+      '',
+      'export class ApiKeys {',
+      '  constructor(private readonly workos: WorkOS) {}',
+      '',
+      '  async createWithMetadata(id: string): Promise<void> {',
+      '    const payload = {',
+      '    nested: { a: 1 },',
+      '  };',
+      '    await this.workos.post(`/api_keys/${id}/meta`, payload);',
+      '  }',
+      '}',
+      '',
+    ].join('\n');
+
+    const merged = mergeGeneratedClassMethodsIntoExisting(existingFile, partialWithInnerBrace);
+    expect(merged).not.toBeNull();
+    // The full method body survives — including the statement AFTER the inner
+    // `};` that the old heuristic would have truncated.
+    expect(merged).toContain('nested: { a: 1 },');
+    expect(merged).toContain('await this.workos.post(`/api_keys/${id}/meta`, payload);');
+    // Existing methods are still intact and the class closes exactly once
+    // (a standalone `}` at column 0 — not the multi-line import's `} from …`).
+    expect(merged).toContain('async deleteApiKey(id: string): Promise<void> {');
+    expect(merged!.match(/^}$/gm)).toHaveLength(1);
+  });
+
+  it('extracts a generated method whose comments and strings contain stray braces', () => {
+    // A `}` inside a line comment, a single-quoted string, and a template
+    // literal must NOT close the method block. Raw character counting (counting
+    // every `}` regardless of context) would clip the method at the comment's
+    // `}`, dropping the rest of the body and the real closing brace; the
+    // string/template/comment-aware scan keeps the whole method.
+    const partialWithStrayBraces = [
+      '// This file is auto-generated by oagen. Do not edit.',
+      '',
+      "import type { WorkOS } from '../workos';",
+      '',
+      'export class ApiKeys {',
+      '  constructor(private readonly workos: WorkOS) {}',
+      '',
+      '  async danger(id: string): Promise<void> {',
+      '    // early return path closes here }',
+      "    const marker = 'closing brace: }';",
+      '    await this.workos.post(`/api_keys/${id}`, { note: marker });',
+      '  }',
+      '}',
+      '',
+    ].join('\n');
+
+    const merged = mergeGeneratedClassMethodsIntoExisting(existingFile, partialWithStrayBraces);
+    expect(merged).not.toBeNull();
+    // Every line of the new method body survives the stray braces.
+    expect(merged).toContain('// early return path closes here }');
+    expect(merged).toContain("const marker = 'closing brace: }';");
+    expect(merged).toContain('await this.workos.post(`/api_keys/${id}`, { note: marker });');
+    // Existing methods are intact and the class still closes exactly once.
+    expect(merged).toContain('async deleteApiKey(id: string): Promise<void> {');
+    expect(merged!.match(/^}$/gm)).toHaveLength(1);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Alias-form re-exports must not trigger structural renames on regeneration.
+//
+// When `export type ApiKeyOwner = OrganizationApiKeyWithValueOwner;` is on
+// disk, the engine's api-surface puts ApiKeyOwner under typeAliases (no
+// fields), so its structural matcher cannot claim the exact name and its
+// Jaccard fallback "renames" the IR model to whatever interface looks
+// similar (here: UserApiKeyOwner). The emitter must treat an exactly-declared
+// name — interface OR alias — as preempting that structural rename, so the
+// emission is identical whether the file on disk holds the alias form or the
+// materialized form.
+// ---------------------------------------------------------------------------
+
+const OWNER_FIELDS = [
+  { name: 'user', type: { kind: 'primitive', type: 'string' }, required: true },
+  { name: 'service_account', type: { kind: 'primitive', type: 'string' }, required: true },
+  // New spec field: forces re-emission against a baseline that lacks it.
+  { name: 'expires_at', type: { kind: 'primitive', type: 'string' }, required: false },
+] as const;
+
+function ownerModels() {
+  // Canonical first: pass-1 fingerprint dedup maps the later twin onto it.
+  return [
+    { name: 'OrganizationApiKeyWithValueOwner', fields: [...OWNER_FIELDS] },
+    { name: 'ApiKeyOwner', fields: [...OWNER_FIELDS] },
+  ];
+}
+
+function ownerSpec(): ApiSpec {
+  return {
+    ...baseSpec,
+    models: ownerModels() as ApiSpec['models'],
+    services: [
+      {
+        name: 'ApiKeys',
+        operations: [
+          {
+            ...makeOp('getApiKeyOwner', 'get', '/api_keys/owner'),
+            response: { kind: 'model', name: 'ApiKeyOwner' },
+          },
+          {
+            ...makeOp('getOrganizationApiKeyOwner', 'get', '/organizations/{id}/api_keys/owner'),
+            response: { kind: 'model', name: 'OrganizationApiKeyWithValueOwner' },
+          },
+        ],
+      },
+    ],
+  };
+}
+
+const CANONICAL_OWNER_FILE = [
+  '// This file is auto-generated by oagen. Do not edit.',
+  '',
+  'export interface OrganizationApiKeyWithValueOwner {',
+  '  user: string;',
+  '  serviceAccount: string;',
+  '}',
+  '',
+  'export interface OrganizationApiKeyWithValueOwnerResponse {',
+  '  user: string;',
+  '  service_account: string;',
+  '}',
+  '',
+].join('\n');
+
+const ALIAS_OWNER_FILE = [
+  '// This file is auto-generated by oagen. Do not edit.',
+  '',
+  'import type {',
+  '  OrganizationApiKeyWithValueOwner,',
+  '  OrganizationApiKeyWithValueOwnerResponse,',
+  "} from './organization-api-key-with-value-owner.interface';",
+  '',
+  'export type ApiKeyOwner = OrganizationApiKeyWithValueOwner;',
+  'export type ApiKeyOwnerResponse = OrganizationApiKeyWithValueOwnerResponse;',
+  '',
+].join('\n');
+
+const MATERIALIZED_OWNER_FILE = [
+  '// This file is auto-generated by oagen. Do not edit.',
+  '',
+  'export interface ApiKeyOwner {',
+  '  user: string;',
+  '  serviceAccount: string;',
+  '}',
+  '',
+  'export interface ApiKeyOwnerResponse {',
+  '  user: string;',
+  '  service_account: string;',
+  '}',
+  '',
+].join('\n');
+
+function createOwnerSdkRoot(form: 'alias' | 'materialized'): string {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), `node-alias-${form}-`));
+  const ifaceDir = path.join(root, 'src', 'api-keys', 'interfaces');
+  const userDir = path.join(root, 'src', 'user-api-keys', 'interfaces');
+  fs.mkdirSync(ifaceDir, { recursive: true });
+  fs.mkdirSync(userDir, { recursive: true });
+  fs.writeFileSync(path.join(root, 'src', 'workos.ts'), '// @oagen-ignore-file\nexport class WorkOS {}\n');
+  fs.writeFileSync(path.join(root, 'src', 'index.ts'), '// @oagen-ignore-file\n');
+  fs.writeFileSync(path.join(ifaceDir, 'organization-api-key-with-value-owner.interface.ts'), CANONICAL_OWNER_FILE);
+  fs.writeFileSync(
+    path.join(ifaceDir, 'api-key-owner.interface.ts'),
+    form === 'alias' ? ALIAS_OWNER_FILE : MATERIALIZED_OWNER_FILE,
+  );
+  fs.writeFileSync(
+    path.join(userDir, 'user-api-key-owner.interface.ts'),
+    [
+      '// This file is auto-generated by oagen. Do not edit.',
+      '',
+      'export interface UserApiKeyOwner {',
+      '  user: string;',
+      '}',
+      '',
+    ].join('\n'),
+  );
+  execFileSync('git', ['init'], { cwd: root, stdio: 'ignore' });
+  execFileSync('git', ['add', 'src'], { cwd: root, stdio: 'ignore' });
+  return root;
+}
+
+function ownerCtx(root: string, form: 'alias' | 'materialized'): EmitterContext {
+  const ifaceField = (fieldKey: string) => ({ [fieldKey]: { type: 'string', optional: false } });
+  const interfaces: Record<string, unknown> = {
+    OrganizationApiKeyWithValueOwner: {
+      fields: { ...ifaceField('user'), ...ifaceField('serviceAccount') },
+      sourceFile: 'src/api-keys/interfaces/organization-api-key-with-value-owner.interface.ts',
+    },
+    OrganizationApiKeyWithValueOwnerResponse: {
+      fields: { ...ifaceField('user'), ...ifaceField('service_account') },
+      sourceFile: 'src/api-keys/interfaces/organization-api-key-with-value-owner.interface.ts',
+    },
+    UserApiKeyOwner: {
+      fields: { ...ifaceField('user') },
+      sourceFile: 'src/user-api-keys/interfaces/user-api-key-owner.interface.ts',
+    },
+  };
+  const typeAliases: Record<string, unknown> = {};
+  const modelNameByIR = new Map<string, string>([
+    ['OrganizationApiKeyWithValueOwner', 'OrganizationApiKeyWithValueOwner'],
+  ]);
+  if (form === 'alias') {
+    typeAliases.ApiKeyOwner = {
+      value: 'OrganizationApiKeyWithValueOwner',
+      sourceFile: 'src/api-keys/interfaces/api-key-owner.interface.ts',
+    };
+    typeAliases.ApiKeyOwnerResponse = {
+      value: 'OrganizationApiKeyWithValueOwnerResponse',
+      sourceFile: 'src/api-keys/interfaces/api-key-owner.interface.ts',
+    };
+    // The engine's exact-name pass cannot see aliases (no fields), so its
+    // Jaccard fallback structurally "renames" the IR model.
+    modelNameByIR.set('ApiKeyOwner', 'UserApiKeyOwner');
+  } else {
+    interfaces.ApiKeyOwner = {
+      fields: { ...ifaceField('user'), ...ifaceField('serviceAccount') },
+      sourceFile: 'src/api-keys/interfaces/api-key-owner.interface.ts',
+    };
+    interfaces.ApiKeyOwnerResponse = {
+      fields: { ...ifaceField('user'), ...ifaceField('service_account') },
+      sourceFile: 'src/api-keys/interfaces/api-key-owner.interface.ts',
+    };
+    // Materialized interface → exact-name identity match.
+    modelNameByIR.set('ApiKeyOwner', 'ApiKeyOwner');
+  }
+
+  const spec = ownerSpec();
+  return {
+    ...baseCtx,
+    spec,
+    outputDir: root,
+    apiSurface: { classes: {}, interfaces, typeAliases, enums: {}, exports: {} },
+    overlayLookup: {
+      methodByOperation: new Map(),
+      interfaceByName: new Map(),
+      modelNameByIR,
+    },
+  } as unknown as EmitterContext;
+}
+
+describe('alias-form model files across regenerations', () => {
+  it('does not invent renamed duplicate declarations when the alias form is on disk', () => {
+    const root = createOwnerSdkRoot('alias');
+    try {
+      const ctx = ownerCtx(root, 'alias');
+      const result = nodeEmitter.generateModels(ctx.spec.models, ctx);
+
+      // No emitted file may declare or re-export under the structurally
+      // renamed name — UserApiKeyOwner belongs to a different model.
+      for (const file of result) {
+        expect(file.content).not.toContain('UserApiKeyOwner');
+      }
+
+      // The alias file keeps its exact-name alias form.
+      const aliasFile = result.find((f) => f.path === 'src/api-keys/interfaces/api-key-owner.interface.ts');
+      if (aliasFile) {
+        expect(aliasFile.content).toContain('export type ApiKeyOwner = OrganizationApiKeyWithValueOwner;');
+      }
+    } finally {
+      fs.rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  it('emits the same files whether the alias or the materialized form is on disk', () => {
+    const aliasRoot = createOwnerSdkRoot('alias');
+    const materializedRoot = createOwnerSdkRoot('materialized');
+    try {
+      const aliasCtx = ownerCtx(aliasRoot, 'alias');
+      const materializedCtx = ownerCtx(materializedRoot, 'materialized');
+      const aliasResult = nodeEmitter.generateModels(aliasCtx.spec.models, aliasCtx);
+      const materializedResult = nodeEmitter.generateModels(materializedCtx.spec.models, materializedCtx);
+
+      const byPath = (files: typeof aliasResult) => new Map(files.map((f) => [f.path, f.content]));
+      expect(byPath(aliasResult)).toEqual(byPath(materializedResult));
+    } finally {
+      fs.rmSync(aliasRoot, { recursive: true, force: true });
+      fs.rmSync(materializedRoot, { recursive: true, force: true });
+    }
+  });
+
+  it('emits byte-identical output for the same input twice', () => {
+    const rootA = createOwnerSdkRoot('alias');
+    const rootB = createOwnerSdkRoot('alias');
+    try {
+      const first = nodeEmitter.generateModels(ownerSpec().models, ownerCtx(rootA, 'alias'));
+      const second = nodeEmitter.generateModels(ownerSpec().models, ownerCtx(rootB, 'alias'));
+      expect(first.map((f) => [f.path, f.content])).toEqual(second.map((f) => [f.path, f.content]));
+    } finally {
+      fs.rmSync(rootA, { recursive: true, force: true });
+      fs.rmSync(rootB, { recursive: true, force: true });
+    }
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Structural matching must be injective end-to-end (workos-node AuditLogs
+// regression): the spec has two near-identical models, AuditLogEventActor and
+// AuditLogEventTarget, and the live SDK declares a hand-written AuditLogActor
+// with the same shape. The structural fallback mapped BOTH IR models onto
+// AuditLogActor, so from regen round 2 onward
+// audit-log-event-target.interface.ts was rewritten declaring
+// `export interface AuditLogActor` (file stem and declaration disagree), with
+// two serializeAuditLogActor definitions across different files. Exactly one
+// IR model may claim a live name; the loser keeps its IR-derived name and its
+// file stem agrees with its declaration.
+// ---------------------------------------------------------------------------
+
+const AUDIT_SHAPE = [
+  { name: 'id', type: { kind: 'primitive', type: 'string' }, required: false },
+  { name: 'name', type: { kind: 'primitive', type: 'string' }, required: true },
+  { name: 'type', type: { kind: 'primitive', type: 'string' }, required: false },
+  { name: 'metadata', type: { kind: 'primitive', type: 'string' }, required: false },
+] as const;
+
+function auditSpec(): ApiSpec {
+  return {
+    ...baseSpec,
+    models: [
+      // One extra spec field each (absent from baseline) forces re-emission;
+      // differing extras keep the structural-fingerprint dedup out of play —
+      // this is the "near-identical shapes" case from the incident.
+      {
+        name: 'AuditLogEventActor',
+        fields: [...AUDIT_SHAPE, { name: 'ip_address', type: { kind: 'primitive', type: 'string' }, required: false }],
+      },
+      {
+        name: 'AuditLogEventTarget',
+        fields: [...AUDIT_SHAPE, { name: 'domain', type: { kind: 'primitive', type: 'string' }, required: false }],
+      },
+    ] as ApiSpec['models'],
+    services: [
+      {
+        name: 'AuditLogs',
+        operations: [
+          {
+            ...makeOp('getAuditLogEventActor', 'get', '/audit_logs/events/actor'),
+            response: { kind: 'model', name: 'AuditLogEventActor' },
+          },
+          {
+            ...makeOp('getAuditLogEventTarget', 'get', '/audit_logs/events/target'),
+            response: { kind: 'model', name: 'AuditLogEventTarget' },
+          },
+        ],
+      },
+    ],
+  };
+}
+
+const HAND_WRITTEN_ACTOR_FILE = [
+  'export interface AuditLogActor {',
+  '  id?: string;',
+  '  name: string;',
+  '  type?: string;',
+  '  metadata?: string;',
+  '}',
+  '',
+].join('\n');
+
+// The observed bad round-1 output: the IR-stem file carries the OTHER
+// model's resolved name.
+function badAutogenFile(): string {
+  return [
+    '// This file is auto-generated by oagen. Do not edit.',
+    '',
+    'export interface AuditLogActor {',
+    '  id?: string;',
+    '  name: string;',
+    '  type?: string;',
+    '  metadata?: string;',
+    '}',
+    '',
+    'export interface AuditLogActorResponse {',
+    '  id?: string;',
+    '  name: string;',
+    '  type?: string;',
+    '  metadata?: string;',
+    '}',
+    '',
+  ].join('\n');
+}
+
+function createAuditSdkRoot(): string {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'node-audit-injective-'));
+  const ifaceDir = path.join(root, 'src', 'audit-logs', 'interfaces');
+  fs.mkdirSync(ifaceDir, { recursive: true });
+  fs.writeFileSync(path.join(root, 'src', 'workos.ts'), '// @oagen-ignore-file\nexport class WorkOS {}\n');
+  fs.writeFileSync(path.join(root, 'src', 'index.ts'), '// @oagen-ignore-file\n');
+  fs.writeFileSync(path.join(ifaceDir, 'audit-log-actor.interface.ts'), HAND_WRITTEN_ACTOR_FILE);
+  fs.writeFileSync(path.join(ifaceDir, 'audit-log-event-actor.interface.ts'), badAutogenFile());
+  fs.writeFileSync(path.join(ifaceDir, 'audit-log-event-target.interface.ts'), badAutogenFile());
+  execFileSync('git', ['init'], { cwd: root, stdio: 'ignore' });
+  execFileSync('git', ['add', 'src'], { cwd: root, stdio: 'ignore' });
+  return root;
+}
+
+function auditCtx(root: string): EmitterContext {
+  const optionalString = { type: 'string', optional: true };
+  return {
+    ...baseCtx,
+    spec: auditSpec(),
+    outputDir: root,
+    apiSurface: {
+      classes: {},
+      interfaces: {
+        AuditLogActor: {
+          fields: {
+            id: optionalString,
+            name: { type: 'string', optional: false },
+            type: optionalString,
+            metadata: optionalString,
+          },
+          sourceFile: 'src/audit-logs/interfaces/audit-log-actor.interface.ts',
+        },
+      },
+      typeAliases: {},
+      enums: {},
+      exports: {},
+    },
+    overlayLookup: {
+      methodByOperation: new Map(),
+      interfaceByName: new Map(),
+      // The non-injective overlay state observed in the incident: both IR
+      // models structurally matched onto the one hand-written declaration.
+      modelNameByIR: new Map([
+        ['AuditLogEventActor', 'AuditLogActor'],
+        ['AuditLogEventTarget', 'AuditLogActor'],
+      ]),
+    },
+  } as unknown as EmitterContext;
+}
+
+describe('structural-match injectivity across emitted model files', () => {
+  it('gives the contested live name to one model; the other keeps its IR name and stem', () => {
+    const root = createAuditSdkRoot();
+    try {
+      const ctx = auditCtx(root);
+      const result = nodeEmitter.generateModels(ctx.spec.models, ctx);
+
+      // The target file must declare ITS OWN derived name — never the
+      // actor's claimed name.
+      const targetFile = result.find((f) => f.path === 'src/audit-logs/interfaces/audit-log-event-target.interface.ts');
+      expect(targetFile).toBeDefined();
+      expect(targetFile!.content).toContain('export interface AuditLogEventTarget {');
+      expect(targetFile!.content).toContain('export interface AuditLogEventTargetResponse {');
+      expect(targetFile!.content).not.toContain('AuditLogActor');
+
+      // No exported declaration may be emitted by two different files —
+      // the incident produced two serializeAuditLogActor definitions.
+      const declared = new Map<string, string>();
+      for (const file of result) {
+        for (const m of file.content.matchAll(/^export (?:interface|class|function|const) (\w+)/gm)) {
+          expect(
+            declared.get(m[1]),
+            `duplicate declaration of ${m[1]} in ${declared.get(m[1])} and ${file.path}`,
+          ).toBeUndefined();
+          declared.set(m[1], file.path);
+        }
+      }
+
+      // Sanity invariant: a model file's declaration matches its stem-derived
+      // name unless that name is the unique claimed structural rename. Here
+      // the actor claims AuditLogActor; every other interface file must
+      // declare exactly its stem's PascalCase name.
+      for (const file of result) {
+        const stemMatch = file.path.match(/\/([^/]+)\.interface\.ts$/);
+        if (!stemMatch) continue;
+        if (file.path.endsWith('audit-log-event-actor.interface.ts')) continue;
+        const pascalStem = stemMatch[1]
+          .split('-')
+          .map((p) => p.charAt(0).toUpperCase() + p.slice(1))
+          .join('');
+        for (const m of file.content.matchAll(/^export interface (\w+)/gm)) {
+          expect([pascalStem, `${pascalStem}Response`]).toContain(m[1]);
+        }
+      }
+    } finally {
+      fs.rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  it('emits identical, injective output on repeated regeneration', () => {
+    const rootA = createAuditSdkRoot();
+    const rootB = createAuditSdkRoot();
+    try {
+      const first = nodeEmitter.generateModels(auditSpec().models, auditCtx(rootA));
+      const second = nodeEmitter.generateModels(auditSpec().models, auditCtx(rootB));
+      expect(first.map((f) => [f.path, f.content])).toEqual(second.map((f) => [f.path, f.content]));
+    } finally {
+      fs.rmSync(rootA, { recursive: true, force: true });
+      fs.rmSync(rootB, { recursive: true, force: true });
+    }
+  });
+});
+
+describe('non-owned autogen resource regeneration', () => {
+  const apiKeysService: Service = {
+    name: 'ApiKeys',
+    operations: [
+      makeOp('createValidation', 'post', '/api_keys/validations'),
+      makeOp('deleteApiKey', 'delete', '/api_keys/{id}'),
+      makeOp('listOrganizationApiKeys', 'get', '/organizations/{id}/api_keys'),
+      makeOp('createOrganizationApiKey', 'post', '/organizations/{id}/api_keys'),
+      makeOp('createApiKeyExpire', 'post', '/api_keys/{id}/expire'),
+    ],
+  };
+
+  it('keeps every existing method and appends the new operation', () => {
+    const root = createApiKeysSdkRoot();
+    try {
+      const spec: ApiSpec = { ...baseSpec, services: [apiKeysService] };
+      const result = nodeEmitter.generateResources(spec.services, {
+        ...baseCtx,
+        spec,
+        outputDir: root,
+        emitterOptions: { adoptMissingServices: true, ownedServices: ['Groups'] },
+        apiSurface: apiKeysBaselineSurface(),
+      } as EmitterContext);
+
+      const file = result.find((f) => f.path === 'src/api-keys/api-keys.ts');
+      expect(file).toBeDefined();
+      // All four pre-existing methods survive the regeneration...
+      expect(file!.content).toContain('async createValidation(');
+      expect(file!.content).toContain('async deleteApiKey(');
+      expect(file!.content).toContain('async listOrganizationApiKeys(');
+      expect(file!.content).toContain('async createOrganizationApiKey(');
+      // ...their bodies are preserved textually...
+      expect(file!.content).toContain('await this.workos.delete(`/api_keys/${id}`);');
+      // ...and the new operation is appended.
+      expect(file!.content).toContain('async createApiKeyExpire(');
+      // The existing import block is preserved.
+      expect(file!.content).toContain("} from './interfaces/validate-api-key.interface';");
+    } finally {
+      fs.rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  it('still fully overwrites when the emission covers every existing method', () => {
+    const root = createApiKeysSdkRoot();
+    try {
+      // No apiSurface baseline → resources.ts emits the full class; the
+      // overwrite path must stay intact so emitter improvements propagate.
+      const spec: ApiSpec = { ...baseSpec, services: [apiKeysService] };
+      const result = nodeEmitter.generateResources(spec.services, {
+        ...baseCtx,
+        spec,
+        outputDir: root,
+        emitterOptions: { adoptMissingServices: true },
+      } as EmitterContext);
+
+      const file = result.find((f) => f.path === 'src/api-keys/api-keys.ts');
+      expect(file).toBeDefined();
+      expect(file!.overwriteExisting).toBe(true);
+      // Full regeneration: generated content replaces the file wholesale.
+      expect(file!.content).toContain('async createApiKeyExpire(');
+      expect(file!.content).not.toContain('await this.workos.delete(`/api_keys/${id}`);');
+    } finally {
+      fs.rmSync(root, { recursive: true, force: true });
+    }
+  });
+});