@workos/oagen 0.6.0 → 0.8.0

package/dist/cli/index.mjs

@@ -11,6 +11,7 @@ import Parser from "tree-sitter";
 import { execFile, execFileSync } from "node:child_process";
 import { promisify } from "node:util";
 import { closeSync, existsSync, mkdirSync, openSync, readFileSync, readSync, readdirSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { createHash } from "node:crypto";
 //#region src/ir/sdk-behavior.ts
 /**
 * Canonical SDK behavior defaults. These match the PHP emitter's current
@@ -600,7 +601,7 @@ function findSchemaByName(pascalName, schemas) {
 	for (const [k, v] of Object.entries(schemas)) if (resolveSchemaName(k) === pascalName) return v;
 	return null;
 }
-/** Walk into a schema to find a field's sub-schema, resolving allOf. */
+/** Walk into a schema to find a field's sub-schema, resolving allOf and oneOf/anyOf. */
 function findNestedFieldSchema(fieldName, parentSchema, schemas) {
 	if (parentSchema.properties?.[fieldName]) return parentSchema.properties[fieldName];
 	if (parentSchema.allOf) for (const sub of parentSchema.allOf) {
@@ -612,6 +613,15 @@ function findNestedFieldSchema(fieldName, parentSchema, schemas) {
 		}
 		if (resolved.properties?.[fieldName]) return resolved.properties[fieldName];
 	}
+	for (const variant of [...parentSchema.oneOf ?? [], ...parentSchema.anyOf ?? []]) {
+		let resolved = variant;
+		if (variant.$ref) {
+			const segments = variant.$ref.split("/");
+			const refName = segments[segments.length - 1];
+			if (refName && schemas[refName]) resolved = schemas[refName];
+		}
+		if (resolved.properties?.[fieldName]) return resolved.properties[fieldName];
+	}
 	return null;
 }
 /** Extract a model (and nested models) from an inline field schema. */
@@ -777,6 +787,19 @@ function extractModel(name, schema, schemas) {
 		if (!fieldSchema) continue;
 		fields.push(buildFieldFromSchema(fieldName, fieldSchema, name, requiredSet));
 	}
+	if (fields.length === 0 && (schema.oneOf || schema.anyOf)) {
+		const variants = schema.oneOf ?? schema.anyOf ?? [];
+		const emptyRequired = /* @__PURE__ */ new Set();
+		const seenFieldNames = /* @__PURE__ */ new Set();
+		for (const variant of variants) {
+			if (!variant.properties) continue;
+			for (const [fieldName, fieldSchema] of Object.entries(variant.properties)) {
+				if (!fieldSchema || seenFieldNames.has(fieldName)) continue;
+				seenFieldNames.add(fieldName);
+				fields.push(buildFieldFromSchema(fieldName, fieldSchema, name, emptyRequired));
+			}
+		}
+	}
 	if (schema.additionalProperties && typeof schema.additionalProperties === "object" && schema.properties) {
 		if (Object.keys(schema.additionalProperties).length > 0) {
 			const valueType = schemaToTypeRef(schema.additionalProperties, "additionalProperties", name);
@@ -800,6 +823,7 @@ function extractModel(name, schema, schemas) {
 function extractAllOfModel(name, schema, schemas) {
 	const fields = [];
 	const requiredSet = /* @__PURE__ */ new Set();
+	let resultDiscriminator;
 	for (const subSchema of schema.allOf ?? []) {
 		let resolved = subSchema;
 		if (subSchema.$ref && schemas) {
@@ -816,6 +840,22 @@ function extractAllOfModel(name, schema, schemas) {
 				});
 				if (f.required) requiredSet.add(f.name);
 			}
+		} else if (resolved.oneOf || resolved.anyOf) {
+			const variants = resolved.oneOf ?? resolved.anyOf ?? [];
+			const discriminatorInfo = detectAllOfVariantDiscriminator(variants, name);
+			if (discriminatorInfo) resultDiscriminator = discriminatorInfo;
+			else {
+				const emptyRequired = /* @__PURE__ */ new Set();
+				const seenFieldNames = new Set(fields.map((f) => f.name));
+				for (const variant of variants) {
+					if (!variant.properties) continue;
+					for (const [fieldName, fieldSchema] of Object.entries(variant.properties)) {
+						if (!fieldSchema || seenFieldNames.has(fieldName)) continue;
+						seenFieldNames.add(fieldName);
+						fields.push(buildFieldFromSchema(fieldName, fieldSchema, name, emptyRequired));
+					}
+				}
+			}
 		} else {
 			if (resolved.required) for (const r of resolved.required) requiredSet.add(r);
 			if (resolved.properties) {
@@ -832,7 +872,42 @@ function extractAllOfModel(name, schema, schemas) {
 	return {
 		name,
 		description: schema.description,
-		fields
+		fields,
+		...resultDiscriminator ? { discriminator: resultDiscriminator } : {}
+	};
+}
+/**
+* Detect an implicit discriminator on an allOf+oneOf where every variant is an
+* object that pins the same property to a distinct const value. Unlike
+* detectConstPropertyDiscriminator (which requires $ref or title for variant
+* model names), this version derives model names from the const value itself
+* using deriveDiscriminatedVariantName — matching how extractDiscriminatedAllOfVariantModels
+* names those models.
+*
+* Returns null when no discriminator can be reliably detected.
+*/
+function detectAllOfVariantDiscriminator(variants, fallbackName) {
+	if (variants.length < 2) return null;
+	const candidates = Object.keys(variants[0]?.properties ?? {});
+	let candidateProperty = null;
+	for (const propName of candidates) if (variants.every((v) => getConstPropertyValue(v, propName) !== null)) {
+		candidateProperty = propName;
+		break;
+	}
+	if (!candidateProperty) return null;
+	const mapping = {};
+	const seenModelNames = /* @__PURE__ */ new Set();
+	for (const v of variants) {
+		const value = getConstPropertyValue(v, candidateProperty);
+		if (value === null) return null;
+		const modelName = deriveDiscriminatedVariantName(v, fallbackName);
+		if (seenModelNames.has(modelName)) return null;
+		seenModelNames.add(modelName);
+		mapping[value] = modelName;
+	}
+	return {
+		property: candidateProperty,
+		mapping
 	};
 }
 function extractDiscriminatedAllOfVariantModels(schema, fallbackName) {
@@ -1672,6 +1747,94 @@ function inferDeeperContext(path) {
 	if (nonParams.length >= 3) return toPascalCase(nonParams.slice(1, -1).join("_"));
 	return null;
 }
+/**
+* Extract mutually-exclusive parameter groups from the `x-mutually-exclusive-parameter-groups`
+* operation extension. Cross-references grouped parameter names against the already-extracted
+* IR parameter arrays so emitters get object-identity references.
+*/
+function extractParameterGroups(op, allIRParams, operationContext) {
+	const raw = op["x-mutually-exclusive-parameter-groups"];
+	if (!raw || typeof raw !== "object") return void 0;
+	const paramByName = /* @__PURE__ */ new Map();
+	for (const p of allIRParams) paramByName.set(p.name, p);
+	const groups = [];
+	for (const [groupName, groupDef] of Object.entries(raw)) {
+		if (!groupDef || typeof groupDef !== "object") throw new Error(`Malformed x-mutually-exclusive-parameter-groups.${groupName} in ${operationContext}: expected an object with "optional" and "variants".`);
+		if (typeof groupDef.optional !== "boolean") throw new Error(`Malformed x-mutually-exclusive-parameter-groups.${groupName}.optional in ${operationContext}: expected a boolean.`);
+		if (!groupDef.variants || typeof groupDef.variants !== "object") throw new Error(`Malformed x-mutually-exclusive-parameter-groups.${groupName}.variants in ${operationContext}: expected an object mapping variant names to parameter name arrays.`);
+		if (Object.keys(groupDef.variants).length === 0) throw new Error(`Malformed x-mutually-exclusive-parameter-groups.${groupName} in ${operationContext}: group has zero variants.`);
+		const variants = Object.entries(groupDef.variants).map(([variantName, paramNames]) => {
+			if (!Array.isArray(paramNames) || paramNames.length === 0) throw new Error(`Malformed x-mutually-exclusive-parameter-groups.${groupName}.variants.${variantName} in ${operationContext}: expected a non-empty array of parameter names.`);
+			return {
+				name: variantName,
+				parameters: paramNames.map((pName) => {
+					const irParam = paramByName.get(pName);
+					if (!irParam) throw new Error(`x-mutually-exclusive-parameter-groups.${groupName}.variants.${variantName} references parameter "${pName}" which does not exist in the operation's parameters[] (${operationContext}).`);
+					return irParam;
+				})
+			};
+		});
+		groups.push({
+			name: groupName,
+			optional: groupDef.optional,
+			variants
+		});
+	}
+	return groups.length > 0 ? groups : void 0;
+}
+/**
+* Extract mutually-exclusive body parameter groups from the
+* `x-mutually-exclusive-body-groups` operation extension. Unlike query
+* parameter groups (whose parameters live in operation.queryParams), body
+* group parameters are synthetic — built from the oneOf variant schemas in
+* the request body. Emitters use the group's presence to generate sum-type
+* interfaces and custom JSON marshalling instead of flat optional fields.
+*/
+function extractBodyParameterGroups(op, operationContext) {
+	const raw = op["x-mutually-exclusive-body-groups"];
+	if (!raw || typeof raw !== "object") return void 0;
+	const bodySchema = op.requestBody?.content?.["application/json"]?.schema;
+	const variantFieldSchemas = /* @__PURE__ */ new Map();
+	if (bodySchema) {
+		for (const sub of bodySchema.allOf ?? []) for (const variant of sub.oneOf ?? []) if (variant.properties) {
+			for (const [name, fieldSchema] of Object.entries(variant.properties)) if (fieldSchema) variantFieldSchemas.set(name, fieldSchema);
+		}
+		for (const variant of bodySchema.oneOf ?? []) if (variant.properties) {
+			for (const [name, fieldSchema] of Object.entries(variant.properties)) if (fieldSchema) variantFieldSchemas.set(name, fieldSchema);
+		}
+	}
+	const groups = [];
+	for (const [groupName, groupDef] of Object.entries(raw)) {
+		if (!groupDef || typeof groupDef !== "object") continue;
+		if (typeof groupDef.optional !== "boolean") continue;
+		if (!groupDef.variants || typeof groupDef.variants !== "object") continue;
+		if (Object.keys(groupDef.variants).length === 0) continue;
+		const variants = Object.entries(groupDef.variants).map(([variantName, paramNames]) => {
+			if (!Array.isArray(paramNames) || paramNames.length === 0) throw new Error(`Malformed x-mutually-exclusive-body-groups.${groupName}.variants.${variantName} in ${operationContext}: expected a non-empty array of parameter names.`);
+			return {
+				name: variantName,
+				parameters: paramNames.map((pName) => {
+					const fieldSchema = variantFieldSchemas.get(pName);
+					return {
+						name: pName,
+						type: fieldSchema ? schemaToTypeRef(fieldSchema, toPascalCase(pName)) : {
+							kind: "primitive",
+							type: "string"
+						},
+						required: false,
+						description: fieldSchema?.description
+					};
+				})
+			};
+		});
+		groups.push({
+			name: groupName,
+			optional: groupDef.optional,
+			variants
+		});
+	}
+	return groups.length > 0 ? groups : void 0;
+}
 function buildOperation(method, path, op, pathLevelParams, operationIdTransform, serviceName) {
 	const allParams = [...pathLevelParams, ...op.parameters ?? []];
 	const hasIdempotencyHeader = allParams.some((p) => p.in === "header" && p.name.toLowerCase() === "idempotency-key");
@@ -1697,6 +1860,16 @@ function buildOperation(method, path, op, pathLevelParams, operationIdTransform,
 		};
 	} else if (paginationFromParams) pagination = paginationFromParams;
 	const security = extractOperationSecurity(op.security);
+	const allIRParams = [
+		...pathParams,
+		...queryParams,
+		...headerParams,
+		...cookieParams
+	];
+	const opLabel = op.operationId ?? `${method.toUpperCase()} ${path}`;
+	const queryParamGroups = extractParameterGroups(op, allIRParams, opLabel);
+	const bodyParamGroups = extractBodyParameterGroups(op, opLabel);
+	const parameterGroups = queryParamGroups || bodyParamGroups ? [...queryParamGroups ?? [], ...bodyParamGroups ?? []] : void 0;
 	return {
 		operation: {
 			name: inferOperationName(method, path, op.operationId, operationIdTransform),
@@ -1716,7 +1889,8 @@ function buildOperation(method, path, op, pathLevelParams, operationIdTransform,
 			injectIdempotencyKey: hasIdempotencyHeader,
 			deprecated: op.deprecated || void 0,
 			async: op["x-oagen-async"],
-			security
+			security,
+			parameterGroups
 		},
 		inlineModels
 	};
@@ -2971,6 +3145,7 @@ const nodeMergeAdapter = {
 		const newText = newMembers.map((m) => m.text).join("\n");
 		for (const match of newText.matchAll(/this\.(\w+)/g)) {
 			const propName = match[1];
+			if (propName === "workos") continue;
 			if (propName && !existingMemberKeys.has(propName)) return true;
 		}
 		return false;
@@ -3627,6 +3802,40 @@ function buildIgnoredSymbolNames(docstrings, regions) {
 	for (const [name, info] of docstrings) if (regions.some((r) => info.declStartIndex >= r.startIndex && info.declStartIndex <= r.endIndex)) ignored.add(name);
 	return ignored;
 }
+function clampIndex(value, contentLength) {
+	if (!Number.isFinite(value)) return 0;
+	if (value < 0) return 0;
+	if (value > contentLength) return contentLength;
+	return value;
+}
+/**
+* Resolve the declaration line start for insertion using the current content,
+* instead of relying on parser column arithmetic. This avoids misplaced inserts
+* when parser columns/offsets drift.
+*/
+function declarationLineStart(content, declStartIndex) {
+	const idx = clampIndex(declStartIndex, content.length);
+	const prevNewline = content.lastIndexOf("\n", Math.max(0, idx - 1));
+	return prevNewline === -1 ? 0 : prevNewline + 1;
+}
+/**
+* Resolve a docstring range by searching for the nearest matching text before
+* the declaration start. Falls back to parser-provided offsets when search fails.
+*/
+function resolveDocRange(content, docText, declStartIndex, fallbackStart, fallbackEnd) {
+	const safeDecl = clampIndex(declStartIndex, content.length);
+	const safeFallbackStart = clampIndex(fallbackStart, content.length);
+	const safeFallbackEnd = clampIndex(fallbackEnd, content.length);
+	const found = content.lastIndexOf(docText, safeDecl);
+	if (found !== -1) return {
+		start: found,
+		end: found + docText.length
+	};
+	return {
+		start: safeFallbackStart,
+		end: safeFallbackEnd
+	};
+}
 /**
 * Check if a tree-sitter grammar is configured for the given language.
 */
@@ -3675,15 +3884,17 @@ async function extractClassEndLines(source, language) {
 		if (source[body ? body.endIndex - 1 : node.endIndex - 1] === "}") map.set(name, { bodyEndLine: endRow });
 		else map.set(name, { bodyEndLine: endRow + 1 });
 	}
-	for (const child of tree.rootNode.children) {
-		if (child.type === "class_definition" || child.type === "class_declaration") processClassNode(child);
-		if (child.type === "decorated_definition") {
-			for (const inner of child.namedChildren) if (inner.type === "class_definition") processClassNode(inner);
+	function walk(node) {
+		if (node.type === "class" || node.type === "class_definition" || node.type === "class_declaration") processClassNode(node);
+		if (node.type === "decorated_definition") {
+			for (const inner of node.namedChildren) if (inner.type === "class_definition") processClassNode(inner);
 		}
-		if (child.type === "export_statement") {
-			for (const inner of child.namedChildren) if (inner.type === "class_declaration") processClassNode(inner);
+		if (node.type === "export_statement") {
+			for (const inner of node.namedChildren) if (inner.type === "class_declaration") processClassNode(inner);
 		}
+		for (const child of node.namedChildren) walk(child);
 	}
+	for (const child of tree.rootNode.children) walk(child);
 	return map;
 }
 /**
@@ -3903,15 +4114,16 @@ async function mergeIntoExisting(existingContent, generatedContent, language, he
 			if (genDoc) if (existInfo.docstring) {
 				if (!existInfo.docstring.text.includes("@oagen-ignore") && existInfo.docstring.text !== genDoc.text) {
 					const newText = preserveDeprecatedTags(existInfo.docstring.text, genDoc.text);
+					const range = resolveDocRange(result, existInfo.docstring.text, existInfo.declStartIndex, existInfo.docstring.startIndex, existInfo.docstring.endIndex);
 					edits.push({
-						start: existInfo.docstring.startIndex,
-						end: existInfo.docstring.endIndex,
+						start: range.start,
+						end: range.end,
 						newText
 					});
 					docstringUpdates++;
 				}
 			} else {
-				const lineStart = existInfo.declStartIndex - existInfo.declColumn;
+				const lineStart = declarationLineStart(result, existInfo.declStartIndex);
 				const indent = " ".repeat(existInfo.declColumn);
 				edits.push({
 					start: lineStart,
@@ -3929,15 +4141,16 @@ async function mergeIntoExisting(existingContent, generatedContent, language, he
 				if (existMember.docstring) {
 					if (!existMember.docstring.text.includes("@oagen-ignore") && existMember.docstring.text !== genMember.docstring.text) {
 						const newText = preserveDeprecatedTags(existMember.docstring.text, genMember.docstring.text);
+						const range = resolveDocRange(result, existMember.docstring.text, existMember.declStartIndex, existMember.docstring.startIndex, existMember.docstring.endIndex);
 						edits.push({
-							start: existMember.docstring.startIndex,
-							end: existMember.docstring.endIndex,
+							start: range.start,
+							end: range.end,
 							newText
 						});
 						docstringUpdates++;
 					}
 				} else {
-					const lineStart = existMember.declStartIndex - existMember.declColumn;
+					const lineStart = declarationLineStart(result, existMember.declStartIndex);
 					const indent = " ".repeat(existMember.declColumn);
 					edits.push({
 						start: lineStart,
@@ -3982,15 +4195,16 @@ async function mergeIntoExisting(existingContent, generatedContent, language, he
 					if (existMember.docstring.text.includes("@oagen-ignore")) continue;
 					if (existMember.docstring.text !== genMember.docstring.text) {
 						const newText = preserveDeprecatedTags(existMember.docstring.text, genMember.docstring.text);
+						const range = resolveDocRange(result, existMember.docstring.text, existMember.declStartIndex, existMember.docstring.startIndex, existMember.docstring.endIndex);
 						edits.push({
-							start: existMember.docstring.startIndex,
-							end: existMember.docstring.endIndex,
+							start: range.start,
+							end: range.end,
 							newText
 						});
 						docstringUpdates++;
 					}
 				} else {
-					const lineStart = existMember.declStartIndex - existMember.declColumn;
+					const lineStart = declarationLineStart(result, existMember.declStartIndex);
 					const indent = " ".repeat(existMember.declColumn);
 					edits.push({
 						start: lineStart,
@@ -4163,7 +4377,7 @@ async function overwriteWithPreservedRegions(existingContent, generatedContent,
 		});
 	}
 	if (blocks.length === 0) return generatedContent;
-	const result = [...generatedLines];
+	const result = stripIgnoreRegions(generatedLines);
 	spliceExtraImports(existingLines, result);
 	const classEndLines = await extractClassEndLines(result.join("\n"), language);
 	const blocksByClass = /* @__PURE__ */ new Map();
@@ -4230,10 +4444,33 @@ async function overwriteWithPreservedRegions(existingContent, generatedContent,
 	for (const ins of insertions) result.splice(ins.line, 0, ...ins.content);
 	return result.join("\n");
 }
+/**
+* Remove every `@oagen-ignore-start`..`@oagen-ignore-end` region from the
+* supplied lines, collapsing stretches of blank lines that get left behind.
+* Used to drop generator-emitted seed blocks before splicing the on-disk
+* versions back in — otherwise every regen doubles up.
+*/
+function stripIgnoreRegions(lines) {
+	const out = [];
+	let skipping = false;
+	for (const line of lines) {
+		if (!skipping && line.includes("@oagen-ignore-start")) {
+			skipping = true;
+			while (out.length > 0 && out[out.length - 1].trim() === "") out.pop();
+			continue;
+		}
+		if (skipping) {
+			if (line.includes("@oagen-ignore-end")) skipping = false;
+			continue;
+		}
+		out.push(line);
+	}
+	return out;
+}
 /** Scan backwards from `lineIdx` to find the nearest class declaration name. */
 function findContainingClass(lines, lineIdx) {
 	for (let j = lineIdx - 1; j >= 0; j--) {
-		const m = lines[j].match(/^(?:export\s+)?class\s+(\w+)/);
+		const m = lines[j].match(/^\s*(?:export\s+)?class\s+(\w+)/);
 		if (m) return m[1];
 	}
 	return "";
@@ -4243,7 +4480,7 @@ function findContainingClass(lines, lineIdx) {
 * by scanning backwards from `beforeLine`.
 */
 function findClassDeclarationStart(lines, className, beforeLine) {
-	const classPattern = new RegExp(`^(?:export\\s+)?class\\s+${className}\\b`);
+	const classPattern = new RegExp(`^\\s*(?:export\\s+)?class\\s+${className}\\b`);
 	for (let i = beforeLine - 1; i >= 0; i--) {
 		if (!classPattern.test(lines[i])) continue;
 		let start = i;
@@ -4712,7 +4949,8 @@ async function resolveFileToDirectoryConflicts(files, targetDir) {
 	};
 }
 async function integrateGeneratedFiles(opts) {
-	const { files: resolved, removals } = await resolveFileToDirectoryConflicts(await treeShakeFiles(mapFilesForTargetIntegration(opts.files, opts.language), opts.language), opts.targetDir);
+	const mapped = mapFilesForTargetIntegration(opts.files, opts.language);
+	const { files: resolved, removals } = await resolveFileToDirectoryConflicts(await treeShakeFiles(mapped, opts.language), opts.targetDir);
 	const result = await writeFiles(resolved, opts.targetDir, {
 		language: opts.language,
 		header: opts.header
@@ -4722,7 +4960,7 @@ async function integrateGeneratedFiles(opts) {
 	} catch {}
 	return {
 		...result,
-		emittedPaths: resolved.map((f) => f.path)
+		emittedPaths: mapped.map((f) => f.path)
 	};
 }
 //#endregion
@@ -4746,6 +4984,7 @@ async function formatTargetFiles(emitter, targetDir, filePaths) {
 	if (!formatCmd) return;
 	const absolutePaths = filePaths.map((f) => path$1.resolve(targetDir, f));
 	const batchSize = formatCmd.batchSize ?? 100;
+	process.stderr.write(`[oagen] formatting ${absolutePaths.length} file(s) with ${formatCmd.cmd} (batch ${batchSize})\n`);
 	for (let i = 0; i < absolutePaths.length; i += batchSize) {
 		const batch = absolutePaths.slice(i, i + batchSize);
 		try {
@@ -4754,7 +4993,10 @@ async function formatTargetFiles(emitter, targetDir, filePaths) {
 				maxBuffer: 10 * 1024 * 1024,
 				timeout: 12e4
 			});
-		} catch {}
+		} catch (err) {
+			const msg = err instanceof Error ? err.message : String(err);
+			process.stderr.write(`[oagen] formatter batch failed: ${msg}\n`);
+		}
 	}
 }
 //#endregion
@@ -4779,7 +5021,7 @@ async function formatTargetFiles(emitter, targetDir, filePaths) {
 *    one-line notice is printed — no surprise deletions.
 */
 const MANIFEST_FILENAME = ".oagen-manifest.json";
-const MANIFEST_VERSION = 1;
+const MANIFEST_VERSION = 2;
 /** Read `.oagen-manifest.json` from a directory.  Returns null if absent or malformed. */
 async function readManifest(dir) {
 	const manifestPath = path$1.join(dir, MANIFEST_FILENAME);
@@ -4806,7 +5048,14 @@ async function writeManifest(dir, opts) {
 	const manifest = {
 		version: MANIFEST_VERSION,
 		language: opts.language,
+		...opts.sdkName !== void 0 ? { sdkName: opts.sdkName } : {},
 		generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+		...opts.specSha !== void 0 ? { specSha: opts.specSha } : {},
+		...opts.specPath !== void 0 ? { specPath: opts.specPath } : {},
+		...opts.emitterSha !== void 0 ? { emitterSha: opts.emitterSha } : {},
+		...opts.emitterVersion !== void 0 ? { emitterVersion: opts.emitterVersion } : {},
+		...opts.configSha !== void 0 ? { configSha: opts.configSha } : {},
+		...opts.compatSchemaVersion !== void 0 ? { compatSchemaVersion: opts.compatSchemaVersion } : {},
 		files: [...new Set(opts.files)].sort()
 	};
 	const manifestPath = path$1.join(dir, MANIFEST_FILENAME);
@@ -4917,6 +5166,8 @@ async function generate(spec, emitter, options) {
 		header,
 		noPrune: options.noPrune
 	});
+	const allOutputFiles = [...writeResult.written, ...writeResult.merged];
+	if (allOutputFiles.length > 0) await formatTargetFiles(emitter, options.outputDir, allOutputFiles);
 	if (options.target) {
 		const targetPrevManifest = targetManifestForCtx;
 		const targetResult = await integrateGeneratedFiles({
@@ -5458,12 +5709,18 @@ function buildModelNameMap(surface, spec, lookup, hints, options) {
 		}
 	}
 }
+/** Categories that can be patched by the overlay retry loop. */
+const PATCHABLE_CATEGORIES = new Set(["symbol_removed", "symbol_renamed"]);
+/** Check if a classified change is patchable by the overlay loop. */
+function isPatchableChange(change) {
+	return PATCHABLE_CATEGORIES.has(change.category);
+}
 /**
-* Patch overlay with violations from a failed verification.
+* Patch overlay with classified changes from a failed verification.
 * Adds explicit name mappings for symbols that were generated with wrong names.
 * Returns a new OverlayLookup (immutable).
 */
-function patchOverlay(overlay, violations, baseline) {
+function patchOverlay(overlay, changes, baseline) {
 	const patched = {
 		methodByOperation: new Map(overlay.methodByOperation),
 		httpKeyByMethod: new Map(overlay.httpKeyByMethod),
@@ -5474,42 +5731,33 @@ function patchOverlay(overlay, violations, baseline) {
 		fileBySymbol: new Map(overlay.fileBySymbol)
 	};
 	let warnedManifest = false;
-	for (const v of violations) {
-		if (v.category === "public-api") {
-			const parts = v.symbolPath.split(".");
-			if (parts.length === 2) {
-				const [className, methodName] = parts;
-				const baseClass = baseline.classes[className];
-				if (baseClass && baseClass.methods[methodName]?.length > 0) {
-					const httpKey = overlay.httpKeyByMethod.get(`${className}.${methodName}`);
-					if (!httpKey && overlay.httpKeyByMethod.size === 0 && !warnedManifest) {
-						console.warn("Warning: No smoke-manifest.json available. Method-level violations cannot be auto-patched. Implement generateManifest in your emitter for the self-correcting loop to resolve these.");
-						warnedManifest = true;
-					}
-					if (httpKey) {
-						const method = baseClass.methods[methodName][0];
-						patched.methodByOperation.set(httpKey, {
-							className,
-							methodName,
-							params: method.params,
-							returnType: method.returnType
-						});
-					}
+	for (const c of changes) {
+		if (!isPatchableChange(c)) continue;
+		const parts = c.symbol.split(".");
+		if (parts.length === 2) {
+			const [className, methodName] = parts;
+			const baseClass = baseline.classes[className];
+			if (baseClass && baseClass.methods[methodName]?.length > 0) {
+				const httpKey = overlay.httpKeyByMethod.get(`${className}.${methodName}`);
+				if (!httpKey && overlay.httpKeyByMethod.size === 0 && !warnedManifest) {
+					console.warn("Warning: No smoke-manifest.json available. Method-level violations cannot be auto-patched. Implement generateManifest in your emitter for the self-correcting loop to resolve these.");
+					warnedManifest = true;
+				}
+				if (httpKey) {
+					const method = baseClass.methods[methodName][0];
+					patched.methodByOperation.set(httpKey, {
+						className,
+						methodName,
+						params: method.params,
+						returnType: method.returnType
+					});
 				}
-				if (baseline.interfaces[className]) patched.interfaceByName.set(className, className);
-			} else if (parts.length === 1) {
-				const name = parts[0];
-				if (baseline.interfaces[name]) patched.interfaceByName.set(name, name);
-				if (baseline.typeAliases[name]) patched.typeAliasByName.set(name, name);
-			}
-		}
-		if (v.category === "export-structure") {
-			const match = v.symbolPath.match(/^exports\[(.+?)\]\.(.+)$/);
-			if (match) {
-				const [, path, symbol] = match;
-				if (!patched.requiredExports.has(path)) patched.requiredExports.set(path, /* @__PURE__ */ new Set());
-				patched.requiredExports.get(path).add(symbol);
 			}
+			if (baseline.interfaces[className]) patched.interfaceByName.set(className, className);
+		} else if (parts.length === 1) {
+			const name = parts[0];
+			if (baseline.interfaces[name]) patched.interfaceByName.set(name, name);
+			if (baseline.typeAliases[name]) patched.typeAliasByName.set(name, name);
 		}
 	}
 	return patched;
@@ -6046,6 +6294,327 @@ async function extractCommand(opts) {
 	console.log(`Extracted ${symbolCount} symbols → ${opts.output}`);
 }
 //#endregion
+//#region src/cli/compat-extract.ts
+const SNAPSHOT_FILENAME = ".oagen-compat-snapshot.json";
+async function compatExtractCommand(opts) {
+	const extractor = getExtractor(opts.lang);
+	console.log(`Extracting ${opts.lang} compat snapshot from ${opts.sdkPath}...`);
+	const snapshot = await extractor.extractSnapshot(opts.sdkPath);
+	if (opts.spec) {
+		const specContent = readFileSync(opts.spec, "utf-8");
+		snapshot.source.specSha = createHash("sha256").update(specContent).digest("hex");
+		enrichWithSpecContext(snapshot, await parseSpec(opts.spec));
+	}
+	const outputPath = resolve(opts.output, SNAPSHOT_FILENAME);
+	writeFileSync(outputPath, JSON.stringify(snapshot, null, 2));
+	console.log(`Extracted ${snapshot.symbols.length} symbols → ${outputPath}`);
+}
+/**
+* Enrich snapshot symbols with operationId and route from the parsed spec.
+*
+* Matches callable symbols to spec operations by comparing method names
+* derived from the spec against the symbol's fqName.
+*/
+function enrichWithSpecContext(snapshot, spec) {
+	const opLookup = /* @__PURE__ */ new Map();
+	for (const service of spec.services) for (const op of service.operations) {
+		const key = `${service.name}.${op.name}`;
+		opLookup.set(key, {
+			operationId: op.name,
+			method: op.httpMethod,
+			path: op.path
+		});
+	}
+	for (const sym of snapshot.symbols) {
+		if (sym.kind !== "callable") continue;
+		const match = opLookup.get(sym.fqName);
+		if (match) {
+			sym.operationId = match.operationId;
+			sym.route = {
+				method: match.method,
+				path: match.path
+			};
+		}
+	}
+}
+//#endregion
+//#region src/compat/schema.ts
+/** Validate the basic structure of a parsed compat snapshot. */
+function validateSnapshot(data) {
+	if (typeof data !== "object" || data === null) return false;
+	const obj = data;
+	return typeof obj.schemaVersion === "string" && typeof obj.source === "object" && obj.source !== null && typeof obj.policies === "object" && obj.policies !== null && Array.isArray(obj.symbols);
+}
+//#endregion
+//#region src/compat/config.ts
+const BREAKING_CATEGORIES = new Set([
+	"symbol_removed",
+	"symbol_renamed",
+	"parameter_removed",
+	"parameter_renamed",
+	"parameter_requiredness_increased",
+	"parameter_type_narrowed",
+	"parameter_position_changed_order_sensitive",
+	"constructor_position_changed_order_sensitive",
+	"named_arg_name_removed",
+	"keyword_name_removed",
+	"overload_removed",
+	"union_wrapper_migration_without_compat_alias",
+	"field_type_changed",
+	"return_type_changed",
+	"enum_member_value_changed"
+]);
+const SOFT_RISK_CATEGORIES = new Set([
+	"parameter_added_non_terminal_optional",
+	"constructor_reordered_named_friendly",
+	"default_value_changed",
+	"wrapper_stricter_than_previous_sdk_but_matches_spec",
+	"doc_surface_drift"
+]);
+/** Get the default severity for a change category. */
+function defaultSeverityForCategory(category) {
+	if (BREAKING_CATEGORIES.has(category)) return "breaking";
+	if (SOFT_RISK_CATEGORIES.has(category)) return "soft-risk";
+	return "additive";
+}
+/** Check whether a severity meets or exceeds a fail threshold. */
+function severityMeetsThreshold(severity, threshold) {
+	if (threshold === "none") return false;
+	if (threshold === "soft-risk") return severity === "breaking" || severity === "soft-risk";
+	return severity === "breaking";
+}
+//#endregion
+//#region src/compat/classify.ts
+/**
+* Classify changes between a baseline and candidate symbol.
+* Returns one or more classified changes for the diff.
+*/
+function classifySymbolChanges(baseline, candidate, policy) {
+	const changes = [];
+	if (!candidate) {
+		changes.push(makeChange({
+			category: "symbol_removed",
+			symbol: baseline.fqName,
+			old: { symbol: baseline.fqName },
+			new: { symbol: "(removed)" },
+			message: `Symbol "${baseline.displayName}" was removed`,
+			policy
+		}));
+		return changes;
+	}
+	if (baseline.fqName !== candidate.fqName && baseline.id === candidate.id) changes.push(makeChange({
+		category: "symbol_renamed",
+		symbol: baseline.fqName,
+		old: { name: baseline.fqName },
+		new: { name: candidate.fqName },
+		message: `Symbol renamed from "${baseline.displayName}" to "${candidate.displayName}"`,
+		policy
+	}));
+	if (baseline.parameters && candidate.parameters) changes.push(...classifyParameterChanges(baseline, candidate, policy));
+	if (baseline.returns && candidate.returns && baseline.returns.name !== candidate.returns.name) changes.push(makeChange({
+		category: "return_type_changed",
+		symbol: baseline.fqName,
+		old: { returnType: baseline.returns.name },
+		new: { returnType: candidate.returns.name },
+		message: `Return type changed for "${baseline.displayName}" from "${baseline.returns.name}" to "${candidate.returns.name}"`,
+		policy
+	}));
+	if (baseline.typeRef && candidate.typeRef && baseline.typeRef.name !== candidate.typeRef.name) changes.push(makeChange({
+		category: "field_type_changed",
+		symbol: baseline.fqName,
+		old: { type: baseline.typeRef.name },
+		new: { type: candidate.typeRef.name },
+		message: `Type changed for "${baseline.displayName}" from "${baseline.typeRef.name}" to "${candidate.typeRef.name}"`,
+		policy
+	}));
+	if (baseline.kind === "enum_member" && candidate.kind === "enum_member" && baseline.value !== void 0 && candidate.value !== void 0 && baseline.value !== candidate.value) changes.push(makeChange({
+		category: "enum_member_value_changed",
+		symbol: baseline.fqName,
+		old: { value: String(baseline.value) },
+		new: { value: String(candidate.value) },
+		message: `Enum value changed for "${baseline.displayName}" from "${baseline.value}" to "${candidate.value}"`,
+		policy
+	}));
+	return changes;
+}
+/**
+* Classify parameter-level changes between two symbol versions.
+*/
+function classifyParameterChanges(baseline, candidate, policy) {
+	const changes = [];
+	const baseParams = baseline.parameters ?? [];
+	const candParams = candidate.parameters ?? [];
+	const baseByName = new Map(baseParams.map((p) => [p.publicName, p]));
+	const candByName = new Map(candParams.map((p) => [p.publicName, p]));
+	const isConstructor = baseline.kind === "constructor";
+	for (const baseParam of baseParams) {
+		const candParam = candByName.get(baseParam.publicName);
+		if (!candParam) {
+			const positionalMatch = candParams[baseParam.position];
+			if (positionalMatch && !baseByName.has(positionalMatch.publicName)) {
+				const isBreakingRename = parameterNameIsPublicApi(baseParam, policy, isConstructor);
+				changes.push(makeChange({
+					category: "parameter_renamed",
+					symbol: baseline.fqName,
+					old: { parameter: baseParam.publicName },
+					new: { parameter: positionalMatch.publicName },
+					message: `Parameter "${baseParam.publicName}" renamed to "${positionalMatch.publicName}" on "${baseline.displayName}"`,
+					policy,
+					severityOverride: isBreakingRename ? void 0 : "soft-risk"
+				}));
+			} else changes.push(makeChange({
+				category: "parameter_removed",
+				symbol: baseline.fqName,
+				old: { parameter: baseParam.publicName },
+				new: { parameter: "(removed)" },
+				message: `Parameter "${baseParam.publicName}" removed from "${baseline.displayName}"`,
+				policy
+			}));
+			continue;
+		}
+		if (!baseParam.required && candParam.required) changes.push(makeChange({
+			category: "parameter_requiredness_increased",
+			symbol: baseline.fqName,
+			old: {
+				parameter: baseParam.publicName,
+				required: "false"
+			},
+			new: {
+				parameter: candParam.publicName,
+				required: "true"
+			},
+			message: `Parameter "${baseParam.publicName}" became required on "${baseline.displayName}"`,
+			policy
+		}));
+		if (baseParam.type.name !== candParam.type.name) changes.push(makeChange({
+			category: "parameter_type_narrowed",
+			symbol: baseline.fqName,
+			old: {
+				parameter: baseParam.publicName,
+				type: baseParam.type.name
+			},
+			new: {
+				parameter: candParam.publicName,
+				type: candParam.type.name
+			},
+			message: `Parameter type changed for "${baseParam.publicName}" on "${baseline.displayName}"`,
+			policy
+		}));
+		if (baseParam.position !== candParam.position) if (isConstructor ? policy.constructorOrderMatters : baseParam.sensitivity.order) {
+			const category = isConstructor ? "constructor_position_changed_order_sensitive" : "parameter_position_changed_order_sensitive";
+			changes.push(makeChange({
+				category,
+				symbol: baseline.fqName,
+				old: {
+					parameter: baseParam.publicName,
+					position: String(baseParam.position)
+				},
+				new: {
+					parameter: candParam.publicName,
+					position: String(candParam.position)
+				},
+				message: `Parameter "${baseParam.publicName}" moved from position ${baseParam.position} to ${candParam.position} on "${baseline.displayName}"`,
+				policy
+			}));
+		} else changes.push(makeChange({
+			category: "constructor_reordered_named_friendly",
+			symbol: baseline.fqName,
+			old: {
+				parameter: baseParam.publicName,
+				position: String(baseParam.position)
+			},
+			new: {
+				parameter: candParam.publicName,
+				position: String(candParam.position)
+			},
+			message: `Parameter "${baseParam.publicName}" reordered on "${baseline.displayName}" (named-friendly language)`,
+			policy
+		}));
+	}
+	for (const candParam of candParams) if (!baseByName.has(candParam.publicName)) {
+		if (changes.some((c) => c.category === "parameter_renamed" && c.new.parameter === candParam.publicName)) continue;
+		const isTerminal = candParam.position === candParams.length - 1;
+		const category = candParam.required ? "parameter_requiredness_increased" : isTerminal ? "parameter_added_optional_terminal" : "parameter_added_non_terminal_optional";
+		if (candParam.required) changes.push(makeChange({
+			category,
+			symbol: baseline.fqName,
+			old: { parameter: "(absent)" },
+			new: {
+				parameter: candParam.publicName,
+				required: "true"
+			},
+			message: `Required parameter "${candParam.publicName}" added to "${baseline.displayName}"`,
+			policy
+		}));
+		else changes.push(makeChange({
+			category,
+			symbol: baseline.fqName,
+			old: { parameter: "(absent)" },
+			new: { parameter: candParam.publicName },
+			message: `Optional parameter "${candParam.publicName}" added to "${baseline.displayName}"`,
+			policy
+		}));
+	}
+	return changes;
+}
+function parameterNameIsPublicApi(param, policy, isConstructor) {
+	if (param.sensitivity.publicName) return true;
+	if (isConstructor) return policy.constructorParameterNamesArePublicApi;
+	return policy.methodParameterNamesArePublicApi;
+}
+/** Build a deterministic conceptual change ID. */
+function buildConceptualChangeId(category, symbol, match) {
+	const parts = [
+		"chg",
+		category,
+		symbol.replace(/[^a-zA-Z0-9_.]/g, "_")
+	];
+	if (match.parameter) parts.push(match.parameter);
+	if (match.member) parts.push(match.member);
+	return parts.join("_").toLowerCase();
+}
+function makeChange(opts) {
+	return {
+		category: opts.category,
+		severity: opts.severityOverride ?? defaultSeverityForCategory(opts.category),
+		symbol: opts.symbol,
+		conceptualChangeId: buildConceptualChangeId(opts.category, opts.symbol, opts.old),
+		provenance: opts.provenance ?? "unknown",
+		old: opts.old,
+		new: opts.new,
+		message: opts.message
+	};
+}
+/**
+* Classify a new symbol as additive.
+*/
+function classifyAddedSymbol(symbol) {
+	return {
+		category: "symbol_added",
+		severity: "additive",
+		symbol: symbol.fqName,
+		conceptualChangeId: buildConceptualChangeId("symbol_added", symbol.fqName, {}),
+		provenance: "unknown",
+		old: { symbol: "(absent)" },
+		new: { symbol: symbol.fqName },
+		message: `Symbol "${symbol.displayName}" was added`
+	};
+}
+/** Summarize a list of classified changes by severity. */
+function summarizeChanges(changes) {
+	let breaking = 0;
+	let softRisk = 0;
+	let additive = 0;
+	for (const c of changes) if (c.severity === "breaking") breaking++;
+	else if (c.severity === "soft-risk") softRisk++;
+	else additive++;
+	return {
+		breaking,
+		softRisk,
+		additive
+	};
+}
+//#endregion
 //#region src/compat/spec-filter.ts
 /**
 * Compute the set of symbol names that are derivable from the OpenAPI spec.
@@ -6211,378 +6780,609 @@ function filterSurface(surface, allowedNames, opts) {
 }
 //#endregion
 //#region src/compat/differ.ts
-function diffSurfaces(baseline, candidate, hints) {
-	const violations = [];
-	const additions = [];
-	let totalBaseline = 0;
-	let preserved = 0;
-	for (const [name, baseClass] of Object.entries(baseline.classes)) {
-		totalBaseline++;
-		const candClass = candidate.classes[name];
-		if (!candClass) {
-			violations.push({
-				category: "public-api",
-				severity: "breaking",
-				symbolPath: name,
-				baseline: name,
-				candidate: "(missing)",
-				message: `Class "${name}" exists in baseline but not in generated output`
-			});
-			totalBaseline += Object.values(baseClass.methods).reduce((sum, overloads) => sum + overloads.length, 0);
-			totalBaseline += Object.keys(baseClass.properties).length;
-			continue;
-		}
-		preserved++;
-		for (const [methodName, baseOverloads] of Object.entries(baseClass.methods)) {
-			const candOverloads = candClass.methods[methodName];
-			for (const baseMethod of baseOverloads) {
-				totalBaseline++;
-				if (!candOverloads || candOverloads.length === 0) {
-					violations.push({
-						category: "public-api",
-						severity: "breaking",
-						symbolPath: `${name}.${methodName}`,
-						baseline: methodName,
-						candidate: "(missing)",
-						message: `Method "${name}.${methodName}" exists in baseline but not in generated output`
-					});
-					continue;
-				}
-				if (!candOverloads.find((c) => signaturesMatch(baseMethod, c))) {
-					if (hints.isSignatureEquivalent ? candOverloads.find((c) => hints.isSignatureEquivalent(baseMethod, c, candidate)) : void 0) {
-						preserved++;
-						continue;
-					}
-					violations.push({
-						category: "signature",
-						severity: "breaking",
-						symbolPath: `${name}.${methodName}`,
-						baseline: formatSignature(baseMethod),
-						candidate: formatSignature(candOverloads[0]),
-						message: `Signature mismatch for "${name}.${methodName}"`
-					});
-					continue;
-				}
-				preserved++;
-			}
-		}
-		for (const methodName of Object.keys(candClass.methods)) if (!baseClass.methods[methodName]) additions.push({
-			symbolPath: `${name}.${methodName}`,
-			symbolType: "method"
-		});
-		for (const [propName, baseProp] of Object.entries(baseClass.properties)) {
-			totalBaseline++;
-			const candProp = candClass.properties[propName];
-			if (!candProp) {
-				violations.push({
-					category: "public-api",
-					severity: "breaking",
-					symbolPath: `${name}.${propName}`,
-					baseline: baseProp.type,
-					candidate: "(missing)",
-					message: `Property "${name}.${propName}" exists in baseline but not in generated output`
-				});
-				continue;
-			}
-			if (baseProp.type !== candProp.type) {
-				const nullableOnly = hints.isNullableOnlyDifference(baseProp.type, candProp.type);
-				violations.push({
-					category: "signature",
-					severity: nullableOnly ? "warning" : "breaking",
-					symbolPath: `${name}.${propName}`,
-					baseline: baseProp.type,
-					candidate: candProp.type,
-					message: `Property type mismatch for "${name}.${propName}"`
-				});
-				if (nullableOnly) preserved++;
-				continue;
-			}
-			preserved++;
-		}
-		for (const propName of Object.keys(candClass.properties)) if (!baseClass.properties[propName]) additions.push({
-			symbolPath: `${name}.${propName}`,
-			symbolType: "property"
+/**
+* Diff two compat snapshots, producing classified changes with
+* policy-aware severity.
+*/
+function diffSnapshots(baseline, candidate, policy) {
+	const effectivePolicy = policy ?? baseline.policies;
+	const changes = [];
+	const candById = /* @__PURE__ */ new Map();
+	const candByFqName = /* @__PURE__ */ new Map();
+	for (const sym of candidate.symbols) {
+		candById.set(sym.id, sym);
+		candByFqName.set(sym.fqName, sym);
+	}
+	const baseByFqName = /* @__PURE__ */ new Set();
+	for (const sym of baseline.symbols) baseByFqName.add(sym.fqName);
+	for (const baseSym of baseline.symbols) {
+		const candSym = candById.get(baseSym.id) ?? candByFqName.get(baseSym.fqName);
+		changes.push(...classifySymbolChanges(baseSym, candSym, effectivePolicy));
+	}
+	for (const candSym of candidate.symbols) if (!baseByFqName.has(candSym.fqName)) changes.push(classifyAddedSymbol(candSym));
+	return {
+		changes,
+		summary: summarizeChanges(changes)
+	};
+}
+//#endregion
+//#region src/compat/concepts.ts
+/**
+* Group classified changes from multiple languages into conceptual changes.
+*
+* Changes are grouped by their `conceptualChangeId` — a deterministic ID
+* derived from the symbol, category, and match details. Changes with the
+* same ID across different languages represent the same conceptual change.
+*/
+function buildConceptualRollup(perLanguageResults) {
+	const grouped = /* @__PURE__ */ new Map();
+	for (const { diff: result, language } of perLanguageResults) for (const change of result.changes) {
+		const existing = grouped.get(change.conceptualChangeId);
+		if (existing) existing.impact[language] = change.severity;
+		else grouped.set(change.conceptualChangeId, {
+			id: change.conceptualChangeId,
+			symbol: change.symbol,
+			category: change.category,
+			impact: { [language]: change.severity },
+			message: change.message,
+			old: change.old,
+			new: change.new
 		});
 	}
-	for (const name of Object.keys(candidate.classes)) if (!baseline.classes[name]) additions.push({
-		symbolPath: name,
-		symbolType: "class"
-	});
-	const candIfaceFieldSets = /* @__PURE__ */ new Map();
-	for (const [n, iface] of Object.entries(candidate.interfaces)) candIfaceFieldSets.set(n, new Set(Object.keys(iface.fields).map((f) => f.toLowerCase())));
-	const candClassPropSets = /* @__PURE__ */ new Map();
-	for (const [n, cls] of Object.entries(candidate.classes)) candClassPropSets.set(n, new Set(Object.keys(cls.properties).map((f) => f.toLowerCase())));
-	for (const [name, baseIface] of Object.entries(baseline.interfaces)) {
-		totalBaseline++;
-		const candIface = candidate.interfaces[name];
-		if (!candIface) {
-			let tolerated = false;
-			if (hints.tolerateCategoryMismatch && name.startsWith("Serialized")) {
-				const baseName = name.slice(10);
-				if (candidate.interfaces[baseName] || candidate.classes[baseName]) tolerated = true;
-			}
-			if (tolerated) {
-				preserved++;
-				totalBaseline += Object.keys(baseIface.fields).length;
-				preserved += Object.keys(baseIface.fields).length;
-				continue;
-			}
-			if (!tolerated) {
-				const baseFieldNamesLower = new Set(Object.keys(baseIface.fields).map((f) => f.toLowerCase()));
-				if (baseFieldNamesLower.size > 0) {
-					for (const [, candFieldNamesLower] of candIfaceFieldSets) if (candFieldNamesLower.size === baseFieldNamesLower.size && [...baseFieldNamesLower].every((f) => candFieldNamesLower.has(f))) {
-						tolerated = true;
-						break;
-					}
-					if (!tolerated) {
-						for (const [, candPropNamesLower] of candClassPropSets) if (candPropNamesLower.size === baseFieldNamesLower.size && [...baseFieldNamesLower].every((f) => candPropNamesLower.has(f))) {
-							tolerated = true;
-							break;
-						}
-					}
-				} else tolerated = true;
-			}
-			if (tolerated) {
-				preserved++;
-				totalBaseline += Object.keys(baseIface.fields).length;
-				preserved += Object.keys(baseIface.fields).length;
-				continue;
-			}
-			violations.push({
-				category: "public-api",
-				severity: "breaking",
-				symbolPath: name,
-				baseline: name,
-				candidate: "(missing)",
-				message: `Interface "${name}" exists in baseline but not in generated output`
-			});
-			totalBaseline += Object.keys(baseIface.fields).length;
-			continue;
-		}
-		preserved++;
-		for (const [fieldName, baseField] of Object.entries(baseIface.fields)) {
-			totalBaseline++;
-			const candField = candIface.fields[fieldName];
-			if (!candField) {
-				const baseTypeClean = baseField.type.replace(/\[\]$/, "").replace(/ \| null$/, "");
-				const typeIsUnresolvable = NAMED_TYPE_RE.test(baseTypeClean) && !typeExistsInSurface(baseTypeClean, candidate);
-				violations.push({
-					category: "public-api",
-					severity: typeIsUnresolvable ? "warning" : "breaking",
-					symbolPath: `${name}.${fieldName}`,
-					baseline: baseField.type,
-					candidate: "(missing)",
-					message: `Field "${name}.${fieldName}" exists in baseline but not in generated output`
-				});
-				if (typeIsUnresolvable) preserved++;
-				continue;
-			}
-			if (baseField.type !== candField.type) {
-				if (hints.isUnionReorder(baseField.type, candField.type)) {
-					preserved++;
-					continue;
-				}
-				if (hints.isTypeEquivalent?.(baseField.type, candField.type, candidate)) {
-					preserved++;
-					continue;
-				}
-				const nullableOnly = hints.isNullableOnlyDifference(baseField.type, candField.type);
-				const genericParam = hints.isGenericTypeParam(baseField.type);
-				const extractionArtifact = hints.isExtractionArtifact(candField.type);
-				const isWarning = nullableOnly || genericParam || extractionArtifact;
-				violations.push({
-					category: "signature",
-					severity: isWarning ? "warning" : "breaking",
-					symbolPath: `${name}.${fieldName}`,
-					baseline: baseField.type,
-					candidate: candField.type,
-					message: `Field type mismatch for "${name}.${fieldName}"`
-				});
-				if (isWarning) preserved++;
-				continue;
-			}
-			preserved++;
-		}
-		for (const fieldName of Object.keys(candIface.fields)) if (!baseIface.fields[fieldName]) additions.push({
-			symbolPath: `${name}.${fieldName}`,
-			symbolType: "property"
-		});
+	return { conceptualChanges: [...grouped.values()] };
+}
+/** Get the highest severity across all languages for a conceptual change. */
+function highestSeverity(change) {
+	const severities = Object.values(change.impact);
+	if (severities.includes("breaking")) return "breaking";
+	if (severities.includes("soft-risk")) return "soft-risk";
+	return "additive";
+}
+/** Count conceptual changes by highest severity. */
+function summarizeConceptualChanges(rollup) {
+	let breaking = 0;
+	let softRisk = 0;
+	let additive = 0;
+	for (const change of rollup.conceptualChanges) {
+		const sev = highestSeverity(change);
+		if (sev === "breaking") breaking++;
+		else if (sev === "soft-risk") softRisk++;
+		else additive++;
 	}
-	for (const name of Object.keys(candidate.interfaces)) if (!baseline.interfaces[name]) additions.push({
-		symbolPath: name,
-		symbolType: "interface"
-	});
-	for (const [name, baseAlias] of Object.entries(baseline.typeAliases)) {
-		totalBaseline++;
-		const candAlias = candidate.typeAliases[name];
-		if (!candAlias) {
-			if (hints.tolerateCategoryMismatch && typeExistsInSurface(name, candidate)) {
-				preserved++;
-				continue;
-			}
-			violations.push({
-				category: "public-api",
-				severity: "breaking",
-				symbolPath: name,
-				baseline: baseAlias.value,
-				candidate: "(missing)",
-				message: `Type alias "${name}" exists in baseline but not in generated output`
-			});
-			continue;
-		}
-		if (baseAlias.value !== candAlias.value) {
-			if (hints.isUnionReorder(baseAlias.value, candAlias.value)) {
-				preserved++;
-				continue;
-			}
-			const nullableOnly = hints.isNullableOnlyDifference(baseAlias.value, candAlias.value);
-			violations.push({
-				category: "signature",
-				severity: nullableOnly ? "warning" : "breaking",
-				symbolPath: name,
-				baseline: baseAlias.value,
-				candidate: candAlias.value,
-				message: `Type alias value mismatch for "${name}"`
-			});
-			if (nullableOnly) preserved++;
-			continue;
+	return {
+		breaking,
+		softRisk,
+		additive
+	};
+}
+//#endregion
+//#region src/compat/report.ts
+/** Generate a machine-readable compat report from a diff result. */
+function generateReport(diff, language) {
+	return {
+		schemaVersion: "1",
+		language: language ?? "unknown",
+		summary: diff.summary,
+		changes: diff.changes.map((c) => ({
+			severity: c.severity,
+			category: c.category,
+			symbol: c.symbol,
+			conceptualChangeId: c.conceptualChangeId,
+			provenance: c.provenance,
+			old: c.old,
+			new: c.new,
+			...c.message ? { message: c.message } : {}
+		}))
+	};
+}
+/** Generate a human-readable summary string for terminal output. */
+function formatHumanSummary(diff, opts) {
+	const lines = [];
+	lines.push(`Compat report${opts?.language ? ` for ${opts.language}` : ""}:`);
+	lines.push(`  ${diff.summary.breaking} breaking, ${diff.summary.softRisk} soft-risk, ${diff.summary.additive} additive`);
+	if (diff.changes.length === 0) {
+		lines.push("  No compatibility changes detected.");
+		return lines.join("\n");
+	}
+	const breaking = diff.changes.filter((c) => c.severity === "breaking");
+	const softRisk = diff.changes.filter((c) => c.severity === "soft-risk");
+	const additive = diff.changes.filter((c) => c.severity === "additive");
+	if (breaking.length > 0) {
+		lines.push("");
+		lines.push("  Breaking:");
+		for (const c of breaking) {
+			lines.push(`    [${c.category}] ${c.symbol} — ${c.message}`);
+			if (opts?.explain && c.provenance !== "unknown") lines.push(`      provenance: ${c.provenance}`);
 		}
-		preserved++;
 	}
-	for (const name of Object.keys(candidate.typeAliases)) if (!baseline.typeAliases[name]) additions.push({
-		symbolPath: name,
-		symbolType: "type-alias"
-	});
-	for (const [name, baseEnum] of Object.entries(baseline.enums)) {
-		totalBaseline++;
-		const candEnum = candidate.enums[name];
-		if (!candEnum) {
-			violations.push({
-				category: "public-api",
-				severity: "breaking",
-				symbolPath: name,
-				baseline: name,
-				candidate: "(missing)",
-				message: `Enum "${name}" exists in baseline but not in generated output`
-			});
-			continue;
+	if (softRisk.length > 0) {
+		lines.push("");
+		lines.push("  Soft-risk:");
+		for (const c of softRisk) {
+			lines.push(`    [${c.category}] ${c.symbol} — ${c.message}`);
+			if (opts?.explain && c.provenance !== "unknown") lines.push(`      provenance: ${c.provenance}`);
 		}
-		const candValueToMembers = /* @__PURE__ */ new Map();
-		for (const [candMember, candValue] of Object.entries(candEnum.members)) {
-			const existing = candValueToMembers.get(candValue);
-			if (existing) existing.push(candMember);
-			else candValueToMembers.set(candValue, [candMember]);
-		}
-		let enumMatch = true;
-		for (const [member, value] of Object.entries(baseEnum.members)) {
-			if (candEnum.members[member] === value) continue;
-			const valueMatches = candValueToMembers.get(value);
-			if (valueMatches && valueMatches.length > 0) {
-				violations.push({
-					category: "signature",
-					severity: "warning",
-					symbolPath: `${name}.${member}`,
-					baseline: `${member}=${String(value)}`,
-					candidate: `${valueMatches[0]}=${String(value)}`,
-					message: `Enum member name differs for "${name}.${member}" (value "${value}" preserved as "${valueMatches[0]}")`
-				});
-				continue;
-			}
-			const lowerValue = String(value).toLowerCase();
-			const caseInsensitiveMatch = [...candValueToMembers.entries()].find(([candVal]) => String(candVal).toLowerCase() === lowerValue);
-			if (caseInsensitiveMatch) {
-				violations.push({
-					category: "signature",
-					severity: "warning",
-					symbolPath: `${name}.${member}`,
-					baseline: `${member}=${String(value)}`,
-					candidate: `${caseInsensitiveMatch[1][0]}=${String(caseInsensitiveMatch[0])}`,
-					message: `Enum member value case differs for "${name}.${member}" (baseline "${value}" vs candidate "${caseInsensitiveMatch[0]}")`
-				});
-				continue;
-			}
-			if (String(value) === member || member === "JsonEnumDefaultValue" || member === "JsonProperty") {
-				violations.push({
-					category: "signature",
-					severity: "warning",
-					symbolPath: `${name}.${member}`,
-					baseline: String(value),
-					candidate: "(extraction artifact)",
-					message: `Enum member "${name}.${member}" appears to be an extraction artifact`
-				});
-				continue;
-			}
-			violations.push({
-				category: "signature",
-				severity: "breaking",
-				symbolPath: `${name}.${member}`,
-				baseline: String(value),
-				candidate: member in candEnum.members ? String(candEnum.members[member]) : "(missing)",
-				message: `Enum member mismatch for "${name}.${member}"`
+	}
+	if (additive.length > 0) {
+		lines.push("");
+		lines.push(`  Additive: ${additive.length} new symbol(s)`);
+	}
+	return lines.join("\n");
+}
+//#endregion
+//#region src/cli/compat-diff.ts
+async function compatDiffCommand(opts) {
+	const baselineData = JSON.parse(readFileSync(opts.baseline, "utf-8"));
+	const candidateData = JSON.parse(readFileSync(opts.candidate, "utf-8"));
+	if (!validateSnapshot(baselineData)) throw new Error(`Invalid baseline snapshot: ${opts.baseline}`);
+	if (!validateSnapshot(candidateData)) throw new Error(`Invalid candidate snapshot: ${opts.candidate}`);
+	const diff = diffSnapshots(baselineData, candidateData);
+	console.log(formatHumanSummary(diff, { explain: opts.explain }));
+	if (opts.output) {
+		const report = generateReport(diff);
+		writeFileSync(opts.output, JSON.stringify(report, null, 2));
+		console.log(`Report written to ${opts.output}`);
+	}
+	const failOn = opts.failOn ?? "breaking";
+	if (diff.changes.some((c) => severityMeetsThreshold(c.severity, failOn))) process.exitCode = 1;
+}
+//#endregion
+//#region src/cli/compat-summary.ts
+/**
+* Format compat report(s) as a markdown PR comment.
+*
+* Single report:
+*   oagen compat-summary --report node-report.json | gh pr comment --body-file -
+*
+* Multiple reports (cross-language rollup):
+*   oagen compat-summary --report php.json --report python.json --report go.json
+*/
+async function compatSummaryCommand(opts) {
+	const reports = (Array.isArray(opts.report) ? opts.report : [opts.report]).map((p) => JSON.parse(readFileSync(p, "utf-8")));
+	const md = reports.length === 1 ? formatSingleReport(reports[0]) : formatCrossLanguageRollup(reports);
+	if (opts.output) {
+		writeFileSync(opts.output, md);
+		console.log(`Summary written to ${opts.output}`);
+	} else process.stdout.write(md);
+}
+function formatSingleReport(report) {
+	const lines = [];
+	const { breaking, softRisk, additive } = report.summary;
+	const total = breaking + softRisk + additive;
+	if (breaking > 0) lines.push(`## :x: Compat check failed — ${report.language}`);
+	else if (softRisk > 0) lines.push(`## :warning: Compat check has warnings — ${report.language}`);
+	else lines.push(`## :white_check_mark: Compat check passed — ${report.language}`);
+	lines.push("");
+	lines.push("| Severity | Count |");
+	lines.push("| --- | --- |");
+	lines.push(`| Breaking | ${breaking} |`);
+	lines.push(`| Soft-risk | ${softRisk} |`);
+	lines.push(`| Additive | ${additive} |`);
+	lines.push(`| **Total** | **${total}** |`);
+	if (total === 0) {
+		lines.push("");
+		lines.push("No compatibility changes detected.");
+		return lines.join("\n") + "\n";
+	}
+	const breakingChanges = report.changes.filter((c) => c.severity === "breaking");
+	if (breakingChanges.length > 0) {
+		lines.push("");
+		lines.push("### Breaking changes");
+		lines.push("");
+		lines.push(formatChangesTable(breakingChanges));
+	}
+	const softRiskChanges = report.changes.filter((c) => c.severity === "soft-risk");
+	if (softRiskChanges.length > 0) {
+		lines.push("");
+		lines.push("<details>");
+		lines.push(`<summary>Soft-risk changes (${softRiskChanges.length})</summary>`);
+		lines.push("");
+		lines.push(formatChangesTable(softRiskChanges));
+		lines.push("</details>");
+	}
+	const additiveChanges = report.changes.filter((c) => c.severity === "additive");
+	if (additiveChanges.length > 0) {
+		lines.push("");
+		lines.push("<details>");
+		lines.push(`<summary>Additive changes (${additiveChanges.length})</summary>`);
+		lines.push("");
+		lines.push(formatChangesTable(additiveChanges));
+		lines.push("</details>");
+	}
+	return lines.join("\n") + "\n";
+}
+function formatCrossLanguageRollup(reports) {
+	const languages = reports.map((r) => r.language);
+	const rollup = buildConceptualRollup(reports.map((r) => ({
+		diff: {
+			changes: r.changes,
+			summary: r.summary
+		},
+		language: r.language
+	})));
+	const summary = summarizeConceptualChanges(rollup);
+	const lines = [];
+	if (summary.breaking > 0) lines.push(`## :x: Compat check failed — ${summary.breaking} breaking across ${languages.length} languages`);
+	else if (summary.softRisk > 0) lines.push(`## :warning: Compat check has warnings — ${summary.softRisk} soft-risk across ${languages.length} languages`);
+	else lines.push(`## :white_check_mark: Compat check passed — ${languages.length} languages`);
+	lines.push("");
+	lines.push("| Language | Breaking | Soft-risk | Additive |");
+	lines.push("| --- | --- | --- | --- |");
+	for (const r of reports) lines.push(`| ${r.language} | ${r.summary.breaking} | ${r.summary.softRisk} | ${r.summary.additive} |`);
+	if (rollup.conceptualChanges.length === 0) {
+		lines.push("");
+		lines.push("No compatibility changes detected.");
+		return lines.join("\n") + "\n";
+	}
+	const breakingConcepts = rollup.conceptualChanges.filter((c) => highestSeverity(c) === "breaking");
+	if (breakingConcepts.length > 0) {
+		lines.push("");
+		lines.push("### Breaking changes");
+		lines.push("");
+		lines.push(formatConceptualTable(breakingConcepts, languages));
+	}
+	const softRiskConcepts = rollup.conceptualChanges.filter((c) => highestSeverity(c) === "soft-risk");
+	if (softRiskConcepts.length > 0) {
+		lines.push("");
+		lines.push("<details>");
+		lines.push(`<summary>Soft-risk changes (${softRiskConcepts.length})</summary>`);
+		lines.push("");
+		lines.push(formatConceptualTable(softRiskConcepts, languages));
+		lines.push("</details>");
+	}
+	const additiveConcepts = rollup.conceptualChanges.filter((c) => highestSeverity(c) === "additive");
+	if (additiveConcepts.length > 0) {
+		lines.push("");
+		lines.push("<details>");
+		lines.push(`<summary>Additive changes (${additiveConcepts.length})</summary>`);
+		lines.push("");
+		lines.push(formatConceptualTable(additiveConcepts, languages));
+		lines.push("</details>");
+	}
+	return lines.join("\n") + "\n";
+}
+function formatConceptualTable(concepts, languages) {
+	const lines = [];
+	const langHeaders = languages.map((l) => l).join(" | ");
+	lines.push(`| Symbol | Category | ${langHeaders} |`);
+	lines.push(`| --- | --- | ${languages.map(() => "---").join(" | ")} |`);
+	for (const c of concepts) {
+		const severities = languages.map((l) => severityIcon(c.impact[l])).join(" | ");
+		lines.push(`| \`${c.symbol}\` | \`${c.category}\` | ${severities} |`);
+	}
+	return lines.join("\n");
+}
+function severityIcon(severity) {
+	if (!severity) return "—";
+	switch (severity) {
+		case "breaking": return ":x: breaking";
+		case "soft-risk": return ":warning: soft-risk";
+		case "additive": return ":white_check_mark: additive";
+	}
+}
+function formatChangesTable(changes) {
+	const lines = [];
+	lines.push("| Category | Symbol | Detail |");
+	lines.push("| --- | --- | --- |");
+	for (const c of changes) {
+		const detail = c.message ?? formatOldNew(c.old, c.new);
+		lines.push(`| \`${c.category}\` | \`${c.symbol}\` | ${escapeMarkdown(detail)} |`);
+	}
+	return lines.join("\n");
+}
+function formatOldNew(old, updated) {
+	const parts = [];
+	for (const key of Object.keys(old)) if (updated[key] && old[key] !== updated[key]) parts.push(`${key}: \`${old[key]}\` → \`${updated[key]}\``);
+	return parts.length > 0 ? parts.join(", ") : "";
+}
+function escapeMarkdown(text) {
+	return text.replace(/\|/g, "\\|").replace(/\n/g, " ");
+}
+//#endregion
+//#region src/compat/approvals.ts
+/**
+* Match a classified change against a list of approvals.
+* Returns the first matching approval, or null if none match.
+*/
+function matchApproval(change, approvals, language) {
+	for (const approval of approvals) if (approvalMatchesChange(approval, change, language)) return approval;
+	return null;
+}
+/**
+* Filter changes to only those NOT covered by approvals.
+* These are the remaining unapproved changes that may cause failure.
+*/
+function unapprovedChanges(changes, approvals, language) {
+	return changes.filter((change) => !matchApproval(change, approvals, language));
+}
+function approvalMatchesChange(approval, change, language) {
+	if (approval.approved === false) return false;
+	if (approval.category !== change.category) return false;
+	if (!symbolMatches(approval.symbol, change.symbol)) return false;
+	if (!languageMatches(approval.appliesTo, language)) return false;
+	if (approval.match && !narrowingMatches(approval.match, change)) return false;
+	return true;
+}
+function symbolMatches(approvalSymbol, changeSymbol) {
+	if (approvalSymbol === changeSymbol) return true;
+	return approvalSymbol.replace(/::/g, ".").replace(/\\/g, ".") === changeSymbol.replace(/::/g, ".").replace(/\\/g, ".");
+}
+function languageMatches(appliesTo, language) {
+	if (!appliesTo || appliesTo === "all-impacted-languages") return true;
+	return appliesTo.includes(language);
+}
+function narrowingMatches(match, change) {
+	if (match.parameter) {
+		const paramInOld = change.old.parameter === match.parameter;
+		const paramInNew = change.new.parameter === match.parameter;
+		if (!paramInOld && !paramInNew) return false;
+	}
+	if (match.member) {
+		const memberInOld = change.old.member === match.member;
+		const memberInNew = change.new.member === match.member;
+		if (!memberInOld && !memberInNew) return false;
+	}
+	if (match.oldName) {
+		if (!Object.values(change.old).some((v) => v === match.oldName)) return false;
+	}
+	if (match.newName) {
+		if (!Object.values(change.new).some((v) => v === match.newName)) return false;
+	}
+	return true;
+}
+//#endregion
+//#region src/compat/policy.ts
+/** Built-in language defaults. */
+const LANGUAGE_DEFAULTS = {
+	php: {
+		callerUsesParamNames: true,
+		constructorOrderMatters: true,
+		methodParameterNamesArePublicApi: true,
+		constructorParameterNamesArePublicApi: true,
+		overloadsArePublicApi: false,
+		arityIsPublicApi: false
+	},
+	python: {
+		callerUsesParamNames: true,
+		constructorOrderMatters: true,
+		methodParameterNamesArePublicApi: true,
+		constructorParameterNamesArePublicApi: true,
+		overloadsArePublicApi: false,
+		arityIsPublicApi: false
+	},
+	ruby: {
+		callerUsesParamNames: true,
+		constructorOrderMatters: true,
+		methodParameterNamesArePublicApi: true,
+		constructorParameterNamesArePublicApi: true,
+		overloadsArePublicApi: false,
+		arityIsPublicApi: false
+	},
+	go: {
+		callerUsesParamNames: false,
+		constructorOrderMatters: true,
+		methodParameterNamesArePublicApi: false,
+		constructorParameterNamesArePublicApi: false,
+		overloadsArePublicApi: false,
+		arityIsPublicApi: true
+	},
+	kotlin: {
+		callerUsesParamNames: true,
+		constructorOrderMatters: false,
+		methodParameterNamesArePublicApi: true,
+		constructorParameterNamesArePublicApi: true,
+		overloadsArePublicApi: true,
+		arityIsPublicApi: false
+	},
+	dotnet: {
+		callerUsesParamNames: true,
+		constructorOrderMatters: false,
+		methodParameterNamesArePublicApi: true,
+		constructorParameterNamesArePublicApi: true,
+		overloadsArePublicApi: true,
+		arityIsPublicApi: false
+	},
+	elixir: {
+		callerUsesParamNames: true,
+		constructorOrderMatters: false,
+		methodParameterNamesArePublicApi: true,
+		constructorParameterNamesArePublicApi: false,
+		overloadsArePublicApi: false,
+		arityIsPublicApi: true
+	},
+	rust: {
+		callerUsesParamNames: false,
+		constructorOrderMatters: true,
+		methodParameterNamesArePublicApi: false,
+		constructorParameterNamesArePublicApi: false,
+		overloadsArePublicApi: false,
+		arityIsPublicApi: true
+	},
+	node: {
+		callerUsesParamNames: false,
+		constructorOrderMatters: false,
+		methodParameterNamesArePublicApi: false,
+		constructorParameterNamesArePublicApi: false,
+		overloadsArePublicApi: false,
+		arityIsPublicApi: false
+	}
+};
+/** Get the built-in default policy for a language. */
+function getDefaultPolicy(language) {
+	return { ...LANGUAGE_DEFAULTS[language] };
+}
+/** Merge user overrides onto language defaults. Only provided keys are overridden. */
+function mergePolicy(defaults, overrides) {
+	return {
+		...defaults,
+		...overrides
+	};
+}
+//#endregion
+//#region src/compat/ir.ts
+/**
+* Convert a legacy ApiSurface to a CompatSnapshot.
+*
+* This bridge allows existing extractors (which produce ApiSurface) to feed
+* into the new classified diff engine without requiring immediate migration.
+*/
+function apiSurfaceToSnapshot(surface) {
+	const language = surface.language || "node";
+	const symbols = [];
+	for (const [className, cls] of Object.entries(surface.classes)) {
+		symbols.push({
+			id: `class:${className}`,
+			kind: "service_accessor",
+			fqName: className,
+			displayName: className,
+			visibility: "public",
+			stability: cls.deprecationMessage ? "deprecated" : "stable",
+			sourceKind: "generated_service_wrapper"
+		});
+		if (cls.constructorParams.length > 0) symbols.push({
+			id: `ctor:${className}`,
+			kind: "constructor",
+			fqName: `${className}.constructor`,
+			ownerFqName: className,
+			displayName: `new ${className}`,
+			visibility: "public",
+			stability: "stable",
+			sourceKind: "generated_resource_constructor",
+			parameters: cls.constructorParams.map((p, i) => apiParamToCompatParam(p, i, language))
+		});
+		for (const [methodName, overloads] of Object.entries(cls.methods)) for (let oi = 0; oi < overloads.length; oi++) {
+			const method = overloads[oi];
+			const suffix = overloads.length > 1 ? `#${oi}` : "";
+			symbols.push({
+				id: `method:${className}.${methodName}${suffix}`,
+				kind: "callable",
+				fqName: `${className}.${methodName}`,
+				ownerFqName: className,
+				displayName: `${className}.${methodName}`,
+				visibility: "public",
+				stability: "stable",
+				sourceKind: "generated_service_wrapper",
+				parameters: method.params.map((p, i) => apiParamToCompatParam(p, i, language)),
+				returns: { name: method.returnType }
 			});
-			enumMatch = false;
 		}
-		if (enumMatch) preserved++;
+		for (const [propName, prop] of Object.entries(cls.properties)) symbols.push({
+			id: `prop:${className}.${propName}`,
+			kind: "property",
+			fqName: `${className}.${propName}`,
+			ownerFqName: className,
+			displayName: `${className}.${propName}`,
+			visibility: "public",
+			stability: "stable",
+			sourceKind: "generated_service_wrapper",
+			typeRef: { name: prop.type }
+		});
 	}
-	for (const name of Object.keys(candidate.enums)) if (!baseline.enums[name]) additions.push({
-		symbolPath: name,
-		symbolType: "enum"
+	for (const [ifaceName, iface] of Object.entries(surface.interfaces)) {
+		symbols.push({
+			id: `iface:${ifaceName}`,
+			kind: "alias",
+			fqName: ifaceName,
+			displayName: ifaceName,
+			visibility: "public",
+			stability: "stable",
+			sourceKind: "generated_resource_constructor"
+		});
+		for (const [fieldName, field] of Object.entries(iface.fields)) symbols.push({
+			id: `field:${ifaceName}.${fieldName}`,
+			kind: "field",
+			fqName: `${ifaceName}.${fieldName}`,
+			ownerFqName: ifaceName,
+			displayName: `${ifaceName}.${fieldName}`,
+			visibility: "public",
+			stability: "stable",
+			sourceKind: "generated_resource_constructor",
+			typeRef: { name: field.type }
+		});
+		if (iface.hasCustomConstructor) symbols.push({
+			id: `ctor:${ifaceName}`,
+			kind: "constructor",
+			fqName: `${ifaceName}.constructor`,
+			ownerFqName: ifaceName,
+			displayName: `new ${ifaceName}`,
+			visibility: "public",
+			stability: "stable",
+			sourceKind: "generated_resource_constructor"
+		});
+	}
+	for (const [aliasName] of Object.entries(surface.typeAliases)) symbols.push({
+		id: `alias:${aliasName}`,
+		kind: "alias",
+		fqName: aliasName,
+		displayName: aliasName,
+		visibility: "public",
+		stability: "stable",
+		sourceKind: "generated_resource_constructor"
 	});
-	for (const [path, baseExports] of Object.entries(baseline.exports)) {
-		const candExports = candidate.exports[path];
-		if (!candExports) {
-			for (const exp of baseExports) violations.push({
-				category: "export-structure",
-				severity: "warning",
-				symbolPath: `exports[${path}].${exp}`,
-				baseline: exp,
-				candidate: "(missing)",
-				message: `Export "${exp}" from "${path}" not found in generated output`
-			});
-			continue;
-		}
-		const candSet = new Set(candExports);
-		for (const exp of baseExports) if (!candSet.has(exp)) violations.push({
-			category: "export-structure",
-			severity: "warning",
-			symbolPath: `exports[${path}].${exp}`,
-			baseline: exp,
-			candidate: "(missing)",
-			message: `Export "${exp}" from "${path}" not found in generated output`
+	for (const [enumName, enumDef] of Object.entries(surface.enums)) {
+		symbols.push({
+			id: `enum:${enumName}`,
+			kind: "enum",
+			fqName: enumName,
+			displayName: enumName,
+			visibility: "public",
+			stability: "stable",
+			sourceKind: "generated_enum"
+		});
+		for (const [memberName, memberValue] of Object.entries(enumDef.members)) symbols.push({
+			id: `enum_member:${enumName}.${memberName}`,
+			kind: "enum_member",
+			fqName: `${enumName}.${memberName}`,
+			ownerFqName: enumName,
+			displayName: `${enumName}.${memberName}`,
+			visibility: "public",
+			stability: "stable",
+			sourceKind: "generated_enum",
+			value: memberValue
 		});
 	}
 	return {
-		preservationScore: totalBaseline > 0 ? Math.round(preserved / totalBaseline * 100) : 100,
-		totalBaselineSymbols: totalBaseline,
-		preservedSymbols: preserved,
-		violations,
-		additions
+		schemaVersion: "1",
+		source: { extractedAt: surface.extractedAt },
+		policies: getDefaultPolicy(language),
+		symbols
 	};
 }
-/**
-* Compare method signatures using raw type strings.
-* NOTE: This only produces meaningful results when both surfaces were extracted
-* by the same extractor for the same language. Cross-language or cross-extractor
-* comparisons will always fail because type representations differ.
-*/
-function signaturesMatch(baseline, candidate) {
-	if (baseline.returnType !== candidate.returnType) return false;
-	for (let i = 0; i < baseline.params.length; i++) {
-		const baseParam = baseline.params[i];
-		const candParam = candidate.params[i];
-		if (!candParam) return false;
-		if (baseParam.type !== candParam.type) return false;
-		if (baseParam.name !== candParam.name) return false;
-	}
-	for (let i = baseline.params.length; i < candidate.params.length; i++) if (!candidate.params[i].optional) return false;
-	return true;
+/** Convert a legacy ApiParam to a CompatParameter. */
+function apiParamToCompatParam(param, position, language) {
+	const policy = getDefaultPolicy(language);
+	return {
+		publicName: param.name,
+		position,
+		required: !param.optional,
+		nullable: false,
+		hasDefault: param.optional,
+		passing: param.passingStyle ?? inferPassingStyle(language),
+		type: { name: param.type },
+		sensitivity: {
+			order: policy.constructorOrderMatters,
+			publicName: policy.methodParameterNamesArePublicApi,
+			requiredness: true,
+			type: true
+		}
+	};
 }
-function formatSignature(method) {
-	return `(${method.params.map((p) => `${p.name}${p.optional ? "?" : ""}: ${p.type}`).join(", ")}) => ${method.returnType}`;
+/** Infer the default parameter passing style for a language. */
+function inferPassingStyle(language) {
+	switch (language) {
+		case "python":
+		case "ruby":
+		case "elixir": return "keyword";
+		case "php":
+		case "kotlin":
+		case "dotnet": return "named";
+		case "node": return "options_object";
+		default: return "positional";
+	}
 }
 //#endregion
 //#region src/verify/run-compat-check.ts
-async function runCompatCheck(baseline, outputDir, lang, spec) {
+async function runCompatCheck(baseline, outputDir, lang, spec, policyOverrides) {
 	const extractor = getExtractor(lang);
 	const candidate = await extractor.extract(outputDir);
 	let scopedBaseline = baseline;
@@ -6597,9 +7397,12 @@ async function runCompatCheck(baseline, outputDir, lang, spec) {
 		scopedToSpec = true;
 		scopedSymbolCount = Object.keys(scopedBaseline.interfaces).length + Object.keys(scopedBaseline.classes).length + Object.keys(scopedBaseline.typeAliases).length + Object.keys(scopedBaseline.enums).length;
 	}
-	const diff = diffSurfaces(scopedBaseline, candidate, extractor.hints);
+	const baseSnap = apiSurfaceToSnapshot(scopedBaseline);
+	const candSnap = apiSurfaceToSnapshot(candidate);
+	const langId = lang;
+	const diff = diffSnapshots(baseSnap, candSnap, policyOverrides ? mergePolicy(getDefaultPolicy(langId), policyOverrides) : getDefaultPolicy(langId));
 	return {
-		passed: diff.violations.every((v) => v.severity !== "breaking"),
+		passed: diff.changes.every((c) => c.severity !== "breaking"),
 		diff,
 		scopedToSpec,
 		scopedSymbolCount
@@ -6607,7 +7410,6 @@ async function runCompatCheck(baseline, outputDir, lang, spec) {
 }
 //#endregion
 //#region src/verify/run-overlay-retry-loop.ts
-const PATCHABLE_CATEGORIES = new Set(["public-api", "export-structure"]);
 /** Generated file header markers used by various emitters. */
 const GENERATED_MARKERS = [
 	"Code generated by oagen",
@@ -6699,21 +7501,21 @@ async function runOverlayRetryLoop(opts) {
 			patchedPerIteration,
 			compatResult
 		};
-		const patchable = compatResult.diff.violations.filter((v) => PATCHABLE_CATEGORIES.has(v.category));
+		const patchable = compatResult.diff.changes.filter(isPatchableChange);
 		if (patchable.length === 0) return {
 			status: "no-patchable",
 			attempts: attempt,
 			patchedPerIteration,
 			compatResult
 		};
-		const currentPreserved = compatResult.diff.preservedSymbols;
-		if (attempt > 0 && currentPreserved <= prevPreserved) return {
+		const currentBreaking = compatResult.diff.summary.breaking;
+		if (attempt > 0 && currentBreaking >= prevPreserved) return {
 			status: "stalled",
 			attempts: attempt,
 			patchedPerIteration,
 			compatResult
 		};
-		prevPreserved = currentPreserved;
+		prevPreserved = currentBreaking;
 		patchedPerIteration.push(patchable.length);
 		onRetry?.(attempt + 1, maxRetries, patchable.length);
 		overlay = patchOverlay(overlay, patchable, baseline);
@@ -6902,17 +7704,20 @@ function runSmokeCheck(opts) {
 function summarizeCompatCheck(result) {
 	const violationsByCategory = {};
 	const violationsBySeverity = {};
-	for (const v of result.diff.violations) {
-		violationsByCategory[v.category] = (violationsByCategory[v.category] ?? 0) + 1;
-		violationsBySeverity[v.severity] = (violationsBySeverity[v.severity] ?? 0) + 1;
+	for (const c of result.diff.changes) {
+		violationsByCategory[c.category] = (violationsByCategory[c.category] ?? 0) + 1;
+		violationsBySeverity[c.severity] = (violationsBySeverity[c.severity] ?? 0) + 1;
 	}
+	const { breaking, softRisk, additive } = result.diff.summary;
+	const totalBaselineSymbols = breaking + softRisk + additive + additive;
+	const preservedSymbols = totalBaselineSymbols - breaking - softRisk;
 	return {
-		totalBaselineSymbols: result.diff.totalBaselineSymbols,
-		preservedSymbols: result.diff.preservedSymbols,
-		preservationScore: result.diff.preservationScore,
+		totalBaselineSymbols,
+		preservedSymbols,
+		preservationScore: totalBaselineSymbols > 0 ? Math.round(preservedSymbols / totalBaselineSymbols * 100) : 100,
 		violationsByCategory,
 		violationsBySeverity,
-		additions: result.diff.additions.length,
+		additions: additive,
 		scopedToSpec: result.scopedToSpec,
 		...result.scopedSymbolCount !== void 0 ? { scopedSymbolCount: result.scopedSymbolCount } : {}
 	};
@@ -6939,9 +7744,12 @@ function printCompatResult(result, baseline) {
 	console.log(`compat: ${result.preservationScore}% (${result.preservedSymbols}/${result.totalBaselineSymbols} symbols preserved)`);
 }
 async function verifyCommand(opts) {
-	const { spec, oldSpec, lang, output, apiSurface, rawResults, smokeConfig, smokeRunner, scope, diagnostics, operationIdTransform, schemaNameTransform } = opts;
+	const { spec, oldSpec, lang, output, apiSurface, rawResults, smokeConfig, smokeRunner, scope, diagnostics, operationIdTransform, schemaNameTransform, compatConfig, compatReport, compatExplain } = opts;
 	const maxRetries = opts.maxRetries ?? 3;
 	const diagData = {};
+	const effectiveFailOn = opts.compatFailOn ?? compatConfig?.failOn ?? "breaking";
+	const effectiveReportPath = compatReport ?? compatConfig?.reportPath;
+	const effectiveExplain = compatExplain ?? compatConfig?.explain ?? false;
 	let stepNum = 1;
 	const baseline = apiSurface ? JSON.parse(readFileSync(apiSurface, "utf-8")) : void 0;
 	if (apiSurface && baseline) {
@@ -6973,11 +7781,13 @@ async function verifyCommand(opts) {
 		};
 		const compatSummary = summarizeCompatCheck(compatFlow.compatResult);
 		printCompatResult(compatSummary, baseline);
-		for (const v of compatFlow.compatResult.diff.violations) console.log(`  [${v.category}] ${v.severity}: ${v.symbolPath} — ${v.message}`);
-		if (compatFlow.compatResult.diff.additions.length > 0) console.log(`  + ${compatFlow.compatResult.diff.additions.length} new symbols added`);
+		const classifiedDiff = compatFlow.compatResult.diff;
+		for (const c of classifiedDiff.changes) if (c.severity !== "additive") console.log(`  [${c.category}] ${c.severity}: ${c.symbol} — ${c.message}`);
+		const additiveCount = classifiedDiff.summary.additive;
+		if (additiveCount > 0) console.log(`  + ${additiveCount} new symbols added`);
 		if (diagnostics) {
 			diagData.compatCheck = compatSummary;
-			if (parsedSpec && maxRetries > 0) setRetryDiagnostics(diagData, compatFlow.attempts, compatFlow.status === "passed", compatFlow.compatResult.diff.preservationScore, compatFlow.patchedPerIteration);
+			if (parsedSpec && maxRetries > 0) setRetryDiagnostics(diagData, compatFlow.attempts, compatFlow.status === "passed", compatSummary.preservationScore, compatFlow.patchedPerIteration);
 		}
 		if (compatFlow.status === "passed" && compatFlow.compatResult.passed) if (compatFlow.attempts > 0) console.log(`Compat: converged after ${compatFlow.attempts} retry iteration(s)`);
 		else console.log("Compat: passed");
@@ -6987,9 +7797,28 @@ async function verifyCommand(opts) {
 				console.log("Diagnostics written to verify-diagnostics.json");
 			}
 			if (compatFlow.status === "no-patchable") console.log("No patchable violations — cannot self-correct. Remaining violations require emitter code changes.");
-			else if (compatFlow.status === "stalled") console.log(`Stalled at ${compatFlow.compatResult.diff.preservationScore}% — overlay patching is not making progress.`);
+			else if (compatFlow.status === "stalled") console.log(`Stalled — overlay patching is not making progress.`);
 			throw new CommandError("\nCompat violations found — fix the emitter and re-run `oagen verify`.", "", 1);
 		}
+		if (effectiveReportPath || effectiveExplain || (compatConfig?.allow?.length ?? 0) > 0) {
+			const langId = lang;
+			const approvals = compatConfig?.allow ?? [];
+			const remaining = unapprovedChanges(classifiedDiff.changes, approvals, langId);
+			const hasFailure = remaining.some((c) => severityMeetsThreshold(c.severity, effectiveFailOn));
+			if (effectiveExplain) {
+				console.log("");
+				console.log(formatHumanSummary(classifiedDiff, { explain: true }));
+			}
+			if (effectiveReportPath) {
+				const report = generateReport(classifiedDiff);
+				writeFileSync(effectiveReportPath, JSON.stringify(report, null, 2) + "\n");
+				console.log(`Compat report written to ${effectiveReportPath}`);
+			}
+			if (hasFailure && effectiveFailOn !== "none") {
+				const unapprovedBreaking = remaining.filter((c) => severityMeetsThreshold(c.severity, effectiveFailOn));
+				console.log(`\n${unapprovedBreaking.length} unapproved change(s) at or above '${effectiveFailOn}' threshold`);
+			}
+		}
 		stepNum++;
 	}
 	if (oldSpec && spec && apiSurface && baseline) {
@@ -7071,10 +7900,16 @@ function packageJson(lang) {
 		type: "module",
 		main: "dist/index.js",
 		types: "dist/index.d.ts",
-		exports: { ".": {
-			types: "./dist/index.d.ts",
-			import: "./dist/index.js"
-		} },
+		exports: {
+			".": {
+				types: "./dist/index.d.ts",
+				import: "./dist/index.js"
+			},
+			"./plugin": {
+				types: "./dist/plugin.d.ts",
+				import: "./dist/plugin.js"
+			}
+		},
 		scripts: {
 			build: "tsup",
 			test: "vitest run",
@@ -7123,7 +7958,7 @@ export default defineConfig({
 function tsupConfig() {
 	return `import { defineConfig } from 'tsup';
 export default defineConfig({
-  entry: { index: 'src/index.ts' },
+  entry: { index: 'src/index.ts', plugin: 'src/plugin.ts' },
   format: ['esm'],
   dts: true,
   clean: true,
@@ -7131,19 +7966,34 @@ export default defineConfig({
 });
 `;
 }
-function oagenConfig(lang) {
-	const varName = `${toCamelCase(lang)}Emitter`;
+function oagenConfig() {
 	return `import type { OagenConfig } from '@workos/oagen';
-import { ${varName} } from './src/${lang}/index.js';
+import { plugin } from './src/plugin.js';
 
+// Minimal config for local emitter development.
+// The canonical consumer config lives in the consumer project's oagen.config.ts,
+// which imports the plugin bundle from this package.
 const config: OagenConfig = {
-  emitters: [${varName}],
+  ...plugin,
 };
 export default config;
 `;
 }
+function srcPlugin(lang) {
+	const varName = `${toCamelCase(lang)}Emitter`;
+	return `import type { OagenConfig } from '@workos/oagen';
+import { ${varName} } from './${lang}/index.js';
+
+export const plugin: Pick<OagenConfig, 'emitters' | 'extractors' | 'smokeRunners'> = {
+  emitters: [${varName}],
+  extractors: [],
+  smokeRunners: {},
+};
+`;
+}
 function srcIndex(lang) {
 	return `export { ${`${toCamelCase(lang)}Emitter`} } from './${lang}/index.js';
+export { plugin } from './plugin.js';
 `;
 }
 function gitignore() {
@@ -7216,7 +8066,8 @@ async function initCommand(opts) {
 		["tsconfig.json", tsconfigJson()],
 		["vitest.config.ts", vitestConfig()],
 		["tsup.config.ts", tsupConfig()],
-		["oagen.config.ts", oagenConfig(lang)],
+		["oagen.config.ts", oagenConfig()],
+		["src/plugin.ts", srcPlugin(lang)],
 		["src/index.ts", srcIndex(lang)],
 		[`src/${lang}/index.ts`, stubEmitter(lang)]
 	];
@@ -7325,12 +8176,30 @@ const CONFIG_NAMES = [
 	"oagen.config.js",
 	"oagen.config.mjs"
 ];
-async function loadConfig(cwd = process.cwd()) {
+/**
+* Load an oagen config file.
+*
+* @param configPath - Explicit path to a config file. When provided, only that
+*   file is attempted (no fallback search).
+* @param cwd - Directory to search when `configPath` is omitted. Defaults to
+*   `process.cwd()`. The loader tries each name in `CONFIG_NAMES` in order.
+*/
+async function loadConfig(configPath, cwd = process.cwd()) {
+	if (configPath) {
+		const resolved = path$1.resolve(cwd, configPath);
+		if (!existsSync(resolved)) throw new ConfigLoadError(`Config file not found: ${resolved}`, "Check that the path passed to --config exists.");
+		try {
+			const mod = await import(pathToFileURL(resolved).href);
+			return mod.default ?? mod;
+		} catch (err) {
+			throw new ConfigLoadError(`Failed to load ${resolved}: ${err instanceof Error ? err.message : String(err)}`, resolved.endsWith(".ts") ? "TypeScript config files require tsx or ts-node. Use .mjs instead, or run via `npx tsx`." : "Check that the config file is valid ESM.");
+		}
+	}
 	for (const name of CONFIG_NAMES) {
-		const configPath = path$1.resolve(cwd, name);
-		if (!existsSync(configPath)) continue;
+		const resolved = path$1.resolve(cwd, name);
+		if (!existsSync(resolved)) continue;
 		try {
-			const mod = await import(pathToFileURL(configPath).href);
+			const mod = await import(pathToFileURL(resolved).href);
 			return mod.default ?? mod;
 		} catch (err) {
 			throw new ConfigLoadError(`Failed to load ${name}: ${err instanceof Error ? err.message : String(err)}`, name.endsWith(".ts") ? "TypeScript config files require tsx or ts-node. Use .mjs instead, or run via `npx tsx`." : "Check that the config file is valid ESM.");
@@ -7352,14 +8221,17 @@ function handleError(err) {
 	if (message) console.error(message);
 	process.exit(exitCode);
 }
+const configArgIdx = process.argv.indexOf("--config");
+const explicitConfigPath = configArgIdx !== -1 ? process.argv[configArgIdx + 1] : void 0;
 let configSmokeRunners;
 let configOperationIdTransform;
 let configSchemaNameTransform;
 let configDocUrl;
 let configOperationHints;
 let configMountRules;
+let configCompat;
 try {
-	const config = await loadConfig();
+	const config = await loadConfig(explicitConfigPath);
 	if (config) {
 		applyConfig(config);
 		configSmokeRunners = config.smokeRunners;
@@ -7368,11 +8240,12 @@ try {
 		configDocUrl = config.docUrl;
 		configOperationHints = config.operationHints;
 		configMountRules = config.mountRules;
+		configCompat = config.compat;
 	}
 } catch (err) {
 	handleError(err);
 }
-const program = new Command().name("oagen").description("Framework for building OpenAPI SDK emitters").version("0.0.1");
+const program = new Command().name("oagen").description("Framework for building OpenAPI SDK emitters").version("0.0.1").option("--config <path>", "Path to oagen config file (default: oagen.config.ts in cwd)");
 program.command("parse").description("Parse an OpenAPI spec and output IR as JSON").option("--spec <path>", "Path to OpenAPI spec file (or set OPENAPI_SPEC_PATH)").action((opts) => {
 	opts.spec ??= process.env.OPENAPI_SPEC_PATH;
 	if (!opts.spec) {
@@ -7408,14 +8281,29 @@ program.command("extract").description("Extract public API surface from a live S
 	opts.output ??= `sdk-${opts.lang}-surface.json`;
 	extractCommand(opts).catch(handleError);
 });
-program.command("verify").description("Run smoke tests (and optional compat check) against an already-generated SDK").option("--spec <path>", "Path to OpenAPI spec file (or set OPENAPI_SPEC_PATH)").requiredOption("--lang <language>", "Target language").requiredOption("--output <dir>", "Path to the generated SDK").option("--api-surface <path>", "Baseline API surface JSON — enables compat verification").option("--raw-results <path>", "Path to an existing smoke baseline file to diff against").option("--smoke-config <path>", "Path to smoke config JSON for skip lists and service mappings").option("--smoke-runner <path>", "Path to a custom smoke runner script (overrides built-in sdk-test.ts)").option("--scope <mode>", "Compat scope: \"full\" compares all baseline symbols, \"spec-only\" compares only symbols derivable from the OpenAPI spec (default: spec-only when --spec is provided)").option("--old-spec <path>", "Previous OpenAPI spec — enables staleness detection for removed/renamed symbols").option("--namespace <name>", "SDK namespace/package name (used by retry loop for regeneration)").option("--diagnostics", "Output verify-diagnostics.json with structured violation breakdown").option("--max-retries <n>", "Max retry iterations for self-correcting overlay loop (default: 3)", "3").action((opts) => {
+program.command("compat-extract").description("Extract a compat snapshot from a live SDK and write .oagen-compat-snapshot.json").requiredOption("--sdk-path <path>", "Path to the live SDK").requiredOption("--lang <language>", "Target language").requiredOption("--output <dir>", "Directory to write .oagen-compat-snapshot.json into").option("--spec <path>", "Path to OpenAPI spec — enriches symbols with operationId, route, and specSha").action((opts) => {
+	opts.spec ??= process.env.OPENAPI_SPEC_PATH;
+	compatExtractCommand(opts).catch(handleError);
+});
+program.command("compat-diff").description("Diff two compat snapshot files and produce a classified change report").requiredOption("--baseline <path>", "Path to the baseline compat snapshot JSON").requiredOption("--candidate <path>", "Path to the candidate compat snapshot JSON").option("--output <path>", "Write machine-readable report to this path").option("--fail-on <level>", "Fail threshold: none, breaking, or soft-risk", "breaking").option("--explain", "Include provenance explanations in output").action((opts) => {
+	compatDiffCommand(opts).catch(handleError);
+});
+program.command("compat-summary").description("Format compat report(s) as a markdown PR comment").requiredOption("--report <path...>", "Path(s) to compat report JSON(s) — pass multiple for cross-language rollup").option("--output <path>", "Write markdown to this file instead of stdout").action((opts) => {
+	compatSummaryCommand(opts).catch(handleError);
+});
+program.command("verify").description("Run smoke tests (and optional compat check) against an already-generated SDK").option("--spec <path>", "Path to OpenAPI spec file (or set OPENAPI_SPEC_PATH)").requiredOption("--lang <language>", "Target language").requiredOption("--output <dir>", "Path to the generated SDK").option("--api-surface <path>", "Baseline API surface JSON — enables compat verification").option("--raw-results <path>", "Path to an existing smoke baseline file to diff against").option("--smoke-config <path>", "Path to smoke config JSON for skip lists and service mappings").option("--smoke-runner <path>", "Path to a custom smoke runner script (overrides built-in sdk-test.ts)").option("--scope <mode>", "Compat scope: \"full\" compares all baseline symbols, \"spec-only\" compares only symbols derivable from the OpenAPI spec (default: spec-only when --spec is provided)").option("--old-spec <path>", "Previous OpenAPI spec — enables staleness detection for removed/renamed symbols").option("--namespace <name>", "SDK namespace/package name (used by retry loop for regeneration)").option("--diagnostics", "Output verify-diagnostics.json with structured violation breakdown").option("--max-retries <n>", "Max retry iterations for self-correcting overlay loop (default: 3)", "3").option("--compat-report <path>", "Write machine-readable compat report to this path").option("--compat-fail-on <level>", "Fail threshold: none, breaking, or soft-risk").option("--compat-baseline <path>", "Path to baseline compatibility snapshot").option("--compat-explain", "Include provenance explanations in compat output").action((opts) => {
 	opts.spec ??= process.env.OPENAPI_SPEC_PATH;
 	opts.smokeRunner ??= configSmokeRunners?.[opts.lang];
 	verifyCommand({
 		...opts,
 		maxRetries: parseInt(opts.maxRetries, 10),
 		operationIdTransform: configOperationIdTransform,
-		schemaNameTransform: configSchemaNameTransform
+		schemaNameTransform: configSchemaNameTransform,
+		compatConfig: configCompat,
+		compatReport: opts.compatReport,
+		compatFailOn: opts.compatFailOn,
+		compatBaseline: opts.compatBaseline,
+		compatExplain: opts.compatExplain
 	}).catch(handleError);
 });
 program.command("resolve").description("Resolve operation names from spec and output a review table").option("--spec <path>", "Path to OpenAPI spec file (or set OPENAPI_SPEC_PATH)").option("--format <format>", "Output format: table or json", "table").action((opts) => {