@workos/oagen-emitters 0.12.1 → 0.12.2

package/test/node/models.test.ts

@@ -1,7 +1,14 @@
 import { describe, it, expect } from 'vitest';
-import { generateModels } from '../../src/node/models.js';
-import type { EmitterContext, ApiSpec, Model, Service } from '@workos/oagen';
+import type { EmitterContext, ApiSpec, Model } from '@workos/oagen';
 import { defaultSdkBehavior } from '@workos/oagen';
+import { generateModels, generateSerializers } from '../../src/node/models.js';
+import { nodeEmitter } from '../../src/node/index.js';
+import { buildLiveSurface, emptyLiveSurface, setActiveLiveSurface } from '../../src/node/live-surface.js';
+import { setBaselineInterfaceNames, setBaselineSerializedNames } from '../../src/node/naming.js';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { execFileSync } from 'node:child_process';
 
 const emptySpec: ApiSpec = {
   name: 'Test',
@@ -19,912 +26,536 @@ const ctx: EmitterContext = {
   spec: emptySpec,
 };
 
+function makeSpec(models: Model[], services?: any[]): ApiSpec {
+  return {
+    ...emptySpec,
+    models,
+    services: services ?? [
+      {
+        name: 'Organizations',
+        operations: [
+          {
+            name: 'getOrganization',
+            httpMethod: 'get',
+            path: '/organizations/{id}',
+            pathParams: [{ name: 'id', type: { kind: 'primitive', type: 'string' }, required: true }],
+            queryParams: [],
+            headerParams: [],
+            response: { kind: 'model', name: 'Organization' },
+            errors: [],
+            injectIdempotencyKey: false,
+          },
+        ],
+      },
+    ],
+  };
+}
+
 describe('generateModels', () => {
   it('returns empty for no models', () => {
     expect(generateModels([], ctx)).toEqual([]);
   });
 
   it('generates domain and response interfaces for a model', () => {
-    const service: Service = {
-      name: 'Organizations',
-      operations: [
-        {
-          name: 'getOrganization',
-          httpMethod: 'get',
-          path: '/organizations/{id}',
-          pathParams: [
-            {
-              name: 'id',
-              type: { kind: 'primitive', type: 'string' },
-              required: true,
-            },
-          ],
-          queryParams: [],
-          headerParams: [],
-          response: { kind: 'model', name: 'Organization' },
-          errors: [],
-          injectIdempotencyKey: false,
-        },
-      ],
-    };
-
     const models: Model[] = [
       {
         name: 'Organization',
         fields: [
-          {
-            name: 'id',
-            type: { kind: 'primitive', type: 'string' },
-            required: true,
-          },
-          {
-            name: 'name',
-            type: { kind: 'primitive', type: 'string' },
-            required: true,
-          },
-          {
-            name: 'created_at',
-            type: { kind: 'primitive', type: 'string', format: 'date-time' },
-            required: true,
-          },
+          { name: 'id', type: { kind: 'primitive', type: 'string' }, required: true },
+          { name: 'name', type: { kind: 'primitive', type: 'string' }, required: true },
+          { name: 'created_at', type: { kind: 'primitive', type: 'string', format: 'date-time' }, required: true },
           {
             name: 'external_id',
-            type: {
-              kind: 'nullable',
-              inner: { kind: 'primitive', type: 'string' },
-            },
-            required: false,
+            type: { kind: 'nullable', inner: { kind: 'primitive', type: 'string' } },
+            required: true,
           },
         ],
       },
     ];
 
-    const ctxWithServices: EmitterContext = {
-      ...ctx,
-      spec: { ...emptySpec, services: [service], models },
-    };
+    const spec = makeSpec(models);
+    const ctxWithModels: EmitterContext = { ...ctx, spec };
+    const result = generateModels(models, ctxWithModels);
 
-    const files = generateModels(models, ctxWithServices);
-    expect(files.length).toBe(1);
-    expect(files[0].path).toBe('src/organizations/interfaces/organization.interface.ts');
+    expect(result.length).toBeGreaterThan(0);
+    const file = result[0];
+    expect(file.path).toBe('src/organizations/interfaces/organization.interface.ts');
 
     // Domain interface has camelCase fields
-    expect(files[0].content).toContain('export interface Organization {');
-    expect(files[0].content).toContain('  id: string;');
-    expect(files[0].content).toContain('  name: string;');
-    expect(files[0].content).toContain('  createdAt: Date;');
-    expect(files[0].content).toContain('  externalId?: string | null;');
-
-    // Response interface has snake_case fields
-    expect(files[0].content).toContain('export interface OrganizationResponse {');
-    expect(files[0].content).toContain('  created_at: string;');
-    expect(files[0].content).toContain('  external_id?: string | null;');
+    expect(file.content).toContain('export interface Organization {');
+    expect(file.content).toContain('id: string;');
+    expect(file.content).toContain('name: string;');
+    expect(file.content).toContain('createdAt: Date;');
+    expect(file.content).toContain('externalId: string | null;');
+
+    // Wire interface has snake_case fields
+    expect(file.content).toContain('export interface OrganizationResponse {');
+    expect(file.content).toContain('created_at: string;');
+    expect(file.content).toContain('external_id: string | null;');
   });
 
   it('generates imports for referenced models', () => {
-    const service: Service = {
-      name: 'Organizations',
-      operations: [
-        {
-          name: 'getOrganization',
-          httpMethod: 'get',
-          path: '/organizations/{id}',
-          pathParams: [
-            {
-              name: 'id',
-              type: { kind: 'primitive', type: 'string' },
-              required: true,
-            },
-          ],
-          queryParams: [],
-          headerParams: [],
-          response: { kind: 'model', name: 'Organization' },
-          errors: [],
-          injectIdempotencyKey: false,
-        },
-      ],
-    };
-
     const models: Model[] = [
       {
         name: 'Organization',
         fields: [
-          {
-            name: 'id',
-            type: { kind: 'primitive', type: 'string' },
-            required: true,
-          },
-          {
-            name: 'domains',
-            type: {
-              kind: 'array',
-              items: { kind: 'model', name: 'OrganizationDomain' },
-            },
-            required: true,
-          },
+          { name: 'id', type: { kind: 'primitive', type: 'string' }, required: true },
+          { name: 'domain', type: { kind: 'model', name: 'OrganizationDomain' }, required: true },
         ],
       },
       {
         name: 'OrganizationDomain',
-        fields: [
-          {
-            name: 'id',
-            type: { kind: 'primitive', type: 'string' },
-            required: true,
-          },
-          {
-            name: 'domain',
-            type: { kind: 'primitive', type: 'string' },
-            required: true,
-          },
-        ],
+        fields: [{ name: 'id', type: { kind: 'primitive', type: 'string' }, required: true }],
       },
     ];
 
-    const ctxWithServices: EmitterContext = {
-      ...ctx,
-      spec: { ...emptySpec, services: [service], models },
-    };
-
-    const files = generateModels(models, ctxWithServices);
+    const spec = makeSpec(models);
+    const ctxWithModels: EmitterContext = { ...ctx, spec };
+    const result = generateModels(models, ctxWithModels);
 
-    // Organization file should import OrganizationDomain
-    const orgFile = files.find((f) => f.path.includes('organization.interface.ts'))!;
-    expect(orgFile.content).toContain(
+    const orgFile = result.find((f) => f.path.includes('organization.interface.ts'));
+    expect(orgFile?.content).toContain(
       "import type { OrganizationDomain, OrganizationDomainResponse } from './organization-domain.interface';",
     );
-
-    // Domain interface uses OrganizationDomain[]
-    expect(orgFile.content).toContain('  domains: OrganizationDomain[];');
-
-    // Response interface uses OrganizationDomainResponse[]
-    expect(orgFile.content).toContain('  domains: OrganizationDomainResponse[];');
   });
 
-  it('handles generic type params', () => {
-    const service: Service = {
-      name: 'DirectorySync',
-      operations: [
-        {
-          name: 'getDirectoryUser',
-          httpMethod: 'get',
-          path: '/directory_users/{id}',
-          pathParams: [{ name: 'id', type: { kind: 'primitive', type: 'string' }, required: true }],
-          queryParams: [],
-          headerParams: [],
-          response: { kind: 'model', name: 'DirectoryUser' },
-          errors: [],
-          injectIdempotencyKey: false,
-        },
-      ],
-    };
-
+  it('uses Wire suffix for models already ending in Response', () => {
     const models: Model[] = [
       {
-        name: 'DirectoryUser',
-        typeParams: [
-          {
-            name: 'TCustom',
-            default: {
-              kind: 'map',
-              valueType: { kind: 'primitive', type: 'unknown' },
-            },
-          },
-        ],
-        fields: [
-          {
-            name: 'id',
-            type: { kind: 'primitive', type: 'string' },
-            required: true,
-          },
-        ],
+        name: 'PortalSessionsCreateResponse',
+        fields: [{ name: 'link', type: { kind: 'primitive', type: 'string' }, required: true }],
       },
     ];
 
-    const ctxWithServices: EmitterContext = {
-      ...ctx,
-      spec: { ...emptySpec, services: [service], models },
-    };
-
-    const files = generateModels(models, ctxWithServices);
-    expect(files[0].content).toContain('export interface DirectoryUser<TCustom = Record<string, any>> {');
-    expect(files[0].content).toContain('export interface DirectoryUserResponse<TCustom = Record<string, any>> {');
-  });
-
-  it('uses Wire suffix for models already ending in Response', () => {
-    const service: Service = {
-      name: 'PortalSessions',
-      operations: [
-        {
-          name: 'createPortalSession',
-          httpMethod: 'post',
-          path: '/portal/sessions',
-          pathParams: [],
-          queryParams: [],
-          headerParams: [],
-          response: { kind: 'model', name: 'PortalSessionsCreateResponse' },
-          errors: [],
-          injectIdempotencyKey: false,
-        },
-      ],
-    };
-
-    const models: Model[] = [
+    const spec = makeSpec(models, [
       {
-        name: 'PortalSessionsCreateResponse',
-        fields: [
-          {
-            name: 'link',
-            type: { kind: 'primitive', type: 'string' },
-            required: true,
+        name: 'Portal',
+        operations: [
+          {
+            name: 'createSession',
+            httpMethod: 'post',
+            path: '/portal/sessions',
+            pathParams: [],
+            queryParams: [],
+            headerParams: [],
+            response: { kind: 'model', name: 'PortalSessionsCreateResponse' },
+            errors: [],
+            injectIdempotencyKey: false,
           },
         ],
       },
-    ];
+    ]);
+    const ctxWithModels: EmitterContext = { ...ctx, spec };
+    const result = generateModels(models, ctxWithModels);
 
-    const ctxWithServices: EmitterContext = {
-      ...ctx,
-      spec: { ...emptySpec, services: [service], models },
-    };
-
-    const files = generateModels(models, ctxWithServices);
-    const content = files[0].content;
-
-    // Should use Wire suffix, not ResponseResponse
-    expect(content).toContain('export interface PortalSessionsCreateResponseWire {');
-    expect(content).not.toContain('PortalSessionsCreateResponseResponse');
+    const file = result[0];
+    expect(file.content).toContain('export interface PortalSessionsCreateResponseWire {');
   });
 
   it('renders @deprecated on fields', () => {
-    const service: Service = {
-      name: 'Organizations',
-      operations: [
-        {
-          name: 'getOrganization',
-          httpMethod: 'get',
-          path: '/organizations/{id}',
-          pathParams: [
-            {
-              name: 'id',
-              type: { kind: 'primitive', type: 'string' },
-              required: true,
-            },
-          ],
-          queryParams: [],
-          headerParams: [],
-          response: { kind: 'model', name: 'Organization' },
-          errors: [],
-          injectIdempotencyKey: false,
-        },
-      ],
-    };
-
     const models: Model[] = [
       {
         name: 'Organization',
         fields: [
+          { name: 'id', type: { kind: 'primitive', type: 'string' }, required: true },
+          { name: 'old_field', type: { kind: 'primitive', type: 'string' }, required: false, deprecated: true },
           {
-            name: 'id',
-            type: { kind: 'primitive', type: 'string' },
-            required: true,
-          },
-          {
-            name: 'legacy_slug',
-            type: { kind: 'primitive', type: 'string' },
-            required: false,
-            description: 'Use external_id instead.',
-            deprecated: true,
-          },
-          {
-            name: 'old_field',
+            name: 'legacy',
             type: { kind: 'primitive', type: 'string' },
             required: false,
             deprecated: true,
+            description: 'Use external_id instead.',
           },
         ],
       },
     ];
 
-    const ctxWithServices: EmitterContext = {
-      ...ctx,
-      spec: { ...emptySpec, services: [service], models },
-    };
-
-    const files = generateModels(models, ctxWithServices);
-    const content = files[0].content;
+    const spec = makeSpec(models);
+    const ctxWithModels: EmitterContext = { ...ctx, spec };
+    const result = generateModels(models, ctxWithModels);
 
-    // Field with description + deprecated gets multiline JSDoc
-    expect(content).toContain('  /**\n   * Use external_id instead.\n   * @deprecated\n   */');
-
-    // Field with only deprecated gets single-line JSDoc
-    expect(content).toContain('  /** @deprecated */');
+    expect(result[0].content).toContain('@deprecated');
+    expect(result[0].content).toContain('Use external_id instead.');
   });
 
-  it('renders field-level JSDoc from OpenAPI descriptions', () => {
-    const service: Service = {
-      name: 'Organizations',
-      operations: [
-        {
-          name: 'getOrganization',
-          httpMethod: 'get',
-          path: '/organizations/{id}',
-          pathParams: [
-            {
-              name: 'id',
-              type: { kind: 'primitive', type: 'string' },
-              required: true,
-            },
-          ],
-          queryParams: [],
-          headerParams: [],
-          response: { kind: 'model', name: 'Organization' },
-          errors: [],
-          injectIdempotencyKey: false,
-        },
-      ],
-    };
-
+  it('skips per-domain ListMetadata models', () => {
     const models: Model[] = [
       {
         name: 'Organization',
-        description: 'An organization in the WorkOS system.',
+        fields: [{ name: 'id', type: { kind: 'primitive', type: 'string' }, required: true }],
+      },
+      {
+        name: 'OrganizationListMetadata',
         fields: [
-          {
-            name: 'id',
-            type: { kind: 'primitive', type: 'string' },
-            required: true,
-            description: 'Unique identifier for the organization.',
-          },
-          {
-            name: 'name',
-            type: { kind: 'primitive', type: 'string' },
-            required: true,
-            description: 'The display name of the organization.',
-          },
-          {
-            name: 'created_at',
-            type: { kind: 'primitive', type: 'string', format: 'date-time' },
-            required: true,
-            // No description — should not get JSDoc
-          },
-          {
-            name: 'allow_profiles_outside_organization',
-            type: { kind: 'primitive', type: 'boolean' },
-            required: false,
-            description:
-              'Whether connections within the organization allow profiles\nthat do not have a domain that is verified by the organization.',
-          },
+          { name: 'before', type: { kind: 'nullable', inner: { kind: 'primitive', type: 'string' } }, required: false },
+          { name: 'after', type: { kind: 'nullable', inner: { kind: 'primitive', type: 'string' } }, required: false },
         ],
       },
     ];
 
-    const ctxWithServices: EmitterContext = {
-      ...ctx,
-      spec: { ...emptySpec, services: [service], models },
-    };
+    const spec = makeSpec(models);
+    const ctxWithModels: EmitterContext = { ...ctx, spec };
+    const result = generateModels(models, ctxWithModels);
 
-    const files = generateModels(models, ctxWithServices);
-    const content = files[0].content;
+    expect(result.every((f) => !f.path.includes('list-metadata'))).toBe(true);
+  });
 
-    // Model-level JSDoc is emitted
-    expect(content).toContain('/** An organization in the WorkOS system. */');
+  it('handles generic type params', () => {
+    const models: Model[] = [
+      {
+        name: 'DirectoryUser',
+        typeParams: [{ name: 'TCustom', default: { kind: 'map', valueType: { kind: 'primitive', type: 'unknown' } } }],
+        fields: [{ name: 'id', type: { kind: 'primitive', type: 'string' }, required: true }],
+      },
+    ];
 
-    // Fields with description get per-field JSDoc
-    expect(content).toContain('/** Unique identifier for the organization. */');
-    expect(content).toContain('/** The display name of the organization. */');
+    const spec = makeSpec(models, [
+      {
+        name: 'DirectorySync',
+        operations: [
+          {
+            name: 'getUser',
+            httpMethod: 'get',
+            path: '/directory_users/{id}',
+            pathParams: [{ name: 'id', type: { kind: 'primitive', type: 'string' }, required: true }],
+            queryParams: [],
+            headerParams: [],
+            response: { kind: 'model', name: 'DirectoryUser' },
+            errors: [],
+            injectIdempotencyKey: false,
+          },
+        ],
+      },
+    ]);
+    const ctxWithModels: EmitterContext = { ...ctx, spec };
+    const result = generateModels(models, ctxWithModels);
 
-    // Multiline description renders correctly
-    expect(content).toContain(
-      '  /**\n   * Whether connections within the organization allow profiles\n   * that do not have a domain that is verified by the organization.\n   */',
-    );
+    expect(result[0].content).toContain('export interface DirectoryUser<TCustom = Record<string, any>>');
+  });
 
-    // Field without description does NOT get JSDoc
-    const lines = content.split('\n');
-    const createdAtIdx = lines.findIndex((l) => l.includes('createdAt'));
-    expect(createdAtIdx).toBeGreaterThan(0);
-    // The line before createdAt should not be a JSDoc closing tag
-    expect(lines[createdAtIdx - 1].trim()).not.toBe('*/');
+  it('does not emit brand-new files into an existing git-tracked SDK', () => {
+    const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'node-emitter-live-'));
+    try {
+      const ifaceDir = path.join(tmpRoot, 'src', 'organizations', 'interfaces');
+      fs.mkdirSync(ifaceDir, { recursive: true });
+      fs.writeFileSync(
+        path.join(ifaceDir, 'organization.interface.ts'),
+        ['export interface Organization {', '  id: string;', '}'].join('\n'),
+      );
+      execFileSync('git', ['init'], { cwd: tmpRoot, stdio: 'ignore' });
+      execFileSync('git', ['add', 'src'], { cwd: tmpRoot, stdio: 'ignore' });
+
+      const models: Model[] = [
+        {
+          name: 'Organization',
+          fields: [
+            { name: 'id', type: { kind: 'primitive', type: 'string' }, required: true },
+            { name: 'domain', type: { kind: 'model', name: 'OrganizationDomain' }, required: false },
+          ],
+        },
+        {
+          name: 'OrganizationDomain',
+          fields: [{ name: 'id', type: { kind: 'primitive', type: 'string' }, required: true }],
+        },
+      ];
+
+      const spec = makeSpec(models);
+      const files = nodeEmitter.generateModels(models, { ...ctx, spec, outputDir: tmpRoot });
+
+      expect(files).toHaveLength(0);
+      expect(files.some((f) => f.path.includes('organization-domain.interface.ts'))).toBe(false);
+      expect(files.some((f) => f.path.includes('/serializers/'))).toBe(false);
+    } finally {
+      fs.rmSync(tmpRoot, { recursive: true, force: true });
+    }
   });
 
-  it('renders readOnly/writeOnly/default annotations', () => {
-    const service: Service = {
-      name: 'Organizations',
-      operations: [
+  it('keeps spec model names for manifest-managed adopted services on rerun', () => {
+    const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'node-adopted-model-rerun-'));
+    try {
+      fs.mkdirSync(path.join(tmpRoot, 'src'), { recursive: true });
+      fs.writeFileSync(path.join(tmpRoot, 'src', 'workos.ts'), '// @oagen-ignore-file\nexport class WorkOS {}\n');
+      fs.writeFileSync(path.join(tmpRoot, 'src', 'index.ts'), '// @oagen-ignore-file\n');
+      fs.mkdirSync(path.join(tmpRoot, 'src', 'connect'), { recursive: true });
+      fs.writeFileSync(
+        path.join(tmpRoot, 'src', 'connect', 'connect.ts'),
+        ['// This file is auto-generated by oagen. Do not edit.', '', 'export class Connect {}'].join('\n'),
+      );
+      execFileSync('git', ['init'], { cwd: tmpRoot, stdio: 'ignore' });
+      execFileSync('git', ['add', 'src/workos.ts', 'src/index.ts'], { cwd: tmpRoot, stdio: 'ignore' });
+
+      const models: Model[] = [
         {
-          name: 'getOrganization',
-          httpMethod: 'get',
-          path: '/organizations/{id}',
-          pathParams: [
+          name: 'CreateM2MApplication',
+          fields: [
+            { name: 'name', type: { kind: 'primitive', type: 'string' }, required: true },
+            { name: 'application_type', type: { kind: 'literal', value: 'm2m' }, required: true },
+          ],
+        },
+      ];
+      const spec = makeSpec(models, [
+        {
+          name: 'Connect',
+          operations: [
             {
-              name: 'id',
-              type: { kind: 'primitive', type: 'string' },
-              required: true,
+              name: 'createApplication',
+              httpMethod: 'post',
+              path: '/connect/applications',
+              pathParams: [],
+              queryParams: [],
+              headerParams: [],
+              requestBody: { kind: 'model', name: 'CreateM2MApplication' },
+              response: { kind: 'primitive', type: 'unknown' },
+              errors: [],
+              injectIdempotencyKey: false,
             },
           ],
-          queryParams: [],
-          headerParams: [],
-          response: { kind: 'model', name: 'Organization' },
-          errors: [],
-          injectIdempotencyKey: false,
         },
-      ],
-    };
+      ]);
+
+      const result = nodeEmitter.generateModels(models, {
+        ...ctx,
+        spec,
+        outputDir: tmpRoot,
+        emitterOptions: { adoptMissingServices: true },
+        priorTargetManifestPaths: new Set(['src/connect/connect.ts']),
+        apiSurface: {
+          language: 'node',
+          extractedFrom: tmpRoot,
+          extractedAt: '2026-05-12T00:00:00Z',
+          classes: {},
+          interfaces: {
+            CreateGroupOptions: {
+              name: 'CreateGroupOptions',
+              fields: { name: { type: 'string', optional: false } },
+              extends: [],
+              sourceFile: 'src/groups/interfaces/create-group-options.interface.ts',
+            },
+          },
+          typeAliases: {},
+          enums: {},
+          exports: {},
+        } as any,
+        overlayLookup: {
+          methodByOperation: new Map(),
+          interfaceByName: new Map(),
+          modelNameByIR: new Map([['CreateM2MApplication', 'CreateGroupOptions']]),
+        } as any,
+      } as EmitterContext);
+
+      const file = result.find((f) => f.path === 'src/connect/interfaces/create-m2m-application.interface.ts');
+      expect(file?.content).toContain('export interface CreateM2MApplication');
+      expect(file?.content).not.toContain('CreateGroupOptions');
+    } finally {
+      fs.rmSync(tmpRoot, { recursive: true, force: true });
+    }
+  });
+});
 
+describe('generateSerializers', () => {
+  it('generates deserializer with camelCase mapping', () => {
     const models: Model[] = [
       {
         name: 'Organization',
         fields: [
-          {
-            name: 'id',
-            type: { kind: 'primitive', type: 'string' },
-            required: true,
-            readOnly: true,
-          },
-          {
-            name: 'secret_key',
-            type: { kind: 'primitive', type: 'string' },
-            required: true,
-            writeOnly: true,
-          },
-          {
-            name: 'status',
-            type: { kind: 'primitive', type: 'string' },
-            required: false,
-            default: 'active',
-          },
+          { name: 'id', type: { kind: 'primitive', type: 'string' }, required: true },
+          { name: 'created_at', type: { kind: 'primitive', type: 'string', format: 'date-time' }, required: true },
         ],
       },
     ];
 
-    const ctxWithServices: EmitterContext = {
-      ...ctx,
-      spec: { ...emptySpec, services: [service], models },
-    };
-
-    const files = generateModels(models, ctxWithServices);
-    const content = files[0].content;
+    const spec = makeSpec(models);
+    const ctxWithModels: EmitterContext = { ...ctx, spec };
+    const result = generateSerializers(models, ctxWithModels);
 
-    // readOnly field gets @readonly JSDoc and readonly TS modifier
-    expect(content).toContain('/** @readonly */');
-    expect(content).toContain('  readonly id: string;');
-
-    // writeOnly field gets @writeonly JSDoc
-    expect(content).toContain('/** @writeonly */');
-
-    // default field gets @default JSDoc
-    expect(content).toContain('@default "active"');
+    expect(result.length).toBeGreaterThan(0);
+    const file = result[0];
+    expect(file.path).toContain('.serializer.ts');
+    expect(file.content).toContain('deserializeOrganization');
+    expect(file.content).toContain('createdAt: new Date(response.created_at)');
   });
 
-  it('skips per-domain ListMetadata models (Fix #4)', () => {
-    const service: Service = {
-      name: 'Connections',
-      operations: [
-        {
-          name: 'listConnections',
-          httpMethod: 'get',
-          path: '/connections',
-          pathParams: [],
-          queryParams: [],
-          headerParams: [],
-          response: { kind: 'model', name: 'ConnectionList' },
-          errors: [],
-          injectIdempotencyKey: false,
-          pagination: {
-            strategy: 'cursor',
-            param: 'after',
-            itemType: { kind: 'model', name: 'Connection' },
-          },
-        },
-      ],
-    };
-
+  it('generates nested model deserialization', () => {
     const models: Model[] = [
       {
-        name: 'ConnectionListListMetadata',
+        name: 'Organization',
         fields: [
+          { name: 'id', type: { kind: 'primitive', type: 'string' }, required: true },
           {
-            name: 'before',
-            type: {
-              kind: 'nullable',
-              inner: { kind: 'primitive', type: 'string' },
-            },
-            required: false,
-          },
-          {
-            name: 'after',
-            type: {
-              kind: 'nullable',
-              inner: { kind: 'primitive', type: 'string' },
-            },
-            required: false,
+            name: 'domains',
+            type: { kind: 'array', items: { kind: 'model', name: 'OrganizationDomain' } },
+            required: true,
           },
         ],
       },
       {
-        name: 'Connection',
-        fields: [
-          {
-            name: 'id',
-            type: { kind: 'primitive', type: 'string' },
-            required: true,
-          },
-        ],
+        name: 'OrganizationDomain',
+        fields: [{ name: 'id', type: { kind: 'primitive', type: 'string' }, required: true }],
       },
     ];
 
-    const ctxWithServices: EmitterContext = {
-      ...ctx,
-      spec: { ...emptySpec, services: [service], models },
-    };
-
-    const files = generateModels(models, ctxWithServices);
-
-    // The ListMetadata model should be skipped entirely
-    const listMetadataFile = files.find((f) => f.path.includes('list-metadata'));
-    expect(listMetadataFile).toBeUndefined();
+    const spec = makeSpec(models);
+    const ctxWithModels: EmitterContext = { ...ctx, spec };
+    const result = generateSerializers(models, ctxWithModels);
 
-    // The Connection model should still be generated
-    const connectionFile = files.find((f) => f.path.includes('connection.interface.ts'));
-    expect(connectionFile).toBeDefined();
+    const orgSerializer = result.find(
+      (f) => f.path.includes('organization.serializer.ts') && !f.path.includes('domain'),
+    );
+    expect(orgSerializer?.content).toContain('domains: response.domains.map(deserializeOrganizationDomain)');
   });
 
-  it('skips per-domain list wrapper models (Fix #6)', () => {
-    const service: Service = {
-      name: 'Connections',
-      operations: [
-        {
-          name: 'listConnections',
-          httpMethod: 'get',
-          path: '/connections',
-          pathParams: [],
-          queryParams: [],
-          headerParams: [],
-          response: { kind: 'model', name: 'ConnectionList' },
-          errors: [],
-          injectIdempotencyKey: false,
-          pagination: {
-            strategy: 'cursor',
-            param: 'after',
-            itemType: { kind: 'model', name: 'Connection' },
-          },
-        },
-      ],
-    };
-
+  it('preserves null fallback for optional nullable model fields', () => {
     const models: Model[] = [
       {
-        name: 'ConnectionList',
-        fields: [
-          {
-            name: 'object',
-            type: { kind: 'literal', value: 'list' },
-            required: true,
-          },
-          {
-            name: 'data',
-            type: {
-              kind: 'array',
-              items: { kind: 'model', name: 'Connection' },
-            },
-            required: true,
-          },
-          {
-            name: 'list_metadata',
-            type: { kind: 'model', name: 'ConnectionListListMetadata' },
-            required: true,
-          },
-        ],
-      },
-      {
-        name: 'ConnectionListListMetadata',
+        name: 'Organization',
         fields: [
-          {
-            name: 'before',
-            type: {
-              kind: 'nullable',
-              inner: { kind: 'primitive', type: 'string' },
-            },
-            required: false,
-          },
-          {
-            name: 'after',
-            type: {
-              kind: 'nullable',
-              inner: { kind: 'primitive', type: 'string' },
-            },
-            required: false,
-          },
+          { name: 'id', type: { kind: 'primitive', type: 'string' }, required: true },
+          { name: 'parent', type: { kind: 'nullable', inner: { kind: 'model', name: 'ParentOrg' } }, required: false },
         ],
       },
       {
-        name: 'Connection',
-        fields: [
-          {
-            name: 'id',
-            type: { kind: 'primitive', type: 'string' },
-            required: true,
-          },
-        ],
+        name: 'ParentOrg',
+        fields: [{ name: 'id', type: { kind: 'primitive', type: 'string' }, required: true }],
       },
     ];
 
-    const ctxWithServices: EmitterContext = {
-      ...ctx,
-      spec: { ...emptySpec, services: [service], models },
-    };
-
-    const files = generateModels(models, ctxWithServices);
-
-    // The list wrapper model should be skipped
-    const listFile = files.find((f) => f.path.includes('connection-list.interface.ts'));
-    expect(listFile).toBeUndefined();
-
-    // The ListMetadata model should also be skipped
-    const listMetadataFile = files.find((f) => f.path.includes('list-metadata'));
-    expect(listMetadataFile).toBeUndefined();
-
-    // The Connection model should still be generated
-    const connectionFile = files.find((f) => f.path.includes('connection.interface.ts'));
-    expect(connectionFile).toBeDefined();
-  });
-
-  it('does not skip models that only partially match list-metadata shape', () => {
-    const service: Service = {
-      name: 'Organizations',
-      operations: [
-        {
-          name: 'getOrganization',
-          httpMethod: 'get',
-          path: '/organizations/{id}',
-          pathParams: [
-            {
-              name: 'id',
-              type: { kind: 'primitive', type: 'string' },
-              required: true,
-            },
-          ],
-          queryParams: [],
-          headerParams: [],
-          response: { kind: 'model', name: 'Pagination' },
-          errors: [],
-          injectIdempotencyKey: false,
-        },
-      ],
-    };
-
-    const models: Model[] = [
+    const spec = makeSpec(models, [
       {
-        name: 'Pagination',
-        fields: [
-          {
-            name: 'before',
-            type: {
-              kind: 'nullable',
-              inner: { kind: 'primitive', type: 'string' },
-            },
-            required: false,
-          },
-          {
-            name: 'after',
-            type: {
-              kind: 'nullable',
-              inner: { kind: 'primitive', type: 'string' },
-            },
-            required: false,
-          },
-          {
-            name: 'total',
-            type: { kind: 'primitive', type: 'integer' },
-            required: true,
+        name: 'Organizations',
+        operations: [
+          {
+            name: 'getOrganization',
+            httpMethod: 'get',
+            path: '/organizations/{id}',
+            pathParams: [{ name: 'id', type: { kind: 'primitive', type: 'string' }, required: true }],
+            queryParams: [],
+            headerParams: [],
+            response: { kind: 'model', name: 'Organization' },
+            errors: [],
+            injectIdempotencyKey: false,
           },
         ],
       },
-    ];
-
-    const ctxWithServices: EmitterContext = {
-      ...ctx,
-      spec: { ...emptySpec, services: [service], models },
-    };
+    ]);
+    const ctxWithModels: EmitterContext = { ...ctx, spec };
+    const result = generateSerializers(models, ctxWithModels);
 
-    const files = generateModels(models, ctxWithServices);
-    // Model with 3 fields should NOT be skipped even if it has before/after
-    expect(files.length).toBe(1);
-    expect(files[0].path).toContain('pagination.interface.ts');
+    const orgSerializer = result.find(
+      (f) => f.path.includes('organization.serializer.ts') && !f.path.includes('parent'),
+    );
+    expect(orgSerializer?.content).toContain(
+      'parent: response.parent != null ? deserializeParentOrg(response.parent) : null',
+    );
   });
-});
 
-describe('model deduplication', () => {
-  it('emits type alias for structurally identical models', () => {
-    const service: Service = {
-      name: 'Roles',
-      operations: [
+  it('skips parent serialization when a structurally matched baseline dependency has no serializer', () => {
+    const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'node-serializer-baseline-'));
+    try {
+      fs.mkdirSync(path.join(tmpRoot, 'src', 'api-keys', 'interfaces'), { recursive: true });
+      fs.mkdirSync(path.join(tmpRoot, 'src', 'api-keys', 'serializers'), { recursive: true });
+      fs.writeFileSync(
+        path.join(tmpRoot, 'src', 'api-keys', 'interfaces', 'created-api-key.interface.ts'),
+        [
+          'export interface CreatedApiKey {',
+          '  id: string;',
+          '}',
+          '',
+          'export interface SerializedCreatedApiKey {',
+          '  id: string;',
+          '}',
+        ].join('\n'),
+      );
+      fs.writeFileSync(
+        path.join(tmpRoot, 'src', 'api-keys', 'serializers', 'created-api-key.serializer.ts'),
+        [
+          "import type { CreatedApiKey, SerializedCreatedApiKey } from '../interfaces/created-api-key.interface';",
+          'export function deserializeCreatedApiKey(apiKey: SerializedCreatedApiKey): CreatedApiKey {',
+          '  return { id: apiKey.id };',
+          '}',
+        ].join('\n'),
+      );
+
+      setActiveLiveSurface(buildLiveSurface(tmpRoot));
+      setBaselineSerializedNames(new Set(['SerializedCreatedApiKey']));
+      setBaselineInterfaceNames(new Set(['CreatedApiKey', 'SerializedCreatedApiKey']));
+
+      const models: Model[] = [
         {
-          name: 'getRole',
-          httpMethod: 'get',
-          path: '/roles/{id}',
-          pathParams: [
+          name: 'OrganizationApiKey',
+          fields: [{ name: 'id', type: { kind: 'primitive', type: 'string' }, required: true }],
+        },
+        {
+          name: 'OrganizationApiKeyList',
+          fields: [
+            { name: 'object', type: { kind: 'literal', value: 'list' }, required: true },
             {
-              name: 'id',
-              type: { kind: 'primitive', type: 'string' },
+              name: 'data',
+              type: { kind: 'array', items: { kind: 'model', name: 'OrganizationApiKey' } },
               required: true,
             },
           ],
-          queryParams: [],
-          headerParams: [],
-          response: { kind: 'model', name: 'EnvironmentRole' },
-          errors: [],
-          injectIdempotencyKey: false,
         },
+      ];
+      const spec = makeSpec(models, [
         {
-          name: 'getOrganizationRole',
-          httpMethod: 'get',
-          path: '/organization_roles/{id}',
-          pathParams: [
+          name: 'ApiKeys',
+          operations: [
             {
-              name: 'id',
-              type: { kind: 'primitive', type: 'string' },
-              required: true,
+              name: 'listOrganizationApiKeys',
+              httpMethod: 'get',
+              path: '/api_keys',
+              pathParams: [],
+              queryParams: [],
+              headerParams: [],
+              response: { kind: 'model', name: 'OrganizationApiKeyList' },
+              errors: [],
+              injectIdempotencyKey: false,
             },
           ],
-          queryParams: [],
-          headerParams: [],
-          response: { kind: 'model', name: 'OrganizationRole' },
-          errors: [],
-          injectIdempotencyKey: false,
         },
-      ],
-    };
-
-    const models: Model[] = [
-      {
-        name: 'EnvironmentRole',
-        fields: [
-          {
-            name: 'id',
-            type: { kind: 'primitive', type: 'string' },
-            required: true,
-          },
-          {
-            name: 'name',
-            type: { kind: 'primitive', type: 'string' },
-            required: true,
-          },
-          {
-            name: 'type',
-            type: { kind: 'literal', value: 'environment_role' },
-            required: true,
-          },
-        ],
-      },
-      {
-        name: 'OrganizationRole',
-        fields: [
-          {
-            name: 'id',
-            type: { kind: 'primitive', type: 'string' },
-            required: true,
-          },
-          {
-            name: 'name',
-            type: { kind: 'primitive', type: 'string' },
-            required: true,
-          },
-          {
-            name: 'type',
-            type: { kind: 'literal', value: 'environment_role' },
-            required: true,
-          },
-        ],
-      },
-    ];
-
-    const ctxWithServices: EmitterContext = {
-      ...ctx,
-      spec: { ...emptySpec, services: [service], models },
-    };
-
-    const files = generateModels(models, ctxWithServices);
-    expect(files.length).toBe(2);
-
-    // First model: full interface
-    expect(files[0].content).toContain('export interface EnvironmentRole');
-
-    // Second model: type alias referencing canonical
-    expect(files[1].content).toContain('export type OrganizationRole = EnvironmentRole');
-    expect(files[1].content).toContain('export type OrganizationRoleResponse = EnvironmentRoleResponse');
-  });
-
-  it('generates Date type for date-time fields even when baseline says string', () => {
-    const service: Service = {
-      name: 'Authorization',
-      operations: [
-        {
-          name: 'getRoleAssignment',
-          httpMethod: 'get',
-          path: '/role_assignments/{id}',
-          pathParams: [{ name: 'id', type: { kind: 'primitive', type: 'string' }, required: true }],
-          queryParams: [],
-          headerParams: [],
-          response: { kind: 'model', name: 'RoleAssignment' },
-          errors: [],
-          injectIdempotencyKey: false,
-        },
-      ],
-    };
-
-    const models: Model[] = [
-      {
-        name: 'RoleAssignment',
-        fields: [
-          {
-            name: 'id',
-            type: { kind: 'primitive', type: 'string' },
-            required: true,
-          },
-          {
-            name: 'created_at',
-            type: { kind: 'primitive', type: 'string', format: 'date-time' },
-            required: true,
-          },
-          {
-            name: 'updated_at',
-            type: { kind: 'primitive', type: 'string', format: 'date-time' },
-            required: true,
-          },
-          // Extra field not in baseline so modelHasNewFields returns true
-          // (allowing the dedup test to proceed with generation)
-          {
-            name: 'role_name',
-            type: { kind: 'primitive', type: 'string' },
-            required: true,
-          },
-        ],
-      },
-    ];
-
-    const ctxWithBaseline: EmitterContext = {
-      ...ctx,
-      spec: { ...emptySpec, services: [service], models },
-      apiSurface: {
-        language: 'node',
-        extractedFrom: 'test',
-        extractedAt: '2024-01-01',
-        classes: {},
-        typeAliases: {},
-        enums: {},
-        exports: {},
-        interfaces: {
-          RoleAssignment: {
-            name: 'RoleAssignment',
-            fields: {
-              id: { name: 'id', type: 'string', optional: false },
-              createdAt: { name: 'createdAt', type: 'string', optional: false },
-              updatedAt: { name: 'updatedAt', type: 'string', optional: false },
+      ]);
+      const result = generateSerializers(models, {
+        ...ctx,
+        spec,
+        outputDir: tmpRoot,
+        apiSurface: {
+          language: 'node',
+          extractedFrom: tmpRoot,
+          extractedAt: '2026-05-12T00:00:00Z',
+          classes: {},
+          interfaces: {
+            CreatedApiKey: {
+              name: 'CreatedApiKey',
+              fields: { id: { type: 'string', optional: false } },
+              extends: [],
+              sourceFile: 'src/api-keys/interfaces/created-api-key.interface.ts',
             },
-            extends: [],
-          },
-          RoleAssignmentResponse: {
-            name: 'RoleAssignmentResponse',
-            fields: {
-              id: { name: 'id', type: 'string', optional: false },
-              created_at: { name: 'created_at', type: 'string', optional: false },
-              updated_at: { name: 'updated_at', type: 'string', optional: false },
+            SerializedCreatedApiKey: {
+              name: 'SerializedCreatedApiKey',
+              fields: { id: { type: 'string', optional: false } },
+              extends: [],
+              sourceFile: 'src/api-keys/interfaces/created-api-key.interface.ts',
             },
-            extends: [],
           },
-        },
-      },
-    };
-
-    const files = generateModels(models, ctxWithBaseline);
-    const content = files[0].content;
-
-    // Domain interface should use Date, not string from baseline
-    expect(content).toContain('  createdAt: Date;');
-    expect(content).toContain('  updatedAt: Date;');
-
-    // Wire interface should stay as string (JSON native)
-    expect(content).toContain('  created_at: string;');
-    expect(content).toContain('  updated_at: string;');
+          typeAliases: {},
+          enums: {},
+          exports: {},
+        } as any,
+        overlayLookup: {
+          methodByOperation: new Map(),
+          interfaceByName: new Map(),
+          modelNameByIR: new Map([['OrganizationApiKey', 'SerializedCreatedApiKey']]),
+        } as any,
+      });
+
+      const listSerializer = result.find((f) => f.path.endsWith('organization-api-key-list.serializer.ts'));
+      expect(listSerializer?.content).toContain('deserializeOrganizationApiKeyList');
+      expect(listSerializer?.content).not.toContain('export const serializeOrganizationApiKeyList');
+    } finally {
+      setActiveLiveSurface(emptyLiveSurface());
+      setBaselineSerializedNames(new Set());
+      setBaselineInterfaceNames(new Set());
+      fs.rmSync(tmpRoot, { recursive: true, force: true });
+    }
   });
 });