@workos/oagen 0.29.1 → 0.29.3

package/dist/cli/index.mjs

@@ -2013,6 +2013,30 @@ function extractInlineModel(name, schema) {
 }
 //#endregion
 //#region src/parser/operations.ts
+/**
+* Resolve a raw parameter entry to a concrete Parameter Object, following
+* `$ref`s into `components/parameters` when present. Follows chains of refs
+* (a component that itself is a `$ref` to another component), with a cycle
+* guard for a spec that refs itself.
+*
+* Throws when a `$ref` can't be resolved so a malformed spec fails loudly at
+* parse time instead of silently losing the parameter (see `extractParams`,
+* which used to drop any entry with no `in` field — every `$ref` object has
+* none).
+*/
+function resolveParameterRef(raw, componentParameters, operationContext) {
+	const seenRefs = /* @__PURE__ */ new Set();
+	let current = raw;
+	while ("$ref" in current) {
+		if (seenRefs.has(current.$ref)) throw new Error(`Circular parameter $ref chain starting at "${current.$ref}" in ${operationContext}.`);
+		seenRefs.add(current.$ref);
+		const refName = /^#\/components\/parameters\/(.+)$/.exec(current.$ref)?.[1].replace(/~1/g, "/").replace(/~0/g, "~");
+		const resolved = refName ? componentParameters?.[refName] : void 0;
+		if (!resolved) throw new Error(`Unresolved parameter $ref "${current.$ref}" in ${operationContext}: no matching entry under components/parameters.`);
+		current = resolved;
+	}
+	return current;
+}
 const HTTP_METHODS = [
 	"get",
 	"post",
@@ -2023,7 +2047,7 @@ const HTTP_METHODS = [
 	"options",
 	"trace"
 ];
-function extractOperations(paths, operationIdTransform, componentSchemas) {
+function extractOperations(paths, operationIdTransform, componentSchemas, componentParameters) {
 	if (!paths) return {
 		services: [],
 		inlineModels: []
@@ -2036,7 +2060,7 @@ function extractOperations(paths, operationIdTransform, componentSchemas) {
 			const op = pathItem[method];
 			if (!op) continue;
 			const serviceName = inferServiceName(path, op.tags?.[0]);
-			const { operation, inlineModels: opModels } = buildOperation(method, path, op, pathLevelParams, operationIdTransform, serviceName, componentSchemas);
+			const { operation, inlineModels: opModels } = buildOperation(method, path, op, pathLevelParams, operationIdTransform, serviceName, componentSchemas, componentParameters);
 			inlineModels.push(...opModels);
 			const ops = serviceMap.get(serviceName) ?? [];
 			ops.push(operation);
@@ -2234,19 +2258,11 @@ function extractParameterGroups(op, allIRParams, operationContext) {
 * the request body. Emitters use the group's presence to generate sum-type
 * interfaces and custom JSON marshalling instead of flat optional fields.
 */
-function extractBodyParameterGroups(op, operationContext) {
+function extractBodyParameterGroups(op, operationContext, componentSchemas) {
 	const raw = op["x-mutually-exclusive-body-groups"];
 	if (!raw || typeof raw !== "object") return void 0;
 	const bodySchema = op.requestBody?.content?.["application/json"]?.schema;
-	const variantFieldSchemas = /* @__PURE__ */ new Map();
-	if (bodySchema) {
-		for (const sub of bodySchema.allOf ?? []) for (const variant of sub.oneOf ?? []) if (variant.properties) {
-			for (const [name, fieldSchema] of Object.entries(variant.properties)) if (fieldSchema) variantFieldSchemas.set(name, fieldSchema);
-		}
-		for (const variant of bodySchema.oneOf ?? []) if (variant.properties) {
-			for (const [name, fieldSchema] of Object.entries(variant.properties)) if (fieldSchema) variantFieldSchemas.set(name, fieldSchema);
-		}
-	}
+	const variantFieldSchemas = collectVariantFieldSchemas(bodySchema, componentSchemas);
 	const groups = [];
 	for (const [groupName, groupDef] of Object.entries(raw)) {
 		if (!groupDef || typeof groupDef !== "object") continue;
@@ -2256,10 +2272,12 @@ function extractBodyParameterGroups(op, operationContext) {
 		const variants = Object.entries(groupDef.variants).map(([variantName, paramNames]) => {
 			if (!Array.isArray(paramNames) || paramNames.length === 0) throw new Error(`Malformed x-mutually-exclusive-body-groups.${groupName}.variants.${variantName} in ${operationContext}: expected a non-empty array of parameter names.`);
 			const parameters = paramNames.map((pName) => {
-				const fieldSchema = variantFieldSchemas.get(pName);
+				const entry = variantFieldSchemas.get(pName);
+				const fieldSchema = entry?.schema;
+				if (!fieldSchema) console.warn(`[oagen] Warning: x-mutually-exclusive-body-groups.${groupName}.variants.${variantName} references "${pName}" in ${operationContext}, but no oneOf branch of the request body declares that property. Falling back to type: string.`);
 				return {
 					name: pName,
-					type: fieldSchema ? schemaToTypeRef(fieldSchema, toPascalCase(pName)) : {
+					type: fieldSchema ? schemaToTypeRef(fieldSchema, toPascalCase(pName), entry?.owner) : {
 						kind: "primitive",
 						type: "string"
 					},
@@ -2283,8 +2301,14 @@ function extractBodyParameterGroups(op, operationContext) {
 	}
 	return groups.length > 0 ? groups : void 0;
 }
-function buildOperation(method, path, op, pathLevelParams, operationIdTransform, serviceName, componentSchemas) {
-	const allParams = [...pathLevelParams, ...op.parameters ?? []];
+function buildOperation(method, path, op, pathLevelParams, operationIdTransform, serviceName, componentSchemas, componentParameters) {
+	const opLabel = op.operationId ?? `${method.toUpperCase()} ${path}`;
+	const paramsByIdentity = /* @__PURE__ */ new Map();
+	for (const raw of [...pathLevelParams, ...op.parameters ?? []]) {
+		const param = resolveParameterRef(raw, componentParameters, opLabel);
+		paramsByIdentity.set(`${param.in}:${param.name}`, param);
+	}
+	const allParams = [...paramsByIdentity.values()];
 	const hasIdempotencyHeader = allParams.some((p) => p.in === "header" && p.name.toLowerCase() === "idempotency-key");
 	const opContext = serviceName;
 	const pathParams = extractParams(allParams, "path", opContext, componentSchemas);
@@ -2308,15 +2332,13 @@ function buildOperation(method, path, op, pathLevelParams, operationIdTransform,
 		};
 	} else if (paginationFromParams) pagination = paginationFromParams;
 	const security = extractOperationSecurity(op.security);
-	const allIRParams = [
+	const queryParamGroups = extractParameterGroups(op, [
 		...pathParams,
 		...queryParams,
 		...headerParams,
 		...cookieParams
-	];
-	const opLabel = op.operationId ?? `${method.toUpperCase()} ${path}`;
-	const queryParamGroups = extractParameterGroups(op, allIRParams, opLabel);
-	const bodyParamGroups = extractBodyParameterGroups(op, opLabel);
+	], opLabel);
+	const bodyParamGroups = extractBodyParameterGroups(op, opLabel, componentSchemas);
 	const parameterGroups = queryParamGroups || bodyParamGroups ? [...queryParamGroups ?? [], ...bodyParamGroups ?? []] : void 0;
 	return {
 		operation: {
@@ -2399,6 +2421,55 @@ function resolveParamSchemaRef(schema, componentSchemas) {
 	if (!match) return void 0;
 	return componentSchemas[match[1]];
 }
+/**
+* Collect the property schemas of every `oneOf` branch reachable from a request
+* body schema, keyed by property name. These are the candidate members of a
+* mutually-exclusive body group.
+*
+* The bundler runs with `dereference: false`, so the body schema is very often
+* a bare `{ $ref: '#/components/schemas/XDto' }` and the `allOf`/`oneOf`
+* composition that actually declares the variant properties lives on the
+* component. Walking without resolving refs finds nothing, and every group
+* member then falls back to `string` — an SDK that compiles but types
+* object-valued members (e.g. a connection's `saml_options`) as plain strings.
+*
+* Composition keywords nest and may themselves be refs, so resolve and recurse
+* at each level. `seen` guards against a schema that (directly or transitively)
+* refs itself.
+*/
+function collectVariantFieldSchemas(schema, componentSchemas, owner = void 0, out = /* @__PURE__ */ new Map(), seen = /* @__PURE__ */ new Set()) {
+	if (!schema) return out;
+	const ref = schema.$ref;
+	if (ref) {
+		if (seen.has(ref)) return out;
+		seen.add(ref);
+		const match = /^#\/components\/schemas\/(.+)$/.exec(ref);
+		return collectVariantFieldSchemas(match && componentSchemas ? componentSchemas[match[1]] : void 0, componentSchemas, match ? resolveSchemaName(match[1]) : owner, out, seen);
+	}
+	for (const variant of schema.oneOf ?? []) {
+		const variantRef = variant.$ref;
+		const refMatch = variantRef ? /^#\/components\/schemas\/(.+)$/.exec(variantRef) : null;
+		const resolved = resolveSchemaRefObject(variant, componentSchemas) ?? variant;
+		const variantOwner = refMatch ? resolveSchemaName(refMatch[1]) : owner;
+		for (const [name, fieldSchema] of Object.entries(resolved.properties ?? {})) if (fieldSchema) out.set(name, {
+			schema: fieldSchema,
+			owner: variantOwner
+		});
+		collectVariantFieldSchemas(variant, componentSchemas, owner, out, seen);
+	}
+	for (const sub of schema.allOf ?? []) collectVariantFieldSchemas(sub, componentSchemas, owner, out, seen);
+	for (const sub of schema.anyOf ?? []) collectVariantFieldSchemas(sub, componentSchemas, owner, out, seen);
+	return out;
+}
+/** Resolve `{ $ref: '#/components/schemas/X' }` to its component, else undefined. */
+function resolveSchemaRefObject(schema, componentSchemas) {
+	if (!schema || !componentSchemas) return void 0;
+	const ref = schema.$ref;
+	if (!ref) return void 0;
+	const match = /^#\/components\/schemas\/(.+)$/.exec(ref);
+	if (!match) return void 0;
+	return componentSchemas[match[1]];
+}
 function extractRequestBody(body, op, inlineModels) {
 	if (!body?.content) return {};
 	let encoding = "json";
@@ -2811,6 +2882,262 @@ function collectInlineEnumsFromOperations(services, enums) {
 	]) collectInlineEnumFromRef(param.type, enums, enumNames);
 }
 //#endregion
+//#region src/parser/parameter-group-names.ts
+/**
+* Assign `ParameterGroup.wrapperName` across the whole spec.
+*
+* Emitters derive a group's generated wrapper type name from the group name
+* alone, so two operations sharing a group name (create and update both
+* declare `protocol_options`) collapse onto a single type. That is only sound
+* while the two declarations carry the same members. Where they differ, one
+* operation ends up typed with the other's member — e.g. a connection update
+* forced to pass `CreateConnectionSAMLOptions`, which accepts three fields the
+* PATCH endpoint rejects.
+*
+* This pass fingerprints every group's members structurally and qualifies the
+* wrapper name with the operation name only for groups that genuinely diverge.
+* Groups whose declarations agree keep the bare group name, so wrapper types
+* already published in the SDKs are never renamed.
+*/
+function assignParameterGroupWrapperNames(spec) {
+	const modelMap = new Map(spec.models.map((m) => [m.name, m]));
+	const enumMap = new Map(spec.enums.map((e) => [e.name, e]));
+	const fingerprints = /* @__PURE__ */ new Map();
+	const occurrences = [];
+	for (const service of spec.services) for (const op of service.operations) for (const group of op.parameterGroups ?? []) {
+		const fp = fingerprintGroup(group, modelMap, enumMap);
+		let seen = fingerprints.get(group.name);
+		if (!seen) {
+			seen = /* @__PURE__ */ new Set();
+			fingerprints.set(group.name, seen);
+		}
+		seen.add(fp);
+		occurrences.push({
+			service,
+			op,
+			group,
+			fingerprint: fp
+		});
+	}
+	for (const { op, group } of occurrences) group.wrapperName = (fingerprints.get(group.name)?.size ?? 0) > 1 ? `${op.name}_${group.name}` : group.name;
+	qualifyResidualCollisions(occurrences);
+	reconcileSharedGroups(occurrences.map((o) => o.group));
+}
+/**
+* Break the collisions the operation-qualified name can still leave behind.
+*
+* `${op.name}_${group.name}` is not a unique key, for two separate reasons:
+*
+*  - `disambiguateOperationNames` makes operation names unique only *within* a
+*    service, so two services that each own an operation named `create`, both
+*    declaring a `password` group with different members, both land on
+*    `create_password`.
+*  - Within one service it deliberately leaves same-name operations alone when
+*    they share a path (see the `uniquePaths.size <= 1` guard — "same path,
+*    different methods"), so `PUT` and `PATCH` on one path both stay `update`
+*    and a service prefix alone still produces one name for both.
+*
+* Either way `reconcileSharedGroups` would then fuse two incompatible
+* declarations into a single type — the exact failure this pass exists to
+* prevent — and it does not drop the surplus member, so the wrapper would
+* expose a field one of the operations rejects.
+*
+* So escalate in rounds, adding a qualifier at a time and re-testing what still
+* collides. `(service, path, method)` identifies an operation uniquely, and a
+* same-name collision within a service implies a shared path, so service then
+* method is sufficient to separate every case.
+*
+* Each round only touches names that *still* group differing fingerprints, so a
+* name whose sharers agree is never renamed: sharing one wrapper is exactly what
+* should happen there, and renaming it would move a type the SDKs already
+* publish. On a spec where no qualified name collides — the WorkOS spec today —
+* the whole pass is a no-op.
+*/
+function qualifyResidualCollisions(occurrences) {
+	const qualifiers = [(o) => o.service.name, (o) => o.op.httpMethod];
+	for (const qualify of qualifiers) for (const sharers of collidingCandidates(occurrences)) {
+		const movable = sharers.filter((o) => o.group.wrapperName !== o.group.name);
+		for (const o of movable) o.group.wrapperName = `${qualify(o)}_${o.group.wrapperName ?? o.group.name}`;
+	}
+	separateRemainingByStructure(occurrences);
+}
+/**
+* Terminal round: separate whatever the operation attributes could not.
+*
+* No combination of operation attributes is unique by construction. Two
+* operations in one service can share a name, a method *and* differ only by
+* path — `normalizeOperationIdForNaming` strips the `[N]` suffix, so a NestJS
+* controller method bound to several routes derives one name for all of them.
+* The WorkOS spec already contains such a pair (`Authorization`'s
+* `listRoleAssignments` on two paths); it declares no parameter groups today,
+* so nothing is wrong in the SDKs, but the shape is present rather than
+* hypothetical. Adding `path` as a fourth qualifier would only move the
+* boundary again.
+*
+* So stop enumerating attributes and separate by the thing that actually
+* matters: a name still fusing distinct structures gets one wrapper per
+* distinct fingerprint. That makes "same `wrapperName` implies same structure"
+* hold unconditionally, which is the invariant every emitter relies on.
+*
+* Suffixes are keyed on the fingerprint, not on a per-occurrence counter, so
+* declarations that agree keep sharing a wrapper.
+*
+* Ordering is by first appearance, not by sorted fingerprint: the structure
+* declared first keeps the unsuffixed name. Sorting by fingerprint would be
+* equally deterministic but less stable in the way that matters — adding a
+* member to one operation changes its fingerprint and could swap which of two
+* published wrappers holds the bare name. Under first-appearance order only
+* reordering the operations themselves can shift a name, which is both rarer
+* and visible in the spec diff.
+*
+* Either way this is a no-op wherever an earlier round already sufficed —
+* including the WorkOS spec, which never reaches this round at all.
+*/
+function separateRemainingByStructure(occurrences) {
+	const taken = new Set(occurrences.map((o) => o.group.wrapperName ?? o.group.name));
+	for (const sharers of collidingCandidates(occurrences)) {
+		const base = sharers[0].group.wrapperName ?? sharers[0].group.name;
+		const nameFor = /* @__PURE__ */ new Map();
+		let n = 2;
+		for (const o of sharers) {
+			if (nameFor.has(o.fingerprint)) continue;
+			if (nameFor.size === 0) {
+				nameFor.set(o.fingerprint, base);
+				continue;
+			}
+			while (taken.has(`${base}_${n}`)) n++;
+			const name = `${base}_${n}`;
+			taken.add(name);
+			nameFor.set(o.fingerprint, name);
+			n++;
+		}
+		for (const o of sharers) o.group.wrapperName = nameFor.get(o.fingerprint);
+	}
+}
+/**
+* Candidate wrapper names shared by declarations that do not agree — the only
+* ones an escalation round may rename.
+*/
+function collidingCandidates(occurrences) {
+	const byCandidate = /* @__PURE__ */ new Map();
+	for (const o of occurrences) {
+		const key = o.group.wrapperName ?? o.group.name;
+		const list = byCandidate.get(key);
+		if (list) list.push(o);
+		else byCandidate.set(key, [o]);
+	}
+	return [...byCandidate.values()].filter((sharers) => sharers.length > 1 && new Set(sharers.map((o) => o.fingerprint)).size > 1);
+}
+/**
+* Make every group that shares a `wrapperName` describe literally the same
+* type.
+*
+* Deciding two declarations may share one wrapper is only half the job. The
+* fingerprint deliberately ignores nullability and member order, so sharers can
+* still disagree on both — and each emitter renders the wrapper from whichever
+* operation it happens to reach first while rendering call sites from their own
+* operation. Kotlin showed the consequence: `ParentResource.ById.id` emitted as
+* `String` from one operation, while the Java-friendly overload built from
+* another passed a `String?` into it, and the SDK stopped compiling.
+*
+* So normalize the two axes the fingerprint waived:
+*   - a member the sharers disagree on settles as non-nullable. Widening to
+*     nullable instead reads as the friendlier choice, but the nullable form
+*     doesn't survive every emitter's group paths (Kotlin's query dispatch
+*     builds a `Pair<String, String>` from the member, which a `String?` can't
+*     satisfy), and non-nullable is what all sharers carried before group
+*     member types were resolved at all — so it changes no published surface.
+*     A member every sharer agrees is nullable stays nullable.
+*
+*     The cost: an operation whose spec really does accept null for a member
+*     (`PATCH` on a resource may clear `parent_resource_id`) can't express that
+*     through the shared wrapper. It never could — the member used to be a flat
+*     `string` everywhere — so nothing regresses, but the limitation is real and
+*     removing it means letting that group's wrapper split per operation.
+*   - member order follows the first sharer, so positional constructors and
+*     their call sites agree.
+*/
+function reconcileSharedGroups(groups) {
+	const byWrapper = /* @__PURE__ */ new Map();
+	for (const group of groups) {
+		const key = group.wrapperName ?? group.name;
+		const list = byWrapper.get(key);
+		if (list) list.push(group);
+		else byWrapper.set(key, [group]);
+	}
+	for (const sharers of byWrapper.values()) {
+		if (sharers.length < 2) continue;
+		for (const variant of sharers[0].variants) {
+			const peers = sharers.slice(1).map((g) => g.variants.find((v) => v.name === variant.name)).filter((v) => v !== void 0);
+			if (peers.length === 0) continue;
+			for (const member of variant.parameters) {
+				const all = [member, ...peers.map((p) => p.parameters.find((q) => q.name === member.name)).filter(isParameter)];
+				if (all.every((p) => p.type.kind === "nullable")) continue;
+				for (const p of all) if (p.type.kind === "nullable") p.type = p.type.inner;
+			}
+			const canonical = variant.parameters.map((p) => p.name);
+			for (const peer of peers) peer.parameters.sort((a, b) => {
+				const ia = canonical.indexOf(a.name);
+				const ib = canonical.indexOf(b.name);
+				if (ia === -1 && ib === -1) return 0;
+				if (ia === -1) return 1;
+				if (ib === -1) return -1;
+				return ia - ib;
+			});
+		}
+	}
+}
+function isParameter(p) {
+	return p !== void 0;
+}
+/**
+* Structural fingerprint of a group: its variants, their members, and each
+* member's resolved shape. Two declarations with the same fingerprint can
+* safely share one generated wrapper type.
+*/
+function fingerprintGroup(group, modelMap, enumMap) {
+	return group.variants.map((v) => {
+		const members = [...v.parameters].sort((a, b) => a.name.localeCompare(b.name)).map((p) => `${p.name}:${fingerprintType(p.type, modelMap, enumMap, /* @__PURE__ */ new Set())}`);
+		const optional = [...v.optionalParameters ?? []].sort();
+		return `${v.name}(${members.join(",")})[${optional.join(",")}]`;
+	}).join("|");
+}
+/**
+* Fingerprint a type by shape rather than by name.
+*
+* Names cannot be compared directly because the parser synthesizes a separate
+* name per declaration site for inline schemas: `create_user` and `update_user`
+* each get their own `PasswordHashType` enum, spelled `CreateUserPasswordHashType`
+* and `UpdateUserPasswordHashType`, though their values are identical. Comparing
+* names would report divergence and rename a wrapper for no reason.
+*
+* Nullability is also stripped: an update declaring a member nullable while
+* create declares it plain is not a reason to split the wrapper type.
+*/
+function fingerprintType(ref, modelMap, enumMap, visiting) {
+	switch (ref.kind) {
+		case "nullable": return fingerprintType(ref.inner, modelMap, enumMap, visiting);
+		case "primitive": return `p:${ref.type}`;
+		case "literal": return `l:${typeof ref.value}:${String(ref.value)}`;
+		case "array": return `a<${fingerprintType(ref.items, modelMap, enumMap, visiting)}>`;
+		case "map": return `m<${fingerprintType(ref.valueType, modelMap, enumMap, visiting)}>`;
+		case "union": return `u<${ref.variants.map((v) => fingerprintType(v, modelMap, enumMap, visiting)).sort().join(",")}>`;
+		case "enum": {
+			const e = enumMap.get(ref.name);
+			if (!e) return `e:${ref.name}`;
+			return `e<${e.values.map((v) => `${typeof v.value}:${String(v.value)}`).sort().join(",")}>`;
+		}
+		case "model": {
+			const m = modelMap.get(ref.name);
+			if (!m) return `M:${ref.name}`;
+			if (visiting.has(ref.name)) return `M:${ref.name}`;
+			const next = new Set(visiting).add(ref.name);
+			return `M<${[...m.fields].sort((a, b) => a.name.localeCompare(b.name)).map((f) => `${f.name}${f.required ? "!" : "?"}:${fingerprintType(f.type, modelMap, enumMap, next)}`).join(",")}>`;
+		}
+		default: return "unknown";
+	}
+}
+//#endregion
 //#region src/parser/normalize-model-refs.ts
 function validateModelRefs(spec) {
 	const knownNames = /* @__PURE__ */ new Set();
@@ -2840,7 +3167,7 @@ async function parseSpec(specPath, options) {
 	const version = spec.openapi ?? "";
 	if (!version.startsWith("3.")) throw new SpecParseError(`Unsupported OpenAPI version: ${version}. oagen requires OpenAPI 3.x`, `Update the spec to OpenAPI 3.0 or 3.1. If you are using Swagger 2.x, convert it first with \`npx swagger2openapi ${specPath}\`.`);
 	const { models, enums } = extractSchemas(spec.components?.schemas, { schemaNameTransform: options?.schemaNameTransform });
-	const { services, inlineModels } = extractOperations(spec.paths, options?.operationIdTransform, spec.components?.schemas);
+	const { services, inlineModels } = extractOperations(spec.paths, options?.operationIdTransform, spec.components?.schemas, spec.components?.parameters);
 	const responseNormalizedModels = mergeInlineResponseModels(models, inlineModels);
 	const fieldInlineModels = extractInlineModelsFromSchemas(spec.components?.schemas);
 	clearSchemaNameTransform();
@@ -2865,6 +3192,7 @@ async function parseSpec(specPath, options) {
 		auth,
 		sdk: defaultSdkBehavior()
 	};
+	assignParameterGroupWrapperNames(result);
 	validateModelRefs(result);
 	return result;
 }
@@ -8165,7 +8493,10 @@ function apiSurfaceToSnapshot(surface) {
 	}
 	return {
 		schemaVersion: "1",
-		source: { extractedAt: surface.extractedAt },
+		source: {
+			extractedAt: surface.extractedAt,
+			language
+		},
 		policies: getDefaultPolicy(language),
 		symbols
 	};
@@ -8395,10 +8726,138 @@ function severityMeetsThreshold(severity, threshold) {
 //#endregion
 //#region src/compat/classify.ts
 /**
+* Normalize a type annotation string to a canonical form before equality
+* comparison. Emitters evolve their annotation style across releases (e.g.
+* Python's PEP 604 `X | None` replacing `Optional[X]`, PEP 585 lowercase
+* generics, or dropping quotes from forward refs); such changes are cosmetic
+* and must not register as breaking type changes. Only Python needs this
+* today — other languages encode optionality with a single stable spelling
+* (`*Foo`, `Option<T>`, `T?`, `T.nilable(Foo)`) so they use exact comparison.
+* String-literal *values* inside `Literal[...]` are preserved verbatim so a
+* genuine change to a wire value stays visible. When `language` is absent
+* (older snapshots) no normalization is applied, preserving prior behaviour.
+*/
+function normalizeType(type, language) {
+	if (!type) return type;
+	if (language !== "python") return type;
+	return canonicalizePythonType(type);
+}
+/** PEP 585 capitalized builtins that map to their lowercase spellings, so
+*  `List[str]` and `list[str]` compare equal. */
+const PEP585_BUILTINS = {
+	List: "list",
+	Dict: "dict",
+	Tuple: "tuple",
+	Set: "set",
+	FrozenSet: "frozenset",
+	Type: "type"
+};
+/** Recursively canonicalize a Python annotation. Structural forms are
+*  normalized (`Optional[X]`→`X | None`, `Union[...]`→` | ` joins, PEP 585
+*  builtins, quoted forward refs, parenthesized unions), but `Literal[...]`
+*  arguments are preserved verbatim — their quotes and inner whitespace are
+*  part of the wire value, not cosmetic. */
+function canonicalizePythonType(s) {
+	const t = s.trim();
+	if (t.length === 0) return t;
+	if (t.startsWith("(") && t.endsWith(")")) return canonicalizePythonType(t.slice(1, -1));
+	if (t.startsWith("Literal[") && t.endsWith("]")) return `Literal[${splitTopLevel(t.slice(8, -1), ",").map((p) => p.trim()).filter((p) => p.length > 0).map(canonicalizeLiteralArg).join(", ")}]`;
+	if (t.startsWith("Optional[") && t.endsWith("]")) return `${canonicalizePythonType(t.slice(9, -1))} | None`;
+	if (t.startsWith("Union[") && t.endsWith("]")) return splitTopLevel(t.slice(6, -1), ",").map((p) => p.trim()).filter((p) => p.length > 0).map(canonicalizePythonType).join(" | ");
+	if (t.includes("|")) {
+		const arms = splitTopLevel(t, "|").map((p) => p.trim()).filter((p) => p.length > 0);
+		if (arms.length > 1) return arms.map(canonicalizePythonType).join(" | ");
+	}
+	const open = t.indexOf("[");
+	if (open !== -1 && t.endsWith("]")) {
+		const outer = t.slice(0, open).trim();
+		const inner = t.slice(open + 1, -1);
+		return `${PEP585_BUILTINS[outer] ?? outer}[${splitTopLevel(inner, ",").map((p) => p.trim()).filter((p) => p.length > 0).map(canonicalizePythonType).join(", ")}]`;
+	}
+	if (t.startsWith("\"") && t.endsWith("\"") && t.length >= 2 || t.startsWith("'") && t.endsWith("'") && t.length >= 2) return t.slice(1, -1);
+	return PEP585_BUILTINS[t] ?? t;
+}
+/** Canonicalize one `Literal[...]` argument so semantically identical string
+*  values compare equal regardless of quote style or escape form. The value
+*  is decoded (backslash escapes processed) then re-encoded in a canonical
+*  double-quoted form, so `Literal['say "hi"']` and `Literal["say \\"hi\\""]`
+*  both canonicalize to `"say \"hi\""`. Bare (unquoted) arguments — e.g. an
+*  enum name or a number — are returned unchanged. */
+function canonicalizeLiteralArg(arg) {
+	const a = arg.trim();
+	if (a.length < 2) return a;
+	let quote = null;
+	if (a.startsWith("\"") && a.endsWith("\"")) quote = "\"";
+	else if (a.startsWith("'") && a.endsWith("'")) quote = "'";
+	if (!quote) return a;
+	return `"${encodeDoubleQuoted(decodeStringLiteral(a.slice(1, -1)))}"`;
+}
+/** Decode the backslash escapes inside a Python string literal's content.
+*  Only the delimiter-relevant escapes (`\\`, `\'`, `\"`) are processed;
+*  other sequences (`\n`, `\t`, `\u…`) are kept verbatim since they're
+*  written identically regardless of quote style and so compare equal already. */
+function decodeStringLiteral(content) {
+	let out = "";
+	for (let i = 0; i < content.length; i++) {
+		const c = content[i];
+		if (c === "\\" && i + 1 < content.length) {
+			const next = content[i + 1];
+			if (next === "\\" || next === "\"" || next === "'") {
+				out += next;
+				i++;
+				continue;
+			}
+			out += c + next;
+			i++;
+			continue;
+		}
+		out += c;
+	}
+	return out;
+}
+/** Re-encode a decoded value as a canonical double-quoted Python string. */
+function encodeDoubleQuoted(value) {
+	return value.replace(/\\/g, "\\\\").replace(/"/g, "\\\"");
+}
+/** Split on a separator that sits at bracket-depth 0 and outside string
+*  literals, so commas/pipes inside `Literal["a,b"]` or `"x|y"` are not split.
+*  An escaped matching quote (`\"` inside a double-quoted string) does not
+*  close the string: only a quote preceded by an even number of backslashes
+*  (zero counts) is a real closing delimiter. */
+function splitTopLevel(s, sep) {
+	const parts = [];
+	let depth = 0;
+	let inStr = null;
+	let start = 0;
+	for (let i = 0; i < s.length; i++) {
+		const c = s[i];
+		if (inStr) {
+			if (c === inStr) {
+				let precedingBackslashes = 0;
+				for (let j = i - 1; j >= 0 && s[j] === "\\"; j--) precedingBackslashes++;
+				if (precedingBackslashes % 2 === 0) inStr = null;
+			}
+			continue;
+		}
+		if (c === "\"" || c === "'") {
+			inStr = c;
+			continue;
+		}
+		if (c === "[") depth++;
+		else if (c === "]") depth--;
+		else if (c === sep && depth === 0) {
+			parts.push(s.slice(start, i));
+			start = i + 1;
+		}
+	}
+	parts.push(s.slice(start));
+	return parts;
+}
+/**
 * Classify changes between a baseline and candidate symbol.
 * Returns one or more classified changes for the diff.
 */
-function classifySymbolChanges(baseline, candidate, policy) {
+function classifySymbolChanges(baseline, candidate, policy, language) {
 	const changes = [];
 	const specRef = baseline.schemaName ?? candidate?.schemaName;
 	if (!candidate) {
@@ -8422,8 +8881,8 @@ function classifySymbolChanges(baseline, candidate, policy) {
 		policy,
 		specRef
 	}));
-	if (baseline.parameters && candidate.parameters) changes.push(...classifyParameterChanges(baseline, candidate, policy, specRef));
-	if (baseline.returns && candidate.returns && baseline.returns.name !== candidate.returns.name) changes.push(makeChange({
+	if (baseline.parameters && candidate.parameters) changes.push(...classifyParameterChanges(baseline, candidate, policy, specRef, language));
+	if (baseline.returns && candidate.returns && normalizeType(baseline.returns.name, language) !== normalizeType(candidate.returns.name, language)) changes.push(makeChange({
 		category: "return_type_changed",
 		symbol: baseline.fqName,
 		old: { returnType: baseline.returns.name },
@@ -8441,7 +8900,7 @@ function classifySymbolChanges(baseline, candidate, policy) {
 		policy,
 		specRef
 	}));
-	if (baseline.typeRef && candidate.typeRef && baseline.typeRef.name !== candidate.typeRef.name) changes.push(makeChange({
+	if (baseline.typeRef && candidate.typeRef && normalizeType(baseline.typeRef.name, language) !== normalizeType(candidate.typeRef.name, language)) changes.push(makeChange({
 		category: "field_type_changed",
 		symbol: baseline.fqName,
 		old: { type: baseline.typeRef.name },
@@ -8463,7 +8922,7 @@ function classifySymbolChanges(baseline, candidate, policy) {
 /**
 * Classify parameter-level changes between two symbol versions.
 */
-function classifyParameterChanges(baseline, candidate, policy, specRef) {
+function classifyParameterChanges(baseline, candidate, policy, specRef, language) {
 	const changes = [];
 	const baseParams = baseline.parameters ?? [];
 	const candParams = candidate.parameters ?? [];
@@ -8512,7 +8971,7 @@ function classifyParameterChanges(baseline, candidate, policy, specRef) {
 			policy,
 			specRef
 		}));
-		if (baseParam.type.name !== candParam.type.name) changes.push(makeChange({
+		if (normalizeType(baseParam.type.name, language) !== normalizeType(candParam.type.name, language)) changes.push(makeChange({
 			category: "parameter_type_narrowed",
 			symbol: baseline.fqName,
 			old: {
@@ -8869,7 +9328,7 @@ function diffSnapshots(baseline, candidate, policy) {
 	for (const baseSym of baseline.symbols) {
 		if (isServiceWrapperConstructor(baseSym, serviceAccessors)) continue;
 		const candSym = candById.get(baseSym.id) ?? candByFqName.get(baseSym.fqName);
-		changes.push(...classifySymbolChanges(baseSym, candSym, effectivePolicy));
+		changes.push(...classifySymbolChanges(baseSym, candSym, effectivePolicy, baseline.source.language));
 	}
 	for (const candSym of candidate.symbols) if (!baseByFqName.has(candSym.fqName)) {
 		if (isServiceWrapperConstructor(candSym, serviceAccessors)) continue;