@workos/oagen-emitters 0.18.4 → 0.19.1

package/src/kotlin/resources.ts

@@ -34,7 +34,7 @@ import {
 import {
   buildResolvedLookup,
   lookupResolved,
-  groupByMount,
+  scopedMountGroups,
   buildHiddenParams,
   getOpDefaults,
   getOpInferFromClient,
@@ -97,7 +97,7 @@ function promoteFieldType(f: Field): Field {
 export function generateResources(services: Service[], ctx: EmitterContext): GeneratedFile[] {
   if (services.length === 0) return [];
 
-  const mountGroups = groupByMount(ctx);
+  const mountGroups = scopedMountGroups(ctx);
   if (mountGroups.size === 0) return [];
 
   const files: GeneratedFile[] = [];

package/src/kotlin/tests.ts

@@ -22,11 +22,14 @@ import {
 } from './naming.js';
 import { mapTypeRef } from './type-map.js';
 import {
-  groupByMount,
+  scopedMountGroups,
   lookupResolved,
   buildResolvedLookup,
   buildHiddenParams,
   collectGroupedParamNames,
+  isModelInScope,
+  isEnumInScope,
+  fileExistsAfterRun,
 } from '../shared/resolved-ops.js';
 import { isListWrapperModel, isListMetadataModel } from '../shared/model-utils.js';
 import { resolveWrapperParams } from '../shared/wrapper-utils.js';
@@ -34,6 +37,23 @@ import { isHandwrittenOverride } from './overrides.js';
 
 const TEST_PREFIX = 'src/test/kotlin/';
 
+// Per-item FILE paths (target-root-relative, matching the prior manifest) the
+// model/enum emitters write. The whole-suite test aggregates below reference
+// these classes by name, so they may only list an item whose file will EXIST
+// on disk after the run (in-scope ∪ prior manifest) — otherwise a scoped
+// (`--services`) run references a `Class::class.java` whose `.kt` was never
+// emitted. Must stay in sync with the paths in `models.ts` / `enums.ts`.
+const MODELS_FILE_PREFIX = 'src/main/kotlin/com/workos/models/';
+const ENUMS_FILE_PREFIX = 'src/main/kotlin/com/workos/types/';
+
+function modelFilePath(modelName: string): string {
+  return `${MODELS_FILE_PREFIX}${className(modelName)}.kt`;
+}
+
+function enumFilePath(enumName: string): string {
+  return `${ENUMS_FILE_PREFIX}${className(enumName)}.kt`;
+}
+
 /**
  * Mirror the ISO-8601 hint promotion the resource/model emitters use so tests
  * synthesize values whose Kotlin type matches the generated method signature.
@@ -76,7 +96,7 @@ function promoteIso8601TypeRef(type: TypeRef, description: string | undefined):
  */
 export function generateTests(spec: ApiSpec, ctx: EmitterContext): GeneratedFile[] {
   const files: GeneratedFile[] = [];
-  const mountGroups = groupByMount(ctx);
+  const mountGroups = scopedMountGroups(ctx);
   const resolvedLookup = buildResolvedLookup(ctx);
 
   const exportedClasses = buildExportedClassNameSet(ctx);
@@ -1029,6 +1049,11 @@ function generateModelRoundTripTest(spec: ApiSpec, ctx: EmitterContext): Generat
   for (const m of spec.models) {
     if (isListWrapperModel(m) || isListMetadataModel(m)) continue;
     if (m.fields.length === 0) continue;
+    // AGGREGATE gate: this whole-suite test references `${cls}::class.java`. In a
+    // scoped run only in-scope model files are emitted, so skip a brand-new
+    // OUT-OF-SCOPE model whose `.kt` won't exist on disk. In-scope ∪ prior
+    // manifest is retained; a full run keeps everything (gate is inert).
+    if (!fileExistsAfterRun(modelFilePath(m.name), isModelInScope(m.name, ctx), ctx)) continue;
     const cls = className(m.name);
     if (seenModelClassNames.has(cls)) continue;
     seenModelClassNames.add(cls);
@@ -1092,10 +1117,20 @@ const MAX_ENUM_FORWARD_COMPAT = 15;
 
 function generateForwardCompatTest(spec: ApiSpec, ctx: EmitterContext): GeneratedFile | null {
   // Select multiple enums for forward-compat testing, not just the first.
-  const enumTargets = spec.enums.filter((e) => e.values.length > 0).slice(0, MAX_ENUM_FORWARD_COMPAT);
+  // AGGREGATE gate: each selected enum is imported as `com.workos.types.X`. In a
+  // scoped run only in-scope enum files are emitted, so skip a brand-new
+  // OUT-OF-SCOPE enum whose `.kt` won't exist on disk (in-scope ∪ prior manifest
+  // retained; full run keeps everything).
+  const enumTargets = spec.enums
+    .filter((e) => e.values.length > 0)
+    .filter((e) => fileExistsAfterRun(enumFilePath(e.name), isEnumInScope(e.name, ctx), ctx))
+    .slice(0, MAX_ENUM_FORWARD_COMPAT);
   const modelTarget = spec.models.find((m) => {
     if (isListWrapperModel(m) || isListMetadataModel(m)) return false;
     if (m.fields.length === 0) return false;
+    // Same aggregate gate as the round-trip test: the model is referenced as
+    // `${cls}::class.java`, so it must exist on disk after the run.
+    if (!fileExistsAfterRun(modelFilePath(m.name), isModelInScope(m.name, ctx), ctx)) return false;
     return synthJsonForModelName(m.name, ctx, new Set()) !== null;
   });
   if (enumTargets.length === 0 && !modelTarget) return null;

package/src/node/enums.ts

@@ -5,6 +5,7 @@ import { docComment, assignModelsToEmittableServices } from './utils.js';
 import { isInlineEnum } from './type-map.js';
 import { isNodeOwnedService } from './options.js';
 import { liveSurfaceConstEnumMembers, liveSurfaceInterfacePath } from './live-surface.js';
+import { isEnumInScope } from '../shared/resolved-ops.js';
 
 export function generateEnums(enums: Enum[], ctx: EmitterContext): GeneratedFile[] {
   if (enums.length === 0) return [];
@@ -120,11 +121,13 @@ export function generateEnums(enums: Enum[], ctx: EmitterContext): GeneratedFile
       lines.push(`  (typeof ${enumDef.name})[keyof typeof ${enumDef.name}];`);
     }
 
-    files.push({
-      path: `src/${dirName}/interfaces/${fileName(enumDef.name)}.interface.ts`,
-      content: lines.join('\n'),
-      skipIfExists: !hasNewValues,
-    });
+    if (isEnumInScope(enumDef.name, ctx)) {
+      files.push({
+        path: `src/${dirName}/interfaces/${fileName(enumDef.name)}.interface.ts`,
+        content: lines.join('\n'),
+        skipIfExists: !hasNewValues,
+      });
+    }
   }
 
   return files;

package/src/node/models.ts

@@ -45,7 +45,7 @@ import {
 import { liveSurfaceHasExistingSdk, liveSurfaceHasManagedFile, liveSurfaceInterfacePath } from './live-surface.js';
 import { isNodeOwnedService, isHandOwnedType } from './options.js';
 import { unwrapListModel } from './fixtures.js';
-import { groupByMount, buildResolvedLookup, lookupResolved } from '../shared/resolved-ops.js';
+import { groupByMount, buildResolvedLookup, lookupResolved, isModelInScope } from '../shared/resolved-ops.js';
 import { resolveWrapperParams } from '../shared/wrapper-utils.js';
 import { collectWrapperResponseModels } from './wrappers.js';
 import { resolveResourceClassName } from './resources.js';
@@ -308,11 +308,13 @@ export function generateModels(models: Model[], ctx: EmitterContext, shared?: Sh
       const aliasLines = importSymbols
         ? [`import type { ${importSymbols} } from '${canonRelPath}';`, '', ...aliasExports]
         : [...aliasExports];
-      files.push({
-        path: aliasPath,
-        content: aliasLines.join('\n'),
-        overwriteExisting: true,
-      });
+      if (isModelInScope(model.name, ctx)) {
+        files.push({
+          path: aliasPath,
+          content: aliasLines.join('\n'),
+          overwriteExisting: true,
+        });
+      }
       continue;
     }
 
@@ -745,11 +747,13 @@ export function generateModels(models: Model[], ctx: EmitterContext, shared?: Sh
       }
     }
 
-    files.push({
-      path: filePath,
-      content: pruneUnusedImports(lines).join('\n'),
-      overwriteExisting: true,
-    });
+    if (isModelInScope(model.name, ctx)) {
+      files.push({
+        path: filePath,
+        content: pruneUnusedImports(lines).join('\n'),
+        overwriteExisting: true,
+      });
+    }
   }
 
   return files;
@@ -943,11 +947,13 @@ export function generateSerializers(
           parts.push(`serialize${canonDomainName} as serialize${domainName}`);
         }
         const reexportContent = `export { ${parts.join(', ')} } from '${rel}';`;
-        files.push({
-          path: serializerPath,
-          content: reexportContent,
-          overwriteExisting: true,
-        });
+        if (isModelInScope(model.name, ctx)) {
+          files.push({
+            path: serializerPath,
+            content: reexportContent,
+            overwriteExisting: true,
+          });
+        }
         continue;
       }
       // The alias is response-reachable, but the canonical model is
@@ -997,11 +1003,13 @@ export function generateSerializers(
       ),
     ];
 
-    files.push({
-      path: serializerPath,
-      content: pruneUnusedImports(lines).join('\n'),
-      overwriteExisting: true,
-    });
+    if (isModelInScope(model.name, ctx)) {
+      files.push({
+        path: serializerPath,
+        content: pruneUnusedImports(lines).join('\n'),
+        overwriteExisting: true,
+      });
+    }
   }
 
   (ctx as any)._skippedSerializeModels = skippedSerializeModels;

package/src/node/resources.ts

@@ -78,6 +78,7 @@ import {
   buildResolvedLookup,
   lookupResolved,
   groupByMount,
+  isMountInScope,
   getOpDefaults,
   getOpInferFromClient,
 } from '../shared/resolved-ops.js';
@@ -718,11 +719,18 @@ export function generateResources(services: Service[], ctx: EmitterContext): Gen
   // multiple IR services mount to the same resource class.
   const mountGroups = groupByMount(ctx);
   const mergedServices: Service[] =
-    mountGroups.size > 0 ? [...mountGroups].map(([name, group]) => ({ name, operations: group.operations })) : services;
+    mountGroups.size > 0 || ctx.scopedServices?.size
+      ? [...mountGroups].map(([name, group]) => ({ name, operations: group.operations }))
+      : services;
 
   const topLevelEnumNames = new Set(ctx.spec.enums.map((e) => e.name));
 
   for (const service of mergedServices) {
+    // Scope gate: in a scoped (`--services`) run, only emit per-service resource
+    // files for the selected post-mount names. `service.name` is the mount-group
+    // key (the POST-MOUNT name that matches `ctx.scopedServices`). Applied as an
+    // additional early continue ahead of the node-owned/coverage skip logic.
+    if (!isMountInScope(service.name, ctx)) continue;
     const isOwnedService = isNodeOwnedService(ctx, service.name, resolveResourceClassName(service, ctx));
     if (!isOwnedService && isServiceCoveredByExisting(service, ctx)) {
       if (!hasMethodsAbsentFromBaseline(service, ctx)) {
@@ -770,6 +778,9 @@ export function generateResources(services: Service[], ctx: EmitterContext): Gen
   // stable.  Placing them under `interfaces/` lets the per-service barrel
   // pick them up automatically.
   for (const service of mergedServices) {
+    // Scope gate: keep the per-service options interfaces aligned with the
+    // resource files emitted above — only the selected post-mount names.
+    if (!isMountInScope(service.name, ctx)) continue;
     const isOwnedService = isNodeOwnedService(ctx, service.name, resolveResourceClassName(service, ctx));
     if (!isOwnedService && isServiceCoveredByExisting(service, ctx) && !hasMethodsAbsentFromBaseline(service, ctx))
       continue;

package/src/node/tests.ts

@@ -35,7 +35,7 @@ import {
   modelHasNewFields,
   computeNonEventReachable,
 } from './utils.js';
-import { groupByMount, buildResolvedLookup, lookupResolved } from '../shared/resolved-ops.js';
+import { groupByMount, buildResolvedLookup, lookupResolved, isMountInScope } from '../shared/resolved-ops.js';
 import { isNodeOwnedService, nodeOptions, planOperationFor } from './options.js';
 
 type BaselineMethod = {
@@ -137,7 +137,7 @@ export function generateTests(spec: ApiSpec, ctx: EmitterContext): GeneratedFile
   }
 
   const testEntries: Array<{ name: string; operations: Operation[] }> =
-    mountGroups.size > 0
+    mountGroups.size > 0 || ctx.scopedServices?.size
       ? [...mountGroups].map(([name, group]) => ({ name, operations: group.operations }))
       : spec.services.map((s) => ({ name: resolveResourceClassName(s, ctx), operations: s.operations }));
 
@@ -159,6 +159,11 @@ export function generateTests(spec: ApiSpec, ctx: EmitterContext): GeneratedFile
   }
 
   for (const { name: mountName, operations } of testEntries) {
+    // Scope gate: in a scoped (`--services`) run, only emit per-service test
+    // files for the selected post-mount names. `mountName` is the mount-group
+    // key (the POST-MOUNT name that matches `ctx.scopedServices`). Applied as an
+    // additional early continue ahead of the node-owned/coverage skip logic.
+    if (!isMountInScope(mountName, ctx)) continue;
     if (operations.length === 0) continue;
     const mergedService: Service = { name: mountName, operations };
     const isOwnedService = isNodeOwnedService(ctx, mountName, resolveResourceClassName(mergedService, ctx));

package/src/php/enums.ts

@@ -2,6 +2,7 @@ import type { Enum, EmitterContext, GeneratedFile } from '@workos/oagen';
 import { toPascalCase } from '@workos/oagen';
 import { className, resolveEnumName } from './naming.js';
 import { phpDocComment } from './utils.js';
+import { isEnumInScope } from '../shared/resolved-ops.js';
 
 /**
  * Generate PHP enum files from IR enums.
@@ -17,6 +18,16 @@ export function generateEnums(enums: Enum[], ctx: EmitterContext): GeneratedFile
     if (emittedCanonical.has(canonical)) continue; // skip aliases
     emittedCanonical.add(canonical);
 
+    // FR-1.4: write the per-enum FILE only when in scope. PHP dedupes
+    // value-identical enums onto a single canonical class, so the canonical
+    // file is needed when EITHER the canonical name OR any alias resolving to
+    // it is reachable from the selected services. PSR-4 (one class per file
+    // under lib/Resource/, no barrel) means an out-of-scope enum is simply
+    // left untouched on disk and stays loadable.
+    const enumInScope = enums.some(
+      (other) => resolveEnumName(other.name) === canonical && isEnumInScope(other.name, ctx),
+    );
+
     const name = className(canonical);
     const _isAllStrings = e.values.every((v) => typeof v.value === 'string');
     const isAllInts = e.values.every((v) => typeof v.value === 'number' && Number.isInteger(v.value));
@@ -56,11 +67,13 @@ export function generateEnums(enums: Enum[], ctx: EmitterContext): GeneratedFile
 
     lines.push('}');
 
-    files.push({
-      path: `lib/Resource/${name}.php`,
-      content: lines.join('\n'),
-      overwriteExisting: true,
-    });
+    if (enumInScope) {
+      files.push({
+        path: `lib/Resource/${name}.php`,
+        content: lines.join('\n'),
+        overwriteExisting: true,
+      });
+    }
   }
 
   return files;

package/src/php/index.ts

@@ -42,9 +42,17 @@ function ensureTrailingNewlines(files: GeneratedFile[]): GeneratedFile[] {
  * classes (no sum types), so a discriminated base whose IR fields the
  * parser stripped (post-allOf-aware detection) gets its original fields
  * restored to avoid silently dropping variant data.
+ *
+ * `enums` is forwarded to seed `enrichModelsFromSpec`'s collision set: an
+ * inline oneOf enum whose synthetic name (`Parent_field`) snake-collapses
+ * onto an existing IR enum (e.g. `DataIntegrationAccessTokenResponse_error`
+ * vs `DataIntegrationAccessTokenResponseError`) must NOT spawn a duplicate
+ * synthetic. Otherwise both collapse to the same `lib/Resource/X.php` path
+ * and the later writer wins by array order — which differs between a full
+ * and a scoped (`--services`) run, producing a non-deterministic case order.
  */
-function enrichModelsForPhp(models: Model[]): Model[] {
-  const enriched = enrichModelsFromSpec(models);
+function enrichModelsForPhp(models: Model[], enums: Enum[]): Model[] {
+  const enriched = enrichModelsFromSpec(models, enums);
   const originalByName = new Map(models.map((m) => [m.name, m]));
   return enriched.map((m) => {
     if ((m as { discriminator?: unknown }).discriminator && m.fields.length === 0) {
@@ -62,7 +70,7 @@ export const phpEmitter: Emitter = {
 
   generateModels(models: Model[], ctx: EmitterContext): GeneratedFile[] {
     ensureNamingInitialized(ctx);
-    return ensureTrailingNewlines(generateModels(enrichModelsForPhp(models), ctx));
+    return ensureTrailingNewlines(generateModels(enrichModelsForPhp(models, ctx.spec.enums), ctx));
   },
 
   generateEnums(enums: Enum[], ctx: EmitterContext): GeneratedFile[] {

package/src/php/models.ts

@@ -10,6 +10,7 @@ import {
   collectNonPaginatedResponseModelNames,
   collectReferencedListMetadataModels,
 } from '../shared/model-utils.js';
+import { isModelInScope } from '../shared/resolved-ops.js';
 export { isListMetadataModel, isListWrapperModel };
 
 /**
@@ -140,11 +141,16 @@ export function generateModels(models: Model[], ctx: EmitterContext): GeneratedF
 
     lines.push('}');
 
-    files.push({
-      path: `lib/Resource/${name}.php`,
-      content: lines.join('\n'),
-      overwriteExisting: true,
-    });
+    // FR-1.4: write the per-model FILE only when in scope. PHP uses PSR-4
+    // (one class per file under lib/Resource/, no barrel/index), so an
+    // out-of-scope model is simply left untouched on disk and stays loadable.
+    if (isModelInScope(model.name, ctx)) {
+      files.push({
+        path: `lib/Resource/${name}.php`,
+        content: lines.join('\n'),
+        overwriteExisting: true,
+      });
+    }
   }
 
   return files;

package/src/php/resources.ts

@@ -12,7 +12,7 @@ import { mapTypeRef, mapTypeRefForPHPDoc } from './type-map.js';
 import { className, fieldName, resolveMethodName, buildExportedClassNameSet, resolveServiceTarget } from './naming.js';
 import { isListWrapperModel } from './models.js';
 import {
-  groupByMount,
+  scopedMountGroups,
   buildResolvedLookup,
   lookupResolved,
   getOpDefaults,
@@ -44,10 +44,12 @@ export function generateResources(services: Service[], ctx: EmitterContext): Gen
   const files: GeneratedFile[] = [];
   const modelMap = new Map(ctx.spec.models.map((m) => [m.name, m]));
 
-  // Group operations by mount target
-  const mountGroups = groupByMount(ctx);
+  // Group operations by mount target. In a scoped (`--services`) run this
+  // returns only the selected post-mount services so we emit per-service
+  // resource files for those alone.
+  const mountGroups = scopedMountGroups(ctx);
   const entries: Array<{ name: string; operations: Operation[] }> =
-    mountGroups.size > 0
+    mountGroups.size > 0 || ctx.scopedServices?.size
       ? [...mountGroups].map(([name, group]) => ({ name, operations: group.operations }))
       : services.map((s) => ({ name: className(s.name), operations: s.operations }));
 

package/src/php/tests.ts

@@ -20,7 +20,7 @@ import { isListWrapperModel } from './models.js';
 import { generateFixtures } from './fixtures.js';
 import {
   getMountTarget,
-  groupByMount,
+  scopedMountGroups,
   buildHiddenParams,
   getOpDefaults,
   getOpInferFromClient,
@@ -39,9 +39,12 @@ export function generateTests(spec: ApiSpec, ctx: EmitterContext): GeneratedFile
 
   // Collect all operations per mount target using resolved per-operation mounts.
   // This correctly handles operationHint mountOn overrides (e.g., audit_logs_retention → AuditLogs).
-  const mountGroupsFromResolved = groupByMount(ctx);
+  // In a scoped (`--services`) run this returns only the selected post-mount
+  // services so we emit per-service test files for those alone. ClientTest.php
+  // and fixtures below are built from `spec` and stay full.
+  const mountGroupsFromResolved = scopedMountGroups(ctx);
   const mountGroups = new Map<string, { op: Operation; service: Service; resolvedOp?: ResolvedOperation }[]>();
-  if (mountGroupsFromResolved.size > 0) {
+  if (mountGroupsFromResolved.size > 0 || ctx.scopedServices?.size) {
     for (const [target, group] of mountGroupsFromResolved) {
       mountGroups.set(
         target,

package/src/python/enums.ts

@@ -2,6 +2,7 @@ import type { Enum, EmitterContext, GeneratedFile } from '@workos/oagen';
 import { toUpperSnakeCase } from '@workos/oagen';
 import { className, fileName, buildMountDirMap, dirToModule } from './naming.js';
 import { computeSchemaPlacement } from './shared-schemas.js';
+import { isEnumInScope } from '../shared/resolved-ops.js';
 
 /**
  * Convert a PascalCase class name to a human-readable lowercase string,
@@ -38,6 +39,10 @@ export function generateEnums(enums: Enum[], ctx: EmitterContext): GeneratedFile
   for (const enumDef of enums) {
     const service = enumToService.get(enumDef.name);
     const dirName = resolveDir(service);
+    // FR-1.4: write per-enum FILES only when in scope; the enum barrel is built
+    // separately (collectGeneratedEnumSymbolsByDir over the full set), so an
+    // out-of-scope enum left on disk stays exported and importable.
+    const enumInScope = isEnumInScope(enumDef.name, ctx);
 
     // If this enum is an alias for a canonical enum, generate a type alias file
     const canonicalName = aliasOf.get(enumDef.name);
@@ -73,12 +78,14 @@ export function generateEnums(enums: Enum[], ctx: EmitterContext): GeneratedFile
         lines.push('        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")');
       }
       lines.push(`__all__ = ["${aliasCls}"]`);
-      files.push({
-        path: `src/${ctx.namespace}/${dirName}/models/${fileName(enumDef.name)}.py`,
-        content: lines.join('\n'),
-        integrateTarget: true,
-        overwriteExisting: true,
-      });
+      if (enumInScope) {
+        files.push({
+          path: `src/${ctx.namespace}/${dirName}/models/${fileName(enumDef.name)}.py`,
+          content: lines.join('\n'),
+          integrateTarget: true,
+          overwriteExisting: true,
+        });
+      }
 
       // Also generate compat alias files for dedup aliases (they may have compat aliases too)
       for (const aliasName of compatAliases.get(enumDef.name) ?? []) {
@@ -107,12 +114,14 @@ export function generateEnums(enums: Enum[], ctx: EmitterContext): GeneratedFile
             `__all__ = ["${aliasName}"]`,
           ].join('\n');
         }
-        files.push({
-          path: `src/${ctx.namespace}/${dirName}/models/${fileName(aliasName)}.py`,
-          content: compatContent,
-          integrateTarget: true,
-          overwriteExisting: true,
-        });
+        if (enumInScope) {
+          files.push({
+            path: `src/${ctx.namespace}/${dirName}/models/${fileName(aliasName)}.py`,
+            content: compatContent,
+            integrateTarget: true,
+            overwriteExisting: true,
+          });
+        }
       }
 
       continue;
@@ -241,26 +250,28 @@ export function generateEnums(enums: Enum[], ctx: EmitterContext): GeneratedFile
       );
     }
 
-    files.push({
-      path: `src/${ctx.namespace}/${dirName}/models/${fileName(enumDef.name)}.py`,
-      content: lines.join('\n'),
-      integrateTarget: true,
-      overwriteExisting: true,
-    });
-
-    for (const aliasName of compatAliases.get(enumDef.name) ?? []) {
+    if (enumInScope) {
       files.push({
-        path: `src/${ctx.namespace}/${dirName}/models/${fileName(aliasName)}.py`,
-        content: [
-          'from typing import TypeAlias',
-          `from .${fileName(enumDef.name)} import ${cls}`,
-          '',
-          `${aliasName}: TypeAlias = ${cls}`,
-          `__all__ = ["${aliasName}"]`,
-        ].join('\n'),
+        path: `src/${ctx.namespace}/${dirName}/models/${fileName(enumDef.name)}.py`,
+        content: lines.join('\n'),
         integrateTarget: true,
         overwriteExisting: true,
       });
+
+      for (const aliasName of compatAliases.get(enumDef.name) ?? []) {
+        files.push({
+          path: `src/${ctx.namespace}/${dirName}/models/${fileName(aliasName)}.py`,
+          content: [
+            'from typing import TypeAlias',
+            `from .${fileName(enumDef.name)} import ${cls}`,
+            '',
+            `${aliasName}: TypeAlias = ${cls}`,
+            `__all__ = ["${aliasName}"]`,
+          ].join('\n'),
+          integrateTarget: true,
+          overwriteExisting: true,
+        });
+      }
     }
   }
 

package/src/python/fixtures.ts

@@ -1,8 +1,9 @@
-import type { Model, TypeRef, Enum } from '@workos/oagen';
+import type { Model, TypeRef, Enum, EmitterContext } from '@workos/oagen';
 
 import { fileName, domainFieldName } from './naming.js';
 import { isListMetadataModel, isListWrapperModel } from './models.js';
 import { collectNonPaginatedResponseModelNames, collectReferencedListMetadataModels } from '../shared/model-utils.js';
+import { isModelInScope, fileExistsAfterRun } from '../shared/resolved-ops.js';
 
 /**
  * Prefix mapping for generating realistic ID fixture values.
@@ -25,18 +26,39 @@ export const ID_PREFIXES: Record<string, string> = {
 
 /**
  * Generate JSON fixture files for test data.
+ *
+ * `ctx` is optional so unit tests can call with a bare spec; when supplied, a
+ * scoped (`--services`) run only emits a fixture for a model whose per-model
+ * file will exist on disk after the run (in-scope, or already present from a
+ * prior manifest). Brand-new out-of-scope models are skipped: the round-trip
+ * test that consumes these fixtures is gated the same way, and the per-service
+ * tests only reference fixtures for their (in-scope) models.
  */
-export function generateFixtures(spec: {
-  models: Model[];
-  enums: Enum[];
-  services: any[];
-}): { path: string; content: string }[] {
+export function generateFixtures(
+  spec: {
+    models: Model[];
+    enums: Enum[];
+    services: any[];
+  },
+  ctx?: EmitterContext,
+): { path: string; content: string }[] {
   if (spec.models.length === 0) return [];
 
   const modelMap = new Map(spec.models.map((m) => [m.name, m]));
   const enumMap = new Map(spec.enums.map((e) => [e.name, e]));
   const files: { path: string; content: string }[] = [];
 
+  // Gate a fixture by ITS OWN path (recorded verbatim in the prior manifest),
+  // scoped on the owning model. A base-model fixture and its `list_*` fixture
+  // are distinct files, so each must be checked against its own path — keying a
+  // list fixture off the base path would leak a brand-new `list_*` fixture for
+  // an out-of-scope model that merely already had its base fixture on disk.
+  // When ctx is absent (unit tests) every fixture is in scope.
+  const fixtureEmitted = (path: string, modelName: string): boolean => {
+    if (!ctx) return true;
+    return fileExistsAfterRun(path, isModelInScope(modelName, ctx), ctx);
+  };
+
   const nonPaginatedRefs = collectNonPaginatedResponseModelNames(spec.services);
   const listMetadataNeeded = collectReferencedListMetadataModels(spec.models, nonPaginatedRefs);
 
@@ -47,6 +69,8 @@ export function generateFixtures(spec: {
     // with hand-maintained @oagen-ignore overrides; generated empty fixtures
     // would not match the override's required fields.
     if (model.fields.length === 0) continue;
+    // Scoped run: skip a fixture for a brand-new out-of-scope model.
+    if (!fixtureEmitted(`tests/fixtures/${fileName(model.name)}.json`, model.name)) continue;
 
     const fixture = generateModelFixture(model, modelMap, enumMap);
 
@@ -65,6 +89,10 @@ export function generateFixtures(spec: {
           const unwrapped = unwrapListModel(itemModel, modelMap);
           if (unwrapped) itemModel = unwrapped;
           if (itemModel.fields.length === 0) continue;
+          // Scoped run: a list fixture for a brand-new out-of-scope item model
+          // would be referenced by no emitted test; gate it on the LIST
+          // fixture's own path (not the base model fixture's).
+          if (!fixtureEmitted(`tests/fixtures/list_${fileName(itemModel.name)}.json`, itemModel.name)) continue;
           const fixture = generateModelFixture(itemModel, modelMap, enumMap);
           const listFixture = {
             data: [fixture],