@workos/oagen-emitters 0.19.0 → 0.19.1

package/dist/plugin.mjs

@@ -1,2 +1,2 @@
-import { t as workosEmittersPlugin } from "./plugin-BXDPA9pJ.mjs";
+import { t as workosEmittersPlugin } from "./plugin-DXIciTnN.mjs";
 export { workosEmittersPlugin };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@workos/oagen-emitters",
-  "version": "0.19.0",
+  "version": "0.19.1",
   "description": "WorkOS' oagen emitters",
   "license": "MIT",
   "author": "WorkOS",

package/src/dotnet/fixtures.ts

@@ -1,7 +1,16 @@
-import type { Model, TypeRef, Enum } from '@workos/oagen';
+import type { Model, TypeRef, Enum, EmitterContext } from '@workos/oagen';
 import { fixtureFileName, domainFieldName } from './naming.js';
 import { isListMetadataModel, isListWrapperModel } from './models.js';
 import { collectNonPaginatedResponseModelNames } from '../shared/model-utils.js';
+import { isModelInScope, fileExistsAfterRun } from '../shared/resolved-ops.js';
+
+/**
+ * Prefix the per-model fixture path with the .NET test project layout so the
+ * scoped-run gate can compare it against the prefixed paths recorded in the
+ * prior manifest. Must mirror `TEST_PREFIX` in index.ts; the fixture path
+ * itself (`testdata/<name>.json`) is what `prefixTestPaths` later prepends to.
+ */
+const TEST_PREFIX = 'test/WorkOSTests/';
 
 /**
  * Prefix mapping for generating realistic ID fixture values.
@@ -25,11 +34,14 @@ export const ID_PREFIXES: Record<string, string> = {
 /**
  * Generate JSON fixture files for test data.
  */
