@workos/oagen-emitters 0.18.4 → 0.19.1

package/src/go/flat-merge.ts

@@ -0,0 +1,253 @@
+import type { EmitterContext } from '@workos/oagen';
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { isScopedRun } from '../shared/resolved-ops.js';
+
+/**
+ * Scoped-run reconciliation for Go's FLAT aggregate files.
+ *
+ * Unlike Rust (one source file per model/enum), Go inlines every type into a
+ * single `models.go` / `enums.go` and every webhook event into one
+ * `pkg/events/events.go`. A scoped (`--services`) run regenerates these flat
+ * files from the FULL new spec, which breaks scoping two ways:
+ *
+ *   1. ADDITION — a brand-new model/enum/event that belongs to an OUT-OF-SCOPE
+ *      service gets inlined, so a scoped batch leaks unrelated changes
+ *      (violates Option B: a scoped batch should contain ONLY the selected
+ *      service's changes).
+ *   2. REMOVAL / RENAME — a type the new spec renamed away (e.g.
+ *      `OrganizationDomainStandAlone` → `OrganizationDomain`) is no longer
+ *      produced, so its block vanishes from `models.go`; but an out-of-scope
+ *      resource file (NOT regenerated this run) still references the old name →
+ *      `undefined: OrganizationDomainStandAlone` and the package won't compile.
+ *
+ * The fix mirrors the Rust principle: in a scoped run, only the selected
+ * services' types should reflect the new spec; everything else must be
+ * preserved exactly as it is on disk. Because Go's manifest records the flat
+ * FILE path (`models.go`) and not per-type paths, we recover the per-type
+ * "present before" signal by reading the prior file from `ctx.outputDir`
+ * (the emitter already reads `go.mod` from there in tests.ts). A type/const
+ * block is then reconciled as:
+ *
+ *   - KEEP a freshly generated block iff it is IN-SCOPE or its name was present
+ *     in the prior file  → drops brand-new out-of-scope additions (fix #1).
+ *   - CARRY OVER verbatim any prior block whose name(s) the new spec no longer
+ *     produces                          → retains renamed/removed types (fix #2).
+ *
+ * A full (non-scoped) run skips all of this and emits the new spec verbatim.
+ */
+
+/** A single named top-level declaration block in a flat Go file. */
+export interface NamedBlock {
+  /** Every type/const name this block declares (a batched `type (...)` alias block declares several). */
+  names: string[];
+  /** Verbatim text of the block (no trailing blank line). */
+  text: string;
+  /**
+   * Whether the block's owning model/enum is in scope this run. Set by the
+   * generator for freshly produced blocks; omitted (treated as false) for
+   * blocks parsed from the prior on-disk file.
+   */
+  inScope?: boolean;
+}
+
+/** Read the prior on-disk content of a generated file, or null when unavailable. */
+export function readPriorFile(relPath: string, ctx: EmitterContext): string | null {
+  if (!ctx.outputDir) return null;
+  const abs = resolve(ctx.outputDir, relPath);
+  if (!existsSync(abs)) return null;
+  try {
+    return readFileSync(abs, 'utf-8');
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Parse a flat Go file into the set of top-level type names it declares, mapped
+ * to the verbatim text of each declaration block (including its leading doc
+ * comment). Used to recover the per-type "present before" signal a scoped run
+ * needs. Recognizes the exact shapes the Go emitter produces:
+ *   - `type Name struct { ... }`        (brace-balanced)
+ *   - `type Name = Other`               (single-line alias)
+ *   - `type Name string` + `const ( ... )`  (string enum)
+ *   - `type ( A = X\n B = X )`          (batched alias block — declares many)
+ * The leading `package` clause and any standalone trailing `const (...)` block
+ * (e.g. the events file) are returned separately by {@link parseFlatGoBlocks}.
+ */
+export function parseFlatGoBlocks(content: string): {
+  blocks: NamedBlock[];
+  byName: Map<string, NamedBlock>;
+} {
+  const lines = content.split('\n');
+  const blocks: NamedBlock[] = [];
+  let i = 0;
+
+  // Skip the generated header / package clause / leading blanks; those are
+  // re-emitted by the generator, not carried over.
+  while (i < lines.length) {
+    const t = lines[i].trim();
+    if (t.startsWith('package ') || t === '' || t.startsWith('// Code generated')) {
+      i++;
+      continue;
+    }
+    break;
+  }
+
+  while (i < lines.length) {
+    // Collect a leading run of `//` doc-comment lines.
+    const start = i;
+    while (i < lines.length && lines[i].trim().startsWith('//')) i++;
+
+    if (i >= lines.length) break;
+    const line = lines[i];
+    const trimmed = line.trim();
+
+    if (trimmed === 'type (') {
+      // Batched alias block: `type (` ... `)`. Each inner line is `Name = Other`.
+      const names: string[] = [];
+      i++;
+      while (i < lines.length && lines[i].trim() !== ')') {
+        const m = lines[i].trim().match(/^(\w+)\s*=/);
+        if (m) names.push(m[1]);
+        i++;
+      }
+      i++; // consume ')'
+      blocks.push({ names, text: lines.slice(start, i).join('\n') });
+    } else if (/^type\s+(\w+)\s+struct\s*\{/.test(trimmed)) {
+      const name = trimmed.match(/^type\s+(\w+)/)![1];
+      // Brace-balanced struct body.
+      let depth = 0;
+      let sawOpen = false;
+      while (i < lines.length) {
+        for (const ch of lines[i]) {
+          if (ch === '{') {
+            depth++;
+            sawOpen = true;
+          } else if (ch === '}') depth--;
+        }
+        i++;
+        if (sawOpen && depth === 0) break;
+      }
+      blocks.push({ names: [name], text: lines.slice(start, i).join('\n') });
+    } else if (/^type\s+(\w+)\s+\w+\s+string\b/.test(trimmed) || /^type\s+(\w+)\s+string\b/.test(trimmed)) {
+      // String enum: `type Name string` possibly followed by a `const ( ... )`.
+      const name = trimmed.match(/^type\s+(\w+)/)![1];
+      i++;
+      // Skip blank lines then an optional const block.
+      let j = i;
+      while (j < lines.length && lines[j].trim() === '') j++;
+      if (j < lines.length && lines[j].trim() === 'const (') {
+        i = j;
+        while (i < lines.length && lines[i].trim() !== ')') i++;
+        i++; // consume ')'
+      }
+      blocks.push({ names: [name], text: lines.slice(start, i).join('\n') });
+    } else if (/^type\s+(\w+)\s*=/.test(trimmed)) {
+      // Single-line alias: `type Name = Other`.
+      const name = trimmed.match(/^type\s+(\w+)/)![1];
+      i++;
+      blocks.push({ names: [name], text: lines.slice(start, i).join('\n') });
+    } else {
+      // Unrecognized top-level construct (e.g. a standalone `const (...)`).
+      // Skip the line so parsing stays robust; such constructs are never
+      // carried over by name.
+      i++;
+    }
+    // Skip trailing blank lines between blocks (re-added on reassembly).
+    while (i < lines.length && lines[i].trim() === '') i++;
+  }
+
+  const byName = new Map<string, NamedBlock>();
+  for (const b of blocks) for (const n of b.names) byName.set(n, b);
+  return { blocks, byName };
+}
+
+/**
+ * Reconcile freshly generated named blocks against the prior on-disk file for a
+ * scoped run. Returns the ordered list of block texts to emit. See file-level
+ * docs for the keep/carry-over rules. In a scoped run a block is emitted as:
+ *   - IN-SCOPE                  → the freshly generated text (apply the new spec).
+ *   - out-of-scope, existed before → the PRIOR on-disk text, FROZEN, so an
+ *     unrelated change to that type in the same spec delta doesn't leak into a
+ *     scoped batch (Option B). (Falls back to fresh text only when the new
+ *     block's names span multiple prior blocks — a batched-alias regrouping —
+ *     which can't be frozen 1:1.)
+ *   - out-of-scope, brand-new   → dropped (the addition that broke the build).
+ * Then any prior block the new spec no longer produces at all is carried over
+ * verbatim (renamed/removed types still referenced by un-regenerated code).
+ *
+ * @param newBlocks    Per-type blocks the current spec produced (in emit order),
+ *                     each tagged with `inScope`.
+ * @param relPath      Flat file path (e.g. `models.go`) for reading the prior file.
+ * @param ctx          Emitter context (provides `outputDir` + scope sets).
+ * @param alsoEmitted  Names this file emits OUTSIDE `newBlocks` (e.g. the fixed
+ *                     `PaginationParams` struct). They must be excluded from the
+ *                     carry-over, or the prior copy would be re-appended and
+ *                     redeclare the separately-emitted one.
+ */
+export function reconcileFlatBlocks(
+  newBlocks: NamedBlock[],
+  relPath: string,
+  ctx: EmitterContext,
+  alsoEmitted: Set<string> = new Set<string>(),
+): string[] {
+  // Full run: emit everything the new spec produced, unchanged.
+  if (!isScopedRun(ctx)) return newBlocks.map((b) => b.text);
+
+  const prior = readPriorFile(relPath, ctx);
+  // No prior file to reconcile against (first generation / missing output dir):
+  // fall back to scope-only gating so we never leak brand-new out-of-scope
+  // types, but there's nothing on disk to retain.
+  const priorParsed = prior ? parseFlatGoBlocks(prior) : { blocks: [], byName: new Map<string, NamedBlock>() };
+
+  const out: string[] = [];
+  const emittedNames = new Set<string>();
+
+  for (const block of newBlocks) {
+    if (block.inScope) {
+      out.push(block.text);
+      for (const n of block.names) emittedNames.add(n);
+      continue;
+    }
+    // Out of scope: freeze to the prior on-disk text when this block maps 1:1
+    // to a single prior block; that keeps an out-of-scope type byte-identical to
+    // disk even if the new spec changed it. A brand-new out-of-scope block has
+    // no prior block → it is dropped.
+    const priorBlocks = block.names.map((n) => priorParsed.byName.get(n)).filter((b): b is NamedBlock => !!b);
+    const uniquePrior = new Set(priorBlocks);
+    if (uniquePrior.size === 1) {
+      const pb = priorBlocks[0];
+      if (!pb.names.some((n) => emittedNames.has(n))) {
+        out.push(pb.text);
+        for (const n of pb.names) emittedNames.add(n);
+      }
+    } else if (uniquePrior.size > 1) {
+      // A regrouping spread this out-of-scope block's names across several prior
+      // blocks. NEVER regenerate out-of-scope content (the fresh text could
+      // re-point an alias at a renamed canonical the scoped run didn't emit);
+      // instead freeze every distinct prior block verbatim. All names are
+      // on-disk here (the generator only puts in-scope ∪ on-disk names in an
+      // out-of-scope block), so this fully retains them.
+      for (const pb of uniquePrior) {
+        if (pb.names.some((n) => emittedNames.has(n))) continue;
+        out.push(pb.text);
+        for (const n of pb.names) emittedNames.add(n);
+      }
+    }
+    // uniquePrior.size === 0 → brand-new out-of-scope → drop.
+  }
+
+  // Carry over prior blocks the new spec no longer produces at all (renamed /
+  // removed types still referenced by out-of-scope, un-regenerated code),
+  // excluding any name this file emits elsewhere (e.g. PaginationParams).
+  for (const block of priorParsed.blocks) {
+    if (block.names.some((n) => alsoEmitted.has(n))) continue;
+    if (block.names.every((n) => !emittedNames.has(n))) {
+      out.push(block.text);
+      for (const n of block.names) emittedNames.add(n);
+    }
+  }
+
+  return out;
+}

package/src/go/models.ts

@@ -3,6 +3,8 @@ import { walkTypeRef } from '@workos/oagen';
 import { mapTypeRef } from './type-map.js';
 import { className, domainFieldName } from './naming.js';
 import { lowerFirstForDoc, fieldDocComment, articleFor } from '../shared/naming-utils.js';
+import { isModelInScope, isScopedRun } from '../shared/resolved-ops.js';
+import { reconcileFlatBlocks, readPriorFile, parseFlatGoBlocks, type NamedBlock } from './flat-merge.js';
 
 // Import and re-export shared model detection utilities
 import {
@@ -114,6 +116,17 @@ export function generateModels(models: Model[], ctx: EmitterContext): GeneratedF
   // Pick canonical for each duplicate group.
   // Empty structs (hash '') are now properly populated by oneOf flattening,
   // so we still skip aliasing them to avoid aliasing truly empty structs.
+  // For the batched-alias block below: in a scoped run, only emit an alias that
+  // is in scope OR already on disk (present in the prior models.go). Otherwise a
+  // `>= 5` structural group containing a single in-scope alias would drag every
+  // brand-new out-of-scope alias in the group into the file. A full run keeps
+  // every alias (isScopedRun is false).
+  const priorModelNames = isScopedRun(ctx)
+    ? new Set(parseFlatGoBlocks(readPriorFile('models.go', ctx) ?? '').blocks.flatMap((b) => b.names))
+    : new Set<string>();
+  const aliasEmitted = (name: string): boolean =>
+    !isScopedRun(ctx) || isModelInScope(name, ctx) || priorModelNames.has(className(name));
+
   const aliasOf = new Map<string, string>();
   for (const [hash, names] of hashGroups) {
     if (names.length <= 1) continue;
@@ -125,6 +138,30 @@ export function generateModels(models: Model[], ctx: EmitterContext): GeneratedF
     }
   }
 
+  // The structural-dedup canonical is chosen alphabetically, independent of
+  // scope, so an in-scope alias can point at a canonical that is itself out of
+  // scope and brand-new — which the reconciler would drop, leaving the alias
+  // `type InScopeModel = Canonical` dangling (`undefined: Canonical`). Force-
+  // retain any canonical referenced by an in-scope alias. The canonical is
+  // structurally identical to that alias, so its field types are reachable from
+  // the in-scope service and therefore also emitted. In a mixed batched-alias
+  // block the in-scope member forces the shared canonical, covering its on-disk
+  // siblings that emit fresh in the same block.
+  const forcedCanonicals = new Set<string>();
+  if (isScopedRun(ctx)) {
+    for (const [aliasName, canonical] of aliasOf) {
+      if (isModelInScope(aliasName, ctx)) forcedCanonicals.add(canonical);
+    }
+  }
+
+  // Build one NamedBlock per emitted model type. In a scoped run these blocks
+  // are reconciled against the prior models.go (see reconcileFlatBlocks): blocks
+  // for out-of-scope models that didn't exist before are dropped, and prior
+  // blocks for renamed/removed types are carried over verbatim. A full run emits
+  // every block unchanged. Tracking the IR model name(s) per block (a batched
+  // alias group declares several) is what lets the reconciler gate by scope.
+  const modelBlocks: NamedBlock[] = [];
+
   const batchedAliases = new Set<string>();
   for (const model of models) {
     if (skipAsListWrapper(model) || skipAsListMetadata(model)) continue;
@@ -149,38 +186,51 @@ export function generateModels(models: Model[], ctx: EmitterContext): GeneratedF
       const groupNames = hashGroups.get(hash) ?? [];
       const aliases = groupNames.filter((n) => aliasOf.has(n) && className(n) !== className(aliasOf.get(n)!));
 
+      const blockLines: string[] = [];
+      const blockNames: string[] = [];
+      let blockInScope = false;
       if (aliases.length >= 5) {
-        // Batch emit all aliases for this group at once
+        // Mark the whole group consumed so its members aren't re-emitted as
+        // singles, but only EMIT aliases that are in scope or already on disk —
+        // dropping brand-new out-of-scope aliases (scope leak fix). On-disk
+        // aliases are retained so out-of-scope code that references them still
+        // compiles.
         for (const aliasName of aliases) {
           batchedAliases.add(aliasName);
         }
-        lines.push(`// The following types are structurally identical to ${canonicalStruct}.`);
-        lines.push('type (');
-        for (const aliasName of aliases) {
-          lines.push(`\t${className(aliasName)} = ${canonicalStruct}`);
+        const emittedAliases = aliases.filter(aliasEmitted);
+        if (emittedAliases.length === 0) continue;
+        blockLines.push(`// The following types are structurally identical to ${canonicalStruct}.`);
+        blockLines.push('type (');
+        for (const aliasName of emittedAliases) {
+          blockLines.push(`\t${className(aliasName)} = ${canonicalStruct}`);
+          blockNames.push(className(aliasName));
+          if (isModelInScope(aliasName, ctx)) blockInScope = true;
         }
-        lines.push(')');
-        lines.push('');
+        blockLines.push(')');
       } else {
-        lines.push(`// ${structName} is an alias for ${canonicalStruct}.`);
-        lines.push(`type ${structName} = ${canonicalStruct}`);
-        lines.push('');
+        blockLines.push(`// ${structName} is an alias for ${canonicalStruct}.`);
+        blockLines.push(`type ${structName} = ${canonicalStruct}`);
+        blockNames.push(structName);
+        if (isModelInScope(model.name, ctx)) blockInScope = true;
       }
+      modelBlocks.push({ names: blockNames, text: blockLines.join('\n'), inScope: blockInScope });
       continue;
     }
 
     // Emit struct
+    const blockLines: string[] = [];
     if (model.description) {
       const descLines = model.description.split('\n').filter((l) => l.trim());
-      lines.push(`// ${structName} ${lowerFirst(descLines[0])}`);
+      blockLines.push(`// ${structName} ${lowerFirst(descLines[0])}`);
       for (let i = 1; i < descLines.length; i++) {
-        lines.push(`// ${descLines[i].trim()}`);
+        blockLines.push(`// ${descLines[i].trim()}`);
       }
     } else {
       const humanized = humanize(model.name);
-      lines.push(`// ${structName} represents ${articleFor(humanized)} ${humanized}.`);
+      blockLines.push(`// ${structName} represents ${articleFor(humanized)} ${humanized}.`);
     }
-    lines.push(`type ${structName} struct {`);
+    blockLines.push(`type ${structName} struct {`);
 
     // Deduplicate fields by Go field name
     const seenFieldNames = new Set<string>();
@@ -198,20 +248,35 @@ export function generateModels(models: Model[], ctx: EmitterContext): GeneratedF
 
       if (field.description) {
         const fdLines = field.description.split('\n').filter((l) => l.trim());
-        lines.push(`\t// ${fieldDocComment(goFieldName, fdLines[0])}`);
+        blockLines.push(`\t// ${fieldDocComment(goFieldName, fdLines[0])}`);
         for (let i = 1; i < fdLines.length; i++) {
-          lines.push(`\t// ${fdLines[i].trim()}`);
+          blockLines.push(`\t// ${fdLines[i].trim()}`);
         }
       }
       if (field.deprecated) {
-        if (field.description) lines.push(`\t//`);
+        if (field.description) blockLines.push(`\t//`);
         const deprecationReason = extractDeprecationReason(field.description);
-        lines.push(`\t// Deprecated: ${deprecationReason}`);
+        blockLines.push(`\t// Deprecated: ${deprecationReason}`);
       }
-      lines.push(`\t${goFieldName} ${goType} \`${jsonTag}\``);
+      blockLines.push(`\t${goFieldName} ${goType} \`${jsonTag}\``);
     }
 
-    lines.push('}');
+    blockLines.push('}');
+    modelBlocks.push({
+      names: [structName],
+      text: blockLines.join('\n'),
+      inScope: isModelInScope(model.name, ctx) || forcedCanonicals.has(model.name),
+    });
+  }
+
+  // Scoped runs: drop brand-new out-of-scope blocks; carry over prior blocks the
+  // new spec renamed/removed (still referenced by un-regenerated resource code).
+  // Full runs return every block unchanged.
+  // `PaginationParams` is emitted separately below (not part of modelBlocks),
+  // so exclude it from carry-over or the prior copy would be redeclared.
+  const reconciled = reconcileFlatBlocks(modelBlocks, 'models.go', ctx, new Set(['PaginationParams']));
+  for (const text of reconciled) {
+    lines.push(text);
     lines.push('');
   }
 

package/src/go/resources.ts

@@ -21,7 +21,7 @@ import {
 import {
   buildResolvedLookup,
   lookupResolved,
-  groupByMount,
+  scopedMountGroups,
   getOpDefaults,
   getOpInferFromClient,
   buildHiddenParams,
@@ -60,11 +60,11 @@ export function generateResources(services: Service[], ctx: EmitterContext): Gen
   if (services.length === 0) return [];
 
   const files: GeneratedFile[] = [];
-  const mountGroups = groupByMount(ctx);
+  const mountGroups = scopedMountGroups(ctx);
 
   // If no resolved operations, fall back to raw services
   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: resolveResourceClassName(s, ctx), operations: s.operations }));
 

package/src/go/tests.ts

@@ -5,7 +5,7 @@ import { resolveResourceClassName, paramsStructName, sortPathParamsByTemplateOrd
 import { buildServiceAccessPaths } from './client.js';
 import { generateFixtures } from './fixtures.js';
 import { isListWrapperModel } from './models.js';
-import { groupByMount, buildResolvedLookup, lookupResolved, buildHiddenParams } from '../shared/resolved-ops.js';
+import { scopedMountGroups, buildResolvedLookup, lookupResolved, buildHiddenParams } from '../shared/resolved-ops.js';
 import { existsSync, readFileSync } from 'node:fs';
 import { resolve } from 'node:path';
 
@@ -71,8 +71,10 @@ export function generateTests(spec: ApiSpec, ctx: EmitterContext): GeneratedFile
     overwriteExisting: true,
   });
 
