@kubb/adapter-oas 5.0.0-beta.11 → 5.0.0-beta.110

package/dist/index.cjs

@@ -16,40 +16,29 @@ var __copyProps = (to, from, except, desc) => {
 	}
 	return to;
 };
-var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule || !__hasOwnProp.call(mod, "default") ? __defProp(target, "default", {
 	value: mod,
 	enumerable: true
 }) : target, mod));
 //#endregion
+let _kubb_ast = require("@kubb/ast");
 let _kubb_core = require("@kubb/core");
+let node_fs_promises = require("node:fs/promises");
 let node_path = require("node:path");
 node_path = __toESM(node_path, 1);
-let _redocly_openapi_core = require("@redocly/openapi-core");
-let oas_normalize = require("oas-normalize");
-oas_normalize = __toESM(oas_normalize, 1);
-let swagger2openapi = require("swagger2openapi");
-swagger2openapi = __toESM(swagger2openapi, 1);
-let oas = require("oas");
-oas = __toESM(oas, 1);
-let oas_types = require("oas/types");
-let oas_utils = require("oas/utils");
+let yaml = require("yaml");
+let _scalar_openapi_upgrader = require("@scalar/openapi-upgrader");
+let api_ref_bundler = require("api-ref-bundler");
+let _kubb_kit = require("@kubb/kit");
 //#region src/constants.ts
 /**
 * Default parser options applied when no explicit options are provided.
-*
-* @example
-* ```ts
-* import { DEFAULT_PARSER_OPTIONS } from '@kubb/adapter-oas'
-*
-* const parser = createOasParser(oas)
-* const root = parser.parse({ ...DEFAULT_PARSER_OPTIONS, dateType: 'date' })
-* ```
 */
 const DEFAULT_PARSER_OPTIONS = {
 	dateType: "string",
 	integerType: "bigint",
-	unknownType: "any",
-	emptySchemaType: "any",
+	unknownType: "unknown",
+	emptySchemaType: "unknown",
 	enumSuffix: "enum"
 };
 /**
@@ -64,32 +53,26 @@ const DEFAULT_PARSER_OPTIONS = {
 */
 const SCHEMA_REF_PREFIX = "#/components/schemas/";
 /**
-* OpenAPI version string written into the stub document created during multi-spec merges.
-*/
-const MERGE_OPENAPI_VERSION = "3.0.0";
-/**
-* Fallback `info.title` placed in the stub document when merging multiple API files.
-*/
-const MERGE_DEFAULT_TITLE = "Merged API";
-/**
-* Fallback `info.version` placed in the stub document when merging multiple API files.
+* HTTP methods that count as operations on an OpenAPI path item. Other keys
+* (`parameters`, `summary`, `$ref`, vendor extensions) are skipped when iterating operations.
 */
-const MERGE_DEFAULT_VERSION = "1.0.0";
+const SUPPORTED_METHODS = /* @__PURE__ */ new Set([
+	"get",
+	"put",
+	"post",
+	"delete",
+	"options",
+	"head",
+	"patch",
+	"trace"
+]);
 /**
 * Set of JSON Schema keywords that prevent a schema fragment from being inlined during `allOf` flattening.
 *
 * A fragment that contains any of these keys carries structural meaning of its own and must stay as a separate
 * intersection member rather than being merged into the parent.
-*
-* @example
-* ```ts
-* import { structuralKeys } from '@kubb/adapter-oas'
-*
-* const isStructural = Object.keys(fragment).some((key) => structuralKeys.has(key))
-* // true when fragment has e.g. 'properties' or 'oneOf'
-* ```
 */
