@workos/oagen 0.6.0 → 0.8.0

package/dist/verify/index.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.mjs","names":["path","path"],"sources":["../../src/verify/run-compat-check.ts","../../src/verify/run-overlay-retry-loop.ts","../../src/compat/staleness.ts","../../src/verify/run-staleness-check.ts","../../src/verify/run-smoke-check.ts"],"sourcesContent":["import { getExtractor } from '../compat/extractor-registry.js';\nimport {\n  diffSurfaces,\n  specDerivedNames,\n  specDerivedFieldPaths,\n  specDerivedMethodPaths,\n  specDerivedEnumValues,\n  filterSurface,\n} from '../compat/differ.js';\nimport type { ApiSpec } from '../ir/types.js';\nimport type { ApiSurface } from '../compat/types.js';\nimport type { CompatCheckResult } from './types.js';\n\nexport async function runCompatCheck(\n  baseline: ApiSurface,\n  outputDir: string,\n  lang: string,\n  spec?: ApiSpec,\n): Promise<CompatCheckResult> {\n  const extractor = getExtractor(lang);\n  const candidate = await extractor.extract(outputDir);\n\n  let scopedBaseline = baseline;\n  let scopedToSpec = false;\n  let scopedSymbolCount: number | undefined;\n  if (spec) {\n    const allowed = specDerivedNames(spec, extractor.hints);\n    const fieldPaths = specDerivedFieldPaths(spec, extractor.hints);\n    const methodPaths = specDerivedMethodPaths(spec);\n    const enumVals = specDerivedEnumValues(spec);\n    scopedBaseline = filterSurface(baseline, allowed, { fieldPaths, methodPaths, enumValues: enumVals });\n    scopedToSpec = true;\n    scopedSymbolCount =\n      Object.keys(scopedBaseline.interfaces).length +\n      Object.keys(scopedBaseline.classes).length +\n      Object.keys(scopedBaseline.typeAliases).length +\n      Object.keys(scopedBaseline.enums).length;\n  }\n\n  const diff = diffSurfaces(scopedBaseline, candidate, extractor.hints);\n  const passed = diff.violations.every((v) => v.severity !== 'breaking');\n\n  return { passed, diff, scopedToSpec, scopedSymbolCount };\n}\n","import { existsSync, readFileSync, readdirSync, unlinkSync, statSync, openSync, readSync, closeSync } from 'node:fs';\nimport * as path from 'node:path';\nimport { buildOverlayLookup, patchOverlay } from '../compat/overlay.js';\nimport type { ManifestEntry } from '../compat/overlay.js';\nimport { getExtractor } from '../compat/extractor-registry.js';\nimport type { ApiSurface, ViolationCategory } from '../compat/types.js';\nimport type { ApiSpec } from '../ir/types.js';\nimport { getEmitter } from '../engine/registry.js';\nimport { generate } from '../engine/orchestrator.js';\nimport { runCompatCheck } from './run-compat-check.js';\nimport type { OverlayRetryResult } from './types.js';\n\nconst PATCHABLE_CATEGORIES: Set<ViolationCategory> = new Set(['public-api', 'export-structure']);\n\n/** Generated file header markers used by various emitters. */\nconst GENERATED_MARKERS = ['Code generated by oagen', 'auto-generated by oagen', 'This file is auto-generated'];\n\n/**\n * Delete oagen-generated source files so the retry loop can regenerate them\n * with overlay-corrected names. Only deletes files that contain an oagen\n * generation marker, preserving hand-written files.\n */\nfunction cleanGeneratedFiles(dir: string): void {\n  let entries: string[];\n  try {\n    entries = readdirSync(dir);\n  } catch {\n    return;\n  }\n  for (const entry of entries) {\n    const full = path.join(dir, entry);\n    let stat;\n    try {\n      stat = statSync(full);\n    } catch {\n      continue;\n    }\n    if (stat.isDirectory()) {\n      cleanGeneratedFiles(full);\n      continue;\n    }\n    // Skip non-source files and manifests\n    if (entry.endsWith('.json') || entry.endsWith('.lock')) continue;\n    // Read only the first 200 bytes to check for generation marker\n    try {\n      const buf = Buffer.alloc(200);\n      const fd = openSync(full, 'r');\n      try {\n        readSync(fd, buf, 0, 200, 0);\n      } finally {\n        closeSync(fd);\n      }\n      const header = buf.toString('utf-8');\n      if (GENERATED_MARKERS.some((m) => header.includes(m))) {\n        unlinkSync(full);\n      }\n    } catch {\n      // ignore read/delete errors\n    }\n  }\n}\n\n/**\n * Load a smoke-manifest.json from the generated SDK directory and convert\n * it to ManifestEntry[] for the overlay builder.\n */\nfunction loadManifestFromDir(outputDir: string): ManifestEntry[] | undefined {\n  const manifestPath = path.join(outputDir, 'smoke-manifest.json');\n  if (!existsSync(manifestPath)) return undefined;\n  try {\n    const parsed = JSON.parse(readFileSync(manifestPath, 'utf-8'));\n    if (Array.isArray(parsed)) return parsed as ManifestEntry[];\n    if (typeof parsed === 'object' && parsed !== null) {\n      return Object.entries(parsed).map(([httpKey, value]) => {\n        const spaceIdx = httpKey.indexOf(' ');\n        const httpMethod = httpKey.slice(0, spaceIdx);\n        const httpPath = httpKey.slice(spaceIdx + 1);\n        const v = value as { sdkMethod?: string; service?: string };\n        return {\n          operationId: '',\n          sdkResourceProperty: v.service ?? '',\n          sdkMethodName: v.sdkMethod ?? '',\n          httpMethod,\n          path: httpPath,\n          pathParams: [],\n          bodyFields: [],\n          queryFields: [],\n        };\n      });\n    }\n  } catch {\n    // ignore parse errors\n  }\n  return undefined;\n}\n\nexport async function runOverlayRetryLoop(opts: {\n  baseline: ApiSurface;\n  parsedSpec: ApiSpec;\n  outputDir: string;\n  lang: string;\n  maxRetries: number;\n  namespace?: string;\n  onRetry?: (attemptNumber: number, maxRetries: number, patchableCount: number) => void;\n}): Promise<OverlayRetryResult> {\n  const { baseline, parsedSpec, outputDir, lang, maxRetries, namespace, onRetry } = opts;\n\n  const manifest = loadManifestFromDir(outputDir);\n  // Pass language-specific hints so property-to-class matching works correctly\n  // (e.g., Ruby snake_case \"api_keys\" → PascalCase \"ApiKeys\").\n  const extractor = getExtractor(lang);\n  let overlay = buildOverlayLookup(baseline, manifest, parsedSpec, extractor.hints);\n  let prevPreserved = -1;\n  const patchedPerIteration: number[] = [];\n\n  for (let attempt = 0; attempt <= maxRetries; attempt++) {\n    const compatResult = await runCompatCheck(baseline, outputDir, lang, parsedSpec);\n    if (compatResult.passed) {\n      return {\n        status: 'passed',\n        attempts: attempt,\n        patchedPerIteration,\n        compatResult,\n      };\n    }\n\n    if (attempt === maxRetries) {\n      return {\n        status: 'max-retries',\n        attempts: attempt,\n        patchedPerIteration,\n        compatResult,\n      };\n    }\n\n    const patchable = compatResult.diff.violations.filter((v) => PATCHABLE_CATEGORIES.has(v.category));\n    if (patchable.length === 0) {\n      return {\n        status: 'no-patchable',\n        attempts: attempt,\n        patchedPerIteration,\n        compatResult,\n      };\n    }\n\n    const currentPreserved = compatResult.diff.preservedSymbols;\n    if (attempt > 0 && currentPreserved <= prevPreserved) {\n      return {\n        status: 'stalled',\n        attempts: attempt,\n        patchedPerIteration,\n        compatResult,\n      };\n    }\n    prevPreserved = currentPreserved;\n    patchedPerIteration.push(patchable.length);\n    onRetry?.(attempt + 1, maxRetries, patchable.length);\n\n    overlay = patchOverlay(overlay, patchable, baseline);\n\n    // Pre-delete generated source files so the writer creates them fresh\n    // with overlay-corrected names. Without this, the AST merger would preserve\n    // old method/class names from the existing files.\n    // Only delete files that look like oagen-generated source files (have the header).\n    cleanGeneratedFiles(outputDir);\n\n    const emitter = getEmitter(lang);\n    await generate(parsedSpec, emitter, {\n      namespace: namespace ?? parsedSpec.name,\n      outputDir,\n      overlayLookup: overlay,\n      apiSurface: baseline,\n    });\n  }\n\n  const compatResult = await runCompatCheck(baseline, outputDir, lang, parsedSpec);\n  return {\n    status: 'max-retries',\n    attempts: maxRetries,\n    patchedPerIteration,\n    compatResult,\n  };\n}\n","import type { ApiSurface, LanguageHints, Violation } from './types.js';\nimport type { ApiSpec } from '../ir/types.js';\nimport { specDerivedNames, specDerivedFieldPaths } from './spec-filter.js';\nimport { diffSpecs } from '../differ/diff.js';\n\n/**\n * Detect symbols that exist in the live SDK surface but are no longer defined\n * in the current OpenAPI spec. These are \"stale\" — they compile and run but\n * represent dead code from a previous spec version.\n *\n * Requires both the old and new spec so we can distinguish hand-written SDK\n * symbols (never in any spec) from genuinely removed spec symbols.\n */\nexport function detectStaleSymbols(\n  liveSurface: ApiSurface,\n  oldSpec: ApiSpec,\n  newSpec: ApiSpec,\n  hints: LanguageHints,\n): Violation[] {\n  const violations: Violation[] = [];\n\n  // Step 1-3: Name-set difference for top-level symbols\n  const oldNames = specDerivedNames(oldSpec, hints);\n  const newNames = specDerivedNames(newSpec, hints);\n\n  const removedNames = new Set<string>();\n  for (const name of oldNames) {\n    if (!newNames.has(name)) removedNames.add(name);\n  }\n\n  for (const name of removedNames) {\n    if (liveSurface.classes[name]) {\n      violations.push({\n        category: 'staleness',\n        severity: 'warning',\n        symbolPath: name,\n        baseline: name,\n        candidate: '(removed from spec)',\n        message: `Class \"${name}\" is no longer defined in the OpenAPI spec`,\n      });\n    }\n    if (liveSurface.interfaces[name]) {\n      violations.push({\n        category: 'staleness',\n        severity: 'warning',\n        symbolPath: name,\n        baseline: name,\n        candidate: '(removed from spec)',\n        message: `Interface \"${name}\" is no longer defined in the OpenAPI spec`,\n      });\n    }\n    if (liveSurface.typeAliases[name]) {\n      violations.push({\n        category: 'staleness',\n        severity: 'warning',\n        symbolPath: name,\n        baseline: name,\n        candidate: '(removed from spec)',\n        message: `Type alias \"${name}\" is no longer defined in the OpenAPI spec`,\n      });\n    }\n    if (liveSurface.enums[name]) {\n      violations.push({\n        category: 'staleness',\n        severity: 'warning',\n        symbolPath: name,\n        baseline: name,\n        candidate: '(removed from spec)',\n        message: `Enum \"${name}\" is no longer defined in the OpenAPI spec`,\n      });\n    }\n  }\n\n  // Step 4-6: Field-level staleness for models that still exist in new spec\n  const oldFieldPaths = specDerivedFieldPaths(oldSpec, hints);\n  const newFieldPaths = specDerivedFieldPaths(newSpec, hints);\n\n  for (const fieldPath of oldFieldPaths) {\n    if (newFieldPaths.has(fieldPath)) continue;\n\n    const [modelName, fieldName] = fieldPath.split('.');\n    // Only flag field-level staleness for models that still exist in the new spec\n    // (fully removed models are already caught above)\n    if (removedNames.has(modelName)) continue;\n\n    const iface = liveSurface.interfaces[modelName];\n    if (iface?.fields[fieldName]) {\n      violations.push({\n        category: 'staleness',\n        severity: 'warning',\n        symbolPath: fieldPath,\n        baseline: fieldName,\n        candidate: '(removed from spec)',\n        message: `Field \"${fieldPath}\" is no longer defined in the OpenAPI spec`,\n      });\n    }\n  }\n\n  // Step 7: Operation-level staleness via diffSpecs\n  const diff = diffSpecs(oldSpec, newSpec);\n  for (const change of diff.changes) {\n    if (change.kind === 'operation-removed') {\n      const cls = liveSurface.classes[change.serviceName];\n      if (cls?.methods[change.operationName]) {\n        violations.push({\n          category: 'staleness',\n          severity: 'warning',\n          symbolPath: `${change.serviceName}.${change.operationName}`,\n          baseline: change.operationName,\n          candidate: '(removed from spec)',\n          message: `Method \"${change.serviceName}.${change.operationName}\" is no longer defined in the OpenAPI spec`,\n        });\n      }\n    }\n  }\n\n  return violations;\n}\n","import { getExtractor } from '../compat/extractor-registry.js';\nimport { detectStaleSymbols } from '../compat/staleness.js';\nimport type { ApiSpec } from '../ir/types.js';\nimport type { ApiSurface } from '../compat/types.js';\nimport type { StalenessCheckResult } from './types.js';\n\nexport function runStalenessCheck(\n  baseline: ApiSurface,\n  oldSpec: ApiSpec,\n  newSpec: ApiSpec,\n  lang: string,\n): StalenessCheckResult {\n  const extractor = getExtractor(lang);\n  const violations = detectStaleSymbols(baseline, oldSpec, newSpec, extractor.hints);\n  return { violations };\n}\n","import { execFileSync } from 'node:child_process';\nimport { existsSync, readFileSync } from 'node:fs';\nimport { fileURLToPath } from 'node:url';\nimport * as path from 'node:path';\nimport { CommandError } from '../errors.js';\nimport type { SmokeCheckResult } from './types.js';\n\nconst __filename = fileURLToPath(import.meta.url);\nconst __dirname = path.dirname(__filename);\n\nfunction resolveScript(scriptRelPath: string): { bin: string; script: string } {\n  const distScript = path.resolve(__dirname, '..', '..', 'dist', 'scripts', scriptRelPath.replace(/\\.ts$/, '.mjs'));\n  if (existsSync(distScript)) {\n    return { bin: 'node', script: distScript };\n  }\n  const srcScript = path.resolve(__dirname, '..', '..', 'scripts', scriptRelPath);\n  return { bin: 'npx', script: srcScript };\n}\n\nfunction runPackagedScript(scriptRelPath: string, args: string[]): void {\n  const { bin, script } = resolveScript(scriptRelPath);\n  const fullArgs = bin === 'npx' ? ['tsx', script, ...args] : [script, ...args];\n  execFileSync(bin, fullArgs, { stdio: 'inherit', env: process.env });\n}\n\nexport function runSmokeCheck(opts: {\n  spec?: string;\n  lang: string;\n  output: string;\n  rawResults?: string;\n  smokeConfig?: string;\n  smokeRunner?: string;\n}): SmokeCheckResult {\n  const { spec, lang, output, rawResults, smokeConfig, smokeRunner } = opts;\n\n  let baselinePath = rawResults ?? 'smoke-results-raw.json';\n  let generatedBaseline = false;\n\n  if (!rawResults && !existsSync('smoke-results-raw.json')) {\n    if (!spec) {\n      throw new CommandError(\n        'error: --spec <path> or OPENAPI_SPEC_PATH env var is required when no raw baseline exists',\n        '',\n        1,\n      );\n    }\n\n    try {\n      runPackagedScript('smoke/baseline.ts', ['--spec', spec]);\n    } catch {\n      throw new CommandError('Baseline generation failed', '', 1);\n    }\n    baselinePath = 'smoke-results-spec-baseline.json';\n    generatedBaseline = true;\n  }\n\n  const smokeArgs = ['--lang', lang, '--sdk-path', output, '--raw-results', baselinePath];\n  if (spec) smokeArgs.push('--spec', spec);\n  if (smokeConfig) smokeArgs.push('--smoke-config', smokeConfig);\n\n  try {\n    if (smokeRunner) {\n      const bin = smokeRunner.endsWith('.ts') ? 'npx' : 'node';\n      const fullArgs = bin === 'npx' ? ['tsx', smokeRunner, ...smokeArgs] : [smokeRunner, ...smokeArgs];\n      execFileSync(bin, fullArgs, { stdio: 'inherit', env: process.env });\n    } else {\n      runPackagedScript('smoke/sdk-test.ts', smokeArgs);\n    }\n\n    return { passed: true, baselinePath, generatedBaseline };\n  } catch {\n    if (existsSync('smoke-compile-errors.json')) {\n      return { passed: false, compileErrors: true, baselinePath, generatedBaseline };\n    }\n\n    const findingsCount = existsSync('smoke-diff-findings.json')\n      ? (JSON.parse(readFileSync('smoke-diff-findings.json', 'utf-8')) as unknown[]).length\n      : undefined;\n\n    return { passed: false, findingsCount, baselinePath, generatedBaseline };\n  }\n}\n"],"mappings":"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"}
+{"version":3,"file":"index.mjs","names":["path","path"],"sources":["../../src/verify/run-compat-check.ts","../../src/verify/run-overlay-retry-loop.ts","../../src/compat/staleness.ts","../../src/verify/run-staleness-check.ts","../../src/verify/run-smoke-check.ts"],"sourcesContent":["import { getExtractor } from '../compat/extractor-registry.js';\nimport {\n  diffSnapshots,\n  specDerivedNames,\n  specDerivedFieldPaths,\n  specDerivedMethodPaths,\n  specDerivedEnumValues,\n  filterSurface,\n} from '../compat/differ.js';\nimport { apiSurfaceToSnapshot } from '../compat/ir.js';\nimport type { LanguageId } from '../compat/ir.js';\nimport { getDefaultPolicy, mergePolicy } from '../compat/policy.js';\nimport type { CompatPolicyHints } from '../compat/policy.js';\nimport type { ApiSpec } from '../ir/types.js';\nimport type { ApiSurface } from '../compat/types.js';\nimport type { CompatCheckResult } from './types.js';\n\nexport async function runCompatCheck(\n  baseline: ApiSurface,\n  outputDir: string,\n  lang: string,\n  spec?: ApiSpec,\n  policyOverrides?: Partial<CompatPolicyHints>,\n): Promise<CompatCheckResult> {\n  const extractor = getExtractor(lang);\n  const candidate = await extractor.extract(outputDir);\n\n  let scopedBaseline = baseline;\n  let scopedToSpec = false;\n  let scopedSymbolCount: number | undefined;\n  if (spec) {\n    const allowed = specDerivedNames(spec, extractor.hints);\n    const fieldPaths = specDerivedFieldPaths(spec, extractor.hints);\n    const methodPaths = specDerivedMethodPaths(spec);\n    const enumVals = specDerivedEnumValues(spec);\n    scopedBaseline = filterSurface(baseline, allowed, { fieldPaths, methodPaths, enumValues: enumVals });\n    scopedToSpec = true;\n    scopedSymbolCount =\n      Object.keys(scopedBaseline.interfaces).length +\n      Object.keys(scopedBaseline.classes).length +\n      Object.keys(scopedBaseline.typeAliases).length +\n      Object.keys(scopedBaseline.enums).length;\n  }\n\n  const baseSnap = apiSurfaceToSnapshot(scopedBaseline);\n  const candSnap = apiSurfaceToSnapshot(candidate);\n\n  const langId = lang as LanguageId;\n  const policy = policyOverrides ? mergePolicy(getDefaultPolicy(langId), policyOverrides) : getDefaultPolicy(langId);\n\n  const diff = diffSnapshots(baseSnap, candSnap, policy);\n  const passed = diff.changes.every((c) => c.severity !== 'breaking');\n\n  return { passed, diff, scopedToSpec, scopedSymbolCount };\n}\n","import { existsSync, readFileSync, readdirSync, unlinkSync, statSync, openSync, readSync, closeSync } from 'node:fs';\nimport * as path from 'node:path';\nimport { buildOverlayLookup, patchOverlay, isPatchableChange } from '../compat/overlay.js';\nimport type { ManifestEntry } from '../compat/overlay.js';\nimport { getExtractor } from '../compat/extractor-registry.js';\nimport type { ApiSurface } from '../compat/types.js';\nimport type { ApiSpec } from '../ir/types.js';\nimport { getEmitter } from '../engine/registry.js';\nimport { generate } from '../engine/orchestrator.js';\nimport { runCompatCheck } from './run-compat-check.js';\nimport type { OverlayRetryResult } from './types.js';\n\n/** Generated file header markers used by various emitters. */\nconst GENERATED_MARKERS = ['Code generated by oagen', 'auto-generated by oagen', 'This file is auto-generated'];\n\n/**\n * Delete oagen-generated source files so the retry loop can regenerate them\n * with overlay-corrected names. Only deletes files that contain an oagen\n * generation marker, preserving hand-written files.\n */\nfunction cleanGeneratedFiles(dir: string): void {\n  let entries: string[];\n  try {\n    entries = readdirSync(dir);\n  } catch {\n    return;\n  }\n  for (const entry of entries) {\n    const full = path.join(dir, entry);\n    let stat;\n    try {\n      stat = statSync(full);\n    } catch {\n      continue;\n    }\n    if (stat.isDirectory()) {\n      cleanGeneratedFiles(full);\n      continue;\n    }\n    // Skip non-source files and manifests\n    if (entry.endsWith('.json') || entry.endsWith('.lock')) continue;\n    // Read only the first 200 bytes to check for generation marker\n    try {\n      const buf = Buffer.alloc(200);\n      const fd = openSync(full, 'r');\n      try {\n        readSync(fd, buf, 0, 200, 0);\n      } finally {\n        closeSync(fd);\n      }\n      const header = buf.toString('utf-8');\n      if (GENERATED_MARKERS.some((m) => header.includes(m))) {\n        unlinkSync(full);\n      }\n    } catch {\n      // ignore read/delete errors\n    }\n  }\n}\n\n/**\n * Load a smoke-manifest.json from the generated SDK directory and convert\n * it to ManifestEntry[] for the overlay builder.\n */\nfunction loadManifestFromDir(outputDir: string): ManifestEntry[] | undefined {\n  const manifestPath = path.join(outputDir, 'smoke-manifest.json');\n  if (!existsSync(manifestPath)) return undefined;\n  try {\n    const parsed = JSON.parse(readFileSync(manifestPath, 'utf-8'));\n    if (Array.isArray(parsed)) return parsed as ManifestEntry[];\n    if (typeof parsed === 'object' && parsed !== null) {\n      return Object.entries(parsed).map(([httpKey, value]) => {\n        const spaceIdx = httpKey.indexOf(' ');\n        const httpMethod = httpKey.slice(0, spaceIdx);\n        const httpPath = httpKey.slice(spaceIdx + 1);\n        const v = value as { sdkMethod?: string; service?: string };\n        return {\n          operationId: '',\n          sdkResourceProperty: v.service ?? '',\n          sdkMethodName: v.sdkMethod ?? '',\n          httpMethod,\n          path: httpPath,\n          pathParams: [],\n          bodyFields: [],\n          queryFields: [],\n        };\n      });\n    }\n  } catch {\n    // ignore parse errors\n  }\n  return undefined;\n}\n\nexport async function runOverlayRetryLoop(opts: {\n  baseline: ApiSurface;\n  parsedSpec: ApiSpec;\n  outputDir: string;\n  lang: string;\n  maxRetries: number;\n  namespace?: string;\n  onRetry?: (attemptNumber: number, maxRetries: number, patchableCount: number) => void;\n}): Promise<OverlayRetryResult> {\n  const { baseline, parsedSpec, outputDir, lang, maxRetries, namespace, onRetry } = opts;\n\n  const manifest = loadManifestFromDir(outputDir);\n  // Pass language-specific hints so property-to-class matching works correctly\n  // (e.g., Ruby snake_case \"api_keys\" → PascalCase \"ApiKeys\").\n  const extractor = getExtractor(lang);\n  let overlay = buildOverlayLookup(baseline, manifest, parsedSpec, extractor.hints);\n  let prevPreserved = -1;\n  const patchedPerIteration: number[] = [];\n\n  for (let attempt = 0; attempt <= maxRetries; attempt++) {\n    const compatResult = await runCompatCheck(baseline, outputDir, lang, parsedSpec);\n    if (compatResult.passed) {\n      return {\n        status: 'passed',\n        attempts: attempt,\n        patchedPerIteration,\n        compatResult,\n      };\n    }\n\n    if (attempt === maxRetries) {\n      return {\n        status: 'max-retries',\n        attempts: attempt,\n        patchedPerIteration,\n        compatResult,\n      };\n    }\n\n    const patchable = compatResult.diff.changes.filter(isPatchableChange);\n    if (patchable.length === 0) {\n      return {\n        status: 'no-patchable',\n        attempts: attempt,\n        patchedPerIteration,\n        compatResult,\n      };\n    }\n\n    const currentBreaking = compatResult.diff.summary.breaking;\n    // Stall detection: if breaking count hasn't decreased, we're not making progress\n    if (attempt > 0 && currentBreaking >= prevPreserved) {\n      return {\n        status: 'stalled',\n        attempts: attempt,\n        patchedPerIteration,\n        compatResult,\n      };\n    }\n    prevPreserved = currentBreaking;\n    patchedPerIteration.push(patchable.length);\n    onRetry?.(attempt + 1, maxRetries, patchable.length);\n\n    overlay = patchOverlay(overlay, patchable, baseline);\n\n    // Pre-delete generated source files so the writer creates them fresh\n    // with overlay-corrected names. Without this, the AST merger would preserve\n    // old method/class names from the existing files.\n    // Only delete files that look like oagen-generated source files (have the header).\n    cleanGeneratedFiles(outputDir);\n\n    const emitter = getEmitter(lang);\n    await generate(parsedSpec, emitter, {\n      namespace: namespace ?? parsedSpec.name,\n      outputDir,\n      overlayLookup: overlay,\n      apiSurface: baseline,\n    });\n  }\n\n  const compatResult = await runCompatCheck(baseline, outputDir, lang, parsedSpec);\n  return {\n    status: 'max-retries',\n    attempts: maxRetries,\n    patchedPerIteration,\n    compatResult,\n  };\n}\n","import type { ApiSurface, LanguageHints, Violation } from './types.js';\nimport type { ApiSpec } from '../ir/types.js';\nimport { specDerivedNames, specDerivedFieldPaths } from './spec-filter.js';\nimport { diffSpecs } from '../differ/diff.js';\n\n/**\n * Detect symbols that exist in the live SDK surface but are no longer defined\n * in the current OpenAPI spec. These are \"stale\" — they compile and run but\n * represent dead code from a previous spec version.\n *\n * Requires both the old and new spec so we can distinguish hand-written SDK\n * symbols (never in any spec) from genuinely removed spec symbols.\n */\nexport function detectStaleSymbols(\n  liveSurface: ApiSurface,\n  oldSpec: ApiSpec,\n  newSpec: ApiSpec,\n  hints: LanguageHints,\n): Violation[] {\n  const violations: Violation[] = [];\n\n  // Step 1-3: Name-set difference for top-level symbols\n  const oldNames = specDerivedNames(oldSpec, hints);\n  const newNames = specDerivedNames(newSpec, hints);\n\n  const removedNames = new Set<string>();\n  for (const name of oldNames) {\n    if (!newNames.has(name)) removedNames.add(name);\n  }\n\n  for (const name of removedNames) {\n    if (liveSurface.classes[name]) {\n      violations.push({\n        category: 'staleness',\n        severity: 'warning',\n        symbolPath: name,\n        baseline: name,\n        candidate: '(removed from spec)',\n        message: `Class \"${name}\" is no longer defined in the OpenAPI spec`,\n      });\n    }\n    if (liveSurface.interfaces[name]) {\n      violations.push({\n        category: 'staleness',\n        severity: 'warning',\n        symbolPath: name,\n        baseline: name,\n        candidate: '(removed from spec)',\n        message: `Interface \"${name}\" is no longer defined in the OpenAPI spec`,\n      });\n    }\n    if (liveSurface.typeAliases[name]) {\n      violations.push({\n        category: 'staleness',\n        severity: 'warning',\n        symbolPath: name,\n        baseline: name,\n        candidate: '(removed from spec)',\n        message: `Type alias \"${name}\" is no longer defined in the OpenAPI spec`,\n      });\n    }\n    if (liveSurface.enums[name]) {\n      violations.push({\n        category: 'staleness',\n        severity: 'warning',\n        symbolPath: name,\n        baseline: name,\n        candidate: '(removed from spec)',\n        message: `Enum \"${name}\" is no longer defined in the OpenAPI spec`,\n      });\n    }\n  }\n\n  // Step 4-6: Field-level staleness for models that still exist in new spec\n  const oldFieldPaths = specDerivedFieldPaths(oldSpec, hints);\n  const newFieldPaths = specDerivedFieldPaths(newSpec, hints);\n\n  for (const fieldPath of oldFieldPaths) {\n    if (newFieldPaths.has(fieldPath)) continue;\n\n    const [modelName, fieldName] = fieldPath.split('.');\n    // Only flag field-level staleness for models that still exist in the new spec\n    // (fully removed models are already caught above)\n    if (removedNames.has(modelName)) continue;\n\n    const iface = liveSurface.interfaces[modelName];\n    if (iface?.fields[fieldName]) {\n      violations.push({\n        category: 'staleness',\n        severity: 'warning',\n        symbolPath: fieldPath,\n        baseline: fieldName,\n        candidate: '(removed from spec)',\n        message: `Field \"${fieldPath}\" is no longer defined in the OpenAPI spec`,\n      });\n    }\n  }\n\n  // Step 7: Operation-level staleness via diffSpecs\n  const diff = diffSpecs(oldSpec, newSpec);\n  for (const change of diff.changes) {\n    if (change.kind === 'operation-removed') {\n      const cls = liveSurface.classes[change.serviceName];\n      if (cls?.methods[change.operationName]) {\n        violations.push({\n          category: 'staleness',\n          severity: 'warning',\n          symbolPath: `${change.serviceName}.${change.operationName}`,\n          baseline: change.operationName,\n          candidate: '(removed from spec)',\n          message: `Method \"${change.serviceName}.${change.operationName}\" is no longer defined in the OpenAPI spec`,\n        });\n      }\n    }\n  }\n\n  return violations;\n}\n","import { getExtractor } from '../compat/extractor-registry.js';\nimport { detectStaleSymbols } from '../compat/staleness.js';\nimport type { ApiSpec } from '../ir/types.js';\nimport type { ApiSurface } from '../compat/types.js';\nimport type { StalenessCheckResult } from './types.js';\n\nexport function runStalenessCheck(\n  baseline: ApiSurface,\n  oldSpec: ApiSpec,\n  newSpec: ApiSpec,\n  lang: string,\n): StalenessCheckResult {\n  const extractor = getExtractor(lang);\n  const violations = detectStaleSymbols(baseline, oldSpec, newSpec, extractor.hints);\n  return { violations };\n}\n","import { execFileSync } from 'node:child_process';\nimport { existsSync, readFileSync } from 'node:fs';\nimport { fileURLToPath } from 'node:url';\nimport * as path from 'node:path';\nimport { CommandError } from '../errors.js';\nimport type { SmokeCheckResult } from './types.js';\n\nconst __filename = fileURLToPath(import.meta.url);\nconst __dirname = path.dirname(__filename);\n\nfunction resolveScript(scriptRelPath: string): { bin: string; script: string } {\n  const distScript = path.resolve(__dirname, '..', '..', 'dist', 'scripts', scriptRelPath.replace(/\\.ts$/, '.mjs'));\n  if (existsSync(distScript)) {\n    return { bin: 'node', script: distScript };\n  }\n  const srcScript = path.resolve(__dirname, '..', '..', 'scripts', scriptRelPath);\n  return { bin: 'npx', script: srcScript };\n}\n\nfunction runPackagedScript(scriptRelPath: string, args: string[]): void {\n  const { bin, script } = resolveScript(scriptRelPath);\n  const fullArgs = bin === 'npx' ? ['tsx', script, ...args] : [script, ...args];\n  execFileSync(bin, fullArgs, { stdio: 'inherit', env: process.env });\n}\n\nexport function runSmokeCheck(opts: {\n  spec?: string;\n  lang: string;\n  output: string;\n  rawResults?: string;\n  smokeConfig?: string;\n  smokeRunner?: string;\n}): SmokeCheckResult {\n  const { spec, lang, output, rawResults, smokeConfig, smokeRunner } = opts;\n\n  let baselinePath = rawResults ?? 'smoke-results-raw.json';\n  let generatedBaseline = false;\n\n  if (!rawResults && !existsSync('smoke-results-raw.json')) {\n    if (!spec) {\n      throw new CommandError(\n        'error: --spec <path> or OPENAPI_SPEC_PATH env var is required when no raw baseline exists',\n        '',\n        1,\n      );\n    }\n\n    try {\n      runPackagedScript('smoke/baseline.ts', ['--spec', spec]);\n    } catch {\n      throw new CommandError('Baseline generation failed', '', 1);\n    }\n    baselinePath = 'smoke-results-spec-baseline.json';\n    generatedBaseline = true;\n  }\n\n  const smokeArgs = ['--lang', lang, '--sdk-path', output, '--raw-results', baselinePath];\n  if (spec) smokeArgs.push('--spec', spec);\n  if (smokeConfig) smokeArgs.push('--smoke-config', smokeConfig);\n\n  try {\n    if (smokeRunner) {\n      const bin = smokeRunner.endsWith('.ts') ? 'npx' : 'node';\n      const fullArgs = bin === 'npx' ? ['tsx', smokeRunner, ...smokeArgs] : [smokeRunner, ...smokeArgs];\n      execFileSync(bin, fullArgs, { stdio: 'inherit', env: process.env });\n    } else {\n      runPackagedScript('smoke/sdk-test.ts', smokeArgs);\n    }\n\n    return { passed: true, baselinePath, generatedBaseline };\n  } catch {\n    if (existsSync('smoke-compile-errors.json')) {\n      return { passed: false, compileErrors: true, baselinePath, generatedBaseline };\n    }\n\n    const findingsCount = existsSync('smoke-diff-findings.json')\n      ? (JSON.parse(readFileSync('smoke-diff-findings.json', 'utf-8')) as unknown[]).length\n      : undefined;\n\n    return { passed: false, findingsCount, baselinePath, generatedBaseline };\n  }\n}\n"],"mappings":"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"}

package/docs/architecture/emitter-contract.md

@@ -154,9 +154,9 @@ Production emitters live in the separate `oagen-emitters` project and import typ
 1. Create design doc at `docs/sdk-architecture/{language}.md` in the emitter project
 2. Scaffold files under `src/{language}/` in the emitter project
 3. Implement all `Emitter` methods
-4. Register in the emitter project's `oagen.config.ts`
+4. Export through the emitter project's plugin bundle (e.g. `src/plugin.ts`)
 5. Add tests under `test/{language}/` in the emitter project
 
 Or use: `/generate-emitter <language>`
 
-Emitters are registered via `oagen.config.ts` — no need to modify CLI source. See the Configuration section in the README.
+Emitters are registered via the plugin bundle exported from the emitter package. The consumer project's `oagen.config.ts` imports the bundle and layers spec interpretation policy on top. See the [CLI Reference](../cli.md#configuration-oagenconfigts) for details.

package/docs/architecture/extractor-contract.md

@@ -98,12 +98,13 @@ const goHints = resolveHints({
 Extractors are registered via `oagen.config.ts` in the consumer project. The CLI loads the config at startup and registers all extractors automatically before any command runs.
 
 ```typescript
-// oagen.config.ts
-import { myExtractor } from "./src/compat/extractors/my-language.js";
+// oagen.config.ts (consumer project)
+import { workosEmittersPlugin } from "@workos/oagen-emitters";
 import type { OagenConfig } from "@workos/oagen";
 
 const config: OagenConfig = {
-  extractors: [myExtractor],
+  ...workosEmittersPlugin, // includes all extractors
+  // spec interpretation policy...
 };
 export default config;
 ```
@@ -212,8 +213,8 @@ All tree-sitter parsers use `safeParse()` from `src/utils/tree-sitter.ts` to han
 3. Provide `hints` as a `LanguageHints` object. Every extractor must have hints — the differ and overlay delegate all language-specific logic through them.
 4. Split into `{language}-parser.ts` and `{language}-surface.ts` if either: (a) the language separates type definitions from method implementations (structural joining needed), or (b) the classification logic for mapping parsed types to `ApiClass`/`ApiInterface`/`ApiEnum` is non-trivial. If the AST co-locates symbols and classification is straightforward, a single `{language}-parser.ts` returning `ApiClass[]` directly is sufficient.
 5. Use `safeParse()` from `src/utils/tree-sitter.ts` instead of calling `parser.parse()` directly.
-6. Export from `src/index.ts`
-7. Register in the consumer project's `oagen.config.ts`
+6. Export from `src/index.ts` and include in the plugin bundle
+7. The consumer project's `oagen.config.ts` picks it up through the plugin bundle
 8. Add tests in `test/compat/extractors/{language}.test.ts`
 9. Create a fixture SDK in `test/fixtures/sample-sdk-{language}/` with known classes, methods, and exports
 10. Verify deterministic output: extracting twice produces identical JSON

package/docs/architecture/pipeline.md

@@ -96,11 +96,12 @@ Every generator method receives:
 Simple map from language name → `Emitter` instance. Emitters are registered at startup via `oagen.config.ts`:
 
 ```typescript
-// In oagen.config.ts (emitter project)
-import { nodeEmitter, rubyEmitter } from "./src/index.js";
+// In oagen.config.ts (consumer project)
+import { workosEmittersPlugin } from "@workos/oagen-emitters";
 
 export default {
-  emitters: [nodeEmitter, rubyEmitter],
+  ...workosEmittersPlugin,
+  // spec interpretation policy...
 };
 ```
 

package/docs/architecture/workflows.md

@@ -12,7 +12,7 @@ gets written or fixed.
 
 ### Skill sequence
 
-**Project setup:** Run `oagen init --lang {language}` to create the emitter project, then implement the emitter methods.
+**Project setup:** Run `oagen init --lang {language}` to scaffold an emitter project, then implement the emitter methods. Export the emitter through a plugin bundle so the consumer project can register it via its `oagen.config.ts`.
 
 **Scenario A** (existing SDK to preserve):
 
@@ -106,8 +106,10 @@ to preserve backwards compatibility:
 3. **Verify:** `oagen verify --spec v2.yml --lang {lang} --output ./sdk --api-surface sdk-{lang}-surface.json`
 4. **Ship** if verify exits 0
 
-**External consumers** configure emitters and extractors via `oagen.config.ts`
-instead of modifying CLI source — see the Configuration section in the README.
+**Consumer projects** register emitters and extractors by importing plugin bundles
+from emitter packages into their `oagen.config.ts`. Spec interpretation policy
+(transforms, hints, mount rules) also lives in the consumer config. See the
+[CLI Reference](../cli.md#configuration-oagenconfigts) for details.
 
 ### If verify fails on a spec update
 

package/docs/cli.md

@@ -52,6 +52,85 @@ oagen extract --sdk-path ./existing-sdk --lang ruby --output my-surface.json
 | `--lang <language>` | Yes      |                           | Target language                                                                                                 |
 | `--output <path>`   | No       | `sdk-{lang}-surface.json` | Output file path (recommend writing to your output dir, e.g. `./sdk/sdk-ruby-surface.json`, and gitignoring it) |
 
+## `oagen compat-extract`
+
+Extract a compat snapshot from a live SDK and write it to a JSON file. The snapshot is a machine-readable record of the SDK's public API surface, used as input to `compat-diff`.
+
+```bash
+oagen compat-extract --sdk-path ./existing-sdk --lang node --output .
+oagen compat-extract --sdk-path ./existing-sdk --lang php --output ./sdk --spec openapi.yml
+```
+
+| Argument            | Required | Default                 | Description                                                                        |
+| ------------------- | -------- | ----------------------- | ---------------------------------------------------------------------------------- |
+| `--sdk-path <path>` | Yes      |                         | Path to the live SDK                                                               |
+| `--lang <language>` | Yes      |                         | Target language                                                                    |
+| `--output <dir>`    | Yes      |                         | Directory to write `.oagen-compat-snapshot.json` into                              |
+| `--spec <path>`     | No       | `OPENAPI_SPEC_PATH` env | Path to OpenAPI spec — enriches symbols with `operationId`, `route`, and `specSha` |
+
+Always writes `.oagen-compat-snapshot.json` in the specified directory. The snapshot file is meant to be committed to the repository and updated on each release.
+
+When `--spec` is provided, the command parses the spec and enriches callable symbols with `operationId` and `route` (HTTP method + path) by matching against spec operations. It also computes a SHA-256 of the spec file and stores it as `source.specSha` in the snapshot.
+
+## `oagen compat-diff`
+
+Diff two compat snapshot files and produce a classified change report. No extraction or spec required — pure file-in, report-out.
+
+```bash
+# Basic diff with terminal output
+oagen compat-diff --baseline .oagen-compat-snapshot.json --candidate /tmp/candidate.json
+
+# With machine-readable report and failure threshold
+oagen compat-diff \
+  --baseline .oagen-compat-snapshot.json \
+  --candidate /tmp/candidate.json \
+  --output compat-report.json \
+  --fail-on breaking
+```
+
+| Argument             | Required | Default    | Description                                        |
+| -------------------- | -------- | ---------- | -------------------------------------------------- |
+| `--baseline <path>`  | Yes      |            | Path to the baseline compat snapshot JSON          |
+| `--candidate <path>` | Yes      |            | Path to the candidate compat snapshot JSON         |
+| `--output <path>`    | No       |            | Write machine-readable JSON report to this path    |
+| `--fail-on <level>`  | No       | `breaking` | Fail threshold: `none`, `breaking`, or `soft-risk` |
+| `--explain`          | No       | `false`    | Include provenance explanations in terminal output |
+
+**Exit codes:** 0 = no changes exceed threshold, 1 = changes exceed threshold.
+
+## `oagen compat-summary`
+
+Format a compat report as a markdown PR comment. Reads the JSON report produced by `compat-diff --output` and outputs markdown to stdout or a file.
+
+```bash
+# Single language
+oagen compat-summary --report compat-report.json | gh pr comment --body-file -
+
+# Cross-language rollup (multiple reports)
+oagen compat-summary --report php.json --report python.json --report go.json
+
+# Write to a file
+oagen compat-summary --report compat-report.json --output summary.md
+```
+
+| Argument             | Required | Default | Description                                                                |
+| -------------------- | -------- | ------- | -------------------------------------------------------------------------- |
+| `--report <path...>` | Yes      |         | Path(s) to compat report JSON(s) — pass multiple for cross-language rollup |
+| `--output <path>`    | No       | stdout  | Write markdown to this file instead of stdout                              |
+
+**Single report** output includes:
+
+- Status header (pass/warning/fail)
+- Summary table with breaking, soft-risk, and additive counts
+- Breaking changes table (always visible)
+- Soft-risk and additive changes in collapsible `<details>` sections
+
+**Multiple reports** produce a cross-language rollup:
+
+- Per-language summary table (breaking/soft-risk/additive per language)
+- Conceptual changes table showing per-language severity for each change
+- Same conceptual change across languages is shown as one row, not N separate rows
+
 ## `oagen verify`
 
 Verify an already-generated SDK — run smoke tests and optional compat checks. Use after `oagen generate`.
@@ -103,9 +182,10 @@ Creates:
 
 - `package.json` with `@workos/oagen` dependency and `sdk:generate`/`sdk:verify`/`sdk:extract` scripts
 - `tsconfig.json`, `vitest.config.ts`, `tsup.config.ts` — build/test tooling
-- `oagen.config.ts` — registers the stub emitter
+- `oagen.config.ts` — minimal config for local development, imports the plugin bundle
+- `src/plugin.ts` — plugin bundle export registering the stub emitter
 - `src/{language}/index.ts` — stub emitter implementing the full `Emitter` interface
-- `src/index.ts` — barrel export
+- `src/index.ts` — barrel export including the plugin bundle
 - Empty directories: `test/`, `smoke/`, `docs/sdk-architecture/`
 
 After initialization, `npm run typecheck` passes immediately. Implement your emitter methods in `src/{language}/` to start generating SDK code.
@@ -141,19 +221,80 @@ oagen resolve --spec openapi.yml --format json
 
 When `oagen.config.ts` defines `operationHints` and/or `mountRules`, they are applied automatically. The table format flags operations that have no hint and are resolved purely by algorithm.
 
+## `--config <path>`
+
+All commands accept a global `--config <path>` option to load a specific config file instead of the default cwd-based discovery.
+
+```bash
+# Explicit config
+oagen generate --config ../openapi-spec/oagen.config.ts --spec openapi.yml --lang node --output ./sdk
+
+# Default: searches for oagen.config.ts in the current directory
+oagen generate --spec openapi.yml --lang node --output ./sdk
+```
+
+When `--config` is omitted, the CLI searches the current working directory for `oagen.config.ts`, `oagen.config.js`, or `oagen.config.mjs` in that order.
+
 ## Configuration (`oagen.config.ts`)
 
-Place an `oagen.config.ts` (or `.js`/`.mjs`) in your project root to register emitters, extractors, and customize pipeline behavior. The CLI loads this file at startup before any command runs.
+Place an `oagen.config.ts` (or `.js`/`.mjs`) in the project that drives generation. The CLI loads this file at startup before any command runs.
+
+The config file belongs to the **consumer project** (the project that owns spec interpretation policy), not the emitter library. Emitter packages export plugin bundles that the consumer config composes.
+
+### Consumer config (recommended)
+
+```ts
+import type { OagenConfig } from "@workos/oagen";
+import { workosEmittersPlugin } from "@workos/oagen-emitters";
+
+const config: OagenConfig = {
+  ...workosEmittersPlugin,
+  docUrl: "https://workos.com/docs",
+  operationIdTransform: (id) => id.replace(/Controller_/, ""),
+  operationHints,
+  mountRules,
+};
+
+export default config;
+```
+
+### Standalone emitter config
+
+For standalone emitter projects that also serve as the consumer:
 
 ```ts
 import type { OagenConfig } from "@workos/oagen";
 import { nodeEmitter } from "./src/node/index.js";
-import { nodeExtractor } from "./src/node/extractor.js";
 
 const config: OagenConfig = {
   emitters: [nodeEmitter],
-  extractors: [nodeExtractor],
-  docUrl: "https://workos.com/docs",
+};
+
+export default config;
+```
+
+### Composing multiple plugin bundles
+
+```ts
+import type { OagenConfig } from "@workos/oagen";
+import { workosEmittersPlugin } from "@workos/oagen-emitters";
+import { experimentalPlugin } from "@workos/oagen-experimental";
+
+const config: OagenConfig = {
+  emitters: [
+    ...(workosEmittersPlugin.emitters ?? []),
+    ...(experimentalPlugin.emitters ?? []),
+  ],
+  extractors: [
+    ...(workosEmittersPlugin.extractors ?? []),
+    ...(experimentalPlugin.extractors ?? []),
+  ],
+  smokeRunners: {
+    ...(workosEmittersPlugin.smokeRunners ?? {}),
+    ...(experimentalPlugin.smokeRunners ?? {}),
+  },
+  operationHints,
+  mountRules,
 };
 
 export default config;
@@ -168,6 +309,7 @@ export default config;
 | `emitterProject`       | `string`                        | Path to the emitter project directory. Used by skills to scaffold new emitters, tests, and smoke runners in the correct location.                                                                                                                |
 | `smokeRunners`         | `Record<string, string>`        | Map from language key to custom smoke runner script path. Overrides the built-in `sdk-test.ts` for `oagen verify`. Can also be set per-invocation with `--smoke-runner`.                                                                         |
 | `operationIdTransform` | `(id: string) => string`        | Custom transform for operation IDs. Receives the raw `operationId` from the spec; return the desired operation name. No additional casing conversion is applied. When omitted, `operationId` values are converted to `camelCase`.                |
+| `schemaNameTransform`  | `(name: string) => string`      | Custom transform for schema (model/enum) names. Applied after the built-in `cleanSchemaName` normalization. Receives the cleaned PascalCase name; return the desired name.                                                                       |
 | `docUrl`               | `string`                        | Base URL for documentation links. When set, relative markdown paths in descriptions (e.g. `[User](/reference/authkit/user)`) are expanded to full URLs (e.g. `[User](https://workos.com/docs/reference/authkit/user)`).                          |
 | `operationHints`       | `Record<string, OperationHint>` | Per-operation overrides keyed by `"METHOD /path"`. Override derived method names, remount to a different service, or split union-body operations into typed wrappers. See [Operation Resolution](architecture/ir-types.md#operation-resolution). |
 | `mountRules`           | `Record<string, string>`        | Service-level remounting. Maps IR service name to target service/namespace (PascalCase). All operations in the source service are mounted on the target unless overridden per-operation in `operationHints`.                                     |

package/docs/contributor/public-api.md

@@ -15,7 +15,7 @@ It includes:
 - spec diffing APIs such as `diffSpecs`
 - naming utilities used by emitters
 - `planOperation`
-- config typing needed by emitter projects
+- config typing needed by consumer and emitter projects
 
 Changes to this surface require a deliberate compatibility review.
 

package/docs/core/compatibility-ir.md

@@ -0,0 +1,200 @@
+# Compatibility IR
+
+The compatibility IR defines the types used to represent, diff, and classify SDK public API surfaces.
+
+## CompatSnapshot
+
+A full snapshot of an SDK's public API surface.
+
+```ts
+interface CompatSnapshot {
+  schemaVersion: string;
+  source: {
+    specSha?: string;
+    extractedAt: string;
+  };
+  policies: CompatPolicyHints;
+  symbols: CompatSymbol[];
+}
+```
+
+## CompatSymbol
+
+A single public API symbol.
+
+```ts
+interface CompatSymbol {
+  id: string;
+  kind: CompatSymbolKind;
+  fqName: string;
+  ownerFqName?: string;
+  displayName: string;
+  visibility: "public" | "protected" | "internal";
+  stability: "stable" | "unstable" | "deprecated";
+  sourceKind: CompatSourceKind;
+  operationId?: string;
+  schemaName?: string;
+  route?: { method: string; path: string };
+  parameters?: CompatParameter[];
+  returns?: CompatTypeRef;
+}
+```
+
+### Symbol Kinds
+
+| Kind               | Description                              |
+| ------------------ | ---------------------------------------- |
+| `service_accessor` | A service class (e.g., `UserManagement`) |
+| `callable`         | A method on a service class              |
+| `constructor`      | A constructor/initializer                |
+| `field`            | A field on an interface/model            |
+| `property`         | A property on a class                    |
+| `enum`             | An enum type                             |
+| `enum_member`      | A member of an enum                      |
+| `alias`            | A type alias or interface name           |
+
+### Source Kinds
+
+| Source Kind                      | Description                      |
+| -------------------------------- | -------------------------------- |
+| `generated_service_wrapper`      | Generated from an API service    |
+| `generated_model_constructor`    | Generated model constructor      |
+| `generated_resource_constructor` | Generated resource constructor   |
+| `generated_enum`                 | Generated from an enum schema    |
+| `compat_alias`                   | Added for backward compatibility |
+
+## CompatParameter
+
+```ts
+interface CompatParameter {
+  publicName: string;
+  wireName?: string;
+  position: number;
+  required: boolean;
+  nullable: boolean;
+  hasDefault: boolean;
+  passing: CompatPassingStyle;
+  type: CompatTypeRef;
+  sensitivity: ParameterSensitivity;
+}
+```
+
+### Passing Styles
+
+| Style                   | Description             | Languages                      |
+| ----------------------- | ----------------------- | ------------------------------ |
+| `positional`            | Position-only arguments | Go, Rust                       |
+| `keyword`               | Keyword arguments       | Python, Ruby, Elixir           |
+| `named`                 | Named arguments         | PHP, Kotlin, C#                |
+| `keyword_or_positional` | Either style            | Python (positional-or-keyword) |
+| `options_object`        | Object destructuring    | Node/TypeScript                |
+| `builder`               | Builder pattern         | Java-style                     |
+
+### Parameter Sensitivity
+
+```ts
+interface ParameterSensitivity {
+  order: boolean; // Position changes are breaking
+  publicName: boolean; // Name changes are breaking
+  requiredness: boolean; // Requiredness changes are breaking
+  type: boolean; // Type changes are breaking
+}
+```
+
+## Change Categories
+
+### Breaking
+
+| Category                                       | Description                                         |
+| ---------------------------------------------- | --------------------------------------------------- |
+| `symbol_removed`                               | A public symbol was removed                         |
+| `symbol_renamed`                               | A public symbol was renamed                         |
+| `parameter_removed`                            | A parameter was removed                             |
+| `parameter_renamed`                            | A parameter was renamed                             |
+| `parameter_requiredness_increased`             | Optional → required                                 |
+| `parameter_type_narrowed`                      | Parameter type changed                              |
+| `parameter_position_changed_order_sensitive`   | Parameter moved in order-sensitive language         |
+| `constructor_position_changed_order_sensitive` | Constructor param moved in order-sensitive language |
+| `named_arg_name_removed`                       | Named argument removed                              |
+| `keyword_name_removed`                         | Keyword argument removed                            |
+| `overload_removed`                             | Method overload removed                             |
+| `union_wrapper_migration_without_compat_alias` | Union wrapper migration without backward compat     |
+
+### Soft-Risk
+
+| Category                                              | Description                                      |
+| ----------------------------------------------------- | ------------------------------------------------ |
+| `parameter_added_non_terminal_optional`               | Optional param added (not at end)                |
+| `constructor_reordered_named_friendly`                | Constructor reordered in named-friendly language |
+| `default_value_changed`                               | Default value changed                            |
+| `wrapper_stricter_than_previous_sdk_but_matches_spec` | Stricter but spec-correct                        |
+| `doc_surface_drift`                                   | Documentation-only drift                         |
+
+### Additive
+
+| Category                            | Description                 |
+| ----------------------------------- | --------------------------- |
+| `symbol_added`                      | New symbol added            |
+| `parameter_added_optional_terminal` | Optional param added at end |
+| `new_constructor_overload_added`    | New constructor overload    |
+| `new_wrapper_alias_added`           | New compatibility alias     |
+
+## Provenance Buckets
+
+Every classified change includes a provenance field explaining the source of drift:
+
+| Provenance                | Description                                    |
+| ------------------------- | ---------------------------------------------- |
+| `spec_shape_change`       | The OpenAPI spec changed shape                 |
+| `spec_ordering_change`    | The spec changed property ordering             |
+| `emitter_template_change` | The emitter template was modified              |
+| `compat_extractor_change` | The extractor logic changed                    |
+| `operation_hint_change`   | An operation hint changed                      |
+| `manual_override_change`  | A manual override was applied                  |
+| `normalization_change`    | Naming normalization produced different output |
+| `unknown`                 | Source not determined                          |
+
+## Extracting Snapshots
+
+Every extractor implements `extractSnapshot()`, which returns a `CompatSnapshot` directly:
+
+```ts
+const extractor = getExtractor("node");
+const snapshot: CompatSnapshot = await extractor.extractSnapshot(sdkPath);
+```
+
+This is the primary method used by `oagen compat-extract`. Internally, extractors call `extract()` to produce an `ApiSurface`, then convert it to a `CompatSnapshot` via the bridge function.
+
+### Extractor Interface
+
+```ts
+interface Extractor {
+  language: string;
+  extract(sdkPath: string): Promise<ApiSurface>;
+  extractSnapshot(sdkPath: string): Promise<CompatSnapshot>;
+  hints: LanguageHints;
+}
+```
+
+Both `extract()` and `extractSnapshot()` are available. Use `extractSnapshot()` for the compat pipeline. Use `extract()` when you need the raw `ApiSurface` for overlay or legacy workflows.
+
+### Spec Enrichment
+
+When `oagen compat-extract` receives `--spec`, it enriches callable symbols with spec-derived metadata:
+
+- **`operationId`** — the operation name from the spec, matched by service + method name
+- **`route`** — the HTTP method and path (e.g., `{ method: "POST", path: "/users" }`)
+- **`source.specSha`** — SHA-256 of the spec file
+
+This enrichment happens after extraction, as a post-step in the CLI. Extractors themselves don't need spec awareness.
+
+### Bridge: ApiSurface → CompatSnapshot
+
+The `apiSurfaceToSnapshot()` function converts an `ApiSurface` to a `CompatSnapshot`, applying language-appropriate passing styles and sensitivity flags. This is what `extractSnapshot()` uses internally.
+
+```ts
+import { apiSurfaceToSnapshot } from "@workos/oagen";
+
+const surface: ApiSurface = await extractor.extract(sdkPath);
+const snapshot: CompatSnapshot = apiSurfaceToSnapshot(surface);
+```