@workos/oagen 0.7.0 → 0.9.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
@@ -822,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) {
@@ -840,14 +842,18 @@ function extractAllOfModel(name, schema, schemas) {
 			}
 		} else if (resolved.oneOf || resolved.anyOf) {
 			const variants = resolved.oneOf ?? resolved.anyOf ?? [];
-			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));
+			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 {
@@ -866,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) {
@@ -4730,8 +4771,7 @@ function generateAllFiles(spec, emitter, ctx) {
 		...emitter.generateClient(spec, ctx),
 		...emitter.generateErrors(ctx),
 		...emitter.generateTypeSignatures?.(reachableSpec, ctx) ?? [],
-		...emitter.generateTests(reachableSpec, ctx),
-		...emitter.generateManifest?.(spec, ctx) ?? []
+		...emitter.generateTests(reachableSpec, ctx)
 	];
 }
 /** Apply file header to generated files, respecting headerPlacement and JSON files. */
@@ -4745,11 +4785,13 @@ function applyFileHeaders(files, header) {
 function generateFiles(spec, emitter, options) {
 	const ctx = buildEmitterContext(spec, options);
 	const files = generateAllFiles(spec, emitter, ctx);
+	const operations = emitter.buildOperationsMap?.(spec, ctx);
 	const header = emitter.fileHeader();
 	return {
 		files: applyFileHeaders(files, header),
 		ctx,
-		header
+		header,
+		operations
 	};
 }
 //#endregion
@@ -4980,7 +5022,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);
@@ -5007,8 +5049,16 @@ 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(),
-		files: [...new Set(opts.files)].sort()
+		...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(),
+		...opts.operations !== void 0 ? { operations: opts.operations } : {}
 	};
 	const manifestPath = path$1.join(dir, MANIFEST_FILENAME);
 	await fs.mkdir(dir, { recursive: true });
