@workos/oagen-emitters 0.19.0 → 0.19.1

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/tests.ts

@@ -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,

package/src/kotlin/models.ts

@@ -8,12 +8,23 @@ import {
   collectNonPaginatedResponseModelNames,
   collectReferencedListMetadataModels,
 } from '../shared/model-utils.js';
-import { isModelInScope } from '../shared/resolved-ops.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.
@@ -133,7 +144,7 @@ export function generateModels(models: Model[], ctx: EmitterContext): GeneratedF
     // Parent of a discriminated union: emit a sealed class.
     if (model.fields.length === 0 && discriminatedUnions.has(typeName)) {
       if (modelInScope) {
-        files.push(emitSealedUnion(typeName, discriminatedUnions.get(typeName)!));
+        files.push(emitSealedUnion(typeName, discriminatedUnions.get(typeName)!, ctx));
       }
       continue;
     }
@@ -168,11 +179,22 @@ export function generateModels(models: Model[], ctx: EmitterContext): GeneratedF
   // 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 });
@@ -254,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}`);
@@ -261,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) {
@@ -294,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);

package/src/kotlin/tests.ts

@@ -27,6 +27,9 @@ import {
   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.
@@ -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/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],

package/src/python/models.ts

@@ -2,9 +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 } from '../shared/resolved-ops.js';
+import { isModelInScope, isEnumInScope, fileExistsAfterRun, priorManifestBasenames } from '../shared/resolved-ops.js';
 
 /**
  * Generate Python dataclass model files from IR Model definitions.
@@ -171,8 +171,11 @@ export function generateModels(models: Model[], ctx: EmitterContext): GeneratedF
       dispLines.push(`        return ${unknownClassName}.from_dict(data)`);
 
       // FR-1.4: write the file only when in scope; the barrel tracking below is
-      // unconditional so out-of-scope models (left on disk) stay exported.
-      if (isModelInScope(model.name, ctx)) {
+      // 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'),
@@ -181,19 +184,24 @@ export function generateModels(models: Model[], ctx: EmitterContext): GeneratedF
         });
       }
 
-      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;
     }
@@ -221,18 +229,24 @@ export function generateModels(models: Model[], ctx: EmitterContext): GeneratedF
       }
       lines.push('');
       lines.push(`${modelClassName}: TypeAlias = ${canonicalClassName}`);
-      if (isModelInScope(model.name, ctx)) {
+      const aliasInScope = isModelInScope(model.name, ctx);
+      const aliasPath = `src/${ctx.namespace}/${dirName}/models/${fileName(model.name)}.py`;
+      if (aliasInScope) {
         files.push({
-          path: `src/${ctx.namespace}/${dirName}/models/${fileName(model.name)}.py`,
+          path: aliasPath,
           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);
+      // 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;
     }
 
@@ -464,18 +478,25 @@ export function generateModels(models: Model[], ctx: EmitterContext): GeneratedF
 
     lines.push('        return result');
 
-    if (isModelInScope(model.name, ctx)) {
+    const regularInScope = isModelInScope(model.name, ctx);
+    if (regularInScope) {
       files.push({
-        path: `src/${ctx.namespace}/${dirName}/models/${fileName(model.name)}.py`,
+        path: modelFilePath,
         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);
+    // 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
@@ -483,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`;
@@ -495,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
@@ -570,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(
@@ -593,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,