@workos/oagen 0.0.1

package/docs/architecture/ir-types.md

@@ -0,0 +1,275 @@
+# IR Type System Reference
+
+Source: `src/ir/types.ts`
+
+The intermediate representation (IR) is the contract between the parser and all language emitters. It uses plain TypeScript interfaces (no classes) with a discriminated union type system.
+
+## Top-Level: ApiSpec
+
+```typescript
+interface ServerEntry {
+  url: string;
+  description?: string;
+}
+
+interface ApiSpec {
+  name: string; // From info.title
+  version: string; // From info.version
+  description?: string; // From info.description
+  baseUrl: string; // From servers[0].url
+  servers?: ServerEntry[]; // All servers from the spec
+  services: Service[]; // Grouped operations
+  models: Model[]; // Schema objects
+  enums: Enum[]; // String enums
+  auth?: AuthScheme[]; // Authentication schemes
+}
+```
+
+The `servers` array contains all server entries from the OpenAPI spec. `baseUrl` is always set to the first server's URL for backward compatibility.
+
+## TypeRef (discriminated union)
+
+Every type in the IR is a `TypeRef`, discriminated on the `kind` field:
+
+| Kind        | Interface       | Example                                                              |
+| ----------- | --------------- | -------------------------------------------------------------------- |
+| `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" }`                                   |
+| `union`     | `UnionType`     | `{ kind: "union", variants: [...], discriminator?: {...} }`          |
+| `nullable`  | `NullableType`  | `{ kind: "nullable", inner: { kind: "primitive", type: "string" } }` |
+| `literal`   | `LiteralType`   | `{ kind: "literal", value: "active" }`                               |
+| `map`       | `MapType`       | `{ kind: "map", valueType: { kind: "primitive", type: "string" } }`  |
+
+### Primitive Formats
+
+The `format` field on `PrimitiveType` carries additional type information:
+
+| type      | format      | Semantic          |
+| --------- | ----------- | ----------------- |
+| `string`  | (none)      | Plain string      |
+| `string`  | `date`      | ISO 8601 date     |
+| `string`  | `date-time` | ISO 8601 datetime |
+| `string`  | `uuid`      | UUID string       |
+| `string`  | `binary`    | Binary data       |
+| `integer` | (none)      | Integer           |
+| `number`  | (none)      | Floating point    |
+| `boolean` | (none)      | Boolean           |
+| `unknown` | (none)      | Unknown/any type  |
+
+### LiteralType
+
+```typescript
+interface LiteralType {
+  kind: "literal";
+  value: string | number | boolean | null;
+}
+```
+
+Represents a fixed value. The `null` variant maps to language-specific null literals.
+
+### MapType
+
+```typescript
+interface MapType {
+  kind: "map";
+  valueType: TypeRef;
+  keyType?: TypeRef; // Defaults to string when absent
+}
+```
+
+The optional `keyType` allows non-string map keys (e.g., enum-keyed maps). When absent, emitters should assume `string` keys.
+
+### UnionType
+
+```typescript
+interface UnionType {
+  kind: "union";
+  variants: TypeRef[];
+  discriminator?: { property: string; mapping: Record<string, string> };
+  compositionKind?: "allOf" | "oneOf" | "anyOf";
+}
+```
+
+The `compositionKind` field tells emitters which OAS composition keyword produced the union, allowing them to distinguish inheritance (`allOf`) from exclusive union (`oneOf`) from open union (`anyOf`).
+
+### TypeParam
+
+```typescript
+interface TypeParam {
+  name: string;
+  default?: TypeRef;
+}
+```
+
+Generic type parameters on models. Example: `DirectoryUser<TCustomAttributes = Record<string, unknown>>`.
+
+## AuthScheme
+
+```typescript
+type AuthScheme =
+  | { kind: "bearer" }
+  | { kind: "apiKey"; in: "header" | "query" | "cookie"; name: string }
+  | { kind: "oauth2"; flows: Record<string, unknown> };
+```
+
+Emitters use `AuthScheme` to generate authentication configuration and client constructors. The `cookie` variant supports cookie-based API key authentication.
+
+## HttpMethod
+
+```typescript
+type HttpMethod =
+  | "get"
+  | "post"
+  | "put"
+  | "patch"
+  | "delete"
+  | "head"
+  | "options"
+  | "trace";
+```
+
+All standard HTTP methods are supported. Emitters should handle `head`, `options`, and `trace` appropriately (e.g., HEAD returns no body).
+
+## PaginationMeta
+
+```typescript
+interface PaginationMeta {
+  strategy: "cursor" | "offset" | "link-header";
+  param: string; // Query param name (e.g., "after" for cursor, "offset" for offset)
+  limitParam?: string; // Limit param name (offset strategy only, e.g., "limit")
+  dataPath?: string; // JSON path to the data array (e.g., "data", "results") — undefined means the response IS the data
+  itemType: TypeRef; // Type of each item in the paginated list
+}
+```
+
+Present on `Operation` when pagination is detected. The `strategy` discriminant tells emitters whether to generate cursor-based, offset-based, or link-header pagination helpers. The `dataPath` is dynamically detected from the response envelope — when `undefined`, emitters should treat the entire response as the data array or use their own default.
+
+The `link-header` strategy is for APIs that use RFC 5988 `Link` headers for pagination (e.g., GitHub API).
+
+## Service & Operation
+
+Service names are derived from OpenAPI tags when present — the first tag on an operation is converted to PascalCase (e.g., `tags: ["multi-factor-auth"]` → service `MultiFactorAuth`). When no tag is present, the parser falls back to the first path segment (e.g., `/organizations/{id}` → `Organizations`). Emitters can further remap service names via an overlay (e.g., `MultiFactorAuth` → `Mfa`) to match existing SDK class names.
+
+```typescript
+interface Service {
+  name: string; // e.g., "Organizations"
+  description?: string;
+  operations: Operation[];
+}
+
+interface Operation {
+  name: string; // e.g., "listUsers", "getUser", "createUser"
+  description?: string;
+  httpMethod: HttpMethod; // All 8 standard HTTP methods
+  path: string; // e.g., "/organizations/{id}"
+  pathParams: Parameter[];
+  queryParams: Parameter[];
+  headerParams: Parameter[];
+  cookieParams?: Parameter[]; // Present only when cookie params exist
+  requestBody?: TypeRef;
+  requestBodyEncoding?:
+    | "json"
+    | "form-data"
+    | "form-urlencoded"
+    | "binary"
+    | "text";
+  response: TypeRef; // Primary response (lowest 2xx with body)
+  successResponses?: SuccessResponse[]; // All 2xx responses (only when multiple exist)
+  errors: ErrorResponse[];
+  pagination?: PaginationMeta;
+  injectIdempotencyKey: boolean; // true when spec declares Idempotency-Key header
+  deprecated?: boolean;
+  async?: boolean;
+}
+
+interface SuccessResponse {
+  statusCode: number;
+  type: TypeRef;
+}
+
+interface Parameter {
+  name: string;
+  type: TypeRef;
+  required: boolean;
+  description?: string;
+  deprecated?: boolean;
+  default?: unknown;
+}
+```
+
+### Idempotency Key
+
+The `injectIdempotencyKey` flag is spec-driven: it is `true` only when the operation explicitly declares an `Idempotency-Key` header parameter in the OpenAPI spec. This means APIs that don't use idempotency keys (e.g., GitHub) get `false`, while APIs that do (e.g., Stripe, billing APIs) already declare the header in their spec and get `true`.
+
+### Request Body Encoding
+
+The `requestBodyEncoding` field tells emitters how to serialize the request body:
+
+| Value             | Content-Type                        |
+| ----------------- | ----------------------------------- |
+| `json`            | `application/json`                  |
+| `form-data`       | `multipart/form-data`               |
+| `form-urlencoded` | `application/x-www-form-urlencoded` |
+| `binary`          | `application/octet-stream`          |
+| `text`            | `text/plain`                        |
+
+### Multiple 2xx Responses
+
+When an operation has multiple 2xx status codes, `successResponses` contains all of them. The `response` field always points to the primary response (lowest 2xx with a body schema). This is useful for emitters that need to handle different status codes differently (e.g., 200 vs 204).
+
+## Model & Field
+
+```typescript
+interface Model {
+  name: string; // PascalCase, e.g., "Organization"
+  description?: string;
+  fields: Field[];
+  typeParams?: TypeParam[]; // Generic type parameters
+}
+
+interface Field {
+  name: string; // snake_case from the spec
+  type: TypeRef;
+  required: boolean;
+  description?: string;
+  readOnly?: boolean;
+  writeOnly?: boolean;
+  deprecated?: boolean;
+  default?: unknown;
+}
+```
+
+## Enum
+
+```typescript
+interface Enum {
+  name: string; // PascalCase
+  values: EnumValue[];
+}
+
+interface EnumValue {
+  name: string; // UPPER_SNAKE_CASE display name
+  value: string | number; // Actual value from spec (preserves numeric types)
+  description?: string;
+  deprecated?: boolean;
+}
+```
+
+## ErrorResponse
+
+```typescript
+interface ErrorResponse {
+  statusCode: number; // e.g., 401, 404, 422
+  type?: TypeRef; // Response body type, if any
+}
+```
+
+## Versioning
+
+The IR does not currently use a version constant. As a 0.x project with no external consumers yet, formal IR versioning is deferred until post-open-source when external emitters need a stable contract signal.
+
+**Compile-time safety:** `assertNever` enforces exhaustive `switch` statements over `TypeRef.kind` at compile time. Adding a new variant causes build failures in any emitter that doesn't handle it — this is the primary compatibility mechanism.
+
+**Walker/Mapper utilities:** `walkTypeRef` and `mapTypeRef` handle recursive traversal of `TypeRef` trees. Both visit `MapType.keyType` when present. The `mapTypeRef` mapper callback for `map` receives an optional third argument `mappedKey?: T` for the mapped key type.