@@ -5090,7 +5140,7 @@ async function removeEmptyParents(startDir, stopDir) {
 async function generate(spec, emitter, options) {
 	const targetManifestForCtx = options.target && !options.noPrune ? await readManifest(options.target) : null;
 	const priorTargetManifestPaths = targetManifestForCtx ? new Set(targetManifestForCtx.files) : void 0;
-	const { files: withHeaders, header } = generateFiles(spec, emitter, {
+	const { files: withHeaders, header, operations } = generateFiles(spec, emitter, {
 		...options,
 		priorTargetManifestPaths
 	});
@@ -5116,8 +5166,11 @@ async function generate(spec, emitter, options) {
 		currentPaths: outputEmittedPaths,
 		language: emitter.language,
 		header,
-		noPrune: options.noPrune
+		noPrune: options.noPrune,
+		operations
 	});
+	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({
@@ -5136,7 +5189,8 @@ async function generate(spec, emitter, options) {
 			currentPaths: targetResult.emittedPaths,
 			language: emitter.language,
 			header,
-			noPrune: options.noPrune
+			noPrune: options.noPrune,
+			operations
 		});
 		const allTargetFiles = [
 			...targetResult.written,
@@ -5152,19 +5206,18 @@ async function generate(spec, emitter, options) {
 * then write the fresh manifest.  Safe on first adoption (no previous manifest).
 */
 async function applyManifestPrune(opts) {
+	const manifestOpts = {
+		language: opts.language,
+		files: opts.currentPaths,
+		operations: opts.operations
+	};
 	if (opts.noPrune) {
-		await writeManifest(opts.dir, {
-			language: opts.language,
-			files: opts.currentPaths
-		});
+		await writeManifest(opts.dir, manifestOpts);
 		return;
 	}
 	if (!opts.prevManifest) {
 		console.log(`${opts.label}: no ${MANIFEST_FILENAME} found — skipping prune (this baseline manifest will be written now).`);
-		await writeManifest(opts.dir, {
-			language: opts.language,
-			files: opts.currentPaths
-		});
+		await writeManifest(opts.dir, manifestOpts);
 		return;
 	}
 	const stale = computeStalePaths(opts.prevManifest, opts.currentPaths);
@@ -5176,10 +5229,7 @@ async function applyManifestPrune(opts) {
 			for (const p of preserved) console.log(`  ${p}`);
 		}
 	}
-	await writeManifest(opts.dir, {
-		language: opts.language,
-		files: opts.currentPaths
-	});
+	await writeManifest(opts.dir, manifestOpts);
 }
 //#endregion
 //#region src/engine/registry.ts
@@ -5659,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),
@@ -5675,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 operations map in .oagen-manifest.json. Method-level violations cannot be auto-patched. Implement buildOperationsMap 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;
@@ -5727,6 +5774,49 @@ function getExtractor(language) {
 	return extractor;
 }
 //#endregion
+//#region src/engine/manifest-reader.ts
+/**
+* Read the operations map from `.oagen-manifest.json` in the given directory
+* and convert it to `ManifestEntry[]` for the overlay builder.
+*
+* Returns undefined if the manifest is absent or has no operations field.
+*/
+function readManifestSync(dir) {
+	const manifestPath = path$1.join(dir, MANIFEST_FILENAME);
+	if (!existsSync(manifestPath)) return void 0;
+	try {
+		const operations = JSON.parse(readFileSync(manifestPath, "utf-8"))?.operations;
+		if (!operations || typeof operations !== "object") return void 0;
+		return convertOperationsToManifestEntries(operations);
+	} catch {
+		return;
+	}
+}
+/** Convert the operations map from .oagen-manifest.json into ManifestEntry[]. */
+function convertOperationsToManifestEntries(operations) {
+	const entries = [];
+	for (const [httpKey, value] of Object.entries(operations)) {
+		const spaceIdx = httpKey.indexOf(" ");
+		const httpMethod = httpKey.slice(0, spaceIdx);
+		const httpPath = httpKey.slice(spaceIdx + 1);
+		const values = Array.isArray(value) ? value : [value];
+		for (const v of values) {
+			const entry = v;
+			entries.push({
+				operationId: "",
+				sdkResourceProperty: entry.service ?? "",
+				sdkMethodName: entry.sdkMethod ?? "",
+				httpMethod,
+				path: httpPath,
+				pathParams: [],
+				bodyFields: [],
+				queryFields: []
+			});
+		}
+	}
+	return entries;
+}
+//#endregion
 //#region src/cli/overlay-loader.ts
 /**
 * Load an API surface from disk, discover/load the manifest, resolve
@@ -5745,30 +5835,7 @@ function loadOverlayContext(opts) {
 	} catch (err) {
 		throw new ConfigError(`Failed to parse API surface JSON: ${err instanceof Error ? err.message : String(err)}`, `Ensure "${opts.apiSurfacePath}" contains valid JSON. Re-run \`oagen extract\` to regenerate it.`);
 	}
-	let manifest;
-	const resolvedManifestPath = opts.manifestPath ?? path$1.join(opts.outputDir, "smoke-manifest.json");
-	if (opts.manifestPath || existsSync(resolvedManifestPath)) try {
-		const parsed = JSON.parse(readFileSync(resolvedManifestPath, "utf-8"));
-		if (Array.isArray(parsed)) manifest = parsed;
-		else if (typeof parsed === "object" && parsed !== null) manifest = Object.entries(parsed).map(([httpKey, value]) => {
-			const spaceIdx = httpKey.indexOf(" ");
-			const httpMethod = httpKey.slice(0, spaceIdx);
-			const httpPath = httpKey.slice(spaceIdx + 1);
-			const v = value;
-			return {
-				operationId: "",
-				sdkResourceProperty: v.service ?? "",
-				sdkMethodName: v.sdkMethod ?? "",
-				httpMethod,
-				path: httpPath,
-				pathParams: [],
-				bodyFields: [],
-				queryFields: []
-			};
-		});
-	} catch {
-		if (opts.manifestPath) throw new ConfigError(`Failed to read manifest: ${resolvedManifestPath}`, `Verify the manifest file exists and contains valid JSON. If using --manifest, check the path is correct.`);
-	}
+	const manifest = readManifestSync(opts.outputDir);
 	let hints = nodeHints;
 	try {
 		hints = getExtractor(opts.lang).hints;
@@ -5849,7 +5916,6 @@ async function generateCommand(opts) {
 	if (opts.apiSurface && opts.compatCheck !== false) {
 		const ctx = loadOverlayContext({
 			apiSurfacePath: opts.apiSurface,
-			manifestPath: opts.manifest,
 			outputDir: opts.output,
 			lang: opts.lang,
 			spec: ir
@@ -6247,6 +6313,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.
@@ -6412,378 +6799,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 [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 name of Object.keys(candidate.enums)) if (!baseline.enums[name]) additions.push({
-		symbolPath: name,
-		symbolType: "enum"
+	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;
@@ -6798,9 +7416,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
@@ -6808,7 +7429,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",
@@ -6853,37 +7473,9 @@ function cleanGeneratedFiles(dir) {
 		} catch {}
 	}
 }
-/**
-* Load a smoke-manifest.json from the generated SDK directory and convert
-* it to ManifestEntry[] for the overlay builder.
-*/
-function loadManifestFromDir(outputDir) {
-	const manifestPath = path$1.join(outputDir, "smoke-manifest.json");
-	if (!existsSync(manifestPath)) return void 0;
-	try {
-		const parsed = JSON.parse(readFileSync(manifestPath, "utf-8"));
-		if (Array.isArray(parsed)) return parsed;
-		if (typeof parsed === "object" && parsed !== null) return Object.entries(parsed).map(([httpKey, value]) => {
-			const spaceIdx = httpKey.indexOf(" ");
-			const httpMethod = httpKey.slice(0, spaceIdx);
-			const httpPath = httpKey.slice(spaceIdx + 1);
-			const v = value;
-			return {
-				operationId: "",
-				sdkResourceProperty: v.service ?? "",
-				sdkMethodName: v.sdkMethod ?? "",
-				httpMethod,
-				path: httpPath,
-				pathParams: [],
-				bodyFields: [],
-				queryFields: []
-			};
-		});
-	} catch {}
-}
 async function runOverlayRetryLoop(opts) {
 	const { baseline, parsedSpec, outputDir, lang, maxRetries, namespace, onRetry } = opts;
-	let overlay = buildOverlayLookup(baseline, loadManifestFromDir(outputDir), parsedSpec, getExtractor(lang).hints);
+	let overlay = buildOverlayLookup(baseline, readManifestSync(outputDir), parsedSpec, getExtractor(lang).hints);
 	let prevPreserved = -1;
 	const patchedPerIteration = [];
 	for (let attempt = 0; attempt <= maxRetries; attempt++) {
@@ -6900,21 +7492,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);
@@ -7103,17 +7695,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 } : {}
 	};
@@ -7140,9 +7735,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) {
@@ -7174,11 +7772,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");
@@ -7188,9 +7788,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) {
@@ -7272,10 +7891,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",
@@ -7324,7 +7949,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,
@@ -7332,19 +7957,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() {
@@ -7390,8 +8030,8 @@ export const ${`${toCamelCase(lang)}Emitter`}: Emitter = {
     return [];
   },
 
-  generateManifest(_spec: ApiSpec, _ctx: EmitterContext): GeneratedFile[] {
-    return [];
+  buildOperationsMap(_spec: ApiSpec, _ctx: EmitterContext) {
+    return {};
   },
 
   fileHeader(): string {
@@ -7417,7 +8057,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)]
 	];
@@ -7526,12 +8167,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.");
@@ -7553,14 +8212,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;
@@ -7569,11 +8231,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) {
@@ -7582,7 +8245,7 @@ program.command("parse").description("Parse an OpenAPI spec and output IR as JSO
 	}
 	return parseCommand(opts);
 });
-program.command("generate").description("Run a registered emitter against an OpenAPI spec").option("--spec <path>", "Path to OpenAPI spec file (or set OPENAPI_SPEC_PATH)").requiredOption("--lang <language>", "Target language").requiredOption("--output <dir>", "Output directory").option("--target <dir>", "Target directory for live SDK integration (merged output)").option("--namespace <name>", "SDK namespace/package name").option("--dry-run", "Preview files without writing").option("--api-surface <path>", "Path to baseline API surface JSON for compat overlay").option("--manifest <path>", "Path to smoke-manifest.json for method overlay").option("--no-compat-check", "Skip compat overlay even if --api-surface is provided").option("--no-prune", "Skip deletion of stale files recorded in the previous .oagen-manifest.json").action((opts) => {
+program.command("generate").description("Run a registered emitter against an OpenAPI spec").option("--spec <path>", "Path to OpenAPI spec file (or set OPENAPI_SPEC_PATH)").requiredOption("--lang <language>", "Target language").requiredOption("--output <dir>", "Output directory").option("--target <dir>", "Target directory for live SDK integration (merged output)").option("--namespace <name>", "SDK namespace/package name").option("--dry-run", "Preview files without writing").option("--api-surface <path>", "Path to baseline API surface JSON for compat overlay").option("--no-compat-check", "Skip compat overlay even if --api-surface is provided").option("--no-prune", "Skip deletion of stale files recorded in the previous .oagen-manifest.json").action((opts) => {
 	opts.spec ??= process.env.OPENAPI_SPEC_PATH;
 	if (!opts.spec) {
 		console.error("error: --spec <path> or OPENAPI_SPEC_PATH env var is required");
@@ -7609,14 +8272,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) => {