@workos/oagen 0.0.1 → 0.1.0

package/dist/scripts/smoke/baseline.js

@@ -252,17 +252,26 @@ function buildInlineModel(name, schema) {
 
 // src/parser/schemas.ts
 function extractSchemas(schemas) {
-  const models = [];
   const enums = [];
-  if (!schemas) return { models, enums };
+  if (!schemas) return { models: [], enums };
+  const modelsByCleanName = /* @__PURE__ */ new Map();
   for (const [name, schema] of Object.entries(schemas)) {
     const pascalName = cleanSchemaName(toPascalCase(name));
     if (schema.enum) {
       enums.push(extractEnum(pascalName, schema));
     } else {
-      models.push(extractModel(pascalName, schema, schemas));
+      const model = extractModel(pascalName, schema, schemas);
+      const existing = modelsByCleanName.get(pascalName);
+      if (existing) {
+        if (model.fields.length > existing.fields.length) {
+          modelsByCleanName.set(pascalName, model);
+        }
+      } else {
+        modelsByCleanName.set(pascalName, model);
+      }
     }
   }
+  const models = [...modelsByCleanName.values()];
   const modelNames = new Set(models.map((m) => m.name));
   const inlineQueue = [...models];
   while (inlineQueue.length > 0) {
@@ -692,6 +701,18 @@ function classifyAndExtractResponse(schema, contextName) {
   }
   return extractDirectResource(schema, contextName);
 }
+var KNOWN_DATA_PATHS = /* @__PURE__ */ new Set(["data", "items", "results", "records", "entries", "values", "nodes", "edges"]);
+var PAGINATION_METADATA_PATTERNS = [
+  "metadata",
+  "pagination",
+  "cursor",
+  "has_more",
+  "page_info",
+  "total",
+  "next_page",
+  "previous_page",
+  "offset"
+];
 function detectListEnvelope(schema) {
   const propSources = [];
   if (schema.allOf) {
@@ -708,17 +729,26 @@ function detectListEnvelope(schema) {
     Object.assign(mergedProps, source);
   }
   const arrayProps = [];
-  let nonArrayCount = 0;
+  const nonArrayKeys = [];
   for (const [key, propSchema] of Object.entries(mergedProps)) {
     if (!propSchema) continue;
     if (propSchema.type === "array") {
       arrayProps.push(key);
     } else {
-      nonArrayCount++;
+      nonArrayKeys.push(key);
     }
   }
-  if (arrayProps.length === 1 && nonArrayCount >= 1) {
-    return { isEnvelope: true, dataPath: arrayProps[0] };
+  if (arrayProps.length === 1 && nonArrayKeys.length >= 1) {
+    const arrayPropName = arrayProps[0];
+    if (KNOWN_DATA_PATHS.has(arrayPropName)) {
+      return { isEnvelope: true, dataPath: arrayPropName };
+    }
+    const hasPaginationCompanion = nonArrayKeys.some(
+      (key) => PAGINATION_METADATA_PATTERNS.some((pattern) => key.toLowerCase().includes(pattern))
+    );
+    if (hasPaginationCompanion) {
+      return { isEnvelope: true, dataPath: arrayPropName };
+    }
   }
   return { isEnvelope: false, dataPath: null };
 }
@@ -1355,20 +1385,24 @@ function keepLargestByName(models) {
   }
   return [...byName.values()];
 }
-function rewriteModelRefsInServices(services, oldName, newName) {
+function rewriteModelRef(ref, oldName, newName) {
+  walkTypeRef(ref, {
+    model: (r) => {
+      if (r.name === oldName) r.name = newName;
+    }
+  });
+}
+function rewriteModelRefs(models, services, oldName, newName) {
+  for (const model of models) {
+    for (const field of model.fields) {
+      rewriteModelRef(field.type, oldName, newName);
+    }
+  }
   for (const service of services) {
     for (const op of service.operations) {
-      walkTypeRef(op.response, {
-        model: (r) => {
-          if (r.name === oldName) r.name = newName;
-        }
-      });
+      rewriteModelRef(op.response, oldName, newName);
       if (op.requestBody) {
-        walkTypeRef(op.requestBody, {
-          model: (r) => {
-            if (r.name === oldName) r.name = newName;
-          }
-        });
+        rewriteModelRef(op.requestBody, oldName, newName);
       }
     }
   }
@@ -1417,9 +1451,30 @@ function mergeFieldInlineModels(existingModels, fieldInlineModels) {
   });
   return [...existingModels, ...keepLargestByName(deduplicatedFieldModels)];
 }
+function hasModelConstDiscriminant(model) {
+  return model.fields.some(
+    (f) => (f.name === "object" || f.name === "type") && f.type.kind === "literal" && typeof f.type.value === "string"
+  );
+}
+function isModelReferencedByOthers(name, models, excludeNames) {
+  for (const model of models) {
+    if (excludeNames.has(model.name)) continue;
+    for (const field of model.fields) {
+      let found = false;
+      walkTypeRef(field.type, {
+        model: (r) => {
+          if (r.name === name) found = true;
+        }
+      });
+      if (found) return true;
+    }
+  }
+  return false;
+}
 function collapseJsonSuffixModels(models, services) {
   const normalizedModels = [...models];
   const byName = new Map(normalizedModels.map((m) => [m.name, m]));
+  const mergeCandidates = [];
   for (const model of normalizedModels) {
     if (!model.name.endsWith("Json")) continue;
     const baseName = model.name.slice(0, -4);
@@ -1427,13 +1482,20 @@ function collapseJsonSuffixModels(models, services) {
     if (!baseModel || model.fields.length <= baseModel.fields.length) continue;
     const isSuperset = baseModel.fields.every((f) => model.fields.some((mf) => mf.name === f.name));
     if (!isSuperset) continue;
-    baseModel.fields = model.fields;
-    const jsonIdx = normalizedModels.indexOf(model);
-    if (jsonIdx !== -1) normalizedModels.splice(jsonIdx, 1);
-    rewriteModelRefsInServices(services, model.name, baseName);
-    console.warn(`[oagen] Merged "${model.name}" into "${baseName}" (${model.fields.length} fields, superset)`);
+    if (hasModelConstDiscriminant(model) && hasModelConstDiscriminant(baseModel)) continue;
+    if (isModelReferencedByOthers(model.name, normalizedModels, /* @__PURE__ */ new Set([model.name, baseName]))) continue;
+    mergeCandidates.push({ jsonModel: model, baseModel });
+  }
+  const toRemove = /* @__PURE__ */ new Set();
+  for (const { jsonModel, baseModel } of mergeCandidates) {
+    baseModel.fields = jsonModel.fields;
+    toRemove.add(jsonModel.name);
+    rewriteModelRefs(normalizedModels, services, jsonModel.name, baseModel.name);
+    console.warn(
+      `[oagen] Merged "${jsonModel.name}" into "${baseModel.name}" (${jsonModel.fields.length} fields, superset)`
+    );
   }
-  return normalizedModels;
+  return normalizedModels.filter((m) => !toRemove.has(m.name));
 }
 
 // src/parser/collect-inline-enums.ts
@@ -1495,11 +1557,11 @@ async function parseSpec(specPath, options) {
     options?.operationIdTransform
   );
   const responseNormalizedModels = mergeInlineResponseModels(models, inlineModels);
-  const jsonCollapsedModels = collapseJsonSuffixModels(responseNormalizedModels, services);
   const fieldInlineModels = extractInlineModelsFromSchemas(
     spec.components?.schemas
   );
-  const finalModels = mergeFieldInlineModels(jsonCollapsedModels, fieldInlineModels);
+  const fieldMergedModels = mergeFieldInlineModels(responseNormalizedModels, fieldInlineModels);
+  const finalModels = collapseJsonSuffixModels(fieldMergedModels, services);
   collectInlineEnumsFromModels(finalModels, enums);
   const auth = extractAuthSchemes(spec.components?.securitySchemes);
   const serverEntries = (spec.servers ?? []).map((s) => ({ url: s.url ?? "", description: s.description })).filter((s) => s.url);

package/dist/smoke.js

@@ -253,17 +253,26 @@ function buildInlineModel(name, schema) {
 
 // src/parser/schemas.ts
 function extractSchemas(schemas) {
-  const models = [];
   const enums = [];
-  if (!schemas) return { models, enums };
+  if (!schemas) return { models: [], enums };
+  const modelsByCleanName = /* @__PURE__ */ new Map();
   for (const [name, schema] of Object.entries(schemas)) {
     const pascalName = cleanSchemaName(toPascalCase(name));
     if (schema.enum) {
       enums.push(extractEnum(pascalName, schema));
     } else {
-      models.push(extractModel(pascalName, schema, schemas));
+      const model = extractModel(pascalName, schema, schemas);
+      const existing = modelsByCleanName.get(pascalName);
+      if (existing) {
+        if (model.fields.length > existing.fields.length) {
+          modelsByCleanName.set(pascalName, model);
+        }
+      } else {
+        modelsByCleanName.set(pascalName, model);
+      }
     }
   }
+  const models = [...modelsByCleanName.values()];
   const modelNames = new Set(models.map((m) => m.name));
   const inlineQueue = [...models];
   while (inlineQueue.length > 0) {
@@ -693,6 +702,18 @@ function classifyAndExtractResponse(schema, contextName) {
   }
   return extractDirectResource(schema, contextName);
 }
+var KNOWN_DATA_PATHS = /* @__PURE__ */ new Set(["data", "items", "results", "records", "entries", "values", "nodes", "edges"]);
+var PAGINATION_METADATA_PATTERNS = [
+  "metadata",
+  "pagination",
+  "cursor",
+  "has_more",
+  "page_info",
+  "total",
+  "next_page",
+  "previous_page",
+  "offset"
+];
 function detectListEnvelope(schema) {
   const propSources = [];
   if (schema.allOf) {
@@ -709,17 +730,26 @@ function detectListEnvelope(schema) {
     Object.assign(mergedProps, source);
   }
   const arrayProps = [];
-  let nonArrayCount = 0;
+  const nonArrayKeys = [];
   for (const [key, propSchema] of Object.entries(mergedProps)) {
     if (!propSchema) continue;
     if (propSchema.type === "array") {
       arrayProps.push(key);
     } else {
-      nonArrayCount++;
+      nonArrayKeys.push(key);
     }
   }
-  if (arrayProps.length === 1 && nonArrayCount >= 1) {
-    return { isEnvelope: true, dataPath: arrayProps[0] };
+  if (arrayProps.length === 1 && nonArrayKeys.length >= 1) {
+    const arrayPropName = arrayProps[0];
+    if (KNOWN_DATA_PATHS.has(arrayPropName)) {
+      return { isEnvelope: true, dataPath: arrayPropName };
+    }
+    const hasPaginationCompanion = nonArrayKeys.some(
+      (key) => PAGINATION_METADATA_PATTERNS.some((pattern) => key.toLowerCase().includes(pattern))
+    );
+    if (hasPaginationCompanion) {
+      return { isEnvelope: true, dataPath: arrayPropName };
+    }
   }
   return { isEnvelope: false, dataPath: null };
 }
@@ -1356,20 +1386,24 @@ function keepLargestByName(models) {
   }
   return [...byName.values()];
 }
-function rewriteModelRefsInServices(services, oldName, newName) {
+function rewriteModelRef(ref, oldName, newName) {
+  walkTypeRef(ref, {
+    model: (r) => {
+      if (r.name === oldName) r.name = newName;
+    }
+  });
+}
+function rewriteModelRefs(models, services, oldName, newName) {
+  for (const model of models) {
+    for (const field of model.fields) {
+      rewriteModelRef(field.type, oldName, newName);
+    }
+  }
   for (const service of services) {
     for (const op of service.operations) {
-      walkTypeRef(op.response, {
-        model: (r) => {
-          if (r.name === oldName) r.name = newName;
-        }
-      });
+      rewriteModelRef(op.response, oldName, newName);
       if (op.requestBody) {
-        walkTypeRef(op.requestBody, {
-          model: (r) => {
-            if (r.name === oldName) r.name = newName;
-          }
-        });
+        rewriteModelRef(op.requestBody, oldName, newName);
       }
     }
   }
@@ -1418,9 +1452,30 @@ function mergeFieldInlineModels(existingModels, fieldInlineModels) {
   });
   return [...existingModels, ...keepLargestByName(deduplicatedFieldModels)];
 }
+function hasModelConstDiscriminant(model) {
+  return model.fields.some(
+    (f) => (f.name === "object" || f.name === "type") && f.type.kind === "literal" && typeof f.type.value === "string"
+  );
+}
+function isModelReferencedByOthers(name, models, excludeNames) {
+  for (const model of models) {
+    if (excludeNames.has(model.name)) continue;
+    for (const field of model.fields) {
+      let found = false;
+      walkTypeRef(field.type, {
+        model: (r) => {
+          if (r.name === name) found = true;
+        }
+      });
+      if (found) return true;
+    }
+  }
+  return false;
+}
 function collapseJsonSuffixModels(models, services) {
   const normalizedModels = [...models];
   const byName = new Map(normalizedModels.map((m) => [m.name, m]));
+  const mergeCandidates = [];
   for (const model of normalizedModels) {
     if (!model.name.endsWith("Json")) continue;
     const baseName = model.name.slice(0, -4);
@@ -1428,13 +1483,20 @@ function collapseJsonSuffixModels(models, services) {
     if (!baseModel || model.fields.length <= baseModel.fields.length) continue;
     const isSuperset = baseModel.fields.every((f) => model.fields.some((mf) => mf.name === f.name));
     if (!isSuperset) continue;
-    baseModel.fields = model.fields;
-    const jsonIdx = normalizedModels.indexOf(model);
-    if (jsonIdx !== -1) normalizedModels.splice(jsonIdx, 1);
-    rewriteModelRefsInServices(services, model.name, baseName);
-    console.warn(`[oagen] Merged "${model.name}" into "${baseName}" (${model.fields.length} fields, superset)`);
+    if (hasModelConstDiscriminant(model) && hasModelConstDiscriminant(baseModel)) continue;
+    if (isModelReferencedByOthers(model.name, normalizedModels, /* @__PURE__ */ new Set([model.name, baseName]))) continue;
+    mergeCandidates.push({ jsonModel: model, baseModel });
+  }
+  const toRemove = /* @__PURE__ */ new Set();
+  for (const { jsonModel, baseModel } of mergeCandidates) {
+    baseModel.fields = jsonModel.fields;
+    toRemove.add(jsonModel.name);
+    rewriteModelRefs(normalizedModels, services, jsonModel.name, baseModel.name);
+    console.warn(
+      `[oagen] Merged "${jsonModel.name}" into "${baseModel.name}" (${jsonModel.fields.length} fields, superset)`
+    );
   }
-  return normalizedModels;
+  return normalizedModels.filter((m) => !toRemove.has(m.name));
 }
 
 // src/parser/collect-inline-enums.ts
@@ -1496,11 +1558,11 @@ async function parseSpec(specPath, options) {
     options?.operationIdTransform
   );
   const responseNormalizedModels = mergeInlineResponseModels(models, inlineModels);
-  const jsonCollapsedModels = collapseJsonSuffixModels(responseNormalizedModels, services);
   const fieldInlineModels = extractInlineModelsFromSchemas(
     spec.components?.schemas
   );
-  const finalModels = mergeFieldInlineModels(jsonCollapsedModels, fieldInlineModels);
+  const fieldMergedModels = mergeFieldInlineModels(responseNormalizedModels, fieldInlineModels);
+  const finalModels = collapseJsonSuffixModels(fieldMergedModels, services);
   collectInlineEnumsFromModels(finalModels, enums);
   const auth = extractAuthSchemes(spec.components?.securitySchemes);
   const serverEntries = (spec.servers ?? []).map((s) => ({ url: s.url ?? "", description: s.description })).filter((s) => s.url);

package/dist/verify/index.js

@@ -2,7 +2,7 @@ import {
   diffSpecs,
   generate,
   getEmitter
-} from "../chunk-P5XUDUGY.js";
+} from "../chunk-VUSRNIG2.js";
 import {
   buildOverlayLookup,
   diffSurfaces,

package/docs/agents/architecture.md

@@ -47,7 +47,7 @@ When changing pipeline behavior:
 - `src/parser/`: OpenAPI to IR (refs, schemas, operations, pagination, inline models)
 - `src/engine/`: orchestration, writer, merger, registry, shared engine types
 - Language-specific emitters live in the separate `oagen-emitters` project (import from `@workos/oagen`)
-- `src/differ/`: incremental diff engine
+- `src/differ/`: spec diffing and breaking change classification
 - `src/compat/`: compat verification, overlay, staleness detection, extractors
 - `src/cli/`: CLI entry points and config loader
 - `src/utils/`: naming utilities (snake_case, camelCase, PascalCase conversions)

package/docs/agents/emitters.md

@@ -53,11 +53,11 @@ When regenerating an SDK for a language that already has a published SDK, verify
 1. Extract the live SDK's API surface (`oagen extract --sdk-path <path> --lang <language> --output <output>/sdk-{language}-surface.json`)
 2. Generate with the overlay (`--api-surface <output>/sdk-{language}-surface.json`) so the emitter preserves existing names
 3. Verify the generated output against the baseline (`oagen verify --api-surface <output>/sdk-{language}-surface.json --lang <language> --output <output>`)
-4. If violations exist, fix the emitter and regenerate — loop mode (`--loop`) automates this cycle
+4. If violations exist, fix the emitter and regenerate — `--max-retries` on `oagen verify` automates the overlay patching cycle
 
 The differ and overlay delegate all language-specific logic to the extractor's `hints: LanguageHints` object. Every extractor must provide hints — use `resolveHints({...})` to override only what differs from Node defaults. See `docs/architecture/extractor-contract.md` for the full hints reference.
 
-The `--api-surface` flag is supported by both `oagen generate` and `oagen diff` (for incremental generation with compat overlay).
+The `--api-surface` flag is supported by `oagen generate`.
 
 Run `/generate-extractor <language>` to scaffold the extractor, then `/verify-compat <language>` for the full guided workflow.
 

package/docs/architecture/dependency-layers.md

@@ -21,7 +21,7 @@ Top-level entrypoints (`src/index.ts`, `src/errors.ts`) are exempt from these di
 | `src/ir/`     | (nothing in `src/`)                                                    | everything                          |
 | `src/utils/`  | `src/ir/`, `src/errors.ts`                                             | parser, engine, differ, compat...   |
 | `src/parser/` | `src/ir/`, `src/utils/`, `src/errors.ts`                               | engine, differ, compat, verify, cli |
-| `src/engine/` | `src/ir/`, `src/utils/`, `src/errors.ts`, `src/differ/`                | parser, verify, cli                 |
+| `src/engine/` | `src/ir/`, `src/utils/`, `src/errors.ts`                               | parser, differ, verify, cli         |
 | `src/differ/` | `src/ir/`, `src/utils/`, `src/errors.ts`                               | parser, compat, verify, cli         |
 | `src/compat/` | `src/ir/`, `src/utils/`, `src/errors.ts`, `src/differ/`                | parser, verify, cli                 |
 | `src/verify/` | `src/ir/`, `src/utils/`, `src/errors.ts`, `src/engine/`, `src/compat/` | parser, cli                         |
@@ -59,10 +59,6 @@ Two type-only exceptions are currently allowed:
 - `differ -> engine/types` for shared generation types such as `EmitterContext` and `GeneratedFile`
 - `engine -> compat/types` because overlay-aware generation threads compat types through `EmitterContext` and generation options without depending on compat implementation modules
 
-One runtime exception is currently allowed:
-
-- `engine -> differ` for incremental generation, which depends on spec diffing and file mapping
-
 If you add a new exception, keep it narrow, make it type-only when possible, and document the reason in both code and docs.
 
 ## Enforcement

package/docs/architecture/emitter-contract.md

@@ -18,7 +18,7 @@ interface Emitter {
   generateClient(spec: ApiSpec, ctx: EmitterContext): GeneratedFile[];
   generateErrors(ctx: EmitterContext): GeneratedFile[];
   generateConfig(ctx: EmitterContext): GeneratedFile[];
-  generateTypeSignatures(spec: ApiSpec, ctx: EmitterContext): GeneratedFile[];
+  generateTypeSignatures?(spec: ApiSpec, ctx: EmitterContext): GeneratedFile[];
   generateTests(spec: ApiSpec, ctx: EmitterContext): GeneratedFile[];
   generateManifest?(spec: ApiSpec, ctx: EmitterContext): GeneratedFile[];
   fileHeader(): string;
@@ -31,8 +31,9 @@ interface Emitter {
 interface GeneratedFile {
   path: string; // Relative path within output directory
   content: string; // File content (header prepended by orchestrator)
-  header?: string; // Optional override of the default file header
   skipIfExists?: boolean; // Don't overwrite if file already exists on disk (defaults to false)
+  headerPlacement?: "prepend" | "skip"; // How to handle the file header (default: 'prepend')
+  integrateTarget?: boolean; // When false, exclude from --target integration (default: true)
 }
 ```
 
@@ -53,7 +54,7 @@ interface EmitterContext {
 
 ## Overlay Integration
 
-When a user passes `--api-surface` to `oagen generate` or `oagen diff`, the engine builds an `OverlayLookup` and passes it to emitters via `ctx.overlayLookup`. Emitters should check the overlay before generating default names to preserve backwards compatibility with an existing SDK.
+When a user passes `--api-surface` to `oagen generate`, the engine builds an `OverlayLookup` and passes it to emitters via `ctx.overlayLookup`. Emitters should check the overlay before generating default names to preserve backwards compatibility with an existing SDK.
 
 **When it's present:** The user has an existing live SDK and wants the generated output to preserve its public API (method names, type names, exports).
 
@@ -75,13 +76,15 @@ When a user passes `--api-surface` to `oagen generate` or `oagen diff`, the engi
 
 **`OverlayLookup` fields:**
 
-| Field               | Type                         | Purpose                                          |
-| ------------------- | ---------------------------- | ------------------------------------------------ |
-| `methodByOperation` | `Map<string, MethodOverlay>` | HTTP key → existing method info (name, params)   |
-| `httpKeyByMethod`   | `Map<string, string>`        | Reverse map: "Class.method" → HTTP key           |
-| `interfaceByName`   | `Map<string, string>`        | IR interface name → existing interface name      |
-| `typeAliasByName`   | `Map<string, string>`        | IR type alias name → existing type alias name    |
-| `requiredExports`   | `Map<string, Set<string>>`   | Barrel file path → symbols that must be exported |
+| Field               | Type                         | Purpose                                                                 |
+| ------------------- | ---------------------------- | ----------------------------------------------------------------------- |
+| `methodByOperation` | `Map<string, MethodOverlay>` | HTTP key → existing method info (name, params)                          |
+| `httpKeyByMethod`   | `Map<string, string>`        | Reverse map: "Class.method" → HTTP key                                  |
+| `interfaceByName`   | `Map<string, string>`        | IR interface name → existing interface name                             |
+| `typeAliasByName`   | `Map<string, string>`        | IR type alias name → existing type alias name                           |
+| `requiredExports`   | `Map<string, Set<string>>`   | Barrel file path → symbols that must be exported                        |
+| `modelNameByIR`     | `Map<string, string>`        | IR model name → SDK interface name (auto-inferred from field structure) |
+| `fileBySymbol`      | `Map<string, string>`        | IR symbol name → relative file path in the live SDK                     |
 
 The `httpKeyByMethod` reverse map is only populated when a manifest (`smoke-manifest.json`) is available. Without it, method-level violations cannot be auto-patched in the self-correcting loop. Emitters that support compat verification should implement `generateManifest`.
 

package/docs/architecture/extractor-contract.md

@@ -35,16 +35,16 @@ interface ApiSurface {
 
 Each sub-type captures a different kind of public symbol:
 
-| Type           | Fields                                               | What it captures                                 |
-| -------------- | ---------------------------------------------------- | ------------------------------------------------ |
-| `ApiClass`     | `name`, `methods`, `properties`, `constructorParams` | Public classes with their methods and properties |
-| `ApiMethod`    | `name`, `params`, `returnType`, `async`              | Method signatures                                |
-| `ApiParam`     | `name`, `type`, `optional`                           | Method and constructor parameters                |
-| `ApiProperty`  | `name`, `type`, `readonly`                           | Class properties                                 |
-| `ApiInterface` | `name`, `fields`, `extends`                          | Interface declarations                           |
-| `ApiField`     | `name`, `type`, `optional`                           | Interface fields                                 |
-| `ApiTypeAlias` | `name`, `value`                                      | Type alias declarations                          |
-| `ApiEnum`      | `name`, `members`                                    | Enum declarations with member values             |
+| Type           | Fields                                                              | What it captures                                                                  |
+| -------------- | ------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
+| `ApiClass`     | `name`, `sourceFile?`, `methods`, `properties`, `constructorParams` | Public classes with their methods and properties                                  |
+| `ApiMethod`    | `name`, `params`, `returnType`, `async`                             | Method signatures (methods is `Record<string, ApiMethod[]>` to support overloads) |
+| `ApiParam`     | `name`, `type`, `optional`                                          | Method and constructor parameters                                                 |
+| `ApiProperty`  | `name`, `type`, `readonly`                                          | Class properties                                                                  |
+| `ApiInterface` | `name`, `sourceFile?`, `fields`, `extends`                          | Interface declarations                                                            |
+| `ApiField`     | `name`, `type`, `optional`                                          | Interface fields                                                                  |
+| `ApiTypeAlias` | `name`, `sourceFile?`, `value`                                      | Type alias declarations                                                           |
+| `ApiEnum`      | `name`, `sourceFile?`, `members`                                    | Enum declarations with member values                                              |
 
 The `exports` field maps file paths to their exported symbol names, capturing the barrel export structure.
 
@@ -62,18 +62,23 @@ The `exports` field maps file paths to their exported symbol names, capturing th
 
 Every extractor must provide a `hints: LanguageHints` object that tells the differ and overlay how to interpret language-specific type strings. The `LanguageHints` interface includes:
 
-| Method/Property                     | Purpose                                       | Node example                                     | Go example                           |
-| ----------------------------------- | --------------------------------------------- | ------------------------------------------------ | ------------------------------------ |
-| `stripNullable(type)`               | Strip nullable wrapper                        | `"string \| null"` → `"string"`                  | `"*Organization"` → `"Organization"` |
-| `isNullableOnlyDifference(a, b)`    | True if a and b differ only by nullability    | `"string"` vs `"string \| null"` → true          |                                      |
-| `isUnionReorder(a, b)`              | True if same union members in different order | `"a" \| "b"` vs `"b" \| "a"` → true              | Always false (Go has no unions)      |
-| `isGenericTypeParam(type)`          | True if type is an unresolvable generic param | `"T"`, `"TCustomAttributes"` → true              |                                      |
-| `isExtractionArtifact(type)`        | True if type is an extraction artifact        | `"any"` → true                                   | `"interface{}"` → true               |
-| `tolerateCategoryMismatch`          | Allow type alias ↔ interface/class mismatch   | `true` (TS allows both forms)                    | `false`                              |
-| `extractReturnTypeName(returnType)` | Extract innermost type from return type       | `"Promise<Organization>"` → `"Organization"`     |                                      |
-| `extractParamTypeName(paramType)`   | Extract type from param (null for primitives) | `"string"` → null                                |                                      |
-| `propertyMatchesClass(prop, class)` | True if property maps to class name           | camelCase: `"organizations"` → `"Organizations"` |                                      |
-| `derivedModelNames(modelName)`      | Additional names a model produces             | `["FooResponse", "SerializedFoo"]`               | `["FooResponse"]`                    |
+| Method/Property                     | Purpose                                                          | Node example                                     | Go example                           |
+| ----------------------------------- | ---------------------------------------------------------------- | ------------------------------------------------ | ------------------------------------ |
+| `stripNullable(type)`               | Strip nullable wrapper                                           | `"string \| null"` → `"string"`                  | `"*Organization"` → `"Organization"` |
+| `isNullableOnlyDifference(a, b)`    | True if a and b differ only by nullability                       | `"string"` vs `"string \| null"` → true          |                                      |
+| `isUnionReorder(a, b)`              | True if same union members in different order                    | `"a" \| "b"` vs `"b" \| "a"` → true              | Always false (Go has no unions)      |
+| `isGenericTypeParam(type)`          | True if type is an unresolvable generic param                    | `"T"`, `"TCustomAttributes"` → true              |                                      |
+| `isExtractionArtifact(type)`        | True if type is an extraction artifact                           | `"any"` → true                                   | `"interface{}"` → true               |
+| `tolerateCategoryMismatch`          | Allow type alias ↔ interface/class mismatch                      | `true` (TS allows both forms)                    | `false`                              |
+| `extractReturnTypeName(returnType)` | Extract innermost type from return type                          | `"Promise<Organization>"` → `"Organization"`     |                                      |
+| `extractParamTypeName(paramType)`   | Extract type from param (null for primitives)                    | `"string"` → null                                |                                      |
+| `propertyMatchesClass(prop, class)` | True if property maps to class name                              | camelCase: `"organizations"` → `"Organizations"` |                                      |
+| `derivedModelNames(modelName)`      | Additional names a model produces                                | `["FooResponse", "SerializedFoo"]`               | `["FooResponse"]`                    |
+| `isTypeEquivalent?(a, b, surface)`  | True if types are semantically equivalent                        | Named enum vs inline union of literals           |                                      |
+| `isSignatureEquivalent?(a, b, s)`   | True if signatures are equivalent despite structural differences | Unpacked params vs dict payload                  |                                      |
+| `modelBaseClasses?`                 | Base class names indicating a data model                         | `["BaseModel"]` (Python/Pydantic)                | —                                    |
+| `exceptionBaseClasses?`             | Base class names indicating an exception                         | `["Exception"]`                                  | —                                    |
+| `listResourcePatterns?`             | Type names for list/paginated wrappers                           | `["ListResource"]`                               | —                                    |
 
 Use `resolveHints({...overrides})` to start from Node defaults and override only the methods that differ for your language:
 
@@ -225,3 +230,6 @@ Use `/generate-extractor <language>` for a guided workflow.
 | Rust     | `rust.ts`, `rust-parser.ts`, `rust-surface.ts`       |
 | PHP      | `php.ts`, `php-parser.ts`, `php-surface.ts`          |
 | Python   | `python.ts`, `python-parser.ts`, `python-surface.ts` |
+| Kotlin   | `kotlin.ts`, `kotlin-parser.ts`, `kotlin-surface.ts` |
+| .NET     | `dotnet.ts`, `dotnet-parser.ts`, `dotnet-surface.ts` |
+| Elixir   | `elixir.ts`, `elixir-parser.ts`, `elixir-surface.ts` |

package/docs/architecture/ir-types.md

@@ -36,7 +36,7 @@ Every type in the IR is a `TypeRef`, discriminated on the `kind` field:
 | `primitive` | `PrimitiveType` | `{ kind: "primitive", type: "string" }`                              |
 | `array`     | `ArrayType`     | `{ kind: "array", items: { kind: "primitive", type: "string" } }`    |
 | `model`     | `ModelRef`      | `{ kind: "model", name: "Organization" }`                            |
-| `enum`      | `EnumRef`       | `{ kind: "enum", name: "Status" }`                                   |
+| `enum`      | `EnumRef`       | `{ kind: "enum", name: "Status", values?: ["active", "inactive"] }`  |
 | `union`     | `UnionType`     | `{ kind: "union", variants: [...], discriminator?: {...} }`          |
 | `nullable`  | `NullableType`  | `{ kind: "nullable", inner: { kind: "primitive", type: "string" } }` |
 | `literal`   | `LiteralType`   | `{ kind: "literal", value: "active" }`                               |
@@ -196,6 +196,7 @@ interface Parameter {
   description?: string;
   deprecated?: boolean;
   default?: unknown;
+  example?: unknown;
 }
 ```
 

package/docs/architecture/pipeline.md

@@ -107,4 +107,4 @@ export default {
 
 ## Diff Engine (`src/differ/`)
 
-Compares two parsed specs (old vs new) and determines which files need regeneration. Classifies changes as additive, breaking, or mixed.
+Compares two parsed specs (old vs new) and produces a `DiffReport` classifying changes as additive, breaking, or mixed. Used by the `oagen diff` CLI command for review before regenerating.

package/docs/architecture/workflows.md

@@ -101,20 +101,11 @@ output of Scenario B's initial generation).
 Every spec update uses `--target` to merge into the live SDK and `--api-surface`
 to preserve backwards compatibility:
 
-1. **Review changes:** `oagen diff --old v1.yml --new v2.yml --report`
+1. **Review changes:** `oagen diff --old v1.yml --new v2.yml`
 2. **Regenerate:** `oagen generate --spec v2.yml --lang {lang} --output ./sdk --target {sdk_path} --api-surface sdk-{lang}-surface.json`
 3. **Verify:** `oagen verify --spec v2.yml --lang {lang} --output ./sdk --api-surface sdk-{lang}-surface.json`
 4. **Ship** if verify exits 0
 
-**Alternative: incremental generation.** Instead of full `generate`, use
-`diff` in generation mode to only regenerate affected files. This also supports
-`--target` for live SDK integration:
-
-```bash
-oagen diff --old v1.yml --new v2.yml --lang ruby --output ./sdk --target {sdk_path} --api-surface sdk-{lang}-surface.json
-oagen verify --spec v2.yml --lang ruby --output ./sdk --api-surface sdk-{lang}-surface.json
-```
-
 **External consumers** configure emitters and extractors via `oagen.config.ts`
 instead of modifying CLI source — see the Configuration section in the README.
 
@@ -144,17 +135,27 @@ The verify pipeline returns structured result types that consumers can use progr
 ```typescript
 interface VerifyDiagnostics {
   compatCheck?: {
-    totalBaselineSymbols;
-    preservedSymbols;
-    preservationScore;
-    violationsByCategory;
-    violationsBySeverity;
-    additions;
-    scopedToSpec;
-    scopedSymbolCount?;
+    totalBaselineSymbols: number;
+    preservedSymbols: number;
+    preservationScore: number;
+    violationsByCategory: Record<string, number>;
+    violationsBySeverity: Record<string, number>;
+    additions: number;
+    scopedToSpec: boolean;
+    scopedSymbolCount?: number;
+  };
+  stalenessCheck?: { staleSymbolCount: number; staleSymbols: string[] };
+  smokeCheck?: {
+    passed: boolean;
+    findingsCount?: number;
+    compileErrors?: boolean;
+  };
+  retryLoop?: {
+    attempts: number;
+    converged: boolean;
+    finalScore: number;
+    patchedPerIteration: number[];
   };
-  smokeCheck?: { passed; findingsCount?; compileErrors?; baselinePath };
-  stalenessCheck?: { violations };
 }
 
 interface CompatCheckResult {