package/docs/architecture/non-additive-changes.md

@@ -0,0 +1,76 @@
+# Non-Additive Spec Changes: Staleness Detection
+
+## Problem
+
+The writer (`src/engine/writer.ts`) is additive-only — it never removes or modifies existing symbols in the live SDK. When an OpenAPI spec removes an endpoint, renames a model, or drops a field, the old symbols persist as dead code. The `oagen verify` command with `--scope spec-only` masks this: `specDerivedNames(newSpec)` excludes removed symbols from the baseline, so they silently pass verification.
+
+## Solution
+
+Staleness detection runs as an optional step in `oagen verify` when `--old-spec`, `--spec`, and `--api-surface` are all provided. It warns about symbols the spec no longer defines but that still exist in the live SDK.
+
+All findings route through the existing compat `Violation` system with category `'staleness'` and severity `'warning'`. Stale symbols compile and run — they are dead code, not breakage.
+
+## Detection Mechanisms
+
+Two complementary mechanisms identify stale symbols:
+
+### 1. Name-set difference (top-level symbols and fields)
+
+```
+removedNames = specDerivedNames(oldSpec) − specDerivedNames(newSpec)
+removedFieldPaths = specDerivedFieldPaths(oldSpec) − specDerivedFieldPaths(newSpec)
+```
+
+This catches:
+
+- Removed models, enums, services, and type aliases at the symbol level
+- Removed fields from models that still exist in the new spec
+
+### 2. Engine differ changes (operation-level)
+
+```
+diffSpecs(oldSpec, newSpec) → operation-removed changes
+```
+
+This catches methods removed from services that still exist — e.g., `Users.deleteUser` removed while the `Users` service continues.
+
+### Cross-reference with live surface
+
+Both mechanisms cross-reference findings against the live SDK surface (`--api-surface`) to confirm the stale symbol actually exists. If a removed spec symbol was never in the SDK (e.g., never generated, or already cleaned up), no warning is emitted.
+
+## CLI Usage
+
+```bash
+oagen verify \
+  --lang node \
+  --output ./sdk \
+  --spec openapi-v2.yml \
+  --old-spec openapi-v1.yml \
+  --api-surface sdk-node-surface.json
+```
+
+Flags:
+
+- `--old-spec <path>` — previous version of the OpenAPI spec
+- `--spec <path>` — current version of the OpenAPI spec
+- `--api-surface <path>` — extracted API surface of the live SDK
+
+All three must be provided for staleness detection to run. When `--diagnostics` is set, staleness findings are included in `verify-diagnostics.json` under `stalenessCheck`.
+
+## Behavior
+
+- Staleness findings are **warnings only** — they never cause a non-zero exit code on their own
+- Hand-written SDK symbols (never in any spec version) are not flagged
+- Field-level staleness is only reported for models that still exist in the new spec (fully removed models are reported at the symbol level)
+
+## Deferred Work
+
+**Rename detection** is not implemented. When a spec renames a model (e.g., `Organization` → `Org`), staleness detection flags the old name as stale and compat verification flags the new name as missing. Precise rename detection (linking old → new) requires manifest comparison across spec versions and is deferred to future work.
+
+## Implementation
+
+- `src/compat/types.ts` — `ViolationCategory` union includes `'staleness'`
+- `src/compat/staleness.ts` — `detectStaleSymbols()` core detection logic
+- `src/cli/verify.ts` — wires staleness detection into the verify command
+- `src/cli/index.ts` — registers `--old-spec` CLI flag
+- `test/compat/staleness.test.ts` — unit tests