-const structuralKeys = new Set([
+const structuralKeys = /* @__PURE__ */ new Set([
 	"properties",
 	"items",
 	"additionalProperties",
@@ -99,21 +82,39 @@ const structuralKeys = new Set([
 	"not"
 ]);
 /**
+* Formats `convertFormat` maps to a dedicated type without going through `formatMap`:
+* `int64`, `uint64` and the date/time family. Keep this in sync with the `convertFormat`
+* special-cases in `parser.ts`. `isHandledFormat` reads it so the
+* `KUBB_UNSUPPORTED_FORMAT` diagnostic and the parser agree on what is handled.
+*/
+const specialCasedFormats = /* @__PURE__ */ new Set([
+	"int64",
+	"uint64",
+	"date-time",
+	"date",
+	"time"
+]);
+/**
+* Formats that describe a number, whether they resolve through `formatMap` or through the
+* `convertFormat` special cases. On a `type: 'string'` schema these do not make the value a
+* number: gRPC-gateway and other ProtoJSON producers send 64-bit integers as JSON strings.
+*
+* @see https://protobuf.dev/programming-guides/json/#int64-strings
+*/
+const numericFormats = /* @__PURE__ */ new Set([
+	"int32",
+	"int64",
+	"uint64",
+	"float",
+	"double"
+]);
+/**
 * Static map from OAS `format` strings to Kubb `SchemaType` values.
 *
 * Only formats whose AST type differs from the OAS `type` field appear here.
-* Formats that depend on runtime options (`int64`, `date-time`, `date`, `time`) are handled separately
-* in the parser. `ipv4` and `ipv6` map to their own dedicated schema types; `hostname` and
-* `idn-hostname` map to `'url'` as the closest generic string-format type.
-*
-* @example
-* ```ts
-* import { formatMap } from '@kubb/adapter-oas'
-*
-* formatMap['uuid']   // 'uuid'
-* formatMap['binary'] // 'blob'
-* formatMap['float']  // 'number'
-* ```
+* Formats that depend on runtime options (`int64`, `date-time`, `date`, `time`) are handled
+* separately in the parser. `ipv4` and `ipv6` map to their own dedicated schema types. `hostname`
+* and `idn-hostname` map to `'url'` as the closest generic string-format type.
 */
 const formatMap = {
 	uuid: "uuid",
@@ -134,49 +135,29 @@ const formatMap = {
 };
 /**
 * Vendor extension keys that attach human-readable labels to enum values, checked in priority order.
-*
-* @example
-* ```ts
-* import { enumExtensionKeys } from '@kubb/adapter-oas'
-*
-* const key = enumExtensionKeys.find((k) => k in schema) // 'x-enumNames' | 'x-enum-varnames' | undefined
-* ```
 */
 const enumExtensionKeys = ["x-enumNames", "x-enum-varnames"];
 /**
-* Maps `'any' | 'unknown' | 'void'` option strings to their `ScalarSchemaType` constant.
-* Replaces a plain object lookup with a `Map` for explicit key membership testing via `.has()`.
+* Vendor extension keys that attach human-readable descriptions to enum values, checked in priority order.
 */
-const typeOptionMap = new Map([
-	["any", _kubb_core.ast.schemaTypes.any],
-	["unknown", _kubb_core.ast.schemaTypes.unknown],
-	["void", _kubb_core.ast.schemaTypes.void]
-]);
+const enumDescriptionKeys = ["x-enumDescriptions", "x-enum-descriptions"];
 //#endregion
-//#region src/discriminator.ts
+//#region src/emit/discriminator/propagate.ts
 /**
-* Injects discriminator enum values into child schemas so they know which value identifies them.
-*
-* Finds every union schema in `input.schemas` that has a `discriminatorPropertyName`, collects the
-* enum value each union member is mapped to, then adds (or replaces) that property on the matching
-* child object schema.
+* Maps each child schema name to its discriminator patch data by scanning the given
+* top-level AST schema nodes for union schemas that carry a `discriminatorPropertyName`.
 *
-* Returns a new `InputNode` — the original is never mutated.
-*
-* @example
-* ```ts
-* const { root } = parseOas(document, options)
-* const next = applyDiscriminatorInheritance(root)
-* ```
+* Called on a small pre-parsed subset of schemas (only the discriminator parents)
+* rather than on all schemas at once.
 */
-function applyDiscriminatorInheritance(root) {
+function buildDiscriminatorChildMap(schemas) {
 	const childMap = /* @__PURE__ */ new Map();
-	for (const schema of root.schemas) {
-		let unionNode = _kubb_core.ast.narrowSchema(schema, "union");
+	for (const schema of schemas) {
+		let unionNode = _kubb_ast.ast.narrowSchema(schema, "union");
 		if (!unionNode) {
-			const intersectionMembers = _kubb_core.ast.narrowSchema(schema, "intersection")?.members;
+			const intersectionMembers = _kubb_ast.ast.narrowSchema(schema, "intersection")?.members;
 			if (intersectionMembers) for (const m of intersectionMembers) {
-				const u = _kubb_core.ast.narrowSchema(m, "union");
+				const u = _kubb_ast.ast.narrowSchema(m, "union");
 				if (u) {
 					unionNode = u;
 					break;
@@ -186,52 +167,56 @@ function applyDiscriminatorInheritance(root) {
 		if (!unionNode?.discriminatorPropertyName || !unionNode.members) continue;
 		const { discriminatorPropertyName, members } = unionNode;
 		for (const member of members) {
-			const intersectionNode = _kubb_core.ast.narrowSchema(member, "intersection");
+			const intersectionNode = _kubb_ast.ast.narrowSchema(member, "intersection");
 			if (!intersectionNode?.members) continue;
-			let refNode;
-			let objNode;
+			let refNode = null;
+			let objNode = null;
 			for (const m of intersectionNode.members) {
-				refNode ??= _kubb_core.ast.narrowSchema(m, "ref");
-				objNode ??= _kubb_core.ast.narrowSchema(m, "object");
+				refNode ??= _kubb_ast.ast.narrowSchema(m, "ref");
+				objNode ??= _kubb_ast.ast.narrowSchema(m, "object");
 			}
 			if (!refNode?.name || !objNode) continue;
 			const prop = objNode.properties.find((p) => p.name === discriminatorPropertyName);
-			const enumNode = prop ? _kubb_core.ast.narrowSchema(prop.schema, "enum") : void 0;
+			const enumNode = prop ? _kubb_ast.ast.narrowSchema(prop.schema, "enum") : null;
 			if (!enumNode?.enumValues?.length) continue;
 			const enumValues = enumNode.enumValues.filter((v) => v !== null);
 			if (!enumValues.length) continue;
 			const existing = childMap.get(refNode.name);
-			if (existing) existing.enumValues.push(...enumValues);
-			else childMap.set(refNode.name, {
-				propertyName: discriminatorPropertyName,
-				enumValues: [...enumValues]
-			});
+			if (!existing) {
+				childMap.set(refNode.name, {
+					propertyName: discriminatorPropertyName,
+					enumValues: [...enumValues]
+				});
+				continue;
+			}
+			existing.enumValues.push(...enumValues);
 		}
 	}
-	if (childMap.size === 0) return root;
-	return _kubb_core.ast.transform(root, { schema(node, { parent }) {
-		if (parent?.kind !== "Input" || !node.name) return;
-		const entry = childMap.get(node.name);
-		if (!entry) return;
-		const objectNode = _kubb_core.ast.narrowSchema(node, "object");
-		if (!objectNode) return;
-		const { propertyName, enumValues } = entry;
-		const enumSchema = _kubb_core.ast.createSchema({
-			type: "enum",
-			enumValues
-		});
-		const newProp = _kubb_core.ast.createProperty({
-			name: propertyName,
-			required: true,
-			schema: enumSchema
-		});
-		const existingIdx = objectNode.properties.findIndex((p) => p.name === propertyName);
-		const newProperties = existingIdx >= 0 ? objectNode.properties.map((p, i) => i === existingIdx ? newProp : p) : [...objectNode.properties, newProp];
-		return {
-			...objectNode,
-			properties: newProperties
-		};
-	} });
+	return childMap;
+}
+/**
+* Patches a single top-level `SchemaNode` with its discriminator entry (adds or replaces
+* the discriminant property).
+*/
+function patchDiscriminatorNode(node, entry) {
+	const objectNode = _kubb_ast.ast.narrowSchema(node, "object");
+	if (!objectNode) return node;
+	const { propertyName, enumValues } = entry;
+	const enumSchema = _kubb_ast.ast.factory.createSchema({
+		type: "enum",
+		enumValues
+	});
+	const newProp = _kubb_ast.ast.factory.createProperty({
+		name: propertyName,
+		required: true,
+		schema: enumSchema
+	});
+	const existingIdx = objectNode.properties.findIndex((p) => p.name === propertyName);
+	const newProperties = existingIdx >= 0 ? objectNode.properties.map((p, i) => i === existingIdx ? newProp : p) : [...objectNode.properties, newProp];
+	return {
+		...objectNode,
+		properties: newProperties
+	};
 }
 //#endregion
 //#region ../../internals/utils/src/casing.ts
@@ -245,470 +230,291 @@ function applyDiscriminatorInheritance(root) {
 function toCamelOrPascal(text, pascal) {
 	return text.trim().replace(/([a-z\d])([A-Z])/g, "$1 $2").replace(/([A-Z]+)([A-Z][a-z])/g, "$1 $2").replace(/(\d)([a-z])/g, "$1 $2").split(/[\s\-_./\\:]+/).filter(Boolean).map((word, i) => {
 		if (word.length > 1 && word === word.toUpperCase()) return word;
-		if (i === 0 && !pascal) return word.charAt(0).toLowerCase() + word.slice(1);
-		return word.charAt(0).toUpperCase() + word.slice(1);
+		return (i === 0 && !pascal ? word.charAt(0).toLowerCase() : word.charAt(0).toUpperCase()) + word.slice(1);
 	}).join("").replace(/[^a-zA-Z0-9]/g, "");
 }
 /**
-* Splits `text` on `.` and applies `transformPart` to each segment.
-* The last segment receives `isLast = true`, all earlier segments receive `false`.
-* Segments are joined with `/` to form a file path.
-*
-* Only splits on dots followed by a letter so that version numbers
-* embedded in operationIds (e.g. `v2025.0`) are kept intact.
-*
-* Empty segments are filtered before joining. They arise when the text starts with
-* a dot followed immediately by a letter (e.g. `..Schema` splits into `['..', 'Schema']`
-* and `'..'` transforms to an empty string). Without this filter the join would produce
-* a leading `/`, which `path.resolve` would interpret as an absolute path, allowing
-* generated files to escape the configured output directory.
-*/
-function applyToFileParts(text, transformPart) {
-	const parts = text.split(/\.(?=[a-zA-Z])/);
-	return parts.map((part, i) => transformPart(part, i === parts.length - 1)).filter(Boolean).join("/");
-}
-/**
-* Converts `text` to camelCase.
-* When `isFile` is `true`, dot-separated segments are each cased independently and joined with `/`.
-*
-* @example
-* camelCase('hello-world')                   // 'helloWorld'
-* camelCase('pet.petId', { isFile: true })   // 'pet/petId'
-*/
-function camelCase(text, { isFile, prefix = "", suffix = "" } = {}) {
-	if (isFile) return applyToFileParts(text, (part, isLast) => camelCase(part, isLast ? {
-		prefix,
-		suffix
-	} : {}));
-	return toCamelOrPascal(`${prefix} ${text} ${suffix}`, false);
-}
-/**
 * Converts `text` to PascalCase.
-* When `isFile` is `true`, the last dot-separated segment is PascalCased and earlier segments are camelCased.
-*
-* @example
-* pascalCase('hello-world')                  // 'HelloWorld'
-* pascalCase('pet.petId', { isFile: true })  // 'pet/PetId'
-*/
-function pascalCase(text, { isFile, prefix = "", suffix = "" } = {}) {
-	if (isFile) return applyToFileParts(text, (part, isLast) => isLast ? pascalCase(part, {
-		prefix,
-		suffix
-	}) : camelCase(part));
-	return toCamelOrPascal(`${prefix} ${text} ${suffix}`, true);
-}
-//#endregion
-//#region ../../internals/utils/src/object.ts
-/**
-* Returns `true` when `value` is a plain (non-null, non-array) object.
 *
-* @example
-* ```ts
-* isPlainObject({})          // true
-* isPlainObject([])          // false
-* isPlainObject(null)        // false
-* ```
-*/
-function isPlainObject(value) {
-	return typeof value === "object" && value !== null && Object.getPrototypeOf(value) === Object.prototype;
-}
-/**
-* Recursively merges `source` into `target`, combining nested plain objects.
-* Arrays and non-object values from `source` override the corresponding values in `target`.
+* @example Word boundaries
+* `pascalCase('hello-world') // 'HelloWorld'`
 *
-* @example
-* ```ts
-* mergeDeep({ a: { x: 1 } }, { a: { y: 2 } })
-* // { a: { x: 1, y: 2 } }
-* ```
+* @example With a suffix
+* `pascalCase('tag', { suffix: 'schema' }) // 'TagSchema'`
 */
-function mergeDeep(target, source) {
-	const result = { ...target };
-	for (const key of Object.keys(source)) {
-		const sv = source[key];
-		const tv = result[key];
-		result[key] = sv !== null && typeof sv === "object" && !Array.isArray(sv) && tv !== null && typeof tv === "object" && !Array.isArray(tv) ? mergeDeep(tv, sv) : sv;
-	}
-	return result;
+function pascalCase(text, { prefix = "", suffix = "" } = {}) {
+	return toCamelOrPascal(`${prefix} ${text} ${suffix}`, true);
 }
 //#endregion
-//#region ../../internals/utils/src/reserved.ts
-/**
-* JavaScript and Java reserved words.
-* @link https://github.com/jonschlinkert/reserved/blob/master/index.js
-*/
-const reservedWords = new Set([
-	"abstract",
-	"arguments",
-	"boolean",
-	"break",
-	"byte",
-	"case",
-	"catch",
-	"char",
-	"class",
-	"const",
-	"continue",
-	"debugger",
-	"default",
-	"delete",
-	"do",
-	"double",
-	"else",
-	"enum",
-	"eval",
-	"export",
-	"extends",
-	"false",
-	"final",
-	"finally",
-	"float",
-	"for",
-	"function",
-	"goto",
-	"if",
-	"implements",
-	"import",
-	"in",
-	"instanceof",
-	"int",
-	"interface",
-	"let",
-	"long",
-	"native",
-	"new",
-	"null",
-	"package",
-	"private",
-	"protected",
-	"public",
-	"return",
-	"short",
-	"static",
-	"super",
-	"switch",
-	"synchronized",
-	"this",
-	"throw",
-	"throws",
-	"transient",
-	"true",
-	"try",
-	"typeof",
-	"var",
-	"void",
-	"volatile",
-	"while",
-	"with",
-	"yield",
-	"Array",
-	"Date",
-	"hasOwnProperty",
-	"Infinity",
-	"isFinite",
-	"isNaN",
-	"isPrototypeOf",
-	"length",
-	"Math",
-	"name",
-	"NaN",
-	"Number",
-	"Object",
-	"prototype",
-	"String",
-	"toString",
-	"undefined",
-	"valueOf"
-]);
+//#region ../../internals/utils/src/errors.ts
 /**
-* Returns `true` when `name` is a syntactically valid JavaScript variable name.
+* Extracts a human-readable message from any thrown value.
 *
 * @example
 * ```ts
-* isValidVarName('status')  // true
-* isValidVarName('class')   // false (reserved word)
-* isValidVarName('42foo')   // false (starts with digit)
+* getErrorMessage(new Error('oops')) // 'oops'
+* getErrorMessage('plain string')    // 'plain string'
 * ```
 */
-function isValidVarName(name) {
-	if (!name || reservedWords.has(name)) return false;
-	return /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(name);
+function getErrorMessage(value) {
+	return value instanceof Error ? value.message : String(value);
 }
 //#endregion
-//#region ../../internals/utils/src/urlPath.ts
+//#region ../../internals/utils/src/runtime.ts
 /**
-* Parses and transforms an OpenAPI/Swagger path string into various URL formats.
+* Detects the JavaScript runtime executing the current process and exposes its name and version.
 *
-* @example
-* const p = new URLPath('/pet/{petId}')
-* p.URL      // '/pet/:petId'
-* p.template // '`/pet/${petId}`'
+* Prefer the shared {@link runtime} instance over constructing your own.
 */
-var URLPath = class {
-	/**
-	* The raw OpenAPI/Swagger path string, e.g. `/pet/{petId}`.
-	*/
-	path;
-	#options;
-	constructor(path, options = {}) {
-		this.path = path;
-		this.#options = options;
-	}
-	/** Converts the OpenAPI path to Express-style colon syntax, e.g. `/pet/{petId}` → `/pet/:petId`.
-	*
-	* @example
-	* ```ts
-	* new URLPath('/pet/{petId}').URL // '/pet/:petId'
-	* ```
-	*/
-	get URL() {
-		return this.toURLPath();
-	}
-	/** Returns `true` when `path` is a fully-qualified URL (e.g. starts with `https://`).
-	*
-	* @example
-	* ```ts
-	* new URLPath('https://petstore.swagger.io/v2/pet').isURL // true
-	* new URLPath('/pet/{petId}').isURL                       // false
-	* ```
-	*/
-	get isURL() {
-		try {
-			return !!new URL(this.path).href;
-		} catch {
-			return false;
-		}
-	}
+var Runtime = class {
 	/**
-	* Converts the OpenAPI path to a TypeScript template literal string.
+	* `true` when the current process is running under Bun.
 	*
-	* @example
-	* new URLPath('/pet/{petId}').template              // '`/pet/${petId}`'
-	* new URLPath('/account/monetary-accountID').template // '`/account/${monetaryAccountId}`'
-	*/
-	get template() {
-		return this.toTemplateString();
-	}
-	/** Returns the path and its extracted params as a structured `URLObject`, or as a stringified expression when `stringify` is set.
-	*
-	* @example
-	* ```ts
-	* new URLPath('/pet/{petId}').object
-	* // { url: '/pet/:petId', params: { petId: 'petId' } }
-	* ```
-	*/
-	get object() {
-		return this.toObject();
-	}
-	/** Returns a map of path parameter names, or `undefined` when the path has no parameters.
+	* Detection keys off the global `Bun` object rather than `process.versions`,
+	* because Bun polyfills `process.versions.node` for Node compatibility and would
+	* otherwise look like Node.
 	*
 	* @example
 	* ```ts
-	* new URLPath('/pet/{petId}').params // { petId: 'petId' }
-	* new URLPath('/pet').params         // undefined
+	* if (runtime.isBun) {
+	*   await Bun.write(path, data)
+	* }
 	* ```
 	*/
-	get params() {
-		return this.getParams();
-	}
-	#transformParam(raw) {
-		const param = isValidVarName(raw) ? raw : camelCase(raw);
-		return this.#options.casing === "camelcase" ? camelCase(param) : param;
+	get isBun() {
+		return typeof Bun !== "undefined";
 	}
 	/**
-	* Iterates over every `{param}` token in `path`, calling `fn` with the raw token and transformed name.
+	* `true` when the current process is running under Deno.
 	*/
-	#eachParam(fn) {
-		for (const match of this.path.matchAll(/\{([^}]+)\}/g)) {
-			const raw = match[1];
-			fn(raw, this.#transformParam(raw));
-		}
-	}
-	toObject({ type = "path", replacer, stringify } = {}) {
-		const object = {
-			url: type === "path" ? this.toURLPath() : this.toTemplateString({ replacer }),
-			params: this.getParams()
-		};
-		if (stringify) {
-			if (type === "template") return JSON.stringify(object).replaceAll("'", "").replaceAll(`"`, "");
-			if (object.params) return `{ url: '${object.url}', params: ${JSON.stringify(object.params).replaceAll("'", "").replaceAll(`"`, "")} }`;
-			return `{ url: '${object.url}' }`;
-		}
-		return object;
+	get isDeno() {
+		return typeof globalThis.Deno !== "undefined";
 	}
 	/**
-	* Converts the OpenAPI path to a TypeScript template literal string.
-	* An optional `replacer` can transform each extracted parameter name before interpolation.
+	* `true` when the current process is running under Node.
 	*
-	* @example
-	* new URLPath('/pet/{petId}').toTemplateString() // '`/pet/${petId}`'
+	* Bun and Deno are excluded first so a polyfilled `process` does not register as Node.
 	*/
-	toTemplateString({ prefix = "", replacer } = {}) {
-		return `\`${prefix}${this.path.split(/\{([^}]+)\}/).map((part, i) => {
-			if (i % 2 === 0) return part;
-			const param = this.#transformParam(part);
-			return `\${${replacer ? replacer(param) : param}}`;
-		}).join("")}\``;
+	get isNode() {
+		return !this.isBun && !this.isDeno && typeof process !== "undefined" && process.versions?.node != null;
 	}
 	/**
-	* Extracts all `{param}` segments from the path and returns them as a key-value map.
-	* An optional `replacer` transforms each parameter name in both key and value positions.
-	* Returns `undefined` when no path parameters are found.
+	* Name of the runtime executing the current process.
 	*
 	* @example
 	* ```ts
-	* new URLPath('/pet/{petId}/tag/{tagId}').getParams()
-	* // { petId: 'petId', tagId: 'tagId' }
+	* runtime.name // 'bun' when run with `bun kubb`, 'node' otherwise
 	* ```
 	*/
-	getParams(replacer) {
-		const params = {};
-		this.#eachParam((_raw, param) => {
-			const key = replacer ? replacer(param) : param;
-			params[key] = key;
-		});
-		return Object.keys(params).length > 0 ? params : void 0;
+	get name() {
+		if (this.isBun) return "bun";
+		if (this.isDeno) return "deno";
+		return "node";
 	}
-	/** Converts the OpenAPI path to Express-style colon syntax.
+	/**
+	* Version of the active runtime, or an empty string when it cannot be read.
 	*
 	* @example
 	* ```ts
-	* new URLPath('/pet/{petId}').toURLPath() // '/pet/:petId'
+	* runtime.version // '1.3.11' under Bun, '22.22.2' under Node
 	* ```
 	*/
-	toURLPath() {
-		return this.path.replace(/\{([^}]+)\}/g, ":$1");
+	get version() {
+		if (this.isBun) return process.versions.bun ?? "";
+		if (this.isDeno) return globalThis.Deno?.version?.deno ?? "";
+		return process.versions?.node ?? "";
 	}
 };
+/**
+* Shared {@link Runtime} instance describing the JavaScript runtime executing the current process.
+*/
+const runtime = new Runtime();
 //#endregion
-//#region src/guards.ts
+//#region ../../internals/utils/src/fs.ts
 /**
-* Returns `true` when `doc` is a Swagger 2.0 document (no `openapi` key).
+* Resolves to `true` when the file or directory at `path` exists.
+* Uses `Bun.file().exists()` when running under Bun, `fs.access` otherwise.
 *
 * @example
 * ```ts
-* if (isOpenApiV2Document(doc)) {
-*   // doc is OpenAPIV2.Document
+* if (await exists('./kubb.config.ts')) {
+*   const content = await read('./kubb.config.ts')
 * }
 * ```
 */
-function isOpenApiV2Document(doc) {
-	return !!doc && isPlainObject(doc) && !("openapi" in doc);
+async function exists(path) {
+	if (runtime.isBun) return Bun.file(path).exists();
+	return (0, node_fs_promises.access)(path).then(() => true, () => false);
 }
 /**
-* Returns `true` when a schema should be treated as nullable.
-*
-* Recognizes all nullable signals across OAS versions: `nullable: true` (OAS 3.0),
-* `x-nullable: true` (vendor extension), `type: 'null'`, and `type: ['null', ...]` (OAS 3.1).
+* Reads the file at `path` as a UTF-8 string.
+* Uses `Bun.file().text()` when running under Bun, `fs.readFile` otherwise.
 *
 * @example
 * ```ts
-* isNullable({ type: 'string', nullable: true }) // true
-* isNullable({ type: ['string', 'null'] })       // true
-* isNullable({ type: 'string' })                 // false
+* const source = await read('./src/Pet.ts')
 * ```
 */
-function isNullable(schema) {
-	if ((schema?.nullable ?? schema?.["x-nullable"]) === true) return true;
-	const schemaType = schema?.type;
-	if (schemaType === "null") return true;
-	if (Array.isArray(schemaType)) return schemaType.includes("null");
-	return false;
+async function read(path) {
+	if (runtime.isBun) return Bun.file(path).text();
+	return (0, node_fs_promises.readFile)(path, { encoding: "utf8" });
 }
+//#endregion
+//#region src/load/source.ts
+const urlRegExp = /^https?:\/+/i;
 /**
-* Returns `true` when `obj` is an OpenAPI `$ref` pointer object.
-*
-* @example
-* ```ts
-* isReference({ $ref: '#/components/schemas/Pet' }) // true
-* isReference({ type: 'string' })                   // false
-* ```
+* Node reports every connection failure as `TypeError: fetch failed` and keeps the useful part
+* (`connect ECONNREFUSED 127.0.0.1:8000`) on `cause`, one level deeper again when a host resolves
+* to several addresses and the attempts collect into an `AggregateError`.
 */
-function isReference(obj) {
-	return !!obj && typeof obj === "object" && "$ref" in obj;
+function describeFetchFailure(error) {
+	if (error instanceof AggregateError && error.errors.length > 0) return describeFetchFailure(error.errors[0]);
+	if (error instanceof Error && error.cause instanceof Error) return describeFetchFailure(error.cause) || error.message;
+	return getErrorMessage(error);
+}
+function helpForStatus(status) {
+	if (status === 401 || status === 403) return "The server refused the request. Kubb sends no credentials, so serve the document without authentication or download it and set `input` to the local file.";
+	if (status === 404) return "Check the URL. Open it in a browser or with `curl` to confirm it serves the OpenAPI document.";
+	if (status >= 500) return "The server failed while serving the document. Check that it is healthy, then run Kubb again.";
+	return "Open the URL in a browser or with `curl` to see what the server returns, then point `input` at a URL that serves the OpenAPI document.";
+}
+async function fetchSource(url) {
+	try {
+		return await fetch(url);
+	} catch (error) {
+		throw new _kubb_core.Diagnostics.Error({
+			code: _kubb_core.Diagnostics.code.inputUnreachable,
+			severity: "error",
+			message: `Cannot reach ${url.href}: ${describeFetchFailure(error)}`,
+			help: "Check that the host is running and reachable from this machine. For a local server, start it and confirm the port matches the one in `input`.",
+			location: { kind: "config" },
+			cause: error instanceof Error ? error : void 0
+		});
+	}
+}
+async function readSource(sourcePath) {
+	if (urlRegExp.test(sourcePath)) {
+		const url = new URL(sourcePath);
+		const response = await fetchSource(url);
+		if (!response.ok) {
+			const status = response.statusText ? `${response.status} ${response.statusText}` : String(response.status);
+			throw new _kubb_core.Diagnostics.Error({
+				code: _kubb_core.Diagnostics.code.inputRequestFailed,
+				severity: "error",
+				message: `The server at ${url.href} answered with HTTP ${status} instead of the OpenAPI document.`,
+				help: helpForStatus(response.status),
+				location: { kind: "config" }
+			});
+		}
+		return response.text();
+	}
+	return read(sourcePath);
 }
 /**
-* Returns `true` when `obj` is a schema with a structured OAS 3.x `discriminator` object.
+* Reads and parses one source file or URL referenced during bundling: YAML/JSON is parsed into an
+* object, Markdown is returned as-is (bundled inline rather than dereferenced).
 *
-* @example
-* ```ts
-* isDiscriminator({ discriminator: { propertyName: 'type', mapping: {} } }) // true
-* isDiscriminator({ discriminator: 'type' })                                 // false (Swagger 2 string form)
-* ```
+* JSON is valid YAML, so `yaml`'s `parse` handles both, but its general-purpose parser (comments,
+* anchors, block scalars, multi-document streams) does much more work than `JSON.parse` needs to.
+* `JSON.parse` runs first and fails fast on the first non-JSON character, so a real YAML document
+* falls through to `parse` at negligible cost.
 */
-function isDiscriminator(obj) {
-	const record = obj;
-	return !!obj && !!record["discriminator"] && typeof record["discriminator"] !== "string";
+async function resolveSource(sourcePath) {
+	const data = await readSource(sourcePath);
+	if (sourcePath.toLowerCase().endsWith(".md")) return data;
+	try {
+		return JSON.parse(data);
+	} catch {
+		return (0, yaml.parse)(data);
+	}
+}
+/**
+* Throws a coded `KUBB_INPUT_NOT_FOUND` diagnostic when a local input path does not exist.
+* URLs are skipped: a remote input reports `KUBB_INPUT_REQUEST_FAILED` or `KUBB_INPUT_UNREACHABLE`
+* from the request itself. A malformed but readable file is left for `parseDocument` to surface
+* its parse error instead.
+*/
+async function assertInputExists(input) {
+	if (URL.canParse(input)) return;
+	if (!await exists(input)) throw new _kubb_core.Diagnostics.Error({
+		code: _kubb_core.Diagnostics.code.inputNotFound,
+		severity: "error",
+		message: `Cannot read the file set as \`input\` (or via \`kubb generate PATH\`): ${input}`,
+		help: "Check that the path exists and is readable, then set it as `input` or pass it as `kubb generate PATH`.",
+		location: { kind: "config" }
+	});
 }
 //#endregion
-//#region src/factory.ts
+//#region src/load/normalize.ts
 /**
-* Loads and dereferences an OpenAPI document, returning the raw `Document`.
+* True when `node` contains a `$ref` pointing outside the current document (a relative path,
+* absolute path, or URL). An internal `#/...` fragment does not count.
 *
-* Accepts a file path string or an already-parsed document object. File paths are bundled via
-* Redocly to resolve external `$ref`s. Swagger 2.0 documents are automatically up-converted
-* to OpenAPI 3.0 via `swagger2openapi`.
+* `Object.values` reads array elements and object property values alike, so the same recursion
+* walks both without a separate array branch.
+*/
+function hasExternalRef(node) {
+	if (!node || typeof node !== "object") return false;
+	const ref = node.$ref;
+	if (typeof ref === "string" && !ref.startsWith("#")) return true;
+	return Object.values(node).some(hasExternalRef);
+}
+/**
+* Bundles a multi-file OpenAPI document into a single document via `api-ref-bundler`.
 *
-* @example
-* ```ts
-* const document = await parseDocument('./openapi.yaml')
-* const document = await parse(rawDocumentObject, { canBundle: false })
-* ```
+* External file schemas are hoisted into named `components.schemas` entries, so a property
+* pointing at `./schemas/User.yaml` ends up referencing `#/components/schemas/User`. Generators
+* can then emit a named type with an import instead of inlining the shape. Sources are read with
+* the Bun-aware `read` util for local YAML and JSON files, and with `fetch` for HTTP(S) URLs.
+*
+* A document with no `$ref` outside itself has nothing to bundle, so it skips `api-ref-bundler`
+* and returns as parsed. `bundle` only rewrites external refs into internal ones; on an
+* all-internal document it is a no-op that still walks the whole tree to confirm that, which
+* costs real time on a large spec.
+*
+* @example Local file
+* `const document = await bundleDocument('./openapi.yaml')`
+*
+* @example Remote URL
+* `const document = await bundleDocument('https://example.com/openapi.yaml')`
 */
-async function parseDocument(pathOrApi, { canBundle = true, enablePaths = true } = {}) {
-	if (typeof pathOrApi === "string" && canBundle) return parseDocument((await (0, _redocly_openapi_core.bundle)({
-		ref: pathOrApi,
-		config: await (0, _redocly_openapi_core.loadConfig)(),
-		base: pathOrApi
-	})).bundle.parsed, {
-		canBundle,
-		enablePaths
-	});
-	const document = await new oas_normalize.default(pathOrApi, {
-		enablePaths,
-		colorizeErrors: true
-	}).load();
-	if (isOpenApiV2Document(document)) {
-		const { openapi } = await swagger2openapi.default.convertObj(document, { anchors: true });
-		return openapi;
-	}
-	return document;
+async function bundleDocument(pathOrUrl) {
+	const cache = /* @__PURE__ */ new Map();
+	const resolver = (sourcePath) => {
+		const key = urlRegExp.test(sourcePath) ? new URL(sourcePath).href : sourcePath;
+		const cached = cache.get(key);
+		if (cached) return cached;
+		const result = resolveSource(sourcePath);
+		cache.set(key, result);
+		return result;
+	};
+	const root = await resolver(pathOrUrl);
+	if (typeof root === "object" && root !== null && !hasExternalRef(root)) return root;
+	return await (0, api_ref_bundler.bundle)(pathOrUrl, resolver);
 }
 /**
-* Deep-merges multiple OpenAPI documents into a single `Document`.
+* Loads and bundles an OpenAPI document, returning the raw `Document`.
 *
-* Each document is parsed independently then recursively merged via `mergeDeep` from `@internals/utils`.
-* Throws when the input array is empty.
+* A string is a file path or URL: it is bundled via `api-ref-bundler`, hoisting external file
+* schemas into named `components.schemas` entries so generators can emit named types and imports.
+* An object is treated as an already-parsed document. Swagger 2.0 and OpenAPI 3.0 documents are
+* up-converted to OpenAPI 3.1 via `@scalar/openapi-upgrader`.
 *
 * @example
 * ```ts
-* const document = await mergeDocuments(['./pets.yaml', './orders.yaml'])
+* const document = await parseDocument('./openapi.yaml')
+* const document = await parseDocument(rawDocumentObject)
 * ```
 */
-async function mergeDocuments(pathOrApi) {
-	const documents = await Promise.all(pathOrApi.map((p) => parseDocument(p, {
-		enablePaths: false,
-		canBundle: false
-	})));
-	if (documents.length === 0) throw new Error("No OAS documents provided for merging.");
-	const seed = {
-		openapi: MERGE_OPENAPI_VERSION,
-		info: {
-			title: MERGE_DEFAULT_TITLE,
-			version: MERGE_DEFAULT_VERSION
-		},
-		paths: {},
-		components: { schemas: {} }
-	};
-	return parseDocument(documents.reduce((acc, current) => mergeDeep(acc, current), seed));
+async function parseDocument(pathOrApi) {
+	if (typeof pathOrApi === "string") return parseDocument(await bundleDocument(pathOrApi));
+	return (0, _scalar_openapi_upgrader.upgrade)(pathOrApi, "3.1");
 }
 /**
 * Creates a `Document` from an `AdapterSource`.
 *
-* Handles all three source types:
-* - `{ type: 'path' }` — resolves and bundles a local file path or remote URL.
-* - `{ type: 'paths' }` — merges multiple file paths into a single document.
-* - `{ type: 'data' }` — parses an inline string (YAML/JSON) or raw object.
+* - `{ type: 'path' }` resolves and bundles a local file path or remote URL.
+* - `{ type: 'data' }` parses an inline string (YAML/JSON) or raw object.
 *
 * @example
 * ```ts
@@ -716,17 +522,33 @@ async function mergeDocuments(pathOrApi) {
 * const document = await parseFromConfig({ type: 'data', data: '{"openapi":"3.0.0",...}' })
 * ```
 */
-function parseFromConfig(source) {
-	if (source.type === "data") {
-		if (typeof source.data === "object") return parseDocument(structuredClone(source.data));
-		return parseDocument(source.data, { canBundle: false });
-	}
-	if (source.type === "paths") return mergeDocuments(source.paths);
-	if (new URLPath(source.path).isURL) return parseDocument(source.path);
-	return parseDocument(node_path.default.resolve(node_path.default.dirname(source.path), source.path));
+async function parseFromConfig(source) {
+	if (source.type === "data") return parseDocument(typeof source.data === "string" ? (0, yaml.parse)(source.data) : structuredClone(source.data));
+	if (URL.canParse(source.path)) return parseDocument(source.path);
+	const resolved = node_path.default.resolve(node_path.default.dirname(source.path), source.path);
+	await assertInputExists(resolved);
+	return parseDocument(resolved);
+}
+/**
+* Asserts the parsed input is an OpenAPI or Swagger document.
+*
+* {@link validateDocument} keeps spec violations non-fatal so imperfect but usable documents still
+* generate. That leniency also swallowed input that is not a document at all, which then produced
+* an empty build with a success exit code. A missing version field is the one failure that cannot
+* be a usable document, so it is fatal regardless of the `validate` option.
+*/
+function assertDocument(document) {
+	if (document && ("openapi" in document || "swagger" in document)) return;
+	throw new _kubb_core.Diagnostics.Error({
+		code: _kubb_core.Diagnostics.code.invalidDocument,
+		severity: "error",
+		message: "The resolved `input` is not an OpenAPI or Swagger document: it declares no `openapi` or `swagger` version.",
+		help: "Point `input` at a document that declares `openapi` or `swagger`. If you pass an object, pass the spec itself rather than a wrapper such as `{ path }` or `{ data }`.",
+		location: { kind: "config" }
+	});
 }
 /**
-* Validates an OpenAPI document using `oas-normalize` with colorized error output.
+* Validates an OpenAPI document using `@readme/openapi-parser` with colorized error output.
 *
 * @example
 * ```ts
@@ -734,273 +556,130 @@ function parseFromConfig(source) {
 * ```
 */
 async function validateDocument(document, { throwOnError = false } = {}) {
+	const { compileErrors, validate } = await import("@readme/openapi-parser");
 	try {
-		await new oas_normalize.default(document, {
-			enablePaths: true,
-			colorizeErrors: true
-		}).validate({ parser: { validate: { errors: { colorize: true } } } });
+		const result = await validate(structuredClone(document), { validate: { errors: { colorize: true } } });
+		if (!result.valid) throw new Error(compileErrors(result));
 	} catch (error) {
 		if (throwOnError) throw error;
 	}
 }
 //#endregion
-//#region src/refs.ts
-const _refCache = /* @__PURE__ */ new WeakMap();
+//#region src/oas.ts
 /**
-* Resolves a local JSON pointer reference from a document.
+* Returns `true` when a schema should be treated as nullable.
+*
+* Recognizes all nullable signals across OAS versions: `nullable: true` (OAS 3.0),
+* `x-nullable: true` (vendor extension), `type: 'null'`, and `type: ['null', ...]` (OAS 3.1).
+*/
+function isNullable(schema) {
+	if ((schema?.nullable ?? schema?.["x-nullable"]) === true) return true;
+	const schemaType = schema?.type;
+	if (schemaType === "null") return true;
+	if (Array.isArray(schemaType)) return schemaType.includes("null");
+	return false;
+}
+/**
+* Returns `true` when `obj` is an OpenAPI `$ref` pointer object.
+*/
+function isReference(obj) {
+	return !!obj && typeof obj === "object" && "$ref" in obj;
+}
+/**
+* Returns `true` when `obj` is a schema with a structured OAS 3.x `discriminator` object,
+* excluding the Swagger 2 string form.
+*/
+function isDiscriminator(obj) {
+	const record = obj;
+	return !!obj && !!record["discriminator"] && typeof record["discriminator"] !== "string";
+}
+/**
+* Returns `true` when a schema is a binary payload: an octet-stream string body.
+*/
+function isBinary(schema) {
+	return schema.type === "string" && schema.contentMediaType === "application/octet-stream";
+}
+/**
+* MIME type fragments that mark a media type as JSON-like.
 *
-* Accepts `#/...` refs. Returns `null` for empty or non-local refs.
-* Throws when the pointer cannot be resolved.
+* A content type is JSON when it contains any of these substrings. The `+json` entry catches
+* structured-syntax suffixes such as `application/vnd.api+json`.
+*/
+const jsonMimeFragments = [
+	"application/json",
+	"application/x-json",
+	"text/json",
+	"text/x-json",
+	"+json"
+];
+/**
+* Returns `true` when a media type string is JSON-like.
 *
 * @example
 * ```ts
-* resolveRef<SchemaObject>(document, '#/components/schemas/Pet') // SchemaObject | null
+* isJsonMimeType('application/json')         // true
+* isJsonMimeType('application/vnd.api+json') // true
+* isJsonMimeType('multipart/form-data')      // false
 * ```
 */
-function resolveRef(document, $ref) {
-	const origRef = $ref;
-	$ref = $ref.trim();
-	if ($ref === "") return null;
-	if ($ref.startsWith("#")) $ref = globalThis.decodeURIComponent($ref.substring(1));
-	else return null;
-	let docCache = _refCache.get(document);
-	if (!docCache) {
-		docCache = /* @__PURE__ */ new Map();
-		_refCache.set(document, docCache);
-	}
-	if (docCache.has($ref)) return docCache.get($ref);
-	const current = $ref.split("/").filter(Boolean).reduce((obj, key) => obj?.[key], document);
-	if (!current) throw new Error(`Could not find a definition for ${origRef}.`);
-	docCache.set($ref, current);
-	return current;
+function isJsonMimeType(mimeType) {
+	return jsonMimeFragments.some((fragment) => mimeType.includes(fragment));
 }
 /**
-* Resolves a `$ref` object while preserving the original `$ref` field on the result.
-*
-* Useful for parser flows that need both dereferenced fields and pointer
-* identity (for naming/import purposes). Non-reference values are returned as-is.
+* Picks a media-type entry from a `content` map: the first JSON-like media type, falling back to
+* the first declared one. Returns `false` when `content` has no entries.
 *
 * @example
 * ```ts
-* dereferenceWithRef(document, { $ref: '#/components/schemas/Pet' })
-* // { $ref: '#/components/schemas/Pet', type: 'object', properties: { ... } }
+* pickContentEntry({ 'application/xml': xmlEntry, 'application/json': jsonEntry })
+* // ['application/json', jsonEntry]
 * ```
 */
-function dereferenceWithRef(document, schema) {
-	if (isReference(schema)) return {
-		...schema,
-		...resolveRef(document, schema.$ref),
-		$ref: schema.$ref
-	};
-	return schema;
+function pickContentEntry(content) {
+	const mediaTypes = Object.keys(content);
+	const available = mediaTypes.find(isJsonMimeType) ?? mediaTypes[0];
+	return available ? [available, content[available]] : false;
 }
 //#endregion
-//#region src/resolvers.ts
+//#region src/model/components.ts
 /**
-* Replaces `{variable}` placeholders in an OpenAPI server URL with provided values.
-* Resolution order: `overrides[key]` → `variable.default` → left unreplaced.
-* Throws if an override value is not in the variable's `enum` list.
+* Extracts the inline schema from a media-type `content` map.
+*
+* Prefers `preferredContentType` when given, otherwise uses the first key in the map.
+* Returns `null` when `content` is absent, the schema is missing, or the schema is a `$ref`.
 *
 * @example
 * ```ts
-* resolveServerUrl(
-*   { url: 'https://{env}.api.example.com', variables: { env: { default: 'dev', enum: ['dev', 'prod'] } } },
-*   { env: 'prod' },
-* )
-* // 'https://prod.api.example.com'
-* ```
-*/
-function resolveServerUrl(server, overrides) {
-	if (!server.variables) return server.url;
-	let url = server.url;
-	for (const [key, variable] of Object.entries(server.variables)) {
-		const value = overrides?.[key] ?? (variable.default != null ? String(variable.default) : void 0);
-		if (value === void 0) continue;
-		if (variable.enum?.length && !variable.enum.some((e) => String(e) === value)) throw new Error(`Invalid server variable value '${value}' for '${key}' when resolving ${server.url}. Valid values are: ${variable.enum.join(", ")}.`);
-		url = url.replaceAll(`{${key}}`, value);
-	}
-	return url;
-}
-/**
-* Returns the Kubb `SchemaType` for a given OAS `format` string, or `null` if not found.
-* Formats not in `formatMap` (e.g., `int64`, `date-time`) are handled separately by parser options.
-*/
-function getSchemaType(format) {
-	return formatMap[format] ?? null;
-}
-/**
-* Converts an OAS primitive type string to its `PrimitiveSchemaType` equivalent.
-* Numeric types (`number`, `integer`, `bigint`) pass through unchanged. `boolean` maps to `'boolean'`. Everything else becomes `'string'`.
-*/
-function getPrimitiveType(type) {
-	if (type === "number" || type === "integer" || type === "bigint") return type;
-	if (type === "boolean") return "boolean";
-	return "string";
-}
-/**
-* Narrows a content-type string to the `MediaType` union Kubb recognizes, or returns `null`.
-*/
-function getMediaType(contentType) {
-	return Object.values(_kubb_core.ast.mediaTypes).includes(contentType) ? contentType : null;
-}
-/**
-* Returns all parameters for an operation, merging path-level and operation-level entries.
-* Operation-level parameters override path-level ones with the same `in:name` key.
-* `$ref` parameters resolve via `dereferenceWithRef` for backward compatibility.
-*
-* @example
-* ```ts
-* getParameters(document, operation)
-* // [{ name: 'petId', in: 'path', required: true, schema: { type: 'integer' } }]
-* ```
-*/
-function getParameters(document, operation) {
-	const resolveParams = (params) => params.map((p) => dereferenceWithRef(document, p)).filter((p) => !!p && typeof p === "object" && "in" in p && "name" in p);
-	const operationParams = resolveParams(operation.schema?.parameters || []);
-	const pathItem = document.paths?.[operation.path];
-	const pathLevelParams = resolveParams(pathItem && !isReference(pathItem) && pathItem.parameters ? pathItem.parameters : []);
-	const paramMap = /* @__PURE__ */ new Map();
-	for (const p of pathLevelParams) if (p.name && p.in) paramMap.set(`${p.in}:${p.name}`, p);
-	for (const p of operationParams) if (p.name && p.in) paramMap.set(`${p.in}:${p.name}`, p);
-	return Array.from(paramMap.values());
-}
-function getResponseBody(responseBody, contentType) {
-	if (!responseBody) return false;
-	if (isReference(responseBody)) return false;
-	const body = responseBody;
-	if (!body.content) return false;
-	if (contentType) {
-		if (!(contentType in body.content)) return false;
-		return body.content[contentType];
-	}
-	let availableContentType;
-	const contentTypes = Object.keys(body.content);
-	for (const mt of contentTypes) if (oas_utils.matchesMimeType.json(mt)) {
-		availableContentType = mt;
-		break;
-	}
-	if (!availableContentType) availableContentType = contentTypes[0];
-	if (availableContentType) return [
-		availableContentType,
-		body.content[availableContentType],
-		...body.description ? [body.description] : []
-	];
-	return false;
-}
-/**
-* Returns the response schema for a given operation and HTTP status code.
-*
-* Returns an empty object `{}` when no response body schema is available.
-*
-* @example
-* ```ts
-* getResponseSchema(document, operation, 200)         // SchemaObject
-* getResponseSchema(document, operation, '4XX')       // {}
-* ```
-*/
-function getResponseSchema(document, operation, statusCode, options = {}) {
-	if (operation.schema.responses) {
-		const responses = operation.schema.responses;
-		for (const key in responses) {
-			const schema = responses[key];
-			if (schema && isReference(schema)) responses[key] = resolveRef(document, schema.$ref);
-		}
-	}
-	const responseBody = getResponseBody(operation.getResponseByStatusCode(statusCode), options.contentType);
-	if (responseBody === false) return {};
-	const schema = Array.isArray(responseBody) ? responseBody[1].schema : responseBody.schema;
-	if (!schema) return {};
-	return dereferenceWithRef(document, schema);
-}
-/**
-* Returns the request body schema for an operation, or `null` when absent.
-*
-* @example
-* ```ts
-* getRequestSchema(document, operation) // SchemaObject | null
-* ```
-*/
-function getRequestSchema(document, operation, options = {}) {
-	if (operation.schema.requestBody) operation.schema.requestBody = dereferenceWithRef(document, operation.schema.requestBody);
-	const requestBody = operation.getRequestBody(options.contentType);
-	if (requestBody === false) return null;
-	const schema = Array.isArray(requestBody) ? requestBody[1].schema : requestBody.schema;
-	if (!schema) return null;
-	return dereferenceWithRef(document, schema);
-}
-/**
-* Flattens a keyword-only `allOf` into its parent schema.
-*
-* Only flattens when every member is a plain fragment — no `$ref` and no structural keywords
-* (see `structuralKeys`). Outer schema values take precedence over fragment values.
-* Returns `null` for a `null` input, and the original schema unchanged when flattening is unsafe.
-*
-* @example
-* ```ts
-* flattenSchema({ allOf: [{ description: 'A pet' }], type: 'object', properties: {} })
-* // { type: 'object', properties: {}, description: 'A pet' }
-*
-* flattenSchema({ allOf: [{ $ref: '#/components/schemas/Pet' }] })
-* // returned unchanged — contains a $ref
-* ```
-*/
-/**
-* Returns `true` when `fragment` carries any JSON Schema keyword that makes it
-* structurally significant on its own (see `structuralKeys`).
-*
-* A fragment with a structural keyword can't be safely merged into a parent schema.
-*/
-function hasStructuralKeywords(fragment) {
-	for (const key in fragment) if (structuralKeys.has(key)) return true;
-	return false;
-}
-function flattenSchema(schema) {
-	if (!schema?.allOf || schema.allOf.length === 0) return schema ?? null;
-	const allOfFragments = schema.allOf;
-	if (allOfFragments.some((item) => (0, oas_types.isRef)(item))) return schema;
-	if (allOfFragments.some(hasStructuralKeywords)) return schema;
-	const merged = { ...schema };
-	delete merged.allOf;
-	for (const fragment of allOfFragments) for (const [key, value] of Object.entries(fragment)) if (merged[key] === void 0) merged[key] = value;
-	return merged;
-}
-/**
-* Extracts the inline schema from a media-type `content` map.
-*
-* Prefers `preferredContentType` when given; otherwise uses the first key in the map.
-* Returns `null` when `content` is absent, the schema is missing, or the schema is a `$ref`.
-*
-* @example
-* ```ts
-* extractSchemaFromContent(operation.content, 'application/json')
-* // SchemaObject | null
+* extractSchemaFromContent(operation.content, 'application/json')
+* // SchemaObject | null
 * ```
 */
 function extractSchemaFromContent(content, preferredContentType) {
 	if (!content) return null;
 	const firstContentType = Object.keys(content)[0] ?? "application/json";
 	const schema = content[preferredContentType ?? firstContentType]?.schema;
-	if (schema && "$ref" in schema) return null;
+	if (isReference(schema)) return null;
 	return schema ?? null;
 }
 /**
 * Walks a schema tree and collects the names of all `#/components/schemas/<name>` `$ref`s.
 */
-function collectRefs(schema, refs = /* @__PURE__ */ new Set()) {
+function* collectRefs(schema) {
 	if (Array.isArray(schema)) {
-		for (const item of schema) collectRefs(item, refs);
-		return refs;
+		for (const item of schema) yield* collectRefs(item);
+		return;
 	}
 	if (schema && typeof schema === "object") for (const key in schema) {
 		const value = schema[key];
-		if (key === "$ref" && typeof value === "string") {
-			if (value.startsWith("#/components/schemas/")) {
-				const name = value.slice(21);
-				if (name) refs.add(name);
-			}
-		} else collectRefs(value, refs);
+		if (!(key === "$ref" && typeof value === "string")) {
+			yield* collectRefs(value);
+			continue;
+		}
+		if (value.startsWith("#/components/schemas/")) {
+			const name = value.slice(21);
+			if (name) yield name;
+		}
 	}
-	return refs;
 }
 /**
 * Returns a copy of `schemas` topologically sorted by `$ref` dependency.
@@ -1016,7 +695,7 @@ function collectRefs(schema, refs = /* @__PURE__ */ new Set()) {
 */
 function sortSchemas(schemas) {
 	const deps = /* @__PURE__ */ new Map();
-	for (const [name, schema] of Object.entries(schemas)) deps.set(name, Array.from(collectRefs(schema)));
+	for (const [name, schema] of Object.entries(schemas)) deps.set(name, [...new Set(collectRefs(schema))]);
 	const sorted = [];
 	const visited = /* @__PURE__ */ new Set();
 	function visit(name, stack) {
@@ -1037,13 +716,16 @@ const semanticSuffixes = {
 	responses: "Response",
 	requestBodies: "Request"
 };
-function getSemanticSuffix(source) {
-	return semanticSuffixes[source];
-}
-function resolveSchemaRef(document, schema) {
-	if (!isReference(schema)) return schema;
-	const resolved = resolveRef(document, schema.$ref);
-	return resolved && !isReference(resolved) ? resolved : schema;
+/**
+* Picks the collision suffix for one name-colliding schema: none when the name is unique,
+* a semantic suffix (`Schema`, `Response`, `Request`) when the collision spans sources, otherwise
+* a numeric suffix (`2`, `3`, …) for same-source collisions.
+*/
+function collisionSuffix({ isSingle, hasMultipleSources, source, index }) {
+	if (isSingle) return "";
+	if (hasMultipleSources) return semanticSuffixes[source];
+	if (index === 0) return "";
+	return String(index + 1);
 }
 /**
 * Collects component schemas from one or more sources and resolves name collisions.
@@ -1057,19 +739,24 @@ function resolveSchemaRef(document, schema) {
 *
 * @example
 * ```ts
-* const { schemas, nameMapping } = getSchemas(document, { contentType: 'application/json' })
+* const { schemas, renames } = getSchemas(document, { contentType: 'application/json' }, refs)
 * ```
 */
-function getSchemas(document, { contentType }) {
+function getSchemas(document, { contentType }, refs) {
 	const components = document.components;
+	function resolveSchemaRef(schema) {
+		if (!isReference(schema)) return schema;
+		const resolved = refs.resolve(schema.$ref);
+		return resolved && !isReference(resolved) ? resolved : schema;
+	}
 	const candidates = [...Object.entries(components?.schemas ?? {}).map(([name, schema]) => ({
-		schema: resolveSchemaRef(document, schema),
+		schema: resolveSchemaRef(schema),
 		source: "schemas",
 		originalName: name
 	})), ...["responses", "requestBodies"].flatMap((source) => Object.entries(components?.[source] ?? {}).flatMap(([name, item]) => {
 		const schema = extractSchemaFromContent(item.content, contentType);
 		return schema ? [{
-			schema: resolveSchemaRef(document, schema),
+			schema: resolveSchemaRef(schema),
 			source,
 			originalName: name
 		}] : [];
@@ -1082,32 +769,222 @@ function getSchemas(document, { contentType }) {
 		normalizedNames.set(key, bucket);
 	}
 	const schemas = {};
-	const nameMapping = /* @__PURE__ */ new Map();
+	const renames = /* @__PURE__ */ new Map();
 	for (const [, items] of normalizedNames) {
 		const isSingle = items.length === 1;
-		let hasMultipleSources = false;
-		if (!isSingle) {
-			const firstSource = items[0].source;
-			for (let i = 1; i < items.length; i++) if (items[i].source !== firstSource) {
-				hasMultipleSources = true;
-				break;
-			}
-		}
+		const hasMultipleSources = !isSingle && new Set(items.map((item) => item.source)).size > 1;
 		items.forEach((item, index) => {
-			const suffix = isSingle ? "" : hasMultipleSources ? getSemanticSuffix(item.source) : index === 0 ? "" : String(index + 1);
+			const suffix = collisionSuffix({
+				isSingle,
+				hasMultipleSources,
+				source: item.source,
+				index
+			});
 			const uniqueName = item.originalName + suffix;
 			schemas[uniqueName] = item.schema;
-			nameMapping.set(`#/components/${item.source}/${item.originalName}`, uniqueName);
+			if (suffix) renames.set(`#/components/${item.source}/${item.originalName}`, uniqueName);
 		});
 	}
 	return {
 		schemas: sortSchemas(schemas),
-		nameMapping
+		renames
 	};
 }
+//#endregion
+//#region src/model/server.ts
+/**
+* Reads the server URL from the document's `servers` array at `server.index`,
+* interpolating any `server.variables` into the URL template.
+*
+* Returns `null` when `server.index` is omitted or out of range.
+*
+* @example Resolve the first server
+* `resolveBaseUrl({ document, server: { index: 0 } })`
+*
+* @example Override a path variable
+* `resolveBaseUrl({ document, server: { index: 0, variables: { version: 'v2' } } })`
+*/
+function resolveBaseUrl({ document, server }) {
+	const index = server?.index;
+	const entry = index !== void 0 ? document.servers?.at(index) : void 0;
+	return entry?.url ? resolveServerUrl(entry, server?.variables) : null;
+}
+/**
+* Replaces `{variable}` placeholders in an OpenAPI server URL with provided values.
+* Resolution order: `overrides[key]` → `variable.default` → left unreplaced.
+* Throws if an override value is not in the variable's `enum` list.
+*
+* @example
+* ```ts
+* resolveServerUrl(
+*   { url: 'https://{env}.api.example.com', variables: { env: { default: 'dev', enum: ['dev', 'prod'] } } },
+*   { env: 'prod' },
+* )
+* // 'https://prod.api.example.com'
+* ```
+*/
+function resolveServerUrl(server, overrides) {
+	if (!server.variables) return server.url;
+	let url = server.url;
+	for (const [key, variable] of Object.entries(server.variables)) {
+		const value = overrides?.[key] ?? (variable.default != null ? String(variable.default) : void 0);
+		if (value === void 0) continue;
+		if (variable.enum?.length && !variable.enum.some((e) => String(e) === value)) throw new _kubb_core.Diagnostics.Error({
+			code: _kubb_core.Diagnostics.code.invalidServerVariable,
+			severity: "error",
+			message: `Invalid server variable value '${value}' for '${key}' when resolving ${server.url}. Valid values are: ${variable.enum.join(", ")}.`,
+			help: `Use one of the allowed enum values, or drop the enum on the '${key}' server variable.`,
+			location: {
+				kind: "document",
+				pointer: "#/servers"
+			}
+		});
+		url = url.replaceAll(`{${key}}`, value);
+	}
+	return url;
+}
+//#endregion
+//#region src/operation.ts
+/**
+* Slugifies a path for the `operationId` fallback: non-alphanumerics collapse to single dashes,
+* with no leading or trailing dash.
+*/
+function slugify(value) {
+	return value.replace(/[^a-zA-Z0-9]/g, "-").replace(/-{2,}/g, "-").replace(/^-|-$/g, "");
+}
+/**
+* Returns the operation's `operationId`, falling back to `<method>_<slugified-path>` when absent.
+*/
+function getOperationId({ path, method, schema }) {
+	const { operationId } = schema;
+	if (typeof operationId === "string" && operationId.length > 0) return operationId;
+	return `${method}_${slugify(path).toLowerCase()}`;
+}
+/**
+* Returns the declared response status codes, skipping `x-` extensions and non-object entries.
+*/
+function getResponseStatusCodes({ schema }) {
+	const responses = schema.responses;
+	if (!responses || isReference(responses)) return [];
+	return Object.keys(responses).filter((key) => !key.startsWith("x-") && !!responses[key] && typeof responses[key] === "object");
+}
+/**
+* Returns the response object for a status code, resolving a `$ref` through `refs`. `false` when absent.
+*/
+function getResponseByStatusCode({ operation, refs, statusCode }) {
+	const responses = operation.schema.responses;
+	if (!responses || isReference(responses)) return false;
+	return refs.deref(responses[statusCode]) ?? false;
+}
+/**
+* Resolves the operation's request body, dereferencing a `$ref` through `refs`. Returns `null`
+* when the operation has no request body or it cannot be resolved.
+*/
+function getRequestBody({ operation, refs }) {
+	return refs.deref(operation.schema.requestBody);
+}
+/**
+* Resolves the request body (a `$ref` through `refs`) and returns its content map, or
+* `undefined` when the operation has no request body.
+*/
+function getRequestBodyContent({ operation, refs }) {
+	return getRequestBody({
+		operation,
+		refs
+	})?.content;
+}
+/**
+* Returns the request body media type. With `mediaType` set, returns that entry or `false`.
+* Otherwise picks the first JSON-like media type, then the first declared one, as a
+* `[mediaType, object]` tuple.
+*/
+function getRequestContent({ operation, refs, mediaType }) {
+	const content = getRequestBodyContent({
+		operation,
+		refs
+	});
+	if (!content) return false;
+	if (mediaType) return mediaType in content ? content[mediaType] : false;
+	return pickContentEntry(content);
+}
+/**
+* Returns the primary request content type. Prefers a JSON-like media type (the last one wins
+* when several are declared), then the first declared one, defaulting to `'application/json'`.
+*/
+function getRequestContentType({ operation, refs }) {
+	const content = getRequestBodyContent({
+		operation,
+		refs
+	});
+	const mediaTypes = content ? Object.keys(content) : [];
+	let result = mediaTypes[0] ?? "application/json";
+	for (const mt of mediaTypes) if (isJsonMimeType(mt)) result = mt;
+	return result;
+}
+/**
+* Builds an `Operation` for every supported HTTP method on every path, in document order.
+* `x-` path keys and unresolvable path-item `$ref`s are skipped.
+*
+* @example
+* ```ts
+* for (const operation of getOperations(document, refs)) {
+*   parseOperation(options, operation)
+* }
+* ```
+*/
+function getOperations(document, refs) {
+	const operations = [];
+	const paths = document.paths;
+	if (!paths) return operations;
+	for (const path of Object.keys(paths)) {
+		if (path.startsWith("x-")) continue;
+		const pathItem = refs.deref(paths[path]);
+		if (!pathItem) continue;
+		const item = pathItem;
+		for (const method of Object.keys(item)) {
+			if (!SUPPORTED_METHODS.has(method)) continue;
+			const schema = item[method];
+			if (!schema || typeof schema !== "object") continue;
+			operations.push({
+				path,
+				method,
+				schema,
+				pathItem
+			});
+		}
+	}
+	return operations;
+}
+//#endregion
+//#region src/emit/schemaShape.ts
+/**
+* Returns the Kubb `SchemaType` for a given OAS `format` string, or `null` if not found.
+* Formats not in `formatMap` (e.g., `int64`, `uint64`, `date-time`) are handled separately by parser options.
+*/
+function getSchemaType(format) {
+	return formatMap[format] ?? null;
+}
+/**
+* Whether the parser maps `format` to a dedicated type. True for any `formatMap` entry, plus the
+* `specialCasedFormats` that `convertFormat` handles directly (int64, uint64, date-time, date, time). False means the format falls back to
+* the base type, which is what `KUBB_UNSUPPORTED_FORMAT` flags. Reading both sources keeps the
+* diagnostic in step with the parser as `formatMap` grows.
+*/
+function isHandledFormat(format) {
+	return getSchemaType(format) !== null || specialCasedFormats.has(format);
+}
+/**
+* Converts an OAS primitive type string to its `PrimitiveSchemaType` equivalent.
+* Numeric types (`number`, `integer`, `bigint`) pass through unchanged. `boolean` maps to `'boolean'`. Everything else becomes `'string'`.
+*/
+function getPrimitiveType(type) {
+	if (type === "number" || type === "integer" || type === "bigint") return type;
+	if (type === "boolean") return "boolean";
+	return "string";
+}
 /**
 * Resolves the AST type descriptor for a date/time format, honoring the `dateType` option.
-* Returns `null` when `dateType: false`, signalling the format should fall through to `string`.
+* Returns `null` when `dateType: false`, so the format falls through to `string`.
 */
 function getDateType(options, format) {
 	if (!options.dateType) return null;
@@ -1139,135 +1016,198 @@ function getDateType(options, format) {
 	};
 }
 /**
-* Collects the shared metadata fields passed to every `createSchema` call.
+* Reads a schema's numeric `exclusiveMinimum`/`exclusiveMaximum` bounds (the OAS 3.1 numeric
+* form). Either key is `undefined` when absent or, for the legacy OAS 3.0 boolean form, not a
+* number.
 */
-function buildSchemaNode(schema, name, nullable, defaultValue) {
+function getExclusiveBounds(schema) {
 	return {
-		name,
-		nullable,
-		title: schema.title,
-		description: schema.description,
-		deprecated: schema.deprecated,
-		readOnly: schema.readOnly,
-		writeOnly: schema.writeOnly,
-		default: defaultValue,
-		example: schema.example
+		exclusiveMinimum: typeof schema.exclusiveMinimum === "number" ? schema.exclusiveMinimum : void 0,
+		exclusiveMaximum: typeof schema.exclusiveMaximum === "number" ? schema.exclusiveMaximum : void 0
 	};
 }
 /**
-* Returns all request body content type keys for an operation.
-*
-* The requestBody is dereferenced **in-place** when it is a `$ref` — the same mutation
-* that `getRequestSchema` already performs — so that the returned list accurately reflects
-* the available content types even for referenced bodies.
-*
-* @example
-* ```ts
-* getRequestBodyContentTypes(document, operation)
-* // ['application/json', 'multipart/form-data']
-* ```
+* Reads schema examples as an array. OAS 3.1 uses an `examples` array, but specs (including ones
+* labeled 3.1) still use the singular OAS 3.0 `example`, which the upgrader only converts on the
+* 3.0 -> 3.1 hop. Normalize both into one array so the AST node exposes only `examples`.
 */
-function getRequestBodyContentTypes(document, operation) {
-	if (operation.schema.requestBody) operation.schema.requestBody = dereferenceWithRef(document, operation.schema.requestBody);
-	const body = operation.schema.requestBody;
-	if (!body) return [];
-	return body.content ? Object.keys(body.content) : [];
+function extractExamples(schema) {
+	if (Array.isArray(schema.examples)) return schema.examples;
+	return schema.example !== void 0 ? [schema.example] : void 0;
 }
-//#endregion
-//#region src/parser.ts
 /**
-* Normalizes malformed `{ type: 'array', enum: [...] }` schemas by moving enum values into items.
-*
-* This pattern violates the OpenAPI spec but appears in real specs. The fix moves enum values
-* from the array to its items sub-schema, making them valid for downstream processing.
+* Returns `true` when `fragment` carries any JSON Schema keyword that makes it
+* structurally significant on its own (see `structuralKeys`).
 *
-* @note This is a defensive measure for robustness with non-compliant specs.
+* A fragment with a structural keyword can't be safely merged into a parent schema.
 */
-function normalizeArrayEnum(schema) {
-	const normalizedItems = {
-		...typeof schema.items === "object" && !Array.isArray(schema.items) ? schema.items : {},
-		enum: schema.enum
-	};
-	const { enum: _enum, ...schemaWithoutEnum } = schema;
-	return {
-		...schemaWithoutEnum,
-		items: normalizedItems
-	};
+function hasStructuralKeywords(fragment) {
+	return Object.keys(fragment).some((key) => structuralKeys.has(key));
 }
 /**
-* Factory function that creates schema and operation converters for a given OpenAPI context.
+* Flattens a keyword-only `allOf` into its parent schema.
 *
-* Returns closures that share mutable state (`resolvingRefs` set for cycle detection).
-* Each converter branch (`convertRef`, `convertAllOf`, etc.) mutually recursively calls `parseSchema`,
-* made possible by hoisting of function declarations.
+* Only flattens when every member is a plain fragment, with no `$ref` and no structural keywords
+* (see `structuralKeys`). Outer schema values take precedence over fragment values.
+* Returns `null` for a `null` input, and the original schema unchanged when flattening is unsafe.
 *
-* @note Not exported; called internally by `parseOas()` and `parseSchema()`.
-*/
-function createSchemaParser(ctx) {
-	const document = ctx.document;
-	/**
-	* Tracks `$ref` paths that are currently being resolved to prevent infinite
-	* recursion when schemas contain circular references (e.g. `Pet → parent → Pet`).
-	*/
-	const resolvingRefs = /* @__PURE__ */ new Set();
-	/**
-	* Converts a `$ref` schema into a `RefSchemaNode`.
-	*
-	* The resolved schema is stored in `node.schema`. Usage-site sibling fields
-	* (description, readOnly, nullable, etc.) are stored directly on the ref node.
-	* Use `syncSchemaRef(node)` in printers to get a merged view of both.
-	* Circular refs are detected via `resolvingRefs` and leave `schema` as `undefined`.
-	*/
-	function convertRef({ schema, name, nullable, defaultValue, rawOptions }) {
-		let resolvedSchema;
-		const refPath = schema.$ref;
-		if (refPath && !resolvingRefs.has(refPath)) try {
-			const referenced = resolveRef(document, refPath);
-			if (referenced) {
-				resolvingRefs.add(refPath);
-				resolvedSchema = parseSchema({ schema: referenced }, rawOptions);
-				resolvingRefs.delete(refPath);
-			}
-		} catch {}
-		return _kubb_core.ast.createSchema({
-			...buildSchemaNode(schema, name, nullable, defaultValue),
-			type: "ref",
-			name: _kubb_core.ast.extractRefName(schema.$ref),
-			ref: schema.$ref,
-			schema: resolvedSchema
+* @example
+* ```ts
+* flattenSchema({ allOf: [{ description: 'A pet' }], type: 'object', properties: {} })
+* // { type: 'object', properties: {}, description: 'A pet' }
+* ```
+*
+* @example
+* ```ts
+* flattenSchema({ allOf: [{ $ref: '#/components/schemas/Pet' }] })
+* // returned unchanged, contains a $ref
+* ```
+*/
+function flattenSchema(schema) {
+	if (!schema?.allOf || schema.allOf.length === 0) return schema ?? null;
+	const allOfFragments = schema.allOf;
+	if (allOfFragments.some((item) => isReference(item))) return schema;
+	if (allOfFragments.some(hasStructuralKeywords)) return schema;
+	const { allOf: _allOf, ...rest } = schema;
+	const merged = rest;
+	for (const fragment of allOfFragments) for (const [key, value] of Object.entries(fragment)) merged[key] ??= value;
+	return merged;
+}
+//#endregion
+//#region src/emit/createNode.ts
+/**
+* Builds a schema node from a converter's base context plus its type-specific fields. Every
+* converter needs the same metadata fields (`title`, `description`, `examples`, ...) alongside
+* whatever makes its node distinct; this folds both into one call.
+*/
+function createNode({ schema, name, nullable, defaultValue }, extras) {
+	return _kubb_ast.ast.factory.createSchema({
+		name,
+		nullable,
+		title: schema.title,
+		description: schema.description,
+		deprecated: schema.deprecated,
+		readOnly: schema.readOnly,
+		writeOnly: schema.writeOnly,
+		default: defaultValue,
+		examples: extractExamples(schema),
+		format: schema.format,
+		...extras
+	});
+}
+//#endregion
+//#region src/emit/discriminator/preserve.ts
+/**
+* Creates a single-property object schema used as a discriminator literal.
+*
+* @example
+* ```ts
+* createDiscriminantNode({ propertyName: 'type', value: 'dog' })
+* // -> { type: 'object', properties: [{ name: 'type', required: true, schema: enum('dog') }] }
+* ```
+*/
+function createDiscriminantNode({ propertyName, value }) {
+	return _kubb_ast.ast.factory.createSchema({
+		type: "object",
+		primitive: "object",
+		properties: [_kubb_ast.ast.factory.createProperty({
+			name: propertyName,
+			schema: _kubb_ast.ast.factory.createSchema({
+				type: "enum",
+				primitive: "string",
+				enumValues: [value]
+			}),
+			required: true
+		})]
+	});
+}
+/**
+* Returns the discriminator key whose mapping value matches `ref`, or `null` when there is no match.
+*
+* @example
+* ```ts
+* findDiscriminator({ dog: '#/components/schemas/Dog' }, '#/components/schemas/Dog') // 'dog'
+* ```
+*/
+function findDiscriminator(mapping, ref) {
+	if (!mapping || !ref) return null;
+	return Object.entries(mapping).find(([, value]) => value === ref)?.[0] ?? null;
+}
+/**
+* Narrows each `oneOf`/`anyOf` member with its discriminant value, intersecting the member's own
+* node with either the shared-properties slice carrying that value, or a synthetic discriminant
+* literal. The referenced child schema's own definition is left untouched — narrowing happens only
+* at this union usage site, which is what makes this mode "preserve" (as opposed to `propagate`,
+* which additionally patches the child schema's own definition in a post-pass).
+*/
+function narrowUnionMembers({ unionMembers, discriminator, sharedPropertiesNode, parse, rawOptions, name, refs }) {
+	function pickDiscriminatorPropertyNode(node, propertyName) {
+		const discriminatorProperty = _kubb_ast.ast.narrowSchema(node, "object")?.properties?.find((property) => property.name === propertyName);
+		if (!discriminatorProperty) return null;
+		return _kubb_ast.ast.factory.createSchema({
+			type: "object",
+			primitive: "object",
+			properties: [discriminatorProperty]
 		});
 	}
-	/**
-	* Converts an `allOf` schema into a flattened node or an `IntersectionSchemaNode`.
-	*/
-	function convertAllOf({ schema, name, nullable, defaultValue, rawOptions }) {
-		if (schema.allOf.length === 1 && !schema.properties && !(Array.isArray(schema.required) && schema.required.length) && schema.additionalProperties === void 0) {
-			const [memberSchema] = schema.allOf;
-			const memberNode = parseSchema({
-				schema: memberSchema,
-				name: null
-			}, rawOptions);
-			const { kind: _kind, ...memberNodeProps } = memberNode;
-			const mergedNullable = nullable || memberNode.nullable || void 0;
-			const mergedDefault = schema.default === null && mergedNullable ? void 0 : schema.default ?? memberNode.default;
-			return _kubb_core.ast.createSchema({
-				...memberNodeProps,
-				name,
-				title: schema.title ?? memberNode.title,
-				description: schema.description ?? memberNode.description,
-				deprecated: schema.deprecated ?? memberNode.deprecated,
-				nullable: mergedNullable,
-				readOnly: schema.readOnly ?? memberNode.readOnly,
-				writeOnly: schema.writeOnly ?? memberNode.writeOnly,
-				default: mergedDefault,
-				example: schema.example ?? memberNode.example,
-				pattern: schema.pattern ?? ("pattern" in memberNode ? memberNode.pattern : void 0)
+	function implicitDiscriminantValue(member) {
+		if (!discriminator || discriminator.mapping || !isReference(member)) return null;
+		const value = (0, _kubb_kit.extractRefName)(member.$ref);
+		if (!value) return null;
+		const variant = refs.resolve(member.$ref, { report: false });
+		if (!variant) return null;
+		const propertyName = discriminator.propertyName;
+		const seen = /* @__PURE__ */ new Set([member.$ref]);
+		function constrains(v) {
+			const prop = v.properties?.[propertyName];
+			const resolved = prop && isReference(prop) ? refs.resolve(prop.$ref, { report: false }) : prop;
+			if (resolved && (Array.isArray(resolved.enum) || resolved.const !== void 0)) return true;
+			const composition = v.allOf ?? v.oneOf ?? v.anyOf;
+			if (!composition) return false;
+			return composition.some((m) => {
+				if (!isReference(m)) return constrains(m);
+				if (seen.has(m.$ref)) return false;
+				seen.add(m.$ref);
+				const r = refs.resolve(m.$ref, { report: false });
+				return r ? constrains(r) : false;
 			});
 		}
-		const filteredDiscriminantValues = [];
-		const allOfMembers = schema.allOf.filter((item) => {
+		return constrains(variant) ? null : value;
+	}
+	return unionMembers.map((s) => {
+		const ref = isReference(s) ? s.$ref : void 0;
+		const discriminatorValue = findDiscriminator(discriminator?.mapping, ref) ?? implicitDiscriminantValue(s);
+		const memberNode = parse({
+			schema: s,
+			name
+		}, rawOptions);
+		if (!discriminatorValue || !discriminator) return memberNode;
+		const narrowedDiscriminatorNode = sharedPropertiesNode ? pickDiscriminatorPropertyNode(_kubb_ast.ast.applyMacros(sharedPropertiesNode, [(0, _kubb_kit.macroDiscriminatorEnum)({
+			propertyName: discriminator.propertyName,
+			values: [discriminatorValue]
+		})], { depth: "shallow" }), discriminator.propertyName) : void 0;
+		return _kubb_ast.ast.factory.createSchema({
+			type: "intersection",
+			members: [memberNode, narrowedDiscriminatorNode ?? createDiscriminantNode({
+				propertyName: discriminator.propertyName,
+				value: discriminatorValue
+			})]
+		});
+	});
+}
+/**
+* Filters the discriminated members out of an `allOf` list: an `allOf` member that `$ref`s a
+* discriminated union's parent, where this schema is itself one of that union's children, is
+* dropped from `members` and its discriminant value collected instead — the same synthetic
+* literal `narrowUnionMembers` produces, so the emitted node stays a plain intersection rather
+* than nesting the whole parent union one level deeper.
+*/
+function extractDiscriminatedAllOfMembers({ allOfMembers, name, refs }) {
+	const discriminantValues = [];
+	return {
+		members: allOfMembers.filter((item) => {
 			if (!isReference(item) || !name) return true;
-			const deref = resolveRef(document, item.$ref);
+			const deref = refs.resolve(item.$ref);
 			if (!deref || !isDiscriminator(deref)) return true;
 			const parentUnion = deref.oneOf ?? deref.anyOf;
 			if (!parentUnion) return true;
@@ -1275,410 +1215,948 @@ function createSchemaParser(ctx) {
 			const inOneOf = parentUnion.some((oneOfItem) => isReference(oneOfItem) && oneOfItem.$ref === childRef);
 			const inMapping = Object.values(deref.discriminator.mapping ?? {}).some((v) => v === childRef);
 			if (inOneOf || inMapping) {
-				const discriminatorValue = _kubb_core.ast.findDiscriminator(deref.discriminator.mapping, childRef);
-				if (discriminatorValue) filteredDiscriminantValues.push({
+				const discriminatorValue = findDiscriminator(deref.discriminator.mapping, childRef);
+				if (discriminatorValue) discriminantValues.push({
 					propertyName: deref.discriminator.propertyName,
 					value: discriminatorValue
 				});
 				return false;
 			}
 			return true;
-		}).map((s) => parseSchema({ schema: s }, rawOptions));
-		const syntheticStart = allOfMembers.length;
-		if (Array.isArray(schema.required) && schema.required.length) {
-			const outerKeys = schema.properties ? new Set(Object.keys(schema.properties)) : /* @__PURE__ */ new Set();
-			const missingRequired = schema.required.filter((key) => !outerKeys.has(key));
-			if (missingRequired.length) {
-				const resolvedMembers = schema.allOf.flatMap((item) => {
-					if (!isReference(item)) return [item];
-					const deref = resolveRef(document, item.$ref);
-					return deref && !isReference(deref) ? [deref] : [];
-				});
-				for (const key of missingRequired) for (const resolved of resolvedMembers) if (resolved.properties?.[key]) {
-					allOfMembers.push(parseSchema({ schema: {
-						properties: { [key]: resolved.properties[key] },
+		}),
+		discriminantValues
+	};
+}
+//#endregion
+//#region src/emit/converters/composition.ts
+/**
+* Converts a `$ref` schema into a `RefSchemaNode`.
+*
+* The resolved schema is stored in `node.schema`. Usage-site sibling fields
+* (description, readOnly, nullable, etc.) are stored directly on the ref node.
+* Use `syncSchemaRef(node)` in printers to get a merged view of both.
+* Circular refs are detected in `refs.resolveNode` and leave `schema` as `null`.
+*/
+function convertRef({ schema, name, nullable, defaultValue, rawOptions, document, parse, refs, renames }) {
+	const refPath = schema.$ref;
+	const resolvedSchema = refPath ? refs.resolveNode(refPath, parse, rawOptions) : null;
+	const ctx = {
+		schema,
+		name,
+		nullable,
+		defaultValue
+	};
+	if (refPath && document.components && !refs.exists(refPath)) return createNode(ctx, { type: "unknown" });
+	const targetName = renames?.get(schema.$ref);
+	return createNode(ctx, {
+		type: "ref",
+		name: (0, _kubb_kit.extractRefName)(schema.$ref),
+		ref: schema.$ref,
+		...targetName ? { targetName } : {},
+		schema: resolvedSchema
+	});
+}
+/**
+* Converts an `allOf` schema into a flattened node or an `IntersectionSchemaNode`.
+*/
+function convertAllOf({ schema, name, nullable, defaultValue, rawOptions, parse, refs }) {
+	if (schema.allOf.length === 1 && !schema.properties && !(Array.isArray(schema.required) && schema.required.length) && schema.additionalProperties === void 0) {
+		const [memberSchema] = schema.allOf;
+		const memberNode = parse({
+			schema: memberSchema,
+			name
+		}, rawOptions);
+		const { kind: _kind, ...memberNodeProps } = memberNode;
+		const mergedNullable = nullable || memberNode.nullable || void 0;
+		const mergedDefault = schema.default === null && mergedNullable ? void 0 : schema.default ?? memberNode.default;
+		return _kubb_ast.ast.factory.createSchema({
+			...memberNodeProps,
+			name,
+			title: schema.title ?? memberNode.title,
+			description: schema.description ?? memberNode.description,
+			deprecated: schema.deprecated ?? memberNode.deprecated,
+			nullable: mergedNullable,
+			readOnly: schema.readOnly ?? memberNode.readOnly,
+			writeOnly: schema.writeOnly ?? memberNode.writeOnly,
+			default: mergedDefault,
+			examples: extractExamples(schema) ?? memberNode.examples,
+			pattern: schema.pattern ?? ("pattern" in memberNode ? memberNode.pattern : void 0),
+			format: schema.format ?? memberNode.format
+		});
+	}
+	const { members: discriminatedAllOf, discriminantValues } = extractDiscriminatedAllOfMembers({
+		allOfMembers: schema.allOf,
+		name,
+		refs
+	});
+	const allOfMembers = discriminatedAllOf.map((s) => parse({
+		schema: s,
+		name
+	}, rawOptions));
+	const syntheticStart = allOfMembers.length;
+	if (Array.isArray(schema.required) && schema.required.length) {
+		const outerKeys = schema.properties ? new Set(Object.keys(schema.properties)) : /* @__PURE__ */ new Set();
+		const missingRequired = schema.required.filter((key) => !outerKeys.has(key));
+		if (missingRequired.length) {
+			const resolvedMembers = schema.allOf.flatMap((item) => {
+				if (!isReference(item)) return [item];
+				const deref = refs.resolve(item.$ref);
+				return deref && !isReference(deref) ? [deref] : [];
+			});
+			for (const key of missingRequired) for (const resolved of resolvedMembers) {
+				const prop = resolved.properties?.[key];
+				if (prop) {
+					const memberSchema = {
+						properties: { [key]: prop },
 						required: [key]
-					} }, rawOptions));
+					};
+					allOfMembers.push(parse({
+						schema: memberSchema,
+						name
+					}, rawOptions));
 					break;
 				}
 			}
 		}
-		if (schema.properties) {
-			const { allOf: _allOf, ...schemaWithoutAllOf } = schema;
-			allOfMembers.push(parseSchema({ schema: schemaWithoutAllOf }, rawOptions));
-		}
-		for (const { propertyName, value } of filteredDiscriminantValues) allOfMembers.push(_kubb_core.ast.createDiscriminantNode({
-			propertyName,
-			value
-		}));
-		return _kubb_core.ast.createSchema({
-			type: "intersection",
-			members: [..._kubb_core.ast.mergeAdjacentObjects(allOfMembers.slice(0, syntheticStart)), ..._kubb_core.ast.mergeAdjacentObjects(allOfMembers.slice(syntheticStart))],
-			...buildSchemaNode(schema, name, nullable, defaultValue)
-		});
 	}
-	/**
-	* Converts a `oneOf` / `anyOf` schema into a `UnionSchemaNode`.
-	*/
-	function convertUnion({ schema, name, nullable, defaultValue, rawOptions }) {
-		function pickDiscriminatorPropertyNode(node, propertyName) {
-			const discriminatorProperty = _kubb_core.ast.narrowSchema(node, "object")?.properties?.find((property) => property.name === propertyName);
-			if (!discriminatorProperty) return null;
-			return _kubb_core.ast.createSchema({
-				type: "object",
-				primitive: "object",
-				properties: [discriminatorProperty]
-			});
-		}
-		const unionMembers = [...schema.oneOf ?? [], ...schema.anyOf ?? []];
-		const strategy = schema.oneOf ? "one" : "any";
-		const unionBase = {
-			...buildSchemaNode(schema, name, nullable, defaultValue),
-			discriminatorPropertyName: isDiscriminator(schema) ? schema.discriminator.propertyName : void 0,
-			strategy
-		};
-		const discriminator = isDiscriminator(schema) ? schema.discriminator : void 0;
-		const sharedPropertiesNode = schema.properties ? (() => {
-			const { oneOf: _oneOf, anyOf: _anyOf, ...schemaWithoutUnion } = schema;
-			return parseSchema({
-				schema: discriminator ? Object.fromEntries(Object.entries(schemaWithoutUnion).filter(([key]) => key !== "discriminator")) : schemaWithoutUnion,
-				name
-			}, rawOptions);
-		})() : void 0;
-		if (sharedPropertiesNode || discriminator?.mapping) {
-			const members = unionMembers.map((s) => {
-				const ref = isReference(s) ? s.$ref : void 0;
-				const discriminatorValue = _kubb_core.ast.findDiscriminator(discriminator?.mapping, ref);
-				const memberNode = parseSchema({ schema: s }, rawOptions);
-				if (!discriminatorValue || !discriminator) return memberNode;
-				const narrowedDiscriminatorNode = sharedPropertiesNode ? pickDiscriminatorPropertyNode(_kubb_core.ast.setDiscriminatorEnum({
-					node: sharedPropertiesNode,
-					propertyName: discriminator.propertyName,
-					values: [discriminatorValue]
-				}), discriminator.propertyName) : void 0;
-				return _kubb_core.ast.createSchema({
-					type: "intersection",
-					members: [memberNode, narrowedDiscriminatorNode ?? _kubb_core.ast.createDiscriminantNode({
-						propertyName: discriminator.propertyName,
-						value: discriminatorValue
-					})]
-				});
-			});
-			const unionNode = _kubb_core.ast.createSchema({
-				type: "union",
-				...unionBase,
-				members
-			});
-			if (!sharedPropertiesNode) return unionNode;
-			return _kubb_core.ast.createSchema({
-				type: "intersection",
-				...buildSchemaNode(schema, name, nullable, defaultValue),
-				members: [unionNode, sharedPropertiesNode]
-			});
-		}
-		return _kubb_core.ast.createSchema({
-			type: "union",
-			...unionBase,
-			members: _kubb_core.ast.simplifyUnion(unionMembers.map((s) => parseSchema({ schema: s }, rawOptions)))
-		});
+	if (schema.properties) {
+		const { allOf: _allOf, ...schemaWithoutAllOf } = schema;
+		allOfMembers.push(parse({ schema: schemaWithoutAllOf }, rawOptions));
 	}
-	/**
-	* Converts an OAS 3.1 `const` schema into a null scalar or a single-value `EnumSchemaNode`.
-	*/
-	function convertConst({ schema, name, nullable, defaultValue }) {
-		const constValue = schema.const;
-		if (constValue === null) return _kubb_core.ast.createSchema({
-			type: "null",
-			primitive: "null",
+	for (const { propertyName, value } of discriminantValues) allOfMembers.push(createDiscriminantNode({
+		propertyName,
+		value
+	}));
+	return createNode({
+		schema,
+		name,
+		nullable,
+		defaultValue
+	}, {
+		type: "intersection",
+		members: [...(0, _kubb_kit.mergeAdjacentObjectsLazy)(allOfMembers.slice(0, syntheticStart)), ...(0, _kubb_kit.mergeAdjacentObjectsLazy)(allOfMembers.slice(syntheticStart))]
+	});
+}
+/**
+* Converts a `oneOf` / `anyOf` schema into a `UnionSchemaNode`.
+*/
+function convertUnion({ schema, name, nullable, defaultValue, rawOptions, parse, refs }) {
+	const ctx = {
+		schema,
+		name,
+		nullable,
+		defaultValue
+	};
+	const unionMembers = [...schema.oneOf ?? [], ...schema.anyOf ?? []];
+	const strategy = schema.oneOf ? "one" : "any";
+	const unionExtras = {
+		discriminatorPropertyName: isDiscriminator(schema) ? schema.discriminator.propertyName : void 0,
+		strategy
+	};
+	const discriminator = isDiscriminator(schema) ? schema.discriminator : void 0;
+	const { oneOf: _o, anyOf: _a, discriminator: _d, ...memberBaseSchema } = schema;
+	const sharedPropertiesNode = schema.properties ? parse({
+		schema: memberBaseSchema,
+		name
+	}, rawOptions) : void 0;
+	if (sharedPropertiesNode || discriminator) {
+		const members = narrowUnionMembers({
+			unionMembers,
+			discriminator,
+			sharedPropertiesNode,
+			parse,
+			rawOptions,
 			name,
-			title: schema.title,
-			description: schema.description,
-			deprecated: schema.deprecated
-		});
-		const constPrimitive = getPrimitiveType(typeof constValue === "number" ? "number" : typeof constValue === "boolean" ? "boolean" : "string");
-		return _kubb_core.ast.createSchema({
-			type: "enum",
-			primitive: constPrimitive,
-			enumValues: [constValue],
-			...buildSchemaNode(schema, name, nullable, defaultValue)
-		});
-	}
-	/**
-	* Converts a format-annotated schema into a special-type `SchemaNode`.
-	* Returns `null` when the format should fall through to string handling (`dateType: false`).
-	*/
-	function convertFormat({ schema, name, nullable, defaultValue, options }) {
-		const base = buildSchemaNode(schema, name, nullable, defaultValue);
-		if (schema.format === "int64") return _kubb_core.ast.createSchema({
-			type: options.integerType === "bigint" ? "bigint" : "integer",
-			primitive: "integer",
-			...base,
-			min: schema.minimum,
-			max: schema.maximum,
-			exclusiveMinimum: typeof schema.exclusiveMinimum === "number" ? schema.exclusiveMinimum : void 0,
-			exclusiveMaximum: typeof schema.exclusiveMaximum === "number" ? schema.exclusiveMaximum : void 0
+			refs
 		});
-		if (schema.format === "date-time" || schema.format === "date" || schema.format === "time") {
-			const dateType = getDateType(options, schema.format);
-			if (!dateType) return null;
-			if (dateType.type === "datetime") return _kubb_core.ast.createSchema({
-				...base,
-				primitive: "string",
-				type: "datetime",
-				offset: dateType.offset,
-				local: dateType.local
-			});
-			return _kubb_core.ast.createSchema({
-				...base,
-				primitive: "string",
-				type: dateType.type,
-				representation: dateType.representation
-			});
-		}
-		const specialType = getSchemaType(schema.format);
-		if (!specialType) return null;
-		const specialPrimitive = specialType === "number" || specialType === "integer" || specialType === "bigint" ? specialType : "string";
-		if (specialType === "number" || specialType === "integer" || specialType === "bigint") return _kubb_core.ast.createSchema({
-			...base,
-			primitive: specialPrimitive,
-			type: specialType
+		const unionNode = createNode(ctx, {
+			type: "union",
+			...unionExtras,
+			members
 		});
-		if (specialType === "url") return _kubb_core.ast.createSchema({
-			...base,
-			primitive: "string",
-			type: "url",
-			min: schema.minLength,
-			max: schema.maxLength
+		if (!sharedPropertiesNode) return unionNode;
+		return createNode(ctx, {
+			type: "intersection",
+			members: [unionNode, sharedPropertiesNode]
 		});
-		if (specialType === "ipv4") return _kubb_core.ast.createSchema({
-			...base,
+	}
+	const unionNode = createNode(ctx, {
+		type: "union",
+		...unionExtras,
+		members: unionMembers.map((s) => parse({
+			schema: s,
+			name
+		}, rawOptions))
+	});
+	return _kubb_ast.ast.applyMacros(unionNode, [_kubb_kit.macroSimplifyUnion], { depth: "shallow" });
+}
+/**
+* Converts an OAS 3.1 multi-type array (e.g. `type: ['string', 'number']`) into a `UnionSchemaNode`.
+* Only called once the multi-type rule's `match` has confirmed more than one non-`null` type
+* remains; a single remaining type (e.g. `['string', 'null']`) is handled as that type instead,
+* with nullability already folded in.
+*/
+function convertMultiType({ schema, name, nullable, defaultValue, rawOptions, parse }) {
+	const types = schema.type;
+	const nonNullTypes = types.filter((t) => t !== "null");
+	return createNode({
+		schema,
+		name,
+		nullable: types.includes("null") || nullable || void 0,
+		defaultValue
+	}, {
+		type: "union",
+		members: nonNullTypes.map((t) => {
+			return parse({
+				schema: {
+					...schema,
+					type: t
+				},
+				name
+			}, rawOptions);
+		})
+	});
+}
+//#endregion
+//#region src/emit/converters/scalar.ts
+/**
+* Normalizes malformed `{ type: 'array', enum: [...] }` schemas by moving enum values into items.
+*
+* This pattern violates the OpenAPI spec but appears in real specs. The fix moves enum values
+* from the array to its items sub-schema, so they are valid for downstream processing.
+*
+* @note A defensive measure for non-compliant specs.
+*/
+function normalizeArrayEnum(schema) {
+	const normalizedItems = {
+		...typeof schema.items === "object" && !Array.isArray(schema.items) ? schema.items : {},
+		enum: schema.enum
+	};
+	const { enum: _enum, ...schemaWithoutEnum } = schema;
+	return {
+		...schemaWithoutEnum,
+		items: normalizedItems
+	};
+}
+/**
+* Builds a `null` scalar node carrying the schema's documentation. Shared by the `const: null`
+* and the drf-spectacular `NullEnum` (`{ enum: [null] }`) branches, which render identically.
+*/
+function createNullNode(schema, name, nullable) {
+	return _kubb_ast.ast.factory.createSchema({
+		type: "null",
+		primitive: "null",
+		name,
+		title: schema.title,
+		description: schema.description,
+		deprecated: schema.deprecated,
+		nullable,
+		format: schema.format
+	});
+}
+/**
+* Converts an OAS 3.1 `const` schema into a null scalar or a single-value `EnumSchemaNode`.
+*/
+function convertConst({ schema, name, nullable, defaultValue }) {
+	const constValue = schema.const;
+	if (constValue === null) return createNullNode(schema, name);
+	const constPrimitive = getPrimitiveType(typeof constValue === "number" ? "number" : typeof constValue === "boolean" ? "boolean" : "string");
+	return createNode({
+		schema,
+		name,
+		nullable,
+		defaultValue
+	}, {
+		type: "enum",
+		primitive: constPrimitive,
+		enumValues: [constValue]
+	});
+}
+/**
+* Converts a format-annotated schema into a special-type `SchemaNode`. Only called once the
+* `format` rule's `match` has confirmed the format is handled (see `isHandledFormat`) and, for
+* a date-ish format, that `dateType` is not `false`.
+*/
+function convertFormat(context) {
+	const { schema, name, nullable, defaultValue, options, type } = context;
+	const ctx = {
+		schema,
+		name,
+		nullable,
+		defaultValue
+	};
+	if (type === "string" && numericFormats.has(schema.format)) return convertString(context);
+	if (schema.format === "int64" || schema.format === "uint64") return createNode(ctx, {
+		type: options.integerType === "bigint" ? "bigint" : "integer",
+		primitive: "integer",
+		min: schema.minimum,
+		max: schema.maximum,
+		...getExclusiveBounds(schema)
+	});
+	if (schema.format === "date-time" || schema.format === "date" || schema.format === "time") {
+		const dateType = getDateType(options, schema.format);
+		if (dateType.type === "datetime") return createNode(ctx, {
 			primitive: "string",
-			type: "ipv4"
+			type: "datetime",
+			offset: dateType.offset,
+			local: dateType.local
 		});
-		if (specialType === "ipv6") return _kubb_core.ast.createSchema({
-			...base,
+		return createNode(ctx, {
 			primitive: "string",
-			type: "ipv6"
+			type: dateType.type,
+			representation: dateType.representation
 		});
-		if (specialType === "uuid" || specialType === "email") return _kubb_core.ast.createSchema({
-			...base,
-			primitive: "string",
-			type: specialType,
+	}
+	const specialType = getSchemaType(schema.format);
+	return createNode(ctx, {
+		primitive: specialType === "number" || specialType === "integer" || specialType === "bigint" ? specialType : "string",
+		type: specialType,
+		...specialType === "url" || specialType === "uuid" || specialType === "email" ? {
 			min: schema.minLength,
 			max: schema.maxLength
-		});
-		return _kubb_core.ast.createSchema({
-			...base,
-			primitive: specialPrimitive,
-			type: specialType
+		} : {}
+	});
+}
+/**
+* Converts an `enum` schema into an `EnumSchemaNode`.
+*/
+function convertEnum({ schema, name, nullable, type, rawOptions, parse }) {
+	if (type === "array") return parse({
+		schema: normalizeArrayEnum(schema),
+		name
+	}, rawOptions);
+	const nullInEnum = schema.enum.includes(null);
+	const filteredValues = nullInEnum ? schema.enum.filter((v) => v !== null) : schema.enum;
+	if (nullInEnum && filteredValues.length === 0) return createNullNode(schema, name);
+	const enumNullable = nullable || nullInEnum || void 0;
+	const enumDefault = schema.default === null && enumNullable ? void 0 : schema.default;
+	const enumPrimitive = getPrimitiveType(type);
+	const ctx = {
+		schema,
+		name,
+		nullable: enumNullable,
+		defaultValue: enumDefault
+	};
+	const enumExtras = {
+		type: "enum",
+		primitive: enumPrimitive
+	};
+	const extensionKey = enumExtensionKeys.find((key) => key in schema);
+	const descriptionKey = enumDescriptionKeys.find((key) => key in schema);
+	if (extensionKey || descriptionKey || enumPrimitive === "number" || enumPrimitive === "integer" || enumPrimitive === "boolean") {
+		let enumPrimitiveType = "string";
+		if (enumPrimitive === "number" || enumPrimitive === "integer") enumPrimitiveType = "number";
+		else if (enumPrimitive === "boolean") enumPrimitiveType = "boolean";
+		const rawEnumNames = extensionKey ? schema[extensionKey] : void 0;
+		const rawEnumDescriptions = descriptionKey ? schema[descriptionKey] : void 0;
+		const uniqueValues = [...new Set(filteredValues)];
+		const seenNames = /* @__PURE__ */ new Set();
+		return createNode(ctx, {
+			...enumExtras,
+			primitive: enumPrimitiveType,
+			namedEnumValues: uniqueValues.map((value, index) => ({
+				name: String(rawEnumNames?.[index] ?? value),
+				value,
+				primitive: enumPrimitiveType,
+				description: rawEnumDescriptions?.[index]
+			})).filter((entry) => {
+				if (seenNames.has(entry.name)) return false;
+				seenNames.add(entry.name);
+				return true;
+			})
 		});
 	}
-	/**
-	* Converts an `enum` schema into an `EnumSchemaNode`.
-	*/
-	function convertEnum({ schema, name, nullable, type, rawOptions }) {
-		if (type === "array") return parseSchema({
-			schema: normalizeArrayEnum(schema),
-			name
-		}, rawOptions);
-		const nullInEnum = schema.enum.includes(null);
-		const filteredValues = nullInEnum ? schema.enum.filter((v) => v !== null) : schema.enum;
-		const enumNullable = nullable || nullInEnum || void 0;
-		const enumDefault = schema.default === null && enumNullable ? void 0 : schema.default;
-		const enumPrimitive = getPrimitiveType(type);
-		const enumBase = {
-			type: "enum",
-			primitive: enumPrimitive,
-			name,
-			title: schema.title,
-			description: schema.description,
-			deprecated: schema.deprecated,
-			nullable: enumNullable,
-			readOnly: schema.readOnly,
-			writeOnly: schema.writeOnly,
-			default: enumDefault,
-			example: schema.example
+	return createNode(ctx, {
+		...enumExtras,
+		enumValues: [...new Set(filteredValues)]
+	});
+}
+/**
+* Converts a `type: 'string'` schema into a `StringSchemaNode`.
+*/
+function convertString({ schema, name, nullable, defaultValue }) {
+	return createNode({
+		schema,
+		name,
+		nullable,
+		defaultValue
+	}, {
+		type: "string",
+		primitive: "string",
+		min: schema.minLength,
+		max: schema.maxLength,
+		pattern: schema.pattern
+	});
+}
+/**
+* Converts a `type: 'number'` or `type: 'integer'` schema.
+*/
+function convertNumeric({ schema, name, nullable, defaultValue }, type) {
+	return createNode({
+		schema,
+		name,
+		nullable,
+		defaultValue
+	}, {
+		type,
+		primitive: type,
+		min: schema.minimum,
+		max: schema.maximum,
+		...getExclusiveBounds(schema),
+		multipleOf: schema.multipleOf
+	});
+}
+/**
+* Converts a `type: 'boolean'` schema.
+*/
+function convertBoolean({ schema, name, nullable, defaultValue }) {
+	return createNode({
+		schema,
+		name,
+		nullable,
+		defaultValue
+	}, {
+		type: "boolean",
+		primitive: "boolean"
+	});
+}
+/**
+* Converts a binary string schema (`type: 'string'`, `contentMediaType: 'application/octet-stream'`)
+* into a `blob` node.
+*/
+function convertBinary({ schema, name, nullable, defaultValue }) {
+	return createNode({
+		schema,
+		name,
+		nullable,
+		defaultValue
+	}, {
+		type: "blob",
+		primitive: "string"
+	});
+}
+//#endregion
+//#region src/emit/converters/structural.ts
+/**
+* Resolves a `true` or empty-object map schema (`additionalProperties`/`patternProperties`) to
+* `options.unknownType`, otherwise parses it as a regular schema.
+*/
+function resolveMapSchema(mapSchema, options, parse, rawOptions) {
+	if (mapSchema === true || typeof mapSchema === "object" && Object.keys(mapSchema).length === 0) return _kubb_ast.ast.factory.createSchema({ type: options.unknownType });
+	return parse({ schema: mapSchema }, rawOptions);
+}
+/**
+* Names the inline enums on a property's schema, and on each item when the property is a tuple, from
+* the parent and property name. Wraps `macroEnumName` at the property construction site.
+*/
+function nameEnums(node, options) {
+	const macro = (0, _kubb_kit.macroEnumName)(options);
+	const named = _kubb_ast.ast.applyMacros(node, [macro], { depth: "shallow" });
+	const tupleNode = _kubb_ast.ast.narrowSchema(named, "tuple");
+	if (tupleNode?.items) {
+		const namedItems = tupleNode.items.map((item) => _kubb_ast.ast.applyMacros(item, [macro], { depth: "shallow" }));
+		if (namedItems.some((item, i) => item !== tupleNode.items[i])) return {
+			...tupleNode,
+			items: namedItems
 		};
-		const extensionKey = enumExtensionKeys.find((key) => key in schema);
-		if (extensionKey || enumPrimitive === "number" || enumPrimitive === "integer" || enumPrimitive === "boolean") {
-			const enumPrimitiveType = enumPrimitive === "number" || enumPrimitive === "integer" ? "number" : enumPrimitive === "boolean" ? "boolean" : "string";
-			const rawEnumNames = extensionKey ? schema[extensionKey] : void 0;
-			const uniqueValues = [...new Set(filteredValues)];
-			const seenNames = /* @__PURE__ */ new Set();
-			return _kubb_core.ast.createSchema({
-				...enumBase,
-				primitive: enumPrimitiveType,
-				namedEnumValues: uniqueValues.map((value, index) => ({
-					name: String(rawEnumNames?.[index] ?? value),
-					value,
-					primitive: enumPrimitiveType
-				})).filter((entry) => {
-					if (seenNames.has(entry.name)) return false;
-					seenNames.add(entry.name);
-					return true;
-				})
-			});
-		}
-		return _kubb_core.ast.createSchema({
-			...enumBase,
-			enumValues: [...new Set(filteredValues)]
-		});
 	}
-	/**
-	* Converts an object-like schema into an `ObjectSchemaNode`.
-	*/
-	function convertObject({ schema, name, nullable, defaultValue, rawOptions, options }) {
-		const properties = schema.properties ? Object.entries(schema.properties).map(([propName, propSchema]) => {
-			const required = Array.isArray(schema.required) ? schema.required.includes(propName) : !!schema.required;
-			const resolvedPropSchema = propSchema;
-			const propNullable = isNullable(resolvedPropSchema);
-			const propNode = parseSchema({
-				schema: resolvedPropSchema,
-				name: _kubb_core.ast.childName(name, propName)
-			}, rawOptions);
-			let schemaNode = _kubb_core.ast.setEnumName(propNode, name, propName, options.enumSuffix);
-			const tupleNode = _kubb_core.ast.narrowSchema(schemaNode, "tuple");
-			if (tupleNode?.items) {
-				const namedItems = tupleNode.items.map((item) => _kubb_core.ast.setEnumName(item, name, propName, options.enumSuffix));
-				if (namedItems.some((item, i) => item !== tupleNode.items[i])) schemaNode = {
-					...tupleNode,
-					items: namedItems
-				};
-			}
-			return _kubb_core.ast.createProperty({
-				name: propName,
-				schema: {
-					...schemaNode,
-					nullable: schemaNode.type === "null" ? void 0 : propNullable || void 0
-				},
-				required
-			});
-		}) : [];
-		const additionalProperties = schema.additionalProperties;
-		let additionalPropertiesNode;
-		if (additionalProperties === true) additionalPropertiesNode = true;
-		else if (additionalProperties && Object.keys(additionalProperties).length > 0) additionalPropertiesNode = parseSchema({ schema: additionalProperties }, rawOptions);
-		else if (additionalProperties === false) additionalPropertiesNode = false;
-		else if (additionalProperties) additionalPropertiesNode = _kubb_core.ast.createSchema({ type: typeOptionMap.get(options.unknownType) });
-		const rawPatternProperties = "patternProperties" in schema ? schema.patternProperties : void 0;
-		const patternProperties = rawPatternProperties ? Object.fromEntries(Object.entries(rawPatternProperties).map(([pattern, patternSchema]) => [pattern, patternSchema === true || typeof patternSchema === "object" && Object.keys(patternSchema).length === 0 ? _kubb_core.ast.createSchema({ type: typeOptionMap.get(options.unknownType) }) : parseSchema({ schema: patternSchema }, rawOptions)])) : void 0;
-		const objectNode = _kubb_core.ast.createSchema({
-			type: "object",
-			primitive: "object",
-			properties,
-			additionalProperties: additionalPropertiesNode,
-			patternProperties,
-			minProperties: schema.minProperties,
-			maxProperties: schema.maxProperties,
-			...buildSchemaNode(schema, name, nullable, defaultValue)
+	return named;
+}
+/**
+* Converts an object-like schema into an `ObjectSchemaNode`.
+*/
+function convertObject({ schema, name, nullable, defaultValue, rawOptions, options, parse }) {
+	const properties = schema.properties ? Object.entries(schema.properties).map(([propName, propSchema]) => {
+		const required = Array.isArray(schema.required) ? schema.required.includes(propName) : !!schema.required;
+		const resolvedPropSchema = propSchema;
+		const propNullable = isNullable(resolvedPropSchema);
+		const schemaNode = nameEnums(parse({
+			schema: resolvedPropSchema,
+			name: (0, _kubb_kit.childName)(name, propName)
+		}, rawOptions), {
+			parentName: name,
+			propName,
+			enumSuffix: options.enumSuffix
 		});
-		if (isDiscriminator(schema) && schema.discriminator.mapping) {
-			const discPropName = schema.discriminator.propertyName;
-			const values = Object.keys(schema.discriminator.mapping);
-			const enumName = name ? _kubb_core.ast.enumPropName(name, discPropName, options.enumSuffix) : void 0;
-			return _kubb_core.ast.setDiscriminatorEnum({
-				node: objectNode,
-				propertyName: discPropName,
-				values,
-				enumName
-			});
-		}
-		return objectNode;
-	}
-	/**
-	* Converts an OAS 3.1 `prefixItems` tuple into a `TupleSchemaNode`.
-	*/
-	function convertTuple({ schema, name, nullable, defaultValue, rawOptions }) {
-		const tupleItems = (schema.prefixItems ?? []).map((item) => parseSchema({ schema: item }, rawOptions));
-		const rest = schema.items ? parseSchema({ schema: schema.items }, rawOptions) : _kubb_core.ast.createSchema({ type: "any" });
-		return _kubb_core.ast.createSchema({
-			type: "tuple",
-			primitive: "array",
-			items: tupleItems,
-			rest,
-			min: schema.minItems,
-			max: schema.maxItems,
-			...buildSchemaNode(schema, name, nullable, defaultValue)
+		return _kubb_ast.ast.factory.createProperty({
+			name: propName,
+			schema: {
+				...schemaNode,
+				nullable: schemaNode.type === "null" ? void 0 : propNullable || void 0
+			},
+			required
 		});
+	}) : [];
+	const additionalProperties = schema.additionalProperties;
+	let additionalPropertiesNode;
+	if (additionalProperties === true) additionalPropertiesNode = true;
+	else if (additionalProperties) additionalPropertiesNode = resolveMapSchema(additionalProperties, options, parse, rawOptions);
+	else additionalPropertiesNode = additionalProperties;
+	const rawPatternProperties = "patternProperties" in schema ? schema.patternProperties : void 0;
+	const patternProperties = rawPatternProperties ? Object.fromEntries(Object.entries(rawPatternProperties).map(([pattern, patternSchema]) => [pattern, resolveMapSchema(patternSchema, options, parse, rawOptions)])) : void 0;
+	const objectNode = createNode({
+		schema,
+		name,
+		nullable,
+		defaultValue
+	}, {
+		type: "object",
+		primitive: "object",
+		properties,
+		additionalProperties: additionalPropertiesNode,
+		patternProperties,
+		minProperties: schema.minProperties,
+		maxProperties: schema.maxProperties
+	});
+	if (isDiscriminator(schema) && schema.discriminator.mapping) {
+		const discPropName = schema.discriminator.propertyName;
+		const values = Object.keys(schema.discriminator.mapping);
+		const enumName = name ? (0, _kubb_kit.enumPropName)(name, discPropName, options.enumSuffix) : void 0;
+		return _kubb_ast.ast.applyMacros(objectNode, [(0, _kubb_kit.macroDiscriminatorEnum)({
+			propertyName: discPropName,
+			values,
+			enumName
+		})], { depth: "shallow" });
+	}
+	return objectNode;
+}
+/**
+* Converts an OAS 3.1 `prefixItems` tuple into a `TupleSchemaNode`.
+*/
+function convertTuple({ schema, name, nullable, defaultValue, rawOptions, options, parse }) {
+	const tupleItems = (schema.prefixItems ?? []).map((item) => parse({ schema: item }, rawOptions));
+	const rest = schema.items === false ? void 0 : !schema.items || schema.items === true ? _kubb_ast.ast.factory.createSchema({ type: options.unknownType }) : parse({ schema: schema.items }, rawOptions);
+	return createNode({
+		schema,
+		name,
+		nullable,
+		defaultValue
+	}, {
+		type: "tuple",
+		primitive: "array",
+		items: tupleItems,
+		rest,
+		min: schema.minItems,
+		max: schema.maxItems
+	});
+}
+/**
+* Converts a `type: 'array'` schema into an `ArraySchemaNode`.
+*/
+function convertArray({ schema, name, nullable, defaultValue, rawOptions, options, parse }) {
+	const rawItems = schema.items;
+	const itemName = rawItems?.enum?.length && name ? (0, _kubb_kit.enumPropName)(null, name, options.enumSuffix) : name;
+	const items = rawItems ? [parse({
+		schema: rawItems,
+		name: itemName
+	}, rawOptions)] : [];
+	return createNode({
+		schema,
+		name,
+		nullable,
+		defaultValue
+	}, {
+		type: "array",
+		primitive: "array",
+		items,
+		min: schema.minItems,
+		max: schema.maxItems,
+		unique: schema.uniqueItems ?? void 0
+	});
+}
+//#endregion
+//#region src/emit/parseSchema.ts
+/**
+* Ordered schema rule table. Order is significant: composition keywords (`$ref`, `allOf`,
+* `oneOf`/`anyOf`) take precedence over `const`/`format`, which take precedence over the plain
+* `type`. The first matching rule that produces a node wins. See {@link SchemaRule} for the
+* match/convert/fall-through contract.
+*/
+const schemaRules = [
+	{
+		match: ({ schema }) => isReference(schema),
+		convert: convertRef
+	},
+	{
+		match: ({ schema }) => !!schema.allOf?.length,
+		convert: convertAllOf
+	},
+	{
+		match: ({ schema }) => !!(schema.oneOf?.length || schema.anyOf?.length),
+		convert: convertUnion
+	},
+	{
+		match: ({ schema }) => "const" in schema && schema.const !== void 0,
+		convert: convertConst
+	},
+	{
+		match: ({ schema, options }) => {
+			if (!schema.format) return false;
+			if (schema.format === "date-time" || schema.format === "date" || schema.format === "time") return options.dateType !== false;
+			return isHandledFormat(schema.format);
+		},
+		convert: convertFormat
+	},
+	{
+		match: ({ schema }) => isBinary(schema),
+		convert: convertBinary
+	},
+	{
+		match: ({ schema }) => Array.isArray(schema.type) && schema.type.filter((t) => t !== "null").length > 1,
+		convert: convertMultiType
+	},
+	{
+		match: ({ schema, type }) => !type && (schema.minLength !== void 0 || schema.maxLength !== void 0 || schema.pattern !== void 0),
+		convert: convertString
+	},
+	{
+		match: ({ schema, type }) => !type && (schema.minimum !== void 0 || schema.maximum !== void 0),
+		convert: (ctx) => convertNumeric(ctx, "number")
+	},
+	{
+		match: ({ schema }) => !!schema.enum?.length,
+		convert: convertEnum
+	},
+	{
+		match: ({ schema, type }) => type === "object" || !!schema.properties || !!schema.additionalProperties || "patternProperties" in schema,
+		convert: convertObject
+	},
+	{
+		match: ({ schema }) => "prefixItems" in schema,
+		convert: convertTuple
+	},
+	{
+		match: ({ schema, type }) => type === "array" || "items" in schema,
+		convert: convertArray
+	},
+	{
+		match: ({ type }) => type === "string",
+		convert: convertString
+	},
+	{
+		match: ({ type }) => type === "number",
+		convert: (ctx) => convertNumeric(ctx, "number")
+	},
+	{
+		match: ({ type }) => type === "integer",
+		convert: (ctx) => convertNumeric(ctx, "integer")
+	},
+	{
+		match: ({ type }) => type === "boolean",
+		convert: convertBoolean
+	},
+	{
+		match: ({ type }) => type === "null",
+		convert: ({ schema, name, nullable }) => createNullNode(schema, name, nullable)
 	}
-	/**
-	* Converts a `type: 'array'` schema into an `ArraySchemaNode`.
-	*/
-	function convertArray({ schema, name, nullable, defaultValue, rawOptions, options }) {
-		const rawItems = schema.items;
-		const itemName = rawItems?.enum?.length && name ? _kubb_core.ast.enumPropName(void 0, name, options.enumSuffix) : void 0;
-		const items = rawItems ? [parseSchema({
-			schema: rawItems,
-			name: itemName
-		}, rawOptions)] : [];
-		return _kubb_core.ast.createSchema({
-			type: "array",
-			primitive: "array",
-			items,
-			min: schema.minItems,
-			max: schema.maxItems,
-			unique: schema.uniqueItems ?? void 0,
-			...buildSchemaNode(schema, name, nullable, defaultValue)
-		});
+];
+//#endregion
+//#region src/refs.ts
+const _refCache = /* @__PURE__ */ new WeakMap();
+/**
+* Walks a local `#/...` JSON pointer against `document`, memoized per document. `applicable` is
+* `false` for an empty or non-local ref (the caller should not treat that as a failed lookup).
+* Shared by `resolveRef`'s reporting walk and `createRefs().resolve`'s silent walk, so both use
+* the same trimming and caching instead of two separate implementations.
+*/
+function walkPointer(document, $ref) {
+	const trimmed = $ref.trim();
+	if (trimmed === "" || !trimmed.startsWith("#")) return {
+		applicable: false,
+		value: null
+	};
+	const pointer = globalThis.decodeURIComponent(trimmed.substring(1));
+	let docCache = _refCache.get(document);
+	if (!docCache) {
+		docCache = /* @__PURE__ */ new Map();
+		_refCache.set(document, docCache);
 	}
+	if (docCache.has(pointer)) return {
+		applicable: true,
+		value: docCache.get(pointer)
+	};
+	const current = pointer.split("/").filter(Boolean).reduce((obj, key) => obj?.[key], document);
+	if (current) docCache.set(pointer, current);
+	return {
+		applicable: true,
+		value: current ?? null
+	};
+}
+/**
+* Resolves a local JSON pointer reference from a document.
+*
+* Accepts `#/...` refs. Returns `null` for an empty or non-local ref. When the pointer cannot be
+* resolved, reports a `refNotFound` diagnostic into the active build and returns `null`. Outside a
+* build there is no sink to collect it, so it throws instead.
+*
+* @example
+* ```ts
+* resolveRef<SchemaObject>(document, '#/components/schemas/Pet')
+* ```
+*/
+function resolveRef(document, $ref) {
+	const { applicable, value } = walkPointer(document, $ref);
+	if (!applicable) return null;
+	if (value) return value;
+	const diagnostic = {
+		code: _kubb_core.Diagnostics.code.refNotFound,
+		severity: "error",
+		message: `Could not find a definition for ${$ref}.`,
+		help: "Add the schema under `components.schemas`, or fix the `$ref`. Run `kubb validate` to check the spec.",
+		location: {
+			kind: "schema",
+			pointer: $ref,
+			ref: $ref
+		}
+	};
+	if (!_kubb_core.Diagnostics.report(diagnostic)) throw new _kubb_core.Diagnostics.Error(diagnostic);
+	return null;
+}
+/**
+* Resolves a `$ref` object while preserving the original `$ref` field on the result.
+*
+* Useful for parser flows that need both dereferenced fields and pointer
+* identity (for naming/import purposes). Non-reference values are returned as-is.
+*
+* @example
+* ```ts
+* dereferenceWithRef(document, { $ref: '#/components/schemas/Pet' })
+* // { $ref: '#/components/schemas/Pet', type: 'object', properties: { ... } }
+* ```
+*/
+function dereferenceWithRef(document, schema) {
+	if (isReference(schema)) return {
+		...schema,
+		...resolveRef(document, schema.$ref),
+		$ref: schema.$ref
+	};
+	return schema;
+}
+/**
+* Creates the `$ref` resolution service for one document.
+*
+* Replaces what used to be six overlapping resolvers (a reporting walk, a silent walk, an
+* existence check, and a resolve-then-parse-into-a-node step, each with its own cache) with one
+* pointer walk and one explicit `report` contract for a missing ref: `report: true` (the default)
+* reports a `refNotFound` diagnostic (or throws outside a build), `report: false` resolves to
+* `null` silently for a speculative lookup.
+*
+* @example
+* ```ts
+* const refs = createRefs(document)
+* refs.resolve<SchemaObject>('#/components/schemas/Pet')
+* refs.resolve<SchemaObject>('#/components/schemas/Pet', { report: false })
+* refs.exists('#/components/schemas/Pet')
+* refs.resolveNode('#/components/schemas/Pet', parseSchema)
+* refs.deref<ResponseObject>(operation.schema.responses?.['200'])
+* ```
+*/
+function createRefs(document) {
+	const resolvedNodeCache = /* @__PURE__ */ new Map();
+	const existenceCache = /* @__PURE__ */ new Map();
+	const resolvingRefs = /* @__PURE__ */ new Set();
 	/**
-	* Converts a `type: 'string'` schema into a `StringSchemaNode`.
+	* Resolves a local `#/...` JSON pointer. Returns `null` for an empty or non-local ref.
+	* `report: true` (default) reports a `refNotFound` diagnostic into the active build (or throws
+	* outside one) when the pointer cannot be resolved. `report: false` resolves to `null` silently,
+	* for a speculative lookup where a missing ref is not an error.
 	*/
-	function convertString({ schema, name, nullable, defaultValue }) {
-		return _kubb_core.ast.createSchema({
-			type: "string",
-			primitive: "string",
-			min: schema.minLength,
-			max: schema.maxLength,
-			pattern: schema.pattern,
-			...buildSchemaNode(schema, name, nullable, defaultValue)
-		});
+	function resolve(refPath, options) {
+		if (options?.report === false) {
+			const { applicable, value } = walkPointer(document, refPath);
+			return applicable ? value : null;
+		}
+		return resolveRef(document, refPath);
 	}
 	/**
-	* Converts a `type: 'number'` or `type: 'integer'` schema.
+	* Returns `true` when a `$ref` path resolves to a component the document actually defines.
+	* A circular ref still resolves to an existing target, so this stays `true` for cycles and only
+	* goes `false` for a `$ref` that points at a component the spec never declares. Memoized.
 	*/
-	function convertNumeric({ schema, name, nullable, defaultValue }, type) {
-		return _kubb_core.ast.createSchema({
-			type,
-			primitive: type,
-			min: schema.minimum,
-			max: schema.maximum,
-			exclusiveMinimum: typeof schema.exclusiveMinimum === "number" ? schema.exclusiveMinimum : void 0,
-			exclusiveMaximum: typeof schema.exclusiveMaximum === "number" ? schema.exclusiveMaximum : void 0,
-			multipleOf: schema.multipleOf,
-			...buildSchemaNode(schema, name, nullable, defaultValue)
-		});
+	function exists(refPath) {
+		if (!existenceCache.has(refPath)) existenceCache.set(refPath, !!resolve(refPath, { report: false }));
+		return existenceCache.get(refPath) ?? false;
 	}
 	/**
-	* Converts a `type: 'boolean'` schema.
+	* Resolves a `$ref` to its parsed node via `parse`, guarding against cycles and memoizing per
+	* instance. Returns `null` when the ref is currently being resolved (a cycle) or cannot be
+	* resolved (e.g. a minimal document in a unit test).
 	*/
-	function convertBoolean({ schema, name, nullable, defaultValue }) {
-		return _kubb_core.ast.createSchema({
-			type: "boolean",
-			primitive: "boolean",
-			...buildSchemaNode(schema, name, nullable, defaultValue)
-		});
+	function resolveNode(refPath, parse, rawOptions) {
+		if (resolvingRefs.has(refPath)) return null;
+		if (!resolvedNodeCache.has(refPath)) {
+			let resolved = null;
+			try {
+				const referenced = resolve(refPath);
+				if (referenced) {
+					resolvingRefs.add(refPath);
+					resolved = parse({ schema: referenced }, rawOptions);
+					resolvingRefs.delete(refPath);
+				}
+			} catch {}
+			resolvedNodeCache.set(refPath, resolved);
+		}
+		return resolvedNodeCache.get(refPath) ?? null;
 	}
 	/**
-	* Converts an explicit `type: 'null'` schema.
+	* Resolves a `$ref` value without mutating anything: when `value` holds a `$ref`, returns the
+	* resolved target. Returns `null` when the value is empty, cannot be resolved, or is still a
+	* `$ref` after resolving (e.g. a document with no component registry). A non-`$ref` value is
+	* returned as-is.
+	*
+	* @example
+	* ```ts
+	* refs.deref<ResponseObject>(operation.schema.responses?.['200'])
+	* ```
 	*/
-	function convertNull({ schema, name, nullable }) {
-		return _kubb_core.ast.createSchema({
-			type: "null",
-			primitive: "null",
-			name,
-			title: schema.title,
-			description: schema.description,
-			deprecated: schema.deprecated,
-			nullable
-		});
+	function deref(value) {
+		if (!isReference(value)) return value ? value : null;
+		const resolved = resolve(value.$ref);
+		return resolved && !isReference(resolved) ? resolved : null;
 	}
+	return {
+		resolve,
+		exists,
+		resolveNode,
+		deref
+	};
+}
+//#endregion
+//#region src/model/operations.ts
+/**
+* Returns all parameters for an operation, merging path-level and operation-level entries.
+* Operation-level parameters override path-level ones with the same `in:name` key.
+* Each `$ref` parameter is dereferenced via `dereferenceWithRef` before merging.
+*
+* @example
+* ```ts
+* getParameters({ document, operation })
+* // [{ name: 'petId', in: 'path', required: true, schema: { type: 'integer' } }]
+* ```
+*/
+function getParameters({ document, operation }) {
+	const resolveParams = (params) => params.map((p) => dereferenceWithRef(document, p)).filter((p) => !!p && typeof p === "object" && "in" in p && "name" in p);
+	const operationParams = resolveParams(operation.schema?.parameters || []);
+	const pathLevelParams = resolveParams(operation.pathItem.parameters ?? []);
+	const paramMap = /* @__PURE__ */ new Map();
+	for (const p of pathLevelParams) if (p.name && p.in) paramMap.set(`${p.in}:${p.name}`, p);
+	for (const p of operationParams) if (p.name && p.in) paramMap.set(`${p.in}:${p.name}`, p);
+	return Array.from(paramMap.values());
+}
+function getResponseBody(responseBody, contentType) {
+	if (!responseBody) return false;
+	if (isReference(responseBody)) return false;
+	const body = responseBody;
+	if (!body.content) return false;
+	if (contentType) return contentType in body.content ? body.content[contentType] : false;
+	const picked = pickContentEntry(body.content);
+	return picked ? picked[1] : false;
+}
+/**
+* Returns the response schema for a given operation and HTTP status code.
+*
+* Returns an empty object `{}` when no response body schema is available.
+*
+* @example
+* ```ts
+* getResponseSchema({ document, operation, refs, statusCode: 200 })   // SchemaObject
+* getResponseSchema({ document, operation, refs, statusCode: '4XX' }) // {}
+* ```
+*/
+function getResponseSchema({ document, operation, refs, statusCode, options = {} }) {
+	const responseBody = getResponseBody(getResponseByStatusCode({
+		operation,
+		refs,
+		statusCode
+	}), options.contentType);
+	if (responseBody === false) return {};
+	const schema = responseBody.schema;
+	if (!schema) return {};
+	return dereferenceWithRef(document, schema);
+}
+/**
+* Returns the request body schema for an operation, or `null` when absent.
+*
+* @example
+* ```ts
+* getRequestSchema({ document, operation, refs }) // SchemaObject | null
+* ```
+*/
+function getRequestSchema({ document, operation, refs, options = {} }) {
+	const requestBody = getRequestContent({
+		operation,
+		refs,
+		mediaType: options.contentType
+	});
+	if (requestBody === false) return null;
+	const mediaType = Array.isArray(requestBody) ? requestBody[0] : options.contentType;
+	const schema = Array.isArray(requestBody) ? requestBody[1].schema : requestBody.schema;
+	if (mediaType === "application/octet-stream" && (!schema || Object.keys(schema).length === 0)) return {
+		type: "string",
+		contentMediaType: "application/octet-stream"
+	};
+	if (!schema) return null;
+	return dereferenceWithRef(document, schema);
+}
+/**
+* Returns all request body content type keys for an operation, resolving a `$ref` requestBody
+* through `refs`.
+*
+* @example
+* ```ts
+* getRequestBodyContentTypes(operation, refs)
+* // ['application/json', 'multipart/form-data']
+* ```
+*/
+function getRequestBodyContentTypes(operation, refs) {
+	const body = getRequestBody({
+		operation,
+		refs
+	});
+	return body?.content ? Object.keys(body.content) : [];
+}
+/**
+* Returns all response content type keys for an operation at a given status code, resolving the
+* response `$ref` through `refs`.
+*
+* @example
+* ```ts
+* getResponseBodyContentTypes(operation, refs, 200)
+* // ['application/json', 'application/xml']
+* ```
+*/
+function getResponseBodyContentTypes(operation, refs, statusCode) {
+	const responseObj = getResponseByStatusCode({
+		operation,
+		refs,
+		statusCode
+	});
+	if (!responseObj || typeof responseObj !== "object" || isReference(responseObj)) return [];
+	const body = responseObj;
+	return body.content ? Object.keys(body.content) : [];
+}
+//#endregion
+//#region src/parser.ts
+/**
+* Creates the schema and operation converters bound to one OpenAPI document.
+*
+* Takes the `$ref` service for this document (shared with the rest of the pipeline, see
+* `adapter.ts`) and owns the `parseSchema` recursion seam, then dispatches each schema through
+* the ordered `schemaRules` table from `emit/parseSchema.ts`. Every converter is a standalone
+* function that recurses through the `parse` function passed to it, so this file only wires
+* state to the converters.
+*
+* @internal
+*/
+function createSchemaParser(ctx) {
+	const document = ctx.document;
+	const refs = ctx.refs;
 	/**
-	* Central dispatcher that converts an OAS `SchemaObject` into a `SchemaNode`.
+	* Converts an OAS `SchemaObject` into a `SchemaNode`.
 	*
-	* Dispatch order (first match wins): `$ref` → `allOf` → `oneOf`/`anyOf` → `const` → `format`
-	* → octet-stream blob → multi-type array → constraint-inferred type → `enum` → object/array/tuple/scalar
-	* → empty-schema fallback (`emptySchemaType` option).
+	* Builds the per-schema context, then walks the ordered {@link schemaRules} table and returns
+	* the first converter that produces a node. When none match, falls back to the configured
+	* `emptySchemaType`.
 	*/
 	function parseSchema({ schema, name }, rawOptions) {
 		const options = {
@@ -1691,88 +2169,64 @@ function createSchemaParser(ctx) {
 			name
 		}, rawOptions);
 		const nullable = isNullable(schema) || void 0;
-		const defaultValue = schema.default === null && nullable ? void 0 : schema.default;
-		const type = Array.isArray(schema.type) ? schema.type[0] : schema.type;
-		const ctx = {
+		const context = {
 			schema,
 			name,
 			nullable,
-			defaultValue,
-			type,
+			defaultValue: schema.default === null && nullable ? void 0 : schema.default,
+			type: Array.isArray(schema.type) ? schema.type[0] : schema.type,
 			rawOptions,
-			options
+			options,
+			parse: parseSchema,
+			document,
+			refs,
+			renames: ctx.renames
 		};
-		if (isReference(schema)) return convertRef(ctx);
-		if (schema.allOf?.length) return convertAllOf(ctx);
-		if ([...schema.oneOf ?? [], ...schema.anyOf ?? []].length) return convertUnion(ctx);
-		if ("const" in schema && schema.const !== void 0) return convertConst(ctx);
-		if (schema.format) {
-			const formatResult = convertFormat(ctx);
-			if (formatResult) return formatResult;
-		}
-		if (schema.type === "string" && schema.contentMediaType === "application/octet-stream") return _kubb_core.ast.createSchema({
-			type: "blob",
-			primitive: "string",
-			...buildSchemaNode(schema, name, nullable, defaultValue)
-		});
-		if (Array.isArray(schema.type) && schema.type.length > 1) {
-			const nonNullTypes = schema.type.filter((t) => t !== "null");
-			const arrayNullable = schema.type.includes("null") || nullable || void 0;
-			if (nonNullTypes.length > 1) return _kubb_core.ast.createSchema({
-				type: "union",
-				members: nonNullTypes.map((t) => parseSchema({
-					schema: {
-						...schema,
-						type: t
-					},
-					name
-				}, rawOptions)),
-				...buildSchemaNode(schema, name, arrayNullable, defaultValue)
-			});
-		}
-		if (!type) {
-			if (schema.minLength !== void 0 || schema.maxLength !== void 0 || schema.pattern !== void 0) return convertString(ctx);
-			if (schema.minimum !== void 0 || schema.maximum !== void 0) return convertNumeric(ctx, "number");
-		}
-		if (schema.enum?.length) return convertEnum(ctx);
-		if (type === "object" || schema.properties || schema.additionalProperties || "patternProperties" in schema) return convertObject(ctx);
-		if ("prefixItems" in schema) return convertTuple(ctx);
-		if (type === "array" || "items" in schema) return convertArray(ctx);
-		if (type === "string") return convertString(ctx);
-		if (type === "number") return convertNumeric(ctx, "number");
-		if (type === "integer") return convertNumeric(ctx, "integer");
-		if (type === "boolean") return convertBoolean(ctx);
-		if (type === "null") return convertNull(ctx);
-		const emptyType = typeOptionMap.get(options.emptySchemaType);
-		return _kubb_core.ast.createSchema({
+		for (const rule of schemaRules) if (rule.match(context)) return rule.convert(context);
+		const emptyType = options.emptySchemaType;
+		return _kubb_ast.ast.factory.createSchema({
 			type: emptyType,
 			name,
 			title: schema.title,
-			description: schema.description
+			description: schema.description,
+			format: schema.format
 		});
 	}
 	/**
 	* Converts a dereferenced OAS parameter object into a `ParameterNode`.
 	*/
-	function parseParameter(options, param) {
+	function parseParameter(options, param, parentName) {
 		const required = param["required"] ?? false;
-		const schema = param["schema"] ? parseSchema({ schema: param["schema"] }, options) : _kubb_core.ast.createSchema({ type: typeOptionMap.get(options.unknownType) });
-		return _kubb_core.ast.createParameter({
-			name: param["name"],
+		const paramName = param["name"];
+		const schemaName = parentName && paramName ? pascalCase(`${parentName} ${paramName}`) : void 0;
+		const schema = param["schema"] ? parseSchema({
+			schema: param["schema"],
+			name: schemaName
+		}, options) : _kubb_ast.ast.factory.createSchema({ type: options.unknownType });
+		const style = param["style"];
+		const explode = param["explode"];
+		return _kubb_ast.ast.factory.createParameter({
+			name: paramName,
 			in: param["in"],
 			schema: {
 				...schema,
 				description: param["description"] ?? schema.description
 			},
-			required
+			required,
+			...style !== void 0 ? { style } : {},
+			...explode !== void 0 ? { explode } : {}
 		});
 	}
 	/**
 	* Reads the inline `requestBody` metadata (description / required) that OAS exposes
-	* outside the schema itself. Returns an empty object when the request body is missing or a `$ref`.
+	* outside the schema itself, resolving a `$ref` requestBody through `refs`. Returns an
+	* empty object when the request body is missing or cannot be resolved.
 	*/
 	function getRequestBodyMeta(operation) {
-		const body = operation.schema.requestBody;
+		const body = getRequestBody({
+			operation,
+			refs
+		});
 		if (!body) return { required: false };
 		return {
 			description: body.description,
@@ -1780,73 +2234,109 @@ function createSchemaParser(ctx) {
 		};
 	}
 	/**
-	* Reads the inline response object (not a `$ref`) and returns its description plus its `content` map.
-	*/
-	function getResponseMeta(responseObj) {
-		if (typeof responseObj !== "object" || responseObj === null || Array.isArray(responseObj)) return {};
-		const inline = responseObj;
-		return {
-			description: inline.description,
-			content: inline.content
-		};
-	}
-	/**
 	* Collects property names whose schema has a truthy boolean flag (`readOnly` or `writeOnly`).
 	* `$ref` entries are skipped since their flags live on the dereferenced target.
 	*/
 	function collectPropertyKeysByFlag(schema, flag) {
-		if (!schema?.properties) return void 0;
+		if (!schema?.properties) return null;
 		const keys = [];
 		for (const key in schema.properties) {
 			const prop = schema.properties[key];
 			if (prop && !isReference(prop) && prop[flag]) keys.push(key);
 		}
-		return keys.length ? keys : void 0;
+		return keys.length ? keys : null;
 	}
 	/**
 	* Converts an OAS `Operation` into an `OperationNode`.
 	*/
 	function parseOperation(options, operation) {
-		const parameters = getParameters(document, operation).map((param) => parseParameter(options, param));
-		const allContentTypes = ctx.contentType ? [ctx.contentType] : getRequestBodyContentTypes(document, operation);
+		const operationId = getOperationId(operation);
+		const operationName = operationId ? pascalCase(operationId) : void 0;
+		const parameters = getParameters({
+			document,
+			operation
+		}).map((param) => parseParameter(options, param, operationName));
+		const allContentTypes = ctx.contentType ? [ctx.contentType] : getRequestBodyContentTypes(operation, refs);
 		const requestBodyMeta = getRequestBodyMeta(operation);
+		const requestBodyName = operationName ? `${operationName}Request` : void 0;
 		const content = allContentTypes.flatMap((ct) => {
-			const schema = getRequestSchema(document, operation, { contentType: ct });
+			const schema = getRequestSchema({
+				document,
+				operation,
+				refs,
+				options: { contentType: ct }
+			});
 			if (!schema) return [];
-			return [{
+			return [_kubb_ast.ast.factory.createContent({
 				contentType: ct,
-				schema: _kubb_core.ast.syncOptionality(parseSchema({ schema }, options), requestBodyMeta.required),
+				schema: _kubb_ast.ast.optionality(parseSchema({
+					schema,
+					name: requestBodyName
+				}, options), requestBodyMeta.required),
 				keysToOmit: collectPropertyKeysByFlag(schema, "readOnly")
-			}];
+			})];
 		});
 		const requestBody = content.length > 0 || requestBodyMeta.description ? {
 			description: requestBodyMeta.description,
 			required: requestBodyMeta.required || void 0,
 			content: content.length > 0 ? content : void 0
 		} : void 0;
-		const responses = operation.getResponseStatusCodes().map((statusCode) => {
-			const responseObj = operation.getResponseByStatusCode(statusCode);
-			const responseSchema = getResponseSchema(document, operation, statusCode, { contentType: ctx.contentType });
-			const schema = responseSchema && Object.keys(responseSchema).length > 0 ? parseSchema({ schema: responseSchema }, options) : _kubb_core.ast.createSchema({ type: typeOptionMap.get(options.emptySchemaType) });
-			const { description, content } = getResponseMeta(responseObj);
-			const mediaType = content ? getMediaType(Object.keys(content)[0] ?? "") : getMediaType(operation.contentType ?? "");
-			return _kubb_core.ast.createResponse({
+		const responses = getResponseStatusCodes(operation).map((statusCode) => {
+			const responseObj = getResponseByStatusCode({
+				operation,
+				refs,
+				statusCode
+			});
+			const responseName = operationName ? `${operationName}Status${statusCode}` : void 0;
+			const description = typeof responseObj === "object" && responseObj !== null ? responseObj.description : void 0;
+			const parseEntrySchema = (contentType) => {
+				const raw = getResponseSchema({
+					document,
+					operation,
+					refs,
+					statusCode,
+					options: { contentType }
+				});
+				return {
+					schema: raw && Object.keys(raw).length > 0 ? parseSchema({
+						schema: raw,
+						name: responseName
+					}, options) : _kubb_ast.ast.factory.createSchema({ type: options.emptySchemaType }),
+					keysToOmit: collectPropertyKeysByFlag(raw, "writeOnly")
+				};
+			};
+			const content = (ctx.contentType ? [ctx.contentType] : getResponseBodyContentTypes(operation, refs, statusCode)).map((contentType) => _kubb_ast.ast.factory.createContent({
+				contentType,
+				...parseEntrySchema(contentType)
+			}));
+			if (content.length === 0) content.push(_kubb_ast.ast.factory.createContent({
+				contentType: getRequestContentType({
+					operation,
+					refs
+				}) || "application/json",
+				...parseEntrySchema(ctx.contentType)
+			}));
+			return _kubb_ast.ast.factory.createResponse({
 				statusCode,
 				description,
-				schema,
-				mediaType,
-				keysToOmit: collectPropertyKeysByFlag(responseSchema, "writeOnly")
+				content
 			});
 		});
-		const urlPath = new URLPath(operation.path);
-		return _kubb_core.ast.createOperation({
-			operationId: operation.getOperationId(),
+		const pickDoc = (key) => {
+			const own = operation.schema[key];
+			if (typeof own === "string") return own;
+			const fallback = operation.pathItem[key];
+			return typeof fallback === "string" ? fallback : void 0;
+		};
+		return _kubb_ast.ast.factory.createOperation({
+			operationId,
+			protocol: "http",
 			method: operation.method.toUpperCase(),
-			path: urlPath.path,
-			tags: operation.getTags().map((tag) => tag.name),
-			summary: operation.getSummary() || void 0,
-			description: operation.getDescription() || void 0,
-			deprecated: operation.isDeprecated() || void 0,
+			path: operation.path,
+			tags: Array.isArray(operation.schema.tags) ? operation.schema.tags.map(String) : [],
+			summary: pickDoc("summary") || void 0,
+			description: pickDoc("description") || void 0,
+			deprecated: operation.schema.deprecated || void 0,
 			parameters,
 			requestBody,
 			responses
@@ -1858,59 +2348,131 @@ function createSchemaParser(ctx) {
 		parseParameter
 	};
 }
+//#endregion
+//#region src/promoteEnums.ts
 /**
-* Parses an OpenAPI specification into Kubb's universal `InputNode` AST.
-*
-* This is the main entry point for `@kubb/adapter-oas`. It converts OpenAPI/Swagger specs into a spec-agnostic tree
-* that downstream plugins (`plugin-ts`, `plugin-zod`, etc.) consume for code generation. No code is generated here —
-* the tree is a pure data structure representing all schemas and operations.
-*
-* Returns the AST root and a `nameMapping` for resolving schema references.
-*
-* @example
-* ```ts
-* import { parseOas } from '@kubb/adapter-oas'
-*
-* const document = await parseFromConfig(config)
-* const { root, nameMapping } = parseOas(document, { dateType: 'date', contentType: 'application/json' })
-* ```
+* Collects inline enums to lift to the top level, keyed by the name the parser derived for them
+* (e.g. `PetStatusEnum`). An enum already defined as a top-level component is left as-is, and a
+* name that recurs maps to the first definition so each name yields one shared type.
 */
-function parseOas(document, options = {}) {
-	const { contentType, ...parserOptions } = options;
-	const mergedOptions = {
-		...DEFAULT_PARSER_OPTIONS,
-		...parserOptions
-	};
-	const { schemas: schemaObjects, nameMapping } = getSchemas(document, { contentType });
-	const { parseSchema: _parseSchema, parseOperation: _parseOperation } = createSchemaParser({
-		document,
-		contentType
+function collectInlineEnums(roots, topLevelNames) {
+	const promoted = /* @__PURE__ */ new Map();
+	for (const root of roots) {
+		const isSchemaRoot = root.kind === "Schema";
+		for (const node of _kubb_ast.ast.collect(root, { schema: (schemaNode) => schemaNode })) {
+			if (node.type !== "enum" || !node.name) continue;
+			if (isSchemaRoot && node === root) continue;
+			if (topLevelNames.has(node.name)) continue;
+			if (!promoted.has(node.name)) promoted.set(node.name, {
+				...node,
+				optional: void 0,
+				nullish: void 0
+			});
+		}
+	}
+	return promoted;
+}
+/**
+* Replaces every promoted inline enum in `node` with a `ref` to its lifted definition, keeping the
+* occurrence's usage-slot and documentation fields.
+*/
+function refPromotedEnums(node, promoted) {
+	if (promoted.size === 0) return node;
+	return _kubb_ast.ast.transform(node, { schema(schemaNode) {
+		if (schemaNode.type !== "enum" || !schemaNode.name || !promoted.has(schemaNode.name)) return void 0;
+		return _kubb_ast.ast.factory.createSchema({
+			type: "ref",
+			name: schemaNode.name,
+			ref: `${SCHEMA_REF_PREFIX}${schemaNode.name}`,
+			optional: schemaNode.optional,
+			nullish: schemaNode.nullish,
+			readOnly: schemaNode.readOnly,
+			writeOnly: schemaNode.writeOnly,
+			deprecated: schemaNode.deprecated,
+			description: schemaNode.description,
+			default: schemaNode.default,
+			examples: schemaNode.examples
+		});
+	} });
+}
+//#endregion
+//#region src/schemaDiagnostics.ts
+/**
+* Scans one freshly converted top-level schema in a single walk, so the post-convert pass never
+* sweeps the same nodes twice. It reports the advisory diagnostics (`KUBB_UNSUPPORTED_FORMAT`,
+* `KUBB_DEPRECATED`) and returns the names of every schema the node references, ready to feed the
+* circular-dependency graph.
+*
+* Walks the node the parser produced, threading the RFC 6901 pointer as it descends so a nested
+* field reports against its full path (`#/components/schemas/Pet/properties/owner/properties/name`).
+* Refs are recorded by name and not followed, so the resolved schema is reported under its own walk.
+* Reports land in the active build run, are a no-op outside one, and repeats are deduped by the build.
+*/
+function scanSchema({ node, name }) {
+	const refs = /* @__PURE__ */ new Set();
+	visit(node, `#/components/schemas/${escapePointerToken(name)}`, refs);
+	return refs;
+}
+/**
+* Escapes a single JSON pointer reference token per RFC 6901 (`~` → `~0`, `/` → `~1`), so a
+* property name with those characters maps to a distinct pointer instead of colliding in the dedupe.
+*/
+function escapePointerToken(token) {
+	return token.replace(/~/g, "~0").replace(/\//g, "~1");
+}
+function visit(node, pointer, refs) {
+	if (node.type === "ref") {
+		const refName = (0, _kubb_ast.resolveRefName)(node);
+		if (refName) refs.add(refName);
+	}
+	if (node.deprecated) _kubb_core.Diagnostics.report({
+		code: _kubb_core.Diagnostics.code.deprecated,
+		severity: "info",
+		message: "This schema is marked as deprecated.",
+		location: {
+			kind: "schema",
+			pointer
+		}
 	});
-	const schemas = Object.entries(schemaObjects).map(([name, schema]) => _parseSchema({
-		schema,
-		name
-	}, mergedOptions));
-	const paths = new oas.default(document).getPaths();
-	const operations = Object.entries(paths).flatMap(([_path, methods]) => Object.entries(methods).map(([, operation]) => operation ? _parseOperation(mergedOptions, operation) : null).filter((op) => op !== null));
-	return {
-		root: _kubb_core.ast.createInput({
-			schemas,
-			operations
-		}),
-		nameMapping
-	};
+	if (typeof node.format === "string" && !isHandledFormat(node.format)) _kubb_core.Diagnostics.report({
+		code: _kubb_core.Diagnostics.code.unsupportedFormat,
+		severity: "warning",
+		message: `Kubb does not map the format "${node.format}" to a specific type, so it falls back to the base type.`,
+		help: `Use a format Kubb supports, or handle "${node.format}" with a custom parser or plugin.`,
+		location: {
+			kind: "schema",
+			pointer
+		}
+	});
+	if (node.type === "object") {
+		for (const property of node.properties) visit(property.schema, `${pointer}/properties/${escapePointerToken(property.name)}`, refs);
+		if (node.additionalProperties && typeof node.additionalProperties === "object") visit(node.additionalProperties, `${pointer}/additionalProperties`, refs);
+		return;
+	}
+	if (node.type === "array") {
+		for (const item of node.items ?? []) visit(item, `${pointer}/items`, refs);
+		return;
+	}
+	if (node.type === "tuple") {
+		for (const [index, item] of (node.items ?? []).entries()) visit(item, `${pointer}/items/${index}`, refs);
+		return;
+	}
+	if (node.type === "union" || node.type === "intersection") for (const [index, member] of (node.members ?? []).entries()) visit(member, `${pointer}/members/${index}`, refs);
 }
 //#endregion
 //#region src/adapter.ts
 /**
-* Stable string identifier for the OAS adapter used in Kubb's adapter registry.
+* The `name` of `@kubb/adapter-oas`, used to identify this adapter in a Kubb config.
 */
 const adapterOasName = "oas";
 /**
-* Creates the default OpenAPI / Swagger adapter for Kubb.
+* Default Kubb adapter for OpenAPI 2.0, 3.0, and 3.1 specifications. Reads the
+* spec from `input` (a file path, URL, inline content, or parsed object), validates
+* it, resolves the base URL, and converts every schema and operation into the
+* universal AST that every downstream plugin consumes.
 *
-* Parses the spec, optionally validates it, resolves the base URL, and converts
-* everything into an `InputNode` that downstream plugins consume.
+* Configure once on `defineConfig`. The adapter's choices (date representation,
+* integer width, server URL) apply to every plugin in the build.
 *
 * @example
 * ```ts
@@ -1919,102 +2481,149 @@ const adapterOasName = "oas";
 * import { pluginTs } from '@kubb/plugin-ts'
 *
 * export default defineConfig({
-*   adapter: adapterOas({ dateType: 'date', serverIndex: 0 }),
-*   input: { path: './openapi.yaml' },
+*   input: './petStore.yaml',
+*   output: { path: './src/gen' },
+*   adapter: adapterOas({
+*     server: { index: 0 },
+*     discriminator: 'propagate',
+*     dateType: 'date',
+*   }),
 *   plugins: [pluginTs()],
 * })
 * ```
 */
 const adapterOas = (0, _kubb_core.createAdapter)((options) => {
-	const { validate = true, contentType, serverIndex, serverVariables, discriminator = "strict", dateType = DEFAULT_PARSER_OPTIONS.dateType, integerType = DEFAULT_PARSER_OPTIONS.integerType, unknownType = DEFAULT_PARSER_OPTIONS.unknownType, enumSuffix = DEFAULT_PARSER_OPTIONS.enumSuffix, emptySchemaType = unknownType || DEFAULT_PARSER_OPTIONS.emptySchemaType } = options;
-	let nameMapping = /* @__PURE__ */ new Map();
-	let parsedDocument;
-	let inputNode;
+	const { validate = true, contentType, server, discriminator = "preserve", enums = "inline", dateType = DEFAULT_PARSER_OPTIONS.dateType, integerType = DEFAULT_PARSER_OPTIONS.integerType, unknownType = DEFAULT_PARSER_OPTIONS.unknownType, enumSuffix = DEFAULT_PARSER_OPTIONS.enumSuffix, emptySchemaType = unknownType || DEFAULT_PARSER_OPTIONS.emptySchemaType } = options;
+	const parserOptions = {
+		...DEFAULT_PARSER_OPTIONS,
+		dateType,
+		integerType,
+		unknownType,
+		emptySchemaType,
+		enumSuffix
+	};
+	let parsedDocument = null;
+	const inputCache = /* @__PURE__ */ new WeakMap();
+	function parseInput({ document, refs, schemas, parser }) {
+		const { parseSchema, parseOperation } = parser;
+		const parsedByName = /* @__PURE__ */ new Map();
+		const refAliasMap = /* @__PURE__ */ new Map();
+		const enumNames = [];
+		const discriminatorParentNodes = [];
+		const refGraph = /* @__PURE__ */ new Map();
+		for (const [name, schema] of Object.entries(schemas)) {
+			const node = parseSchema({
+				schema,
+				name
+			}, parserOptions);
+			parsedByName.set(name, node);
+			const refs = scanSchema({
+				node,
+				name
+			});
+			if (node.name) refGraph.set(node.name, refs);
+			if (node.type === "ref" && node.name && node.name !== name) refAliasMap.set(name, node);
+			if ((0, _kubb_ast.narrowSchema)(node, "enum") && node.name) enumNames.push(node.name);
+			if (discriminator === "propagate" && (schema.oneOf ?? schema.anyOf) && schema.discriminator?.propertyName) discriminatorParentNodes.push(node);
+		}
+		const circularNames = [...(0, _kubb_ast.findCircularSchemasFromGraph)(refGraph)];
+		const discriminatorChildMap = discriminatorParentNodes.length > 0 ? buildDiscriminatorChildMap(discriminatorParentNodes) : null;
+		const operationNodes = [];
+		for (const operation of getOperations(document, refs)) {
+			const operationNode = parseOperation(parserOptions, operation);
+			if (operationNode) operationNodes.push(operationNode);
+		}
+		let promotedEnums = null;
+		if (enums === "root") {
+			promotedEnums = collectInlineEnums([...parsedByName.values(), ...operationNodes], new Set(Object.keys(schemas)));
+			for (const name of promotedEnums.keys()) enumNames.push(name);
+		}
+		const schemaNodes = promotedEnums ? [...promotedEnums.values()] : [];
+		for (const name of Object.keys(schemas)) {
+			const alias = refAliasMap.get(name);
+			let node;
+			if (alias?.name && parsedByName.has(alias.name)) node = {
+				...parsedByName.get(alias.name),
+				name
+			};
+			else {
+				const parsed = parsedByName.get(name);
+				const child = discriminatorChildMap?.get(name);
+				node = child ? patchDiscriminatorNode(parsed, child) : parsed;
+			}
+			schemaNodes.push(promotedEnums ? refPromotedEnums(node, promotedEnums) : node);
+		}
+		const operations = promotedEnums ? operationNodes.map((node) => refPromotedEnums(node, promotedEnums)) : operationNodes;
+		return _kubb_ast.ast.factory.createInput({
+			schemas: schemaNodes,
+			operations,
+			meta: {
+				title: document.info?.title,
+				description: document.info?.description,
+				version: document.info?.version,
+				baseURL: resolveBaseUrl({
+					document,
+					server
+				}),
+				circularNames,
+				enumNames
+			}
+		});
+	}
 	return {
 		name: "oas",
 		get options() {
 			return {
 				validate,
 				contentType,
-				serverIndex,
-				serverVariables,
+				server,
 				discriminator,
+				enums,
 				dateType,
 				integerType,
 				unknownType,
 				emptySchemaType,
-				enumSuffix,
-				nameMapping
+				enumSuffix
 			};
 		},
 		get document() {
 			return parsedDocument;
 		},
-		get inputNode() {
-			return inputNode;
-		},
 		async validate(input, options) {
-			await validateDocument(await parseDocument(input), options);
-		},
-		getImports(node, resolve) {
-			return _kubb_core.ast.collectImports({
-				node,
-				nameMapping,
-				resolve: (schemaName) => {
-					const result = resolve(schemaName);
-					if (!result) return;
-					return _kubb_core.ast.createImport({
-						name: [result.name],
-						path: result.path
-					});
-				}
-			});
+			await assertInputExists(input);
+			const document = await parseDocument(input);
+			assertDocument(document);
+			await validateDocument(document, options);
 		},
 		async parse(source) {
-			const document = await parseFromConfig(source);
-			if (validate) await validateDocument(document);
-			const server = serverIndex !== void 0 ? document.servers?.at(serverIndex) : void 0;
-			const baseURL = server?.url ? resolveServerUrl(server, serverVariables) : void 0;
-			const { root: parsedRoot, nameMapping: parsedNameMapping } = parseOas(document, {
-				contentType,
-				dateType,
-				integerType,
-				unknownType,
-				emptySchemaType,
-				enumSuffix
-			});
-			const node = discriminator === "inherit" ? applyDiscriminatorInheritance(parsedRoot) : parsedRoot;
-			nameMapping = parsedNameMapping;
-			parsedDocument = document;
-			inputNode = _kubb_core.ast.createInput({
-				...node,
-				meta: {
-					title: document.info?.title,
-					description: document.info?.description,
-					version: document.info?.version,
-					baseURL
-				}
-			});
-			return inputNode;
+			const cached = inputCache.get(source);
+			if (cached) return cached;
+			const promise = (async () => {
+				const document = await parseFromConfig(source);
+				assertDocument(document);
+				if (validate) await validateDocument(document);
+				parsedDocument = document;
+				const refs = createRefs(document);
+				const { schemas, renames } = getSchemas(document, { contentType }, refs);
+				return parseInput({
+					document,
+					refs,
+					schemas,
+					parser: createSchemaParser({
+						document,
+						refs,
+						contentType,
+						renames
+					})
+				});
+			})();
+			inputCache.set(source, promise);
+			return promise;
 		}
 	};
 });
 //#endregion
-//#region src/types.ts
-/**
-* Maps uppercase HTTP method names to lowercase for backwards compatibility.
-*
-* @example
-* ```ts
-* HttpMethods['GET'] // 'get'
-* HttpMethods['POST'] // 'post'
-* ```
-*/
-const HttpMethods = Object.fromEntries(Object.entries(_kubb_core.ast.httpMethods).map(([lower, upper]) => [upper, lower]));
-//#endregion
-exports.HttpMethods = HttpMethods;
 exports.adapterOas = adapterOas;
 exports.adapterOasName = adapterOasName;
-exports.mergeDocuments = mergeDocuments;
 
 //# sourceMappingURL=index.cjs.map