-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]));
@@ -50,10 +62,19 @@ export function generateFixtures(spec: {
     if (isListMetadataModel(model)) continue;
     if (isListWrapperModel(model) && !nonPaginatedWrapperRefs.has(model.name)) continue;
 
+    // Scoped-run gate: only emit a per-model fixture whose file will exist on
+    // disk after the run (in-scope, or already present from a prior manifest).
+    // A brand-new out-of-scope model's fixture would be a stray file for a
+    // model no in-scope test can reference; a renamed/removed-but-on-disk one
+    // is retained. Full runs emit everything. `relPath` carries the
+    // `test/WorkOSTests/` prefix so it matches the prefixed prior-manifest paths.
+    const fixturePath = `testdata/${fixtureFileName(model.name)}.json`;
+    if (!fileExistsAfterRun(`${TEST_PREFIX}${fixturePath}`, isModelInScope(model.name, ctx), ctx)) continue;
+
     const fixture = model.fields.length === 0 ? {} : generateModelFixture(model, modelMap, enumMap);
 
     files.push({
-      path: `testdata/${fixtureFileName(model.name)}.json`,
+      path: fixturePath,
       content: JSON.stringify(fixture, null, 2),
     });
 

package/src/dotnet/index.ts

@@ -19,7 +19,7 @@ import { generateClient } from './client.js';
 import { generateTests } from './tests.js';
 import { buildOperationsMap } from './manifest.js';
 import { generateWrapperOptionsClasses } from './wrappers.js';
-import { groupByMount } from '../shared/resolved-ops.js';
+import { groupByMount, isModelInScope, fileExistsAfterRun } from '../shared/resolved-ops.js';
 import { AUTOGEN_NOTICE } from '../shared/file-header.js';
 import { discriminatedUnions, resolveModelName } from './type-map.js';
 import { modelClassName } from './naming.js';
@@ -66,6 +66,28 @@ function prefixTestPaths(files: GeneratedFile[]): GeneratedFile[] {
   return files;
 }
 
+/**
+ * Scoped-run gate for a discriminated-union variant referenced by a generated
+ * converter (the event-registry / polymorphic dispatch aggregate). A converter
+ * may only name a variant whose per-model `Entities/<Class>.cs` file will exist
+ * on disk after the run — otherwise the `new <Class>()` / `ToObject<<Class>>`
+ * arm references a type whose file is never emitted (CS0246). The set that
+ * exists after the run is: in-scope variants (emitted this run) ∪ variants
+ * already on disk from a prior manifest (scoped runs never prune), so a
+ * renamed/removed-but-still-on-disk variant is RETAINED while a brand-new
+ * out-of-scope variant is EXCLUDED. A full run includes everything.
+ *
+ * The variant name is resolved through the model-alias map first, exactly as
+ * the converter emits it (`modelClassName(resolveModelName(name))`), and the
+ * candidate path carries the `src/WorkOS.net/` prefix so it matches the
+ * prefixed paths recorded in `priorTargetManifestPaths`.
+ */
+function variantFileExistsAfterRun(variantModelName: string, ctx: EmitterContext): boolean {
+  const canonical = resolveModelName(variantModelName);
+  const relPath = `${SRC_PREFIX}Entities/${modelClassName(canonical)}.cs`;
+  return fileExistsAfterRun(relPath, isModelInScope(canonical, ctx), ctx);
+}
+
 export const dotnetEmitter: Emitter = {
   language: 'dotnet',
 
@@ -146,6 +168,11 @@ export const dotnetEmitter: Emitter = {
         lines.push('            switch (discriminatorValue)');
         lines.push('            {');
         for (const [value, modelName] of Object.entries(disc.mapping)) {
+          // Scoped-run gate: only dispatch to a variant whose `Entities/*.cs`
+          // file will exist after the run. A brand-new out-of-scope variant is
+          // skipped (its `.cs` is never emitted ⇒ CS0246); unmatched discriminator
+          // values fall through to the `default` arm below.
+          if (!variantFileExistsAfterRun(modelName, c)) continue;
           const csName = modelClassName(resolveModelName(modelName));
           lines.push(`                case "${value}": return jObject.ToObject<${csName}>(serializer);`);
         }
@@ -177,6 +204,12 @@ export const dotnetEmitter: Emitter = {
     // CanWrite is false so serialization uses the default path and never
     // re-enters WriteJson.
     for (const [baseName, disc] of modelDiscriminators) {
+      // Skip the converter entirely when the base model's own `Entities/*.cs`
+      // won't exist after a scoped run (brand-new out-of-scope base): its
+      // `new <baseClass>()` default arm and `[JsonConverter]` attribute would
+      // both dangle. When the base is already on disk we still emit it — the
+      // untouched base class references this converter by name.
+      if (!variantFileExistsAfterRun(baseName, c)) continue;
       const baseClass = modelClassName(baseName);
       const converterName = `${baseClass}DiscriminatorConverter`;
       const lines: string[] = [];
@@ -210,6 +243,14 @@ export const dotnetEmitter: Emitter = {
       lines.push('            switch (discriminatorValue)');
       lines.push('            {');
       for (const [value, variantModelName] of Object.entries(disc.mapping)) {
+        // Scoped-run gate: only construct a variant whose `Entities/*.cs` file
+        // will exist after the run. This is the event-registry aggregate
+        // (`EventSchema` enumerates every event payload model): a brand-new
+        // out-of-scope event type is skipped (its `.cs` is never emitted ⇒
+        // CS0246), while a renamed/removed-but-still-on-disk one is retained.
+        // Unmatched discriminator values fall through to the `default` arm,
+        // which deserializes into the base class.
+        if (!variantFileExistsAfterRun(variantModelName, c)) continue;
         const csName = modelClassName(variantModelName);
         lines.push(`                case "${value}": target = new ${csName}(); break;`);
       }

package/src/dotnet/tests.ts

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

package/src/go/enums.ts

@@ -1,6 +1,8 @@
 import type { Enum, EmitterContext, GeneratedFile, Service } from '@workos/oagen';
 import { walkTypeRef } from '@workos/oagen';
 import { className } from './naming.js';
+import { isEnumInScope, isScopedRun } from '../shared/resolved-ops.js';
+import { reconcileFlatBlocks, readPriorFile, type NamedBlock } from './flat-merge.js';
 
 /**
  * Generate Go typed string enum constants from IR Enum definitions.
@@ -16,6 +18,16 @@ export function generateEnums(enums: Enum[], ctx: EmitterContext): GeneratedFile
   if (enums.length === 0) return [];
 
   const aliasOf = collectEnumAliasOf(enums);
+  // An in-scope enum alias emits `type Alias = Canonical` against the current
+  // spec; the canonical may itself be out of scope and brand-new, which the
+  // reconciler would drop, leaving the alias dangling. Force-retain any
+  // canonical referenced by an in-scope alias.
+  const forcedCanonicals = new Set<string>();
+  if (isScopedRun(ctx)) {
+    for (const [aliasName, canonical] of aliasOf) {
+      if (isEnumInScope(aliasName, ctx)) forcedCanonicals.add(canonical);
+    }
+  }
   const files: GeneratedFile[] = [];
 
   // Group all enums into a single file per SDK
@@ -23,6 +35,12 @@ export function generateEnums(enums: Enum[], ctx: EmitterContext): GeneratedFile
   lines.push(`package ${ctx.namespace}`);
   lines.push('');
 
+  // Build one NamedBlock per emitted enum type so a scoped run can reconcile
+  // them against the prior enums.go (drop brand-new out-of-scope enums, retain
+  // renamed/removed ones still referenced by un-regenerated code). A full run
+  // emits every block unchanged.
+  const enumBlocks: NamedBlock[] = [];
+
   for (const enumDef of enums) {
     // If this enum is an alias, emit a simple type alias
     const canonicalName = aliasOf.get(enumDef.name);
@@ -33,9 +51,11 @@ export function generateEnums(enums: Enum[], ctx: EmitterContext): GeneratedFile
       // enums from enrichModelsFromSpec whose underscore names collapse to the
       // same PascalCase as the original enum).
       if (aliasType === canonicalType) continue;
-      lines.push(`// ${aliasType} is an alias for ${canonicalType}.`);
-      lines.push(`type ${aliasType} = ${canonicalType}`);
-      lines.push('');
+      enumBlocks.push({
+        names: [aliasType],
+        text: [`// ${aliasType} is an alias for ${canonicalType}.`, `type ${aliasType} = ${canonicalType}`].join('\n'),
+        inScope: isEnumInScope(enumDef.name, ctx),
+      });
       continue;
     }
 
@@ -43,9 +63,11 @@ export function generateEnums(enums: Enum[], ctx: EmitterContext): GeneratedFile
 
     if (enumDef.values.length === 0) {
       const humanized = humanize(enumDef.name);
-      lines.push(`// ${typeName} represents ${humanized} values.`);
-      lines.push(`type ${typeName} = string`);
-      lines.push('');
+      enumBlocks.push({
+        names: [typeName],
+        text: [`// ${typeName} represents ${humanized} values.`, `type ${typeName} = string`].join('\n'),
+        inScope: isEnumInScope(enumDef.name, ctx) || forcedCanonicals.has(enumDef.name),
+      });
       continue;
     }
 
@@ -61,10 +83,11 @@ export function generateEnums(enums: Enum[], ctx: EmitterContext): GeneratedFile
     }
 
     const humanized = humanize(enumDef.name);
-    lines.push(`// ${typeName} represents ${humanized} values.`);
-    lines.push(`type ${typeName} string`);
-    lines.push('');
-    lines.push('const (');
+    const blockLines: string[] = [];
+    blockLines.push(`// ${typeName} represents ${humanized} values.`);
+    blockLines.push(`type ${typeName} string`);
+    blockLines.push('');
+    blockLines.push('const (');
 
     const usedNames = new Set<string>();
     for (const v of uniqueValues) {
@@ -79,15 +102,25 @@ export function generateEnums(enums: Enum[], ctx: EmitterContext): GeneratedFile
       usedNames.add(constName);
       const valueStr = typeof v.value === 'string' ? `"${v.value}"` : String(v.value);
       if (v.description) {
-        lines.push(`\t// ${constName} is ${v.description}.`);
+        blockLines.push(`\t// ${constName} is ${v.description}.`);
       }
       if (v.deprecated) {
-        if (v.description) lines.push(`\t//`);
-        lines.push(`\t// Deprecated: this value is deprecated.`);
+        if (v.description) blockLines.push(`\t//`);
+        blockLines.push(`\t// Deprecated: this value is deprecated.`);
       }
-      lines.push(`\t${constName} ${typeName} = ${valueStr}`);
+      blockLines.push(`\t${constName} ${typeName} = ${valueStr}`);
     }
-    lines.push(')');
+    blockLines.push(')');
+    enumBlocks.push({
+      names: [typeName],
+      text: blockLines.join('\n'),
+      inScope: isEnumInScope(enumDef.name, ctx) || forcedCanonicals.has(enumDef.name),
+    });
+  }
+
+  const reconciled = reconcileFlatBlocks(enumBlocks, 'enums.go', ctx);
+  for (const text of reconciled) {
+    lines.push(text);
     lines.push('');
   }
 
@@ -96,7 +129,7 @@ export function generateEnums(enums: Enum[], ctx: EmitterContext): GeneratedFile
     content: lines.join('\n'),
     overwriteExisting: true,
   });
-  const eventConstantsFile = generateEventConstantsFile(enums);
+  const eventConstantsFile = generateEventConstantsFile(enums, ctx);
   if (eventConstantsFile) files.push(eventConstantsFile);
 
   return files;
@@ -175,10 +208,28 @@ function collectEnumAliasOf(enums: Enum[]): Map<string, string> {
   return aliasOf;
 }
 
-function generateEventConstantsFile(enums: Enum[]): GeneratedFile | null {
+const EVENTS_FILE_PATH = 'pkg/events/events.go';
+
+function generateEventConstantsFile(enums: Enum[], ctx: EmitterContext): GeneratedFile | null {
   const enumDef = findWebhookEventEnum(enums);
   if (!enumDef) return null;
 
+  // Scoped-run gate for the flat events file. Unlike models/enums, an event
+  // value can't be mapped to a single selected service, so there is no
+  // per-event "in scope" signal. The correct Option-B behavior is therefore to
+  // keep this aggregate byte-stable in a scoped run: emit only event constants
+  // that already existed in the prior events.go (dropping brand-new additions
+  // such as `session.reauthenticated` from an out-of-scope service) and never
+  // drop a constant that was present before. Equivalent to: in a scoped run,
+  // emit exactly the prior file's constant set.
+  let priorEventConsts: Set<string> | null = null;
+  if (isScopedRun(ctx)) {
+    const prior = readPriorFile(EVENTS_FILE_PATH, ctx);
+    if (prior !== null) {
+      priorEventConsts = collectPriorEventConstNames(prior);
+    }
+  }
+
   const lines: string[] = [];
   lines.push('package events');
   lines.push('');
@@ -195,6 +246,13 @@ function generateEventConstantsFile(enums: Enum[]): GeneratedFile | null {
     seenValues.add(valueStr);
 
     const constName = uniqueEventConstantName(valueStr, usedNames);
+
+    // Scoped run: skip a constant that wasn't in the prior file (a brand-new,
+    // out-of-scope event). When there's no prior file to compare against, fall
+    // through and emit everything (first generation / non-target run).
+    if (priorEventConsts !== null && !priorEventConsts.has(constName)) {
+      continue;
+    }
     usedNames.add(constName);
 
     if (value.description) {
@@ -213,12 +271,27 @@ function generateEventConstantsFile(enums: Enum[]): GeneratedFile | null {
   lines.push('');
 
   return {
-    path: 'pkg/events/events.go',
+    path: EVENTS_FILE_PATH,
     content: lines.join('\n'),
     overwriteExisting: true,
   };
 }
 
+/**
+ * Collect the constant names declared in a prior `pkg/events/events.go`. Each
+ * event constant is emitted as `\tConstName = "wire.value"` inside the single
+ * `const (...)` block, so a simple line scan recovers the prior name set used
+ * to keep the file byte-stable across scoped runs.
+ */
+function collectPriorEventConstNames(content: string): Set<string> {
+  const names = new Set<string>();
+  for (const raw of content.split('\n')) {
+    const m = raw.trim().match(/^(\w+)\s*=\s*"/);
+    if (m) names.add(m[1]);
+  }
+  return names;
+}
+
 function findWebhookEventEnum(enums: Enum[]): Enum | null {
   return (
     enums.find((enumDef) => enumDef.name === 'CreateWebhookEndpointEvents') ??

package/src/go/fixtures.ts

@@ -1,7 +1,8 @@
-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.
@@ -24,8 +25,18 @@ export const ID_PREFIXES: Record<string, string> = {
 
 /**
  * Generate JSON fixture files for test data.
+ *
+ * Scoped runs only emit a fixture for a model whose per-model fixture FILE will
+ * exist on disk after the run (in-scope, or already present from a prior run —
+ * the fixture path is per-model so the prior manifest records it directly).
+ * This drops brand-new out-of-scope fixtures (the round-trip ADDITION case) and
+ * keeps prior fixtures untouched, mirroring the Rust fixtures fix. `ctx` is
+ * optional so unit tests that assert raw content can call it for a full run.
  */
-export function generateFixtures(spec: { models: Model[]; enums: Enum[]; services: any[] }): {
+export function generateFixtures(
+  spec: { models: Model[]; enums: Enum[]; services: any[] },
+  ctx?: EmitterContext,
+): {
   files: { path: string; content: string }[];
   pathRewrites: Map<string, string>;
 } {
@@ -38,14 +49,21 @@ export function generateFixtures(spec: { models: Model[]; enums: Enum[]; service
   const nonPaginatedRefs = collectNonPaginatedResponseModelNames(spec.services);
   const listMetadataNeeded = collectReferencedListMetadataModels(spec.models, nonPaginatedRefs);
 
+  // Full run (no ctx / no scoping): every fixture is in scope.
+  const fixtureInScope = (relPath: string, modelName: string): boolean =>
+    !ctx || fileExistsAfterRun(relPath, isModelInScope(modelName, ctx), ctx);
+
   for (const model of spec.models) {
     if (isListMetadataModel(model) && !listMetadataNeeded.has(model.name)) continue;
     if (isListWrapperModel(model) && !nonPaginatedRefs.has(model.name)) continue;
 
+    const path = `testdata/${fileName(model.name)}.json`;
+    if (!fixtureInScope(path, model.name)) continue;
+
     const fixture = model.fields.length === 0 ? {} : generateModelFixture(model, modelMap, enumMap);
 
     files.push({
-      path: `testdata/${fileName(model.name)}.json`,
+      path,
       content: JSON.stringify(fixture, null, 2),
     });
   }
@@ -67,6 +85,10 @@ export function generateFixtures(spec: { models: Model[]; enums: Enum[]; service
           const path = `testdata/list_${fileName(itemModel.name)}.json`;
           if (seenListPaths.has(path)) continue;
           seenListPaths.add(path);
+          // Scoped run: only emit a list fixture whose file will exist after the
+          // run (in-scope item model, or already on disk). Keyed on the item
+          // model so an out-of-scope paginated endpoint doesn't add a new file.
+          if (!fixtureInScope(path, itemModel.name)) continue;
           const fixture = generateModelFixture(itemModel, modelMap, enumMap);
           const listFixture = {
             data: [fixture],

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;
+}