package/docs/architecture/pipeline.md

@@ -0,0 +1,110 @@
+# Pipeline Architecture
+
+## Overview
+
+oagen provides a three-stage pipeline for transforming OpenAPI specs into SDK code: Parse → Emit → Write. Emitters are registered plugins that implement the `Emitter` interface.
+
+```
+┌──────────────────┐     ┌─────────────────────┐      ┌──────────────┐
+│   OpenAPI Spec   │────▶│   Parser Pipeline    │────▶│     IR       │
+│   (YAML/JSON)    │     │                      │     │  (ApiSpec)   │
+└──────────────────┘     └─────────────────────┘      └──────┬───────┘
+                                                             │
+                         ┌──────────────────────┐            │
+                         │  Emitter (per lang)  │◀───────────┘
+                         │  generator methods   │
+                         └──────────┬───────────┘
+                                    │
+                         ┌──────────▼───────────┐
+                         │   GeneratedFile[]    │
+                         │  { path, content }   │
+                         └──────────┬───────────┘
+                                    │
+                         ┌──────────▼───────────┐
+                         │      Writer          │
+                         │  (disk + headers)    │
+                         └──────────────────────┘
+```
+
+## Stage 1: Parse (`src/parser/`)
+
+Entry point: `parse.ts` → `parseSpec(specPath: string): Promise<ApiSpec>`
+
+1. **refs.ts** — Loads the spec file, uses `@redocly/openapi-core` to bundle and resolve all `$ref` pointers
+2. **schemas.ts** — Walks `components.schemas`, extracts `Model[]` and `Enum[]`
+3. **operations.ts** — Walks `paths`, groups endpoints into `Service[]` with `Operation[]`
+4. **pagination.ts** — Detects cursor-based pagination from query params; also detected from response shape in `responses.ts` (either source sets `paginated: true`)
+
+### Operation Name Inference
+
+If an `operationId` is present, it takes precedence. Names are inferred from HTTP method + path pattern:
+
+| Method | Path Pattern  | Inferred Name |
+| ------ | ------------- | ------------- |
+| GET    | `/users`      | `list`        |
+| GET    | `/users/{id}` | `get`         |
+| POST   | `/users`      | `create`      |
+| PUT    | `/users/{id}` | `update`      |
+| DELETE | `/users/{id}` | `delete`      |
+
+The collection vs. instance distinction is determined by whether the path ends with a `{param}` segment.
+
+## Stage 2: Emit (`src/engine/`)
+
+Entry point: `orchestrator.ts` → `generate(spec, emitter, options)`
+
+The orchestrator calls each generator method in order:
+
+```typescript
+generateModels(models, ctx); // Data classes/structs
+generateEnums(enums, ctx); // Enum types
+generateResources(services, ctx); // API resource classes
+generateClient(spec, ctx); // HTTP client
+generateErrors(ctx); // Error hierarchy
+generateConfig(ctx); // Configuration
+generateTypeSignatures(spec, ctx); // Type annotations (optional)
+generateTests(spec, ctx); // Tests + fixtures
+generateManifest?.(spec, ctx); // Smoke-test manifest (optional)
+```
+
+### OperationPlan
+
+Before rendering, emitters call `planOperation(op)` from `src/engine/operation-plan.ts` to compute an `OperationPlan` — a flat struct of semantic decisions (`isDelete`, `hasBody`, `isIdempotentPost`, `pathParamsInOptions`, `isPaginated`, `responseModelName`, etc.). This separates _what_ the generated code should do from _how_ it is rendered as a string. The plan is shared across all language emitters.
+
+Each method returns `GeneratedFile[]`. The orchestrator:
+
+1. Collects all files
+2. Prepends `emitter.fileHeader()` to each file's content
+3. Passes to writer (or prints paths in dry-run mode)
+
+### EmitterContext
+
+Every generator method receives:
+
+- `namespace` — snake_case version of the SDK namespace
+- `namespacePascal` — PascalCase version
+- `spec` — the full IR (for cross-references)
+- `outputDir` — target directory
+
+## Stage 3: Write (`src/engine/writer.ts`)
+
+- Writes `GeneratedFile[]` to disk under the output directory
+- Respects `skipIfExists` flag — won't overwrite files marked as hand-editable
+- Creates directories as needed
+
+## Emitter Registry (`src/engine/registry.ts`)
+
+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";
+
+export default {
+  emitters: [nodeEmitter, rubyEmitter],
+};
+```
+
+## Diff Engine (`src/differ/`)
+
+Compares two parsed specs (old vs new) and determines which files need regeneration. Classifies changes as additive, breaking, or mixed.

package/docs/architecture/workflows.md

@@ -0,0 +1,215 @@
+# Workflows
+
+Two distinct phases: one-time setup (add a new SDK), then ongoing spec-driven
+updates. The emitter-fixing loop only happens during setup.
+
+---
+
+## Phase 1: /generate-sdk (one-time setup)
+
+Build and validate a new language emitter. This is the only time emitter code
+gets written or fixed.
+
+### Skill sequence
+
+**Project setup:** Run `oagen init --lang {language}` to create the emitter project, then implement the emitter methods.
+
+**Scenario A** (existing SDK to preserve):
+
+1. `/generate-emitter` — scaffold emitter, design doc, tests
+2. `/generate-extractor` — scaffold extractor for API surface extraction
+3. `/verify-compat` — extract baseline, generate with overlay, verify (includes overlay loop)
+4. `/generate-smoke-test` — wire-level HTTP parity tests against output dir
+5. `/verify-smoke-test` — iterate until smoke tests pass
+6. `/integrate` — merge generated code into the live SDK
+
+**Scenario B** (fresh, no compat constraints):
+
+1. `/generate-emitter` — scaffold emitter, design doc, tests
+2. `/generate-smoke-test` — wire-level HTTP parity tests
+
+> **Lifecycle note:** Scenario B is a one-time bootstrap. Once the generated SDK
+> ships, it becomes the live SDK. All future spec updates follow Scenario A —
+> use `--target` to integrate into the live SDK and `--api-surface` to preserve
+> backwards compatibility. Phase 2 is always Scenario A.
+
+### Overlay loop (Scenario A only, inside /verify-compat)
+
+Mechanical, automated. The overlay patches itself to resolve naming mismatches
+between the generated SDK and the live SDK's API surface. The extractor's
+`hints: LanguageHints` flows through to both the overlay builder and the differ,
+so all type string interpretation (nullability, unions, extraction artifacts) is
+language-appropriate.
+
+1. Generate SDK with compat overlay applied (hints from extractor)
+2. Diff generated output against baseline `<output>/sdk-{language}-surface.json` (hints from extractor)
+3. If violations found, `patchOverlay()` adjusts the overlay
+4. Regenerate with the patched overlay
+5. Repeat
+
+**Caps:**
+
+- `--max-retries <n>` flag on `oagen verify` (default 3, set to 0 for single-pass)
+- Stall detection — if the preservation score doesn't improve between iterations,
+  stops early (the remaining violations can't be fixed by overlay patching)
+- Only `public-api` and `export-structure` violations are patchable; `signature`
+  and `behavioral` violations require emitter code changes
+
+**Guard rails:** The retry loop only activates when BOTH `--api-surface` AND
+`--spec` are provided (the spec is needed to regenerate). Without both,
+verify runs a single pass.
+
+**What it can't fix:** Structural emitter issues (e.g., wrong method signature
+shape, async/sync mismatches). Those require changing emitter code — the loop
+exits 1 and the emitter-fixing loop takes over.
+
+**Code:** `src/cli/verify.ts` (retry loop + compat check) and `src/compat/overlay.ts`
+(`patchOverlay` — also available as a library export for custom loops)
+
+### Emitter-fixing loop (Phase 1 only)
+
+This loop only runs during `/generate-sdk` setup, after all skills complete.
+Its purpose is to get the new emitter producing correct output for the first time:
+
+1. `oagen generate --spec {spec} --lang {lang} --output {sdk-path}`
+2. `oagen verify --spec {spec} --lang {lang} --output {sdk-path}`
+3. If exit 0 — done, proceed to final validation
+4. If exit 1 — read `smoke-diff-findings.json`, fix emitter or smoke script, go to 1
+5. If exit 2 — read `smoke-compile-errors.json`, fix emitter, go to 1
+
+This loop ends when verify exits 0. After that, the emitter is stable and
+Phase 2 (spec-driven updates) takes over.
+
+### Final validation
+
+```bash
+npx tsc --noEmit        # type check
+npx vitest run          # tests
+npx tsup                # build
+```
+
+---
+
+## Phase 2: Spec updates (ongoing)
+
+The emitter is stable. Phase 2 is always Scenario A — there is always a live
+SDK to integrate into (either a pre-existing one from Scenario A setup, or the
+output of Scenario B's initial generation).
+
+### Pipeline
+
+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`
+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.
+
+### If verify fails on a spec update
+
+This is rare — it means the new spec introduced a pattern the emitter doesn't
+handle yet (a new type, an unusual response shape). This is not the same as the
+emitter-fixing loop from Phase 1. Fix the specific gap in the emitter, re-run
+`generate` + `verify`, and move on.
+
+**Diagnostics:** Pass `--diagnostics` to produce `verify-diagnostics.json` with
+a structured breakdown of compat violations and smoke results. This is useful
+for measuring overlay effectiveness per language and tracking preservation scores
+over time.
+
+```bash
+oagen verify --spec v2.yml --lang node --output ./sdk --api-surface surface.json --diagnostics
+# → verify-diagnostics.json
+```
+
+### Verify Result Types
+
+Source: `src/verify/types.ts`, `src/compat/types.ts`, `src/differ/types.ts`
+
+The verify pipeline returns structured result types that consumers can use programmatically:
+
+```typescript
+interface VerifyDiagnostics {
+  compatCheck?: {
+    totalBaselineSymbols;
+    preservedSymbols;
+    preservationScore;
+    violationsByCategory;
+    violationsBySeverity;
+    additions;
+    scopedToSpec;
+    scopedSymbolCount?;
+  };
+  smokeCheck?: { passed; findingsCount?; compileErrors?; baselinePath };
+  stalenessCheck?: { violations };
+}
+
+interface CompatCheckResult {
+  passed: boolean; // true if no breaking violations
+  diff: DiffResult; // detailed diff between baseline and candidate
+  scopedToSpec: boolean; // true if --spec was used to filter
+  scopedSymbolCount?: number;
+}
+
+interface SmokeCheckResult {
+  passed: boolean;
+  findingsCount?: number; // number of CRITICAL/WARNING findings
+  compileErrors?: boolean; // true if SDK failed type check
+  baselinePath: string; // path to the baseline used
+  generatedBaseline: boolean;
+}
+```
+
+The compat differ returns a `DiffResult`:
+
+```typescript
+interface DiffResult {
+  preservationScore: number; // 0–100% of baseline symbols preserved
+  totalBaselineSymbols: number;
+  preservedSymbols: number;
+  violations: Violation[]; // breaking changes found
+  additions: Addition[]; // new symbols not in baseline
+}
+```
+
+Each `Violation` carries a `ViolationCategory` that indicates the kind of breaking change:
+
+| ViolationCategory  | Meaning                                                |
+| ------------------ | ------------------------------------------------------ |
+| `public-api`       | A public class, method, or type was renamed or removed |
+| `signature`        | A method's parameter list or return type changed       |
+| `export-structure` | A barrel export is missing or reorganized              |
+| `behavioral`       | A behavioral contract changed (e.g., async to sync)    |
+| `staleness`        | A symbol was removed from the spec but still exists    |
+
+The spec differ (used by `oagen diff`) returns a `DiffReport`:
+
+```typescript
+interface DiffReport {
+  oldVersion: string;
+  newVersion: string;
+  changes: Change[]; // ModelAdded, ModelRemoved, EnumAdded, OperationAdded, etc.
+  summary: { added; removed; modified; breaking; additive };
+}
+```
+
+### Exit codes from `oagen verify`
+
+| Exit code | Meaning                                       | Findings file               |
+| --------- | --------------------------------------------- | --------------------------- |
+| 0         | Clean — all checks passed                     | —                           |
+| 1         | Findings — CRITICAL mismatches or missing ops | `smoke-diff-findings.json`  |
+| 2         | Compile error — SDK failed type check         | `smoke-compile-errors.json` |