@workos/oagen-emitters 0.18.4 → 0.19.1

package/src/python/models.ts

@@ -2,8 +2,9 @@ import type { Model, EmitterContext, GeneratedFile } from '@workos/oagen';
 import { collectFieldDependencies, walkTypeRef } from '@workos/oagen';
 import { mapTypeRef } from './type-map.js';
 import { className, domainFieldName, fileName, buildMountDirMap, dirToModule } from './naming.js';
-import { collectGeneratedEnumSymbolsByDir } from './enums.js';
+import { collectGeneratedEnumSymbolsByDir, collectCompatEnumAliases } from './enums.js';
 import { computeSchemaPlacement } from './shared-schemas.js';
+import { isModelInScope, isEnumInScope, fileExistsAfterRun, priorManifestBasenames } from '../shared/resolved-ops.js';
 
 /**
  * Generate Python dataclass model files from IR Model definitions.
@@ -169,26 +170,38 @@ export function generateModels(models: Model[], ctx: EmitterContext): GeneratedF
       dispLines.push(`            return cast("${variantTypeName}", dispatch_cls.from_dict(data))`);
       dispLines.push(`        return ${unknownClassName}.from_dict(data)`);
 
-      files.push({
-        path: `src/${ctx.namespace}/${dirName}/models/${fileName(model.name)}.py`,
-        content: dispLines.join('\n'),
-        integrateTarget: true,
-        overwriteExisting: true,
-      });
+      // FR-1.4: write the file only when in scope; the barrel tracking below is
+      // gated on the file existing after the run so out-of-scope models that
+      // are already on disk stay exported, but brand-new out-of-scope models
+      // (whose file is never emitted) are NOT referenced by the barrel.
+      const dispInScope = isModelInScope(model.name, ctx);
+      if (dispInScope) {
+        files.push({
+          path: `src/${ctx.namespace}/${dirName}/models/${fileName(model.name)}.py`,
+          content: dispLines.join('\n'),
+          integrateTarget: true,
+          overwriteExisting: true,
+        });
+      }
 
-      if (!emittedModelSymbolsByDir.has(dirName)) emittedModelSymbolsByDir.set(dirName, []);
-      emittedModelSymbolsByDir.get(dirName)!.push(model.name);
-      // Also register the variant type alias and unknown variant in the barrel,
-      // pointing to the same file as the dispatcher.
-      emittedModelSymbolsByDir.get(dirName)!.push(variantTypeName);
-      symbolToFile.set(variantTypeName, fileName(model.name));
-      emittedModelSymbolsByDir.get(dirName)!.push(unknownClassName);
-      symbolToFile.set(unknownClassName, fileName(model.name));
-      const dispatcherNatural = originalModelToService.get(model.name);
-      if (dispatcherNatural) {
-        symbolToOriginalService.set(model.name, dispatcherNatural);
-        symbolToOriginalService.set(variantTypeName, dispatcherNatural);
-        symbolToOriginalService.set(unknownClassName, dispatcherNatural);
+      // Only reference this dispatcher (and its variant/unknown symbols, which
+      // live in the same file) from the barrel when that file exists on disk
+      // after the run.
+      if (fileExistsAfterRun(`src/${ctx.namespace}/${dirName}/models/${fileName(model.name)}.py`, dispInScope, ctx)) {
+        if (!emittedModelSymbolsByDir.has(dirName)) emittedModelSymbolsByDir.set(dirName, []);
+        emittedModelSymbolsByDir.get(dirName)!.push(model.name);
+        // Also register the variant type alias and unknown variant in the barrel,
+        // pointing to the same file as the dispatcher.
+        emittedModelSymbolsByDir.get(dirName)!.push(variantTypeName);
+        symbolToFile.set(variantTypeName, fileName(model.name));
+        emittedModelSymbolsByDir.get(dirName)!.push(unknownClassName);
+        symbolToFile.set(unknownClassName, fileName(model.name));
+        const dispatcherNatural = originalModelToService.get(model.name);
+        if (dispatcherNatural) {
+          symbolToOriginalService.set(model.name, dispatcherNatural);
+          symbolToOriginalService.set(variantTypeName, dispatcherNatural);
+          symbolToOriginalService.set(unknownClassName, dispatcherNatural);
+        }
       }
       continue;
     }
@@ -216,16 +229,24 @@ export function generateModels(models: Model[], ctx: EmitterContext): GeneratedF
       }
       lines.push('');
       lines.push(`${modelClassName}: TypeAlias = ${canonicalClassName}`);
-      files.push({
-        path: `src/${ctx.namespace}/${dirName}/models/${fileName(model.name)}.py`,
-        content: lines.join('\n'),
-        integrateTarget: true,
-        overwriteExisting: true,
-      });
-      if (!emittedModelSymbolsByDir.has(dirName)) emittedModelSymbolsByDir.set(dirName, []);
-      emittedModelSymbolsByDir.get(dirName)!.push(model.name);
-      const aliasNatural = originalModelToService.get(model.name);
-      if (aliasNatural) symbolToOriginalService.set(model.name, aliasNatural);
+      const aliasInScope = isModelInScope(model.name, ctx);
+      const aliasPath = `src/${ctx.namespace}/${dirName}/models/${fileName(model.name)}.py`;
+      if (aliasInScope) {
+        files.push({
+          path: aliasPath,
+          content: lines.join('\n'),
+          integrateTarget: true,
+          overwriteExisting: true,
+        });
+      }
+      // Reference the alias from the barrel only when its file exists on disk
+      // after the run (in-scope, or already present from a prior run).
+      if (fileExistsAfterRun(aliasPath, aliasInScope, ctx)) {
+        if (!emittedModelSymbolsByDir.has(dirName)) emittedModelSymbolsByDir.set(dirName, []);
+        emittedModelSymbolsByDir.get(dirName)!.push(model.name);
+        const aliasNatural = originalModelToService.get(model.name);
+        if (aliasNatural) symbolToOriginalService.set(model.name, aliasNatural);
+      }
       continue;
     }
 
@@ -457,16 +478,25 @@ export function generateModels(models: Model[], ctx: EmitterContext): GeneratedF
 
     lines.push('        return result');
 
-    files.push({
-      path: `src/${ctx.namespace}/${dirName}/models/${fileName(model.name)}.py`,
-      content: lines.join('\n'),
-      integrateTarget: true,
-      overwriteExisting: true,
-    });
-    if (!emittedModelSymbolsByDir.has(dirName)) emittedModelSymbolsByDir.set(dirName, []);
-    emittedModelSymbolsByDir.get(dirName)!.push(model.name);
-    const regularNatural = originalModelToService.get(model.name);
-    if (regularNatural) symbolToOriginalService.set(model.name, regularNatural);
+    const regularInScope = isModelInScope(model.name, ctx);
+    if (regularInScope) {
+      files.push({
+        path: modelFilePath,
+        content: lines.join('\n'),
+        integrateTarget: true,
+        overwriteExisting: true,
+      });
+    }
+    // Reference the model from the barrel only when its file exists on disk
+    // after the run (in-scope, or already present from a prior run). A
+    // brand-new out-of-scope model whose file is never emitted must NOT be
+    // referenced, or the `from .x import X` line dangles and the import fails.
+    if (fileExistsAfterRun(modelFilePath, regularInScope, ctx)) {
+      if (!emittedModelSymbolsByDir.has(dirName)) emittedModelSymbolsByDir.set(dirName, []);
+      emittedModelSymbolsByDir.get(dirName)!.push(model.name);
+      const regularNatural = originalModelToService.get(model.name);
+      if (regularNatural) symbolToOriginalService.set(model.name, regularNatural);
+    }
   }
 
   // Generate __init__.py barrel files for each models/ directory
@@ -474,7 +504,11 @@ export function generateModels(models: Model[], ctx: EmitterContext): GeneratedF
   // A direct symbol lives in the file at `dirPath/<file>.py`. A re-exported
   // symbol was relocated to common/ but is being mirrored from its natural
   // service barrel for backwards compatibility.
-  type BarrelSymbol = { name: string; reExport?: { fromDir: string; file: string } };
+  // A `retainBasename` symbol has no known IR name — it is a per-item file
+  // recorded in the PRIOR manifest (renamed/removed from the current spec but
+  // still on disk) that we re-export wholesale via `from .<base> import *` so
+  // out-of-scope code the scoped run did not regenerate keeps resolving.
+  type BarrelSymbol = { name: string; reExport?: { fromDir: string; file: string }; retainBasename?: string };
   const symbolsByDir = new Map<string, BarrelSymbol[]>();
   for (const [dirName, names] of emittedModelSymbolsByDir) {
     const key = `src/${ctx.namespace}/${dirName}/models`;
@@ -486,10 +520,57 @@ export function generateModels(models: Model[], ctx: EmitterContext): GeneratedF
   const reachableEnumNames = collectReachableEnumNames(ctx);
   const emittedEnums = ctx.spec.enums.filter((enumDef) => reachableEnumNames.has(enumDef.name));
   const enumSymbolsByDir = collectGeneratedEnumSymbolsByDir(emittedEnums, ctx);
+  // Map each compat-alias symbol back to its canonical enum so we can gate it by
+  // the canonical enum's scope (the alias file is only written when the
+  // canonical enum is in scope; see enums.ts).
+  const aliasToCanonicalEnum = new Map<string, string>();
+  for (const [canonical, aliasNames] of collectCompatEnumAliases(emittedEnums, ctx)) {
+    for (const aliasName of aliasNames) aliasToCanonicalEnum.set(aliasName, canonical);
+  }
   for (const [dirName, names] of enumSymbolsByDir) {
     const key = `src/${ctx.namespace}/${dirName}/models`;
     if (!symbolsByDir.has(key)) symbolsByDir.set(key, []);
-    for (const name of names) symbolsByDir.get(key)!.push({ name });
+    for (const name of names) {
+      // Reference an enum (or its compat alias) from the barrel only when its
+      // per-enum file exists on disk after the run. A brand-new out-of-scope
+      // enum whose file is never emitted must NOT be referenced.
+      const enumFilePath = `${key}/${fileName(name)}.py`;
+      const scopeName = aliasToCanonicalEnum.get(name) ?? name;
+      if (fileExistsAfterRun(enumFilePath, isEnumInScope(scopeName, ctx), ctx)) {
+        symbolsByDir.get(key)!.push({ name });
+      }
+    }
+  }
+
+  // Scoped runs: retain barrel entries for per-item files still on disk (prior
+  // manifest) that the current spec no longer produces — e.g. a model/enum
+  // renamed or removed for an out-of-scope service. Out-of-scope code we did
+  // not regenerate may still `from .<base> import X`, so dropping it would
+  // break the import. We can't recover the original class name from the
+  // basename, so re-export the module wholesale with `import *`. A full run
+  // (priorManifestBasenames returns []) yields nothing here. De-duped against
+  // files already referenced by an emitted/enum symbol in the same dir.
+  //
+  // Candidate dirs are every `src/<ns>/<dir>/models` that appears in the prior
+  // manifest (a dir may have no in-scope items yet still hold on-disk files
+  // referenced by stale out-of-scope code).
+  const manifestModelDirs = new Set<string>();
+  for (const p of ctx.priorTargetManifestPaths ?? []) {
+    const m = p.match(new RegExp(`^(src/${ctx.namespace}/[^/]+/models)/[^/]+\\.py$`));
+    if (m) manifestModelDirs.add(m[1]);
+  }
+  for (const dirPath of manifestModelDirs) {
+    if (!symbolsByDir.has(dirPath)) symbolsByDir.set(dirPath, []);
+    const referencedBasenames = new Set<string>();
+    for (const sym of symbolsByDir.get(dirPath)!) {
+      if (sym.reExport || sym.retainBasename) continue;
+      referencedBasenames.add(symbolToFile.get(sym.name) ?? fileName(sym.name));
+    }
+    for (const base of priorManifestBasenames(ctx, dirPath, '.py', new Set(['__init__']))) {
+      if (referencedBasenames.has(base)) continue;
+      referencedBasenames.add(base);
+      symbolsByDir.get(dirPath)!.push({ name: base, retainBasename: base });
+    }
   }
 
   // Backwards-compat re-exports: every relocated model is also re-exported
@@ -561,6 +642,12 @@ export function generateModels(models: Model[], ctx: EmitterContext): GeneratedF
     // Use `import X as X` syntax for explicit re-exports (required by pyright strict)
     const importLines: string[] = [];
     for (const sym of uniqueSymbols) {
+      if (sym.retainBasename) {
+        // On-disk module renamed/removed from the spec: re-export it wholesale
+        // since its concrete symbol names are unknown from the manifest alone.
+        importLines.push(`from .${sym.retainBasename} import *  # noqa: F401,F403`);
+        continue;
+      }
       const cls = className(sym.name);
       if (sym.reExport) {
         importLines.push(
@@ -584,9 +671,15 @@ export function generateModels(models: Model[], ctx: EmitterContext): GeneratedF
     // which includes both the resource class re-export and model star import.
     if (!serviceDirModelPaths.has(dirPath)) {
       const parentDir = dirPath.replace(/\/models$/, '');
-      const reExports = uniqueSymbols
-        .map((sym) => `from .models import ${className(sym.name)} as ${className(sym.name)}`)
-        .join('\n');
+      const reExports = [
+        ...new Set(
+          uniqueSymbols.map((sym) =>
+            sym.retainBasename
+              ? 'from .models import *  # noqa: F401,F403'
+              : `from .models import ${className(sym.name)} as ${className(sym.name)}`,
+          ),
+        ),
+      ].join('\n');
       files.push({
         path: `${parentDir}/__init__.py`,
         content: reExports,

package/src/python/resources.ts

@@ -30,7 +30,7 @@ import {
   buildResolvedLookup,
   lookupMethodName,
   lookupResolved,
-  groupByMount,
+  scopedMountGroups,
   getOpDefaults,
   getOpInferFromClient,
   buildHiddenParams as buildHiddenParamsShared,
@@ -1056,12 +1056,12 @@ export function generateResources(services: Service[], ctx: EmitterContext): Gen
   const resolvedLookup = buildResolvedLookup(ctx);
   const files: GeneratedFile[] = [];
   const mountDirMap = buildMountDirMap(ctx);
-  const mountGroups = groupByMount(ctx);
+  const mountGroups = scopedMountGroups(ctx);
 
   // Build mount group entries. When resolved operations are available, group by
   // mount target. Otherwise fall back to one group per service (for tests).
   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: resolveClassName(s, ctx), operations: s.operations }));
 

package/src/python/tests.ts

@@ -25,11 +25,13 @@ import { generateFixtures, generateModelFixture } from './fixtures.js';
 import { isListWrapperModel, isListMetadataModel } from './models.js';
 import { collectNonPaginatedResponseModelNames, collectReferencedListMetadataModels } from '../shared/model-utils.js';
 import {
-  groupByMount,
+  scopedMountGroups,
   buildResolvedLookup,
   lookupResolved,
   buildHiddenParams,
   collectGroupedParamNames,
+  isModelInScope,
+  fileExistsAfterRun,
 } from '../shared/resolved-ops.js';
 import { resolveWrapperParams } from '../shared/wrapper-utils.js';
 import { pythonLiteral } from './wrappers.js';
@@ -100,7 +102,7 @@ export function generateTests(spec: ApiSpec, ctx: EmitterContext): GeneratedFile
   const files: GeneratedFile[] = [];
 
   // Generate fixture JSON files
-  const fixtures = generateFixtures(spec);
+  const fixtures = generateFixtures(spec, ctx);
   for (const fixture of fixtures) {
     files.push({
       path: fixture.path,
@@ -118,9 +120,9 @@ export function generateTests(spec: ApiSpec, ctx: EmitterContext): GeneratedFile
   const accessPaths = buildServiceAccessPaths(spec.services, ctx);
 
   // Generate per-mount-target test files (merges all sub-services into one file)
-  const mountGroups = groupByMount(ctx);
+  const mountGroups = scopedMountGroups(ctx);
   const testEntries: Array<{ name: string; operations: Operation[]; resolvedOps?: ResolvedOperation[] }> =
-    mountGroups.size > 0
+    mountGroups.size > 0 || ctx.scopedServices?.size
       ? [...mountGroups].map(([name, group]) => ({
           name,
           operations: group.operations,
@@ -1461,22 +1463,39 @@ function generateModelRoundTripTests(spec: ApiSpec, ctx: EmitterContext): Genera
 
   const nonPaginatedRefs = collectNonPaginatedResponseModelNames(spec.services);
   const listMetadataNeeded = collectReferencedListMetadataModels(spec.models, nonPaginatedRefs);
-  const models = spec.models.filter(
-    (m) =>
-      !(isListWrapperModel(m) && !nonPaginatedRefs.has(m.name)) &&
-      !(isListMetadataModel(m) && !listMetadataNeeded.has(m.name)) &&
-      !requestOnlyModelNames.has(m.name),
-  );
-  if (models.length === 0) return null;
 
   // The round-trip test imports models from their *natural* (pre-relocation)
   // service so existing callers keep working — those imports resolve via the
   // BC re-exports that the model emitter writes into each service barrel.
-  const modelToService = computeSchemaPlacement(spec, ctx).originalModelToService;
+  const placement = computeSchemaPlacement(spec, ctx);
+  const modelToService = placement.originalModelToService;
+  // The per-model FILE is written to the RELOCATED dir; use it to compute the
+  // gate's relPath so it lines up with the prior manifest.
+  const relocatedModelToService = placement.modelToService;
   const roundTripDirMap = buildMountDirMap(ctx);
   const resolveDir = (irService: string | undefined) =>
     irService ? (roundTripDirMap.get(irService) ?? 'common') : 'common';
 
+  // Scoped runs: the round-trip test must only reference a model whose per-model
+  // file exists on disk after the run (in-scope, or already present from the
+  // prior manifest). A brand-new out-of-scope model is excluded — its file is
+  // never emitted, so importing it would raise ModuleNotFoundError. A full run
+  // keeps every model (fileExistsAfterRun ⇒ true).
+  const modelFileExists = (name: string): boolean => {
+    const dir = resolveDir(relocatedModelToService.get(name));
+    const path = `src/${ctx.namespace}/${dir}/models/${fileName(name)}.py`;
+    return fileExistsAfterRun(path, isModelInScope(name, ctx), ctx);
+  };
+
+  const models = spec.models.filter(
+    (m) =>
+      !(isListWrapperModel(m) && !nonPaginatedRefs.has(m.name)) &&
+      !(isListMetadataModel(m) && !listMetadataNeeded.has(m.name)) &&
+      !requestOnlyModelNames.has(m.name) &&
+      modelFileExists(m.name),
+  );
+  if (models.length === 0) return null;
+
   const lines: string[] = [];
   lines.push('"""Model round-trip tests: from_dict(to_dict()) preserves data."""');
   lines.push('');

package/src/ruby/enums.ts

@@ -1,6 +1,7 @@
 import type { Enum, EmitterContext, GeneratedFile } from '@workos/oagen';
 import { toUpperSnakeCase } from '@workos/oagen';
 import { className, fileName } from './naming.js';
+import { isEnumInScope } from '../shared/resolved-ops.js';
 
 /**
  * Generate Ruby enum class files.
@@ -9,7 +10,6 @@ import { className, fileName } from './naming.js';
  * and a frozen `ALL` array of all values.
  */
 export function generateEnums(enums: Enum[], ctx: EmitterContext): GeneratedFile[] {
-  void ctx;
   if (enums.length === 0) return [];
 
   const files: GeneratedFile[] = [];
@@ -17,6 +17,9 @@ export function generateEnums(enums: Enum[], ctx: EmitterContext): GeneratedFile
 
   for (const enumDef of enums) {
     const cls = className(enumDef.name);
+    // FR-1.4: write the per-enum file only when in scope. Out-of-scope enum
+    // files are left untouched on disk; Zeitwerk autoloads them by path.
+    const enumInScope = isEnumInScope(enumDef.name, ctx);
 
     // If this enum duplicates another (by value set), emit a Ruby constant
     // alias. Zeitwerk autoloads the canonical when the alias is first
@@ -30,12 +33,14 @@ export function generateEnums(enums: Enum[], ctx: EmitterContext): GeneratedFile
       lines.push(`    ${cls} = ${canonicalCls}`);
       lines.push('  end');
       lines.push('end');
-      files.push({
-        path: `lib/workos/types/${fileName(enumDef.name)}.rb`,
-        content: lines.join('\n'),
-        integrateTarget: true,
-        overwriteExisting: true,
-      });
+      if (enumInScope) {
+        files.push({
+          path: `lib/workos/types/${fileName(enumDef.name)}.rb`,
+          content: lines.join('\n'),
+          integrateTarget: true,
+          overwriteExisting: true,
+        });
+      }
       continue;
     }
 
@@ -60,12 +65,14 @@ export function generateEnums(enums: Enum[], ctx: EmitterContext): GeneratedFile
       lines.push('    end');
       lines.push('  end');
       lines.push('end');
-      files.push({
-        path: `lib/workos/types/${fileName(enumDef.name)}.rb`,
-        content: lines.join('\n'),
-        integrateTarget: true,
-        overwriteExisting: true,
-      });
+      if (enumInScope) {
+        files.push({
+          path: `lib/workos/types/${fileName(enumDef.name)}.rb`,
+          content: lines.join('\n'),
+          integrateTarget: true,
+          overwriteExisting: true,
+        });
+      }
       continue;
     }
 