-  // Generate fixture JSON files
-  const { files: fixtures, pathRewrites: fixtureRewrites } = generateFixtures(spec);
+  // Generate fixture JSON files. Pass ctx so a scoped run only emits fixtures
+  // for in-scope models (or ones already on disk), dropping brand-new
+  // out-of-scope fixtures while leaving prior fixtures untouched.
+  const { files: fixtures, pathRewrites: fixtureRewrites } = generateFixtures(spec, ctx);
   for (const fixture of fixtures) {
     files.push({
       path: fixture.path,
@@ -85,9 +87,9 @@ export function generateTests(spec: ApiSpec, ctx: EmitterContext): GeneratedFile
   const accessPaths = buildServiceAccessPaths(spec.services, ctx);
 
   // Generate per-mount-target test files
-  const mountGroups = groupByMount(ctx);
+  const mountGroups = scopedMountGroups(ctx);
   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),

package/src/kotlin/enums.ts

@@ -1,5 +1,6 @@
 import type { Enum, EmitterContext, GeneratedFile } from '@workos/oagen';
 import { className, ktStringLiteral } from './naming.js';
+import { isEnumInScope } from '../shared/resolved-ops.js';
 
 const KOTLIN_SRC_PREFIX = 'src/main/kotlin/';
 const ENUMS_PACKAGE = 'com.workos.types';
@@ -24,7 +25,7 @@ export const enumCanonicalMap = new Map<string, string>();
  * shortest PascalCase name becomes canonical and the rest emit `typealias`
  * files pointing at the canonical class.
  */
-export function generateEnums(enums: Enum[], _ctx: EmitterContext): GeneratedFile[] {
+export function generateEnums(enums: Enum[], ctx: EmitterContext): GeneratedFile[] {
   if (enums.length === 0) return [];
 
   // Reset the canonical map on every generation run (guards against re-entry).
@@ -74,6 +75,11 @@ export function generateEnums(enums: Enum[], _ctx: EmitterContext): GeneratedFil
 
     const typeName = canonicalEnumTypeName(enumDef);
 
+    // FR-1.4: write per-enum FILES only when in scope. Each enum is its own
+    // `.kt` file (no barrel), so an out-of-scope enum left untouched on disk
+    // stays importable.
+    const enumInScope = isEnumInScope(enumDef.name, ctx);
+
     // Non-canonical enum: emit a typealias instead of a full enum class.
     const sharedSortEmitter = sharedSortEmitters.has(enumDef.name);
     const canonicalName = sharedSortEmitter
@@ -94,11 +100,13 @@ export function generateEnums(enums: Enum[], _ctx: EmitterContext): GeneratedFil
         aliasLine,
         '',
       ].join('\n');
-      files.push({
-        path: `${KOTLIN_SRC_PREFIX}${ENUMS_DIR}/${typeName}.kt`,
-        content: aliasContent,
-        overwriteExisting: true,
-      });
+      if (enumInScope) {
+        files.push({
+          path: `${KOTLIN_SRC_PREFIX}${ENUMS_DIR}/${typeName}.kt`,
+          content: aliasContent,
+          overwriteExisting: true,
+        });
+      }
       continue;
     }
 
@@ -175,11 +183,13 @@ export function generateEnums(enums: Enum[], _ctx: EmitterContext): GeneratedFil
     lines.push('}');
     lines.push('');
 
-    files.push({
-      path: `${KOTLIN_SRC_PREFIX}${ENUMS_DIR}/${typeName}.kt`,
-      content: lines.join('\n'),
-      overwriteExisting: true,
-    });
+    if (enumInScope) {
+      files.push({
+        path: `${KOTLIN_SRC_PREFIX}${ENUMS_DIR}/${typeName}.kt`,
+        content: lines.join('\n'),
+        overwriteExisting: true,
+      });
+    }
   }
 
   return files;

package/src/kotlin/models.ts

@@ -8,11 +8,23 @@ import {
   collectNonPaginatedResponseModelNames,
   collectReferencedListMetadataModels,
 } from '../shared/model-utils.js';
+import { isModelInScope, fileExistsAfterRun } from '../shared/resolved-ops.js';
 
 const KOTLIN_SRC_PREFIX = 'src/main/kotlin/';
 const MODELS_PACKAGE = 'com.workos.models';
 const MODELS_DIR = 'com/workos/models';
 
+/**
+ * The relative path (target-root-relative, matching the prior manifest) of the
+ * per-model `.kt` FILE the emitter writes for a model. The aggregate gate
+ * ({@link fileExistsAfterRun}) checks this exact path against the freshly-emitted
+ * in-scope set and the prior manifest. Must stay in sync with the path used in
+ * {@link emitDataClass} / {@link emitSealedUnion} / the typealias branch.
+ */
+function modelFilePath(modelName: string): string {
+  return `${KOTLIN_SRC_PREFIX}${MODELS_DIR}/${className(modelName)}.kt`;
+}
+
 /**
  * Some specs leave string fields without `format: date-time` even though the
  * description (or the example) makes clear they carry an ISO-8601 timestamp.
@@ -123,10 +135,17 @@ export function generateModels(models: Model[], ctx: EmitterContext): GeneratedF
   for (const model of models) {
     if (skipAsListWrapper(model) || skipAsListMetadata(model)) continue;
     const typeName = className(model.name);
+    // FR-1.4: write per-model FILES only when in scope. Each model is its own
+    // `.kt` file (no barrel), so an out-of-scope model left untouched on disk
+    // stays importable. The WorkOSEvent sealed interface below is an aggregate
+    // built from many event models, so it is NOT gated.
+    const modelInScope = isModelInScope(model.name, ctx);
 
     // Parent of a discriminated union: emit a sealed class.
     if (model.fields.length === 0 && discriminatedUnions.has(typeName)) {
-      files.push(emitSealedUnion(typeName, discriminatedUnions.get(typeName)!));
+      if (modelInScope) {
+        files.push(emitSealedUnion(typeName, discriminatedUnions.get(typeName)!, ctx));
+      }
       continue;
     }
 
@@ -142,25 +161,40 @@ export function generateModels(models: Model[], ctx: EmitterContext): GeneratedF
         `typealias ${typeName} = ${canonicalType}`,
         '',
       ].join('\n');
-      files.push({
-        path: `${KOTLIN_SRC_PREFIX}${MODELS_DIR}/${typeName}.kt`,
-        content: aliasContent,
-        overwriteExisting: true,
-      });
+      if (modelInScope) {
+        files.push({
+          path: `${KOTLIN_SRC_PREFIX}${MODELS_DIR}/${typeName}.kt`,
+          content: aliasContent,
+          overwriteExisting: true,
+        });
+      }
       continue;
     }
 
-    files.push(emitDataClass(model));
+    if (modelInScope) {
+      files.push(emitDataClass(model));
+    }
   }
 
   // Generate the sealed WorkOSEvent interface. Collect all event envelope
   // models that have a literal `event` field and build the @JsonSubTypes
   // mapping so Jackson can deserialize directly to the correct concrete type.
+  //
+  // This is an AGGREGATE: it enumerates many event models by name. A scoped
+  // (`--services`) run emits per-model `.kt` files only for in-scope models, so
+  // listing a brand-new OUT-OF-SCOPE event model here would reference a
+  // `ModelName::class` whose file is never written → "Unresolved reference"
+  // (the WorkOSEvent.kt build break). Gate each entry so it appears only if its
+  // model file will EXIST on disk after the run = in-scope (emitted now) ∪
+  // already-on-disk (prior manifest; scoped runs never prune). Renamed/
+  // removed-but-on-disk models still present under the same name in the spec are
+  // retained; full runs include everything (gate is inert).
   const eventMapping: Array<{ wireValue: string; modelName: string }> = [];
   for (const model of models) {
     if (skipAsListWrapper(model) || skipAsListMetadata(model)) continue;
     if (aliasOf.has(model.name)) continue;
     if (!isEventEnvelopeModel(model)) continue;
+    if (!fileExistsAfterRun(modelFilePath(model.name), isModelInScope(model.name, ctx), ctx)) continue;
     const eventField = model.fields.find((f) => f.name === 'event');
     if (eventField && eventField.type.kind === 'literal' && typeof eventField.type.value === 'string') {
       eventMapping.push({ wireValue: eventField.type.value, modelName: model.name });
@@ -242,6 +276,7 @@ function emitDataClass(model: Model): GeneratedFile {
 function emitSealedUnion(
   typeName: string,
   disc: { property: string; mapping: Record<string, string>; variantTypes: string[] },
+  ctx: EmitterContext,
 ): GeneratedFile {
   const lines: string[] = [];
   lines.push(`package ${MODELS_PACKAGE}`);
@@ -249,11 +284,19 @@ function emitSealedUnion(
   lines.push('import com.fasterxml.jackson.annotation.JsonSubTypes');
   lines.push('import com.fasterxml.jackson.annotation.JsonTypeInfo');
   lines.push('');
+  // AGGREGATE gate: @JsonSubTypes enumerates each variant model by name
+  // (`VariantClass::class`). The sealed parent itself is in scope here, but a
+  // scoped run may not emit a brand-new OUT-OF-SCOPE variant's `.kt` file — so
+  // only list variants whose model file will exist on disk after the run
+  // (in-scope ∪ prior manifest). A full run keeps every variant (gate is inert).
+  const entries = Object.entries(disc.mapping).filter(([, modelName]) =>
+    fileExistsAfterRun(modelFilePath(modelName), isModelInScope(modelName, ctx), ctx),
+  );
   // KDoc with worked Kotlin + Java consumption examples. These unions are
   // returned by Jackson; callers branch on the concrete subtype to access
-  // variant-specific data.
-  const exampleVariantWire = Object.keys(disc.mapping)[0];
-  const exampleVariantType = exampleVariantWire ? className(disc.mapping[exampleVariantWire]) : null;
+  // variant-specific data. Use a surviving variant so the example never names a
+  // class whose file the scoped run skipped.
+  const exampleVariantType = entries.length > 0 ? className(entries[0][1]) : null;
   lines.push('/**');
   lines.push(` * Discriminated union over ${typeName} variants. Selected by \`${disc.property}\`.`);
   if (exampleVariantType) {
@@ -282,7 +325,6 @@ function emitSealedUnion(
   lines.push('  visible = true');
   lines.push(')');
   lines.push('@JsonSubTypes(');
-  const entries = Object.entries(disc.mapping);
   for (let i = 0; i < entries.length; i++) {
     const [wireValue, modelName] = entries[i];
     const variantType = className(modelName);