@workos/oagen 0.6.0 → 0.8.0

package/dist/{differ-CG5ZErKl.mjs → overlay-TYxHOCow.mjs}

@@ -1,13 +1,537 @@
 import { A as walkTypeRef, f as toSnakeCase, o as splitWords, x as RegistryError } from "./tree-sitter-C53w_0WE.mjs";
-//#region src/compat/extractor-registry.ts
-const extractors = /* @__PURE__ */ new Map();
-function registerExtractor(extractor) {
-	extractors.set(extractor.language, extractor);
+//#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] };
 }
-function getExtractor(language) {
-	const extractor = extractors.get(language);
-	if (!extractor) throw new RegistryError(`No extractor registered for language: ${language}. Available: ${[...extractors.keys()].join(", ") || "(none)"}`, `Register an extractor for "${language}" via registerExtractor() or add one in your oagen.config.ts plugin.`);
-	return extractor;
+/** Merge user overrides onto language defaults. Only provided keys are overridden. */
+function mergePolicy(defaults, overrides) {
+	return {
+		...defaults,
+		...overrides
+	};
+}
+/** All supported language IDs. */
+const ALL_LANGUAGE_IDS = Object.keys(LANGUAGE_DEFAULTS);
+//#endregion
+//#region src/compat/schema.ts
+/** Current schema version for compatibility snapshots. */
+const COMPAT_SCHEMA_VERSION = "1";
+/** Validate that a parsed snapshot has a compatible schema version. */
+function isCompatibleSchemaVersion(snapshot) {
+	return snapshot.schemaVersion === "1";
+}
+/** 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/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 }
+			});
+		}
+		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 [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 [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 {
+		schemaVersion: "1",
+		source: { extractedAt: surface.extractedAt },
+		policies: getDefaultPolicy(language),
+		symbols
+	};
+}
+/** 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
+		}
+	};
+}
+/** 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/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/language-hints.ts
@@ -157,574 +681,213 @@ function resolveHints(overrides) {
 	};
 }
 //#endregion
-//#region src/compat/overlay.ts
+//#region src/compat/spec-filter.ts
 /**
-* Find the class name that owns a given SDK resource property.
-* E.g. if the surface has a class "Organizations" with property "organizations",
-* and sdkResourceProperty is "organizations", return "Organizations".
+* Compute the set of symbol names that are derivable from the OpenAPI spec.
+* Only these names should be compared during compat verification — everything
+* else in the baseline is hand-written and out of scope for generation.
 */
-function findClassForProperty(surface, sdkResourceProperty, hints) {
-	for (const [className, cls] of Object.entries(surface.classes)) {
-		if (hints.propertyMatchesClass(sdkResourceProperty, className)) return className;
-		for (const [propName, prop] of Object.entries(cls.properties)) if (propName === sdkResourceProperty) {
-			const propType = prop.type;
-			if (propType && surface.classes[propType]) return propType;
-			return;
+function specDerivedNames(spec, hints) {
+	const names = /* @__PURE__ */ new Set();
+	const topLevelEnumNames = new Set(spec.enums.map((e) => e.name));
+	for (const service of spec.services) {
+		names.add(service.name);
+		for (const op of service.operations) {
+			collectTypeRefNames(op.response, names, hints, topLevelEnumNames);
+			if (op.requestBody) collectTypeRefNames(op.requestBody, names, hints, topLevelEnumNames);
+			for (const p of [
+				...op.pathParams,
+				...op.queryParams,
+				...op.headerParams,
+				...op.cookieParams ?? []
+			]) collectTypeRefNames(p.type, names, hints, topLevelEnumNames);
 		}
 	}
-	const propWords = splitWords(sdkResourceProperty).map((w) => w.toLowerCase());
-	if (propWords.length > 1) for (const [className] of Object.entries(surface.classes)) {
-		const classWords = splitWords(className).map((w) => w.toLowerCase());
-		if (classWords.length > 0 && classWords.length < propWords.length) {
-			const suffix = propWords.slice(propWords.length - classWords.length);
-			if (classWords.every((w, i) => w === suffix[i])) return className;
-		}
+	for (const model of spec.models) {
+		names.add(model.name);
+		for (const derived of hints.derivedModelNames(model.name)) names.add(derived);
+		for (const field of model.fields) collectTypeRefNames(field.type, names, hints, topLevelEnumNames);
 	}
+	for (const e of spec.enums) names.add(e.name);
+	return names;
 }
-function buildOverlayLookup(surface, manifest, spec, hints, options) {
-	const resolvedHints = hints ?? nodeHints;
-	const lookup = {
-		methodByOperation: /* @__PURE__ */ new Map(),
-		httpKeyByMethod: /* @__PURE__ */ new Map(),
-		interfaceByName: /* @__PURE__ */ new Map(),
-		typeAliasByName: /* @__PURE__ */ new Map(),
-		requiredExports: /* @__PURE__ */ new Map(),
-		modelNameByIR: /* @__PURE__ */ new Map(),
-		fileBySymbol: /* @__PURE__ */ new Map()
-	};
-	if (manifest) for (const entry of manifest) {
-		const key = `${entry.httpMethod.toUpperCase()} ${entry.path}`;
-		const className = findClassForProperty(surface, entry.sdkResourceProperty, resolvedHints);
-		if (className) {
-			let resolvedMethodName = entry.sdkMethodName;
-			let methods = surface.classes[className]?.methods[resolvedMethodName];
-			if (!methods) {
-				const classMethods = surface.classes[className]?.methods ?? {};
-				const prefix = resolvedMethodName.toLowerCase();
-				const candidates = [];
-				for (const [name, overloads] of Object.entries(classMethods)) if (name.toLowerCase().startsWith(prefix) && name !== resolvedMethodName) candidates.push([name, overloads]);
-				if (candidates.length === 1) {
-					methods = candidates[0][1];
-					resolvedMethodName = candidates[0][0];
-				} else if (candidates.length > 1) {
-					const firstSegment = entry.path.split("/").filter(Boolean)[0]?.replace(/[{}_-]/g, "") ?? "";
-					if (firstSegment) {
-						const segLower = firstSegment.toLowerCase();
-						const segSingular = segLower.endsWith("s") ? segLower.slice(0, -1) : segLower;
-						const best = candidates.find(([name]) => {
-							const lower = name.toLowerCase();
-							return lower === prefix + segLower || lower === prefix + segSingular;
-						});
-						if (best) {
-							methods = best[1];
-							resolvedMethodName = best[0];
-						}
-					}
-					if (!methods) {
-						const verbMatch = disambiguateByHttpVerb(candidates, entry.httpMethod);
-						if (verbMatch) {
-							methods = verbMatch[1];
-							resolvedMethodName = verbMatch[0];
-						}
-					}
-				}
-			}
-			if (!methods) {
-				const classMethods = surface.classes[className]?.methods ?? {};
-				const suffix = resolvedMethodName.toLowerCase();
-				const candidates = [];
-				for (const [name, overloads] of Object.entries(classMethods)) if (name.toLowerCase().endsWith(suffix) && name !== resolvedMethodName) candidates.push([name, overloads]);
-				if (candidates.length === 1) {
-					methods = candidates[0][1];
-					resolvedMethodName = candidates[0][0];
-				}
-			}
-			if (!methods) {
-				const manifestWords = splitCamelCase(resolvedMethodName);
-				if (manifestWords.length >= 2) {
-					const classMethods = surface.classes[className]?.methods ?? {};
-					const candidates = [];
-					for (const [name, overloads] of Object.entries(classMethods)) {
-						if (name === resolvedMethodName) continue;
-						const surfaceWords = splitCamelCase(name);
-						if (surfaceWords.length > manifestWords.length && isSubsequence(manifestWords, surfaceWords)) candidates.push([name, overloads]);
-					}
-					if (candidates.length === 1) {
-						methods = candidates[0][1];
-						resolvedMethodName = candidates[0][0];
-					} else if (candidates.length > 1) {
-						const verbMatch = disambiguateByHttpVerb(candidates, entry.httpMethod);
-						if (verbMatch) {
-							methods = verbMatch[1];
-							resolvedMethodName = verbMatch[0];
-						}
-					}
-				}
-			}
-			if (!methods) {
-				const classMethods = surface.classes[className]?.methods ?? {};
-				const manifestLower = resolvedMethodName.toLowerCase();
-				const candidates = [];
-				for (const [name, overloads] of Object.entries(classMethods)) {
-					if (name === resolvedMethodName) continue;
-					if (manifestLower.startsWith(name.toLowerCase()) && name.length >= 3) candidates.push([name, overloads]);
-				}
-				if (candidates.length === 1) {
-					methods = candidates[0][1];
-					resolvedMethodName = candidates[0][0];
-				} else if (candidates.length > 1) {
-					const verbMatch = disambiguateByHttpVerb(candidates, entry.httpMethod);
-					if (verbMatch) {
-						methods = verbMatch[1];
-						resolvedMethodName = verbMatch[0];
-					}
-				}
-			}
-			const method = methods?.[0];
-			if (method) {
-				lookup.methodByOperation.set(key, {
-					className,
-					methodName: resolvedMethodName,
-					params: method.params,
-					returnType: method.returnType
-				});
-				lookup.httpKeyByMethod.set(`${className}.${resolvedMethodName}`, key);
-			}
-		}
+/**
+* Compute a map of enum name → set of wire values that appear in the spec.
+* Used by filterSurface to exclude hand-added enum members that aren't in the spec.
+*/
+function specDerivedEnumValues(spec) {
+	const result = /* @__PURE__ */ new Map();
+	for (const e of spec.enums) result.set(e.name, new Set(e.values.map((v) => v.value)));
+	return result;
+}
+/**
+* Compute the set of field paths (e.g., "Organization.name") that are defined
+* in the OpenAPI spec's model schemas. Used by filterSurface to exclude
+* hand-added SDK fields that reference spec-derived types.
+*/
+function specDerivedFieldPaths(spec, hints) {
+	const paths = /* @__PURE__ */ new Set();
+	for (const model of spec.models) {
+		for (const field of model.fields) paths.add(`${model.name}.${field.name}`);
+		for (const derived of hints.derivedModelNames(model.name)) for (const field of model.fields) paths.add(`${derived}.${field.name}`);
 	}
-	for (const name of Object.keys(surface.interfaces)) lookup.interfaceByName.set(name, name);
-	for (const name of Object.keys(surface.typeAliases)) lookup.typeAliasByName.set(name, name);
-	for (const [path, symbols] of Object.entries(surface.exports)) lookup.requiredExports.set(path, new Set(symbols));
-	for (const record of [
-		surface.classes,
-		surface.interfaces,
-		surface.typeAliases,
-		surface.enums
-	]) for (const [name, item] of Object.entries(record)) if (item.sourceFile) lookup.fileBySymbol.set(name, item.sourceFile);
-	if (spec) {
-		buildModelNameMap(surface, spec, lookup, resolvedHints, options);
-		for (const [irName, sdkName] of lookup.modelNameByIR) {
-			const filePath = lookup.fileBySymbol.get(sdkName);
-			if (filePath) lookup.fileBySymbol.set(irName, filePath);
-		}
-	}
-	return lookup;
-}
-/** Map HTTP methods to preferred method name prefixes for disambiguation. */
-const HTTP_VERB_PREFIXES = {
-	GET: [
-		"list",
-		"get",
-		"fetch",
-		"retrieve",
-		"find"
-	],
-	POST: [
-		"create",
-		"add",
-		"insert",
-		"send"
-	],
-	PUT: [
-		"set",
-		"update",
-		"replace",
-		"put"
-	],
-	PATCH: [
-		"update",
-		"patch",
-		"modify"
-	],
-	DELETE: [
-		"delete",
-		"remove",
-		"revoke"
-	]
-};
-/**
-* Disambiguate multiple method candidates using HTTP verb semantics.
-* Returns the best match or undefined if no unique match is found.
-*/
-function disambiguateByHttpVerb(candidates, httpMethod) {
-	const prefixes = HTTP_VERB_PREFIXES[httpMethod.toUpperCase()];
-	if (!prefixes) return void 0;
-	const verbCandidates = candidates.filter(([name]) => {
-		const lower = name.toLowerCase();
-		return prefixes.some((p) => lower.startsWith(p));
-	});
-	if (verbCandidates.length === 1) return verbCandidates[0];
-}
-/** Split a camelCase identifier into its word parts (e.g., "getByExternalId" → ["get","By","External","Id"]). */
-function splitCamelCase(name) {
-	const parts = [];
-	let start = 0;
-	for (let i = 1; i < name.length; i++) if (name[i] >= "A" && name[i] <= "Z") {
-		parts.push(name.slice(start, i));
-		start = i;
-	}
-	parts.push(name.slice(start));
-	return parts;
-}
-/** Check if `needle` words form a subsequence of `haystack` words (case-insensitive). */
-function isSubsequence(needle, haystack) {
-	let ni = 0;
-	for (let hi = 0; hi < haystack.length && ni < needle.length; hi++) if (needle[ni].toLowerCase() === haystack[hi].toLowerCase()) ni++;
-	return ni === needle.length;
+	return paths;
 }
 /**
-* Normalize a field name to a canonical form for comparison.
-* Handles camelCase → snake_case so "createdAt" and "created_at" match.
+* Compute the set of method paths (e.g., "SSO.authorize") that are defined
+* as operations in the OpenAPI spec's services. Used by filterSurface to
+* exclude hand-written SDK methods that don't correspond to spec operations.
 */
-function normalizeFieldName(name) {
-	return toSnakeCase(name);
+function specDerivedMethodPaths(spec) {
+	const paths = /* @__PURE__ */ new Set();
+	for (const service of spec.services) for (const op of service.operations) paths.add(`${service.name}.${op.name}`);
+	return paths;
 }
 /**
-* Compute the Jaccard similarity between two sets of normalized field names.
-* Returns score (0–1) and raw intersection count.
+* Compute the set of HTTP operation keys (e.g., "GET /sso/authorize") that
+* exist in the spec. Used for overlay-based method matching.
 */
-function jaccardSimilarity(a, b) {
-	if (a.size === 0 && b.size === 0) return {
-		score: 0,
-		intersection: 0
-	};
-	let intersection = 0;
-	for (const item of a) if (b.has(item)) intersection++;
-	const union = a.size + b.size - intersection;
-	return {
-		score: union === 0 ? 0 : intersection / union,
-		intersection
-	};
+function specDerivedHttpKeys(spec) {
+	const keys = /* @__PURE__ */ new Set();
+	for (const service of spec.services) for (const op of service.operations) keys.add(`${op.httpMethod.toUpperCase()} ${op.path}`);
+	return keys;
 }
-/**
-* Build a set of normalized field names from an IR model.
-*/
-function irModelFieldSignature(model) {
-	return new Set(model.fields.map((f) => normalizeFieldName(f.name)));
+function collectTypeRefNames(ref, out, hints, topLevelEnums) {
+	walkTypeRef(ref, {
+		model: (r) => {
+			out.add(r.name);
+			for (const derived of hints.derivedModelNames(r.name)) out.add(derived);
+		},
+		enum: (r) => {
+			if (!topLevelEnums || topLevelEnums.has(r.name)) out.add(r.name);
+		}
+	});
 }
-/**
-* Build a set of normalized field names from an SDK interface.
-*/
-function sdkInterfaceFieldSignature(iface) {
-	return new Set(Object.keys(iface.fields).map(normalizeFieldName));
+function filterRecord(record, allowed) {
+	const result = {};
+	for (const [name, value] of Object.entries(record)) if (allowed.has(name)) result[name] = value;
+	return result;
 }
 /**
-* Populate the modelNameByIR map using two strategies:
+* Filter an ApiSurface to only include symbols whose names appear in the
+* allowed set. Symbols not in the set are dropped entirely — they won't
+* count toward the total or produce violations.
 *
-* 1. Operation-based matching (high confidence):
-*    When a manifest maps an HTTP operation to an SDK method, extract the
-*    method's return type and parameter types. Match them against the IR
-*    operation's response model and request body model.
+* For interfaces: when fieldPaths is provided, only keeps fields that appear
+* in the spec-derived field paths. This prevents false positives from hand-added
+* SDK fields that reference spec-derived types but aren't defined in the spec.
 *
-* 2. Field-structure matching (fallback):
-*    For IR models not matched by operations, compare their field names
-*    against all SDK interfaces using Jaccard similarity. A match requires
-*    ≥60% field overlap with ≥3 fields in common.
+* For classes: when methodPaths is provided, only keeps methods whose names
+* appear in the spec-derived method paths. This prevents false positives from
+* hand-written SDK methods (e.g., SSO.authorization_url, Webhooks.construct_event)
+* that don't correspond to spec operations. Properties on service classes are
+* also filtered: only UPPER_CASE constants that are spec-derivable are kept.
 */
-function buildModelNameMap(surface, spec, lookup, hints, options) {
-	const mapped = /* @__PURE__ */ new Set();
-	const usedSdkNames = /* @__PURE__ */ new Set();
-	if (lookup.methodByOperation.size > 0) for (const service of spec.services) for (const op of service.operations) {
-		const httpKey = `${op.httpMethod.toUpperCase()} ${op.path}`;
-		const methodOverlay = lookup.methodByOperation.get(httpKey);
-		if (!methodOverlay) continue;
-		if (op.response.kind === "model" && !mapped.has(op.response.name)) {
-			const sdkTypeName = hints.extractReturnTypeName(methodOverlay.returnType);
-			if (sdkTypeName && surface.interfaces[sdkTypeName]) {
-				lookup.modelNameByIR.set(op.response.name, sdkTypeName);
-				mapped.add(op.response.name);
-				usedSdkNames.add(sdkTypeName);
-			}
+function filterSurface(surface, allowedNames, opts) {
+	const { fieldPaths, methodPaths, enumValues } = opts ?? {};
+	const filteredInterfaces = filterRecord(surface.interfaces, allowedNames);
+	if (fieldPaths) for (const [name, iface] of Object.entries(filteredInterfaces)) {
+		const filteredFields = {};
+		for (const [fieldName, field] of Object.entries(iface.fields)) if (fieldPaths.has(`${name}.${fieldName}`)) filteredFields[fieldName] = field;
+		filteredInterfaces[name] = {
+			...iface,
+			fields: filteredFields
+		};
+	}
+	let filteredClasses = filterRecord(surface.classes, allowedNames);
+	if (methodPaths) {
+		const serviceClassNames = /* @__PURE__ */ new Set();
+		for (const path of methodPaths) {
+			const dot = path.indexOf(".");
+			if (dot !== -1) serviceClassNames.add(path.slice(0, dot));
 		}
-		if (op.requestBody?.kind === "model" && !mapped.has(op.requestBody.name)) for (const param of methodOverlay.params) {
-			const sdkTypeName = hints.extractParamTypeName(param.type);
-			if (sdkTypeName && surface.interfaces[sdkTypeName]) {
-				lookup.modelNameByIR.set(op.requestBody.name, sdkTypeName);
-				mapped.add(op.requestBody.name);
-				usedSdkNames.add(sdkTypeName);
-				break;
+		const newClasses = {};
+		for (const [name, cls] of Object.entries(filteredClasses)) if (serviceClassNames.has(name)) {
+			const filteredMethods = {};
+			for (const [methodName, overloads] of Object.entries(cls.methods)) if (methodPaths.has(`${name}.${methodName}`)) filteredMethods[methodName] = overloads;
+			const filteredProperties = {};
+			for (const [propName, prop] of Object.entries(cls.properties)) if (methodPaths.has(`${name}.${propName}`)) filteredProperties[propName] = prop;
+			newClasses[name] = {
+				...cls,
+				methods: filteredMethods,
+				properties: filteredProperties
+			};
+		} else if (fieldPaths) {
+			const filteredProperties = {};
+			for (const [propName, prop] of Object.entries(cls.properties)) if (fieldPaths.has(`${name}.${propName}`)) filteredProperties[propName] = prop;
+			const filteredMethods = {};
+			for (const [methodName, overloads] of Object.entries(cls.methods)) if (fieldPaths.has(`${name}.${methodName}`) || methodPaths.has(`${name}.${methodName}`)) filteredMethods[methodName] = overloads;
+			newClasses[name] = {
+				...cls,
+				methods: filteredMethods,
+				properties: filteredProperties
+			};
+		} else newClasses[name] = cls;
+		filteredClasses = newClasses;
+	}
+	let filteredEnums = filterRecord(surface.enums, allowedNames);
+	if (enumValues) {
+		const newEnums = {};
+		for (const [name, enumDef] of Object.entries(filteredEnums)) {
+			const specValues = enumValues.get(name);
+			if (!specValues) {
+				newEnums[name] = enumDef;
+				continue;
 			}
+			const specValuesLower = new Set([...specValues].map((v) => String(v).toLowerCase()));
+			const filteredMembers = {};
+			for (const [member, value] of Object.entries(enumDef.members)) if (specValues.has(value) || specValuesLower.has(String(value).toLowerCase())) filteredMembers[member] = value;
+			newEnums[name] = {
+				...enumDef,
+				members: filteredMembers
+			};
 		}
+		filteredEnums = newEnums;
 	}
-	const sdkSignatures = [];
-	for (const [name, iface] of Object.entries(surface.interfaces)) {
-		if (usedSdkNames.has(name)) continue;
-		const fields = sdkInterfaceFieldSignature(iface);
-		if (fields.size >= 2) sdkSignatures.push({
-			name,
-			fields,
-			fieldCount: fields.size
-		});
+	return {
+		...surface,
+		classes: filteredClasses,
+		interfaces: filteredInterfaces,
+		typeAliases: filterRecord(surface.typeAliases, allowedNames),
+		enums: filteredEnums,
+		exports: {}
+	};
+}
+//#endregion
+//#region src/compat/differ.ts
+/**
+* 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 sdkSignatureNames = new Set(sdkSignatures.map((s) => s.name));
-	for (const model of spec.models) {
-		if (mapped.has(model.name)) continue;
-		if (model.fields.length < 2) continue;
-		if (sdkSignatureNames.has(model.name) && !usedSdkNames.has(model.name)) {
-			lookup.modelNameByIR.set(model.name, model.name);
-			mapped.add(model.name);
-			usedSdkNames.add(model.name);
-			continue;
-		}
-		const derivedNames = hints.derivedModelNames(model.name);
-		for (const derived of derivedNames) if (sdkSignatureNames.has(derived) && !usedSdkNames.has(derived)) {
-			lookup.modelNameByIR.set(model.name, derived);
-			mapped.add(model.name);
-			usedSdkNames.add(derived);
-			break;
-		}
-		if (mapped.has(model.name)) continue;
-		if (options?.strictModelMatch) continue;
-		const irFields = irModelFieldSignature(model);
-		let bestMatch = null;
-		let bestScore = 0;
-		for (const sdk of sdkSignatures) {
-			if (usedSdkNames.has(sdk.name)) continue;
-			const { score, intersection } = jaccardSimilarity(irFields, sdk.fields);
-			const minIntersection = Math.max(3, Math.ceil(irFields.size * .5));
-			if (score > bestScore && score >= .6 && intersection >= minIntersection) {
-				bestScore = score;
-				bestMatch = sdk.name;
-			}
-		}
-		if (bestMatch) {
-			lookup.modelNameByIR.set(model.name, bestMatch);
-			mapped.add(model.name);
-			usedSdkNames.add(bestMatch);
-		}
+	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));
 	}
-}
-/**
-* Patch overlay with violations 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) {
-	const patched = {
-		methodByOperation: new Map(overlay.methodByOperation),
-		httpKeyByMethod: new Map(overlay.httpKeyByMethod),
-		interfaceByName: new Map(overlay.interfaceByName),
-		typeAliasByName: new Map(overlay.typeAliasByName),
-		requiredExports: new Map(Array.from(overlay.requiredExports.entries()).map(([k, v]) => [k, new Set(v)])),
-		modelNameByIR: new Map(overlay.modelNameByIR),
-		fileBySymbol: new Map(overlay.fileBySymbol)
+	for (const candSym of candidate.symbols) if (!baseByFqName.has(candSym.fqName)) changes.push(classifyAddedSymbol(candSym));
+	return {
+		changes,
+		summary: summarizeChanges(changes)
 	};
-	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
-						});
-					}
-				}
-				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);
-			}
-		}
-	}
-	return patched;
-}
-//#endregion
-//#region src/compat/spec-filter.ts
-/**
-* Compute the set of symbol names that are derivable from the OpenAPI spec.
-* Only these names should be compared during compat verification — everything
-* else in the baseline is hand-written and out of scope for generation.
-*/
-function specDerivedNames(spec, hints) {
-	const names = /* @__PURE__ */ new Set();
-	const topLevelEnumNames = new Set(spec.enums.map((e) => e.name));
-	for (const service of spec.services) {
-		names.add(service.name);
-		for (const op of service.operations) {
-			collectTypeRefNames(op.response, names, hints, topLevelEnumNames);
-			if (op.requestBody) collectTypeRefNames(op.requestBody, names, hints, topLevelEnumNames);
-			for (const p of [
-				...op.pathParams,
-				...op.queryParams,
-				...op.headerParams,
-				...op.cookieParams ?? []
-			]) collectTypeRefNames(p.type, names, hints, topLevelEnumNames);
-		}
-	}
-	for (const model of spec.models) {
-		names.add(model.name);
-		for (const derived of hints.derivedModelNames(model.name)) names.add(derived);
-		for (const field of model.fields) collectTypeRefNames(field.type, names, hints, topLevelEnumNames);
-	}
-	for (const e of spec.enums) names.add(e.name);
-	return names;
-}
-/**
-* Compute a map of enum name → set of wire values that appear in the spec.
-* Used by filterSurface to exclude hand-added enum members that aren't in the spec.
-*/
-function specDerivedEnumValues(spec) {
-	const result = /* @__PURE__ */ new Map();
-	for (const e of spec.enums) result.set(e.name, new Set(e.values.map((v) => v.value)));
-	return result;
-}
-/**
-* Compute the set of field paths (e.g., "Organization.name") that are defined
-* in the OpenAPI spec's model schemas. Used by filterSurface to exclude
-* hand-added SDK fields that reference spec-derived types.
-*/
-function specDerivedFieldPaths(spec, hints) {
-	const paths = /* @__PURE__ */ new Set();
-	for (const model of spec.models) {
-		for (const field of model.fields) paths.add(`${model.name}.${field.name}`);
-		for (const derived of hints.derivedModelNames(model.name)) for (const field of model.fields) paths.add(`${derived}.${field.name}`);
-	}
-	return paths;
-}
-/**
-* Compute the set of method paths (e.g., "SSO.authorize") that are defined
-* as operations in the OpenAPI spec's services. Used by filterSurface to
-* exclude hand-written SDK methods that don't correspond to spec operations.
-*/
-function specDerivedMethodPaths(spec) {
-	const paths = /* @__PURE__ */ new Set();
-	for (const service of spec.services) for (const op of service.operations) paths.add(`${service.name}.${op.name}`);
-	return paths;
-}
-/**
-* Compute the set of HTTP operation keys (e.g., "GET /sso/authorize") that
-* exist in the spec. Used for overlay-based method matching.
-*/
-function specDerivedHttpKeys(spec) {
-	const keys = /* @__PURE__ */ new Set();
-	for (const service of spec.services) for (const op of service.operations) keys.add(`${op.httpMethod.toUpperCase()} ${op.path}`);
-	return keys;
-}
-function collectTypeRefNames(ref, out, hints, topLevelEnums) {
-	walkTypeRef(ref, {
-		model: (r) => {
-			out.add(r.name);
-			for (const derived of hints.derivedModelNames(r.name)) out.add(derived);
-		},
-		enum: (r) => {
-			if (!topLevelEnums || topLevelEnums.has(r.name)) out.add(r.name);
-		}
-	});
-}
-function filterRecord(record, allowed) {
-	const result = {};
-	for (const [name, value] of Object.entries(record)) if (allowed.has(name)) result[name] = value;
-	return result;
 }
 /**
-* Filter an ApiSurface to only include symbols whose names appear in the
-* allowed set. Symbols not in the set are dropped entirely — they won't
-* count toward the total or produce violations.
-*
-* For interfaces: when fieldPaths is provided, only keeps fields that appear
-* in the spec-derived field paths. This prevents false positives from hand-added
-* SDK fields that reference spec-derived types but aren't defined in the spec.
+* Compare two ApiSurface objects and return a DiffResult.
 *
-* For classes: when methodPaths is provided, only keeps methods whose names
-* appear in the spec-derived method paths. This prevents false positives from
-* hand-written SDK methods (e.g., SSO.authorization_url, Webhooks.construct_event)
-* that don't correspond to spec operations. Properties on service classes are
-* also filtered: only UPPER_CASE constants that are spec-derivable are kept.
+* This preserves the existing diffing behavior used by the overlay retry loop,
+* compat check, and all existing tests. The internal implementation uses the
+* same algorithms as before to maintain full backward compatibility with
+* overlay patching and verification workflows.
 */
-function filterSurface(surface, allowedNames, opts) {
-	const { fieldPaths, methodPaths, enumValues } = opts ?? {};
-	const filteredInterfaces = filterRecord(surface.interfaces, allowedNames);
-	if (fieldPaths) for (const [name, iface] of Object.entries(filteredInterfaces)) {
-		const filteredFields = {};
-		for (const [fieldName, field] of Object.entries(iface.fields)) if (fieldPaths.has(`${name}.${fieldName}`)) filteredFields[fieldName] = field;
-		filteredInterfaces[name] = {
-			...iface,
-			fields: filteredFields
-		};
-	}
-	let filteredClasses = filterRecord(surface.classes, allowedNames);
-	if (methodPaths) {
-		const serviceClassNames = /* @__PURE__ */ new Set();
-		for (const path of methodPaths) {
-			const dot = path.indexOf(".");
-			if (dot !== -1) serviceClassNames.add(path.slice(0, dot));
-		}
-		const newClasses = {};
-		for (const [name, cls] of Object.entries(filteredClasses)) if (serviceClassNames.has(name)) {
-			const filteredMethods = {};
-			for (const [methodName, overloads] of Object.entries(cls.methods)) if (methodPaths.has(`${name}.${methodName}`)) filteredMethods[methodName] = overloads;
-			const filteredProperties = {};
-			for (const [propName, prop] of Object.entries(cls.properties)) if (methodPaths.has(`${name}.${propName}`)) filteredProperties[propName] = prop;
-			newClasses[name] = {
-				...cls,
-				methods: filteredMethods,
-				properties: filteredProperties
-			};
-		} else if (fieldPaths) {
-			const filteredProperties = {};
-			for (const [propName, prop] of Object.entries(cls.properties)) if (fieldPaths.has(`${name}.${propName}`)) filteredProperties[propName] = prop;
-			const filteredMethods = {};
-			for (const [methodName, overloads] of Object.entries(cls.methods)) if (fieldPaths.has(`${name}.${methodName}`) || methodPaths.has(`${name}.${methodName}`)) filteredMethods[methodName] = overloads;
-			newClasses[name] = {
-				...cls,
-				methods: filteredMethods,
-				properties: filteredProperties
-			};
-		} else newClasses[name] = cls;
-		filteredClasses = newClasses;
-	}
-	let filteredEnums = filterRecord(surface.enums, allowedNames);
-	if (enumValues) {
-		const newEnums = {};
-		for (const [name, enumDef] of Object.entries(filteredEnums)) {
-			const specValues = enumValues.get(name);
-			if (!specValues) {
-				newEnums[name] = enumDef;
-				continue;
-			}
-			const specValuesLower = new Set([...specValues].map((v) => String(v).toLowerCase()));
-			const filteredMembers = {};
-			for (const [member, value] of Object.entries(enumDef.members)) if (specValues.has(value) || specValuesLower.has(String(value).toLowerCase())) filteredMembers[member] = value;
-			newEnums[name] = {
-				...enumDef,
-				members: filteredMembers
-			};
-		}
-		filteredEnums = newEnums;
-	}
-	return {
-		...surface,
-		classes: filteredClasses,
-		interfaces: filteredInterfaces,
-		typeAliases: filterRecord(surface.typeAliases, allowedNames),
-		enums: filteredEnums,
-		exports: {}
-	};
-}
-//#endregion
-//#region src/compat/differ.ts
 function diffSurfaces(baseline, candidate, hints) {
 	const violations = [];
 	const additions = [];
@@ -1073,12 +1236,6 @@ function diffSurfaces(baseline, candidate, hints) {
 		additions
 	};
 }
-/**
-* 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++) {
@@ -1095,6 +1252,408 @@ function formatSignature(method) {
 	return `(${method.params.map((p) => `${p.name}${p.optional ? "?" : ""}: ${p.type}`).join(", ")}) => ${method.returnType}`;
 }
 //#endregion
-export { registerExtractor as _, specDerivedHttpKeys as a, buildOverlayLookup as c, defaultIsNullableOnlyDifference as d, namedTypeWordsOverlap as f, getExtractor as g, typeExistsInSurface as h, specDerivedFieldPaths as i, patchOverlay as l, resolveHints as m, filterSurface as n, specDerivedMethodPaths as o, nodeHints as p, specDerivedEnumValues as r, specDerivedNames as s, diffSurfaces as t, NAMED_TYPE_RE as u };
+//#region src/compat/extractor-registry.ts
+const extractors = /* @__PURE__ */ new Map();
+function registerExtractor(extractor) {
+	extractors.set(extractor.language, extractor);
+}
+function getExtractor(language) {
+	const extractor = extractors.get(language);
+	if (!extractor) throw new RegistryError(`No extractor registered for language: ${language}. Available: ${[...extractors.keys()].join(", ") || "(none)"}`, `Register an extractor for "${language}" via registerExtractor() or add one in your oagen.config.ts plugin.`);
+	return extractor;
+}
+//#endregion
+//#region src/compat/overlay.ts
+/**
+* Find the class name that owns a given SDK resource property.
+* E.g. if the surface has a class "Organizations" with property "organizations",
+* and sdkResourceProperty is "organizations", return "Organizations".
+*/
+function findClassForProperty(surface, sdkResourceProperty, hints) {
+	for (const [className, cls] of Object.entries(surface.classes)) {
+		if (hints.propertyMatchesClass(sdkResourceProperty, className)) return className;
+		for (const [propName, prop] of Object.entries(cls.properties)) if (propName === sdkResourceProperty) {
+			const propType = prop.type;
+			if (propType && surface.classes[propType]) return propType;
+			return;
+		}
+	}
+	const propWords = splitWords(sdkResourceProperty).map((w) => w.toLowerCase());
+	if (propWords.length > 1) for (const [className] of Object.entries(surface.classes)) {
+		const classWords = splitWords(className).map((w) => w.toLowerCase());
+		if (classWords.length > 0 && classWords.length < propWords.length) {
+			const suffix = propWords.slice(propWords.length - classWords.length);
+			if (classWords.every((w, i) => w === suffix[i])) return className;
+		}
+	}
+}
+function buildOverlayLookup(surface, manifest, spec, hints, options) {
+	const resolvedHints = hints ?? nodeHints;
+	const lookup = {
+		methodByOperation: /* @__PURE__ */ new Map(),
+		httpKeyByMethod: /* @__PURE__ */ new Map(),
+		interfaceByName: /* @__PURE__ */ new Map(),
+		typeAliasByName: /* @__PURE__ */ new Map(),
+		requiredExports: /* @__PURE__ */ new Map(),
+		modelNameByIR: /* @__PURE__ */ new Map(),
+		fileBySymbol: /* @__PURE__ */ new Map()
+	};
+	if (manifest) for (const entry of manifest) {
+		const key = `${entry.httpMethod.toUpperCase()} ${entry.path}`;
+		const className = findClassForProperty(surface, entry.sdkResourceProperty, resolvedHints);
+		if (className) {
+			let resolvedMethodName = entry.sdkMethodName;
+			let methods = surface.classes[className]?.methods[resolvedMethodName];
+			if (!methods) {
+				const classMethods = surface.classes[className]?.methods ?? {};
+				const prefix = resolvedMethodName.toLowerCase();
+				const candidates = [];
+				for (const [name, overloads] of Object.entries(classMethods)) if (name.toLowerCase().startsWith(prefix) && name !== resolvedMethodName) candidates.push([name, overloads]);
+				if (candidates.length === 1) {
+					methods = candidates[0][1];
+					resolvedMethodName = candidates[0][0];
+				} else if (candidates.length > 1) {
+					const firstSegment = entry.path.split("/").filter(Boolean)[0]?.replace(/[{}_-]/g, "") ?? "";
+					if (firstSegment) {
+						const segLower = firstSegment.toLowerCase();
+						const segSingular = segLower.endsWith("s") ? segLower.slice(0, -1) : segLower;
+						const best = candidates.find(([name]) => {
+							const lower = name.toLowerCase();
+							return lower === prefix + segLower || lower === prefix + segSingular;
+						});
+						if (best) {
+							methods = best[1];
+							resolvedMethodName = best[0];
+						}
+					}
+					if (!methods) {
+						const verbMatch = disambiguateByHttpVerb(candidates, entry.httpMethod);
+						if (verbMatch) {
+							methods = verbMatch[1];
+							resolvedMethodName = verbMatch[0];
+						}
+					}
+				}
+			}
+			if (!methods) {
+				const classMethods = surface.classes[className]?.methods ?? {};
+				const suffix = resolvedMethodName.toLowerCase();
+				const candidates = [];
+				for (const [name, overloads] of Object.entries(classMethods)) if (name.toLowerCase().endsWith(suffix) && name !== resolvedMethodName) candidates.push([name, overloads]);
+				if (candidates.length === 1) {
+					methods = candidates[0][1];
+					resolvedMethodName = candidates[0][0];
+				}
+			}
+			if (!methods) {
+				const manifestWords = splitCamelCase(resolvedMethodName);
+				if (manifestWords.length >= 2) {
+					const classMethods = surface.classes[className]?.methods ?? {};
+					const candidates = [];
+					for (const [name, overloads] of Object.entries(classMethods)) {
+						if (name === resolvedMethodName) continue;
+						const surfaceWords = splitCamelCase(name);
+						if (surfaceWords.length > manifestWords.length && isSubsequence(manifestWords, surfaceWords)) candidates.push([name, overloads]);
+					}
+					if (candidates.length === 1) {
+						methods = candidates[0][1];
+						resolvedMethodName = candidates[0][0];
+					} else if (candidates.length > 1) {
+						const verbMatch = disambiguateByHttpVerb(candidates, entry.httpMethod);
+						if (verbMatch) {
+							methods = verbMatch[1];
+							resolvedMethodName = verbMatch[0];
+						}
+					}
+				}
+			}
+			if (!methods) {
+				const classMethods = surface.classes[className]?.methods ?? {};
+				const manifestLower = resolvedMethodName.toLowerCase();
+				const candidates = [];
+				for (const [name, overloads] of Object.entries(classMethods)) {
+					if (name === resolvedMethodName) continue;
+					if (manifestLower.startsWith(name.toLowerCase()) && name.length >= 3) candidates.push([name, overloads]);
+				}
+				if (candidates.length === 1) {
+					methods = candidates[0][1];
+					resolvedMethodName = candidates[0][0];
+				} else if (candidates.length > 1) {
+					const verbMatch = disambiguateByHttpVerb(candidates, entry.httpMethod);
+					if (verbMatch) {
+						methods = verbMatch[1];
+						resolvedMethodName = verbMatch[0];
+					}
+				}
+			}
+			const method = methods?.[0];
+			if (method) {
+				lookup.methodByOperation.set(key, {
+					className,
+					methodName: resolvedMethodName,
+					params: method.params,
+					returnType: method.returnType
+				});
+				lookup.httpKeyByMethod.set(`${className}.${resolvedMethodName}`, key);
+			}
+		}
+	}
+	for (const name of Object.keys(surface.interfaces)) lookup.interfaceByName.set(name, name);
+	for (const name of Object.keys(surface.typeAliases)) lookup.typeAliasByName.set(name, name);
+	for (const [path, symbols] of Object.entries(surface.exports)) lookup.requiredExports.set(path, new Set(symbols));
+	for (const record of [
+		surface.classes,
+		surface.interfaces,
+		surface.typeAliases,
+		surface.enums
+	]) for (const [name, item] of Object.entries(record)) if (item.sourceFile) lookup.fileBySymbol.set(name, item.sourceFile);
+	if (spec) {
+		buildModelNameMap(surface, spec, lookup, resolvedHints, options);
+		for (const [irName, sdkName] of lookup.modelNameByIR) {
+			const filePath = lookup.fileBySymbol.get(sdkName);
+			if (filePath) lookup.fileBySymbol.set(irName, filePath);
+		}
+	}
+	return lookup;
+}
+/** Map HTTP methods to preferred method name prefixes for disambiguation. */
+const HTTP_VERB_PREFIXES = {
+	GET: [
+		"list",
+		"get",
+		"fetch",
+		"retrieve",
+		"find"
+	],
+	POST: [
+		"create",
+		"add",
+		"insert",
+		"send"
+	],
+	PUT: [
+		"set",
+		"update",
+		"replace",
+		"put"
+	],
+	PATCH: [
+		"update",
+		"patch",
+		"modify"
+	],
+	DELETE: [
+		"delete",
+		"remove",
+		"revoke"
+	]
+};
+/**
+* Disambiguate multiple method candidates using HTTP verb semantics.
+* Returns the best match or undefined if no unique match is found.
+*/
+function disambiguateByHttpVerb(candidates, httpMethod) {
+	const prefixes = HTTP_VERB_PREFIXES[httpMethod.toUpperCase()];
+	if (!prefixes) return void 0;
+	const verbCandidates = candidates.filter(([name]) => {
+		const lower = name.toLowerCase();
+		return prefixes.some((p) => lower.startsWith(p));
+	});
+	if (verbCandidates.length === 1) return verbCandidates[0];
+}
+/** Split a camelCase identifier into its word parts (e.g., "getByExternalId" → ["get","By","External","Id"]). */
+function splitCamelCase(name) {
+	const parts = [];
+	let start = 0;
+	for (let i = 1; i < name.length; i++) if (name[i] >= "A" && name[i] <= "Z") {
+		parts.push(name.slice(start, i));
+		start = i;
+	}
+	parts.push(name.slice(start));
+	return parts;
+}
+/** Check if `needle` words form a subsequence of `haystack` words (case-insensitive). */
+function isSubsequence(needle, haystack) {
+	let ni = 0;
+	for (let hi = 0; hi < haystack.length && ni < needle.length; hi++) if (needle[ni].toLowerCase() === haystack[hi].toLowerCase()) ni++;
+	return ni === needle.length;
+}
+/**
+* Normalize a field name to a canonical form for comparison.
+* Handles camelCase → snake_case so "createdAt" and "created_at" match.
+*/
+function normalizeFieldName(name) {
+	return toSnakeCase(name);
+}
+/**
+* Compute the Jaccard similarity between two sets of normalized field names.
+* Returns score (0–1) and raw intersection count.
+*/
+function jaccardSimilarity(a, b) {
+	if (a.size === 0 && b.size === 0) return {
+		score: 0,
+		intersection: 0
+	};
+	let intersection = 0;
+	for (const item of a) if (b.has(item)) intersection++;
+	const union = a.size + b.size - intersection;
+	return {
+		score: union === 0 ? 0 : intersection / union,
+		intersection
+	};
+}
+/**
+* Build a set of normalized field names from an IR model.
+*/
+function irModelFieldSignature(model) {
+	return new Set(model.fields.map((f) => normalizeFieldName(f.name)));
+}
+/**
+* Build a set of normalized field names from an SDK interface.
+*/
+function sdkInterfaceFieldSignature(iface) {
+	return new Set(Object.keys(iface.fields).map(normalizeFieldName));
+}
+/**
+* Populate the modelNameByIR map using two strategies:
+*
+* 1. Operation-based matching (high confidence):
+*    When a manifest maps an HTTP operation to an SDK method, extract the
+*    method's return type and parameter types. Match them against the IR
+*    operation's response model and request body model.
+*
+* 2. Field-structure matching (fallback):
+*    For IR models not matched by operations, compare their field names
+*    against all SDK interfaces using Jaccard similarity. A match requires
+*    ≥60% field overlap with ≥3 fields in common.
+*/
+function buildModelNameMap(surface, spec, lookup, hints, options) {
+	const mapped = /* @__PURE__ */ new Set();
+	const usedSdkNames = /* @__PURE__ */ new Set();
+	if (lookup.methodByOperation.size > 0) for (const service of spec.services) for (const op of service.operations) {
+		const httpKey = `${op.httpMethod.toUpperCase()} ${op.path}`;
+		const methodOverlay = lookup.methodByOperation.get(httpKey);
+		if (!methodOverlay) continue;
+		if (op.response.kind === "model" && !mapped.has(op.response.name)) {
+			const sdkTypeName = hints.extractReturnTypeName(methodOverlay.returnType);
+			if (sdkTypeName && surface.interfaces[sdkTypeName]) {
+				lookup.modelNameByIR.set(op.response.name, sdkTypeName);
+				mapped.add(op.response.name);
+				usedSdkNames.add(sdkTypeName);
+			}
+		}
+		if (op.requestBody?.kind === "model" && !mapped.has(op.requestBody.name)) for (const param of methodOverlay.params) {
+			const sdkTypeName = hints.extractParamTypeName(param.type);
+			if (sdkTypeName && surface.interfaces[sdkTypeName]) {
+				lookup.modelNameByIR.set(op.requestBody.name, sdkTypeName);
+				mapped.add(op.requestBody.name);
+				usedSdkNames.add(sdkTypeName);
+				break;
+			}
+		}
+	}
+	const sdkSignatures = [];
+	for (const [name, iface] of Object.entries(surface.interfaces)) {
+		if (usedSdkNames.has(name)) continue;
+		const fields = sdkInterfaceFieldSignature(iface);
+		if (fields.size >= 2) sdkSignatures.push({
+			name,
+			fields,
+			fieldCount: fields.size
+		});
+	}
+	const sdkSignatureNames = new Set(sdkSignatures.map((s) => s.name));
+	for (const model of spec.models) {
+		if (mapped.has(model.name)) continue;
+		if (model.fields.length < 2) continue;
+		if (sdkSignatureNames.has(model.name) && !usedSdkNames.has(model.name)) {
+			lookup.modelNameByIR.set(model.name, model.name);
+			mapped.add(model.name);
+			usedSdkNames.add(model.name);
+			continue;
+		}
+		const derivedNames = hints.derivedModelNames(model.name);
+		for (const derived of derivedNames) if (sdkSignatureNames.has(derived) && !usedSdkNames.has(derived)) {
+			lookup.modelNameByIR.set(model.name, derived);
+			mapped.add(model.name);
+			usedSdkNames.add(derived);
+			break;
+		}
+		if (mapped.has(model.name)) continue;
+		if (options?.strictModelMatch) continue;
+		const irFields = irModelFieldSignature(model);
+		let bestMatch = null;
+		let bestScore = 0;
+		for (const sdk of sdkSignatures) {
+			if (usedSdkNames.has(sdk.name)) continue;
+			const { score, intersection } = jaccardSimilarity(irFields, sdk.fields);
+			const minIntersection = Math.max(3, Math.ceil(irFields.size * .5));
+			if (score > bestScore && score >= .6 && intersection >= minIntersection) {
+				bestScore = score;
+				bestMatch = sdk.name;
+			}
+		}
+		if (bestMatch) {
+			lookup.modelNameByIR.set(model.name, bestMatch);
+			mapped.add(model.name);
+			usedSdkNames.add(bestMatch);
+		}
+	}
+}
+/** 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 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, changes, baseline) {
+	const patched = {
+		methodByOperation: new Map(overlay.methodByOperation),
+		httpKeyByMethod: new Map(overlay.httpKeyByMethod),
+		interfaceByName: new Map(overlay.interfaceByName),
+		typeAliasByName: new Map(overlay.typeAliasByName),
+		requiredExports: new Map(Array.from(overlay.requiredExports.entries()).map(([k, v]) => [k, new Set(v)])),
+		modelNameByIR: new Map(overlay.modelNameByIR),
+		fileBySymbol: new Map(overlay.fileBySymbol)
+	};
+	let warnedManifest = false;
+	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);
+		}
+	}
+	return patched;
+}
+//#endregion
+export { getDefaultPolicy as A, defaultSeverityForCategory as C, isCompatibleSchemaVersion as D, COMPAT_SCHEMA_VERSION as E, validateSnapshot as O, summarizeChanges as S, apiSurfaceToSnapshot as T, nodeHints as _, registerExtractor as a, classifyAddedSymbol as b, filterSurface as c, specDerivedHttpKeys as d, specDerivedMethodPaths as f, namedTypeWordsOverlap as g, defaultIsNullableOnlyDifference as h, getExtractor as i, mergePolicy as j, ALL_LANGUAGE_IDS as k, specDerivedEnumValues as l, NAMED_TYPE_RE as m, isPatchableChange as n, diffSnapshots as o, specDerivedNames as p, patchOverlay as r, diffSurfaces as s, buildOverlayLookup as t, specDerivedFieldPaths as u, resolveHints as v, severityMeetsThreshold as w, classifySymbolChanges as x, typeExistsInSurface as y };
 
-//# sourceMappingURL=differ-CG5ZErKl.mjs.map
+//# sourceMappingURL=overlay-TYxHOCow.mjs.map