@@ -108,12 +115,14 @@ export function generateEnums(enums: Enum[], ctx: EmitterContext): GeneratedFile
     lines.push('  end');
     lines.push('end');
 
-    files.push({
-      path: `lib/workos/types/${fileName(enumDef.name)}.rb`,
-      content: lines.join('\n'),
-      integrateTarget: true,
-      overwriteExisting: true,
-    });
+    if (enumInScope) {
+      files.push({
+        path: `lib/workos/types/${fileName(enumDef.name)}.rb`,
+        content: lines.join('\n'),
+        integrateTarget: true,
+        overwriteExisting: true,
+      });
+    }
   }
 
   return files;

package/src/ruby/models.ts

@@ -6,6 +6,7 @@ import {
   isListMetadataModel,
   collectNonPaginatedResponseModelNames,
 } from '../shared/model-utils.js';
+import { isModelInScope } from '../shared/resolved-ops.js';
 
 /** Folder under lib/workos/ for models not owned by any service. */
 export const SHARED_MODEL_DIR = 'shared';
@@ -119,12 +120,17 @@ export function generateModels(models: Model[], ctx: EmitterContext): GeneratedF
       lines.push('module WorkOS');
       lines.push(`  ${cls} = ${canonCls}`);
       lines.push('end');
-      files.push({
-        path: `lib/workos/${dirFor(model.name)}/${file}.rb`,
-        content: lines.join('\n'),
-        integrateTarget: true,
-        overwriteExisting: true,
-      });
+      // FR-1.4: write the per-model file only when in scope. Zeitwerk autoloads
+      // by path, so there is no barrel to keep in sync; out-of-scope alias files
+      // are left untouched on disk.
+      if (isModelInScope(model.name, ctx)) {
+        files.push({
+          path: `lib/workos/${dirFor(model.name)}/${file}.rb`,
+          content: lines.join('\n'),
+          integrateTarget: true,
+          overwriteExisting: true,
+        });
+      }
       continue;
     }
 
