@workos/oagen 0.30.2 → 0.31.0

package/dist/smoke.mjs

@@ -4,6 +4,7 @@ import { readFile } from "node:fs/promises";
 import { resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import { BaseResolver, Oas3_1Types, bundleDocument, createConfig, makeDocumentFromString } from "@redocly/openapi-core";
+import { createHash } from "node:crypto";
 //#region src/utils/naming.ts
 /**
 * Known compound tokens that the regex-based splitter over-splits.
@@ -50,7 +51,7 @@ function splitWords(s) {
 	if (!s) return [];
 	return recombineCompounds(s.replace(/[^a-zA-Z0-9_\-\s.]/g, "_").replace(/([a-z])([A-Z])/g, "$1\0$2").replace(/([A-Z]+)([A-Z][a-z])/g, "$1\0$2").replace(/([a-zA-Z])(\d)/g, "$1\0$2").replace(/(\d)([a-zA-Z])/g, "$1\0$2").split(/[\0_\-\s.]+/).filter((w) => w.length > 0));
 }
-const ACRONYM_SET = new Set([
+const ACRONYM_SET = /* @__PURE__ */ new Set([
 	"SSO",
 	"FGA",
 	"SAML",
@@ -60,7 +61,7 @@ const ACRONYM_SET = new Set([
 	"M2M"
 ]);
 function toPascalCase(s, acronyms) {
-	const merged = acronyms ? new Set([...ACRONYM_SET, ...acronyms]) : ACRONYM_SET;
+	const merged = acronyms ? /* @__PURE__ */ new Set([...ACRONYM_SET, ...acronyms]) : ACRONYM_SET;
 	return splitWords(s).map((w) => {
 		const upper = w.toUpperCase();
 		if (merged.has(upper)) return upper;
@@ -69,7 +70,7 @@ function toPascalCase(s, acronyms) {
 	}).join("");
 }
 function toCamelCase(s, acronyms) {
-	const merged = acronyms ? new Set([...ACRONYM_SET, ...acronyms]) : ACRONYM_SET;
+	const merged = acronyms ? /* @__PURE__ */ new Set([...ACRONYM_SET, ...acronyms]) : ACRONYM_SET;
 	const words = splitWords(s);
 	if (words.length === 0) return "";
 	return words.map((w, i) => {
@@ -102,7 +103,7 @@ function stripListItemMarkers(name) {
 	return name.replace(/ListItem/g, "").replace(/ByExternalId/g, "").replace(/ByResourceId/g, "").replace(/ForResource/g, "");
 }
 /** Words that look plural but must NOT be singularized. */
-const SINGULAR_SAFE_LIST = new Set([
+const SINGULAR_SAFE_LIST = /* @__PURE__ */ new Set([
 	"Status",
 	"Address",
 	"Access",
@@ -283,11 +284,15 @@ var SpecParseError = class extends OagenError {
 //#region src/parser/refs.ts
 async function loadAndBundleSpec(specPath) {
 	const absolutePath = resolve(specPath);
+	const content = await readFile(absolutePath, "utf-8");
+	const document = makeDocumentFromString(content, pathToFileURL(absolutePath).href);
+	const config = await createConfig({});
+	const resolver = new BaseResolver();
 	const result = await bundleDocument({
-		document: makeDocumentFromString(await readFile(absolutePath, "utf-8"), pathToFileURL(absolutePath).href),
-		config: await createConfig({}),
+		document,
+		config,
 		types: Oas3_1Types,
-		externalRefResolver: new BaseResolver(),
+		externalRefResolver: resolver,
 		dereference: false
 	});
 	if (result.problems.some((p) => p.severity === "error")) throw new SpecParseError(`Failed to parse spec: ${result.problems.filter((p) => p.severity === "error").map((p) => p.message).join("\n")}`, `Check the OpenAPI spec at "${absolutePath}" for syntax errors. Run a linter such as \`npx @redocly/cli lint ${specPath}\` to identify issues.`);
@@ -353,6 +358,38 @@ function walkTypeRef(ref, visitor) {
 		default: assertNever(ref);
 	}
 }
+/**
+* Collect all model names referenced (directly or transitively) by a TypeRef.
+*/
+function collectModelRefs(ref) {
+	const names = [];
+	walkTypeRef(ref, { model: (r) => names.push(r.name) });
+	return names;
+}
+/**
+* Every response header an operation declares: the primary response's, each
+* alternate success entry's, and each error entry's. The primary list is the
+* same array as its `successResponses` entry when both exist, so it is yielded
+* once. Every pass that walks an operation's type refs (reachability, model
+* assignment, ref rewriting and validation, direction, compat filtering, enum
+* collection) goes through this so a type reached only through a header is
+* treated the way a body or parameter type is.
+*/
+function collectResponseHeaders(op) {
+	const result = [];
+	const seen = /* @__PURE__ */ new Set();
+	const lists = [
+		op.responseHeaders,
+		...(op.successResponses ?? []).map((r) => r.headers),
+		...op.errors.map((e) => e.headers)
+	];
+	for (const list of lists) {
+		if (!list || seen.has(list)) continue;
+		seen.add(list);
+		result.push(...list);
+	}
+	return result;
+}
 //#endregion
 //#region src/parser/inline-models.ts
 /**
@@ -373,138 +410,598 @@ function qualifyInlineModelName(baseName, parentName) {
 	return `${cleanParent}${baseName}`;
 }
 /**
+* The inline model or enum names `schemaToTypeRef` would mint for `schema`
+* typed under `contextName` with `parentModelName`; empty when it mints none
+* (a `$ref`, a primitive, an array or map of those). Mirrors the naming
+* branches of `schemaToTypeRef`: an inline object in any form it recognises
+* (`properties`, an `allOf` with object members) takes
+* `qualifyInlineModelName`; a `oneOf`/`anyOf` mints one model per inline
+* object variant, named exactly as the union references them
+* (`nameInlineVariants`: `DrawingLayer`, `DrawingLayerWithOpacity`, or
+* `CircleDrawingLayer` when every variant is titled); an inline enum, or a
+* `oneOf` of string consts that collapses into one, takes the parent-prefixed
+* enum name, which is never singularized; an array or map claims whatever its
+* items or values would.
+*/
+function mintedInlineNames(contextName, schema, parentModelName) {
+	return mintedInlineNameEntries(contextName, schema, parentModelName).map((entry) => entry.name);
+}
+/** `mintedInlineNames`, also telling for each name whether it is context-free. */
+function mintedInlineNameEntries(contextName, schema, parentModelName) {
+	const s = unwrapNullableSchema(schema);
+	if (s.$ref) return [];
+	const base = toPascalCase(contextName);
+	const modelName = () => [{
+		name: qualifyInlineModelName(base, parentModelName),
+		contextFree: false
+	}];
+	const enumName = () => {
+		const cleanParent = parentModelName ? stripListItemMarkers(parentModelName) : void 0;
+		return [{
+			name: cleanParent && !base.startsWith(cleanParent) ? `${cleanParent}${base}` : base,
+			contextFree: false
+		}];
+	};
+	if (s.allOf) {
+		const only = s.allOf.length === 1 ? s.allOf[0] : void 0;
+		if (only) return mintedInlineNameEntries(contextName, only, parentModelName);
+		return s.allOf.some((m) => !m.$ref && (m.properties || m.type === "object")) ? modelName() : [];
+	}
+	const variants = s.oneOf ?? s.anyOf;
+	if (variants) {
+		const nonNull = variants.filter((v) => !isNullSchema$1(v));
+		if (nonNull.length >= 2 && nonNull.every((v) => typeof v.const === "string")) return enumName();
+		return [...nameInlineVariantEntries(s, modelName()[0].name)].map(([variant, entry]) => ({
+			...entry,
+			schema: variant
+		}));
+	}
+	if (s.const !== void 0) return [];
+	if ((s.enum ?? []).filter((v) => v !== null).length >= 2) return enumName();
+	if (isInlineObjectSchema(s)) return modelName();
+	if (s.items && (s.type === "array" || !s.type)) return mintedInlineNameEntries(contextName, s.items, parentModelName);
+	if (s.type === "object" && !s.properties) {
+		const value = mapValueSchema(s);
+		return value ? mintedInlineNameEntries(contextName, value, parentModelName) : [];
+	}
+	return [];
+}
+/**
+* The inline names the other properties of an object mint
+* (`mintedInlineNameEntries`) which a `oneOf`/`anyOf` under `fieldName` must
+* not give one of its variants (`nameInlineVariants`): beside a
+* `shape_with_side` object, the `{ side }` variant of `shape` cannot become
+* `DrawingShapeWithSide`. Every context-dependent sibling name is reserved.
+* A context-free name — a title-mapped variant's title — names one shape
+* wherever it appears, so it is shared, not reserved, when this field gives
+* the same title a variant of the identical shape (`schemaShapeKey`:
+* documentation keywords ignored, property names verbatim — the rule array
+* items already use to share a singular sibling's model); a sibling giving
+* the same title a different shape, or one this field does not use, reserves
+* it, so this union's variant falls back to its context-qualified name. Each
+* sibling's names are read in isolation, without the reservations that
+* sibling would itself apply, so the set depends on sibling names and content
+* only, two unions beside each other cannot chase each other's names, and
+* the shape test is symmetric: when `Circle` means `{ radius }` on one side
+* and `{ diameter }` on the other, both fall back (`CircleDrawingShape`,
+* `CircleDrawingMarker`) and neither keeps the bare `Circle`. Empty without a
+* sibling set, as for a request body or response that is itself a union.
+*/
+function reservedInlineNames(fieldName, siblings, parentModelName) {
+	const reserved = /* @__PURE__ */ new Set();
+	if (!siblings) return reserved;
+	const ownShapes = /* @__PURE__ */ new Map();
+	const fieldSchema = siblings.get(fieldName);
+	if (fieldSchema) for (const own of mintedInlineNameEntries(fieldName, fieldSchema, parentModelName)) {
+		if (!own.contextFree || !own.schema) continue;
+		ownShapes.set(own.name, [...ownShapes.get(own.name) ?? [], schemaShapeKey(own.schema)]);
+	}
+	for (const [siblingName, siblingSchema] of siblings) {
+		if (siblingName === fieldName) continue;
+		for (const minted of mintedInlineNameEntries(siblingName, siblingSchema, parentModelName)) {
+			if (!minted.contextFree) {
+				reserved.add(minted.name);
+				continue;
+			}
+			const shapes = ownShapes.get(minted.name);
+			const siblingShape = minted.schema ? schemaShapeKey(minted.schema) : void 0;
+			if (!(shapes !== void 0 && siblingShape !== void 0 && shapes.every((s) => s === siblingShape))) reserved.add(minted.name);
+		}
+	}
+	return reserved;
+}
+/** Documentation keywords that do not shape a model; ignored by `schemaShapeKey` at a schema's own level. */
+const DOC_KEYWORDS = /* @__PURE__ */ new Set([
+	"description",
+	"title",
+	"example",
+	"examples",
+	"summary",
+	"externalDocs",
+	"deprecated"
+]);
+/** Keywords whose value maps NAMES (not keywords) to schemas: names are kept verbatim, values recurse as schemas. */
+const NAMED_SCHEMA_MAPS = /* @__PURE__ */ new Set([
+	"properties",
+	"patternProperties",
+	"dependentSchemas",
+	"$defs",
+	"definitions"
+]);
+/** Keywords whose value is a single schema. */
+const SCHEMA_KEYWORDS = /* @__PURE__ */ new Set([
+	"items",
+	"additionalProperties",
+	"additionalItems",
+	"contains",
+	"propertyNames",
+	"not",
+	"if",
+	"then",
+	"else",
+	"unevaluatedProperties",
+	"unevaluatedItems"
+]);
+/** Keywords whose value is an ordered list of schemas. */
+const SCHEMA_LIST_KEYWORDS = /* @__PURE__ */ new Set([
+	"allOf",
+	"oneOf",
+	"anyOf",
+	"prefixItems"
+]);
+/** Keywords whose list value is a set: compared order-insensitively. */
+const UNORDERED_LIST_KEYWORDS = /* @__PURE__ */ new Set(["required", "type"]);
+/**
+* A canonical rendering of a schema's shape, for deciding whether two inline
+* schemas describe the same model: every structural keyword (`type`,
+* `properties`, `required`, `items`, `additionalProperties`,
+* `patternProperties`, `allOf`/`oneOf`/`anyOf`, `enum`, `const`, `format`,
+* `nullable`, ...) recursively, with keywords sorted and the `required` and
+* `type` lists order-insensitive. Documentation keywords (`description`,
+* `title`, `example`, `examples`, `summary`, `externalDocs`, `deprecated`)
+* and vendor extensions (`x-*`) are ignored, and so is `nullable: false`,
+* which the nullable unwrap leaves behind — but only where they are a
+* schema's own keywords. Inside `properties`, `patternProperties`,
+* `dependentSchemas`, `dependentRequired` and `$defs` the keys are property
+* names, kept verbatim: a field named `description` or `title` is part of the
+* shape. Enum, const and default values are compared as plain data, in
+* order, as the IR keeps them.
+*/
+function schemaShapeKey(schema) {
+	const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+	const dataKey = (value) => {
+		if (Array.isArray(value)) return value.map(dataKey);
+		if (!isRecord(value)) return value;
+		const out = {};
+		for (const key of Object.keys(value).sort()) out[key] = dataKey(value[key]);
+		return out;
+	};
+	const schemaKey = (value) => {
+		if (!isRecord(value)) return value;
+		const out = {};
+		for (const keyword of Object.keys(value).sort()) {
+			const v = value[keyword];
+			if (DOC_KEYWORDS.has(keyword) || keyword.startsWith("x-")) continue;
+			if (keyword === "nullable" && v === false) continue;
+			if (NAMED_SCHEMA_MAPS.has(keyword) && isRecord(v)) {
+				const named = {};
+				for (const name of Object.keys(v).sort()) named[name] = schemaKey(v[name]);
+				out[keyword] = named;
+			} else if (keyword === "dependentRequired" && isRecord(v)) {
+				const named = {};
+				for (const name of Object.keys(v).sort()) {
+					const names = v[name];
+					named[name] = Array.isArray(names) ? names.map(String).sort() : dataKey(names);
+				}
+				out[keyword] = named;
+			} else if (SCHEMA_KEYWORDS.has(keyword)) out[keyword] = schemaKey(v);
+			else if (SCHEMA_LIST_KEYWORDS.has(keyword) && Array.isArray(v)) out[keyword] = v.map(schemaKey);
+			else if (UNORDERED_LIST_KEYWORDS.has(keyword) && Array.isArray(v)) out[keyword] = v.map(String).sort();
+			else out[keyword] = dataKey(v);
+		}
+		return out;
+	};
+	return JSON.stringify(schemaKey(schema));
+}
+/**
+* The context name an array field's items (`kind: 'item'`) or a map field's
+* values (`kind: 'value'`) are typed and extracted under. By default it is
+* the field itself, so the inline model is the parent plus the singularized
+* field (`layers` on `Drawing` → `DrawingLayer`).
+*
+* When a sibling property of the same object would mint that very name —
+* `layer` as an inline object, an inline enum, an inline union with object
+* variants (any of whose variant names counts), or an array or map of such
+* (`mintedInlineNames`); a primitive `email` beside `emails` claims nothing
+* — the elements step aside to
+* `<field>_item` / `<field>_value`, which qualify to `<Parent><Field>Item` /
+* `<Parent><Field>Value` (`DrawingLayersItem`, `DrawingLayersValue`),
+* matching the `<Variant>Item` convention. Should a sibling mint that name
+* too (a property `layers_item`), the fallback keeps going the way
+* `variantMemberKeys` does for variants: `<field>_array_item`, then
+* `<field>_array_item2`, `<field>_array_item3`, ... for items
+* (`DrawingLayersArrayItem`, ...) and `<field>_member_value`,
+* `<field>_member_value2`, ... for values, taking the first candidate whose
+* minted name no sibling claims.
+*
+* Identical-shape sharing: when every sibling claiming the singular name is
+* an inline object whose shape is structurally identical to the items or
+* values (`schemaShapeKey`: same properties, required, types, nested inline
+* schemas and enum values; description, title and example ignored), the
+* fields share one model under the singular name. They are the same shape,
+* so one model is the right SDK type and a duplicate would only add noise;
+* should a later spec version make the shapes diverge, the split happens
+* then, which is the moment the item type genuinely changes. This
+* deliberately departs from a literal one-model-per-field reading for the
+* identical case.
+*
+* Only context-dependent names take part: a title-mapped variant's title
+* (`MintedInlineName.contextFree`) is the same under every context, so no
+* candidate could step away from it, and such a name is shared by design —
+* two sibling arrays whose items carry the same titled variants both
+* reference `Circle` and `Square` (`nameInlineVariants`). The search always
+* terminates: it stops as soon as a candidate changes nothing about the names
+* (`firstFreeElementContext`'s no-progress rule), and
+* `MAX_ELEMENT_CONTEXT_ATTEMPTS` caps it as a backstop; both return the last
+* candidate tried, deterministically.
+*
+* Decided from sibling names and schema content alone, so document order
+* plays no part. `schemaToTypeRef` and every extractor call this with the
+* same sibling set (`collectProperties`); otherwise the reference and the
+* model disagree.
+*/
+function elementContextName(fieldName, kind, siblings, parentModelName, elementSchema) {
+	return elementContextDecision(fieldName, kind, siblings, parentModelName, elementSchema).context;
+}
+/** `elementContextName`, with the reason it decided as it did (see `ElementContextReason`). */
+function elementContextDecision(fieldName, kind, siblings, parentModelName, elementSchema) {
+	if (!siblings) return {
+		context: fieldName,
+		reason: "no-siblings"
+	};
+	const dependentNames = (candidate) => mintedInlineNameEntries(candidate, elementSchema, parentModelName).filter((entry) => !entry.contextFree).map((entry) => entry.name);
+	const own = dependentNames(fieldName);
+	if (own.length === 0) return {
+		context: fieldName,
+		reason: "nothing-minted"
+	};
+	const claimed = /* @__PURE__ */ new Map();
+	for (const [siblingName, siblingSchema] of siblings) {
+		if (siblingName === fieldName) continue;
+		for (const minted of mintedInlineNames(siblingName, siblingSchema, parentModelName)) claimed.set(minted, [...claimed.get(minted) ?? [], siblingSchema]);
+	}
+	const rivals = [...new Set(own.flatMap((name) => claimed.get(name) ?? []))];
+	if (rivals.length === 0) return {
+		context: fieldName,
+		reason: "unclaimed"
+	};
+	const element = unwrapNullableSchema(elementSchema);
+	const identical = (rival) => {
+		const sibling = unwrapNullableSchema(rival);
+		return isInlineObjectSchema(sibling) && isInlineObjectSchema(element) && schemaShapeKey(sibling) === schemaShapeKey(element);
+	};
+	if (rivals.every(identical)) return {
+		context: fieldName,
+		reason: "shared-shape"
+	};
+	return firstFreeElementContext(fieldName, kind, new Set(claimed.keys()), dependentNames, own);
+}
+/**
+* The first fallback context under which the elements mint no claimed name:
+* `<field>_item` / `<field>_value`, then `<field>_array_item` /
+* `<field>_member_value`, then `<field>_array_item2`, `…3`, ... (the way
+* `variantMemberKeys` numbers a variant's members). `mint` gives the names
+* under a candidate and `previous` those under the context tried before the
+* first candidate. The search stops with `no-progress` as soon as a
+* candidate mints the same names as the one before it — the names do not
+* depend on the context, so no candidate can avoid the claim — and with
+* `cap` after `maxAttempts` candidates; both keep the last candidate tried.
+*/
+function firstFreeElementContext(fieldName, kind, claimed, mint, previous, maxAttempts = 256) {
+	const fallback = kind === "item" ? "array_item" : "member_value";
+	let last = previous;
+	let candidate = fieldName;
+	for (let i = 0; i < maxAttempts; i++) {
+		candidate = i === 0 ? `${fieldName}_${kind}` : i === 1 ? `${fieldName}_${fallback}` : `${fieldName}_${fallback}${i}`;
+		const minted = mint(candidate);
+		if (minted.every((name) => !claimed.has(name))) return {
+			context: candidate,
+			reason: "free"
+		};
+		if (sameNames(minted, last)) return {
+			context: candidate,
+			reason: "no-progress"
+		};
+		last = minted;
+	}
+	return {
+		context: candidate,
+		reason: "cap"
+	};
+}
+/** The same names, in any order. */
+function sameNames(a, b) {
+	if (a.length !== b.length) return false;
+	const sortedB = [...b].sort();
+	return [...a].sort().every((name, i) => name === sortedB[i]);
+}
+/**
+* Every property the object described by `schema` exposes, by name: its own
+* `properties`, those of its `allOf` members (following a member's `$ref`
+* into `schemas` when given, as `extractAllOfModel` does), and those of
+* inline `oneOf`/`anyOf` variants, whose fields the model extractors flatten
+* in; the first definition of a name wins. This is the sibling set
+* `elementContextName` decides from; the TypeRef builder and every extractor
+* derive it through this one function so they agree.
+*/
+function collectProperties(schema, schemas) {
+	const properties = /* @__PURE__ */ new Map();
+	const seen = /* @__PURE__ */ new Set();
+	const visit = (s, followRef) => {
+		if (!s || seen.has(s)) return;
+		seen.add(s);
+		if (s.$ref) {
+			if (followRef && schemas) visit(schemas[s.$ref.split("/").pop() ?? ""], true);
+			return;
+		}
+		for (const [key, value] of Object.entries(s.properties ?? {})) if (value && !properties.has(key)) properties.set(key, value);
+		for (const sub of s.allOf ?? []) visit(sub, true);
+		for (const variant of [...s.oneOf ?? [], ...s.anyOf ?? []]) visit(variant, false);
+	};
+	visit(schema, false);
+	return properties;
+}
+/**
 * Walk all component schemas and extract inline Model definitions for fields
-* that are objects with properties (or arrays of such objects).
+* that are objects with properties, including objects reached through array
+* items, `oneOf` variants, and map (`additionalProperties` /
+* `patternProperties`) values.
 * These correspond to the ModelRef entries created by schemaToTypeRef.
 */
 function extractInlineModelsFromSchemas(schemas) {
 	if (!schemas) return [];
 	const inlineModels = [];
-	for (const [schemaName, schema] of Object.entries(schemas)) extractInlineModelsFromProperties(schema, inlineModels, resolveSchemaName(schemaName));
+	for (const [schemaName, schema] of Object.entries(schemas)) extractInlineModelsFromProperties(schema, inlineModels, resolveSchemaName(schemaName), schemas, collectProperties(schema, schemas));
 	return inlineModels;
 }
-function extractInlineModelsFromProperties(schema, results, parentName) {
+/**
+* Walk a schema's properties and materialise every inline object as a model.
+* `componentSchemas` is optional and only feeds `buildFieldFromSchema`, so a
+* field that `$ref`s a component can take its `example`/`examples` from it;
+* callers without the component map at hand simply omit it.
+* `siblingProperties` is the parent object's full property set, for callers
+* that see more of it than this schema shows (see `elementContextName`).
+* `reservedNames` is set only on the re-entry for a field's array items or
+* map values: the inline names that field's siblings mint, which a union
+* among the items or values must step around exactly as `schemaToTypeRef`
+* does when it hands the same set down (`reservedNamesFor`).
+*
+* The recursion follows the document's own inline structure only: a `$ref`
+* is resolved solely to read a component's property list for typing (an
+* augmentation's inherited fields, a sibling set), never descended into, so
+* the depth is bounded by the document's inline nesting and no component
+* graph — self-extending, mutually extending, or reused at several levels —
+* can make it run away.
+*/
+function extractInlineModelsFromProperties(schema, results, parentName, componentSchemas, siblingProperties, reservedNames) {
 	const properties = schema.properties ?? {};
 	const allOfSchemas = schema.allOf ?? [];
-	for (const sub of allOfSchemas) if (sub.properties) extractInlineModelsFromProperties(sub, results, parentName);
-	for (const [fieldName, fieldSchema] of Object.entries(properties)) {
-		if (!fieldSchema) continue;
-		if (fieldSchema.properties && (fieldSchema.type === "object" || !fieldSchema.type)) {
+	const siblings = siblingProperties ?? collectProperties(schema);
+	const reservedFor = (fieldName) => reservedNames ?? reservedInlineNames(fieldName, siblings, parentName);
+	for (const sub of allOfSchemas) if (sub.properties) extractInlineModelsFromProperties(sub, results, parentName, componentSchemas, siblings, reservedNames);
+	for (const [fieldName, rawFieldSchema] of Object.entries(properties)) {
+		if (!rawFieldSchema) continue;
+		const fieldSchema = unwrapNullableField(rawFieldSchema);
+		if (isInlineObjectSchema(fieldSchema)) {
 			const modelName = qualifyInlineModelName(toPascalCase(fieldName), parentName);
-			results.push(buildInlineModel(modelName, fieldSchema));
-			extractInlineModelsFromProperties(fieldSchema, results, modelName);
+			results.push(buildInlineModel(modelName, fieldSchema, componentSchemas));
+			extractInlineModelsFromProperties(fieldSchema, results, modelName, componentSchemas);
 		}
-		if (fieldSchema.type === "array" && fieldSchema.items) {
-			const items = fieldSchema.items;
-			if (items.properties && (items.type === "object" || !items.type)) {
-				const modelName = qualifyInlineModelName(toPascalCase(fieldName), parentName);
-				results.push(buildInlineModel(modelName, items));
-				extractInlineModelsFromProperties(items, results, modelName);
-			}
+		if (fieldSchema.type === "array" && fieldSchema.items) extractInlineModelsFromProperties({ properties: { [elementContextName(fieldName, "item", siblings, parentName, fieldSchema.items)]: fieldSchema.items } }, results, parentName, componentSchemas, void 0, reservedFor(fieldName));
+		if (fieldSchema.type === "object" && !fieldSchema.properties) {
+			const valueSchema = mapValueSchema(fieldSchema);
+			if (valueSchema) extractInlineModelsFromProperties({ properties: { [elementContextName(fieldName, "value", siblings, parentName, valueSchema)]: valueSchema } }, results, parentName, componentSchemas, void 0, reservedFor(fieldName));
 		}
-		if (fieldSchema.allOf && fieldSchema.allOf.every((s) => !s.$ref && !s.oneOf && !s.anyOf)) {
-			const merged = mergeAllOfObjectSchema(fieldSchema);
-			if (Object.keys(merged.properties ?? {}).length > 0) {
+		if (fieldSchema.allOf) {
+			const members = fieldSchema.allOf;
+			const emitMerged = () => {
+				const merged = mergeAugmentation(fieldSchema, componentSchemas);
+				if (merged.properties.length === 0) return;
 				const modelName = qualifyInlineModelName(toPascalCase(fieldName), parentName);
-				results.push(buildInlineModel(modelName, merged));
-				extractInlineModelsFromProperties(merged, results, modelName);
-			}
+				results.push(buildMergedModel(modelName, merged, componentSchemas));
+				const own = {};
+				for (const p of merged.properties) if (p.origin === null) own[p.name] = p.schema;
+				const mergedSiblings = new Map(merged.properties.map((p) => [p.name, p.schema]));
+				extractInlineModelsFromProperties({ properties: own }, results, modelName, componentSchemas, mergedSiblings);
+			};
+			const only = members.length === 1 ? members[0] : void 0;
+			if (members.some((m) => m.$ref)) {
+				if (members.some((m) => !m.$ref && (m.properties || m.type === "object"))) emitMerged();
+			} else if (only) extractInlineModelsFromProperties({ properties: { [fieldName]: {
+				...only,
+				...extractConstraints(fieldSchema)
+			} } }, results, parentName, componentSchemas, siblings, reservedNames);
+			else if (members.some((m) => m.properties)) emitMerged();
 		}
-		if (fieldSchema.oneOf) {
-			const inlineObjectVariants = fieldSchema.oneOf.filter((v) => !v.$ref && v.properties && (v.type === "object" || !v.type));
+		const unionVariants = fieldSchema.oneOf ?? fieldSchema.anyOf;
+		if (unionVariants) {
+			const inlineObjectVariants = unionVariants.filter((v) => isInlineObjectSchema(v));
 			if (inlineObjectVariants.length > 0) {
 				const modelName = qualifyInlineModelName(toPascalCase(fieldName), parentName);
 				const existingNames = new Set(results.map((r) => r.name));
-				const namingDiscProp = deriveOneOfNamingDiscriminator(inlineObjectVariants);
-				const emittedNames = [];
+				const variantNames = nameInlineVariants(fieldSchema, modelName, reservedFor(fieldName));
 				for (const variant of inlineObjectVariants) {
-					const variantName = nameOneOfVariant(variant, modelName, emittedNames, namingDiscProp);
-					emittedNames.push(variantName);
+					const variantName = variantNames.get(variant);
+					if (variantName === void 0) continue;
 					if (!existingNames.has(variantName)) {
 						existingNames.add(variantName);
-						results.push(buildInlineModel(variantName, variant));
-						extractInlineModelsFromProperties(variant, results, variantName);
+						results.push(buildInlineModel(variantName, variant, componentSchemas));
+						extractInlineModelsFromProperties(variant, results, variantName, componentSchemas);
+						extractInlineModelsFromProperties({ properties: variantMemberSchemas(variant, variantName) }, results, variantName, componentSchemas);
 					}
 				}
 			}
 		}
 	}
 }
-/** Find a single string-const-valued property shared by every variant whose
-*  values are all distinct — the implicit discriminator. Returns null when no
-*  such property exists. Mirrors `deriveConstNamingDiscriminator` in schemas.ts. */
-function deriveOneOfNamingDiscriminator(variants) {
-	if (variants.length < 2) return null;
-	const candidates = Object.keys(variants[0]?.properties ?? {});
-	for (const propName of candidates) {
-		const values = variants.map((v) => readConstString(v.properties?.[propName]));
-		if (values.some((v) => v === null)) continue;
-		if (new Set(values).size !== values.length) continue;
-		return propName;
-	}
-	return null;
-}
-function readConstString(prop) {
-	if (!prop) return null;
-	if (typeof prop.const === "string") return prop.const;
-	if (Array.isArray(prop.enum) && prop.enum.length === 1 && typeof prop.enum[0] === "string") return prop.enum[0];
-	return null;
-}
-/** Produce a per-variant model name. Variant 0 keeps the bare parent name;
-*  later variants are prefixed by the const-derived label. Mirrors
-*  `nameVariantModel` in schemas.ts. Falls back to a numeric suffix when no
-*  discriminator is available, the const value PascalCases to nothing, or
-*  the derived candidate collides with the parent or an already-emitted name. */
-function nameOneOfVariant(variant, parentName, alreadyEmitted, discriminatorProperty) {
-	if (alreadyEmitted.length === 0) return parentName;
-	if (discriminatorProperty) {
-		const constValue = readConstString(variant.properties?.[discriminatorProperty]);
-		if (constValue) {
-			const prefix = toPascalCase(constValue);
-			if (prefix) {
-				const candidate = parentName.startsWith(prefix) ? parentName : `${prefix}${parentName}`;
-				if (!(candidate === parentName || alreadyEmitted.includes(candidate))) return candidate;
-			}
-		}
-	}
-	return `${parentName}${alreadyEmitted.length + 1}`;
-}
 /**
-* Merge the object members of an `allOf` (recursively) into a single
-* object-shaped schema, so an inline object expressed via `allOf` can be
-* materialized as one model — mirroring how schemaToTypeRef collapses such a
-* field into a single merged model ref. Earlier members win on key conflicts,
-* matching the merge order used elsewhere in the parser.
+* Merge an `allOf` field into one object shape, remembering where each
+* property comes from. A `$ref` member is resolved against `componentSchemas`
+* by its component name, as `extractAllOfModel` does, and contributes its
+* properties — its own nested `allOf` chain included — tagged with that
+* component's model name, so the merged model can type them exactly as the
+* component's own model does; inline members contribute properties tagged as
+* the merged model's own. `required` is collected from every member. Earlier
+* members win on key conflicts, matching the merge order used elsewhere in
+* the parser; an unresolvable ref contributes nothing. The walk reads the
+* components' property lists only — it never descends into a property — so
+* it is finite for any component graph (the `seen` set only short-circuits a
+* component reached twice within one merge).
 */
-function mergeAllOfObjectSchema(schema) {
-	const properties = {};
+function mergeAugmentation(schema, componentSchemas) {
+	const properties = [];
+	const seenNames = /* @__PURE__ */ new Set();
 	const required = [];
-	const visit = (s) => {
-		if (s.properties) {
-			for (const [key, value] of Object.entries(s.properties)) if (value && !(key in properties)) properties[key] = value;
+	const seen = /* @__PURE__ */ new Set();
+	const visit = (s, origin) => {
+		if (seen.has(s)) return;
+		seen.add(s);
+		if (s.$ref) {
+			const rawName = s.$ref.split("/").pop() ?? "";
+			const target = componentSchemas?.[rawName];
+			if (!target) return;
+			visit(target, origin ?? {
+				name: resolveSchemaName(rawName),
+				schema: target
+			});
+			return;
+		}
+		for (const [key, value] of Object.entries(s.properties ?? {})) {
+			if (!value || seenNames.has(key)) continue;
+			seenNames.add(key);
+			properties.push({
+				name: key,
+				schema: value,
+				origin
+			});
 		}
 		if (s.required) required.push(...s.required);
-		if (s.allOf) for (const sub of s.allOf) visit(sub);
+		for (const sub of s.allOf ?? []) visit(sub, origin);
 	};
-	visit(schema);
+	visit(schema, null);
 	return {
-		type: "object",
 		properties,
 		required,
-		description: schema.description
+		description: schema.description,
+		constraints: extractConstraints(schema)
+	};
+}
+/**
+* Build the model for a merged `allOf` field. An inherited property is typed
+* with its component as naming context and the component's own sibling set,
+* so it carries the same TypeRef as in the component's model (`BaseMeta`,
+* `BaseChild`, ...); the merged model's own properties are typed under its
+* name with the full merged property set as siblings.
+*/
+function buildMergedModel(name, merged, componentSchemas) {
+	const requiredSet = new Set(merged.required);
+	const mergedSiblings = new Map(merged.properties.map((p) => [p.name, p.schema]));
+	const componentSiblings = /* @__PURE__ */ new Map();
+	const fields = merged.properties.map((p) => {
+		if (p.origin === null) return buildFieldFromSchema(p.name, p.schema, name, requiredSet, componentSchemas, mergedSiblings);
+		let siblings = componentSiblings.get(p.origin.name);
+		if (!siblings) {
+			siblings = collectProperties(p.origin.schema, componentSchemas);
+			componentSiblings.set(p.origin.name, siblings);
+		}
+		return buildFieldFromSchema(p.name, p.schema, p.origin.name, requiredSet, componentSchemas, siblings);
+	});
+	return {
+		name,
+		description: merged.description,
+		fields,
+		...merged.constraints ? { constraints: merged.constraints } : {}
 	};
 }
-function buildInlineModel(name, schema) {
+/**
+* Strip the nullable wrappers `schemaToTypeRef` unwraps before it names
+* anything — the OAS 3.1 `type: [X, 'null']` array, the OAS 3.0
+* `nullable: true` flag, and a `oneOf`/`anyOf` with a single non-null
+* variant — so extraction dispatches on the same shape the TypeRef was built
+* from. The unwrap keeps `contextName`/`parentModelName` semantics intact:
+* `schemaToTypeRef` passes both through each of these wrappers unchanged.
+*/
+function unwrapNullableSchema(schema) {
+	if (schema.$ref) return schema;
+	if (Array.isArray(schema.type)) {
+		const nonNullTypes = schema.type.filter((t) => t !== "null");
+		if (nonNullTypes.length !== 1) return schema;
+		return unwrapNullableSchema({
+			...schema,
+			type: nonNullTypes[0],
+			nullable: false
+		});
+	}
+	if (schema.nullable && schema.type) return unwrapNullableSchema({
+		...schema,
+		nullable: false
+	});
+	const variants = schema.allOf ? void 0 : schema.oneOf ?? schema.anyOf;
+	if (variants) {
+		const nullVariant = variants.find(isNullSchema$1);
+		const nonNullVariants = variants.filter((v) => v !== nullVariant);
+		const only = nonNullVariants[0];
+		if (nullVariant && nonNullVariants.length === 1 && only) return unwrapNullableSchema(only);
+	}
+	return schema;
+}
+/**
+* `unwrapNullableSchema` for a field, carrying the wrapper's limits onto the
+* branch it unwraps to. The type-array and `nullable: true` forms unwrap by
+* spreading, so every keyword survives; the union form swaps in the bare
+* branch, which would drop a `minProperties` written beside
+* `anyOf: [{ type: 'object', … }, { type: 'null' }]`. `extractConstraints`
+* conjoins that wrapper's own keywords with its branch's as the field's
+* limits, so the model built from the branch must carry the same ones or
+* `Model.constraints` would omit what the field declares.
+*/
+function unwrapNullableField(schema) {
+	const inner = unwrapNullableSchema(schema);
+	if (inner === schema || schema.allOf || !(schema.oneOf ?? schema.anyOf)) return inner;
+	return {
+		...inner,
+		...extractConstraints(schema)
+	};
+}
+/** The `{ type: 'null' }` member that marks a `oneOf`/`anyOf` as nullable — same test as schemaToTypeRef. */
+function isNullSchema$1(schema) {
+	return schema.type === "null" || Array.isArray(schema.type) && schema.type.length === 1 && schema.type[0] === "null";
+}
+/**
+* The schema that types a map's values, in the precedence `schemaToTypeRef`
+* uses: a non-empty `additionalProperties` object wins, otherwise the first
+* `patternProperties` entry. `additionalProperties: {}` means "any value"
+* (typed `unknown`, nothing to extract) and does not fall through to
+* `patternProperties`, matching the type-ref branch.
+*/
+function mapValueSchema(schema) {
+	const additional = schema.additionalProperties;
+	if (additional && typeof additional === "object") return Object.keys(additional).length > 0 ? additional : null;
+	return (schema.patternProperties ? Object.values(schema.patternProperties) : [])[0] ?? null;
+}
+function buildInlineModel(name, schema, componentSchemas) {
 	const requiredSet = new Set(schema.required ?? []);
 	const fields = [];
+	const siblings = collectProperties(schema);
 	for (const [fieldName, fieldSchema] of Object.entries(schema.properties ?? {})) {
 		if (!fieldSchema) continue;
-		fields.push(buildFieldFromSchema(fieldName, fieldSchema, name, requiredSet));
+		fields.push(buildFieldFromSchema(fieldName, fieldSchema, name, requiredSet, componentSchemas, siblings));
 	}
 	return {
 		name,
 		description: schema.description,
-		fields
+		fields,
+		...constraintsEntry(schema)
 	};
 }
 //#endregion
@@ -512,9 +1009,21 @@ function buildInlineModel(name, schema) {
 /**
 * Module-level transform set during extractSchemas(). Used by schemaToTypeRef()
 * to apply the same name transform to $ref model/enum references.
+*
+* Receives the cleaned PascalCase name and, when the name is a
+* `components.schemas` key, the raw key exactly as spelled in the document.
+* Names oagen synthesises (inline enums, request-body variant models,
+* title-derived names) pass no second argument.
 */
 let activeSchemaNameTransform = null;
 /**
+* Module-level set of raw `components.schemas` keys for the spec being
+* extracted. resolveSchemaName() consults it to decide whether the name it was
+* handed is a real component key (forwarded to the transform as
+* `originalName`) or a name oagen synthesised (no `originalName`).
+*/
+let activeComponentSchemaKeys = /* @__PURE__ */ new Set();
+/**
 * Module-level set of resolved schema names whose components/schemas entry is
 * an enum (i.e. has `enum:`). Populated by extractSchemas() so schemaToTypeRef()
 * can classify a `$ref` to a top-level enum schema as `kind: 'enum'` instead of
@@ -522,33 +1031,308 @@ let activeSchemaNameTransform = null;
 * ref, even when the target was a shared enum like `PaginationOrder`.
 */
 let activeEnumSchemaNames = /* @__PURE__ */ new Set();
-/** Apply cleanSchemaName + the active transform (if any) to a raw schema name. */
+/**
+* Subset of `activeEnumSchemaNames` whose component schema also admits
+* `null` — via an OAS 3.1 `type: [..., 'null']` array, the OAS 3.0
+* `nullable: true` flag, or a literal `null` member in `enum:`. A `$ref` to
+* one of these resolves to `nullable(enum)` so the component's own
+* nullability survives the reference, matching the shape an inline
+* `oneOf: [{ $ref }, { type: 'null' }]` already produces.
+*/
+let activeNullableEnumSchemaNames = /* @__PURE__ */ new Set();
+/** Drop `null` from an `enum:` list — it marks nullability, it is not a member. */
+function nonNullEnumValues(values) {
+	return (values ?? []).filter((v) => v !== null);
+}
+/** True when an enum schema admits `null` by any OAS 3.0 / 3.1 spelling. */
+function isNullableEnumSchema(schema) {
+	if (schema.nullable === true) return true;
+	if (Array.isArray(schema.type) && schema.type.includes("null")) return true;
+	return Array.isArray(schema.enum) && schema.enum.includes(null);
+}
+/** Wrap `ref` in `nullable` unless it already is one, so a nullable enum `$ref` is never double-wrapped. */
+function asNullable(ref) {
+	return ref.kind === "nullable" ? ref : {
+		kind: "nullable",
+		inner: ref
+	};
+}
+/**
+* Apply cleanSchemaName + the active transform (if any) to a raw schema name.
+* When `rawName` is a `components.schemas` key the transform also receives it
+* as `originalName`, so a consumer can opt out of normalization by returning
+* the original spelling. Names oagen synthesises (request-body variant
+* models, title-derived names, ...) are not component keys and get no
+* `originalName`.
+*/
 function resolveSchemaName(rawName) {
 	let name = cleanSchemaName(toPascalCase(rawName));
-	if (activeSchemaNameTransform) name = activeSchemaNameTransform(name);
+	if (activeSchemaNameTransform) {
+		const originalName = activeComponentSchemaKeys.has(rawName) ? rawName : void 0;
+		name = activeSchemaNameTransform(name, originalName);
+	}
 	return name;
 }
+/** Validation keywords copied through unchanged when they hold a number. */
+const NUMERIC_CONSTRAINT_KEYS = [
+	"multipleOf",
+	"minLength",
+	"maxLength",
+	"minItems",
+	"maxItems",
+	"minContains",
+	"maxContains",
+	"minProperties",
+	"maxProperties"
+];
+/**
+* Collect the JSON Schema validation keywords declared directly on `schema`
+* into a `Constraints` object, or `undefined` when it declares none — so a
+* schema without limits yields no `constraints` key on its IR node at all.
+*
+* Numeric bounds are normalized to the OAS 3.1 shape. OAS 3.0 spells an
+* exclusive bound as `exclusiveMinimum: true` beside `minimum: n`; that pair
+* becomes `exclusiveMinimum: n` with no `minimum`. A boolean `false`, or a
+* `true` with no bound to apply to, is dropped. The 3.1 numeric form passes
+* through, including the legal-but-unusual case of both an inclusive and an
+* exclusive bound on the same side. `uniqueItems: false` restates the default
+* and is dropped too.
+*
+* Only the schema's own keywords are read: limits nested inside array `items`
+* or map values are not collected. The one exception is a nullable wrapper —
+* a `oneOf`/`anyOf` with a single non-null, non-`$ref` branch — that declares
+* none itself: it takes that branch's keywords, since the IR collapses it to
+* `nullable<T>`. Values of the wrong type (a string `maxLength`, say) are
+* ignored rather than carried.
+*/
+function extractConstraints(schema) {
+	let out = ownConstraints(schema);
+	for (const member of schema.allOf ?? []) out = combineConstraints(out, extractConstraints(member));
+	const branch = singleNonNullBranch(schema);
+	return branch ? combineConstraints(out, extractConstraints(branch)) : out;
+}
+/** The keywords declared strictly on `schema`, normalized — without the nullable-branch fallback. */
+function ownConstraints(schema) {
+	const out = {};
+	const lower = normalizeBound(schema.minimum, schema.exclusiveMinimum);
+	if (lower.inclusive !== void 0) out.minimum = lower.inclusive;
+	if (lower.exclusive !== void 0) out.exclusiveMinimum = lower.exclusive;
+	const upper = normalizeBound(schema.maximum, schema.exclusiveMaximum);
+	if (upper.inclusive !== void 0) out.maximum = upper.inclusive;
+	if (upper.exclusive !== void 0) out.exclusiveMaximum = upper.exclusive;
+	for (const key of NUMERIC_CONSTRAINT_KEYS) {
+		const value = schema[key];
+		if (typeof value === "number") out[key] = value;
+	}
+	if (typeof schema.pattern === "string") out.pattern = schema.pattern;
+	if (schema.uniqueItems === true) out.uniqueItems = true;
+	const dependentRequired = readDependentRequired(schema.dependentRequired);
+	if (dependentRequired) out.dependentRequired = dependentRequired;
+	return Object.keys(out).length > 0 ? out : void 0;
+}
+/** The one non-null, non-`$ref` branch of a `oneOf`/`anyOf`, or `undefined` for anything else. */
+function singleNonNullBranch(schema) {
+	const variants = schema.oneOf ?? schema.anyOf;
+	if (!variants) return void 0;
+	const nonNull = variants.filter((v) => !isNullSchema(v));
+	return nonNull.length === 1 && !nonNull[0].$ref ? nonNull[0] : void 0;
+}
+/** True for the `{ type: 'null' }` / `{ type: ['null'] }` branch of a nullable wrapper. */
+function isNullSchema(schema) {
+	return schema.type === "null" || Array.isArray(schema.type) && schema.type.length === 1 && schema.type[0] === "null";
+}
+/**
+* `{ constraints }` when `schema` declares any validation keyword, `{}`
+* otherwise — spread into an IR node so the key stays absent rather than
+* present-but-undefined.
+*/
+function constraintsEntry(schema) {
+	const constraints = extractConstraints(schema);
+	return constraints ? { constraints } : {};
+}
+/** Keywords where the stricter of two declarations is the larger value. */
+const MIN_KEYS = [
+	"minimum",
+	"exclusiveMinimum",
+	"minLength",
+	"minItems",
+	"minContains",
+	"minProperties"
+];
+/** Keywords where the stricter of two declarations is the smaller value. */
+const MAX_KEYS = [
+	"maximum",
+	"exclusiveMaximum",
+	"maxLength",
+	"maxItems",
+	"maxContains",
+	"maxProperties"
+];
+/**
+* Conjoin two constraint sets the way `allOf` conjoins schemas: an instance
+* must satisfy both, so every `min*` takes the larger value, every `max*` the
+* smaller, `uniqueItems` holds if either side demands it, and
+* `dependentRequired` merges per property with the union of its names
+* (deduplicated, `a`'s order first). A keyword declared on one side only is
+* kept as is, and an absent side yields the other unchanged.
+*
+* `multipleOf` and `pattern` keep `a`'s value when the two differ: a true
+* conjunction would need the least common multiple, or a lookahead regex
+* joining both patterns, and neither is worth carrying into the IR.
+*
+* Not for the parameter `$ref` fallback in extractParams: keywords written
+* beside a `$ref` override the target's there, which is a different operation.
+*/
+function combineConstraints(a, b) {
+	if (!a) return b;
+	if (!b) return a;
+	const out = {
+		...a,
+		...b
+	};
+	for (const key of MIN_KEYS) {
+		const [x, y] = [a[key], b[key]];
+		if (x !== void 0 && y !== void 0) out[key] = Math.max(x, y);
+	}
+	for (const key of MAX_KEYS) {
+		const [x, y] = [a[key], b[key]];
+		if (x !== void 0 && y !== void 0) out[key] = Math.min(x, y);
+	}
+	if (a.uniqueItems || b.uniqueItems) out.uniqueItems = true;
+	if (a.multipleOf !== void 0 && b.multipleOf !== void 0) out.multipleOf = a.multipleOf;
+	if (a.pattern !== void 0 && b.pattern !== void 0) out.pattern = a.pattern;
+	if (a.dependentRequired && b.dependentRequired) out.dependentRequired = unionDependentRequired(a.dependentRequired, b.dependentRequired);
+	return out;
+}
+/** Per-property union of two `dependentRequired` maps, deduplicated and keeping `a`'s order first. */
+function unionDependentRequired(a, b) {
+	const merged = /* @__PURE__ */ new Map();
+	for (const [property, names] of Object.entries(a)) merged.set(property, [...names]);
+	for (const [property, names] of Object.entries(b)) {
+		const existing = merged.get(property);
+		if (!existing) {
+			merged.set(property, [...names]);
+			continue;
+		}
+		for (const name of names) if (!existing.includes(name)) existing.push(name);
+	}
+	return Object.fromEntries(merged);
+}
+/**
+* Resolve one side's bound from `minimum` / `maximum` plus its `exclusive*`
+* companion into the OAS 3.1 shape: a numeric companion is the exclusive
+* bound itself, `true` turns the inclusive bound into the exclusive one, and
+* `false` or absent leaves the inclusive bound as is.
+*/
+function normalizeBound(inclusive, exclusive) {
+	const bound = typeof inclusive === "number" ? inclusive : void 0;
+	if (typeof exclusive === "number") return {
+		inclusive: bound,
+		exclusive
+	};
+	if (exclusive === true) return { exclusive: bound };
+	return { inclusive: bound };
+}
+/** Copy `dependentRequired` when it is an object whose values are string arrays; anything else is ignored. */
+function readDependentRequired(value) {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return void 0;
+	const entries = [];
+	for (const [property, deps] of Object.entries(value)) if (Array.isArray(deps) && deps.every((d) => typeof d === "string")) entries.push([property, [...deps]]);
+	return entries.length > 0 ? Object.fromEntries(entries) : void 0;
+}
+/**
+* Narrow a raw `examples` value to a non-empty list, or undefined. Guards
+* against documents that put an OAS Example Object map (or anything else)
+* where JSON Schema expects an array, and against an empty list, so the IR
+* carries `examples` only when there is at least one value.
+*/
+function nonEmptyExamples(value) {
+	return Array.isArray(value) && value.length > 0 ? value : void 0;
+}
+/**
+* Pick the single `example` the IR carries: the document's own `example`
+* when it is set (including an explicit `null`), otherwise the first entry
+* of the resolved `examples` list.
+*/
+function pickExample(example, examples) {
+	return example !== void 0 ? example : examples?.[0];
+}
+/**
+* Resolve `example` and `examples` across ordered precedence levels: for a
+* parameter its own declaration, its inline schema, then the component its
+* `$ref` points at; for a field its own schema, then its `$ref` target.
+*
+* Each value walks the levels independently. `examples` is the first
+* non-empty list. `example` comes from the first level that has either an
+* `example` or a list, preferring that level's own `example` over its first
+* list entry — so a schema-level `example` can never mask the parameter's
+* own `examples` map. A level with neither falls through; an explicit
+* `null` is a value and stops the walk.
+*/
+function resolveExamples(levels) {
+	let example;
+	let examples;
+	for (const level of levels) {
+		if (examples === void 0) examples = level.examples;
+		if (example === void 0) example = pickExample(level.example, level.examples);
+	}
+	return {
+		example,
+		examples
+	};
+}
+/**
+* If a schema is a `$ref` to `#/components/schemas/X`, return the referenced
+* component schema. Used to surface schema-level metadata (default, example,
+* examples, deprecated, description) that would otherwise be invisible at the
+* field or parameter level.
+*
+* Refs are not pre-resolved by the bundler (`dereference: false` in refs.ts),
+* so without this, a param like `schema: { $ref: '.../PaginationOrder' }`
+* silently loses the target's `default: desc` and the SDK stops emitting the
+* spec-mandated default value in generated method signatures.
+*/
+function resolveComponentSchemaRef(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 extractSchemas(schemas, options) {
 	const enums = [];
 	if (!schemas) return {
 		models: [],
 		enums
 	};
+	activeComponentSchemaKeys = new Set(Object.keys(schemas));
 	if (options?.schemaNameTransform) {
 		const transform = options.schemaNameTransform;
-		const cleanedNames = Object.keys(schemas).map((n) => cleanSchemaName(toPascalCase(n)));
-		const transformedToOriginals = /* @__PURE__ */ new Map();
-		for (const cleaned of cleanedNames) {
-			const transformed = transform(cleaned);
-			if (!transformedToOriginals.has(transformed)) transformedToOriginals.set(transformed, []);
-			transformedToOriginals.get(transformed).push(cleaned);
-		}
-		const unsafeToTransform = /* @__PURE__ */ new Set();
-		for (const [, originals] of transformedToOriginals) if (originals.length > 1) for (const n of originals) unsafeToTransform.add(n);
-		activeSchemaNameTransform = (name) => unsafeToTransform.has(name) ? name : transform(name);
+		const transformedToRawKeys = /* @__PURE__ */ new Map();
+		for (const raw of Object.keys(schemas)) {
+			const transformed = transform(cleanSchemaName(toPascalCase(raw)), raw);
+			if (!transformedToRawKeys.has(transformed)) transformedToRawKeys.set(transformed, []);
+			transformedToRawKeys.get(transformed).push(raw);
+		}
+		const unsafeRawKeys = /* @__PURE__ */ new Set();
+		const unsafeCleanedNames = /* @__PURE__ */ new Set();
+		for (const [, rawKeys] of transformedToRawKeys) if (rawKeys.length > 1) for (const raw of rawKeys) {
+			unsafeRawKeys.add(raw);
+			unsafeCleanedNames.add(cleanSchemaName(toPascalCase(raw)));
+		}
+		activeSchemaNameTransform = (name, originalName) => {
+			return (originalName !== void 0 ? unsafeRawKeys.has(originalName) : unsafeCleanedNames.has(name)) ? name : transform(name, originalName);
+		};
 	} else activeSchemaNameTransform = null;
 	activeEnumSchemaNames = /* @__PURE__ */ new Set();
-	for (const [name, schema] of Object.entries(schemas)) if (schema.enum) activeEnumSchemaNames.add(resolveSchemaName(name));
+	activeNullableEnumSchemaNames = /* @__PURE__ */ new Set();
+	for (const [name, schema] of Object.entries(schemas)) {
+		if (!schema.enum) continue;
+		const resolved = resolveSchemaName(name);
+		activeEnumSchemaNames.add(resolved);
+		if (isNullableEnumSchema(schema)) activeNullableEnumSchemaNames.add(resolved);
+	}
 	const modelsByCleanName = /* @__PURE__ */ new Map();
 	for (const [name, schema] of Object.entries(schemas)) {
 		const pascalName = resolveSchemaName(name);
@@ -559,7 +1343,7 @@ function extractSchemas(schemas, options) {
 			if (existing) {
 				if (model.fields.length > existing.fields.length) modelsByCleanName.set(pascalName, model);
 			} else modelsByCleanName.set(pascalName, model);
-			for (const inlineModel of extractDiscriminatedAllOfVariantModels(schema, pascalName)) {
+			for (const inlineModel of extractDiscriminatedAllOfVariantModels(schema, pascalName, schemas)) {
 				const existingInline = modelsByCleanName.get(inlineModel.name);
 				if (existingInline) {
 					if (inlineModel.fields.length > existingInline.fields.length) modelsByCleanName.set(inlineModel.name, inlineModel);
@@ -584,6 +1368,8 @@ function extractSchemas(schemas, options) {
 function clearSchemaNameTransform() {
 	activeSchemaNameTransform = null;
 	activeEnumSchemaNames = /* @__PURE__ */ new Set();
+	activeNullableEnumSchemaNames = /* @__PURE__ */ new Set();
+	activeComponentSchemaKeys = /* @__PURE__ */ new Set();
 }
 /**
 * Walk a single TypeRef and extract inline enum refs as top-level enum definitions.
@@ -619,14 +1405,17 @@ function collectInlineEnums(fields, enums) {
 * that schemaToTypeRef turns into model refs but aren't extracted from components.
 */
 function collectNestedInlineModels(ref, fieldName, parentModelName, schemas, models, modelNames, queue) {
+	const directRefs = directModelRefNames(ref);
 	walkTypeRef(ref, { model: (modelRef) => {
 		if (modelNames.has(modelRef.name)) return;
+		if (!directRefs.has(modelRef.name)) return;
 		if (Object.keys(schemas).some((k) => resolveSchemaName(k) === modelRef.name)) return;
 		const parentSchema = findSchemaByName(parentModelName, schemas);
 		if (!parentSchema) return;
 		const fieldSchema = findNestedFieldSchema(fieldName, parentSchema, schemas);
 		if (!fieldSchema) return;
-		const extracted = extractNestedSchema(modelRef.name, fieldSchema);
+		const reserved = reservedInlineNames(fieldName, collectProperties(parentSchema, schemas), parentModelName);
+		const extracted = extractNestedSchema(unionBaseName(modelRef.name, fieldName, fieldSchema, parentModelName, reserved), fieldSchema, schemas, reserved);
 		for (const m of extracted) if (!modelNames.has(m.name)) {
 			models.push(m);
 			modelNames.add(m.name);
@@ -634,6 +1423,35 @@ function collectNestedInlineModels(ref, fieldName, parentModelName, schemas, mod
 		}
 	} });
 }
+/**
+* The base name `extractNestedSchema` should name a field's `oneOf` variants
+* from: the field's qualified inline name when naming the variants from it
+* yields `refName` (the ref the walk is resolving), else `refName` itself,
+* which is right for every non-union field and for a union whose variant 0 is
+* bare.
+*/
+function unionBaseName(refName, fieldName, fieldSchema, parentModelName, reserved) {
+	if (!fieldSchema.oneOf) return refName;
+	const fromField = qualifyInlineModelName(toPascalCase(fieldName), parentModelName);
+	return [...nameInlineVariants(fieldSchema, fromField, reserved).values()].includes(refName) ? fromField : refName;
+}
+/**
+* The model refs a field's TypeRef produces directly: the ref itself, the
+* items of a (possibly nullable) array, or each (possibly nullable) variant of
+* a union — the shapes `extractNestedSchema` can name from a ref. Refs nested
+* any deeper are excluded.
+*/
+function directModelRefNames(ref) {
+	const names = /* @__PURE__ */ new Set();
+	let root = ref;
+	while (root.kind === "nullable" || root.kind === "array") root = root.kind === "nullable" ? root.inner : root.items;
+	const leaves = root.kind === "union" ? root.variants : [root];
+	for (const leaf of leaves) {
+		const inner = leaf.kind === "nullable" ? leaf.inner : leaf;
+		if (inner.kind === "model") names.add(inner.name);
+	}
+	return names;
+}
 /** Find a component schema by PascalCase name. */
 function findSchemaByName(pascalName, schemas) {
 	for (const [k, v] of Object.entries(schemas)) if (resolveSchemaName(k) === pascalName) return v;
@@ -662,104 +1480,278 @@ function findNestedFieldSchema(fieldName, parentSchema, schemas) {
 	}
 	return null;
 }
-/** Extract a model (and nested models) from an inline field schema. */
-function extractNestedSchema(name, schema) {
+/**
+* Extract a model (and nested models) from an inline field schema. `reserved`
+* holds the inline names the field's sibling properties mint
+* (`reservedInlineNames`), which a `oneOf` variant must not take.
+*/
+function extractNestedSchema(name, schema, schemas, reserved = NO_RESERVED) {
 	if (schema.oneOf) {
 		const models = [];
-		const constNamingDiscriminator = deriveConstNamingDiscriminator(schema.oneOf.filter((v) => !v.$ref && v.properties && (v.type === "object" || !v.type)));
+		const variantNames = nameInlineVariants(schema, name, reserved);
 		for (const variant of schema.oneOf) {
-			if (variant.$ref) continue;
-			if (variant.properties && (variant.type === "object" || !variant.type)) {
-				const requiredSet = new Set(variant.required ?? []);
-				const fields = [];
-				for (const [fn, fs] of Object.entries(variant.properties)) {
-					if (!fs) continue;
-					fields.push(buildFieldFromSchema(fn, fs, name, requiredSet));
-				}
-				const variantName = nameVariantModel(variant, name, models, constNamingDiscriminator);
-				models.push({
-					name: variantName,
-					description: variant.description,
-					fields
-				});
+			const variantName = variantNames.get(variant);
+			if (variantName === void 0) continue;
+			const requiredSet = new Set(variant.required ?? []);
+			const siblings = collectProperties(variant);
+			const fields = [];
+			for (const [fn, fs] of Object.entries(variant.properties ?? {})) {
+				if (!fs) continue;
+				fields.push(buildFieldFromSchema(fn, fs, variantName, requiredSet, schemas, siblings));
 			}
+			models.push({
+				name: variantName,
+				description: variant.description,
+				fields,
+				...constraintsEntry(variant)
+			});
 		}
 		return models;
 	}
 	if (schema.properties && (schema.type === "object" || !schema.type)) {
 		const requiredSet = new Set(schema.required ?? []);
+		const siblings = collectProperties(schema);
 		const fields = [];
 		for (const [fn, fs] of Object.entries(schema.properties)) {
 			if (!fs) continue;
-			fields.push(buildFieldFromSchema(fn, fs, name, requiredSet));
+			fields.push(buildFieldFromSchema(fn, fs, name, requiredSet, schemas, siblings));
 		}
 		return [{
 			name,
 			description: schema.description,
-			fields
+			fields,
+			...constraintsEntry(schema)
 		}];
 	}
 	if (schema.type === "array" && schema.items?.properties) {
 		const requiredSet = new Set(schema.items.required ?? []);
+		const siblings = collectProperties(schema.items);
 		const fields = [];
 		for (const [fn, fs] of Object.entries(schema.items.properties)) {
 			if (!fs) continue;
-			fields.push(buildFieldFromSchema(fn, fs, name, requiredSet));
+			fields.push(buildFieldFromSchema(fn, fs, name, requiredSet, schemas, siblings));
 		}
 		return [{
 			name,
 			description: schema.items.description,
-			fields
+			fields,
+			...constraintsEntry(schema.items)
 		}];
 	}
 	return [];
 }
 /**
-* Derive a meaningful name for a oneOf object variant past the first,
-* falling back to the numeric-suffix scheme (`Foo2`, `Foo3`) when no
-* better signal is available. The "better signal" is a const-valued
-* discriminator property that distinguishes one variant from the others.
-*
-* For a schema like `ApiKey.owner` whose oneOf has two variants — one
-* with `type: { const: "organization" }` and one with `type: { const:
-* "user" }` — this returns `ApiKeyOwner` for the first variant (the
-* baseline name that the union TypeRef will reference, so consumer-
-* visible typed fields stay backward-compatible) and `UserApiKeyOwner`
-* for the second instead of `ApiKeyOwner2`. SDK consumers reading the
-* generated types can tell the variants apart at a glance.
-*
-* The first variant always keeps the bare parent name because
-* `schemaToTypeRef` builds union variants whose model refs collapse to
-* `qualifyInlineModelName(field, parent)` — so the first model name
-* must match for the union's degenerate-collapse to land on a valid
-* type. Renaming variant 0 would orphan it.
-*
-* Falls back to numeric suffix when:
-*   - The variant has no discriminator property (no shared const
-*     property across all object variants), OR
-*   - The const value PascalCases to an empty/whitespace name, OR
-*   - The derived name collides with the parent name or an already-
-*     emitted variant name (numeric keeps uniqueness).
-*/
-function nameVariantModel(variant, parentName, alreadyEmitted, discriminator) {
-	if (alreadyEmitted.length === 0) return parentName;
+* The prefix a variant's `title` contributes to its name: the title trimmed
+* and PascalCased, or null when there is no title or it PascalCases to
+* nothing.
+*/
+function variantTitlePrefix(variant) {
+	const title = typeof variant["title"] === "string" ? variant["title"].trim() : "";
+	return title ? toPascalCase(title) || null : null;
+}
+/** `<Prefix><Base>`, or `base` unchanged when it already starts with the prefix (no doubling). */
+function prefixedVariantName(prefix, base) {
+	return base.startsWith(prefix) ? base : `${prefix}${base}`;
+}
+/**
+* The properties `variant` declares that no other inline object variant of
+* the same union declares, in the variant's own `properties` order.
+*/
+function distinguishingProperties(variant, siblings) {
+	const declaredElsewhere = /* @__PURE__ */ new Set();
+	for (const sibling of siblings) {
+		if (sibling === variant) continue;
+		for (const property of Object.keys(sibling.properties ?? {})) declaredElsewhere.add(property);
+	}
+	return Object.keys(variant.properties ?? {}).filter((property) => !declaredElsewhere.has(property));
+}
+/**
+* Name an inline object variant of a `oneOf`/`anyOf` that has no better
+* signal: it is not variant 0 (which keeps the union's base name) and no
+* const discriminator gave it a prefix. The name is derived from the
+* variant's own content, never from where it sits in the document (beyond
+* its position among the variants, which only the final counter reads), so
+* an SDK user can tell the variants apart and reordering them changes nothing
+* but which one is variant 0. In order, taking the first candidate that is
+* neither the base name nor a name already given to an earlier variant of
+* the same union:
+*
+*   1. the variant's `title` (trimmed and PascalCased): `<Title><Base>`
+*      (`CircleDrawingShape`), the same prefix form a const discriminator
+*      produces, including the rule that a base already starting with the
+*      prefix is not doubled (that candidate equals the base, so it falls
+*      through); a title an earlier variant already took falls through too;
+*   2. a distinguishing property — the first property, in the variant's own
+*      order, that it declares and no other inline object variant declares:
+*      `<Base>With<Property>` (`DrawingShapeWithSide`); a property that
+*      PascalCases to nothing is skipped;
+*   3. the position counter, `<Base><position + 1>` (`DrawingShape2`), which
+*      now remains only for variants whose property sets are identical, and
+*      which keeps counting past a taken name (`DrawingShape3`).
+*
+* Every candidate is also checked against `reserved`: the inline names the
+* parent's other properties mint (`reservedInlineNames`), so a variant can
+* never take a name another field's model already has — beside a
+* `shape_with_side` object, the `{ side }` variant of `shape` is not
+* `DrawingShapeWithSide` but the next candidate. Read from sibling names and
+* content only, so document order plays no part.
+*
+* `siblings` are the inline object variants of the union, this one included;
+* `emitted` are the names already given to the earlier ones, in order. Every
+* site that names a variant — the union TypeRef, the component-field,
+* request-body and response extractors, and `mintedInlineNames` — goes
+* through this function (via `nameInlineVariant`), so they cannot drift.
+*/
+function nameUndiscriminatedVariant(variant, siblings, base, emitted, reserved = NO_RESERVED) {
+	const taken = (candidate) => candidate === base || emitted.includes(candidate) || reserved.has(candidate);
+	const titlePrefix = variantTitlePrefix(variant);
+	if (titlePrefix !== null) {
+		const candidate = prefixedVariantName(titlePrefix, base);
+		if (!taken(candidate)) return candidate;
+	}
+	for (const property of distinguishingProperties(variant, siblings)) {
+		const word = toPascalCase(property);
+		if (!word) continue;
+		const candidate = `${base}With${word}`;
+		if (!taken(candidate)) return candidate;
+	}
+	for (let position = emitted.length + 1;; position++) {
+		const candidate = `${base}${position}`;
+		if (!taken(candidate)) return candidate;
+	}
+}
+/** No reserved names: for a union with no sibling properties (a request body or response that is itself a union). */
+const NO_RESERVED = /* @__PURE__ */ new Set();
+/**
+* True when the union's inline object variants (two or more) each carry a
+* title and no two titles PascalCase to the same prefix: the one case in
+* which variant 0 is named from its title rather than keeping the base name.
+*/
+function allDistinctlyTitled(siblings) {
+	if (siblings.length < 2) return false;
+	const prefixes = siblings.map(variantTitlePrefix);
+	return prefixes.every((prefix) => prefix !== null) && new Set(prefixes).size === prefixes.length;
+}
+/**
+* The name of one inline object variant of a `oneOf`/`anyOf`, given the
+* union's base name (the field's qualified inline name, e.g. `ApiKeyOwner`),
+* the inline object variants of the union (`siblings`, this one included),
+* the names already given to the earlier variants (`emitted`, in order), and
+* the const-valued property that distinguishes the variants when there is
+* one (`deriveConstNamingDiscriminator`).
+*
+* Variant 0 keeps the bare base name: the union TypeRef and every extractor
+* reference it under that name, and a consumer's typed field keeps the name
+* it always had. The one exception: when the union has no const discriminator
+* and every variant carries a distinct title, variant 0 is named from its
+* title like the others (`CircleDrawingShape` beside `SquareDrawingShape`)
+* instead of being the only one left bare. Whether the union is discriminated
+* is read from the variants themselves here, not from `discriminator`, so a
+* caller forcing a property (an explicit `discriminator:` without `mapping:`)
+* still agrees with the extractors on variant 0.
+*
+* A later variant takes `<ConstValue><Base>` from the discriminator
+* (`UserApiKeyOwner`) when the value PascalCases to something and the name is
+* neither the base, nor already emitted, nor minted by one of the parent's
+* other properties (`reserved`), and otherwise falls to
+* `nameUndiscriminatedVariant`: its title, a distinguishing property, then
+* the position counter, each checked the same way.
+*/
+function nameInlineVariant(variant, siblings, base, emitted, discriminator, reserved = NO_RESERVED) {
+	if (emitted.length === 0) {
+		const titlePrefix = deriveConstNamingDiscriminator([...siblings]) === null && allDistinctlyTitled(siblings) ? variantTitlePrefix(variant) : null;
+		return titlePrefix === null ? base : prefixedVariantName(titlePrefix, base);
+	}
 	if (discriminator) {
 		const constValue = getConstPropertyValue(variant, discriminator.property);
-		if (constValue) {
-			const prefix = toPascalCase(constValue);
-			if (prefix) {
-				const candidate = parentName.startsWith(prefix) ? parentName : `${prefix}${parentName}`;
-				if (!(candidate === parentName || alreadyEmitted.some((m) => m.name === candidate))) return candidate;
+		const prefix = constValue ? toPascalCase(constValue) : "";
+		if (prefix) {
+			const candidate = prefixedVariantName(prefix, base);
+			if (candidate !== base && !emitted.includes(candidate) && !reserved.has(candidate)) return candidate;
+		}
+	}
+	return nameUndiscriminatedVariant(variant, siblings, base, emitted, reserved);
+}
+/**
+* Name every inline object variant of a `oneOf`/`anyOf` schema from the
+* union's base name, keyed by variant schema identity; null, non-object and
+* `$ref` variants get no entry. Positions are local to this variant list, so
+* the union's TypeRef entries and the extracted models agree no matter what
+* else has been extracted. `reserved` holds the inline names the parent's
+* other properties mint (`reservedInlineNames`); every site that has a
+* sibling set passes the same one, so the reference and the model step
+* around them identically.
+*
+* One union shape is named differently: a `oneOf` with no explicit
+* `discriminator:` whose every variant carries a `$ref` or a `title` and pins
+* the same const property (`titleMappedDiscriminatorProperty`). Its
+* discriminator mapping has always named an inline variant by its title
+* (`resolveSchemaName(title)`: `Circle`, `Square`, run through the project's
+* schema-name transform like a component), and `schemaToTypeRef` references
+* the variant by that mapped name, so the title is the model name here too —
+* unless it is the base, already emitted, or reserved by a sibling, in which
+* case the variant takes a context-qualified name (its title as a prefix on
+* the base, `CircleDrawingMarker`, else a distinguishing property, else the
+* counter) and the mapping, which is read from this map, follows it. A kept
+* title is context-free: it is the same whatever field, array or map the
+* union sits under, so it names one shape wherever it appears, as a
+* component name would. A second union beside it using the same title for a
+* variant of the identical shape (`schemaShapeKey`) therefore shares the
+* model instead of stepping around it; a sibling giving the same title a
+* different shape reserves it (`reservedInlineNames`), and since both sides
+* read their siblings in isolation the decision is symmetric: when the
+* shapes differ, both unions fall back to their context-qualified names
+* (`CircleDrawingShape`, `CircleDrawingMarker`) and neither keeps the bare
+* `Circle`; when they are identical, both keep `Circle` and one model is
+* emitted. `elementContextName` never lets a context-free name drive an
+* items/values step-aside, which no context could satisfy.
+* `nameInlineVariantEntries` reports which names are context-free; a
+* fallen-back title name is context-dependent.
+*
+* This is the list-level entry point every site uses: `schemaToTypeRef` (via
+* `nameInlineObjectVariants`), `extractNestedSchema`,
+* `extractInlineModelDeep`, `extractInlineModelsFromProperties` and
+* `mintedInlineNames`.
+*/
+function nameInlineVariants(union, base, reserved = NO_RESERVED) {
+	const names = /* @__PURE__ */ new Map();
+	for (const [variant, entry] of nameInlineVariantEntries(union, base, reserved)) names.set(variant, entry.name);
+	return names;
+}
+/** `nameInlineVariants`, also telling for each name whether it is context-free. */
+function nameInlineVariantEntries(union, base, reserved = NO_RESERVED) {
+	const nonNullVariants = (union.oneOf ?? union.anyOf ?? []).filter((v) => !isNullVariantSchema(v));
+	const inlineObjectVariants = nonNullVariants.filter((v) => isInlineObjectSchema(v));
+	const discriminator = deriveConstNamingDiscriminator(inlineObjectVariants);
+	const titleMapped = union.oneOf !== void 0 && !union.discriminator && titleMappedDiscriminatorProperty(nonNullVariants) !== null;
+	const emitted = [];
+	const entries = /* @__PURE__ */ new Map();
+	for (const variant of inlineObjectVariants) {
+		let name = null;
+		let contextFree = false;
+		if (titleMapped) {
+			const titled = resolveVariantModelName(variant);
+			if (titled !== null) {
+				if (titled !== base && !emitted.includes(titled) && !reserved.has(titled)) {
+					name = titled;
+					contextFree = true;
+				} else name = nameUndiscriminatedVariant(variant, inlineObjectVariants, base, emitted, reserved);
 			}
 		}
+		name ??= nameInlineVariant(variant, inlineObjectVariants, base, emitted, discriminator, reserved);
+		emitted.push(name);
+		entries.set(variant, {
+			name,
+			contextFree
+		});
 	}
-	return `${parentName}${alreadyEmitted.length + 1}`;
+	return entries;
 }
 /**
 * Returns a discriminator descriptor when every inline object variant in a
 * oneOf has a string-const value on the same property — the signature of a
 * discriminated union without an explicit `discriminator:` keyword. Used by
-* `nameVariantModel` to derive variant names from the const values.
+* `nameInlineVariant` to derive variant names from the const values.
 *
 * Distinct from `detectConstPropertyDiscriminator` (which requires every
 * variant to carry a `$ref` or `title` so a name mapping can be built):
@@ -777,18 +1769,96 @@ function deriveConstNamingDiscriminator(variants) {
 	}
 	return null;
 }
-/** Build a single Field from a schema property entry. Shared across all extraction sites. */
-function buildFieldFromSchema(fieldName, fieldSchema, contextName, requiredSet) {
+/**
+* True for a schema that `schemaToTypeRef` turns into an inline model reference:
+* it declares `properties` directly (no `$ref`) and is an object — whether by
+* `type: 'object'`, by omitting `type`, or by an OAS 3.1 nullable array such as
+* `type: ['object', 'null']`. Every inline-model extractor must use the same
+* test, or a field's reference points at a model nobody materializes.
+*/
+function isInlineObjectSchema(schema) {
+	if (!schema || schema.$ref || !schema.properties) return false;
+	const { type } = schema;
+	return type === void 0 || type === "object" || Array.isArray(type) && type.includes("object");
+}
+/** The `{ type: 'null' }` member that marks a `oneOf`/`anyOf` as nullable; never a variant to name. */
+function isNullVariantSchema(schema) {
+	return schema.type === "null" || Array.isArray(schema.type) && schema.type.length === 1 && schema.type[0] === "null";
+}
+/**
+* The synthetic context names a multi-type inline variant's non-object
+* members are typed and extracted under, chosen so the models they name can
+* never collide with a model named from one of the variant's own properties.
+* An `array` member's items go under `item` (`<Variant>Item`), falling back
+* to `array_item` (`<Variant>ArrayItem`) and then `array_item2`,
+* `array_item3`, ... when a property already claims that name; any other
+* member goes under `value` (`<Variant>Value`), then `member_value`,
+* `member_value2`, .... A candidate is skipped when the model name
+* `qualifyInlineModelName` derives from it equals one derived from a
+* property — compared after qualification, so a property `items`, whose
+* name singularizes to `<Variant>Item`, blocks `item` as well.
+* This is the single source of these names for the TypeRef builder
+* (`inlineVariantTypeRef`) and the extractors (`variantMemberSchemas`).
+*/
+function variantMemberKeys(variant, variantName) {
+	const modelNameFor = (key) => qualifyInlineModelName(toPascalCase(key), variantName);
+	const claimed = new Set(Object.keys(variant.properties ?? {}).map(modelNameFor));
+	const pick = (preferred, fallback) => {
+		for (let i = 0;; i++) {
+			const candidate = i === 0 ? preferred : i === 1 ? fallback : `${fallback}${i}`;
+			if (!claimed.has(modelNameFor(candidate))) return candidate;
+		}
+	};
+	return {
+		item: pick("item", "array_item"),
+		value: pick("value", "member_value")
+	};
+}
+/**
+* The schemas carried by the non-object members of a multi-type inline
+* variant (`type: ['object', 'array']` with `items`), keyed by the synthetic
+* context name from `variantMemberKeys` that `schemaToTypeRef` types them
+* under, so an inline object item is `<Variant>Item` (or `<Variant>ArrayItem`
+* when `item` is taken) and its own nested objects `<Variant>ItemChild`.
+* Every extractor re-enters with these under the variant's name so the
+* models line up with the refs by construction. A map member cannot occur
+* here: a variant with `properties` is typed as a model, never as a map.
+*/
+function variantMemberSchemas(variant, variantName) {
+	const members = {};
+	if (Array.isArray(variant.type) && variant.type.includes("array") && variant.items) members[variantMemberKeys(variant, variantName).item] = variant.items;
+	return members;
+}
+/**
+* Build a single Field from a schema property entry. Shared across all
+* extraction sites. Pass `componentSchemas` where they are at hand so a
+* field whose schema is a bare `$ref` can take `example`/`examples` from the
+* component it points at, as a parameter does. `siblingProperties` are the
+* other properties of the object the field belongs to (`collectProperties`);
+* array items and map values use them to step aside from a sibling that
+* would take their singular name (`elementContextName`).
+*/
+function buildFieldFromSchema(fieldName, fieldSchema, contextName, requiredSet, componentSchemas, siblingProperties) {
+	const refTarget = resolveComponentSchemaRef(fieldSchema, componentSchemas);
+	const { example, examples } = resolveExamples([{
+		example: fieldSchema.example,
+		examples: nonEmptyExamples(fieldSchema.examples)
+	}, {
+		example: refTarget?.example,
+		examples: nonEmptyExamples(refTarget?.examples)
+	}]);
 	return {
 		name: fieldName,
-		type: schemaToTypeRef(fieldSchema, fieldName, contextName),
+		type: schemaToTypeRef(fieldSchema, fieldName, contextName, siblingProperties),
 		required: requiredSet.has(fieldName),
 		description: fieldSchema.description,
 		readOnly: fieldSchema.readOnly || void 0,
 		writeOnly: fieldSchema.writeOnly || void 0,
 		deprecated: fieldSchema.deprecated || void 0,
 		default: fieldSchema.default,
-		example: fieldSchema.example
+		example,
+		...examples ? { examples } : {},
+		...constraintsEntry(fieldSchema)
 	};
 }
 /**
@@ -825,39 +1895,27 @@ function buildSyntheticEnumRef(values, contextName, parentModelName) {
 	};
 }
 /**
-* Detect an implicit discriminator on an oneOf where every variant is an
-* object schema that pins the same property to a const value. Returns
-* { property, mapping } so the IR can represent the union as discriminated
-* without needing an explicit `discriminator:` key in the spec.
+* Detect an implicit discriminator on a `oneOf` whose every variant pins the
+* same property to a const value AND is nameable on its own — by a `$ref` to
+* a component or by a `title` — so the IR can represent the union as
+* discriminated, with a mapping to concrete names, without an explicit
+* `discriminator:` keyword. Returns the property, or null when any variant
+* doesn't fit the pattern or when the variants disagree on which property
+* carries the discriminator. The mapping itself is built by `schemaToTypeRef`
+* from the names `nameInlineVariants` gives the inline variants (their titles
+* unless taken) and the component names of `$ref` variants, so it can only
+* ever point at a model that exists.
 *
-* Both shapes are supported:
+* Both const shapes are supported:
 *   { properties: { event: { const: "x" } }, required: ["event"] }
 *   { properties: { event: { type: "string", enum: ["x"] } } }
-*
-* Returns null when any variant doesn't fit the pattern or when variants
-* disagree on which property carries the discriminator.
 */
-function detectConstPropertyDiscriminator(variants) {
+function titleMappedDiscriminatorProperty(variants) {
 	if (variants.length < 2) return null;
-	let candidateProperty = null;
+	if (!variants.every((v) => resolveVariantModelName(v) !== null)) return null;
 	const candidates = Object.keys(variants[0]?.properties ?? {});
-	for (const propName of candidates) if (variants.every((v) => getConstPropertyValue(v, propName) !== null)) {
-		candidateProperty = propName;
-		break;
-	}
-	if (!candidateProperty) return null;
-	const mapping = {};
-	for (const v of variants) {
-		const value = getConstPropertyValue(v, candidateProperty);
-		if (value === null) return null;
-		const variantName = resolveVariantModelName(v);
-		if (!variantName) return null;
-		mapping[value] = variantName;
-	}
-	return {
-		property: candidateProperty,
-		mapping
-	};
+	for (const propName of candidates) if (variants.every((v) => getConstPropertyValue(v, propName) !== null)) return propName;
+	return null;
 }
 function getConstPropertyValue(schema, property) {
 	const prop = schema.properties?.[property];
@@ -883,42 +1941,96 @@ function mapVariantToDiscriminatorEntry(variant, discriminator) {
 }
 /**
 * Derive a discriminator value → variant model name mapping for an inline-
-* variant `oneOf` whose explicit `discriminator:` has no `mapping:` clause.
-*
-* Each variant model name is reproduced via `nameVariantModel` so it matches
-* what `extractNestedSchema` registered when it walked the same `oneOf` to
-* pull variants out as named models. Variant 0 keeps the bare parent name
-* (e.g. `ApiKeyOwner`); subsequent variants get a const-derived prefix
-* (e.g. `UserApiKeyOwner` for the `type: const: user` variant).
-*
-* The "parent name" used here mirrors the one `collectNestedInlineModels`
-* passes to `extractNestedSchema`: it's the qualified inline model name
-* built from `contextName` (the field name) plus `parentModelName` (the
-* containing model). Returns null when any non-object variant is present
-* or when a variant lacks a const value on the discriminator property.
+* variant `oneOf` from the names `nameInlineVariants` gave its variants
+* (`inlineVariantNames`): the explicit `discriminator:` without a `mapping:`
+* clause, and the implicit const discriminator of anonymous inline variants
+* (`ApiKeyCreatedData.owner`: `ApiKeyCreatedDataOwner`,
+* `UserApiKeyCreatedDataOwner`). Reading the names rather than deriving them
+* again is what keeps the mapping pointing at models the extractors create.
+* Returns null without a context name, when any variant is not an inline
+* object, or when a variant lacks a const value on the property.
 */
-function deriveInlineVariantMapping(variants, discriminatorProperty, contextName, parentModelName) {
+function deriveInlineVariantMapping(variants, discriminatorProperty, contextName, inlineVariantNames) {
 	if (variants.length === 0 || !contextName) return null;
-	const inlineObjectVariants = variants.filter((v) => !v.$ref && v.properties && (v.type === "object" || !v.type));
-	if (inlineObjectVariants.length !== variants.length) return null;
-	const baseInlineName = qualifyInlineModelName(toPascalCase(contextName), parentModelName);
-	const namingDiscriminator = { property: discriminatorProperty };
 	const mapping = {};
-	const emittedSoFar = [];
-	for (const variant of inlineObjectVariants) {
+	for (const variant of variants) {
+		const variantName = inlineVariantNames.get(variant);
+		if (variantName === void 0) return null;
 		const constValue = getConstPropertyValue(variant, discriminatorProperty);
 		if (constValue === null) return null;
-		const variantName = nameVariantModel(variant, baseInlineName, emittedSoFar, namingDiscriminator);
 		mapping[constValue] = variantName;
-		emittedSoFar.push({
-			name: variantName,
-			fields: []
-		});
 	}
 	return mapping;
 }
+/**
+* The names reserved for a union typed under `contextName`: the set an
+* enclosing field handed down (`reservedNames`, for a union among a field's
+* array items or map values), else the inline names the field's own sibling
+* properties mint (`reservedInlineNames`), else nothing. The extractor
+* derives the same set at each of those levels, so the reference and the
+* model step around a sibling's name identically.
+*/
+function reservedNamesFor(contextName, siblingProperties, parentModelName, reservedNames) {
+	if (reservedNames) return reservedNames;
+	if (contextName === void 0) return NO_RESERVED;
+	return reservedInlineNames(contextName, siblingProperties, parentModelName);
+}
+/**
+* Name the inline object variants of a field's `oneOf`/`anyOf` exactly as the
+* inline-model extractors do (`extractInlineModelsFromProperties` in
+* inline-models.ts, and `extractNestedSchema` / `extractInlineModelDeep`
+* here): the union's base name is the field's qualified inline name, the
+* names the field's sibling properties mint — or the set handed down from an
+* enclosing field — are reserved (`reservedNamesFor`), and
+* `nameInlineVariants` hands out the variant names from there. Returned keyed
+* by variant schema identity.
+*/
+function nameInlineObjectVariants(union, contextName, parentModelName, siblingProperties, reservedNames) {
+	return nameInlineVariants(union, qualifyInlineModelName(toPascalCase(contextName ?? "UnknownModel"), parentModelName), reservedNamesFor(contextName, siblingProperties, parentModelName, reservedNames));
+}
+/**
+* The TypeRef for an inline object variant referenced by the name its
+* extracted model carries, keeping every other type the variant allows.
+* Mirrors what `schemaToTypeRef` builds for the same schema — one member per
+* non-null entry of a `type` array, `union`-wrapped when there is more than
+* one, `nullable`-wrapped when `null` or OAS 3.0 `nullable: true` is present
+* — with the `object` member swapped for the named ref:
+* `type: ['object', 'string']` → `union[model, string]`,
+* `['object', 'integer', 'null']` → `nullable<union[model, integer]>`,
+* `['object', 'null']` / `nullable: true` → `nullable<model>`.
+* A `oneOf: [X, { type: 'null' }]` variant has no `properties` of its own
+* and never reaches this path; `schemaToTypeRef` types it directly.
+*
+* Anything inline under a non-object member is named from the variant, never
+* from the union's field: an `array` member types its items under the
+* variant as parent with the context `variantMemberKeys` picks (`item` →
+* `<Variant>Item`, or `array_item` → `<Variant>ArrayItem` when a property
+* claims `item`), and any other member under its `value` key
+* (`<Variant>Value` for an inline enum, else `<Variant>MemberValue`). Naming
+* them from the field would hand variant 0's model name to every variant's
+* items.
+*/
+function inlineVariantTypeRef(variant, name) {
+	const modelRef = {
+		kind: "model",
+		name
+	};
+	const typeList = Array.isArray(variant.type) ? variant.type : [];
+	const nullable = variant.nullable === true || typeList.includes("null");
+	const keys = variantMemberKeys(variant, name);
+	const members = typeList.filter((t) => t !== "null").map((t) => t === "object" ? modelRef : schemaToTypeRef({
+		...variant,
+		type: t,
+		nullable: false
+	}, t === "array" ? keys.item : keys.value, name));
+	const ref = members.length > 1 ? {
+		kind: "union",
+		variants: members
+	} : modelRef;
+	return nullable ? asNullable(ref) : ref;
+}
 function extractEnum(name, schema) {
-	const values = (schema.enum ?? []).map((v) => ({
+	const values = nonNullEnumValues(schema.enum).map((v) => ({
 		name: toUpperSnakeCase(String(v)),
 		value: typeof v === "number" ? v : String(v),
 		description: void 0
@@ -934,9 +2046,10 @@ function extractModel(name, schema, schemas) {
 	if (schema.allOf) return extractAllOfModel(name, schema, schemas);
 	const requiredSet = new Set(schema.required ?? []);
 	const fields = [];
+	const siblings = collectProperties(schema, schemas);
 	for (const [fieldName, fieldSchema] of Object.entries(schema.properties ?? {})) {
 		if (!fieldSchema) continue;
-		fields.push(buildFieldFromSchema(fieldName, fieldSchema, name, requiredSet));
+		fields.push(buildFieldFromSchema(fieldName, fieldSchema, name, requiredSet, schemas, siblings));
 	}
 	if (fields.length === 0 && (schema.oneOf || schema.anyOf)) {
 		const variants = schema.oneOf ?? schema.anyOf ?? [];
@@ -947,7 +2060,7 @@ function extractModel(name, schema, schemas) {
 			for (const [fieldName, fieldSchema] of Object.entries(variant.properties)) {
 				if (!fieldSchema || seenFieldNames.has(fieldName)) continue;
 				seenFieldNames.add(fieldName);
-				fields.push(buildFieldFromSchema(fieldName, fieldSchema, name, emptyRequired));
+				fields.push(buildFieldFromSchema(fieldName, fieldSchema, name, emptyRequired, schemas, siblings));
 			}
 		}
 	}
@@ -968,12 +2081,14 @@ function extractModel(name, schema, schemas) {
 	return {
 		name,
 		description: schema.description,
-		fields
+		fields,
+		...constraintsEntry(schema)
 	};
 }
-function extractAllOfModel(name, schema, schemas) {
+function extractAllOfModel(name, schema, schemas, siblingProperties) {
 	const fields = [];
 	const requiredSet = /* @__PURE__ */ new Set();
+	const siblings = siblingProperties ?? collectProperties(schema, schemas);
 	let resultDiscriminator;
 	for (const subSchema of schema.allOf ?? []) {
 		let resolved = subSchema;
@@ -983,7 +2098,7 @@ function extractAllOfModel(name, schema, schemas) {
 			if (refName && schemas[refName]) resolved = schemas[refName];
 		}
 		if (resolved.allOf) {
-			const nested = extractAllOfModel(name, resolved, schemas);
+			const nested = extractAllOfModel(name, resolved, schemas, siblings);
 			for (const f of nested.fields) {
 				fields.push({
 					...f,
@@ -1003,7 +2118,7 @@ function extractAllOfModel(name, schema, schemas) {
 					for (const [fieldName, fieldSchema] of Object.entries(variant.properties)) {
 						if (!fieldSchema || seenFieldNames.has(fieldName)) continue;
 						seenFieldNames.add(fieldName);
-						fields.push(buildFieldFromSchema(fieldName, fieldSchema, name, emptyRequired));
+						fields.push(buildFieldFromSchema(fieldName, fieldSchema, name, emptyRequired, schemas, siblings));
 					}
 				}
 			}
@@ -1013,7 +2128,7 @@ function extractAllOfModel(name, schema, schemas) {
 				const emptyRequired = /* @__PURE__ */ new Set();
 				for (const [fieldName, fieldSchema] of Object.entries(resolved.properties)) {
 					if (!fieldSchema) continue;
-					fields.push(buildFieldFromSchema(fieldName, fieldSchema, name, emptyRequired));
+					fields.push(buildFieldFromSchema(fieldName, fieldSchema, name, emptyRequired, schemas, siblings));
 				}
 			}
 		}
@@ -1024,7 +2139,8 @@ function extractAllOfModel(name, schema, schemas) {
 		name,
 		description: schema.description,
 		fields,
-		...resultDiscriminator ? { discriminator: resultDiscriminator } : {}
+		...resultDiscriminator ? { discriminator: resultDiscriminator } : {},
+		...constraintsEntry(schema)
 	};
 }
 /**
@@ -1095,18 +2211,23 @@ function detectAllOfVariantDiscriminator(variants, fallbackName) {
 		mapping
 	};
 }
-function extractDiscriminatedAllOfVariantModels(schema, fallbackName) {
+function extractDiscriminatedAllOfVariantModels(schema, fallbackName, schemas) {
 	const models = [];
 	const seenNames = /* @__PURE__ */ new Set();
 	const baseProperties = {};
 	const baseRequired = /* @__PURE__ */ new Set();
+	let baseConstraints = ownConstraints(schema);
 	for (const subSchema of schema.allOf ?? []) {
-		if (subSchema.oneOf) continue;
+		if (subSchema.oneOf) {
+			baseConstraints = combineConstraints(baseConstraints, ownConstraints(subSchema));
+			continue;
+		}
 		const flat = subSchema.allOf ? flattenVariantForExtraction(subSchema) : subSchema;
 		if (flat.properties) {
 			for (const [k, v] of Object.entries(flat.properties)) if (!(k in baseProperties) && v) baseProperties[k] = v;
 		}
 		if (flat.required) for (const r of flat.required) baseRequired.add(r);
+		baseConstraints = combineConstraints(baseConstraints, extractConstraints(subSchema));
 	}
 	for (const subSchema of schema.allOf ?? []) for (const variant of subSchema.oneOf ?? []) {
 		const flat = flattenVariantForExtraction(variant);
@@ -1116,10 +2237,11 @@ function extractDiscriminatedAllOfVariantModels(schema, fallbackName) {
 		const merged = {
 			type: "object",
 			properties: mergedProperties,
-			required: [...new Set([...baseRequired, ...flat.required ?? []])]
+			required: [.../* @__PURE__ */ new Set([...baseRequired, ...flat.required ?? []])],
+			...combineConstraints(baseConstraints, extractConstraints(variant))
 		};
 		const variantName = deriveDiscriminatedVariantName(variant, fallbackName);
-		for (const model of extractInlineModelDeep(variantName, merged)) {
+		for (const model of extractInlineModelDeep(variantName, merged, schemas)) {
 			if (seenNames.has(model.name)) continue;
 			seenNames.add(model.name);
 			models.push(model);
@@ -1225,16 +2347,27 @@ function deriveDiscriminatedVariantName(schema, fallbackName) {
 	if (pascal.endsWith(fallbackName)) return pascal;
 	return `${fallbackName}${pascal}`;
 }
-function extractInlineModelDeep(name, schema) {
+function extractInlineModelDeep(name, schema, schemas) {
 	const requiredSet = new Set(schema.required ?? []);
 	const fields = [];
 	const properties = schema.properties ?? {};
 	const nestedModels = [];
+	const siblings = collectProperties(schema);
 	for (const [fieldName, fieldSchema] of Object.entries(properties)) {
 		if (!fieldSchema) continue;
-		fields.push(buildFieldFromSchema(fieldName, fieldSchema, name, requiredSet));
-		if (fieldSchema.type === "object" && fieldSchema.properties) nestedModels.push(...extractInlineModelDeep(qualifyNestedInlineName(name, fieldName), fieldSchema));
-		if (fieldSchema.type === "array" && fieldSchema.items?.properties) nestedModels.push(...extractInlineModelDeep(qualifyNestedInlineName(name, fieldName), fieldSchema.items));
+		fields.push(buildFieldFromSchema(fieldName, fieldSchema, name, requiredSet, schemas, siblings));
+		if (fieldSchema.type === "object" && fieldSchema.properties) nestedModels.push(...extractInlineModelDeep(qualifyNestedInlineName(name, fieldName), fieldSchema, schemas));
+		if (fieldSchema.type === "array" && fieldSchema.items?.properties) {
+			const itemContext = elementContextName(fieldName, "item", siblings, name, fieldSchema.items);
+			nestedModels.push(...extractInlineModelDeep(qualifyNestedInlineName(name, itemContext), fieldSchema.items, schemas));
+		}
+		if (fieldSchema.type === "object" && !fieldSchema.properties) {
+			const valueSchema = mapValueSchema(fieldSchema);
+			if (valueSchema && !valueSchema.$ref && valueSchema.properties) {
+				const valueContext = elementContextName(fieldName, "value", siblings, name, valueSchema);
+				nestedModels.push(...extractInlineModelDeep(qualifyNestedInlineName(name, valueContext), valueSchema, schemas));
+			}
+		}
 		if (fieldSchema.allOf) {
 			const mergedProperties = {};
 			const mergedRequired = [];
@@ -1245,22 +2378,20 @@ function extractInlineModelDeep(name, schema) {
 			if (Object.keys(mergedProperties).length > 0) nestedModels.push(...extractInlineModelDeep(qualifyNestedInlineName(name, fieldName), {
 				type: "object",
 				properties: mergedProperties,
-				required: mergedRequired
-			}));
+				required: mergedRequired,
+				...extractConstraints(fieldSchema)
+			}, schemas));
 		}
 		if (fieldSchema.oneOf) {
-			const inlineObjectVariants = fieldSchema.oneOf.filter((v) => !v.$ref && v.properties && (v.type === "object" || !v.type));
+			const inlineObjectVariants = fieldSchema.oneOf.filter((v) => isInlineObjectSchema(v));
 			if (inlineObjectVariants.length > 0) {
-				const baseQualified = qualifyNestedInlineName(name, fieldName);
-				const namingDisc = deriveConstNamingDiscriminator(inlineObjectVariants);
-				const emitted = [];
+				const variantNames = nameInlineVariants(fieldSchema, qualifyNestedInlineName(name, fieldName), reservedInlineNames(fieldName, siblings, name));
 				for (const variant of inlineObjectVariants) {
-					const variantName = nameVariantModel(variant, baseQualified, emitted, namingDisc);
-					emitted.push({
-						name: variantName,
-						fields: []
-					});
-					nestedModels.push(...extractInlineModelDeep(variantName, variant));
+					const variantName = variantNames.get(variant);
+					if (variantName === void 0) continue;
+					nestedModels.push(...extractInlineModelDeep(variantName, variant, schemas));
+					const memberSchemas = variantMemberSchemas(variant, variantName);
+					if (Object.keys(memberSchemas).length > 0) nestedModels.push(...extractInlineModelDeep(variantName, { properties: memberSchemas }, schemas).slice(1));
 				}
 			}
 		}
@@ -1268,7 +2399,8 @@ function extractInlineModelDeep(name, schema) {
 	return [{
 		name,
 		description: schema.description,
-		fields
+		fields,
+		...constraintsEntry(schema)
 	}, ...nestedModels];
 }
 function qualifyNestedInlineName(parentName, fieldName) {
@@ -1279,15 +2411,28 @@ function qualifyNestedInlineName(parentName, fieldName) {
 	if (match && match[2]) return match[1] + singularize(match[2]);
 	return qualified;
 }
-function schemaToTypeRef(schema, contextName, parentModelName) {
+/**
+* `elementContextName` for an optional context: with no field name there is
+* nothing to decide, and the items / values keep an undefined context.
+*/
+function elementContext(contextName, kind, siblingProperties, parentModelName, elementSchema) {
+	return contextName === void 0 ? void 0 : elementContextName(contextName, kind, siblingProperties, parentModelName, elementSchema);
+}
+function schemaToTypeRef(schema, contextName, parentModelName, siblingProperties, reservedNames) {
 	if (schema.$ref) {
 		const segments = schema.$ref.split("/");
 		const rawName = segments[segments.length - 1];
 		const resolved = resolveSchemaName(rawName);
-		if (activeEnumSchemaNames.has(resolved)) return {
-			kind: "enum",
-			name: resolved
-		};
+		if (activeEnumSchemaNames.has(resolved)) {
+			const enumRef = {
+				kind: "enum",
+				name: resolved
+			};
+			return activeNullableEnumSchemaNames.has(resolved) ? {
+				kind: "nullable",
+				inner: enumRef
+			} : enumRef;
+		}
 		return {
 			kind: "model",
 			name: resolved
@@ -1302,21 +2447,18 @@ function schemaToTypeRef(schema, contextName, parentModelName) {
 				type: "unknown"
 			}
 		};
-		if (schema.type.includes("null") && nonNullTypes.length === 1) return {
-			kind: "nullable",
-			inner: schemaToTypeRef({
-				...schema,
-				type: nonNullTypes[0],
-				nullable: false
-			}, contextName)
-		};
+		if (schema.type.includes("null") && nonNullTypes.length === 1) return asNullable(schemaToTypeRef({
+			...schema,
+			type: nonNullTypes[0],
+			nullable: false
+		}, contextName, parentModelName, siblingProperties, reservedNames));
 		if (nonNullTypes.length > 1) {
 			const ref = {
 				kind: "union",
 				variants: nonNullTypes.map((t) => schemaToTypeRef({
 					...schema,
 					type: t
-				}, contextName))
+				}, contextName, parentModelName, siblingProperties, reservedNames))
 			};
 			if (schema.type.includes("null")) return {
 				kind: "nullable",
@@ -1325,13 +2467,10 @@ function schemaToTypeRef(schema, contextName, parentModelName) {
 			return ref;
 		}
 	}
-	if (schema.nullable && schema.type) return {
-		kind: "nullable",
-		inner: schemaToTypeRef({
-			...schema,
-			nullable: false
-		}, contextName)
-	};
+	if (schema.nullable && schema.type) return asNullable(schemaToTypeRef({
+		...schema,
+		nullable: false
+	}, contextName, parentModelName, siblingProperties, reservedNames));
 	if (schema.allOf) {
 		const refItem = schema.allOf.find((s) => s.$ref);
 		if (refItem) {
@@ -1341,7 +2480,7 @@ function schemaToTypeRef(schema, contextName, parentModelName) {
 			};
 			return schemaToTypeRef(refItem, contextName, parentModelName);
 		}
-		if (schema.allOf.length === 1) return schemaToTypeRef(schema.allOf[0], contextName, parentModelName);
+		if (schema.allOf.length === 1) return schemaToTypeRef(schema.allOf[0], contextName, parentModelName, siblingProperties, reservedNames);
 		if (schema.allOf.some((s) => s.properties)) return {
 			kind: "model",
 			name: qualifyInlineModelName(toPascalCase(contextName ?? "UnknownModel"), parentModelName)
@@ -1350,12 +2489,9 @@ function schemaToTypeRef(schema, contextName, parentModelName) {
 	if (schema.oneOf || schema.anyOf) {
 		const compositionKind = schema.oneOf ? "oneOf" : "anyOf";
 		const rawVariants = schema.oneOf ?? schema.anyOf ?? [];
-		const nullVariant = rawVariants.find((v) => v.type === "null" || Array.isArray(v.type) && v.type.length === 1 && v.type[0] === "null");
+		const nullVariant = rawVariants.find(isNullVariantSchema);
 		const nonNullVariants = rawVariants.filter((v) => v !== nullVariant);
-		if (nullVariant && nonNullVariants.length === 1) return {
-			kind: "nullable",
-			inner: schemaToTypeRef(nonNullVariants[0], contextName, parentModelName)
-		};
+		if (nullVariant && nonNullVariants.length === 1) return asNullable(schemaToTypeRef(nonNullVariants[0], contextName, parentModelName, siblingProperties, reservedNames));
 		const literalStrings = collectLiteralStringConsts(nonNullVariants);
 		if (literalStrings !== null && literalStrings.length >= 2) {
 			const enumRef = buildSyntheticEnumRef(literalStrings, contextName, parentModelName);
@@ -1364,13 +2500,14 @@ function schemaToTypeRef(schema, contextName, parentModelName) {
 				inner: enumRef
 			} : enumRef;
 		}
+		const inlineVariantNames = nameInlineObjectVariants(schema, contextName, parentModelName, siblingProperties, reservedNames);
 		let resolvedDiscriminator;
 		if (schema.discriminator) {
 			const property = schema.discriminator.propertyName;
 			const explicitMapping = schema.discriminator.mapping ?? {};
 			let mapping = Object.fromEntries(Object.entries(explicitMapping).map(([k, v]) => [k, v.replace(/^#\/components\/schemas\//, "")]));
 			if (Object.keys(mapping).length === 0) {
-				const inlineMapping = deriveInlineVariantMapping(nonNullVariants, property, contextName, parentModelName);
+				const inlineMapping = deriveInlineVariantMapping(nonNullVariants, property, contextName, inlineVariantNames);
 				if (inlineMapping) mapping = inlineMapping;
 			}
 			resolvedDiscriminator = {
@@ -1378,12 +2515,22 @@ function schemaToTypeRef(schema, contextName, parentModelName) {
 				mapping
 			};
 		} else if (compositionKind === "oneOf") {
-			const synthetic = detectConstPropertyDiscriminator(nonNullVariants);
-			if (synthetic) resolvedDiscriminator = synthetic;
-			else {
+			const titleProperty = titleMappedDiscriminatorProperty(nonNullVariants);
+			if (titleProperty) {
+				const mapping = {};
+				for (const v of nonNullVariants) {
+					const value = getConstPropertyValue(v, titleProperty);
+					const mappedName = inlineVariantNames.get(v) ?? resolveVariantModelName(v);
+					if (value !== null && mappedName !== null) mapping[value] = mappedName;
+				}
+				resolvedDiscriminator = {
+					property: titleProperty,
+					mapping
+				};
+			} else {
 				const namingDisc = deriveConstNamingDiscriminator(nonNullVariants);
 				if (namingDisc) {
-					const inlineMapping = deriveInlineVariantMapping(nonNullVariants, namingDisc.property, contextName, parentModelName);
+					const inlineMapping = deriveInlineVariantMapping(nonNullVariants, namingDisc.property, contextName, inlineVariantNames);
 					if (inlineMapping) resolvedDiscriminator = {
 						property: namingDisc.property,
 						mapping: inlineMapping
@@ -1394,12 +2541,11 @@ function schemaToTypeRef(schema, contextName, parentModelName) {
 		const variants = [];
 		for (const v of rawVariants) {
 			if (v === nullVariant) continue;
-			const inlineMappingName = resolvedDiscriminator && !v.$ref && v.properties && (v.type === "object" || !v.type) ? mapVariantToDiscriminatorEntry(v, resolvedDiscriminator) : null;
-			if (inlineMappingName) variants.push({
-				kind: "model",
-				name: inlineMappingName
-			});
-			else variants.push(schemaToTypeRef(v, contextName, parentModelName));
+			const inlineName = inlineVariantNames.get(v);
+			if (inlineName) {
+				const mappedName = resolvedDiscriminator ? mapVariantToDiscriminatorEntry(v, resolvedDiscriminator) : null;
+				variants.push(inlineVariantTypeRef(v, mappedName ?? inlineName));
+			} else variants.push(schemaToTypeRef(v, contextName, parentModelName));
 		}
 		const hasNull = !!nullVariant;
 		const union = {
@@ -1442,30 +2588,30 @@ function schemaToTypeRef(schema, contextName, parentModelName) {
 			};
 		}
 	}
-	if (schema.enum && schema.enum.length === 1) {
-		const v = schema.enum[0];
-		return {
+	const enumValues = nonNullEnumValues(schema.enum);
+	const enumAdmitsNull = schema.enum !== void 0 && enumValues.length !== schema.enum.length;
+	if (schema.enum && enumValues.length === 1) {
+		const v = enumValues[0];
+		const literal = {
 			kind: "literal",
 			value: typeof v === "number" ? v : String(v)
 		};
+		return enumAdmitsNull ? asNullable(literal) : literal;
 	}
 	if (schema.enum) {
 		const baseName = toPascalCase(contextName ?? "UnknownEnum");
 		const cleanParent = parentModelName ? stripListItemMarkers(parentModelName) : void 0;
 		const qualifiedName = cleanParent && !baseName.startsWith(cleanParent) ? `${cleanParent}${baseName}` : baseName;
-		return {
+		const enumRef = {
 			kind: "enum",
 			name: activeSchemaNameTransform ? activeSchemaNameTransform(qualifiedName) : qualifiedName,
-			values: schema.enum.map((v) => typeof v === "number" ? v : String(v))
+			values: enumValues.map((v) => typeof v === "number" ? v : String(v))
 		};
+		return enumAdmitsNull ? asNullable(enumRef) : enumRef;
 	}
-	if (schema.type === "array" && schema.items) return {
+	if ((schema.type === "array" || !schema.type) && schema.items) return {
 		kind: "array",
-		items: schemaToTypeRef(schema.items, contextName, parentModelName)
-	};
-	if (!schema.type && schema.items) return {
-		kind: "array",
-		items: schemaToTypeRef(schema.items, contextName, parentModelName)
+		items: schemaToTypeRef(schema.items, elementContext(contextName, "item", siblingProperties, parentModelName, schema.items), parentModelName, void 0, reservedNamesFor(contextName, siblingProperties, parentModelName, reservedNames))
 	};
 	if (schema.type === "object" && schema.properties) return {
 		kind: "model",
@@ -1476,12 +2622,8 @@ function schemaToTypeRef(schema, contextName, parentModelName) {
 			kind: "primitive",
 			type: "unknown"
 		};
-		if (schema.additionalProperties && typeof schema.additionalProperties === "object") {
-			if (Object.keys(schema.additionalProperties).length > 0) valueType = schemaToTypeRef(schema.additionalProperties, contextName);
-		} else if (schema.patternProperties) {
-			const patterns = Object.values(schema.patternProperties);
-			if (patterns.length > 0) valueType = schemaToTypeRef(patterns[0], contextName);
-		}
+		const valueSchema = mapValueSchema(schema);
+		if (valueSchema) valueType = schemaToTypeRef(valueSchema, elementContext(contextName, "value", siblingProperties, parentModelName, valueSchema), parentModelName, void 0, reservedNamesFor(contextName, siblingProperties, parentModelName, reservedNames));
 		return {
 			kind: "map",
 			valueType
@@ -1581,11 +2723,11 @@ function classifyAndExtractResponse(schema, contextName, componentSchemas) {
 		isPaginated: false
 	};
 	const envelope = detectListEnvelope(schema);
-	if (envelope.isEnvelope) return extractListResponse(schema, contextName, envelope.dataPath);
-	if (isSingleResourceWrapper(schema)) return extractWrappedResource(schema, contextName);
+	if (envelope.isEnvelope) return extractListResponse(schema, contextName, envelope.dataPath, componentSchemas);
+	if (isSingleResourceWrapper(schema)) return extractWrappedResource(schema, contextName, componentSchemas);
 	return extractDirectResource(schema, contextName, componentSchemas);
 }
-const KNOWN_DATA_PATHS = new Set([
+const KNOWN_DATA_PATHS = /* @__PURE__ */ new Set([
 	"data",
 	"items",
 	"results",
@@ -1643,33 +2785,27 @@ function detectListEnvelope(schema) {
 		dataPath: null
 	};
 }
-function extractListResponse(schema, contextName, dataPath) {
+function extractListResponse(schema, contextName, dataPath, componentSchemas) {
 	let itemTypeRef = {
 		kind: "primitive",
 		type: "string"
 	};
 	const inlineModels = [];
-	const propSources = [];
-	if (schema.allOf) {
-		for (const sub of schema.allOf) if (sub.properties) propSources.push(sub.properties);
-	}
-	if (schema.properties) propSources.push(schema.properties);
-	for (const props of propSources) {
-		const dataProp = props[dataPath];
-		if (!dataProp) continue;
-		if (dataProp.type === "array" && dataProp.items) {
-			const items = dataProp.items;
-			if (items.$ref) itemTypeRef = schemaToTypeRef(items, contextName);
-			else if (items.type === "object" && items.properties) {
-				const itemName = contextName.replace(/Response$/, "") + "Item";
-				itemTypeRef = {
-					kind: "model",
-					name: itemName
-				};
-				inlineModels.push(...extractInlineModel(itemName, items));
-			}
+	const { properties, required } = collectEnvelopeProperties(schema, componentSchemas);
+	const dataProp = properties[dataPath];
+	if (dataProp?.type === "array" && dataProp.items) {
+		const items = dataProp.items;
+		if (items.$ref) itemTypeRef = schemaToTypeRef(items, contextName);
+		else if (items.type === "object" && items.properties) {
+			const itemName = contextName.replace(/Response$/, "") + "Item";
+			itemTypeRef = {
+				kind: "model",
+				name: itemName
+			};
+			inlineModels.push(...extractInlineModel(itemName, items, componentSchemas));
 		}
 	}
+	const { envelopeFields, envelopeCompanions } = extractEnvelopeCompanions(properties, required, dataPath, contextName.replace(/Response$/, ""), componentSchemas);
 	return {
 		response: {
 			kind: "array",
@@ -1678,7 +2814,117 @@ function extractListResponse(schema, contextName, dataPath) {
 		inlineModels,
 		isPaginated: true,
 		dataPath,
-		itemType: itemTypeRef
+		itemType: itemTypeRef,
+		envelopeFields,
+		envelopeCompanions: envelopeCompanions.length > 0 ? envelopeCompanions : void 0
+	};
+}
+/**
+* Every property the envelope declares, merged across its `allOf` branches,
+* with the `required` lists that go with them.
+*
+* A `$ref` branch is resolved against the component schemas so fields an
+* envelope inherits from a shared base (`trace_id` on every response, say)
+* are not silently dropped. A property declared by more than one branch keeps
+* both declarations' shape when both are inline objects — `pagination.next`
+* from one branch and `pagination.total` from another both belong to the
+* response — and otherwise takes the later declaration, as `allOf` merging
+* does elsewhere in the parser.
+*/
+function collectEnvelopeProperties(schema, componentSchemas) {
+	const properties = {};
+	const required = [];
+	const seenRefs = /* @__PURE__ */ new Set();
+	const visit = (s) => {
+		if (s.$ref) {
+			if (seenRefs.has(s.$ref)) return;
+			seenRefs.add(s.$ref);
+			const refName = s.$ref.split("/").pop();
+			const resolved = refName ? componentSchemas?.[refName] : void 0;
+			if (resolved) visit(resolved);
+			return;
+		}
+		for (const sub of s.allOf ?? []) visit(sub);
+		for (const [key, prop] of Object.entries(s.properties ?? {})) {
+			if (!prop) continue;
+			const existing = properties[key];
+			properties[key] = existing ? mergePropertyDeclarations(existing, prop) : prop;
+		}
+		if (s.required) required.push(...s.required);
+	};
+	visit(schema);
+	return {
+		properties,
+		required
+	};
+}
+/**
+* Combine two `allOf` declarations of one property. Inline objects merge their
+* fields; an array keeps the earlier `items` when the later declaration only
+* constrains it (`minItems: 1`), so `data: User[]` is not downgraded to
+* `string[]`; anything else takes the later declaration.
+*/
+function mergePropertyDeclarations(earlier, later) {
+	if (isInlineObjectSchema(earlier) && isInlineObjectSchema(later)) return {
+		...earlier,
+		...later,
+		properties: {
+			...earlier.properties,
+			...later.properties
+		},
+		required: [...earlier.required ?? [], ...later.required ?? []]
+	};
+	if (earlier.type === "array" && later.type === "array") return {
+		...earlier,
+		...later,
+		items: later.items ?? earlier.items
+	};
+	return later;
+}
+/**
+* Type a list envelope's companion properties as fields, lifting any inline
+* object among them (and anything nested inside it) to a model.
+*
+* Models come from `extractInlineModelsFromProperties`, the extractor that
+* mirrors `schemaToTypeRef` form for form — plain, nullable and `allOf`
+* objects, arrays of objects, and every `oneOf`/`anyOf` object variant — so a
+* field's reference always has a model behind it.
+*
+* Each companion is extracted twice: once under the operation's name, which
+* is how its models enter the IR (`ListUsersListMetadata`), and once under no
+* parent, which yields the name each model would carry if named from its
+* property alone (`ListMetadata`). Both runs walk the same code path, so the
+* two model lists line up index for index. `resolveEnvelopeCompanionNames`
+* later picks, per companion, which of the two names survives — the bare one
+* only where every copy of that companion across the API agrees structurally.
+*/
+function extractEnvelopeCompanions(properties, required, dataPath, operationName, componentSchemas) {
+	const envelopeFields = [];
+	const envelopeCompanions = [];
+	const requiredSet = new Set(required);
+	const siblings = collectProperties({ properties });
+	for (const [key, propSchema] of Object.entries(properties)) {
+		if (key === dataPath) continue;
+		const field = buildFieldFromSchema(key, propSchema, operationName, requiredSet, componentSchemas, siblings);
+		envelopeFields.push(field);
+		const single = {
+			type: "object",
+			properties: { [key]: propSchema }
+		};
+		const models = [];
+		extractInlineModelsFromProperties(single, models, operationName, componentSchemas, siblings);
+		if (models.length === 0) continue;
+		const bare = [];
+		extractInlineModelsFromProperties(single, bare, void 0, componentSchemas, siblings);
+		envelopeCompanions.push({
+			field,
+			models,
+			bareNames: bare.map((m) => m.name)
+		});
+	}
+	return {
+		envelopeFields,
+		envelopeCompanions
 	};
 }
 function hasDiscriminantConstField(schema) {
@@ -1724,7 +2970,7 @@ function isSingleResourceWrapper(schema) {
 	if (propSchema.oneOf) return propSchema.oneOf.some((v) => v.type === "object" && hasDiscriminantConstField(v) !== null);
 	return false;
 }
-function extractWrappedResource(schema, contextName) {
+function extractWrappedResource(schema, contextName, componentSchemas) {
 	const props = schema.properties;
 	const propSchema = props[schema.required && schema.required.length === 1 ? schema.required[0] : Object.keys(props)[0]];
 	const inlineModels = [];
@@ -1733,7 +2979,7 @@ function extractWrappedResource(schema, contextName) {
 		const objectVariant = propSchema.oneOf.find((v) => v.type === "object" && hasDiscriminantConstField(v) !== null);
 		if (objectVariant) {
 			const modelName = deriveModelName(objectVariant, resourceName);
-			inlineModels.push(...extractInlineModel(modelName, objectVariant));
+			inlineModels.push(...extractInlineModel(modelName, objectVariant, componentSchemas));
 			const hasNullVariant = propSchema.oneOf.some((v) => v.type === "null" || Array.isArray(v.type) && v.type.includes("null"));
 			const modelRef = {
 				kind: "model",
@@ -1750,7 +2996,7 @@ function extractWrappedResource(schema, contextName) {
 		}
 	}
 	const modelName = deriveModelName(propSchema, resourceName);
-	inlineModels.push(...extractInlineModel(modelName, propSchema));
+	inlineModels.push(...extractInlineModel(modelName, propSchema, componentSchemas));
 	return {
 		response: {
 			kind: "model",
@@ -1764,7 +3010,7 @@ function extractDirectResource(schema, contextName, componentSchemas) {
 	const inlineModels = [];
 	if (schema.properties && (schema.type === "object" || !schema.type)) {
 		const modelName = deriveModelName(schema, contextName);
-		inlineModels.push(...extractInlineModel(modelName, schema));
+		inlineModels.push(...extractInlineModel(modelName, schema, componentSchemas));
 		return {
 			response: {
 				kind: "model",
@@ -1811,10 +3057,11 @@ function extractDirectResource(schema, contextName, componentSchemas) {
 			const merged = {
 				type: "object",
 				properties: mergedProperties,
-				required: mergedRequired
+				required: mergedRequired,
+				...extractConstraints(schema)
 			};
 			const modelName = mergedRefFields ? toPascalCase(contextName) : deriveModelName(merged, contextName);
-			inlineModels.push(...extractInlineModel(modelName, merged));
+			inlineModels.push(...extractInlineModel(modelName, merged, componentSchemas));
 			return {
 				response: {
 					kind: "model",
@@ -1825,12 +3072,7 @@ function extractDirectResource(schema, contextName, componentSchemas) {
 			};
 		}
 	}
-	if (schema.oneOf) {
-		for (const variant of schema.oneOf) if (variant.properties && (variant.type === "object" || !variant.type)) {
-			const modelName = deriveModelName(variant, contextName);
-			if (!new Set(inlineModels.map((m) => m.name)).has(modelName)) inlineModels.push(...extractInlineModel(modelName, variant));
-		}
-	}
+	if (schema.oneOf) extractInlineModelsFromProperties({ properties: { [contextName]: schema } }, inlineModels, void 0, componentSchemas);
 	if (schema.type === "array" && schema.items) {
 		const items = schema.items;
 		if (items.$ref) return {
@@ -1843,7 +3085,7 @@ function extractDirectResource(schema, contextName, componentSchemas) {
 		};
 		if (items.properties && (items.type === "object" || !items.type)) {
 			const itemName = contextName.replace(/Response$/, "") + "Item";
-			inlineModels.push(...extractInlineModel(itemName, items));
+			inlineModels.push(...extractInlineModel(itemName, items, componentSchemas));
 			return {
 				response: {
 					kind: "array",
@@ -1869,74 +3111,292 @@ function deriveModelName(schema, fallback) {
 		const field = schema.properties[name];
 		if (field && field.const && typeof field.const === "string") return toPascalCase(field.const);
 	}
-	for (const [, field] of Object.entries(schema.properties)) if (field && field.const && typeof field.const === "string") return toPascalCase(field.const);
-	return toPascalCase(fallback);
+	for (const [, field] of Object.entries(schema.properties)) if (field && field.const && typeof field.const === "string") return toPascalCase(field.const);
+	return toPascalCase(fallback);
+}
+/**
+* Materialise an inline response object (and every nested inline object
+* under it) as models. `componentSchemas` only feeds `buildFieldFromSchema`,
+* so a response field that `$ref`s a component takes the component's
+* `example`/`examples` exactly as a request-body or component-model field
+* does; nested models get the same map so the fallback reaches every level.
+*/
+function extractInlineModel(name, schema, componentSchemas) {
+	const requiredSet = new Set(schema.required ?? []);
+	const fields = [];
+	const properties = schema.properties ?? {};
+	const nestedModels = [];
+	const siblings = collectProperties(schema);
+	for (const [fieldName, fieldSchema] of Object.entries(properties)) {
+		if (!fieldSchema) continue;
+		fields.push(buildFieldFromSchema(fieldName, fieldSchema, name, requiredSet, componentSchemas, siblings));
+	}
+	extractInlineModelsFromProperties(schema, nestedModels, name, componentSchemas);
+	return [{
+		name,
+		description: schema.description,
+		fields,
+		...constraintsEntry(schema)
+	}, ...nestedModels];
+}
+//#endregion
+//#region src/parser/security.ts
+/**
+* Convert a document- or operation-level `security` list into the IR shape,
+* preserving what the list says rather than flattening it:
+*
+* - absent (or not a list) → `undefined`: nothing declared here.
+* - `[]` → `[]`: no authentication required.
+* - `[{ a: [] }, { b: [] }]` → `[[a], [b]]`: either scheme suffices.
+* - `[{ a: [], b: [] }]` → `[[a, b]]`: both schemes are required together.
+* - `[{ a: [] }, {}]` → `[[a], []]`: the empty set is an anonymous alternative,
+*   which is how a document marks authentication optional.
+*
+* An entry that is not an object (`null`, say) is not a requirement object.
+* Reading it as `{}` would declare an anonymous alternative and make the
+* operation look open, so it is dropped with an `[oagen] Warning:` naming
+* `context` (the operation, or the document). A non-empty list left with no
+* valid entry is treated as undeclared (`undefined`) rather than as `[]`:
+* the document never said "no authentication", so the operation keeps
+* inheriting the default.
+*
+* The previous flattening collapsed the alternatives onto one list and turned
+* `[]` into `undefined`, so "no auth" read the same as "use the default" and
+* "either of" the same as "all of" (#182).
+*/
+function extractSecurityRequirements(security, context) {
+	if (!Array.isArray(security)) return void 0;
+	const sets = [];
+	for (const entry of security) {
+		if (entry === null || typeof entry !== "object" || Array.isArray(entry)) {
+			console.warn(`[oagen] Warning: Ignoring security requirement ${JSON.stringify(entry)} on ${context} — not a requirement object`);
+			continue;
+		}
+		sets.push(Object.entries(entry).map(([schemeName, scopes]) => ({
+			schemeName,
+			scopes: Array.isArray(scopes) ? scopes : []
+		})));
+	}
+	if (security.length > 0 && sets.length === 0) {
+		console.warn(`[oagen] Warning: No valid security requirement on ${context}; treating security as undeclared`);
+		return;
+	}
+	return sets;
+}
+//#endregion
+//#region src/parser/envelope-companion-names.ts
+/**
+* Decide the final name of every lifted companion model, across all list
+* operations at once, and return the models to merge into the IR.
+*
+* The same envelope recurs on every list endpoint of an API, so naming each
+* copy after its operation would mint one identical `ListMetadata` per
+* endpoint. But naming by property alone is only safe while the copies agree:
+* `mergeInlineResponseModels` keeps the largest model of a name, so a
+* `pagination` with three fields would silently replace an unrelated
+* `Pagination` component, or absorb another endpoint's two-field `pagination`.
+*
+* So a companion takes its bare name only when that cannot change any other
+* type's shape:
+*
+* Copies are compared structurally — field names, requiredness and each
+* field's shape, with nested models resolved and inline enums compared by
+* value — never by name alone. A copy collapses onto a target shape only when
+* the target *admits* every value the copy can hold: the same fields with the
+* same types, where the target may be looser (a field the copy requires may be
+* optional on the target, a non-null copy field may be nullable there) but
+* never stricter. Widening a response type loses no data a reader can see;
+* narrowing it would promise fields the wire may omit.
+*
+* - When a component model of that name exists — compared after the parser's
+*   own renaming, so `PaginationDto` → `Pagination` is caught — the copies it
+*   admits collapse onto it (the component stays as written); the others keep
+*   their operation-qualified name.
+* - Otherwise the most common exact shape (first declared, on a tie) becomes
+*   the target: it and every copy it admits take the bare name; any other
+*   copy keeps its operation-qualified name.
+*
+* The comparison covers the companion's whole field type, so a `oneOf`
+* companion is judged on every variant, not just the first, and a copy folds
+* among copies only when its lifted models line up name for name with the
+* target's (same variants, same order); onto a component, only a companion
+* whose field references exactly its own lifted model can fold.
+*
+* Only the target's definition survives a collapse. The admitted copies'
+* models are dropped rather than handed to the merge pass, which keeps the
+* first model of a name and would let a stricter copy declared earlier
+* narrow the shared type for everyone; their field references are repointed
+* at the target's models instead.
+*
+* Enums declared inline in a companion stay operation-qualified, exactly like
+* enums declared inline in a parameter.
+*/
+function resolveEnvelopeCompanionNames(companions, componentModels) {
+	const byBareName = /* @__PURE__ */ new Map();
+	/** Copies folded onto another definition; their own models are not emitted. */
+	const folded = /* @__PURE__ */ new Set();
+	for (const companion of companions) {
+		if (companion.models.length === 0) continue;
+		const bare = companion.bareNames[0];
+		const group = byBareName.get(bare) ?? [];
+		group.push(companion);
+		byBareName.set(bare, group);
+	}
+	const componentMap = new Map((componentModels ?? []).map((m) => [m.name, m]));
+	const localMap = (c) => new Map(c.models.map((m) => [m.name, m]));
+	const unwrap = (t) => t.kind === "nullable" ? t.inner : t;
+	for (const [bare, group] of byBareName) {
+		let folds;
+		let finalNames;
+		let owner;
+		const component = componentMap.get(bare);
+		if (component) {
+			const targetType = {
+				kind: "model",
+				name: component.name
+			};
+			finalNames = [component.name];
+			folds = (c) => {
+				const refs = collectModelRefs(c.field.type);
+				if (refs.length !== 1 || refs[0] !== c.models[0].name) return false;
+				return typeAdmits(targetType, componentMap, unwrap(c.field.type), localMap(c), /* @__PURE__ */ new Set());
+			};
+		} else {
+			const counts = /* @__PURE__ */ new Map();
+			for (const c of group) {
+				const key = `${fingerprintType$1(unwrap(c.field.type), localMap(c), /* @__PURE__ */ new Set())}|${c.bareNames.join(",")}`;
+				const seen = counts.get(key);
+				if (seen) seen.n += 1;
+				else counts.set(key, {
+					n: 1,
+					first: c
+				});
+			}
+			let best = {
+				n: 0,
+				first: group[0]
+			};
+			for (const entry of counts.values()) if (entry.n > best.n) best = entry;
+			owner = best.first;
+			finalNames = owner.bareNames;
+			const ownerType = unwrap(owner.field.type);
+			const ownerMap = localMap(owner);
+			const ownerNames = owner.bareNames;
+			folds = (c) => c.bareNames.length === ownerNames.length && c.bareNames.every((name, i) => name === ownerNames[i]) && typeAdmits(ownerType, ownerMap, unwrap(c.field.type), localMap(c), /* @__PURE__ */ new Set());
+		}
+		const collapsing = group.filter(folds);
+		for (const companion of collapsing) {
+			renameCompanion(companion, finalNames);
+			if (companion !== owner) folded.add(companion);
+		}
+	}
+	return companions.filter((c) => !folded.has(c)).flatMap((c) => c.models);
+}
+/**
+* Rename a companion's models to `names` (index-aligned with `models`) and
+* repoint every reference, in its field and inside its models.
+*/
+function renameCompanion(companion, names) {
+	const renames = /* @__PURE__ */ new Map();
+	companion.models.forEach((model, i) => {
+		const name = names[i];
+		if (name !== void 0 && model.name !== name) renames.set(model.name, name);
+	});
+	if (renames.size === 0) return;
+	const repoint = (ref) => {
+		walkTypeRef(ref, { model: (r) => {
+			const renamed = renames.get(r.name);
+			if (renamed !== void 0) r.name = renamed;
+		} });
+	};
+	repoint(companion.field.type);
+	for (const model of companion.models) {
+		model.name = renames.get(model.name) ?? model.name;
+		for (const field of model.fields) repoint(field.type);
+	}
 }
 /**
-* Qualify a nested inline model name with its parent to avoid generic names.
-* e.g., parent="Connection" + field="domains" → "ConnectionDomain" (singularized)
-* Only qualifies when the field name alone would be too generic.
+* Whether `target` admits every value `copy` can hold: the same field names,
+* each field's type admitted (see `typeAdmits`), and no field the target
+* requires that the copy leaves optional. Nested models resolve through their
+* respective maps and are compared the same way; a model neither map resolves
+* is compared by name.
 */
-function qualifyNestedName(parentName, fieldName) {
-	const pascalField = toPascalCase(fieldName);
-	if (pascalField.startsWith(parentName)) return pascalField;
-	const qualified = `${stripListItemMarkers(parentName)}${pascalField}`;
-	const match = qualified.match(/^(.+?)([A-Z][a-z]+s?)$/);
-	if (match && match[2]) {
-		const trailing = singularize(match[2]);
-		return match[1] + trailing;
+function admits(target, targetMap, copy, copyMap, visiting) {
+	const key = `${target.name}|${copy.name}`;
+	if (visiting.has(key)) return true;
+	visiting.add(key);
+	try {
+		if (target.fields.length !== copy.fields.length) return false;
+		const targetFields = new Map(target.fields.map((f) => [f.name, f]));
+		for (const field of copy.fields) {
+			const expected = targetFields.get(field.name);
+			if (!expected) return false;
+			if (expected.required && !field.required) return false;
+			if (!typeAdmits(expected.type, targetMap, field.type, copyMap, visiting)) return false;
+		}
+		return true;
+	} finally {
+		visiting.delete(key);
 	}
-	return qualified;
 }
-function extractInlineModel(name, schema) {
-	const requiredSet = new Set(schema.required ?? []);
-	const fields = [];
-	const properties = schema.properties ?? {};
-	const nestedModels = [];
-	for (const [fieldName, fieldSchema] of Object.entries(properties)) {
-		if (!fieldSchema) continue;
-		fields.push(buildFieldFromSchema(fieldName, fieldSchema, name, requiredSet));
-		if (fieldSchema.type === "object" && fieldSchema.properties) {
-			const nestedName = qualifyNestedName(name, fieldName);
-			nestedModels.push(...extractInlineModel(nestedName, fieldSchema));
-		}
-		if (fieldSchema.type === "array" && fieldSchema.items) {
-			const items = fieldSchema.items;
-			if (items.type === "object" && items.properties) {
-				const nestedName = qualifyNestedName(name, fieldName);
-				nestedModels.push(...extractInlineModel(nestedName, items));
-			}
+/**
+* Whether `target` admits every value of `copy`'s type. A nullable target
+* admits a nullable or a non-null copy; a non-null target admits only a
+* non-null copy. An enum with known values admits a copy whose values are a
+* subset of its own. Everything else must match exactly, by fingerprint.
+*/
+function typeAdmits(target, targetMap, copy, copyMap, visiting) {
+	if (target.kind === "nullable") return typeAdmits(target.inner, targetMap, copy.kind === "nullable" ? copy.inner : copy, copyMap, visiting);
+	if (copy.kind === "nullable") return false;
+	if (target.kind !== copy.kind) return false;
+	switch (target.kind) {
+		case "model": {
+			const t = targetMap.get(target.name);
+			const c = copyMap.get(copy.name);
+			if (t && c) return admits(t, targetMap, c, copyMap, visiting);
+			return target.name === copy.name;
 		}
-		if (fieldSchema.allOf) {
-			const mergedProperties = {};
-			const mergedRequired = [];
-			for (const sub of fieldSchema.allOf) {
-				if (sub.properties) Object.assign(mergedProperties, sub.properties);
-				if (sub.required) mergedRequired.push(...sub.required);
-			}
-			if (Object.keys(mergedProperties).length > 0) {
-				const nestedName = qualifyNestedName(name, fieldName);
-				const merged = {
-					type: "object",
-					properties: mergedProperties,
-					required: mergedRequired
-				};
-				if (!new Set(nestedModels.map((m) => m.name)).has(nestedName)) nestedModels.push(...extractInlineModel(nestedName, merged));
+		case "array": return typeAdmits(target.items, targetMap, copy.items, copyMap, visiting);
+		case "enum": {
+			const c = copy;
+			if (target.values && c.values) {
+				const allowed = new Set(target.values.map((v) => `${typeof v}:${String(v)}`));
+				return c.values.every((v) => allowed.has(`${typeof v}:${String(v)}`));
 			}
+			return target.name === c.name;
 		}
-		if (fieldSchema.oneOf) {
-			const objectVariant = fieldSchema.oneOf.find((v) => v.properties && (v.type === "object" || !v.type));
-			if (objectVariant) {
-				const nestedName = qualifyNestedName(name, fieldName);
-				if (!new Set(nestedModels.map((m) => m.name)).has(nestedName)) nestedModels.push(...extractInlineModel(nestedName, objectVariant));
-			}
+		default: return fingerprintType$1(target, targetMap, /* @__PURE__ */ new Set()) === fingerprintType$1(copy, copyMap, /* @__PURE__ */ new Set());
+	}
+}
+/**
+* Structural fingerprint of a companion model: field names, requiredness, and
+* each field's shape, with models nested inside the companion compared by
+* shape rather than by (operation-qualified) name, and inline enums compared
+* by their values. Models outside the companion are compared by name.
+*/
+function fingerprintModel(model, local, visiting) {
+	if (visiting.has(model.name)) return `rec:${model.name}`;
+	visiting.add(model.name);
+	const fields = [...model.fields].sort((a, b) => a.name.localeCompare(b.name)).map((f) => `${f.name}${f.required ? "!" : "?"}:${fingerprintType$1(f.type, local, visiting)}`);
+	visiting.delete(model.name);
+	return `{${fields.join(",")}}`;
+}
+function fingerprintType$1(ref, local, visiting) {
+	switch (ref.kind) {
+		case "primitive": return `p:${ref.type}${ref.format ? `:${ref.format}` : ""}`;
+		case "literal": return `l:${typeof ref.value}:${String(ref.value)}`;
+		case "nullable": return `n<${fingerprintType$1(ref.inner, local, visiting)}>`;
+		case "array": return `a<${fingerprintType$1(ref.items, local, visiting)}>`;
+		case "map": return `m<${ref.keyType ? `${fingerprintType$1(ref.keyType, local, visiting)},` : ""}${fingerprintType$1(ref.valueType, local, visiting)}>`;
+		case "union": return `u:${ref.compositionKind ?? ""}<${ref.variants.map((v) => fingerprintType$1(v, local, visiting)).sort().join(",")}>`;
+		case "enum": return ref.values ? `e<${[...ref.values].map((v) => `${typeof v}:${String(v)}`).sort().join("|")}>` : `e:${ref.name}`;
+		case "model": {
+			const nested = local.get(ref.name);
+			return nested ? fingerprintModel(nested, local, visiting) : `ref:${ref.name}`;
 		}
+		default: return assertNever(ref);
 	}
-	return [{
-		name,
-		description: schema.description,
-		fields
-	}, ...nestedModels];
 }
 //#endregion
 //#region src/parser/operations.ts
@@ -1985,6 +3445,39 @@ function resolveRequestBodyRef(raw, componentRequestBodies, operationContext) {
 	}
 	return current;
 }
+/**
+* Resolve a raw response header to a concrete Header Object, following `$ref`
+* chains into `components/headers` with a cycle guard.
+*
+* Unlike parameters and request bodies, a header that cannot be resolved is
+* warned about and dropped rather than failing the parse: a response header
+* is informational, so losing one costs an emitter a typed accessor, not a
+* wire contract, and should not block generating the rest of the SDK.
+*/
+function resolveHeaderRef(raw, componentHeaders, headerName, operationContext) {
+	const seenRefs = /* @__PURE__ */ new Set();
+	let current = raw;
+	let description;
+	while ("$ref" in current) {
+		if (description === void 0 && typeof current.description === "string") description = current.description;
+		if (seenRefs.has(current.$ref)) {
+			console.warn(`[oagen] Warning: Circular header $ref chain starting at "${current.$ref}" for response header "${headerName}" in ${operationContext}. Skipping the header.`);
+			return;
+		}
+		seenRefs.add(current.$ref);
+		const refName = /^#\/components\/headers\/(.+)$/.exec(current.$ref)?.[1].replace(/~1/g, "/").replace(/~0/g, "~");
+		const resolved = refName ? componentHeaders?.[refName] : void 0;
+		if (!resolved) {
+			console.warn(`[oagen] Warning: Unresolved header $ref "${current.$ref}" for response header "${headerName}" in ${operationContext}: no matching entry under components/headers. Skipping the header.`);
+			return;
+		}
+		current = resolved;
+	}
+	return description === void 0 ? current : {
+		...current,
+		description
+	};
+}
 const HTTP_METHODS = [
 	"get",
 	"post",
@@ -1995,26 +3488,34 @@ const HTTP_METHODS = [
 	"options",
 	"trace"
 ];
-function extractOperations(paths, operationIdTransform, componentSchemas, componentParameters, componentRequestBodies) {
+function extractOperations(paths, operationIdTransform, componentSchemas, componentParameters, componentRequestBodies, componentModels, documentTags, componentExamples, componentHeaders) {
 	if (!paths) return {
 		services: [],
 		inlineModels: []
 	};
+	const pathModelBaseNames = resolvePathModelBaseNames(paths, componentModels, componentRequestBodies);
 	const serviceMap = /* @__PURE__ */ new Map();
 	const inlineModels = [];
+	const envelopeCompanions = [];
+	const tagServiceByOperation = /* @__PURE__ */ new Map();
+	const headerModelRegistry = new Map((componentModels ?? []).map((model) => [model.name, { fingerprint: modelFingerprint(model) }]));
 	for (const [path, pathItem] of Object.entries(paths)) {
 		const pathLevelParams = pathItem.parameters ?? [];
 		for (const method of HTTP_METHODS) {
 			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, componentParameters, componentRequestBodies);
+			const tag = op.tags?.[0];
+			const serviceName = inferServiceName(path, tag);
+			const { operation, inlineModels: opModels, envelopeCompanions: opCompanions } = buildOperation(method, path, op, pathLevelParams, pathModelBaseNames.get(`${method} ${path}`) ?? derivePathModelBaseName(path, method), operationIdTransform, serviceName, componentSchemas, componentParameters, componentRequestBodies, componentExamples, componentHeaders, headerModelRegistry);
 			inlineModels.push(...opModels);
+			if (opCompanions) envelopeCompanions.push(...opCompanions);
+			if (tag) tagServiceByOperation.set(operation, serviceName);
 			const ops = serviceMap.get(serviceName) ?? [];
 			ops.push(operation);
 			serviceMap.set(serviceName, ops);
 		}
 	}
+	inlineModels.push(...resolveEnvelopeCompanionNames(envelopeCompanions, componentModels));
 	for (const [serviceName, operations] of serviceMap) {
 		const pathGroups = /* @__PURE__ */ new Map();
 		for (const op of operations) {
@@ -2036,14 +3537,73 @@ function extractOperations(paths, operationIdTransform, componentSchemas, compon
 		}
 	}
 	for (const [, operations] of serviceMap) disambiguateOperationNames(operations);
+	const declaredTags = indexDocumentTags(documentTags);
 	return {
-		services: Array.from(serviceMap.entries()).map(([name, operations]) => ({
-			name,
-			operations
-		})),
+		services: Array.from(serviceMap.entries()).map(([name, operations]) => {
+			const description = resolveServiceDescription(name, operations, tagServiceByOperation, declaredTags);
+			return description === void 0 ? {
+				name,
+				operations
+			} : {
+				name,
+				description,
+				operations
+			};
+		}),
 		inlineModels
 	};
 }
+/**
+* Index the document's top-level `tags[]` by the service name each tag
+* produces, so a tag spelled `user_management`, `User Management`, or
+* `user-management` all map to the `UserManagement` service. Every named tag
+* is indexed — with its description when it declares a non-blank one, and
+* `undefined` otherwise — because a declared-but-undescribed tag still marks
+* its service as one that must not borrow another tag's wording. When several
+* tags normalize to the same service name, the first described one wins.
+*
+* `parseSpec` ignored `tags` entirely before descriptions were read, so a
+* document with a malformed value — `tags` written as an object, a `null`
+* entry, a numeric `name` — used to parse and must keep parsing. Anything
+* that cannot be matched is skipped rather than thrown on.
+*/
+function indexDocumentTags(documentTags) {
+	const index = /* @__PURE__ */ new Map();
+	if (!Array.isArray(documentTags)) return index;
+	for (const tag of documentTags) {
+		if (typeof tag !== "object" || tag === null) continue;
+		const { name, description } = tag;
+		if (typeof name !== "string" || name === "") continue;
+		const serviceName = toPascalCase(name);
+		if (index.get(serviceName) !== void 0) continue;
+		const described = typeof description === "string" && description.trim() !== "";
+		index.set(serviceName, described ? description : void 0);
+	}
+	return index;
+}
+/**
+* Pick a service's description from the document's tags.
+*
+* A service whose own name is a declared tag is described by that tag alone:
+* its description when it has one, nothing otherwise. Another tag's wording is
+* never borrowed for it — operations tagged `api_keys` that the path-prefix
+* split merges into `UserManagement` must not label that service "API keys".
+*
+* A service whose own name is not declared is one the split carved out of a
+* tag (e.g. `OrganizationDomains` from operations tagged `organizations`); it
+* inherits the description of the first described tag its operations carry.
+* Path-named services whose operations have no tag carry nothing and stay
+* undescribed.
+*/
+function resolveServiceDescription(serviceName, operations, tagServiceByOperation, declaredTags) {
+	if (declaredTags.has(serviceName)) return declaredTags.get(serviceName);
+	for (const op of operations) {
+		const tagService = tagServiceByOperation.get(op);
+		if (tagService === void 0) continue;
+		const description = declaredTags.get(tagService);
+		if (description !== void 0) return description;
+	}
+}
 function inferServiceName(path, tag) {
 	if (tag) return toPascalCase(tag);
 	const first = path.split("/").filter(Boolean)[0] ?? "Default";
@@ -2062,6 +3622,24 @@ function inferServiceName(path, tag) {
 function normalizeOperationIdForNaming(operationId) {
 	return operationId.replace(/\[\d+\]\s*$/, "");
 }
+/**
+* The inline request body or response model name of an operation that has an
+* `operationId`. The single source of that name: extractRequestBody and
+* deriveResponseName use it to name, resolvePathModelBaseNames to reserve.
+*/
+function operationIdModelName(operationId, suffix) {
+	return cleanSchemaName(toPascalCase(normalizeOperationIdForNaming(operationId)) + suffix);
+}
+/**
+* The stem every model derived from an `operationId` starts with: its
+* `Request` and `Response` models, a list's `Item`, nested inline models under
+* those (`…ResponseOwner`) and envelope companions (`…ListMetadata`). Every
+* step of cleanSchemaName is a global replace or acts on the leading word, so
+* this is a true prefix of each of those names. Used to reserve them all.
+*/
+function operationIdModelBase(operationId) {
+	return cleanSchemaName(toPascalCase(normalizeOperationIdForNaming(operationId)));
+}
 function inferOperationName(method, path, operationId, operationIdTransform) {
 	if (operationId) {
 		const normalized = normalizeOperationIdForNaming(operationId);
@@ -2249,8 +3827,9 @@ function extractBodyParameterGroups(op, requestBody, operationContext, component
 	}
 	return groups.length > 0 ? groups : void 0;
 }
-function buildOperation(method, path, op, pathLevelParams, operationIdTransform, serviceName, componentSchemas, componentParameters, componentRequestBodies) {
-	const opLabel = op.operationId ?? `${method.toUpperCase()} ${path}`;
+function buildOperation(method, path, op, pathLevelParams, pathModelBaseName, operationIdTransform, serviceName, componentSchemas, componentParameters, componentRequestBodies, componentExamples, componentHeaders, headerModelRegistry = /* @__PURE__ */ new Map()) {
+	const opLabel = operationLabel(op, path, method);
+	const operationName = inferOperationName(method, path, op.operationId, operationIdTransform);
 	const requestBodyObject = resolveRequestBodyRef(op.requestBody, componentRequestBodies, opLabel);
 	const paramsByIdentity = /* @__PURE__ */ new Map();
 	for (const raw of [...pathLevelParams, ...op.parameters ?? []]) {
@@ -2267,14 +3846,20 @@ function buildOperation(method, path, op, pathLevelParams, operationIdTransform,
 	}
 	const wireParams = bodyOwnedNames.size > 0 ? allParams.filter((p) => !(p.in === "query" && bodyOwnedNames.has(p.name))) : allParams;
 	const opContext = serviceName;
-	const pathParams = extractParams(wireParams, "path", opContext, componentSchemas);
-	const queryParams = extractParams(wireParams, "query", opContext, componentSchemas);
-	const headerParams = extractParams(wireParams, "header", opContext, componentSchemas).filter((p) => p.name.toLowerCase() !== "idempotency-key");
-	const cookieParams = extractParams(wireParams, "cookie", opContext, componentSchemas);
-	const bodyOwnedQueryParams = bodyOwnedNames.size > 0 ? extractParams(allParams.filter((p) => p.in === "query" && bodyOwnedNames.has(p.name)), "query", opContext, componentSchemas) : [];
+	const pathParams = extractParams(wireParams, "path", opContext, componentSchemas, componentExamples, opLabel);
+	const queryParams = extractParams(wireParams, "query", opContext, componentSchemas, componentExamples, opLabel);
+	const headerParams = extractParams(wireParams, "header", opContext, componentSchemas, componentExamples, opLabel).filter((p) => p.name.toLowerCase() !== "idempotency-key");
+	const cookieParams = extractParams(wireParams, "cookie", opContext, componentSchemas, componentExamples, opLabel);
+	const bodyOwnedQueryParams = bodyOwnedNames.size > 0 ? extractParams(allParams.filter((p) => p.in === "query" && bodyOwnedNames.has(p.name)), "query", opContext, componentSchemas, componentExamples, opLabel) : [];
 	const reqBodyModels = [];
-	const { body: requestBody, encoding: requestBodyEncoding } = extractRequestBody(requestBodyObject, op, reqBodyModels);
-	const { response, successResponses, errors, inlineModels, isPaginated, dataPath: responseDataPath, itemType: responseItemType } = extractResponses(op.responses, op, path, method, componentSchemas);
+	const { body: requestBody, encoding: requestBodyEncoding } = extractRequestBody(requestBodyObject, op, pathModelBaseName, reqBodyModels, componentSchemas);
+	const { response, responseHeaders, successResponses, errors, inlineModels, isPaginated, dataPath: responseDataPath, itemType: responseItemType, envelopeFields, envelopeCompanions } = extractResponses(op.responses, op, pathModelBaseName, path, method, componentSchemas, {
+		componentHeaders,
+		componentSchemas,
+		serviceName: opContext,
+		operationQualifier: toPascalCase(operationName),
+		registry: headerModelRegistry
+	});
 	inlineModels.push(...reqBodyModels);
 	const paginationFromParams = detectPagination(response, queryParams, responseDataPath);
 	let pagination;
@@ -2285,10 +3870,11 @@ function buildOperation(method, path, op, pathLevelParams, operationIdTransform,
 			param: paginationFromParams?.param ?? "after",
 			limitParam: paginationFromParams?.limitParam,
 			dataPath: responseDataPath ?? paginationFromParams?.dataPath,
-			itemType
+			itemType,
+			envelopeFields
 		};
 	} else if (paginationFromParams) pagination = paginationFromParams;
-	const security = extractOperationSecurity(op.security);
+	const security = extractSecurityRequirements(op.security, opLabel);
 	const queryParamGroups = extractParameterGroups(op, [
 		...pathParams,
 		...queryParams,
@@ -2297,10 +3883,12 @@ function buildOperation(method, path, op, pathLevelParams, operationIdTransform,
 	], opLabel);
 	const bodyParamGroups = extractBodyParameterGroups(op, requestBodyObject, opLabel, componentSchemas);
 	const parameterGroups = queryParamGroups || bodyParamGroups ? [...queryParamGroups ?? [], ...bodyParamGroups ?? []] : void 0;
+	const summary = presentText(op.summary);
 	return {
 		operation: {
-			name: inferOperationName(method, path, op.operationId, operationIdTransform),
-			description: buildDescription(op.summary, op.description),
+			name: operationName,
+			...summary !== void 0 ? { summary } : {},
+			description: buildDescription(summary, op.description),
 			httpMethod: method,
 			path,
 			pathParams,
@@ -2311,6 +3899,7 @@ function buildOperation(method, path, op, pathLevelParams, operationIdTransform,
 			requestBody,
 			requestBodyEncoding,
 			response,
+			...responseHeaders && { responseHeaders },
 			successResponses,
 			errors,
 			pagination,
@@ -2320,31 +3909,49 @@ function buildOperation(method, path, op, pathLevelParams, operationIdTransform,
 			security,
 			parameterGroups
 		},
-		inlineModels
+		inlineModels,
+		envelopeCompanions
 	};
 }
 /**
-* Extract per-operation security requirements from an OpenAPI security directive.
-* Returns undefined when the operation uses the spec-level default security.
-*
-* OpenAPI security format: `security: [{ schemeName: [scope1, scope2] }]`
+* Combine an operation's `summary` and `description` into one doc text.
+* Empty or whitespace-only text counts as absent, so `summary: "List pets"`
+* with `description: ""` yields `"List pets"` rather than `""`. Text that has
+* content is kept verbatim, surrounding whitespace included.
 */
-function extractOperationSecurity(security) {
-	if (!security || security.length === 0) return void 0;
-	const requirements = [];
-	for (const entry of security) for (const [schemeName, scopes] of Object.entries(entry)) requirements.push({
-		schemeName,
-		scopes: scopes ?? []
-	});
-	return requirements.length > 0 ? requirements : void 0;
-}
 function buildDescription(summary, description) {
-	if (summary && description && summary !== description) return `${summary}\n\n${description}`;
-	return description ?? summary;
+	const presentSummary = presentText(summary);
+	const presentDescription = presentText(description);
+	if (presentSummary && presentDescription && presentSummary !== presentDescription) return `${presentSummary}\n\n${presentDescription}`;
+	return presentDescription ?? presentSummary;
 }
-function extractParams(params, location, operationContext, componentSchemas) {
+/** The text itself when it has non-whitespace content, otherwise `undefined`. */
+function presentText(text) {
+	return typeof text === "string" && text.trim() !== "" ? text : void 0;
+}
+function extractParams(params, location, operationContext, componentSchemas, componentExamples, opLabel) {
 	return params.filter((p) => p.in === location).map((p) => {
-		const refTarget = resolveParamSchemaRef(p.schema, componentSchemas);
+		const refTarget = resolveComponentSchemaRef(p.schema, componentSchemas);
+		const { example, examples } = resolveExamples([
+			{
+				example: p.example,
+				examples: exampleObjectValues(p.examples, componentExamples, `parameter "${p.name}" in ${opLabel ?? location}`)
+			},
+			{
+				example: p.schema?.example,
+				examples: nonEmptyExamples(p.schema?.examples)
+			},
+			{
+				example: refTarget?.example,
+				examples: nonEmptyExamples(refTarget?.examples)
+			}
+		]);
+		const own = p.schema ? extractConstraints(p.schema) : void 0;
+		const inherited = refTarget ? extractConstraints(refTarget) : void 0;
+		const constraints = own && inherited ? {
+			...inherited,
+			...own
+		} : own ?? inherited;
 		return {
 			name: p.name,
 			type: p.schema ? schemaToTypeRef(p.schema, p.name, operationContext ? toPascalCase(operationContext) : void 0) : {
@@ -2352,32 +3959,74 @@ function extractParams(params, location, operationContext, componentSchemas) {
 				type: "string"
 			},
 			required: p.required ?? false,
-			description: p.description,
+			description: firstDescription(p.description, p.schema?.description, refTarget?.description),
 			deprecated: p.deprecated || p.schema?.deprecated || refTarget?.deprecated || void 0,
 			default: p.schema?.default ?? refTarget?.default,
-			example: p.example ?? p.schema?.example ?? refTarget?.example,
+			example,
+			...examples ? { examples } : {},
 			style: p.style,
-			explode: p.explode
+			explode: p.explode,
+			...constraints ? { constraints } : {}
 		};
 	});
 }
 /**
-* If a parameter's schema is a `$ref` to `#/components/schemas/X`, return the
-* referenced component schema. Used to surface schema-level metadata (default,
-* example, deprecated) that wouldn't otherwise be visible at the param level.
-*
-* Refs are not pre-resolved by the bundler (`dereference: false` in refs.ts),
-* so without this, a param like `schema: { $ref: '.../PaginationOrder' }`
-* silently loses the target's `default: desc` and the SDK stops emitting the
-* spec-mandated default value in generated method signatures.
+* First non-empty description in precedence order. A parameter that declares
+* `description: ""` is treated as undocumented so its schema's text still
+* surfaces, and the result is `undefined` rather than `""` when nothing in
+* the chain is documented.
 */
-function resolveParamSchemaRef(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 firstDescription(...candidates) {
+	return candidates.find((candidate) => typeof candidate === "string" && candidate.length > 0);
+}
+/**
+* Flatten a parameter's `examples` map of Example Objects to the inline
+* values it carries, in document order. A `$ref` entry is resolved against
+* `components.examples` first (see `resolveExampleRef`). Entries that point
+* elsewhere (`externalValue`) or have no `value` are skipped; `null` is a
+* legitimate value and kept. Returns undefined when nothing remains so the
+* caller can fall through to the schema's `examples`.
+*/
+function exampleObjectValues(examples, componentExamples, context) {
+	if (!examples || typeof examples !== "object" || Array.isArray(examples)) return void 0;
+	const values = [];
+	for (const raw of Object.values(examples)) {
+		const entry = resolveExampleRef(raw, componentExamples, context);
+		if (!entry || typeof entry !== "object") continue;
+		if (entry.externalValue !== void 0 || entry.value === void 0) continue;
+		values.push(entry.value);
+	}
+	return values.length > 0 ? values : void 0;
+}
+/**
+* Follow an Example Object's `$ref` into `components.examples`, including a
+* component that is itself a `$ref`, with a cycle guard. The bundler keeps
+* refs (`dereference: false`), so without this every `$ref` entry would be
+* dropped and a map made only of refs would silently yield nothing — the
+* parameter would then take its `examples` from the schema instead of the
+* values the document points at. A ref that can't be resolved is skipped
+* with a warning rather than failing the parse: a missing example is a doc
+* gap, not a broken API surface.
+*/
+function resolveExampleRef(raw, componentExamples, context) {
+	const seenRefs = /* @__PURE__ */ new Set();
+	let current = raw;
+	while (current && typeof current === "object" && current.$ref !== void 0) {
+		const ref = current.$ref;
+		if (seenRefs.has(ref)) {
+			console.warn(`[oagen] Warning: Circular example $ref chain starting at "${ref}" on ${context}; skipping`);
+			return;
+		}
+		seenRefs.add(ref);
+		const refName = /^#\/components\/examples\/(.+)$/.exec(ref)?.[1].replace(/~1/g, "/").replace(/~0/g, "~");
+		const resolved = refName ? componentExamples?.[refName] : void 0;
+		if (!resolved) {
+			console.warn(`[oagen] Warning: Unresolved example $ref "${ref}" on ${context}; skipping`);
+			return;
+		}
+		current = resolved;
+	}
+	return current;
 }
 /**
 * Collect the property schemas of every `oneOf` branch reachable from a request
@@ -2429,7 +4078,7 @@ function resolveSchemaRefObject(schema, componentSchemas) {
 	return componentSchemas[match[1]];
 }
 /** HTTP methods whose request body is the primary parameter carrier. */
-const BODY_CARRYING_METHODS = new Set([
+const BODY_CARRYING_METHODS = /* @__PURE__ */ new Set([
 	"post",
 	"put",
 	"patch"
@@ -2492,7 +4141,7 @@ function collectBodyPropertyNames(schema, componentSchemas, seen = /* @__PURE__
 	const ref = schema.$ref;
 	if (ref) {
 		if (seen.has(ref)) return /* @__PURE__ */ new Set();
-		return collectBodyPropertyNames(resolveSchemaRefObject(schema, componentSchemas), componentSchemas, new Set([...seen, ref]));
+		return collectBodyPropertyNames(resolveSchemaRefObject(schema, componentSchemas), componentSchemas, /* @__PURE__ */ new Set([...seen, ref]));
 	}
 	const names = new Set(Object.keys(schema.properties ?? {}));
 	for (const sub of schema.allOf ?? []) for (const name of collectBodyPropertyNames(sub, componentSchemas, seen)) names.add(name);
@@ -2508,7 +4157,7 @@ function collectBodyPropertyNames(schema, componentSchemas, seen = /* @__PURE__
 	}
 	return names;
 }
-function extractRequestBody(body, op, inlineModels) {
+function extractRequestBody(body, op, pathModelBaseName, inlineModels, componentSchemas) {
 	if (!body?.content) return {};
 	const selected = selectRequestBodyContent(body);
 	const encoding = selected.encoding;
@@ -2531,24 +4180,26 @@ function extractRequestBody(body, op, inlineModels) {
 		};
 		return {};
 	}
-	const contextName = cleanSchemaName(op?.operationId ? toPascalCase(normalizeOperationIdForNaming(op.operationId)) + "Request" : "RequestBody");
+	const contextName = op?.operationId ? operationIdModelName(op.operationId, "Request") : pathModelBaseName + "Request";
 	if (schema.oneOf && schema.discriminator) {
 		const merged = flattenDiscriminatedUnionBody(schema);
 		if (merged) schema = merged;
 	}
 	if (schema.properties && (schema.type === "object" || !schema.type)) {
 		const requiredSet = new Set(schema.required ?? []);
+		const siblings = collectProperties(schema);
 		const fields = [];
 		for (const [fieldName, fieldSchema] of Object.entries(schema.properties)) {
 			if (!fieldSchema) continue;
-			fields.push(buildFieldFromSchema(fieldName, fieldSchema, contextName, requiredSet));
+			fields.push(buildFieldFromSchema(fieldName, fieldSchema, contextName, requiredSet, componentSchemas, siblings));
 		}
 		inlineModels.push({
 			name: contextName,
 			description: void 0,
-			fields
+			fields,
+			...constraintsEntry(schema)
 		});
-		extractInlineModelsFromProperties(schema, inlineModels, contextName);
+		extractInlineModelsFromProperties(schema, inlineModels, contextName, componentSchemas);
 		return {
 			body: {
 				kind: "model",
@@ -2559,23 +4210,29 @@ function extractRequestBody(body, op, inlineModels) {
 	}
 	if (schema.oneOf) {
 		const variants = [];
+		const inlineObjectVariants = schema.oneOf.filter((v) => !v.$ref && v.properties && (v.type === "object" || !v.type));
+		const contentNamed = [];
 		for (const variant of schema.oneOf) if (variant.$ref) {
 			const ref = schemaToTypeRef(variant, contextName);
 			variants.push(ref);
 		} else if (variant.type === "null") {} else if (variant.properties && (variant.type === "object" || !variant.type)) {
-			const variantName = deriveOneOfVariantName(variant, contextName, inlineModels);
+			const named = deriveOneOfVariantName(variant, contextName, inlineModels, inlineObjectVariants, contentNamed, Boolean(op?.operationId));
+			const variantName = named.name;
+			if (named.fromContent) contentNamed.push(variantName);
 			const requiredSet = new Set(variant.required ?? []);
+			const siblings = collectProperties(variant);
 			const fields = [];
 			for (const [fieldName, fieldSchema] of Object.entries(variant.properties)) {
 				if (!fieldSchema) continue;
-				fields.push(buildFieldFromSchema(fieldName, fieldSchema, variantName, requiredSet));
+				fields.push(buildFieldFromSchema(fieldName, fieldSchema, variantName, requiredSet, componentSchemas, siblings));
 			}
 			inlineModels.push({
 				name: variantName,
 				description: variant.description,
-				fields
+				fields,
+				...constraintsEntry(variant)
 			});
-			extractInlineModelsFromProperties(variant, inlineModels, variantName);
+			extractInlineModelsFromProperties(variant, inlineModels, variantName, componentSchemas);
 			variants.push({
 				kind: "model",
 				name: variantName
@@ -2661,38 +4318,451 @@ function flattenDiscriminatedUnionBody(schema) {
 		type: "object",
 		properties,
 		required: order.filter((name) => name === discProp || requiredCounts[name] === variantCount),
-		...schema.description ? { description: schema.description } : {}
+		...schema.description ? { description: schema.description } : {},
+		...extractConstraints(schema)
 	};
 }
-/** Derive a unique variant name for a oneOf inline model. */
-function deriveOneOfVariantName(variant, baseName, existingModels) {
+/**
+* Derive a unique variant name for a request-body `oneOf` inline model.
+*
+* A variant with a string-const property is named after it
+* (`RadarEmailChallengeCodeSessionAuthenticateRequest`). Any other variant is
+* named from its content by the same rule every inline union variant follows
+* (`nameInlineVariant`): the first const-less variant keeps the body's name
+* (or its title, when every inline variant of the union is titled), and each
+* later one takes its title, a distinguishing property
+* (`CreateThingRequestWithB`) or, when its property set repeats an earlier
+* variant's, the position counter (`CreateThingRequest2`). `siblings` are the
+* union's inline object variants and `contentNamed` the names its const-less
+* variants have taken so far; `fromContent` tells the caller to record this
+* one there. A clash with a model minted elsewhere still bumps the counter:
+* on the base for a content-named variant (`CreateThingRequest2`), on the
+* const-derived name for a const-named one (`FooCreateThingRequest2`) — so a
+* variant titled `Foo` and a later one pinning `kind: foo` in the same body
+* never share a model.
+*
+* `fromOperationId` says where `baseName` came from. An operationId-derived
+* base is already in cleanSchemaName form and its variants go through
+* resolveSchemaName, so they follow the same project-level naming policy as
+* component schemas. A path-derived base is used verbatim: it is deliberately
+* not cleaned (see derivePathModelBaseName) and resolvePathModelBaseNames
+* reserves names by that exact prefix, so cleaning a variant here would let it
+* slip past the reservation — `NotesPostRequest` became `NotePostRequest` and
+* collided with a component of that name.
+*/
+function deriveOneOfVariantName(variant, baseName, existingModels, siblings, contentNamed, fromOperationId) {
+	const finalize = (name) => fromOperationId ? resolveSchemaName(name) : name;
+	const existingNames = new Set(existingModels.map((m) => m.name));
+	const unique = (name, stem) => {
+		let candidate = name;
+		for (let suffix = 2; existingNames.has(candidate); suffix++) candidate = `${stem}${suffix}`;
+		return candidate;
+	};
 	if (variant.properties) {
-		for (const [, propSchema] of Object.entries(variant.properties)) if (propSchema?.const && typeof propSchema.const === "string") return resolveSchemaName(toPascalCase(propSchema.const) + baseName.replace(/Request$/, "") + "Request");
+		for (const [, propSchema] of Object.entries(variant.properties)) if (propSchema?.const && typeof propSchema.const === "string") {
+			const derivedName = finalize(toPascalCase(propSchema.const) + baseName.replace(/Request$/, "") + "Request");
+			return {
+				name: unique(derivedName, derivedName),
+				fromContent: false
+			};
+		}
 	}
-	const existingNames = new Set(existingModels.map((m) => m.name));
-	const transformedBaseName = resolveSchemaName(baseName);
-	let name = transformedBaseName;
-	let suffix = 2;
-	while (existingNames.has(name)) {
-		name = `${transformedBaseName}${suffix}`;
-		suffix++;
+	const finalBaseName = finalize(baseName);
+	return {
+		name: unique(nameInlineVariant(variant, siblings, finalBaseName, contentNamed, null), finalBaseName),
+		fromContent: true
+	};
+}
+/** Human-readable label for an operation in diagnostics: its operationId, else `METHOD /path`. */
+function operationLabel(op, path, method) {
+	return op?.operationId ?? `${method.toUpperCase()} ${path}`;
+}
+/** Shape of a model, independent of field order: name, requiredness, and type of every field. */
+function modelFingerprint(model) {
+	return model.fields.map((f) => `${f.name}${f.required ? "!" : "?"}:${stableStringify(f.type)}`).sort().join("|");
+}
+/** `JSON.stringify` with object keys sorted, so equal shapes serialize equally. */
+function stableStringify(value) {
+	if (Array.isArray(value)) return `[${value.map(stableStringify).join(",")}]`;
+	if (value !== null && typeof value === "object") {
+		const record = value;
+		return `{${Object.keys(record).sort().map((key) => `${JSON.stringify(key)}:${stableStringify(record[key])}`).join(",")}}`;
 	}
-	return name;
+	return JSON.stringify(value) ?? "undefined";
+}
+/**
+* Type a header's schema and materialize the inline models it names, under a
+* property name that does not collide with a different shape anywhere in the
+* spec.
+*
+* Header models are named from the service and header name alone, so an
+* inline `X-Meta` on a `Documents` operation is `DocumentsXMeta` — the same
+* name a component schema, or the same header on a 429 or on another
+* `Documents` operation, may already own with a different shape. Left alone,
+* the later merge keeps one definition for the name and every other
+* reference silently gets the wrong fields (a request body using the
+* component would even change type without any emitter reading headers).
+*
+* The first owner of a name keeps it: component models are seeded before any
+* operation, operations are visited in path order, and a single operation's
+* responses in ascending status-code order (integer-like keys iterate that
+* way), so the lowest code wins regardless of where it appears in the
+* document. A later header with a different shape — at any depth, a nested
+* object that differs counts — is re-derived under the first free candidate:
+*
+*   1. the bare header name                `DocumentsXMeta`
+*   2. when the name is taken inside this operation, the status code
+*      (`DocumentsXMeta429`); when taken by a component or another
+*      operation, the operation (`DocumentsCreateDocumentXMeta`)
+*   3. the other of those two
+*   4. operation and status code            `DocumentsCreateDocumentXMeta429`
+*   5. a numeric suffix                     `DocumentsXMeta2`, `DocumentsXMeta3`, ...
+*
+* Both the type and the models come from the same property name, so nested
+* models (`DocumentsXMeta429Origin`) line up by construction. A shape
+* identical to the name's current owner shares it and materializes nothing
+* new, which is also how a header reuses a matching component model.
+*
+* Treating the header as a one-property object reuses the field-level
+* extractor, whose names come from the same `qualifyInlineModelName(name,
+* parent)` rule `schemaToTypeRef` applies — the trick the inline request-body
+* path uses.
+*/
+function typeHeaderSchema(schema, name, statusCode, ctx, models) {
+	const parentName = ctx.serviceName ? toPascalCase(ctx.serviceName) : void 0;
+	const byStatus = `${name}${statusCode}`;
+	const byOperation = `${ctx.operationQualifier}${name}`;
+	const byBoth = `${ctx.operationQualifier}${name}${statusCode}`;
+	let candidates = [
+		name,
+		byStatus,
+		byOperation,
+		byBoth
+	];
+	for (let attempt = 0;; attempt++) {
+		const propertyName = attempt < candidates.length ? candidates[attempt] : `${name}${attempt - candidates.length + 2}`;
+		const trial = [];
+		extractInlineModelsFromProperties({ properties: { [propertyName]: schema } }, trial, parentName, ctx.componentSchemas);
+		const fingerprints = trial.map((model) => [model, modelFingerprint(model)]);
+		const collisions = fingerprints.flatMap(([model, fingerprint]) => {
+			const registered = ctx.registry.get(model.name);
+			return registered !== void 0 && registered.fingerprint !== fingerprint ? [registered] : [];
+		});
+		if (collisions.length > 0) {
+			if (attempt === 0 && !collisions.every((c) => c.operation === ctx.operationQualifier)) candidates = [
+				name,
+				byOperation,
+				byStatus,
+				byBoth
+			];
+			continue;
+		}
+		for (const [model, fingerprint] of fingerprints) {
+			if (ctx.registry.has(model.name)) continue;
+			ctx.registry.set(model.name, {
+				fingerprint,
+				operation: ctx.operationQualifier
+			});
+			models.push(model);
+		}
+		return schemaToTypeRef(schema, propertyName, parentName);
+	}
+}
+/**
+* Read a Response Object's `headers` map into IR response headers, resolving
+* `components/headers` refs. Returns `undefined` rather than `[]` when nothing
+* survives so callers can leave the `headers` key off entirely.
+*
+* An object-shaped header schema (directly, inside an array, or as a oneOf
+* variant) becomes a `ModelRef`, so the model it names is appended to
+* `models` — otherwise the ref would dangle with nothing to emit.
+*/
+function extractResponseHeaders(headers, operationLabel, statusCode, ctx, models) {
+	if (!headers) return void 0;
+	const result = [];
+	for (const [name, raw] of Object.entries(headers)) {
+		if (name.toLowerCase() === "content-type") continue;
+		const header = resolveHeaderRef(raw, ctx.componentHeaders, name, operationLabel);
+		if (!header) continue;
+		const contentSchema = header.content ? Object.values(header.content)[0]?.schema : void 0;
+		const schema = header.schema ?? contentSchema;
+		const type = schema ? typeHeaderSchema(schema, name, statusCode, ctx, models) : {
+			kind: "primitive",
+			type: "string"
+		};
+		result.push({
+			name,
+			type,
+			required: header.required ?? false,
+			description: header.description,
+			deprecated: header.deprecated || void 0
+		});
+	}
+	return result.length > 0 ? result : void 0;
+}
+/**
+* Build the prefix (`NotesByIdPinPost`) that names both inline models — the
+* request body (`…Request`) and the response (`…Response`) — of an operation
+* that has no `operationId`, from the only thing that identifies it: its path
+* and method.
+*
+* Every non-parameter segment is PascalCased in order and every parameter
+* segment becomes `By` + PascalCase(param name); then the optional
+* disambiguator and the method are appended. The whole is normalized with
+* toPascalCase so it is a fixed point of that function: responses.ts re-cases
+* the response name in `deriveModelName`, and without this step `POST /a/b`
+* named its body `ABPostRequest` but its response `AbPostResponse`.
+*
+*   GET  /widgets                   → WidgetsGet
+*   POST /notes                     → NotesPost
+*   POST /notes/{id}/pin            → NotesByIdPinPost
+*   GET  /users/{user_id}/sessions  → UsersByUserIdSessionsGet
+*
+* This tells the common path shapes apart (list vs. item, sibling and nested
+* sub-resources) but is not unique by construction: `/foo-bar` and `/foo/bar`,
+* `/notes/by-id` and `/notes/{id}`, `/notes` and `/notes/` all flatten to the
+* same words. `resolvePathModelBaseNames` detects such collisions: the path
+* spelled most plainly keeps the plain name and every other one gets a
+* `disambiguator` derived from its raw path.
+*
+* A single-segment path keeps the name the old first-segment rule produced.
+* The result is deliberately not passed through cleanSchemaName (the old
+* fallback wasn't either): the segments are the resource names as the API
+* spells them.
+*/
+function derivePathModelBaseName(path, method, disambiguator = "") {
+	const parts = path.split("/").filter(Boolean).map((segment) => segment.startsWith("{") ? "By" + toPascalCase(segment.replace(/[{}]/g, "")) : toPascalCase(segment));
+	return toPascalCase([
+		parts.length > 0 ? parts.join("") : "Unknown",
+		disambiguator,
+		method
+	].filter(Boolean).join("_"));
+}
+/**
+* Decide the path-derived model prefix of every operation that has no
+* `operationId`, keyed by `${method} ${path}`.
+*
+* A prefix collides when two distinct raw paths with the same method flatten
+* to it (see derivePathModelBaseName), or when a reserved name starts with
+* it. The reserved names are every resolved component model name and, for
+* every operation with an `operationId`, its model stem
+* (operationIdModelBase). A prefix is the stem of several emitted names —
+* `…Request`, `…Response`, a list's `…Item`, nested inline models such as
+* `…ResponseOwner`, envelope companions such as `…ListMetadata` — so the
+* check is on the stem, not on an enumeration of suffixes: an unnamed
+* `GET /audit/events` must not overwrite `components/schemas/AuditEventsGetItem`
+* any more than an unnamed `POST /audit/events` may overwrite the models of
+* a `POST /legacy-audit` whose operationId is `auditEventsPost`. Reserved
+* names never change.
+*
+* This is deliberately a superset: a component named `AuditEventsGetter`, or
+* an operationId `auditEventsGetSummary`, also pushes `GET /audit/events`
+* onto a hashed name although no emitted name would coincide. Determinism
+* and never sharing a name wrongly matter more than the rare extra hash, and
+* the reservation is unconditional — an inline body is never merged into a
+* same-named component even when the shapes agree — so the rule stays
+* simple and order-free. Every name derived from a path-based prefix uses it
+* verbatim (body `oneOf` variants included; see deriveOneOfVariantName), and
+* as a second line of defence the check also runs on the cleaned spellings
+* of the prefix (see prefixSpellings), so `GET /notes` yields to a component
+* `NoteGetItem` although its own item model is `NotesGetItem`. Names that
+* embed the prefix behind a const value — a body `oneOf` variant pinning
+* `kind: email` is `EmailTagsPostRequest`, a nested variant
+* `<Const><Parent><Field>` — are checked too, with each const the operation
+* can mint prepended to every spelling (see collectOperationConstPrefixes);
+* the hash then lands inside those names as well (`EmailTags151Dd5PostRequest`).
+*
+* These names are types SDK users read and import, so a collision costs the
+* plain name only where it must. Within a group of paths that flatten to one
+* prefix, the path spelled most plainly (see pathDeviation: no trailing
+* slash, `{id}` rather than a literal `by-id`) is canonical and keeps the
+* plain prefix; every other path gets a six-character disambiguator, the
+* start of the SHA-1 of its raw path, inserted before the method
+* (`POST /foo-bar` next to `POST /foo/bar` → `FooBar546F12Post`). When two
+* paths tie for plainest, or the prefix is reserved, nobody is canonical and
+* every path in the group is disambiguated. The outcome depends only on the
+* document's paths, operationIds and component names, never on their order,
+* and a path that stops colliding returns to its plain name.
+*/
+function resolvePathModelBaseNames(paths, componentModels, componentRequestBodies) {
+	const candidates = [];
+	const rawPathsByPlainName = /* @__PURE__ */ new Map();
+	const constPrefixesByPlainName = /* @__PURE__ */ new Map();
+	const reservedNames = /* @__PURE__ */ new Set();
+	for (const model of componentModels ?? []) reservedNames.add(model.name);
+	for (const [path, pathItem] of Object.entries(paths)) for (const method of HTTP_METHODS) {
+		const op = pathItem[method];
+		if (!op) continue;
+		if (op.operationId) {
+			reservedNames.add(operationIdModelBase(op.operationId));
+			continue;
+		}
+		const plain = derivePathModelBaseName(path, method);
+		candidates.push({
+			key: `${method} ${path}`,
+			path,
+			method,
+			plain
+		});
+		const rawPaths = rawPathsByPlainName.get(plain) ?? /* @__PURE__ */ new Set();
+		rawPaths.add(path);
+		rawPathsByPlainName.set(plain, rawPaths);
+		const constPrefixes = constPrefixesByPlainName.get(plain) ?? /* @__PURE__ */ new Set();
+		for (const prefix of collectOperationConstPrefixes(op, componentRequestBodies, operationLabel(op, path, method))) constPrefixes.add(prefix);
+		constPrefixesByPlainName.set(plain, constPrefixes);
+	}
+	const reservedList = [...reservedNames];
+	const canonicalByPlainName = /* @__PURE__ */ new Map();
+	for (const [plain, rawPaths] of rawPathsByPlainName) {
+		const spellings = prefixSpellings(plain);
+		const reserved = ["", ...constPrefixesByPlainName.get(plain) ?? []].flatMap((constPrefix) => spellings.map((spelling) => constPrefix + spelling)).some((stem) => reservedList.some((name) => name.startsWith(stem)));
+		canonicalByPlainName.set(plain, reserved ? void 0 : canonicalPath(rawPaths));
+	}
+	const resolved = /* @__PURE__ */ new Map();
+	for (const { key, path, method, plain } of candidates) {
+		const keepsPlainName = canonicalByPlainName.get(plain) === path;
+		resolved.set(key, keepsPlainName ? plain : derivePathModelBaseName(path, method, pathDisambiguator(path)));
+	}
+	return resolved;
+}
+/**
+* The one path in a group that is spelled most plainly by pathDeviation, or
+* undefined when two or more tie for it, so the choice never depends on the
+* order the paths were written in.
+*/
+function canonicalPath(rawPaths) {
+	let best;
+	let bestScore;
+	let tied = false;
+	for (const path of rawPaths) {
+		const score = pathDeviation(path);
+		const cmp = bestScore ? compareDeviation(score, bestScore) : -1;
+		if (cmp < 0) {
+			best = path;
+			bestScore = score;
+			tied = false;
+		} else if (cmp === 0) tied = true;
+	}
+	return tied ? void 0 : best;
+}
+/**
+* How far a raw path's spelling is from the plain prefix it flattens to:
+* `[trailing slash, literal segments with any character outside a-z0-9]`,
+* compared lexicographically. `/notes` scores [0, 0] and `/notes/` [1, 0];
+* `/notes/{id}` scores [0, 0] and `/notes/by-id` [0, 1].
+*/
+function pathDeviation(rawPath) {
+	return [rawPath.length > 1 && rawPath.endsWith("/") ? 1 : 0, rawPath.split("/").filter(Boolean).filter((segment) => !segment.startsWith("{") && /[^a-z0-9]/.test(segment)).length];
+}
+function compareDeviation(a, b) {
+	return a[0] - b[0] || a[1] - b[1];
+}
+/** The first six hex characters of the SHA-1 of a raw path. */
+function pathDisambiguator(rawPath) {
+	return createHash("sha1").update(rawPath).digest("hex").slice(0, 6);
+}
+/**
+* The spellings a path-based prefix could take if a name derived from it were
+* run through one of the parser's cleaning steps: the prefix itself (every
+* path-derived name uses it verbatim), cleanSchemaName's form (lead-word
+* singularization plus backend and ListItem-marker stripping),
+* resolveSchemaName's form (the same plus the project's schemaNameTransform),
+* and stripListItemMarkers alone, which nested-model and inline-enum
+* qualification apply to a parent name. Reserving by every spelling is the
+* second line of defence behind "use the base verbatim": a cleaning step added
+* later cannot let a derived name slip past the reservation. Empty spellings
+* are dropped so a degenerate prefix cannot match every reserved name.
+*/
+function prefixSpellings(prefix) {
+	const spellings = [
+		prefix,
+		cleanSchemaName(prefix),
+		resolveSchemaName(prefix),
+		stripListItemMarkers(prefix)
+	];
+	return [...new Set(spellings)].filter((spelling) => spelling.length > 0);
+}
+/**
+* The PascalCase const values an operationId-less operation can prepend to a
+* name minted from its prefix, read from the schemas its request body and 2xx
+* responses declare inline. A body `oneOf` variant pinning `kind: email`
+* yields `EmailTagsPostRequest` (deriveOneOfVariantName); a nested
+* `oneOf`/`anyOf` object variant yields `<Const><Parent><Field>`
+* (nameOneOfVariant, nameVariantModel). Every string const or single-value
+* enum of every inline object variant is collected, top level and nested — a
+* superset of whichever property each of those picks as the discriminator, so
+* the reservation can never be narrower than the naming. `$ref` targets are
+* components with names of their own and are not followed. A request body
+* `$ref` that cannot be resolved is left for buildOperation to report.
+*
+* Names that do not embed the prefix at all — a response `oneOf` variant
+* named from its bare const (`Email`, see deriveModelName in responses.ts)
+* or a `title`-mapped variant — are outside what a disambiguator can
+* separate and are not reserved here.
+*/
+function collectOperationConstPrefixes(op, componentRequestBodies, opLabel) {
+	const prefixes = /* @__PURE__ */ new Set();
+	let body;
+	try {
+		body = resolveRequestBodyRef(op.requestBody, componentRequestBodies, opLabel);
+	} catch {
+		body = void 0;
+	}
+	collectConstPrefixes(selectRequestBodyContent(body).schema, prefixes, 0);
+	for (const [statusCode, response] of Object.entries(op.responses ?? {})) {
+		const code = parseInt(statusCode, 10);
+		if (code < 200 || code >= 300) continue;
+		for (const media of Object.values(response.content ?? {})) collectConstPrefixes(media?.schema, prefixes, 0);
+	}
+	return prefixes;
+}
+function collectConstPrefixes(schema, out, depth) {
+	if (!schema || schema.$ref || depth > 16) return;
+	for (const variants of [schema.oneOf, schema.anyOf]) for (const variant of variants ?? []) {
+		if (variant.$ref || !variant.properties) continue;
+		for (const property of Object.values(variant.properties)) {
+			const value = constStringOf(property);
+			const prefix = value === null ? "" : toPascalCase(value);
+			if (prefix) out.add(prefix);
+		}
+	}
+	const children = [
+		...schema.oneOf ?? [],
+		...schema.anyOf ?? [],
+		...schema.allOf ?? [],
+		schema.items,
+		...Object.values(schema.properties ?? {}),
+		typeof schema.additionalProperties === "object" ? schema.additionalProperties : void 0
+	];
+	for (const child of children) collectConstPrefixes(child, out, depth + 1);
+}
+/** A property's pinned string value: a string `const`, or a single-value string `enum`. */
+function constStringOf(property) {
+	if (!property) return null;
+	if (typeof property.const === "string") return property.const;
+	if (Array.isArray(property.enum) && property.enum.length === 1 && typeof property.enum[0] === "string") return property.enum[0];
+	return null;
 }
-function deriveResponseName(op, path, method) {
-	if (op?.operationId) return cleanSchemaName(toPascalCase(normalizeOperationIdForNaming(op.operationId)) + "Response");
-	return toPascalCase(path.split("/").filter(Boolean)[0] ?? "Unknown") + toPascalCase(method) + "Response";
+function deriveResponseName(op, pathModelBaseName) {
+	if (op?.operationId) return operationIdModelName(op.operationId, "Response");
+	return pathModelBaseName + "Response";
 }
-function extractResponses(responses, op, path, method, componentSchemas) {
+function extractResponses(responses, op, pathModelBaseName, path, method, componentSchemas, headerContext = {
+	operationQualifier: "",
+	registry: /* @__PURE__ */ new Map()
+}) {
 	const errors = [];
 	let response = {
 		kind: "primitive",
 		type: "string"
 	};
+	let responseHeaders;
 	let inlineModels = [];
 	let isPaginated = false;
 	let dataPath;
 	let itemType;
+	let envelopeFields;
+	let envelopeCompanions;
 	if (!responses) return {
 		response,
 		errors,
@@ -2700,8 +4770,11 @@ function extractResponses(responses, op, path, method, componentSchemas) {
 		isPaginated
 	};
 	const allSuccessResponses = [];
+	const opLabel = operationLabel(op, path ?? "/", method ?? "get");
+	const headerModels = [];
 	for (const [statusCode, resp] of Object.entries(responses)) {
 		const code = parseInt(statusCode, 10);
+		const headers = code >= 200 ? extractResponseHeaders(resp.headers, opLabel, code, headerContext, headerModels) : void 0;
 		if (code >= 200 && code < 300) {
 			let extractedType = {
 				kind: "primitive",
@@ -2709,62 +4782,75 @@ function extractResponses(responses, op, path, method, componentSchemas) {
 			};
 			const jsonContent = resp.content?.["application/json"];
 			if (jsonContent?.schema) {
-				const contextName = deriveResponseName(op, path ?? "/", method ?? "get");
+				const contextName = deriveResponseName(op, pathModelBaseName);
 				const result = classifyAndExtractResponse(jsonContent.schema, contextName, componentSchemas);
 				extractedType = result.response;
 				inlineModels = result.inlineModels;
 				isPaginated = result.isPaginated;
 				dataPath = result.dataPath;
 				itemType = result.itemType;
-			} else if (resp.content) if (resp.content["application/octet-stream"] || resp.content["application/pdf"]) extractedType = {
-				kind: "primitive",
-				type: "string",
-				format: "binary"
-			};
-			else if (resp.content["text/plain"] || resp.content["text/html"] || resp.content["text/xml"] || resp.content["application/xml"]) extractedType = {
-				kind: "primitive",
-				type: "string"
-			};
-			else {
-				const firstKey = Object.keys(resp.content)[0];
-				if (firstKey) {
-					const firstContent = resp.content[firstKey];
-					if (firstContent?.schema) extractedType = schemaToTypeRef(firstContent.schema, deriveResponseName(op, path ?? "/", method ?? "get"));
+				envelopeFields = result.envelopeFields;
+				envelopeCompanions = result.envelopeCompanions;
+			} else if (resp.content) {
+				if (resp.content["application/octet-stream"] || resp.content["application/pdf"]) extractedType = {
+					kind: "primitive",
+					type: "string",
+					format: "binary"
+				};
+				else if (resp.content["text/plain"] || resp.content["text/html"] || resp.content["text/xml"] || resp.content["application/xml"]) extractedType = {
+					kind: "primitive",
+					type: "string"
+				};
+				else {
+					const firstKey = Object.keys(resp.content)[0];
+					if (firstKey) {
+						const firstContent = resp.content[firstKey];
+						if (firstContent?.schema) extractedType = schemaToTypeRef(firstContent.schema, deriveResponseName(op, pathModelBaseName));
+					}
 				}
 			}
 			allSuccessResponses.push({
 				statusCode: code,
-				type: extractedType
+				type: extractedType,
+				...headers && { headers }
 			});
 		} else if (code >= 300 && code < 400) allSuccessResponses.push({
 			statusCode: code,
 			type: {
 				kind: "primitive",
 				type: "unknown"
-			}
+			},
+			...headers && { headers }
 		});
 		else if (code >= 400) {
 			const jsonContent = resp.content?.["application/json"];
 			const type = jsonContent?.schema ? schemaToTypeRef(jsonContent.schema, `Error${code}`) : void 0;
 			errors.push({
 				statusCode: code,
-				type
+				type,
+				...headers && { headers }
 			});
 		}
 	}
 	if (allSuccessResponses.length > 0) {
 		const sorted = [...allSuccessResponses].sort((a, b) => a.statusCode - b.statusCode);
-		response = (sorted.find((r) => r.type.kind !== "primitive" || r.type.type !== "unknown") ?? sorted[0]).type;
+		const primary = sorted.find((r) => r.type.kind !== "primitive" || r.type.type !== "unknown") ?? sorted[0];
+		response = primary.type;
+		responseHeaders = primary.headers;
 	}
 	const successResponses = allSuccessResponses.length > 1 ? allSuccessResponses : void 0;
+	if (headerModels.length > 0) inlineModels = [...inlineModels, ...headerModels];
 	return {
 		response,
+		responseHeaders,
 		successResponses,
 		errors,
 		inlineModels,
 		isPaginated,
 		dataPath,
-		itemType
+		itemType,
+		envelopeFields,
+		envelopeCompanions
 	};
 }
 //#endregion
@@ -2773,10 +4859,25 @@ function keepLargestByName(models) {
 	const byName = /* @__PURE__ */ new Map();
 	for (const model of models) {
 		const existing = byName.get(model.name);
+		if (existing && !haveSameFields(existing, model)) {
+			const kept = model.fields.length === existing.fields.length ? "keeping the first definition" : "keeping the one with more fields";
+			console.warn(`[oagen] Warning: Inline model "${model.name}" has more than one definition with different fields or field types (${model.fields.length} vs ${existing.fields.length}) — ${kept}`);
+		}
 		if (!existing || model.fields.length > existing.fields.length) byName.set(model.name, model);
 	}
 	return [...byName.values()];
 }
+/**
+* Same field names with the same types, in any order. Types are compared by
+* their JSON serialization: the parser builds a given shape's TypeRef with the
+* same key order every time, so equal shapes serialize identically.
+*/
+function haveSameFields(a, b) {
+	const signatures = (m) => new Set(m.fields.map((f) => `${f.name}:${JSON.stringify(f.type)}`));
+	const aSignatures = signatures(a);
+	const bSignatures = signatures(b);
+	return aSignatures.size === bSignatures.size && [...aSignatures].every((s) => bSignatures.has(s));
+}
 function rewriteModelRef(ref, oldName, newName) {
 	walkTypeRef(ref, { model: (r) => {
 		if (r.name === oldName) r.name = newName;
@@ -2787,6 +4888,8 @@ function rewriteModelRefs(models, services, oldName, newName) {
 	for (const service of services) for (const op of service.operations) {
 		rewriteModelRef(op.response, oldName, newName);
 		if (op.requestBody) rewriteModelRef(op.requestBody, oldName, newName);
+		for (const field of op.pagination?.envelopeFields ?? []) rewriteModelRef(field.type, oldName, newName);
+		for (const header of collectResponseHeaders(op)) rewriteModelRef(header.type, oldName, newName);
 	}
 }
 function mergeInlineResponseModels(schemaModels, inlineModels) {
@@ -2809,15 +4912,25 @@ function mergeInlineResponseModels(schemaModels, inlineModels) {
 	});
 	return [...mergedSchemaModels, ...keepLargestByName(deduplicatedInlineModels)];
 }
-function mergeFieldInlineModels(existingModels, fieldInlineModels) {
+/**
+* Fold the field extractor's inline models into the models gathered so far,
+* keeping the earlier definition on a name clash. `componentNames` tells a
+* clash with a real component schema apart from one between two inline
+* models, so the warning can say which happened and name both shapes.
+*/
+function mergeFieldInlineModels(existingModels, fieldInlineModels, componentNames) {
 	const modelNames = new Set(existingModels.map((m) => m.name));
 	const modelsByName = new Map(existingModels.map((m) => [m.name, m]));
+	const fieldList = (m) => m.fields.map((f) => f.name).join(", ") || "(no fields)";
 	const deduplicatedFieldModels = fieldInlineModels.filter((model) => {
 		if (!modelNames.has(model.name)) return true;
 		const existing = modelsByName.get(model.name);
 		const existingFieldNames = new Set(existing.fields.map((f) => f.name));
 		const inlineFieldNames = new Set(model.fields.map((f) => f.name));
-		if (model.fields.some((f) => !existingFieldNames.has(f.name)) || existing.fields.some((f) => !inlineFieldNames.has(f.name))) console.warn(`[oagen] Warning: Inline model "${model.name}" has different fields than component schema — using component schema`);
+		if (model.fields.some((f) => !existingFieldNames.has(f.name)) || existing.fields.some((f) => !inlineFieldNames.has(f.name))) {
+			if (componentNames && !componentNames.has(model.name)) console.warn(`[oagen] Warning: Two inline models are named "${model.name}" (fields: ${fieldList(existing)} | ${fieldList(model)}) — keeping the first, the second is dropped`);
+			else console.warn(`[oagen] Warning: Inline model "${model.name}" has different fields than component schema — using component schema`);
+		}
 		return false;
 	});
 	return [...existingModels, ...keepLargestByName(deduplicatedFieldModels)];
@@ -2849,7 +4962,7 @@ function collapseJsonSuffixModels(models, services) {
 		if (!baseModel || model.fields.length <= baseModel.fields.length) continue;
 		if (!baseModel.fields.every((f) => model.fields.some((mf) => mf.name === f.name))) continue;
 		if (hasModelConstDiscriminant(model) && hasModelConstDiscriminant(baseModel)) continue;
-		if (isModelReferencedByOthers(model.name, normalizedModels, new Set([model.name, baseName]))) continue;
+		if (isModelReferencedByOthers(model.name, normalizedModels, /* @__PURE__ */ new Set([model.name, baseName]))) continue;
 		mergeCandidates.push({
 			jsonModel: model,
 			baseModel
@@ -2858,6 +4971,10 @@ function collapseJsonSuffixModels(models, services) {
 	const toRemove = /* @__PURE__ */ new Set();
 	for (const { jsonModel, baseModel } of mergeCandidates) {
 		baseModel.fields = jsonModel.fields;
+		if (jsonModel.constraints || baseModel.constraints) baseModel.constraints = {
+			...baseModel.constraints,
+			...jsonModel.constraints
+		};
 		toRemove.add(jsonModel.name);
 		rewriteModelRefs(normalizedModels, services, jsonModel.name, baseModel.name);
 		console.warn(`[oagen] Merged "${jsonModel.name}" into "${baseModel.name}" (${jsonModel.fields.length} fields, superset)`);
@@ -2893,17 +5010,82 @@ function collectInlineEnumsFromModels(models, enums) {
 }
 /**
 * Collect inline enum definitions from operation parameters (query, path, header)
-* and promote them to top-level enums so emitters can generate typed enum files.
+* list-envelope companion fields, and response headers, and promote them to
+* top-level enums so emitters can generate typed enum files.
 */
 function collectInlineEnumsFromOperations(services, enums) {
 	const enumNames = new Set(enums.map((e) => e.name));
-	for (const service of services) for (const op of service.operations) for (const param of [
-		...op.pathParams,
-		...op.queryParams,
-		...op.bodyOwnedQueryParams ?? [],
-		...op.headerParams,
-		...op.cookieParams ?? []
-	]) collectInlineEnumFromRef(param.type, enums, enumNames);
+	for (const service of services) for (const op of service.operations) {
+		for (const param of [
+			...op.pathParams,
+			...op.queryParams,
+			...op.bodyOwnedQueryParams ?? [],
+			...op.headerParams,
+			...op.cookieParams ?? []
+		]) collectInlineEnumFromRef(param.type, enums, enumNames);
+		for (const field of op.pagination?.envelopeFields ?? []) collectInlineEnumFromRef(field.type, enums, enumNames);
+		for (const { headers, qualifier } of responseHeaderGroups(op)) for (const header of headers) collectHeaderEnums(header, qualifier, enums, enumNames);
+	}
+}
+/**
+* Header lists to walk, each with the status-code qualifier that keeps a
+* colliding enum name apart. When `successResponses` exists the primary list
+* is the same array as its entry there, so the entries are walked with their
+* own codes instead of `responseHeaders`; a lone 2xx carries no status code
+* in the IR, so its headers get no qualifier.
+*/
+function responseHeaderGroups(op) {
+	const groups = [];
+	if (op.successResponses) {
+		for (const entry of op.successResponses) if (entry.headers) groups.push({
+			headers: entry.headers,
+			qualifier: String(entry.statusCode)
+		});
+	} else if (op.responseHeaders) groups.push({ headers: op.responseHeaders });
+	for (const error of op.errors) if (error.headers) groups.push({
+		headers: error.headers,
+		qualifier: String(error.statusCode)
+	});
+	return groups;
+}
+/**
+* Promote a header's inline enums. A header enum is named from the service
+* and header name alone, so `X-Policy` allowing `fast`/`slow` on a 200 and
+* `retry`/`stop` on a 429 would share one name and whichever was collected
+* first would silently win; a request parameter named like the header
+* collides the same way. When the name is already taken by a different value
+* set, the header's ref is renamed to a distinct name before it is promoted.
+* A taken name with the same values is shared, as before.
+*/
+function collectHeaderEnums(header, qualifier, enums, enumNames) {
+	walkTypeRef(header.type, { enum: (ref) => {
+		if (!ref.values) return;
+		const existing = enums.find((e) => e.name === ref.name);
+		if (existing && !sameEnumValues(existing, ref.values)) ref.name = distinctEnumName(ref.name, ref.values, qualifier, enums);
+		collectInlineEnumFromRef(ref, enums, enumNames);
+	} });
+}
+/** Order-insensitive: a reordering of the same members is the same type. */
+function sameEnumValues(existing, values) {
+	if (existing.values.length !== values.length) return false;
+	const have = new Set(existing.values.map((v) => v.value));
+	return values.every((v) => have.has(v));
+}
+/**
+* The first name not taken by a different value set: the base qualified by
+* the status code (`DocumentsXPolicy429`), then numeric suffixes
+* (`DocumentsXPolicy2`, `DocumentsXPolicy3`, ...). Deterministic for a given
+* spec, since it depends only on declaration order.
+*/
+function distinctEnumName(base, values, qualifier, enums) {
+	const isUsable = (name) => {
+		const taken = enums.find((e) => e.name === name);
+		return !taken || sameEnumValues(taken, values);
+	};
+	if (qualifier && isUsable(`${base}${qualifier}`)) return `${base}${qualifier}`;
+	let suffix = 2;
+	while (!isUsable(`${base}${suffix}`)) suffix++;
+	return `${base}${suffix}`;
 }
 //#endregion
 //#region src/parser/parameter-group-names.ts
@@ -3182,6 +5364,8 @@ function validateModelRefs(spec) {
 		]) walkRef(p.type, `${service.name}.${op.name}.${p.name}`);
 		if (op.requestBody) walkRef(op.requestBody, `${service.name}.${op.name}.requestBody`);
 		walkRef(op.response, `${service.name}.${op.name}.response`);
+		for (const field of op.pagination?.envelopeFields ?? []) walkRef(field.type, `${service.name}.${op.name}.pagination.${field.name}`);
+		for (const header of collectResponseHeaders(op)) walkRef(header.type, `${service.name}.${op.name}.headers.${header.name}`);
 	}
 }
 //#endregion
@@ -3192,11 +5376,12 @@ 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, spec.components?.parameters, spec.components?.requestBodies);
+	const { services, inlineModels } = extractOperations(spec.paths, options?.operationIdTransform, spec.components?.schemas, spec.components?.parameters, spec.components?.requestBodies, models, spec.tags, spec.components?.examples, spec.components?.headers);
 	const responseNormalizedModels = mergeInlineResponseModels(models, inlineModels);
 	const fieldInlineModels = extractInlineModelsFromSchemas(spec.components?.schemas);
+	const componentNames = new Set(Object.keys(spec.components?.schemas ?? {}).map((schemaName) => resolveSchemaName(schemaName)));
 	clearSchemaNameTransform();
-	const finalModels = collapseJsonSuffixModels(mergeFieldInlineModels(responseNormalizedModels, fieldInlineModels), services);
+	const finalModels = collapseJsonSuffixModels(mergeFieldInlineModels(responseNormalizedModels, fieldInlineModels, componentNames), services);
 	applyFieldHints(finalModels, options?.fieldHints);
 	collectInlineEnumsFromModels(finalModels, enums);
 	collectInlineEnumsFromOperations(services, enums);
@@ -3215,6 +5400,7 @@ async function parseSpec(specPath, options) {
 		models: finalModels,
 		enums,
 		auth,
+		security: extractSecurityRequirements(spec.security, "the document"),
 		sdk: defaultSdkBehavior()
 	};
 	assignParameterGroupWrapperNames(result);
@@ -3237,20 +5423,47 @@ function applyFieldHints(models, fieldHints) {
 		}
 	}
 }
-/** Extract authentication schemes from OpenAPI securitySchemes. */
+/**
+* Extract authentication schemes from OpenAPI securitySchemes.
+*
+* Document order is preserved. Each entry carries its `securitySchemes` key as
+* `schemeName` so emitters can join the requirements under `ApiSpec.security`
+* and `Operation.security` back to it.
+* Schemes the IR cannot represent are omitted with a warning rather than silently.
+*/
 function extractAuthSchemes(securitySchemes) {
 	if (!securitySchemes) return void 0;
 	const schemes = [];
-	for (const [, scheme] of Object.entries(securitySchemes)) if (scheme.type === "http" && scheme.scheme === "bearer") schemes.push({ kind: "bearer" });
-	else if (scheme.type === "apiKey" && scheme.in && scheme.name) schemes.push({
-		kind: "apiKey",
-		in: scheme.in,
-		name: scheme.name
-	});
-	else if (scheme.type === "oauth2" && scheme.flows) schemes.push({
-		kind: "oauth2",
-		flows: scheme.flows
-	});
+	for (const [schemeName, scheme] of Object.entries(securitySchemes)) {
+		const common = scheme.description !== void 0 ? {
+			schemeName,
+			description: scheme.description
+		} : { schemeName };
+		const httpScheme = scheme.type === "http" ? scheme.scheme?.toLowerCase() : void 0;
+		if (httpScheme === "bearer") schemes.push({
+			kind: "bearer",
+			...common
+		});
+		else if (httpScheme === "basic") schemes.push({
+			kind: "basic",
+			...common
+		});
+		else if (scheme.type === "apiKey" && scheme.in && scheme.name) schemes.push({
+			kind: "apiKey",
+			...common,
+			in: scheme.in,
+			name: scheme.name
+		});
+		else if (scheme.type === "oauth2" && scheme.flows) schemes.push({
+			kind: "oauth2",
+			...common,
+			flows: scheme.flows
+		});
+		else {
+			const detail = scheme.type === "http" ? `type: http, scheme: ${scheme.scheme}` : `type: ${scheme.type}`;
+			console.warn(`[oagen] Warning: Unsupported security scheme "${schemeName}" (${detail}) omitted from spec.auth`);
+		}
+	}
 	return schemes.length > 0 ? schemes : void 0;
 }
 //#endregion