@@ -214,12 +220,17 @@ export function generateModels(models: Model[], ctx: EmitterContext): GeneratedF
     lines.push('  end');
     lines.push('end');
 
-    files.push({
-      path: `lib/workos/${dirFor(model.name)}/${file}.rb`,
-      content: lines.join('\n'),
-      integrateTarget: true,
-      overwriteExisting: true,
-    });
+    // FR-1.4: write the per-model file only when in scope. Zeitwerk autoloads by
+    // path, so there is no barrel to keep in sync; out-of-scope model files are
+    // left untouched on disk.
+    if (isModelInScope(model.name, ctx)) {
+      files.push({
+        path: `lib/workos/${dirFor(model.name)}/${file}.rb`,
+        content: lines.join('\n'),
+        integrateTarget: true,
+        overwriteExisting: true,
+      });
+    }
   }
 
   return files;

package/src/ruby/rbi.ts

@@ -15,6 +15,8 @@ import {
 import {
   buildResolvedLookup,
   groupByMount,
+  isMountInScope,
+  isModelInScope,
   lookupResolved,
   buildHiddenParams,
   collectGroupedParamNames,
@@ -116,12 +118,17 @@ export function generateRbiFiles(spec: ApiSpec, ctx: EmitterContext): GeneratedF
     lines.push('  end');
     lines.push('end');
 
-    files.push({
-      path: `rbi/workos/${fileName(model.name)}.rbi`,
-      content: lines.join('\n'),
-      integrateTarget: true,
-      overwriteExisting: true,
-    });
+    // FR-1.4: write the per-model .rbi only when in scope. The client.rbi
+    // aggregate (section 3) stays on the full set so sigs for out-of-scope
+    // services whose .rb/.rbi still exist keep resolving.
+    if (isModelInScope(model.name, ctx)) {
+      files.push({
+        path: `rbi/workos/${fileName(model.name)}.rbi`,
+        content: lines.join('\n'),
+        integrateTarget: true,
+        overwriteExisting: true,
+      });
+    }
   }
 
   // 2. Generate service RBI files
@@ -137,6 +144,10 @@ export function generateRbiFiles(spec: ApiSpec, ctx: EmitterContext): GeneratedF
   const exportedClasses = buildExportedClassNameSet(ctx);
 
   for (const [mountTarget, group] of groups) {
+    // Scoped run: emit per-service .rbi only for selected mount targets. The
+    // client.rbi aggregate loop below intentionally stays on the FULL `groups`
+    // set so it keeps emitting sigs for every service whose .rb still exists.
+    if (!isMountInScope(mountTarget, ctx)) continue;
     const resolvedTarget = resolveServiceTarget(mountTarget, exportedClasses);
     const cls = className(resolvedTarget);
     const lines: string[] = [];

package/src/ruby/resources.ts

@@ -15,7 +15,7 @@ import { mapTypeRefForYard } from './type-map.js';
 import {
   buildResolvedLookup,
   lookupResolved,
-  groupByMount,
+  scopedMountGroups,
   getOpDefaults,
   getOpInferFromClient,
   buildHiddenParams,
@@ -33,7 +33,7 @@ import { buildGroupOwnerMap, collectVariantsForMountTarget, emitInlineVariantCla
 export function generateResources(services: Service[], ctx: EmitterContext): GeneratedFile[] {
   const files: GeneratedFile[] = [];
 
-  const groups = groupByMount(ctx);
+  const groups = scopedMountGroups(ctx);
   const lookup = buildResolvedLookup(ctx);
   const modelNames = new Set(ctx.spec.models.map((m) => m.name));
   const enumNames = new Set(ctx.spec.enums.map((e) => e.name));

package/src/ruby/tests.ts

@@ -1,4 +1,5 @@
 import type { ApiSpec, EmitterContext, GeneratedFile, Model, Operation, ResolvedWrapper, TypeRef } from '@workos/oagen';
+import { assignModelsToServices } from '@workos/oagen';
 import {
   className,
   fileName,
@@ -10,15 +11,19 @@ import {
   resolveMethodName,
   buildExportedClassNameSet,
   resolveServiceTarget,
+  buildMountDirMap,
 } from './naming.js';
 import {
   buildResolvedLookup,
-  groupByMount,
+  scopedMountGroups,
   lookupResolved,
   buildHiddenParams,
   collectBodyFieldTypes,
+  isModelInScope,
+  fileExistsAfterRun,
 } from '../shared/resolved-ops.js';
 import { isListWrapperModel, isListMetadataModel } from '../shared/model-utils.js';
+import { classifyUnassignedModel } from './models.js';
 import { resolveWrapperParams } from '../shared/wrapper-utils.js';
 import { buildGroupOwnerMap, pickVariantParamType } from './parameter-groups.js';
 
@@ -34,7 +39,7 @@ import { buildGroupOwnerMap, pickVariantParamType } from './parameter-groups.js'
 export function generateTests(spec: ApiSpec, ctx: EmitterContext): GeneratedFile[] {
   const files: GeneratedFile[] = [];
 
-  const groups = groupByMount(ctx);
+  const groups = scopedMountGroups(ctx);
   const models = spec.models as Model[];
   const modelByName = new Map<string, Model>();
   for (const m of models) modelByName.set(m.name, m);
@@ -203,7 +208,7 @@ export function generateTests(spec: ApiSpec, ctx: EmitterContext): GeneratedFile
     });
   }
 
-  files.push(generateModelRoundTripTest(spec));
+  files.push(generateModelRoundTripTest(spec, ctx));
 
   return files;
 }
@@ -212,8 +217,19 @@ export function generateTests(spec: ApiSpec, ctx: EmitterContext): GeneratedFile
  * Emit test/workos/model_round_trip_test.rb that round-trips every non-wrapper
  * model through `.new(json)` and `.to_json`, asserting the result is a Hash and
  * that required fields appear with the seeded values.
+ *
+ * This is a whole-suite AGGREGATE: it references `WorkOS::<Class>` for every
+ * model. Under a scoped (`--services`) run only the selected services' per-model
+ * `.rb` files are (re)written, so a test referencing a brand-new out-of-scope
+ * model whose file was never emitted would raise `NameError: uninitialized
+ * constant`. Each per-model test is therefore gated by {@link fileExistsAfterRun}
+ * on the SAME path `models.ts` writes (`lib/workos/<dir>/<file>.rb`): emit only
+ * when that file will exist on disk after the run — in-scope (emitted this run)
+ * OR already present from a prior run (`priorTargetManifestPaths`). Brand-new
+ * out-of-scope models are excluded; renamed/removed-but-on-disk models are
+ * retained. A full run (scoping inert) keeps every model.
  */
-function generateModelRoundTripTest(spec: ApiSpec): GeneratedFile {
+function generateModelRoundTripTest(spec: ApiSpec, ctx: EmitterContext): GeneratedFile {
   const lines: string[] = [];
   lines.push(`require 'test_helper'`);
   lines.push('');
@@ -223,7 +239,24 @@ function generateModelRoundTripTest(spec: ApiSpec): GeneratedFile {
   const enumNames = new Set(spec.enums.map((e) => e.name));
   const emitted = new Set<string>();
 
+  // Resolve each model's per-model file path EXACTLY as models.ts does, so the
+  // scope gate keys on the same path the per-model FILE writer uses.
+  const modelToService = assignModelsToServices(models, ctx.spec.services, ctx.modelHints);
+  const mountDirMap = buildMountDirMap(ctx);
+  const dirFor = (modelName: string): string => {
+    const service = modelToService.get(modelName);
+    if (!service) return classifyUnassignedModel(modelName);
+    return mountDirMap.get(service) ?? classifyUnassignedModel(modelName);
+  };
+
   for (const model of models) {
+    // Skip models whose per-model `.rb` file will NOT exist on disk after this
+    // run (brand-new + out-of-scope under `--services`). Without this gate the
+    // aggregate would reference an undefined constant. The path mirrors
+    // models.ts's `lib/workos/${dirFor}/${fileName}.rb`.
+    const modelFilePath = `lib/workos/${dirFor(model.name)}/${fileName(model.name)}.rb`;
+    if (!fileExistsAfterRun(modelFilePath, isModelInScope(model.name, ctx), ctx)) continue;
+
     // Avoid duplicate test names when two IR model names collapse to the same
     // snake_case file name (we use the file name as the test suffix).
     const fileBase = fileName(model.name);