@lovrozagar/honey 0.6.5 → 0.7.0

package/src/codegen.ts

@@ -1,14 +1,32 @@
 import { InternPool } from "./codegen-route-tree-intern.ts"
-import { deriveErrorEnvelopeName, deriveSchemaName, isErrorEnvelope, shortHash } from "./codegen-schema-naming.ts"
+import {
+	deriveErrorEnvelopeName,
+	deriveSchemaName,
+	isErrorEnvelope,
+	sanitizeComponentName,
+	shortHash,
+} from "./codegen-schema-naming.ts"
 import type { SchemaNameContext } from "./codegen-schema-naming.ts"
 import { effectJsonSchemaFn, loadEffectJsonSchema, loadToJSONSchema, toJSONSchemaFn } from "./codegen-loaders.ts"
 import { sanitizeZodJsonSchema } from "./codegen-sanitize.ts"
-import { methodsOf, namespacesOf, schemaToIR, toIR } from "./codegen-ir.ts"
-import type { IRNamespace } from "./codegen-ir.ts"
+import {
+	bodiesOf,
+	irErrorEnvelope,
+	irResolver,
+	methodsOf,
+	namespacesOf,
+	openApiPathParams,
+	schemaToIR,
+	toIR,
+} from "./codegen-ir.ts"
+import type { IR, IRBody, IRNamespace, IROperation, IRSchema } from "./codegen-ir.ts"
+import { isJsonMedia, isTextMedia, mediaEssence } from "./codegen-sdk-model.ts"
 import type { HoneyError } from "./error.ts"
 import { ERROR_META } from "./errors.ts"
 import type { ErrorMetaEntry } from "./errors.ts"
 import type { InvalidateCheckConfig } from "./invalidate-check.ts"
+import { publishableMetaKeys } from "./meta-spec.ts"
+import { metaSpecOf } from "./meta-spec-merge.ts"
 import type { Honey } from "./index.ts"
 import {
 	generateOpenApiFromTree,
@@ -17,12 +35,16 @@ import {
 	type OpenApiSpec,
 } from "./openapi/document.ts"
 import { getJsonSchemaConverter, setJsonSchemaConverter } from "./openapi/json-schema-slot.ts"
-import type { RouteHandler, TreeNode } from "./tree.ts"
+import { collectRoutes, extractParams } from "./openapi/collect.ts"
+import { parsePattern, patternParams } from "./pattern.ts"
+import type { RouteHandler, RouteTree } from "./tree.ts"
+import { forEachLeaf, ROUTE_TREE_VERSION } from "./tree.ts"
 import { irToTs } from "./ts-type-emitter.ts"
-import { createTypeEmitState, emitSchemaType } from "./type-emitter.ts"
+import { createTypeEmitState, emitSchemaType, quoteKey } from "./type-emitter.ts"
 import type { TypeEmitState } from "./type-emitter.ts"
-import type { InputSchemaEntry, InputSchemasDef, OutputSchemaDef, StandardSchemaLike } from "./types.ts"
+import type { InputSchemaEntry, InputSchemasDef, MetaSpecConfig, OutputSchemaDef, StandardSchemaLike } from "./types.ts"
 import { EMPTY_OBJ, statusKeyToCode } from "./types.ts"
+import { CROSS_ORIGIN_SAFE_HEADERS } from "./client/redirect-policy.ts"
 
 export { prepareCodegen } from "./codegen-loaders.ts"
 export type { InvalidateCheckConfig, InvalidateCheckLevel } from "./invalidate-check.ts"
@@ -57,21 +79,80 @@ const ERROR_EXPORT_NAMES: ReadonlyArray<string> = [
 
 type ValibotSchema = Record<string, unknown> & { type: string }
 
-function valibotToJsonSchema(schema: unknown): unknown {
+/** Wrappers that make an object entry optional. */
+const VALIBOT_OPTIONAL = new Set(["exact_optional", "nullish", "optional", "undefinedable"])
+
+/** Pipe actions with a JSON Schema equivalent. Anything else constrains nothing in the document. */
+function applyValibotPipe(schema: ValibotSchema, json: Record<string, unknown>): Record<string, unknown> {
+	const pipe = schema.pipe as Array<Record<string, unknown>> | undefined
+	if (!Array.isArray(pipe)) return json
+	const formats: Record<string, string> = {
+		email: "email",
+		ipv4: "ipv4",
+		ipv6: "ipv6",
+		iso_date: "date",
+		iso_date_time: "date-time",
+		iso_timestamp: "date-time",
+		url: "uri",
+		uuid: "uuid",
+	}
+	for (const action of pipe.slice(1)) {
+		const type = action.type as string
+		const req = action.requirement
+		if (type in formats) json.format = formats[type]
+		else if (type === "integer") json.type = "integer"
+		else if (type === "regex" && req instanceof RegExp) json.pattern = req.source
+		else if (type === "min_length" && typeof req === "number")
+			json[json.type === "array" ? "minItems" : "minLength"] = req
+		else if (type === "max_length" && typeof req === "number")
+			json[json.type === "array" ? "maxItems" : "maxLength"] = req
+		else if (type === "length" && typeof req === "number") {
+			json[json.type === "array" ? "minItems" : "minLength"] = req
+			json[json.type === "array" ? "maxItems" : "maxLength"] = req
+		} else if (type === "min_value" && typeof req === "number") json.minimum = req
+		else if (type === "max_value" && typeof req === "number") json.maximum = req
+		else if (type === "description" && typeof action.description === "string") json.description = action.description
+	}
+	return json
+}
+
+function valibotObject(s: ValibotSchema, depth: number): Record<string, unknown> {
+	const entries = s.entries as Record<string, ValibotSchema>
+	if (Object.keys(entries).length === 0 && s.type === "object") return { type: "object" }
+	const properties: Record<string, unknown> = {}
+	const required: string[] = []
+	for (const k of Object.keys(entries)) {
+		const entry = entries[k]
+		properties[k] = valibotToJsonSchema(entry, depth + 1)
+		if (!VALIBOT_OPTIONAL.has(entry.type)) required.push(k)
+	}
+	const result: Record<string, unknown> = { properties, type: "object" }
+	if (required.length > 0) result.required = required
+	if (s.type === "strict_object") result.additionalProperties = false
+	else if (s.type === "object_with_rest") result.additionalProperties = valibotToJsonSchema(s.rest, depth + 1)
+	return result
+}
+
+function valibotToJsonSchema(schema: unknown, depth = 0): unknown {
+	/* a lazy schema can recurse without end; past this depth the node is unconstrained */
+	if (depth > 32) return {}
 	const s = schema as ValibotSchema
-	const t = s.type
+	const walk = (child: unknown): unknown => valibotToJsonSchema(child, depth + 1)
 
-	switch (t) {
+	switch (s.type) {
 		case "string":
-			return { type: "string" }
+			return applyValibotPipe(s, { type: "string" })
 		case "number":
-			return { type: "number" }
+			return applyValibotPipe(s, { type: "number" })
 		case "boolean":
 			return { type: "boolean" }
 		case "bigint":
-			return { type: "integer" }
+			return { format: "int64", type: "integer" }
 		case "date":
 			return { format: "date-time", type: "string" }
+		case "file":
+		case "blob":
+			return { contentEncoding: "binary", format: "binary", type: "string" }
 		case "undefined":
 		case "void":
 			return {}
@@ -80,69 +161,62 @@ function valibotToJsonSchema(schema: unknown): unknown {
 		case "any":
 		case "unknown":
 			return {}
-		case "literal": {
-			const val = s.literal
-			return { const: val }
-		}
-		case "object": {
-			const entries = s.entries as Record<string, unknown>
-			const keys = Object.keys(entries)
-			if (keys.length === 0) return { type: "object" }
-			const properties: Record<string, unknown> = {}
-			const required: string[] = []
-			for (const k of keys) {
-				const entry = entries[k] as ValibotSchema
-				if (entry.type === "optional") {
-					properties[k] = valibotToJsonSchema(entry.wrapped as unknown)
-				} else {
-					properties[k] = valibotToJsonSchema(entry)
-					required.push(k)
-				}
-			}
-			const result: Record<string, unknown> = { properties, type: "object" }
-			if (required.length > 0) result.required = required
-			return result
-		}
+		case "literal":
+			return { const: s.literal }
+		case "object":
+		case "strict_object":
+		case "loose_object":
+		case "object_with_rest":
+			return valibotObject(s, depth)
 		case "array":
-			return { items: valibotToJsonSchema(s.item as unknown), type: "array" }
+			return applyValibotPipe(s, { items: walk(s.item), type: "array" })
 		case "optional":
-			return valibotToJsonSchema(s.wrapped as unknown)
-		case "nullable": {
-			const inner = valibotToJsonSchema(s.wrapped as unknown) as Record<string, unknown>
-			return { anyOf: [inner, { type: "null" }] }
-		}
-		case "nullish": {
-			const inner = valibotToJsonSchema(s.wrapped as unknown) as Record<string, unknown>
-			return { anyOf: [inner, { type: "null" }] }
+		case "exact_optional":
+		case "undefinedable":
+		case "non_nullable":
+		case "non_nullish":
+		case "non_optional": {
+			const inner = walk(s.wrapped) as Record<string, unknown>
+			const fallback = s.default
+			return fallback === undefined || typeof fallback === "function" ? inner : { ...inner, default: fallback }
 		}
+		case "nullable":
+		case "nullish":
+			return { anyOf: [walk(s.wrapped), { type: "null" }] }
 		case "union":
-			return {
-				anyOf: (s.options as unknown[]).map((o) => valibotToJsonSchema(o)),
-			}
+		case "variant":
+			return { anyOf: (s.options as unknown[]).map(walk) }
 		case "intersect":
-			return {
-				allOf: (s.options as unknown[]).map((o) => valibotToJsonSchema(o)),
-			}
+			return { allOf: (s.options as unknown[]).map(walk) }
 		case "picklist":
 			return { enum: s.options }
 		case "enum": {
-			const enumObj = s.enum as Record<string, string>
-			return { enum: Object.values(enumObj) }
-		}
-		case "record": {
+			const enumObj = s.enum as Record<string, string | number>
+			/* a TS numeric enum carries reverse mappings — keep the values */
 			return {
-				additionalProperties: valibotToJsonSchema(s.value as unknown),
-				type: "object",
+				enum: Object.keys(enumObj)
+					.filter((k) => typeof enumObj[enumObj[k] as string] !== "number")
+					.map((k) => enumObj[k]),
 			}
 		}
-		case "tuple": {
-			const items = (s.items as unknown[]).map((i) => valibotToJsonSchema(i))
-			return {
-				items,
-				maxItems: items.length,
-				minItems: items.length,
-				type: "array",
+		case "record":
+			return { additionalProperties: walk(s.value), type: "object" }
+		case "tuple":
+		case "strict_tuple":
+		case "loose_tuple":
+		case "tuple_with_rest": {
+			const items = (s.items as unknown[]).map(walk)
+			const result: Record<string, unknown> = { minItems: items.length, prefixItems: items, type: "array" }
+			if (s.type === "tuple_with_rest") result.items = walk(s.rest)
+			else if (s.type !== "loose_tuple") {
+				result.items = false
+				result.maxItems = items.length
 			}
+			return result
+		}
+		case "lazy": {
+			const getter = s.getter as ((input: unknown) => unknown) | undefined
+			return typeof getter === "function" ? walk(getter(undefined)) : {}
 		}
 		default:
 			return {}
@@ -222,9 +296,10 @@ function yupDescBase(desc: YupJsonDesc): unknown {
 			if (!Array.isArray(desc.innerType)) return { type: "array" }
 			const items = desc.innerType.map((i) => yupDescToJsonSchema(i))
 			return {
-				items,
+				items: false,
 				maxItems: items.length,
 				minItems: items.length,
+				prefixItems: items,
 				type: "array",
 			}
 		}
@@ -272,16 +347,6 @@ type RouteManifest = {
 	routes: RouteManifestEntry[]
 }
 
-function extractParams(path: string): string[] {
-	const params: string[] = []
-	for (const seg of path.split("/")) {
-		if (seg.startsWith(":")) {
-			params.push(seg.endsWith("?") ? seg.slice(1, -1) : seg.slice(1))
-		}
-	}
-	return params
-}
-
 type CollectedRoute = {
 	handler: RouteHandler
 	method: string
@@ -292,30 +357,6 @@ function isMetaInternal(handler: RouteHandler): boolean {
 	return (handler.mt as { internal?: boolean } | null)?.internal === true
 }
 
-function walkTree(node: TreeNode, currentPath: string, routes: CollectedRoute[], includeSkipped?: boolean): void {
-	if (node.m !== null) {
-		for (const [method, handler] of Object.entries(node.m)) {
-			if (handler._skip && !includeSkipped) continue
-			routes.push({ handler, method, path: currentPath || "/" })
-		}
-	}
-
-	for (const [seg, child] of Object.entries(node.s)) {
-		walkTree(child, `${currentPath}/${seg}`, routes, includeSkipped)
-	}
-
-	if (node.d !== null) {
-		walkTree(node.d.c, `${currentPath}/:${node.d.n}`, routes, includeSkipped)
-	}
-
-	if (node.w !== null) {
-		for (const [method, handler] of Object.entries(node.w.m)) {
-			if (handler._skip && !includeSkipped) continue
-			routes.push({ handler, method, path: `${currentPath}/*${node.w.n}` })
-		}
-	}
-}
-
 type ErrorInfo = { errorKey: string; status: number; statusKey: string }
 
 /* Longest suffix first so `*_not_found` wins over `*_found` (302). */
@@ -384,10 +425,18 @@ function introspectSchema(schema: StandardSchemaLike): unknown {
 
 export { normalizeSecurity } from "./meta-spec.ts"
 
+/** Locale-independent string order (UTF-16 code units), so output is the same on every machine. */
+export function compareCodeUnits(a: string, b: string): number {
+	if (a === b) return 0
+	return a < b ? -1 : 1
+}
+
 export function canonicalizeSchema(schema: Record<string, unknown>): string {
 	return JSON.stringify(schema, (_, value) => {
 		if (value && typeof value === "object" && !Array.isArray(value)) {
-			return Object.fromEntries(Object.entries(value as Record<string, unknown>).sort(([a], [b]) => a.localeCompare(b)))
+			return Object.fromEntries(
+				Object.entries(value as Record<string, unknown>).sort(([a], [b]) => compareCodeUnits(a, b)),
+			)
 		}
 		return value
 	})
@@ -395,6 +444,7 @@ export function canonicalizeSchema(schema: Record<string, unknown>): string {
 
 type SchemaSlot = {
 	canonical: string
+	contentType: string
 	context: SchemaNameContext
 	/* path key from the spec — used for context-based ref rewriting */
 	pathKey: string
@@ -408,6 +458,16 @@ function isObjectSchema(schema: unknown): schema is Record<string, unknown> {
 	return s.type === "object" || (typeof s.properties === "object" && s.properties !== null)
 }
 
+/**
+ * A response key as a number: `"200"` → 200, `"default"` → 0, `"4XX"` → 400. Never `NaN`, which
+ * would name a schema `…ResponseNaN` and make every `default` response collide.
+ */
+function statusNumber(key: string): number {
+	if (/^[1-5][0-9][0-9]$/.test(key)) return Number(key)
+	if (/^[1-5]XX$/i.test(key)) return Number(key[0]) * 100
+	return 0
+}
+
 function collectSchemaSlots(paths: Record<string, Record<string, Record<string, unknown>>>): SchemaSlot[] {
 	const slots: SchemaSlot[] = []
 
@@ -420,11 +480,11 @@ function collectSchemaSlots(paths: Record<string, Record<string, Record<string,
 			if (requestBody) {
 				const content = requestBody.content as Record<string, Record<string, unknown>> | undefined
 				if (content) {
-					for (const mediaType of Object.values(content)) {
+					for (const [contentType, mediaType] of Object.entries(content)) {
 						const schema = mediaType.schema as Record<string, unknown> | undefined
 						if (schema && !schema.$ref) {
 							const context: SchemaNameContext = { method: m, path: pathKey, role: "request" }
-							slots.push({ canonical: canonicalizeSchema(schema), context, pathKey, schema })
+							slots.push({ canonical: canonicalizeSchema(schema), contentType, context, pathKey, schema })
 						}
 					}
 				}
@@ -437,17 +497,17 @@ function collectSchemaSlots(paths: Record<string, Record<string, Record<string,
 						| Record<string, Record<string, unknown>>
 						| undefined
 					if (content) {
-						for (const mediaType of Object.values(content)) {
+						for (const [contentType, mediaType] of Object.entries(content)) {
 							const schema = mediaType.schema as Record<string, unknown> | undefined
 							if (schema && !schema.$ref) {
-								const statusNum = Number(status)
+								const statusNum = statusNumber(status)
 								const context: SchemaNameContext = {
 									method: m,
 									path: pathKey,
 									role: "response",
 									status: statusNum,
 								}
-								slots.push({ canonical: canonicalizeSchema(schema), context, pathKey, schema })
+								slots.push({ canonical: canonicalizeSchema(schema), contentType, context, pathKey, schema })
 							}
 						}
 					}
@@ -473,6 +533,20 @@ type HoistedResult = {
 	schemas: Record<string, Record<string, unknown>>
 }
 
+/**
+ * A component name nobody holds yet. A clash gets the content hash, and a clash on the
+ * hashed name (24 bits collide) a counter — a name is never handed out twice.
+ */
+function uniqueName(base: string, canonical: string, taken: (name: string) => boolean): string {
+	if (!taken(base)) return base
+	const hashed = `${base}_${shortHash(canonical)}`
+	if (!taken(hashed)) return hashed
+	for (let n = 2; ; n++) {
+		const candidate = `${hashed}_${n}`
+		if (!taken(candidate)) return candidate
+	}
+}
+
 function walkNestedObjects(
 	schema: Record<string, unknown>,
 	slotName: string,
@@ -482,7 +556,8 @@ function walkNestedObjects(
 ): void {
 	const props = schema.properties as Record<string, unknown> | undefined
 	if (!props) return
-	for (const [key, val] of Object.entries(props)) {
+	for (const key of Object.keys(props)) {
+		const val = props[key]
 		if (!isObjectSchema(val)) continue
 		const child = val as Record<string, unknown>
 		const childPath = [...fieldPath, key]
@@ -505,7 +580,7 @@ function walkNestedObjects(
 function collectHoistedSchemas(
 	slots: SchemaSlot[],
 	slotNames: Map<SchemaSlot, string>,
-	reservedNames: Set<string>,
+	taken: (name: string) => boolean,
 ): HoistedResult {
 	const nestedMap = new Map<string, NestedEntry>()
 	for (const slot of slots) {
@@ -529,19 +604,25 @@ function collectHoistedSchemas(
 		const owner = entry.samples.slice().sort((a, b) => {
 			const na = a.slotName + a.fieldPath.join("")
 			const nb = b.slotName + b.fieldPath.join("")
-			return na.localeCompare(nb)
+			return compareCodeUnits(na, nb)
 		})[0]
 
-		const fieldPart = owner.fieldPath.map((f) => f.charAt(0).toUpperCase() + f.slice(1)).join("")
-		let name = `${owner.slotName}${fieldPart}`
-		if (reservedNames.has(name)) name = `${name}_${shortHash(canonical)}`
-		if (schemas[name]) continue
-
+		const fieldPart = owner.fieldPath
+			.map((f) => sanitizeComponentName(f))
+			.map((f) => f.charAt(0).toUpperCase() + f.slice(1))
+			.join("")
+		const name = uniqueName(
+			sanitizeComponentName(`${owner.slotName}${fieldPart}`),
+			canonical,
+			(n) => taken(n) || Object.hasOwn(schemas, n),
+		)
 		schemas[name] = entry.schema
 		canonicalToName.set(canonical, name)
-		reservedNames.add(name)
 	}
 
+	/* nested hoists inside a hoisted schema point at their component too */
+	for (const name of Object.keys(schemas)) schemas[name] = rewriteNestedRefs(schemas[name], canonicalToName)
+
 	return { canonicalToName, schemas }
 }
 
@@ -549,7 +630,8 @@ function collectHoistedSchemas(
  * Builds a new paths object by shallow-copying only the containers that need schema
  * replacement. Avoids structuredClone (which fails on arktype schemas containing
  * native functions). Original schema objects are dropped; only $ref objects are new.
- * Also rewrites nested inline object properties that were hoisted (canonicalToName).
+ * Also rewrites nested inline object properties that were hoisted (canonicalToName),
+ * at any depth — a hoisted name nothing points at would be an orphan component.
  */
 
 function rewriteNestedRefs(
@@ -559,40 +641,72 @@ function rewriteNestedRefs(
 	const props = schema.properties as Record<string, unknown> | undefined
 	if (!props) return schema
 	let newProps: Record<string, unknown> | undefined
-	for (const [key, val] of Object.entries(props)) {
+	for (const key of Object.keys(props)) {
+		const val = props[key]
 		if (!isObjectSchema(val)) continue
 		const child = val as Record<string, unknown>
 		const name = canonicalToName.get(canonicalizeSchema(child))
-		if (!name) continue
+		const next = name ? { $ref: `#/components/schemas/${name}` } : rewriteNestedRefs(child, canonicalToName)
+		if (next === child) continue
 		if (!newProps) newProps = { ...props }
-		newProps[key] = { $ref: `#/components/schemas/${name}` }
+		newProps[key] = next
 	}
 	if (!newProps) return schema
 	return { ...schema, properties: newProps }
 }
 
+function slotKey(
+	pathKey: string,
+	method: string,
+	role: string,
+	status: number | undefined,
+	contentType: string,
+): string {
+	return `${pathKey}::${method}::${role}::${status ?? ""}::${contentType}`
+}
+
 function rewritePathsToRefs(
 	paths: Record<string, Record<string, Record<string, unknown>>>,
 	slots: SchemaSlot[],
 	slotNames: Map<SchemaSlot, string>,
 	hoistedCanonicalToName: Map<string, string>,
 ): Record<string, Record<string, Record<string, unknown>>> {
-	const ctxKey = (pathKey: string, method: string, role: string, status?: number): string =>
-		`${pathKey}::${method}::${role}::${status ?? ""}`
-
+	/* keyed by operation + status + content type: JSON and XML bodies of one status are two slots */
 	const lookup = new Map<string, string>()
 	for (const slot of slots) {
 		const name = slotNames.get(slot)
-		if (name)
-			lookup.set(
-				ctxKey(
-					slot.pathKey,
-					slot.context.method,
-					slot.context.role,
-					slot.context.role === "response" ? slot.context.status : undefined,
-				),
-				name,
-			)
+		if (!name) continue
+		const status = slot.context.role === "response" ? slot.context.status : undefined
+		lookup.set(slotKey(slot.pathKey, slot.context.method, slot.context.role, status, slot.contentType), name)
+	}
+
+	const rewriteContent = (
+		content: Record<string, Record<string, unknown>>,
+		keyFor: (ct: string) => string,
+	): Record<string, Record<string, unknown>> | null => {
+		const newContent: Record<string, Record<string, unknown>> = {}
+		let changed = false
+		for (const [ct, mediaType] of Object.entries(content)) {
+			const schema = mediaType.schema as Record<string, unknown> | undefined
+			if (!schema || schema.$ref) {
+				newContent[ct] = mediaType
+				continue
+			}
+			const name = lookup.get(keyFor(ct))
+			if (name) {
+				newContent[ct] = { ...mediaType, schema: { $ref: `#/components/schemas/${name}` } }
+				changed = true
+				continue
+			}
+			const rewritten = hoistedCanonicalToName.size > 0 ? rewriteNestedRefs(schema, hoistedCanonicalToName) : schema
+			if (rewritten !== schema) {
+				newContent[ct] = { ...mediaType, schema: rewritten }
+				changed = true
+			} else {
+				newContent[ct] = mediaType
+			}
+		}
+		return changed ? newContent : null
 	}
 
 	const newPaths: Record<string, Record<string, Record<string, unknown>>> = {}
@@ -606,76 +720,23 @@ function rewritePathsToRefs(
 			let newOp = op
 
 			const requestBody = op.requestBody as Record<string, unknown> | undefined
-			if (requestBody) {
-				const content = requestBody.content as Record<string, Record<string, unknown>> | undefined
-				if (content) {
-					const reqName = lookup.get(ctxKey(pathKey, m, "request"))
-					const newContent: Record<string, Record<string, unknown>> = {}
-					for (const [ct, mediaType] of Object.entries(content)) {
-						const schema = mediaType.schema as Record<string, unknown> | undefined
-						if (schema && !schema.$ref) {
-							if (reqName) {
-								newContent[ct] = {
-									...mediaType,
-									schema: { $ref: `#/components/schemas/${reqName}` },
-								}
-							} else if (hoistedCanonicalToName.size > 0) {
-								newContent[ct] = {
-									...mediaType,
-									schema: rewriteNestedRefs(schema, hoistedCanonicalToName),
-								}
-							} else {
-								newContent[ct] = mediaType
-							}
-						} else {
-							newContent[ct] = mediaType
-						}
-					}
-					if (Object.keys(newContent).length > 0) {
-						newOp = { ...op, requestBody: { ...requestBody, content: newContent } }
-					}
-				}
+			const reqContent = requestBody?.content as Record<string, Record<string, unknown>> | undefined
+			if (requestBody && reqContent) {
+				const next = rewriteContent(reqContent, (ct) => slotKey(pathKey, m, "request", undefined, ct))
+				if (next) newOp = { ...op, requestBody: { ...requestBody, content: next } }
 			}
 
-			const responses = (newOp as Record<string, unknown>).responses as
-				| Record<string, Record<string, unknown>>
-				| undefined
+			const responses = newOp.responses as Record<string, Record<string, unknown>> | undefined
 			if (responses) {
 				let newResponses: Record<string, Record<string, unknown>> | undefined
 				for (const [status, response] of Object.entries(responses)) {
-					const content = (response as Record<string, unknown>).content as
-						| Record<string, Record<string, unknown>>
-						| undefined
+					const content = response.content as Record<string, Record<string, unknown>> | undefined
 					if (!content) continue
-					const statusNum = Number(status)
-					const respName = lookup.get(ctxKey(pathKey, m, "response", statusNum))
-					const newContent: Record<string, Record<string, unknown>> = {}
-					let changed = false
-					for (const [ct, mediaType] of Object.entries(content)) {
-						const schema = mediaType.schema as Record<string, unknown> | undefined
-						if (schema && !schema.$ref) {
-							if (respName) {
-								newContent[ct] = {
-									...mediaType,
-									schema: { $ref: `#/components/schemas/${respName}` },
-								}
-								changed = true
-							} else if (hoistedCanonicalToName.size > 0) {
-								const rewritten = rewriteNestedRefs(schema, hoistedCanonicalToName)
-								newContent[ct] = { ...mediaType, schema: rewritten }
-								if (rewritten !== schema) changed = true
-								else newContent[ct] = mediaType
-							} else {
-								newContent[ct] = mediaType
-							}
-						} else {
-							newContent[ct] = mediaType
-						}
-					}
-					if (changed) {
-						if (!newResponses) newResponses = { ...responses }
-						newResponses[status] = { ...(response as Record<string, unknown>), content: newContent }
-					}
+					const statusNum = statusNumber(status)
+					const next = rewriteContent(content, (ct) => slotKey(pathKey, m, "response", statusNum, ct))
+					if (!next) continue
+					if (!newResponses) newResponses = { ...responses }
+					newResponses[status] = { ...response, content: next }
 				}
 				if (newResponses) newOp = { ...newOp, responses: newResponses }
 			}
@@ -689,18 +750,35 @@ function rewritePathsToRefs(
 	return newPaths
 }
 
+/** Every `#/components/schemas/<name>` a value refers to. */
+function collectComponentRefs(value: unknown, out: Set<string>): void {
+	if (Array.isArray(value)) {
+		for (const item of value) collectComponentRefs(item, out)
+		return
+	}
+	if (value === null || typeof value !== "object") return
+	for (const [key, child] of Object.entries(value)) {
+		if (key === "$ref" && typeof child === "string" && child.startsWith("#/components/schemas/")) {
+			out.add(child.slice("#/components/schemas/".length))
+		} else {
+			collectComponentRefs(child, out)
+		}
+	}
+}
+
 export function deduplicateSchemas(spec: OpenApiSpec): OpenApiSpec {
 	/* Sort paths lexicographically for determinism — input order must not affect output. */
 	const sortedPaths: Record<string, Record<string, Record<string, unknown>>> = {}
 	for (const key of Object.keys(spec.paths).sort()) sortedPaths[key] = spec.paths[key]
 
 	const slots = collectSchemaSlots(sortedPaths)
+	const existing = spec.components?.schemas ?? {}
 
 	/* Group slots by canonical shape — same shape = one component. */
 	const groups = new Map<string, SchemaSlot[]>()
 	for (const slot of slots) {
-		const existing = groups.get(slot.canonical)
-		if (existing) existing.push(slot)
+		const group = groups.get(slot.canonical)
+		if (group) group.push(slot)
 		else groups.set(slot.canonical, [slot])
 	}
 
@@ -709,29 +787,28 @@ export function deduplicateSchemas(spec: OpenApiSpec): OpenApiSpec {
 	 *   Tier 1: unique shape (group.length === 1) → operation-derived name
 	 *   Tier 2: shared error envelope → Err{status}* name
 	 *   Tier 3: shared non-error → first-slot operation-derived name
-	 * Collision (two canonicals → same tier name) → hash suffix on second.
+	 * Collision (two canonicals → same tier name, or a name an existing component holds) →
+	 * hash suffix, re-checked until free.
 	 */
 	const canonicalToName = new Map<string, string>()
 	const nameToCanonical = new Map<string, string>()
 
 	for (const [canonical, groupSlots] of groups) {
 		const firstSlot = groupSlots[0]
-		let name: string
+		let base: string
 
-		if (groupSlots.length === 1) {
-			name = deriveSchemaName(firstSlot.context)
-		} else if (isErrorEnvelope(firstSlot.schema)) {
+		if (groupSlots.length > 1 && isErrorEnvelope(firstSlot.schema)) {
 			const fallbackStatus = firstSlot.context.role === "response" ? firstSlot.context.status : undefined
-			name = deriveErrorEnvelopeName(firstSlot.schema, fallbackStatus)
+			base = deriveErrorEnvelopeName(firstSlot.schema, fallbackStatus)
 		} else {
-			name = deriveSchemaName(firstSlot.context)
+			base = deriveSchemaName(firstSlot.context)
 		}
 
-		/* Collision: different canonical claims same name → suffix second with hash. */
-		const claimed = nameToCanonical.get(name)
-		if (claimed !== undefined && claimed !== canonical) {
-			name = `${name}_${shortHash(canonical)}`
-		}
+		const name = uniqueName(
+			base,
+			canonical,
+			(n) => Object.hasOwn(existing, n) || (nameToCanonical.has(n) && nameToCanonical.get(n) !== canonical),
+		)
 		nameToCanonical.set(name, canonical)
 		canonicalToName.set(canonical, name)
 	}
@@ -746,27 +823,23 @@ export function deduplicateSchemas(spec: OpenApiSpec): OpenApiSpec {
 	/* Nested hoisting: collect shared nested objects, then rewrite inline → $ref.
 	 * Error envelope slots (any tier) mark their nested schemas as envelope-owned so
 	 * envelope-exclusive nesting (e.g. `fields`) is not hoisted under a per-spec name. */
-	const allTopLevelNames = new Set(slotNames.values())
 	const { schemas: hoistedSchemas, canonicalToName: hoistedCanonicalToName } = collectHoistedSchemas(
 		slots,
 		slotNames,
-		allTopLevelNames,
+		(n) => Object.hasOwn(existing, n) || nameToCanonical.has(n),
 	)
 
 	/* Build components map, rewriting nested fields → $refs where hoisted */
 	const extractedSchemas: Record<string, Record<string, unknown>> = {}
-	const seenNames = new Set<string>()
 	for (const slot of slots) {
 		const name = slotNames.get(slot)
-		if (name && !seenNames.has(name)) {
-			seenNames.add(name)
+		if (name && !Object.hasOwn(extractedSchemas, name)) {
 			extractedSchemas[name] =
 				hoistedCanonicalToName.size > 0 ? rewriteNestedRefs(slot.schema, hoistedCanonicalToName) : slot.schema
 		}
 	}
-	Object.assign(extractedSchemas, hoistedSchemas)
 
-	const hasNewSchemas = Object.keys(extractedSchemas).length > 0
+	const hasNewSchemas = Object.keys(extractedSchemas).length > 0 || Object.keys(hoistedSchemas).length > 0
 	/* Nothing to extract and no existing components — return unchanged */
 	if (!hasNewSchemas && !spec.components) return spec
 
@@ -775,7 +848,17 @@ export function deduplicateSchemas(spec: OpenApiSpec): OpenApiSpec {
 			? rewritePathsToRefs(sortedPaths, slots, slotNames, hoistedCanonicalToName)
 			: sortedPaths
 
-	const mergedSchemas = { ...spec.components?.schemas, ...extractedSchemas }
+	const mergedSchemas: Record<string, Record<string, unknown>> = { ...existing, ...extractedSchemas }
+
+	/* a hoisted nested schema whose every user became a component $ref is still referenced from
+	   that component; one referenced from nowhere is dropped */
+	const referenced = new Set<string>()
+	collectComponentRefs(paths, referenced)
+	collectComponentRefs(mergedSchemas, referenced)
+	for (const [name, schema] of Object.entries(hoistedSchemas)) {
+		if (referenced.has(name)) mergedSchemas[name] = schema
+	}
+
 	const components: OpenApiSpec["components"] = {
 		...spec.components,
 		...(Object.keys(mergedSchemas).length > 0 ? { schemas: mergedSchemas } : {}),
@@ -834,35 +917,53 @@ function cloneJson<T>(value: T): T {
 	}
 }
 
+/* Inlining expands each $ref; a graph of shared refs can grow exponentially (`L30` with two
+   fields that both point at `L29`, …), so the output is bounded and generation fails loudly. */
+const MAX_INLINED_SCHEMA_NODES = 200_000
+
+type InlineBudget = { nodes: number }
+
+function chargeInline(budget: InlineBudget): void {
+	if (++budget.nodes > MAX_INLINED_SCHEMA_NODES) {
+		throw new Error(
+			`SDK codegen: inlined schemas exceed ${MAX_INLINED_SCHEMA_NODES} nodes (deeply shared $refs); ` +
+				"flatten the shared component chain",
+		)
+	}
+}
+
 function resolveSchema(
 	schema: Record<string, unknown>,
 	schemas: Record<string, Record<string, unknown>>,
+	budget: InlineBudget,
 	visited = new Set<string>(),
 ): Record<string, unknown> {
 	if (typeof schema.$ref === "string" && schema.$ref.startsWith("#/components/schemas/")) {
 		const name = schema.$ref.slice("#/components/schemas/".length)
 		/* circular ref guard — return empty schema which maps to unknown in IR */
 		if (visited.has(name)) return {}
-		const resolved = schemas[name]
+		const resolved = Object.hasOwn(schemas, name) ? schemas[name] : undefined
 		if (!resolved) throw new Error(`$ref points to nonexistent component: ${schema.$ref}`)
 		const next = new Set(visited)
 		next.add(name)
-		return resolveSchemaDeep(cloneJson(resolved), schemas, next)
+		return resolveSchemaDeep(cloneJson(resolved), schemas, budget, next)
 	}
-	return resolveSchemaDeep(schema, schemas, visited)
+	return resolveSchemaDeep(schema, schemas, budget, visited)
 }
 
 function resolveSchemaDeep(
 	schema: Record<string, unknown>,
 	schemas: Record<string, Record<string, unknown>>,
+	budget: InlineBudget,
 	visited: Set<string>,
 ): Record<string, unknown> {
+	chargeInline(budget)
 	for (const key of ["oneOf", "anyOf", "allOf"] as const) {
 		const arr = schema[key]
 		if (Array.isArray(arr)) {
 			schema[key] = arr.map((item: unknown) => {
 				if (item && typeof item === "object" && !Array.isArray(item)) {
-					return resolveSchema(item as Record<string, unknown>, schemas, visited)
+					return resolveSchema(item as Record<string, unknown>, schemas, budget, visited)
 				}
 				return item
 			})
@@ -870,14 +971,14 @@ function resolveSchemaDeep(
 	}
 	/* resolve array items */
 	if (schema.items && typeof schema.items === "object" && !Array.isArray(schema.items)) {
-		schema.items = resolveSchema(schema.items as Record<string, unknown>, schemas, visited)
+		schema.items = resolveSchema(schema.items as Record<string, unknown>, schemas, budget, visited)
 	}
 	/* resolve object properties */
 	if (schema.properties && typeof schema.properties === "object") {
 		const props = schema.properties as Record<string, unknown>
 		for (const [k, v] of Object.entries(props)) {
 			if (v && typeof v === "object" && !Array.isArray(v)) {
-				props[k] = resolveSchema(v as Record<string, unknown>, schemas, visited)
+				props[k] = resolveSchema(v as Record<string, unknown>, schemas, budget, visited)
 			}
 		}
 	}
@@ -890,6 +991,7 @@ function resolveSchemaDeep(
 		schema.additionalProperties = resolveSchema(
 			schema.additionalProperties as Record<string, unknown>,
 			schemas,
+			budget,
 			visited,
 		)
 	}
@@ -901,6 +1003,7 @@ export function resolveRefs(spec: OpenApiSpecInput): OpenApiSpecInput {
 	if (!schemas || Object.keys(schemas).length === 0) return spec
 
 	const paths = cloneJson(spec.paths)
+	const budget: InlineBudget = { nodes: 0 }
 
 	for (const methods of Object.values(paths)) {
 		for (const operation of Object.values(methods)) {
@@ -912,7 +1015,7 @@ export function resolveRefs(spec: OpenApiSpecInput): OpenApiSpecInput {
 				if (content) {
 					for (const [ct, mediaType] of Object.entries(content)) {
 						const schema = mediaType.schema as Record<string, unknown> | undefined
-						if (schema) content[ct] = { ...mediaType, schema: resolveSchema(schema, schemas) }
+						if (schema) content[ct] = { ...mediaType, schema: resolveSchema(schema, schemas, budget) }
 					}
 				}
 			}
@@ -921,20 +1024,14 @@ export function resolveRefs(spec: OpenApiSpecInput): OpenApiSpecInput {
 			if (responses) {
 				for (const [status, response] of Object.entries(responses)) {
 					const content = response.content as Record<string, Record<string, unknown>> | undefined
-					if (content) {
-						for (const [ct, mediaType] of Object.entries(content)) {
-							const schema = mediaType.schema as Record<string, unknown> | undefined
-							if (schema) {
-								responses[status] = {
-									...response,
-									content: {
-										...content,
-										[ct]: { ...mediaType, schema: resolveSchema(schema, schemas) },
-									},
-								}
-							}
-						}
+					if (!content) continue
+					/* every content type resolved, not only the last one written */
+					const resolved: Record<string, Record<string, unknown>> = {}
+					for (const [ct, mediaType] of Object.entries(content)) {
+						const schema = mediaType.schema as Record<string, unknown> | undefined
+						resolved[ct] = schema ? { ...mediaType, schema: resolveSchema(schema, schemas, budget) } : mediaType
 					}
+					responses[status] = { ...response, content: resolved }
 				}
 			}
 		}
@@ -946,25 +1043,60 @@ export function resolveRefs(spec: OpenApiSpecInput): OpenApiSpecInput {
 	return { ...spec, components, paths }
 }
 
+/**
+ * Zod node kinds JSON Schema has no word for. Zod emits `{}` for each of them under
+ * `unrepresentable: "any"`; the degrade is per node, and the rest of the schema survives.
+ */
+const ZOD_UNREPRESENTABLE = new Set(["custom", "function", "map", "nan", "promise", "set", "symbol", "transform"])
+
+type ZodOverrideCtx = { jsonSchema: Record<string, unknown>; zodSchema: unknown }
+
+/** `override` for Zod's converter: give `Date` and `BigInt` their wire shape, record what degraded. */
+function zodOverride(degraded: Set<string>): (ctx: ZodOverrideCtx) => void {
+	return (ctx) => {
+		const def = zodDefOf(ctx.zodSchema)
+		const kind = String(def?.type ?? "")
+		if (kind === "date") {
+			/* JSON.stringify writes a Date as an ISO string */
+			ctx.jsonSchema.format = "date-time"
+			ctx.jsonSchema.type = "string"
+			return
+		}
+		if (kind === "bigint") {
+			ctx.jsonSchema.format = "int64"
+			ctx.jsonSchema.type = "integer"
+			return
+		}
+		if (ZOD_UNREPRESENTABLE.has(kind) && Object.keys(ctx.jsonSchema).length === 0) degraded.add(kind)
+	}
+}
+
 /** Zod 4 puts converters on the schema instance. Use those first so Workers
  * (where `import("zod")` does not resolve) still emit real JSON Schema. */
 function zodInstanceToJsonSchema(
 	schema: StandardSchemaLike,
 	io: "input" | "output",
+	degraded: Set<string>,
 ): Record<string, unknown> | undefined {
+	const libraryOptions = { override: zodOverride(degraded), unrepresentable: "any" as const }
 	const jsonSchema = (
 		schema["~standard"] as {
-			jsonSchema?: { input?: () => unknown; output?: () => unknown }
+			jsonSchema?: Record<"input" | "output", ((params?: unknown) => unknown) | undefined>
 		}
 	).jsonSchema
 	const fromStandard = jsonSchema?.[io]
 	if (typeof fromStandard === "function") {
-		const result = fromStandard()
+		const result = fromStandard({ libraryOptions, target: "draft-2020-12" })
 		if (result && typeof result === "object") return result as Record<string, unknown>
 	}
-	const inst = (schema as { toJSONSchema?: (opts?: { io?: "input" | "output" }) => unknown }).toJSONSchema
+	const inst = (schema as { toJSONSchema?: (opts?: Record<string, unknown>) => unknown }).toJSONSchema
 	if (typeof inst === "function") {
-		const result = inst.call(schema, { io })
+		const result = inst.call(schema, { ...libraryOptions, io })
+		if (result && typeof result === "object") return result as Record<string, unknown>
+	}
+	if (toJSONSchemaFn) {
+		const convert = toJSONSchemaFn as (schema: unknown, opts: Record<string, unknown>) => unknown
+		const result = convert(schema, { ...libraryOptions, io })
 		if (result && typeof result === "object") return result as Record<string, unknown>
 	}
 	return undefined
@@ -997,32 +1129,47 @@ function zodDefOf(schema: unknown): Record<string, unknown> | undefined {
 	return s._def ?? s.def ?? s._zod?.def
 }
 
-function zodDefIsOptional(def: Record<string, unknown>): boolean {
+function zodDefIsOptional(def: Record<string, unknown>, io: "input" | "output"): boolean {
 	const t = String(def.typeName ?? def.type ?? "")
 	if (t === "ZodOptional" || t === "optional") return true
+	/* a default fills the value in: optional on the way in, always present on the way out */
+	if ((t === "ZodDefault" || t === "default" || t === "prefault") && io === "input") return true
 	if (
 		t === "ZodNullable" ||
 		t === "nullable" ||
 		t === "ZodDefault" ||
 		t === "default" ||
+		t === "prefault" ||
 		t === "ZodCatch" ||
-		t === "catch"
+		t === "catch" ||
+		t === "ZodReadonly" ||
+		t === "readonly"
 	) {
 		const inner = def.innerType
 		if (inner) {
 			const innerDef = zodDefOf(inner)
-			if (innerDef) return zodDefIsOptional(innerDef)
+			if (innerDef) return zodDefIsOptional(innerDef, io)
 		}
 	}
 	return false
 }
 
+function literalSchema(values: readonly unknown[]): Record<string, unknown> {
+	if (values.length === 1) return { const: values[0] }
+	return { enum: [...values] }
+}
+
 /** Walk Zod 3/4 internals. Survives Workers bundles that drop `toJSONSchema`. */
-function zodDefToJsonSchema(schema: unknown, depth = 0): Record<string, unknown> | undefined {
+function zodDefToJsonSchema(
+	schema: unknown,
+	io: "input" | "output" = "output",
+	depth = 0,
+): Record<string, unknown> | undefined {
 	if (depth > 24) return {}
 	const def = zodDefOf(schema)
 	if (!def) return undefined
 	const typeName = String(def.typeName ?? def.type ?? "")
+	const walk = (child: unknown): Record<string, unknown> => zodDefToJsonSchema(child, io, depth + 1) ?? {}
 
 	switch (typeName) {
 		case "ZodString":
@@ -1036,7 +1183,7 @@ function zodDefToJsonSchema(schema: unknown, depth = 0): Record<string, unknown>
 			return { type: "boolean" }
 		case "ZodBigInt":
 		case "bigint":
-			return { type: "integer" }
+			return { format: "int64", type: "integer" }
 		case "ZodDate":
 		case "date":
 			return { format: "date-time", type: "string" }
@@ -1058,14 +1205,25 @@ function zodDefToJsonSchema(schema: unknown, depth = 0): Record<string, unknown>
 			return {}
 		case "ZodLiteral":
 		case "literal": {
-			const val = def.value !== undefined ? def.value : (def.values as unknown[])?.[0]
-			return { const: val }
+			const values = Array.isArray(def.values) ? (def.values as unknown[]) : [def.value]
+			return literalSchema(values.map((v) => (typeof v === "bigint" ? Number(v) : v)))
 		}
 		case "ZodEnum":
 		case "enum": {
-			const vals = (def.values ?? def.entries) as unknown
-			const list = Array.isArray(vals) ? vals : Object.values(vals as Record<string, string>)
-			return { enum: list, type: "string" }
+			const raw = (def.values ?? def.entries) as unknown
+			let list: unknown[]
+			if (Array.isArray(raw)) list = raw
+			else {
+				/* a TS numeric enum carries reverse mappings: { A: 0, "0": "A" } — keep the values */
+				const entries = raw as Record<string, unknown>
+				list = Object.keys(entries)
+					.filter((k) => typeof entries[entries[k] as string] !== "number")
+					.map((k) => entries[k])
+			}
+			const types = new Set(list.map((v) => typeof v))
+			if (types.size === 1 && types.has("string")) return { enum: list, type: "string" }
+			if (types.size === 1 && types.has("number")) return { enum: list, type: "number" }
+			return { enum: list }
 		}
 		case "ZodObject":
 		case "object": {
@@ -1074,60 +1232,88 @@ function zodDefToJsonSchema(schema: unknown, depth = 0): Record<string, unknown>
 			if (!shape) return { type: "object" }
 			const properties: Record<string, unknown> = {}
 			const required: string[] = []
-			for (const [key, prop] of Object.entries(shape)) {
-				const converted = zodDefToJsonSchema(prop, depth + 1) ?? {}
-				properties[key] = converted
+			for (const key of Object.keys(shape)) {
+				const prop = shape[key]
+				properties[key] = walk(prop)
 				const propDef = zodDefOf(prop)
-				if (!propDef || !zodDefIsOptional(propDef)) required.push(key)
+				if (!propDef || !zodDefIsOptional(propDef, io)) required.push(key)
 			}
-			const result: Record<string, unknown> = { additionalProperties: false, properties, type: "object" }
+			const result: Record<string, unknown> = { properties, type: "object" }
+			if (io === "output") result.additionalProperties = false
 			if (required.length > 0) result.required = required
 			return result
 		}
 		case "ZodArray":
 		case "array":
-			return { items: zodDefToJsonSchema(def.element ?? def.type, depth + 1) ?? {}, type: "array" }
+			return { items: walk(def.element ?? def.type), type: "array" }
 		case "ZodOptional":
 		case "optional":
-			return zodDefToJsonSchema(def.innerType, depth + 1)
+			return zodDefToJsonSchema(def.innerType, io, depth + 1)
 		case "ZodNullable":
-		case "nullable": {
-			const inner = zodDefToJsonSchema(def.innerType, depth + 1) ?? {}
-			return { anyOf: [inner, { type: "null" }] }
-		}
+		case "nullable":
+			return { anyOf: [walk(def.innerType), { type: "null" }] }
 		case "ZodUnion":
 		case "ZodDiscriminatedUnion":
 		case "union":
-			return { anyOf: ((def.options as unknown[]) ?? []).map((o) => zodDefToJsonSchema(o, depth + 1) ?? {}) }
+			return { anyOf: ((def.options as unknown[]) ?? []).map(walk) }
+		case "ZodIntersection":
+		case "intersection":
+			return { allOf: [walk(def.left), walk(def.right)] }
 		case "ZodRecord":
 		case "record":
-			return {
-				additionalProperties: zodDefToJsonSchema(def.valueType, depth + 1) ?? {},
-				type: "object",
-			}
+			return { additionalProperties: walk(def.valueType), type: "object" }
 		case "ZodTuple":
-		case "tuple":
-			return {
-				items: ((def.items as unknown[]) ?? []).map((i) => zodDefToJsonSchema(i, depth + 1) ?? {}),
-				type: "array",
+		case "tuple": {
+			const items = ((def.items as unknown[]) ?? []).map(walk)
+			const out: Record<string, unknown> = { prefixItems: items, type: "array" }
+			if (def.rest) out.items = walk(def.rest)
+			else {
+				out.items = false
+				out.maxItems = items.length
 			}
+			out.minItems = items.length
+			return out
+		}
 		case "ZodDefault":
-		case "ZodCatch":
 		case "default":
+		case "prefault": {
+			const inner = walk(def.innerType)
+			const value = (def as { defaultValue?: unknown }).defaultValue
+			const resolved = typeof value === "function" ? undefined : value
+			return resolved === undefined ? inner : { ...inner, default: resolved }
+		}
+		case "ZodCatch":
 		case "catch":
 		case "ZodReadonly":
 		case "readonly":
-			return zodDefToJsonSchema(def.innerType, depth + 1)
+			return zodDefToJsonSchema(def.innerType, io, depth + 1)
 		case "ZodPipeline":
 		case "pipe":
-			return zodDefToJsonSchema(def.out, depth + 1)
+			/* a pipe validates `in` and returns `out` */
+			return zodDefToJsonSchema(io === "input" ? def.in : def.out, io, depth + 1)
 		case "ZodBranded":
-			return zodDefToJsonSchema(def.type, depth + 1)
+			return zodDefToJsonSchema(def.type, io, depth + 1)
+		case "ZodLazy":
+		case "lazy": {
+			const getter = def.getter as (() => unknown) | undefined
+			return typeof getter === "function" ? zodDefToJsonSchema(getter(), io, depth + 1) : {}
+		}
 		default:
 			return undefined
 	}
 }
 
+/** How a schema that cannot be converted at all is handled. Set per `generateOpenApi` call. */
+let schemaFailureMode: "throw" | "warn" = "throw"
+
+function schemaConversionFailed(what: string, io: "input" | "output", err: unknown): Record<string, unknown> {
+	const msg = err instanceof Error ? err.message : String(err)
+	const text = `[honey:codegen] schemaToJsonSchema could not convert ${what} (io=${io}): ${msg}`
+	if (schemaFailureMode === "throw") throw new Error(text)
+	console.warn(`${text}. Documented as an unconstrained schema.`)
+	return {}
+}
+
 function schemaToJsonSchema(schema: StandardSchemaLike, io: "input" | "output" = "output"): unknown {
 	/* Pre-serialized JSON-schema blob or non-schema value — no ~standard marker.
 	 * Arktype schemas are functions but still carry the marker, so pass those through too. */
@@ -1141,66 +1327,86 @@ function schemaToJsonSchema(schema: StandardSchemaLike, io: "input" | "output" =
 	const vendor = schema["~standard"].vendor
 
 	if (vendor === "zod") {
+		const kind = (schema as { _zod?: { def?: { type?: string } } })?._zod?.def?.type ?? "unknown"
+		const degraded = new Set<string>()
+		let result: Record<string, unknown> | undefined
 		try {
-			const result =
-				zodInstanceToJsonSchema(schema, io) ??
-				(toJSONSchemaFn?.(schema, { io }) as Record<string, unknown> | undefined) ??
-				zodDefToJsonSchema(schema)
-			if (result) {
-				return sanitizeZodJsonSchema(result)
-			}
+			result = zodInstanceToJsonSchema(schema, io, degraded) ?? zodDefToJsonSchema(schema, io)
 		} catch (err) {
-			const msg = err instanceof Error ? err.message : String(err)
-			const defType = (schema as { _zod?: { def?: { type?: string } } })?._zod?.def?.type ?? "unknown"
+			return schemaConversionFailed(`zod/${kind}`, io, err)
+		}
+		if (!result) return schemaConversionFailed(`zod/${kind}`, io, new Error("no converter available"))
+		if (degraded.size > 0) {
 			console.warn(
-				`[honey:codegen] schemaToJsonSchema failed for zod/${defType} (io=${io}): ${msg}. Falling back to metadata-only introspection.`,
+				`[honey:codegen] schemaToJsonSchema: zod/${kind} (io=${io}) has ${[...degraded].sort().join(", ")} ` +
+					"node(s) JSON Schema cannot express; each is documented as an unconstrained schema. " +
+					'Describe them with .meta({ ... }) or z.toJSONSchema\'s "override".',
 			)
 		}
+		return sanitizeZodJsonSchema(result)
 	}
 
-	if (vendor === "valibot") {
-		return valibotToJsonSchema(schema)
-	}
-
-	if (vendor === "arktype") {
-		return arkTypeToJsonSchema(schema)
-	}
-
-	if (vendor === "yup") {
-		return yupToJsonSchema(schema)
-	}
-
-	if (vendor === "effect") {
-		return effectToJsonSchema(schema)
+	try {
+		if (vendor === "valibot") return valibotToJsonSchema(schema)
+		if (vendor === "arktype") return arkTypeToJsonSchema(schema)
+		if (vendor === "yup") return yupToJsonSchema(schema)
+		if (vendor === "effect") return effectToJsonSchema(schema)
+	} catch (err) {
+		return schemaConversionFailed(vendor, io, err)
 	}
 
-	return introspectSchema(schema)
+	/* no converter for this vendor: say so once per schema, never emit the introspection object */
+	console.warn(
+		`[honey:codegen] schemaToJsonSchema: no JSON Schema converter for vendor "${vendor}"; ` +
+			"documented as an unconstrained schema.",
+	)
+	return {}
 }
 
 /* ---- Manifest generation ---- */
 
+export type GenerateManifestOptions = {
+	/** Drop routes the predicate rejects, as `openapi({ filterRoutes })` does. */
+	filterRoutes?: (route: OpenApiRouteInfo) => boolean
+	/**
+	 * `"all"` (default, the `honey generate` artifact): every route and meta key.
+	 * `"published"` (a served `/manifest.json`): the OpenAPI document's visibility policy —
+	 * `meta.internal` routes are left out, and meta carries only keys the app's `metaSpec`
+	 * maps (built-ins included) and does not hide.
+	 */
+	visibility?: "all" | "published"
+}
+
 export function generateManifest<TEnv, TCtx>(
 	app: Honey<TEnv, TCtx, unknown, unknown, unknown, string, string>,
+	options: GenerateManifestOptions = {},
 ): RouteManifest {
-	const tree = (app as unknown as { _tree: TreeNode })._tree
 	const factory = getErrorFactory(app)
-	const collected: CollectedRoute[] = []
-	walkTree(tree, "", collected)
+	const published = options.visibility === "published"
+	const publishable = published ? publishableMetaKeys(metaSpecOf(app)) : null
+	const collected: CollectedRoute[] = collectRoutes(app).filter(({ handler, method, path }) => {
+		if (published && isMetaInternal(handler)) return false
+		return !options.filterRoutes || options.filterRoutes({ meta: handler.mt ?? EMPTY_OBJ, method, path })
+	})
 
-	const allErrorKeys = new Set<string>()
+	/* each key resolved against the factory of a route that declares it — a mounted sub-app keeps its own */
+	const allErrorKeys = new Map<string, Record<string, () => HoneyError> | null>()
 
 	const routes: RouteManifestEntry[] = collected.map(({ handler, method, path }) => {
 		const entry: RouteManifestEntry = {
 			errors: Array.from(handler.ek),
-			meta: handler.mt ?? EMPTY_OBJ,
+			meta: publishable
+				? Object.fromEntries(Object.entries(handler.mt ?? EMPTY_OBJ).filter(([key]) => publishable(key)))
+				: (handler.mt ?? EMPTY_OBJ),
 			method,
 			middleware: handler.mw.map((mw) => mw.name || "anonymous"),
 			params: extractParams(path),
 			path,
 		}
 
+		const routeFactory = (handler.fac as Record<string, () => HoneyError> | null | undefined) ?? factory
 		for (const ek of handler.ek) {
-			allErrorKeys.add(ek)
+			if (!allErrorKeys.has(ek)) allErrorKeys.set(ek, routeFactory)
 		}
 
 		if (handler.iv) {
@@ -1235,7 +1441,7 @@ export function generateManifest<TEnv, TCtx>(
 	})
 
 	return {
-		errors: Array.from(allErrorKeys).map((key) => resolveErrorInfo(key, factory)),
+		errors: Array.from(allErrorKeys).map(([key, keyFactory]) => resolveErrorInfo(key, keyFactory)),
 		routes,
 	}
 }
@@ -1253,6 +1459,13 @@ export async function generateOpenApi<TEnv, TCtx, TMeta = unknown>(
 		 * nothing. `"off"` for a document served at runtime.
 		 */
 		invalidate?: InvalidateCheckConfig
+		/**
+		 * A schema that cannot be converted at all: `"throw"` (default, `honey generate`) fails
+		 * the build; `"warn"` (a served document) logs it and documents an unconstrained schema.
+		 * A single node JSON Schema cannot express (`z.date()`, `z.custom()`) never fails either
+		 * way — only that node degrades.
+		 */
+		onSchemaError?: "throw" | "warn"
 		/** Named metaSpec profile — selects which emitted keys this document carries */
 		profile?: string
 		securitySchemes?: Record<string, unknown>
@@ -1260,21 +1473,23 @@ export async function generateOpenApi<TEnv, TCtx, TMeta = unknown>(
 ): Promise<OpenApiSpec> {
 	await Promise.all([loadToJSONSchema(), loadEffectJsonSchema()])
 	const prev = getJsonSchemaConverter()
+	const prevMode = schemaFailureMode
+	schemaFailureMode = options.onSchemaError ?? "throw"
 	setJsonSchemaConverter((schema, io) => schemaToJsonSchema(schema, io) as Record<string, unknown>)
 	try {
-		const spec = generateOpenApiFromTree(app, options)
+		const { onSchemaError: _mode, ...rest } = options
+		const spec = generateOpenApiFromTree(app, rest)
 		return deduplicateSchemas(spec)
 	} finally {
 		setJsonSchemaConverter(prev)
+		schemaFailureMode = prevMode
 	}
 }
 
 export function extractSchemas<TEnv, TCtx>(
 	app: Honey<TEnv, TCtx, unknown, unknown, unknown, string, string>,
 ): Record<string, Record<string, unknown>> {
-	const tree = (app as unknown as { _tree: TreeNode })._tree
-	const collected: CollectedRoute[] = []
-	walkTree(tree, "", collected)
+	const collected: CollectedRoute[] = collectRoutes(app)
 
 	const result: Record<string, Record<string, unknown>> = {}
 
@@ -1311,213 +1526,72 @@ export function extractSchemas<TEnv, TCtx>(
 
 /* ---- Static route tree codegen ---- */
 
-type RouteConfig = {
-	boundaryErrorKey: string | null
-	errorKeys: string[]
-	/** JSON Schema per input source — { json?, form?, params?, search?, headers?, cookies? }; null = no input validation */
-	inputSchemas: Record<string, Record<string, unknown>> | null
-	meta: Record<string, unknown> | null
-	method: string
-	middlewareNames: string[]
-	/**
-	 * JSON Schema per (contentType, statusKey). Special case: `redirect` contentType holds
-	 * `Record<statusKey, true>` with no schema (declaration-only, no body to validate).
-	 * null = no output validation declared.
-	 */
-	outputSchemas: Record<string, Record<string, unknown>> | null
-	path: string
-}
-
-function serializeInputSchemas(iv: InputSchemasDef | null): Record<string, Record<string, unknown>> | null {
-	if (!iv) return null
-	const result: Record<string, Record<string, unknown>> = {}
-	for (const [source, entry] of Object.entries(iv)) {
-		if (entry === undefined) continue
-		const unwrapped = unwrapEntry(entry as InputSchemaEntry)
-		result[source] = schemaToJsonSchema(unwrapped, "input") as Record<string, unknown>
-	}
-	return Object.keys(result).length > 0 ? result : null
-}
-
-function serializeOutputSchemas(os: OutputSchemaDef | null): Record<string, Record<string, unknown>> | null {
-	if (!os) return null
-	const result: Record<string, Record<string, unknown>> = {}
-	for (const [contentType, schemas] of Object.entries(os)) {
-		if (schemas === undefined) continue
-		if (contentType === "redirect") {
-			/* redirect map is Record<statusKey, true> — copy as-is, no schema conversion */
-			result[contentType] = { ...(schemas as Record<string, true>) }
-			continue
-		}
-		const converted: Record<string, unknown> = {}
-		for (const [statusKey, schema] of Object.entries(schemas)) {
-			if (schema === undefined) continue
-			converted[statusKey] = schemaToJsonSchema(schema as StandardSchemaLike)
-		}
-		if (Object.keys(converted).length > 0) {
-			result[contentType] = converted
-		}
+/**
+ * Reject meta a generated file cannot reproduce. A route tree is JSON plus topology: a value
+ * JSON cannot round-trip (`Date`, `RegExp`, `NaN`, `BigInt`, class instances) would be
+ * emitted as something else, or interned together with a different value.
+ */
+function assertJsonValue(value: unknown, where: string, path: string): void {
+	const fail = (what: string): never => {
+		throw new Error(`${where}: ${path} is ${what} — route trees carry JSON values only`)
 	}
-	return Object.keys(result).length > 0 ? result : null
-}
-
-function buildRouteConfig(handler: RouteHandler, method: string, path: string): RouteConfig {
-	return {
-		boundaryErrorKey: handler.bek,
-		errorKeys: Array.from(handler.ek),
-		inputSchemas: serializeInputSchemas(handler.iv as InputSchemasDef | null),
-		meta: handler.mt,
-		method,
-		middlewareNames: handler.mw.map((mw) => mw.name || "anonymous"),
-		outputSchemas: serializeOutputSchemas(handler.os as OutputSchemaDef | null),
-		path,
+	if (value === null || typeof value === "string" || typeof value === "boolean") return
+	if (typeof value === "number") {
+		if (!Number.isFinite(value)) fail(String(value))
+		return
 	}
-}
-
-function collectRoutesForTree(node: TreeNode, currentPath: string, routes: RouteConfig[]): void {
-	if (node.m !== null) {
-		for (const [method, handler] of Object.entries(node.m)) {
-			routes.push(buildRouteConfig(handler, method, currentPath || "/"))
-		}
+	if (value === undefined) return
+	if (typeof value !== "object") fail(`a ${typeof value}`)
+	if (Array.isArray(value)) {
+		for (let k = 0; k < value.length; k++) assertJsonValue(value[k], where, `${path}[${k}]`)
+		return
 	}
-
-	for (const [seg, child] of Object.entries(node.s)) {
-		collectRoutesForTree(child, `${currentPath}/${seg}`, routes)
+	const proto = Object.getPrototypeOf(value) as unknown
+	if (proto !== Object.prototype && proto !== null) {
+		const name = (value as { constructor?: { name?: string } }).constructor?.name ?? "an object"
+		fail(`a ${name}`)
 	}
-
-	if (node.d !== null) {
-		collectRoutesForTree(node.d.c, `${currentPath}/:${node.d.n}`, routes)
+	for (const key of Object.keys(value as Record<string, unknown>)) {
+		assertJsonValue((value as Record<string, unknown>)[key], where, `${path}.${key}`)
 	}
+}
 
-	if (node.w !== null) {
-		for (const [method, handler] of Object.entries(node.w.m)) {
-			routes.push(buildRouteConfig(handler, method, `${currentPath}/*${node.w.n}`))
-		}
-	}
+/** Object-literal key that defines an own property even for `__proto__`. */
+function keyExpr(key: string): string {
+	return key === "__proto__" ? '["__proto__"]' : JSON.stringify(key)
 }
 
-type TreeBuild = {
-	children: Record<string, TreeBuild>
-	dynamic: { child: TreeBuild; name: string } | null
-	handlers: Array<{ handler: string; method: string }>
-	wildcard: {
-		handlers: Array<{ handler: string; method: string }>
-		name: string
-	} | null
+type TreeNodeLike = {
+	d: { c: TreeNodeLike; n: string } | null
+	m: Record<string, string> | null
+	s: Record<string, TreeNodeLike>
+	w: { m: Record<string, string>; n: string } | null
+	ws: string | null
 }
 
-function createTreeBuild(): TreeBuild {
-	return { children: {}, dynamic: null, handlers: [], wildcard: null }
+function methodMapExpr(m: Record<string, string>, intern: InternPool): string {
+	const parts = Object.keys(m).map((method) => `${keyExpr(method)}: ${intern.expr(m[method])}`)
+	return `S({ ${parts.join(", ")} })`
 }
 
-function serializeNode(node: TreeBuild): string {
-	const staticEntries = Object.entries(node.children)
+function serializeNode(node: TreeNodeLike, intern: InternPool): string {
+	const statics = Object.keys(node.s)
 	const sExpr =
-		staticEntries.length > 0
-			? `S({ ${staticEntries.map(([k, v]) => `${JSON.stringify(k)}: ${serializeNode(v)}`).join(", ")} })`
-			: "E"
-
-	const dExpr = node.dynamic
-		? `{ n: ${JSON.stringify(node.dynamic.name)}, c: ${serializeNode(node.dynamic.child)} }`
-		: "null"
-
-	const wExpr = node.wildcard
-		? `{ n: ${JSON.stringify(node.wildcard.name)}, m: { ${node.wildcard.handlers.map((h) => `${h.method}: ${h.handler}`).join(", ")} } }`
-		: "null"
-
-	const mExpr =
-		node.handlers.length > 0 ? `{ ${node.handlers.map((h) => `${h.method}: ${h.handler}`).join(", ")} }` : "null"
-
-	const args = [sExpr]
-	if (mExpr !== "null" || dExpr !== "null" || wExpr !== "null") {
-		args.push(mExpr)
-		if (dExpr !== "null" || wExpr !== "null") {
-			args.push(dExpr)
-			if (wExpr !== "null") args.push(wExpr)
-		}
-	}
+		statics.length > 0
+			? `S({ ${statics.map((k) => `${keyExpr(k)}: ${serializeNode(node.s[k], intern)}`).join(", ")} })`
+			: "undefined"
+	const args = [
+		sExpr,
+		node.m !== null ? methodMapExpr(node.m, intern) : "null",
+		node.d !== null ? `{ n: ${JSON.stringify(node.d.n)}, c: ${serializeNode(node.d.c, intern)} }` : "null",
+		node.w !== null ? `{ n: ${JSON.stringify(node.w.n)}, m: ${methodMapExpr(node.w.m, intern)} }` : "null",
+		node.ws !== null ? intern.expr(node.ws) : "null",
+	]
+	while (args.length > 0 && (args[args.length - 1] === "null" || args[args.length - 1] === "undefined")) args.pop()
 	return `N(${args.join(", ")})`
 }
 
-function nodeHasStatic(node: TreeBuild): boolean {
-	if (Object.keys(node.children).length > 0) return true
-	if (node.dynamic !== null) return nodeHasStatic(node.dynamic.child)
-	return false
-}
-
-function selectorOf(route: RouteConfig): string {
-	return `${route.method} ${route.path}`
-}
-
-function mapKeyExpr(intern: InternPool, selector: string): string {
-	const id = intern.id(selector)
-	return id !== undefined ? `[${id}]` : JSON.stringify(selector)
-}
-
-function buildInternPool(routes: RouteConfig[]): InternPool {
-	const intern = new InternPool()
-	for (const route of routes) {
-		intern.count(route.boundaryErrorKey)
-		intern.count(route.errorKeys)
-		intern.count(route.meta)
-		intern.count(selectorOf(route))
-	}
-	for (const route of routes) {
-		intern.force(route.meta, "M")
-		intern.force(selectorOf(route), "P")
-	}
-	intern.seal()
-	return intern
-}
-
-function insertHandler(rootBuild: TreeBuild, route: RouteConfig, hName: string): void {
-	const segments = route.path.split("/").filter((s) => s.length > 0)
-	let node = rootBuild
-
-	for (let i = 0; i < segments.length; i++) {
-		const seg = segments[i]
-		if (seg.startsWith("*")) {
-			const name = seg.length > 1 ? seg.slice(1) : "*"
-			if (node.wildcard === null) {
-				node.wildcard = { handlers: [], name }
-			}
-			node.wildcard.handlers.push({ handler: hName, method: route.method })
-			return
-		}
-		if (seg.startsWith(":")) {
-			const name = seg.endsWith("?") ? seg.slice(1, -1) : seg.slice(1)
-			if (node.dynamic === null) {
-				node.dynamic = { child: createTreeBuild(), name }
-			}
-			if (i === segments.length - 1) {
-				node.dynamic.child.handlers.push({
-					handler: hName,
-					method: route.method,
-				})
-			} else {
-				node = node.dynamic.child
-			}
-			continue
-		}
-		if (node.children[seg] === undefined) {
-			node.children[seg] = createTreeBuild()
-		}
-		if (i === segments.length - 1) {
-			node.children[seg].handlers.push({
-				handler: hName,
-				method: route.method,
-			})
-		} else {
-			node = node.children[seg]
-		}
-	}
-
-	if (segments.length === 0) {
-		node.handlers.push({ handler: hName, method: route.method })
-	}
-}
-
-function collectMetaShape(collected: CollectedRoute[]): {
+function collectMetaShape(entries: Array<{ mt: Record<string, unknown> | null | undefined }>): {
 	allKeys: Map<string, Set<string>>
 	keyCount: Map<string, number>
 	metaHandlerCount: number
@@ -1525,10 +1599,10 @@ function collectMetaShape(collected: CollectedRoute[]): {
 	const allKeys = new Map<string, Set<string>>()
 	const keyCount = new Map<string, number>()
 	let metaHandlerCount = 0
-	for (const { handler } of collected) {
-		if (handler.mt === null) continue
+	for (const { mt } of entries) {
+		if (mt === null || mt === undefined) continue
 		metaHandlerCount++
-		for (const [k, v] of Object.entries(handler.mt)) {
+		for (const [k, v] of Object.entries(mt)) {
 			if (!allKeys.has(k)) allKeys.set(k, new Set())
 			allKeys.get(k)?.add(emitLiteral(v))
 			keyCount.set(k, (keyCount.get(k) ?? 0) + 1)
@@ -1540,137 +1614,144 @@ function collectMetaShape(collected: CollectedRoute[]): {
 function emitMetaShapeType(shape: ReturnType<typeof collectMetaShape>): string {
 	if (shape.allKeys.size === 0) return ""
 	const props = [...shape.allKeys.entries()]
-		.sort(([a], [b]) => a.localeCompare(b))
+		.sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
 		.map(([key, types]) => {
 			const optional = (shape.keyCount.get(key) ?? 0) < shape.metaHandlerCount ? "?" : ""
-			const safeKey = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(key) ? key : `"${key}"`
+			const safeKey = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(key) ? key : JSON.stringify(key)
 			return `\t${safeKey}${optional}: ${[...types].join(" | ")}`
 		})
 	return `export type MetaShape = {\n${props.join("\n")}\n} & Record<string, unknown>\n`
 }
 
-function emitRouteTree(routes: RouteConfig[], collected: CollectedRoute[] | null): string {
-	const intern = buildInternPool(routes)
-	const metaShape = collected !== null ? collectMetaShape(collected) : null
-	const hasMetaShape = metaShape !== null && metaShape.allKeys.size > 0
-	const lines: string[] = []
-	lines.push('import type { TreeNode, RouteHandler, RouteTree } from "@lovrozagar/honey/tree"')
-	lines.push("")
-	lines.push("const E = Object.create(null) as Record<string, TreeNode>")
-	lines.push(
-		'function N(s: Record<string, TreeNode>, m: Record<string, RouteHandler> | null = null, d: TreeNode["d"] = null, w: { n: string; m: Record<string, RouteHandler> } | null = null): TreeNode {',
-	)
-	lines.push('\treturn { s, d, w: w as TreeNode["w"], m: m as TreeNode["m"], ws: null }')
-	lines.push("}")
+type EmitEntry = {
+	bek: string | null
+	ek: string[]
+	id: string
+	internalMeta: boolean
+	mt: Record<string, unknown> | null
+}
 
-	const rootBuild = createTreeBuild()
-	for (let i = 0; i < routes.length; i++) {
-		insertHandler(rootBuild, routes[i], `H${i}`)
+/**
+ * Emit a route tree module: topology with `RouteId` leaves plus per-route data (meta, error
+ * keys, boundary key). No handler fields — the app that loads the tree registers its routes,
+ * which bind to these ids; leaves it does not register are delegated to its catch-all.
+ */
+function emitRouteTree(tree: RouteTree): string {
+	const order: string[] = []
+	const seen = new Set<string>()
+	forEachLeaf(tree.root, (_method, _path, id) => {
+		if (!seen.has(id)) {
+			seen.add(id)
+			order.push(id)
+		}
+	})
+	const entries: EmitEntry[] = []
+	for (const id of order) {
+		const entry = tree.routes[id]
+		if (entry === undefined) throw new Error(`route tree leaf ${id} has no route entry`)
+		const mt = entry.mt ?? null
+		if (mt !== null) assertJsonValue(mt, `Route meta for ${id}`, "meta")
+		entries.push({
+			bek: entry.bek ?? null,
+			ek: [...(entry.ek ?? [])],
+			id,
+			internalMeta: (mt as { internal?: unknown } | null)?.internal === true,
+			mt,
+		})
 	}
 
-	if (nodeHasStatic(rootBuild)) {
-		lines.push("function S(o: Record<string, TreeNode>): Record<string, TreeNode> {")
-		lines.push("\treturn Object.assign(Object.create(null), o) as Record<string, TreeNode>")
-		lines.push("}")
+	const intern = new InternPool()
+	for (const e of entries) {
+		intern.count(e.bek)
+		if (e.ek.length > 0) intern.count(e.ek)
+		intern.count(e.mt)
+		intern.count(e.id)
 	}
-
-	if (routes.length > 0) {
-		lines.push('const FN = null as unknown as RouteHandler["fn"]')
+	for (const e of entries) {
+		intern.force(e.mt, "M")
+		intern.force(e.id, "P")
 	}
+	intern.seal()
+
+	const metaShape = collectMetaShape(entries)
+	const hasMetaShape = metaShape.allKeys.size > 0
+	const lines: string[] = []
+	lines.push('import type { RouteTree, TreeNode } from "@lovrozagar/honey/tree"')
+	lines.push("")
+	lines.push("function S<T>(o: Record<string, T>): Record<string, T> {")
+	lines.push("\treturn Object.assign(Object.create(null) as Record<string, T>, o)")
+	lines.push("}")
+	lines.push(
+		'function N(s: Record<string, TreeNode> = S({}), m: Record<string, string> | null = null, d: TreeNode["d"] = null, w: TreeNode["w"] = null, ws: string | null = null): TreeNode {',
+	)
+	lines.push("\treturn { d, m, s, w, ws }")
+	lines.push("}")
 
 	const consts = intern.emitConstLines()
 	if (consts.length > 0) {
 		lines.push("")
 		for (const line of consts) {
 			if (hasMetaShape && /^const M\d+ = /.test(line)) lines.push(`${line} as unknown as MetaShape`)
-			else lines.push(line)
-		}
-	}
-
-	if (routes.length > 0) {
-		lines.push("")
-		/* unique handler per route — sharing H objects would cross-wire .routeTree() patches */
-		for (let i = 0; i < routes.length; i++) {
-			const route = routes[i]
-			const bekExpr = route.boundaryErrorKey !== null ? intern.expr(route.boundaryErrorKey) : "null"
-			const ekSet = route.errorKeys.length > 0 ? `new Set(${intern.expr(route.errorKeys)})` : "new Set()"
-			const mtExpr = route.meta !== null ? intern.expr(route.meta) : "null"
-			lines.push(`const H${i}: RouteHandler = { bek: ${bekExpr}, fn: FN, mw: [], ek: ${ekSet}, mt: ${mtExpr} }`)
+			else lines.push(line)
 		}
 	}
 
 	lines.push("")
-	lines.push(`export const tree: TreeNode = ${serializeNode(rootBuild)}`)
+	lines.push(`export const tree: TreeNode = ${serializeNode(tree.root as TreeNodeLike, intern)}`)
 	lines.push("")
-
-	const handlerMapEntries = routes.map((route, index) => `\t${mapKeyExpr(intern, selectorOf(route))}: H${index}`)
-	lines.push(`export const handlers: Record<string, RouteHandler> = {\n${handlerMapEntries.join(",\n")}\n}`)
+	const routeLines = entries.map((e) => {
+		const parts: string[] = []
+		if (e.bek !== null) parts.push(`bek: ${intern.expr(e.bek)}`)
+		if (e.ek.length > 0) parts.push(`ek: ${intern.expr(e.ek)}`)
+		if (e.mt !== null) parts.push(`mt: ${intern.expr(e.mt)}`)
+		return `\t[${intern.expr(e.id)}]: ${parts.length > 0 ? `{ ${parts.join(", ")} }` : "{}"}`
+	})
+	lines.push(`export const routes: RouteTree["routes"] = S({\n${routeLines.join(",\n")}\n})`)
 	lines.push("")
 
 	let code = lines.join("\n")
-	if (collected === null) return code
-
-	const metaEntries: string[] = []
-	for (const { handler, method, path } of collected) {
-		if (handler.mt === null || Object.keys(handler.mt).length === 0) continue
-		const selector = `${method} ${path}`
-		metaEntries.push(`\t${mapKeyExpr(intern, selector)}: ${intern.expr(handler.mt)}`)
-	}
 
-	if (hasMetaShape && metaShape !== null) {
-		code += `\n${emitMetaShapeType(metaShape)}\n`
-	}
+	if (hasMetaShape) code += `\n${emitMetaShapeType(metaShape)}\n`
 
-	const selectors = new Set<string>()
-	for (const { handler, method, path } of collected) {
-		if (handler._skip || isMetaInternal(handler)) continue
-		selectors.add(`${method} ${path}`)
-	}
-	if (selectors.size > 0) {
-		const sorted = [...selectors].sort()
-		const parts = sorted.map((s) => {
-			const id = intern.id(s)
-			return id !== undefined ? `typeof ${id}` : JSON.stringify(s)
+	const selectors = entries.filter((e) => !e.id.startsWith("WS ") && !e.internalMeta).map((e) => e.id)
+	if (selectors.length > 0) {
+		const sorted = [...new Set(selectors)].sort()
+		const parts = sorted.map((sel) => {
+			const ref = intern.id(sel)
+			return ref !== undefined ? `typeof ${ref}` : JSON.stringify(sel)
 		})
 		code += `\nexport type RouteSelector = ${parts.join(" | ")}\n`
 	}
 
+	const metaEntries = entries
+		.filter((e) => e.mt !== null && Object.keys(e.mt).length > 0)
+		.map((e) => `\t[${intern.expr(e.id)}]: ${intern.expr(e.mt)}`)
+	const metaType = hasMetaShape ? "Record<string, MetaShape>" : "Record<string, Record<string, unknown>>"
 	if (metaEntries.length > 0) {
-		const metaType = hasMetaShape ? "Record<string, MetaShape>" : "Record<string, Record<string, unknown>>"
-		code += `export const meta: ${metaType} = {\n${metaEntries.join(",\n")}\n}\n`
+		code += `export const meta: ${metaType} = S({\n${metaEntries.join(",\n")}\n})\n`
 	}
-
-	const hasMetaExport = metaEntries.length > 0
-	code += `export const routeTree: RouteTree = { root: tree, ${hasMetaExport ? "meta, " : "meta: {}, "}handlers }\n`
+	code += `export const routeTree: RouteTree = { v: ${ROUTE_TREE_VERSION}, root: tree, routes, ${metaEntries.length > 0 ? "meta" : "meta: {}"} }\n`
 
 	return code
 }
 
-export function generateRouteTree(routes: RouteConfig[]): string {
-	return emitRouteTree(routes, null)
-}
-
-function generateFromTreeRoot(root: TreeNode): string {
-	const routes: RouteConfig[] = []
-	collectRoutesForTree(root, "", routes)
-	const collected: CollectedRoute[] = []
-	walkTree(root, "", collected)
-	return emitRouteTree(routes, collected)
+/** Emit a route tree module from a tree (a `mergeTree` result or an `app.toRouteTree()` snapshot). */
+export function generateRouteTree(tree: RouteTree): string {
+	return emitRouteTree(tree)
 }
 
 export function generateRouteTreeFromApp<TEnv, TCtx>(
 	app: Honey<TEnv, TCtx, unknown, unknown, unknown, string, string>,
 ): string {
-	const root = (app as unknown as { _tree: TreeNode })._tree
-	return generateFromTreeRoot(root)
+	return emitRouteTree(app.toRouteTree())
 }
 
 /**
  * Generate static route tree code from a pre-built RouteTree.
  * Supports gateway patterns: import service trees → enrich meta → mergeTree → generate.
  */
-export function generateRouteTreeFromRouteTree(rt: { root: TreeNode }): string {
-	return generateFromTreeRoot(rt.root)
+export function generateRouteTreeFromRouteTree(rt: RouteTree): string {
+	return emitRouteTree(rt)
 }
 
 /* ---- Type codegen ---- */
@@ -1707,14 +1788,14 @@ function emitOutputType(handler: RouteHandler, state: TypeEmitState): string {
 		if (contentType === "redirect") {
 			const keys = Object.keys(schemas).filter((k) => schemas[k as keyof typeof schemas])
 			if (keys.length > 0) {
-				ctEntries.push(`"redirect": { ${keys.map((k) => `${k}: true`).join("; ")} }`)
+				ctEntries.push(`"redirect": { ${keys.map((k) => `${quoteKey(k)}: true`).join("; ")} }`)
 			}
 			continue
 		}
 		const statusEntries: string[] = []
 		for (const [statusKey, schema] of Object.entries(schemas)) {
 			if (schema === undefined) continue
-			statusEntries.push(`${statusKey}: ${emitSchemaType(schema as StandardSchemaLike, state)}`)
+			statusEntries.push(`${quoteKey(statusKey)}: ${emitSchemaType(schema as StandardSchemaLike, state)}`)
 		}
 		if (statusEntries.length > 0) {
 			ctEntries.push(`${JSON.stringify(contentType)}: { ${statusEntries.join("; ")} }`)
@@ -1728,8 +1809,7 @@ function emitMetaType(handler: RouteHandler): string {
 	if (!handler.mt) return "{}"
 	const entries: string[] = []
 	for (const [k, v] of Object.entries(handler.mt)) {
-		const key = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(k) ? k : JSON.stringify(k)
-		entries.push(`${key}: ${emitLiteral(v)}`)
+		entries.push(`${quoteKey(k)}: ${emitLiteral(v)}`)
 	}
 	if (entries.length === 0) return "{}"
 	return `{ ${entries.join("; ")} }`
@@ -1739,7 +1819,9 @@ function emitLiteral(value: unknown): string {
 	if (value === null) return "null"
 	if (value === undefined) return "undefined"
 	if (typeof value === "string") return JSON.stringify(value)
-	if (typeof value === "number" || typeof value === "boolean") return String(value)
+	if (typeof value === "number") return Number.isFinite(value) ? String(value) : "number"
+	if (typeof value === "boolean") return String(value)
+	if (typeof value === "bigint") return `${value}n`
 	if (Array.isArray(value)) {
 		if (value.length === 0) return "[]"
 		return `[${value.map((v) => emitLiteral(v)).join(", ")}]`
@@ -1772,9 +1854,9 @@ function emitErrorShapes(
 		const entry = meta?.[key]
 		if (entry?.schema) {
 			const schemaType = emitSchemaType(entry.schema as StandardSchemaLike, state)
-			entries.push(`${key}: ${schemaType}`)
+			entries.push(`${quoteKey(key)}: ${schemaType}`)
 		} else {
-			entries.push(`${key}: null`)
+			entries.push(`${quoteKey(key)}: null`)
 		}
 	}
 	return `{ ${entries.join("; ")} }`
@@ -1824,16 +1906,15 @@ function emitErrorsCtxType(handler: RouteHandler): string {
 		.sort()
 		.map(
 			(k) =>
-				`${k}: (opts?: { cause?: unknown; fields?: Record<string, { error_key: string; message: string; path: string }[]>; headers?: Record<string, string>; vars?: Record<string, string | number> }) => HoneyError`,
+				`${quoteKey(k)}: (opts?: { cause?: unknown; fields?: Record<string, { error_key: string; message: string; path: string }[]>; headers?: Record<string, string>; vars?: Record<string, string | number> }) => HoneyError`,
 		)
 	return `readonly errors: { ${entries.join("; ")} }`
 }
 
 /**
- * Look up per-route middleware type additions.
- * The type extractor stores keys as `"method /route-path"` (no basePath prefix),
- * but the codegen resolves routes to full paths (with basePath).
- * Try exact match first, then strip leading segments until a match is found.
+ * Per-route middleware type additions. The type extractor keys routes by their full path —
+ * basePath included — exactly as the router registers them, so the lookup is exact: a route
+ * with no entry gets the base ctx, never another route's additions.
  */
 function resolveRouteMiddleware(
 	routeMiddleware: Record<string, string> | undefined,
@@ -1841,27 +1922,15 @@ function resolveRouteMiddleware(
 	fullPath: string,
 ): string | undefined {
 	if (!routeMiddleware) return undefined
-	const exact = routeMiddleware[`${method} ${fullPath}`]
-	if (exact) return exact
-
-	/* strip leading path segments (basePath) until match */
-	let p = fullPath
-	while (p.includes("/", 1)) {
-		const nextSlash = p.indexOf("/", 1)
-		p = p.slice(nextSlash)
-		const key = `${method} ${p}`
-		if (routeMiddleware[key]) return routeMiddleware[key]
-	}
-	return undefined
+	const key = `${method} ${fullPath}`
+	return Object.hasOwn(routeMiddleware, key) ? routeMiddleware[key] : undefined
 }
 
 export function generateTypes<TEnv, TCtx>(
 	app: Honey<TEnv, TCtx, unknown, unknown, unknown, string, string>,
 	options: GenerateTypesOptions,
 ): string {
-	const tree = (app as unknown as { _tree: TreeNode })._tree
-	const collected: CollectedRoute[] = []
-	walkTree(tree, "", collected, true)
+	const collected: CollectedRoute[] = collectRoutes(app, true)
 
 	const factory = getErrorFactory(app)
 	const errorMeta = getErrorMeta(factory)
@@ -1906,7 +1975,8 @@ export function generateTypes<TEnv, TCtx>(
 		const sorted = [...selectors].sort()
 		lines.push(`export type RouteSelector = ${sorted.map((s) => JSON.stringify(s)).join(" | ")}`)
 		lines.push("")
-		lines.push('declare module "honey" {')
+		/* augment the module consumers import — an augmentation of any other name silently applies to nothing */
+		lines.push('declare module "@lovrozagar/honey" {')
 		lines.push("\tinterface HoneyCodegen {")
 		lines.push(`\t\trouteSelector: RouteSelector`)
 		lines.push("\t}")
@@ -1946,7 +2016,7 @@ export function generateTypes<TEnv, TCtx>(
 
 	function buildMwType(method: string, path: string): string | undefined {
 		const key = `${method} ${path}`
-		const props = routeProps?.[key]
+		const props = routeProps && Object.hasOwn(routeProps, key) ? routeProps[key] : undefined
 		if (props?.length) {
 			const entries = props.map((p) => {
 				const typeStr = subTypeMap.get(p.type) ?? p.type
@@ -1983,7 +2053,7 @@ export function generateTypes<TEnv, TCtx>(
 	routesLines.push("export type Routes = {")
 
 	for (const [path, methods] of byPath) {
-		routesLines.push(`\t"${path}": {`)
+		routesLines.push(`\t${JSON.stringify(path)}: {`)
 		for (const { handler, method } of methods) {
 			const mwType = buildMwType(method, path)
 			const mwAlias = mwType ? mwTypeMap.get(mwType) : undefined
@@ -1991,9 +2061,10 @@ export function generateTypes<TEnv, TCtx>(
 			const additions: string[] = []
 			const inputType = emitInputType(handler, emitState)
 			if (inputType !== "{}") additions.push(`input: ${inputType}`)
-			const params = extractParams(path)
+			/* the names ctx.params carries at runtime — an unnamed wildcard is "*" */
+			const params = patternParams(parsePattern(path))
 			if (params.length > 0) {
-				const paramEntries = params.map((p) => `${p}: string`).join("; ")
+				const paramEntries = params.map((p) => `${quoteKey(p)}: string`).join("; ")
 				additions.push(`readonly params: { ${paramEntries} }`)
 			}
 			const errorsCtx = emitErrorsCtxType(handler)
@@ -2002,13 +2073,16 @@ export function generateTypes<TEnv, TCtx>(
 			const errorType = emitErrorType(handler)
 			const metaType = emitMetaType(handler)
 			const outputType = emitOutputType(handler, emitState)
-			routesLines.push(`\t\t${method}: {`)
+			routesLines.push(`\t\t${quoteKey(method)}: {`)
 			routesLines.push(`\t\t\tctx: WithOutput<${ctxType}, ${outputType}>`)
 			routesLines.push(`\t\t\terrors: ${errorType}`)
-			const shapesType = emitErrorShapes(handler, errorMeta, emitState)
+			/* a mounted sub-app's route keeps its own error factory */
+			const routeFactory = (handler.fac as Record<string, () => HoneyError> | null | undefined) ?? factory
+			const routeErrorMeta = routeFactory === factory ? errorMeta : getErrorMeta(routeFactory)
+			const shapesType = emitErrorShapes(handler, routeErrorMeta, emitState)
 			if (shapesType) {
 				routesLines.push(`\t\t\terrorShapes: ${shapesType}`)
-				const byStatusType = emitErrorsByStatus(handler, errorMeta, factory, emitState)
+				const byStatusType = emitErrorsByStatus(handler, routeErrorMeta, routeFactory, emitState)
 				if (byStatusType) {
 					routesLines.push(`\t\t\terrorsByStatus: ${byStatusType}`)
 				}
@@ -2194,6 +2268,8 @@ type ServiceEntry = {
 	realtime?: boolean
 	ws?: boolean
 	sse?: boolean
+	/** The path param that is a wildcard: its value may span segments */
+	wildcard?: string
 }
 
 type NestedServiceNode =
@@ -2214,6 +2290,8 @@ type GeneratedSDK = {
 type SDKMethod = {
 	action: string
 	errorsByStatusType: string | null
+	/** Full operationId (explicit or derived) */
+	id: string
 	inputHasMandatory: boolean
 	inputType: string
 	realtime: boolean
@@ -2225,7 +2303,8 @@ type SDKMethod = {
 
 export function extractOpenApiPathParams(path: string): string[] {
 	const params: string[] = []
-	const re = /\{(\w+)\}/g
+	/* any name between braces — `{user-id}` is one parameter, not `{user}` and a literal `-id` */
+	const re = /\{([^{}/]+)\}/g
 	let match: RegExpExecArray | null = re.exec(path)
 	while (match !== null) {
 		params.push(match[1])
@@ -2253,87 +2332,76 @@ export function jsonSchemaToTS(schema: Record<string, unknown> | undefined, dept
 /* a file part of a multipart body is sent as a Blob/File; the runtime appends it to FormData as is */
 const FORM_BINARY_TS = "Blob"
 
+/* the TS SDK input field a request body fills, by its media type */
+function sdkBodyField(body: IRBody): "body" | "form" | "json" | null {
+	if (body.kind === "stream") return "body"
+	if (body.kind === "multipart") return "form"
+	const essence = mediaEssence(body.contentType)
+	if (isJsonMedia(body.contentType)) return "json"
+	if (essence === "multipart/form-data" || essence === "application/x-www-form-urlencoded") return "form"
+	return null
+}
+
 /* extract input type for an operation */
-function emitSDKInputType(op: Record<string, unknown>, path: string): { hasMandatory: boolean; type: string } {
+function emitSDKInputType(op: IROperation): { hasMandatory: boolean; type: string } {
 	const mandatoryParts: string[] = []
 	const optionalParts: string[] = []
 
 	/* path params — always required */
-	const pathParamNames = extractOpenApiPathParams(path)
-	if (pathParamNames.length > 0) {
-		const allParameters = op.parameters as Array<Record<string, unknown>> | undefined
-		const entries = pathParamNames
-			.map((name) => {
-				const paramDef = allParameters?.find((p) => p.name === name && p.in === "path")
-				const schema = paramDef?.schema as Record<string, unknown> | undefined
-				const tsType = schema ? jsonSchemaToTS(schema) : "string"
-				const safeParamName = sdkSafeName(name)
-				return `${safeParamName}: ${tsType}`
-			})
-			.join("; ")
+	if (op.params.path.length > 0) {
+		const entries = op.params.path.map((p) => `${sdkSafeName(p.name)}: ${irToTs(p.schema)}`).join("; ")
 		mandatoryParts.push(`params: { ${entries} }`)
 	}
 
 	/* query params */
-	const parameters = op.parameters as Array<Record<string, unknown>> | undefined
-	if (parameters) {
-		const queryParams = parameters.filter((p) => p.in === "query")
-		if (queryParams.length > 0) {
-			const hasRequired = queryParams.some((p) => p.required === true)
-			const entries = queryParams
-				.sort((a, b) => String(a.name).localeCompare(String(b.name)))
-				.map((p) => {
-					const name = String(p.name)
-					const required = p.required === true
-					const schema = p.schema as Record<string, unknown> | undefined
-					const tsType = jsonSchemaToTS(schema)
-					const safeQueryName = sdkSafeName(name)
-					return `${safeQueryName}${required ? "" : "?"}: ${tsType}`
-				})
-			const searchEntry = `search: { ${entries.join("; ")} }`
-			if (hasRequired) {
-				mandatoryParts.push(searchEntry)
-			} else {
-				optionalParts.push(searchEntry)
-			}
-		}
+	if (op.params.query.length > 0) {
+		const entries = op.params.query
+			.slice()
+			.sort((a, b) => compareCodeUnits(a.name, b.name))
+			.map((p) => `${sdkSafeName(p.name)}${p.required === true ? "" : "?"}: ${irToTs(p.schema)}`)
+		const searchEntry = `search: { ${entries.join("; ")} }`
+		if (op.params.query.some((p) => p.required === true)) mandatoryParts.push(searchEntry)
+		else optionalParts.push(searchEntry)
 	}
 
-	/* request body */
-	const requestBody = op.requestBody as Record<string, unknown> | undefined
-	if (requestBody) {
-		const required = (requestBody.required as boolean | undefined) === true
-		const content = requestBody.content as Record<string, Record<string, unknown>> | undefined
-		if (content) {
-			/* application/octet-stream: raw byte stream — emit `body:` field,
-			 * mutually exclusive with json/form for this operation */
-			if ("application/octet-stream" in content) {
-				const entry = "body: ReadableStream<Uint8Array> | Blob | ArrayBuffer | Uint8Array"
-				if (required) {
-					mandatoryParts.push(entry)
-				} else {
-					optionalParts.push(entry)
-				}
-			}
-			const jsonContent = content["application/json"]
-			if (jsonContent?.schema) {
-				const entry = `json: ${jsonSchemaToTS(jsonContent.schema as Record<string, unknown>)}`
-				if (required) {
-					mandatoryParts.push(entry)
-				} else {
-					optionalParts.push(entry)
-				}
-			}
-			const formContent = content["multipart/form-data"] ?? content["application/x-www-form-urlencoded"]
-			if (formContent?.schema) {
-				const entry = `form: ${jsonSchemaToTS(formContent.schema as Record<string, unknown>, 0, FORM_BINARY_TS)}`
-				if (required) {
-					mandatoryParts.push(entry)
-				} else {
-					optionalParts.push(entry)
-				}
-			}
+	/* header and cookie params — typed on top of the free-form per-call `headers` / `cookies` */
+	for (const [declared, field] of [
+		[op.params.header, "headers"],
+		[op.params.cookie ?? [], "cookies"],
+	] as const) {
+		if (declared.length === 0) continue
+		const entries = declared
+			.slice()
+			.sort((a, b) => compareCodeUnits(a.name, b.name))
+			.map((p) => {
+				/* sent as text: a header or cookie value is a string on the wire */
+				const tsType = p.schema.kind === "scalar" && p.schema.enum ? irToTs(p.schema) : "string"
+				return `${quoteKey(p.name)}${p.required === true ? "" : "?"}: ${tsType}`
+			})
+		const entry = `${field}: { ${entries.join("; ")} }`
+		if (declared.some((p) => p.required === true)) mandatoryParts.push(entry)
+		else optionalParts.push(entry)
+	}
+
+	/* request body: one input field per kind; the preferred content type of each kind wins */
+	const byField = new Map<string, IRBody>()
+	for (const body of bodiesOf(op)) {
+		const field = sdkBodyField(body)
+		if (field && !byField.has(field)) byField.set(field, body)
+	}
+	/* raw bytes first, then json, then form: the order the fields always had */
+	for (const field of ["body", "json", "form"] as const) {
+		const body = byField.get(field)
+		if (!body) continue
+		let entry: string
+		if (field === "body") entry = "body: ReadableStream<Uint8Array> | Blob | ArrayBuffer | Uint8Array"
+		else if (field === "json") entry = `json: ${body.kind === "raw" ? irToTs(body.schema) : "unknown"}`
+		else {
+			const schema = body.kind === "raw" ? body.schema : body.kind === "multipart" ? body.schema : undefined
+			entry = `form: ${schema ? irToTs(schema, 0, FORM_BINARY_TS) : "Record<string, unknown>"}`
 		}
+		if (body.required) mandatoryParts.push(entry)
+		else optionalParts.push(entry)
 	}
 
 	const allParts = [...mandatoryParts, ...optionalParts]
@@ -2342,49 +2410,31 @@ function emitSDKInputType(op: Record<string, unknown>, path: string): { hasManda
 }
 
 /* extract response type for an operation */
-function emitSDKResponseType(op: Record<string, unknown>): string {
-	const responses = op.responses as Record<string, Record<string, unknown>> | undefined
-	if (!responses) return "void"
-
-	/* check for SSE — shape mirrors runtime _SSEEvent (event/id/retry all optional) */
-	for (const response of Object.values(responses)) {
-		const content = response.content as Record<string, unknown> | undefined
-		if (content && "text/event-stream" in content)
-			return "AsyncIterable<{ data: string; event?: string; id?: string; retry?: number }>"
-	}
+function emitSDKResponseType(op: IROperation): string {
+	/* SSE — shape mirrors runtime _SSEEvent (event/id/retry all optional) */
+	if (op.extensions.sse) return "AsyncIterable<{ data: string; event?: string; id?: string; retry?: number }>"
 
-	/* collect success response types (2xx) */
+	/* collect success response types (2xx) — `default` and `4XX`-style keys are never success */
 	const successTypes: string[] = []
-	for (const [status, response] of Object.entries(responses)) {
-		const code = Number.parseInt(status, 10)
-		if (code < 200 || code >= 300) continue
-		if (code === 204) {
+	for (const [status, response] of Object.entries(op.responses)) {
+		if (!/^2(?:[0-9][0-9]|XX)$/i.test(status)) continue
+		const code = /^2XX$/i.test(status) ? 200 : Number(status)
+		if (code === 204 || code === 205 || !response.contentType) {
 			successTypes.push("null")
 			continue
 		}
-		const content = response.content as Record<string, Record<string, unknown>> | undefined
-		if (!content) {
-			successTypes.push("null")
-			continue
-		}
-		if (content["application/json"]?.schema) {
-			successTypes.push(jsonSchemaToTS(content["application/json"].schema as Record<string, unknown>))
-		} else if ("application/octet-stream" in content) {
-			successTypes.push("ArrayBuffer")
+		/* the same classes the runtime's body parser reads: JSON, text, otherwise bytes */
+		if (isJsonMedia(response.contentType)) {
+			successTypes.push(response.schema ? irToTs(response.schema) : "unknown")
+		} else if (isTextMedia(response.contentType)) {
+			successTypes.push("string")
 		} else {
-			const keys = Object.keys(content)
-			const isText = keys.some((k) => k.startsWith("text/") || k === "application/xml")
-			if (isText) {
-				successTypes.push("string")
-			} else if (keys.length > 0) {
-				successTypes.push("ArrayBuffer")
-			}
+			successTypes.push("ArrayBuffer")
 		}
 	}
 
 	if (successTypes.length === 0) return "void"
-	if (successTypes.length === 1) return successTypes[0]
-	return successTypes.join(" | ")
+	return [...new Set(successTypes)].join(" | ")
 }
 
 /* detect whether a JSON schema matches the standard error envelope shape */
@@ -2424,25 +2474,19 @@ export function isStandardErrEnvelope(schema: Record<string, unknown>): { keys:
 }
 
 /* extract error types by status code for an operation (non-2xx responses) */
-function emitSDKErrorsByStatusType(op: Record<string, unknown>): string | null {
-	const responses = op.responses as Record<string, Record<string, unknown>> | undefined
-	if (!responses) return null
-
+function emitSDKErrorsByStatusType(op: IROperation, resolve: (schema: IRSchema) => IRSchema): string | null {
 	const entries: string[] = []
-	for (const [status, response] of Object.entries(responses)) {
-		const code = Number.parseInt(status, 10)
-		if (code < 400) continue /* only error responses */
-
-		const content = response.content as Record<string, Record<string, unknown>> | undefined
-		const schema = content?.["application/json"]?.schema as Record<string, unknown> | undefined
-		if (!schema) continue
-
-		const envelope = isStandardErrEnvelope(schema)
+	for (const [status, response] of Object.entries(op.responses)) {
+		/* only concrete error statuses: `default` and `4XX` have no single status to key on */
+		if (!/^[45][0-9][0-9]$/.test(status)) continue
+		if (!response.schema || !response.contentType || !isJsonMedia(response.contentType)) continue
+		const code = Number(status)
+		const envelope = irErrorEnvelope(response.schema, resolve)
 		if (envelope) {
 			const keyUnion = envelope.keys.map((k) => JSON.stringify(k)).join(" | ")
 			entries.push(`${code}: _ErrEnvelope<${envelope.status}, ${keyUnion}>`)
 		} else {
-			entries.push(`${code}: ${jsonSchemaToTS(schema)}`)
+			entries.push(`${code}: ${irToTs(response.schema)}`)
 		}
 	}
 
@@ -2502,7 +2546,7 @@ function buildTypeAliases(
 	const aliases = new Map<string, string>()
 	const lines: string[] = []
 	let idx = 0
-	for (const [typeStr, count] of [...counts.entries()].sort(([a], [b]) => a.localeCompare(b))) {
+	for (const [typeStr, count] of [...counts.entries()].sort(([a], [b]) => compareCodeUnits(a, b))) {
 		if (count >= minCount || typeStr.length > 200) {
 			const alias = `${prefix}${idx++}`
 			aliases.set(typeStr, alias)
@@ -2703,6 +2747,7 @@ function buildSDKTypes(
 	l.push("\tauthHeaderName?: string")
 	l.push("\tauthHeaderPrefix?: string")
 	l.push("\tonLog?: (entry: _LogEntry) => void")
+	l.push('\tredirect?: "error" | "follow" | "manual" | "same-origin"')
 	l.push("\tsortSearchParams?: boolean")
 	l.push("\tsseMaxBufferChars?: number")
 	l.push("\tstate?: Record<string, unknown>")
@@ -2770,13 +2815,14 @@ function emitNestedMapNode(node: NestedServiceNode, indent: string): string[] {
 		const parts = [`method: ${JSON.stringify(entry.method)}`, `path: ${JSON.stringify(entry.path)}`]
 		if (entry.params) parts.push(`params: ${JSON.stringify(entry.params)}`)
 		if (entry.sse) parts.push("sse: true")
+		if (entry.wildcard) parts.push(`wildcard: ${JSON.stringify(entry.wildcard)}`)
 		if (entry.ws) parts.push("ws: true")
 		if (entry.idempotent) parts.push("idempotent: true")
 		if (entry.invalidate) parts.push(`invalidate: ${JSON.stringify(entry.invalidate)}`)
 		return [`{ ${parts.join(", ")} }`]
 	}
 	const lines: string[] = ["{"]
-	for (const [key, child] of [...node.children.entries()].sort(([a], [b]) => a.localeCompare(b))) {
+	for (const [key, child] of [...node.children.entries()].sort(([a], [b]) => compareCodeUnits(a, b))) {
 		const safeKey = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(key) ? key : JSON.stringify(key)
 		const childLines = emitNestedMapNode(child, `${indent}\t`)
 		if (childLines.length === 1) {
@@ -2795,7 +2841,7 @@ function buildSDKMap(nestedMap: Map<string, NestedServiceNode>): string {
 	const l: string[] = []
 
 	l.push("export const serviceMap = {")
-	for (const [key, node] of [...nestedMap.entries()].sort(([a], [b]) => a.localeCompare(b))) {
+	for (const [key, node] of [...nestedMap.entries()].sort(([a], [b]) => compareCodeUnits(a, b))) {
 		const safeKey = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(key) ? key : JSON.stringify(key)
 		const childLines = emitNestedMapNode(node, "\t")
 		if (childLines.length === 1) {
@@ -3483,6 +3529,7 @@ type _ServiceEntry = {
 \tparams?: readonly string[]
 \tpath: string
 \tsse?: boolean
+\twildcard?: string
 \tws?: boolean
 }
 
@@ -3511,6 +3558,16 @@ type _RequestMeta = {
 \tselector: string
 \tseqSnapshot: number
 }
+
+type _StaleEntry = { by: string[]; refreshed?: Set<string>; seq: number; until: number }
+
+/* a path parameter value that would change the request's path once a URL parser normalizes it */
+class _PathParamError extends Error {
+\tconstructor(message: string) {
+\t\tsuper(message)
+\t\tthis.name = "PathParamError"
+\t}
+}
 `
 }
 
@@ -3555,7 +3612,8 @@ export class ${n}<TThrow extends boolean = false> {
 \t#resourceCache = new Map<string, Record<string, unknown>>()
 \t#searchSerializer: (query: Record<string, unknown>) => URLSearchParams
 \t#staleTime: number
-\t#staleUntil: Map<string, { by: string[]; seq: number; until: number }> | null
+\t#staleUntil: Map<string, _StaleEntry> | null
+\t#stalePatterns = new Map<string, Map<string, _StaleEntry>>()
 \t#patternRegexCache = new Map<string, RegExp>()
 \t#invalidationSeq = 0
 \t#staleMaxEntries: number
@@ -3564,6 +3622,8 @@ export class ${n}<TThrow extends boolean = false> {
 \t#sseMaxBufferChars: number
 \t#disposeCtrl = new AbortController()
 \t#disposed = false
+\t#refreshing: Promise<string | null> | null = null
+\t#token: string | null = null
 `
 }
 
@@ -3576,9 +3636,7 @@ function sdkClientConstructor(n: string): string {
 \t\tthis.#fetchFn = config.fetch ?? (typeof globalThis.fetch === "function" ? globalThis.fetch.bind(globalThis) : globalThis.fetch)
 \t\tthis.#searchSerializer = config.buildSearchParams ?? ((q: Record<string, unknown>) => this.#serializeSearch(q))
 \t\tthis.#staleTime = config.invalidation?.staleTime ?? 0
-\t\tthis.#staleUntil = this.#staleTime > 0
-\t\t\t? new Map<string, { by: string[]; seq: number; until: number }>()
-\t\t\t: null
+\t\tthis.#staleUntil = this.#staleTime > 0 ? new Map<string, _StaleEntry>() : null
 \t\tthis.#staleMaxEntries = config.invalidation?.staleMaxEntries ?? 1000
 \t\tthis.#maxSourcesPerTarget = Math.max(config.invalidation?.maxSourcesPerTarget ?? 16, 1)
 \t\tthis.#maxErrorMessageChars = config.maxErrorMessageChars ?? 512
@@ -3589,41 +3647,45 @@ function sdkClientConstructor(n: string): string {
 function sdkClientProxy(n: string): string {
 	return `
 \t\tconst self = this
+\t\tconst callable = (entry: _ServiceEntry, name: string): ((input?: Record<string, unknown>) => unknown) => {
+\t\t\tconst entryPath = self.#toColonParams(entry.path, entry.wildcard)
+\t\t\tlet fn: (input?: Record<string, unknown>) => unknown
+\t\t\tif (entry.ws) {
+\t\t\t\tfn = (input?: Record<string, unknown>) => self.#connectWS(entry, entryPath, (input ?? {}) as _RequestOptions)
+\t\t\t} else if (entry.sse) {
+\t\t\t\tfn = (input?: Record<string, unknown>) => self.#requestSSE(entry, entryPath, (input ?? {}) as _RequestOptions)
+\t\t\t} else {
+\t\t\t\tfn = (input?: Record<string, unknown>) => self.#request(entry, input ?? {})
+\t\t\t}
+\t\t\tObject.defineProperty(fn, "name", { value: name })
+\t\t\treturn fn
+\t\t}
+\t\tconst isEntry = (node: unknown): node is _ServiceEntry =>
+\t\t\ttypeof node === "object" && node !== null && Object.hasOwn(node, "method") && typeof (node as Record<string, unknown>)["method"] === "string"
+\t\t/* only the map's own keys are operations — never toString, constructor or then */
+\t\tconst childOf = (node: _ServiceMapNode, key: string): _ServiceMapNode | undefined =>
+\t\t\tObject.hasOwn(node, key) ? (node as Record<string, _ServiceMapNode>)[key] : undefined
+
 \t\tfunction makeNodeProxy(node: _ServiceMapNode, path: string[]): object {
 \t\t\tconst actionCache = new Map<string, (input?: Record<string, unknown>) => unknown>()
 \t\t\tconst childCache = new Map<string, object>()
 \t\t\treturn new Proxy({} as Record<string, unknown>, {
-\t\t\t\tget: (_, key: string | symbol) => {
-\t\t\t\t\tif (typeof key === "symbol") return undefined
-\t\t\t\t\tconst child = (node as Record<string, unknown>)[key]
-\t\t\t\t\tif (child === undefined) return undefined
+\t\t\t\tget: (target, key: string | symbol) => {
+\t\t\t\t\tif (typeof key === "symbol") return Reflect.get(target, key)
+\t\t\t\t\tconst child = childOf(node, key)
+\t\t\t\t\tif (child === undefined) return Reflect.get(target, key)
 
-\t\t\t\t\t/* leaf: entry has a "method" string field */
-\t\t\t\t\tif (typeof (child as Record<string, unknown>)["method"] === "string") {
+\t\t\t\t\tif (isEntry(child)) {
 \t\t\t\t\t\tconst cached = actionCache.get(key)
 \t\t\t\t\t\tif (cached) return cached
-\t\t\t\t\t\tconst entry = child as _ServiceEntry
-\t\t\t\t\t\tconst entryPath = self.#toColonParams(entry.path)
-\t\t\t\t\t\tlet fn: (input?: Record<string, unknown>) => unknown
-\t\t\t\t\t\tif (entry.ws) {
-\t\t\t\t\t\t\tfn = (input?: Record<string, unknown>) =>
-\t\t\t\t\t\t\t\tself.#connectWS(entry, entryPath, (input ?? {}) as _RequestOptions)
-\t\t\t\t\t\t} else if (entry.sse) {
-\t\t\t\t\t\t\tfn = (input?: Record<string, unknown>) =>
-\t\t\t\t\t\t\t\tself.#requestSSE(entry, entryPath, (input ?? {}) as _RequestOptions)
-\t\t\t\t\t\t} else {
-\t\t\t\t\t\t\tfn = (input?: Record<string, unknown>) =>
-\t\t\t\t\t\t\t\tself.#request(entry, input ?? {})
-\t\t\t\t\t\t}
-\t\t\t\t\t\tObject.defineProperty(fn, "name", { value: [...path, key].join(".") })
+\t\t\t\t\t\tconst fn = callable(child, [...path, key].join("."))
 \t\t\t\t\t\tactionCache.set(key, fn)
 \t\t\t\t\t\treturn fn
 \t\t\t\t\t}
 
-\t\t\t\t\t/* namespace: recurse */
 \t\t\t\t\tconst cachedChild = childCache.get(key)
 \t\t\t\t\tif (cachedChild) return cachedChild
-\t\t\t\t\tconst childProxy = makeNodeProxy(child as _ServiceMapNode, [...path, key])
+\t\t\t\t\tconst childProxy = makeNodeProxy(child, [...path, key])
 \t\t\t\t\tchildCache.set(key, childProxy)
 \t\t\t\t\treturn childProxy
 \t\t\t\t},
@@ -3632,57 +3694,32 @@ function sdkClientProxy(n: string): string {
 
 \t\treturn new Proxy(this, {
 \t\t\tget: (target, key: string | symbol) => {
-\t\t\t\tif (typeof key === "symbol") return Reflect.get(target, key)
+\t\t\t\t/* the client's own members (state, dispose, toString, ...) always win */
+\t\t\t\tif (typeof key === "symbol" || key in target) return Reflect.get(target, key)
 
 \t\t\t\tconst cached = target.#resourceCache.get(key)
 \t\t\t\tif (cached) return cached
 
-\t\t\t\tconst node = (serviceMap as _ServiceMap)[key]
-\t\t\t\tif (node === undefined) return Reflect.get(target, key)
+\t\t\t\tconst node = childOf(serviceMap as _ServiceMap, key)
+\t\t\t\tif (node === undefined) return undefined
 
 \t\t\t\t/* root-level leaf (single-segment operationId) */
-\t\t\t\tif (typeof (node as Record<string, unknown>)["method"] === "string") {
-\t\t\t\t\tconst entry = node as _ServiceEntry
-\t\t\t\t\tconst entryPath = target.#toColonParams(entry.path)
-\t\t\t\t\tlet fn: (input?: Record<string, unknown>) => unknown
-\t\t\t\t\tif (entry.ws) {
-\t\t\t\t\t\tfn = (input?: Record<string, unknown>) =>
-\t\t\t\t\t\t\ttarget.#connectWS(entry, entryPath, (input ?? {}) as _RequestOptions)
-\t\t\t\t\t} else if (entry.sse) {
-\t\t\t\t\t\tfn = (input?: Record<string, unknown>) =>
-\t\t\t\t\t\t\ttarget.#requestSSE(entry, entryPath, (input ?? {}) as _RequestOptions)
-\t\t\t\t\t} else {
-\t\t\t\t\t\tfn = (input?: Record<string, unknown>) =>
-\t\t\t\t\t\t\ttarget.#request(entry, input ?? {})
-\t\t\t\t\t}
-\t\t\t\t\tObject.defineProperty(fn, "name", { value: key })
+\t\t\t\tif (isEntry(node)) {
+\t\t\t\t\tconst fn = callable(node, key)
 \t\t\t\t\ttarget.#resourceCache.set(key, fn as unknown as Record<string, unknown>)
 \t\t\t\t\treturn fn
 \t\t\t\t}
 
 \t\t\t\t/* namespace node — check for single _call promotion */
-\t\t\t\tconst nodeRecord = node as Record<string, unknown>
-\t\t\t\tconst nodeKeys = Object.keys(nodeRecord)
-\t\t\t\tif (nodeKeys.length === 1 && nodeKeys[0] === "_call") {
-\t\t\t\t\tconst entry = nodeRecord["_call"] as _ServiceEntry
-\t\t\t\t\tconst entryPath = target.#toColonParams(entry.path)
-\t\t\t\t\tlet fn: (input?: Record<string, unknown>) => unknown
-\t\t\t\t\tif (entry.ws) {
-\t\t\t\t\t\tfn = (input?: Record<string, unknown>) =>
-\t\t\t\t\t\t\ttarget.#connectWS(entry, entryPath, (input ?? {}) as _RequestOptions)
-\t\t\t\t\t} else if (entry.sse) {
-\t\t\t\t\t\tfn = (input?: Record<string, unknown>) =>
-\t\t\t\t\t\t\ttarget.#requestSSE(entry, entryPath, (input ?? {}) as _RequestOptions)
-\t\t\t\t\t} else {
-\t\t\t\t\t\tfn = (input?: Record<string, unknown>) =>
-\t\t\t\t\t\t\ttarget.#request(entry, input ?? {})
-\t\t\t\t\t}
-\t\t\t\t\tObject.defineProperty(fn, "name", { value: key })
+\t\t\t\tconst nodeKeys = Object.keys(node)
+\t\t\t\tconst only = childOf(node, "_call")
+\t\t\t\tif (nodeKeys.length === 1 && only !== undefined && isEntry(only)) {
+\t\t\t\t\tconst fn = callable(only, key)
 \t\t\t\t\ttarget.#resourceCache.set(key, fn as unknown as Record<string, unknown>)
 \t\t\t\t\treturn fn
 \t\t\t\t}
 
-\t\t\t\tconst proxy = makeNodeProxy(node as _ServiceMapNode, [key])
+\t\t\t\tconst proxy = makeNodeProxy(node, [key])
 \t\t\t\ttarget.#resourceCache.set(key, proxy as Record<string, unknown>)
 \t\t\t\treturn proxy
 \t\t\t},
@@ -3693,44 +3730,113 @@ function sdkClientProxy(n: string): string {
 
 function sdkClientInterpolatePath(): string {
 	return `
-\t#interpolatePath(path: string, params: Record<string, string>): string {
-\t\treturn path.replace(/:(\\w+)/g, (_, key: string) => {
-\t\t\tconst val = params[key]
-\t\t\tif (val === undefined) throw new Error(\`Missing path param: \${key}\`)
-\t\t\treturn encodeURIComponent(val)
-\t\t})
+\t/* Keep in sync with client/path.ts — :name (whole segment), *name (rest), {name} (inside a segment). */
+\t#encodeSegmentValue(key: string, value: string): string {
+\t\tif (value === "" || value === "." || value === "..") {
+\t\t\tthrow new _PathParamError(\`Invalid path param \${JSON.stringify(key)}: \${JSON.stringify(value)} is not a path segment\`)
+\t\t}
+\t\treturn encodeURIComponent(value)
+\t}
+
+\t#encodeWildcardValue(key: string, value: string): string {
+\t\tif (value === "") return ""
+\t\treturn value.split("/").map((part) => this.#encodeSegmentValue(key, part)).join("/")
+\t}
+
+\t#paramValue(params: Record<string, string> | undefined, key: string): string | undefined {
+\t\tif (!params || !Object.hasOwn(params, key)) return undefined
+\t\tconst raw = params[key] as unknown
+\t\tif (raw === undefined || raw === null) return undefined
+\t\treturn typeof raw === "string" ? raw : String(raw)
+\t}
+
+\t#interpolatePath(path: string, params: Record<string, string> | undefined, partial = false): string {
+\t\tconst segments = path.split("/")
+\t\tconst out: string[] = []
+\t\tfor (let i = 0; i < segments.length; i++) {
+\t\t\tconst seg = segments[i] ?? ""
+\t\t\tif (seg.length > 1 && seg.charCodeAt(0) === 58) {
+\t\t\t\tconst optional = seg.endsWith("?")
+\t\t\t\tconst name = optional ? seg.slice(1, -1) : seg.slice(1)
+\t\t\t\tconst value = this.#paramValue(params, name)
+\t\t\t\tif (value === undefined) {
+\t\t\t\t\tif (partial) { out.push(seg); continue }
+\t\t\t\t\tif (optional) continue
+\t\t\t\t\tthrow new _PathParamError(\`Missing path param: \${name}\`)
+\t\t\t\t}
+\t\t\t\tout.push(this.#encodeSegmentValue(name, value))
+\t\t\t\tcontinue
+\t\t\t}
+\t\t\tif (seg.charCodeAt(0) === 42 && i === segments.length - 1) {
+\t\t\t\tconst name = seg.length > 1 ? seg.slice(1) : "*"
+\t\t\t\tconst value = this.#paramValue(params, name)
+\t\t\t\tif (value === undefined) {
+\t\t\t\t\tif (partial) { out.push(seg); continue }
+\t\t\t\t\tif (seg.length === 1) { out.push(""); continue }
+\t\t\t\t\tthrow new _PathParamError(\`Missing path param: \${name}\`)
+\t\t\t\t}
+\t\t\t\tout.push(this.#encodeWildcardValue(name, value))
+\t\t\t\tcontinue
+\t\t\t}
+\t\t\tout.push(
+\t\t\t\tseg.replace(/\\{([^{}/]+)\\}/g, (match: string, name: string) => {
+\t\t\t\t\tconst value = this.#paramValue(params, name)
+\t\t\t\t\tif (value === undefined) {
+\t\t\t\t\t\tif (partial) return match
+\t\t\t\t\t\tthrow new _PathParamError(\`Missing path param: \${name}\`)
+\t\t\t\t\t}
+\t\t\t\t\treturn this.#encodeSegmentValue(name, value)
+\t\t\t\t}),
+\t\t\t)
+\t\t}
+\t\treturn out.join("/")
+\t}
+
+\t#hasPlaceholder(path: string): boolean {
+\t\tfor (const seg of path.split("/")) {
+\t\t\tif (seg.length > 1 && seg.charCodeAt(0) === 58) return true
+\t\t\tif (seg.charCodeAt(0) === 42) return true
+\t\t\tif (/\\{[^{}/]+\\}/.test(seg)) return true
+\t\t}
+\t\treturn false
 \t}
 `
 }
 
 function sdkClientToColonParams(): string {
 	return `
-\t#toColonParams(path: string): string {
-\t\treturn path.replace(/\\{(\\w+)\\}/g, ":$1")
+\t/* OpenAPI template → route pattern: a whole-segment {name} is :name, the wildcard *name; {name} inside a segment stays */
+\t#toColonParams(path: string, wildcard?: string): string {
+\t\treturn path
+\t\t\t.split("/")
+\t\t\t.map((seg) => {
+\t\t\t\tconst m = /^\\{([^{}/]+)\\}$/.exec(seg)
+\t\t\t\tif (!m) return seg
+\t\t\t\treturn m[1] === wildcard ? \`*\${m[1]}\` : \`:\${m[1]}\`
+\t\t\t})
+\t\t\t.join("/")
 \t}
 `
 }
 
 function sdkClientResolveInvalidationTargets(): string {
 	return `
+\t/* params that are present are substituted; a target left partly unresolved stays a narrower pattern */
 \t#resolveInvalidationTargets(
 \t\ttargets: readonly string[],
 \t\tparams: Record<string, string> | undefined,
 \t): string[] {
 \t\tconst resolved: string[] = []
 \t\tfor (const target of targets) {
-\t\t\tif (!params || !target.includes(":")) { resolved.push(target); continue }
 \t\t\tconst spaceIdx = target.indexOf(" ")
+\t\t\tif (spaceIdx <= 0) continue
 \t\t\tconst targetMethod = target.slice(0, spaceIdx)
 \t\t\tconst targetPath = target.slice(spaceIdx + 1)
-\t\t\tlet hasUnresolved = false
-\t\t\tconst replaced = targetPath.replace(/:(\\w+)/g, (match, key: string) => {
-\t\t\t\tconst val = params[key]
-\t\t\t\tif (val === undefined) { hasUnresolved = true; return match }
-\t\t\t\treturn encodeURIComponent(val)
-\t\t\t})
-\t\t\tif (hasUnresolved) continue
-\t\t\tresolved.push(\`\${targetMethod} \${replaced}\`)
+\t\t\ttry {
+\t\t\t\tresolved.push(\`\${targetMethod} \${this.#interpolatePath(targetPath, params, true)}\`)
+\t\t\t} catch {
+\t\t\t\t/* a param value that is not a path segment marks nothing */
+\t\t\t}
 \t\t}
 \t\treturn resolved
 \t}
@@ -3742,11 +3848,27 @@ function sdkClientPathMatchesPattern(): string {
 \t#pathMatchesPattern(concretePath: string, pattern: string): boolean {
 \t\tlet re = this.#patternRegexCache.get(pattern)
 \t\tif (!re) {
-\t\t\tconst escaped = pattern
-\t\t\t\t.replace(/:[^\\/]+/g, "\\x00")
-\t\t\t\t.replace(/[.*+?^\${}()|[\\]\\\\]/g, "\\\\$&")
-\t\t\t\t.replace(/\\x00/g, "[^/]+")
-\t\t\tre = new RegExp(\`^\${escaped}$\`)
+\t\t\tconst esc = (text: string) => text.replace(/[.*+?^\${}()|[\\]\\\\]/g, "\\\\$&")
+\t\t\tconst segments = pattern.split("/")
+\t\t\tlet source = ""
+\t\t\tfor (let i = 0; i < segments.length; i++) {
+\t\t\t\tconst seg = segments[i] ?? ""
+\t\t\t\tconst sep = i === 0 ? "" : "/"
+\t\t\t\tif (seg.length > 1 && seg.charCodeAt(0) === 58) {
+\t\t\t\t\tsource += seg.endsWith("?") ? \`(?:\${sep}[^/]+)?\` : \`\${sep}[^/]+\`
+\t\t\t\t\tcontinue
+\t\t\t\t}
+\t\t\t\tif (seg.charCodeAt(0) === 42 && i === segments.length - 1) {
+\t\t\t\t\tsource += \`(?:\${sep}.*)?\`
+\t\t\t\t\tcontinue
+\t\t\t\t}
+\t\t\t\tsource += sep + seg.split(/\\{[^{}/]+\\}/).map(esc).join("[^/]+")
+\t\t\t}
+\t\t\tre = new RegExp(\`^\${source}$\`)
+\t\t\tif (this.#patternRegexCache.size >= 1024) {
+\t\t\t\tconst oldest = this.#patternRegexCache.keys().next().value
+\t\t\t\tif (oldest !== undefined) this.#patternRegexCache.delete(oldest)
+\t\t\t}
 \t\t\tthis.#patternRegexCache.set(pattern, re)
 \t\t}
 \t\treturn re.test(concretePath)
@@ -3756,35 +3878,31 @@ function sdkClientPathMatchesPattern(): string {
 
 function sdkClientLookupStale(): string {
 	return `
+\t/* Keep in sync with client/sdk.ts StaleIndex — exact keys and pattern keys are kept apart, so a
+\t   concrete path containing ":" is never read as a pattern, and a lookup scans only its method. */
 \t#lookupStale(
 \t\tconcreteSelector: string,
 \t\tconcretePath: string,
 \t\tmethod: string,
 \t\tnow: number,
 \t): { by: string[]; isStale: boolean } {
-\t\tconst allBy: string[] = []
-
+\t\tconst by = new Set<string>()
 \t\tconst exact = this.#staleUntil?.get(concreteSelector)
-\t\tif (exact && exact.until > now) allBy.push(...exact.by)
-\t\telse if (exact) this.#staleUntil?.delete(concreteSelector)
-
-\t\tconst expired: string[] = []
-\t\tif (this.#staleUntil) {
-\t\t\tfor (const [key, entry] of this.#staleUntil) {
-\t\t\t\tif (entry.until <= now) { expired.push(key); continue }
-\t\t\t\tif (!key.includes(":")) continue
-\t\t\t\tconst spaceIdx = key.indexOf(" ")
-\t\t\t\tconst keyMethod = key.slice(0, spaceIdx)
-\t\t\t\tconst keyPattern = key.slice(spaceIdx + 1)
-\t\t\t\tif (keyMethod !== method) continue
-\t\t\t\tif (this.#pathMatchesPattern(concretePath, keyPattern)) {
-\t\t\t\t\tallBy.push(...entry.by)
+\t\tif (exact) {
+\t\t\tif (exact.until > now) for (const m of exact.by) by.add(m)
+\t\t\telse this.#staleUntil?.delete(concreteSelector)
+\t\t}
+\t\tconst table = this.#stalePatterns.get(method)
+\t\tif (table) {
+\t\t\tfor (const [key, entry] of table) {
+\t\t\t\tif (entry.until <= now) { table.delete(key); continue }
+\t\t\t\tif (entry.refreshed?.has(concretePath)) continue
+\t\t\t\tif (this.#pathMatchesPattern(concretePath, key.slice(key.indexOf(" ") + 1))) {
+\t\t\t\t\tfor (const m of entry.by) by.add(m)
 \t\t\t\t}
 \t\t\t}
-\t\t\tfor (const key of expired) this.#staleUntil.delete(key)
 \t\t}
-
-\t\treturn { by: [...new Set(allBy)], isStale: allBy.length > 0 }
+\t\treturn { by: [...by], isStale: by.size > 0 }
 \t}
 `
 }
@@ -3793,7 +3911,8 @@ function sdkClientCreateTypedWebSocket(): string {
 	return `
 \t#createTypedWebSocket(url: string, protocols?: string | string[]): _TypedWebSocket {
 \t\tconst ws = protocols ? new WebSocket(url, protocols) : new WebSocket(url)
-\t\tconst listenerMap = new WeakMap<(...args: never[]) => void, EventListener>()
+\t\t/* keyed by event and handler: one function may listen to several events */
+\t\tconst listenerMap = new Map<string, WeakMap<(...args: never[]) => void, EventListener>>()
 \t\tconst sendBuffer: Array<ArrayBuffer | ArrayBufferView | string> = []
 \t\tlet buffering = true
 
@@ -3802,10 +3921,16 @@ function sdkClientCreateTypedWebSocket(): string {
 \t\t\tfor (const msg of sendBuffer) ws.send(msg as Parameters<WebSocket["send"]>[0])
 \t\t\tsendBuffer.length = 0
 \t\t})
-
-\t\tfunction close(code?: number, reason?: string) {
+\t\t/* a socket that never opens must not hold messages forever */
+\t\tconst drop = () => {
 \t\t\tbuffering = false
 \t\t\tsendBuffer.length = 0
+\t\t}
+\t\tws.addEventListener("close", drop)
+\t\tws.addEventListener("error", drop)
+
+\t\tfunction close(code?: number, reason?: string) {
+\t\t\tdrop()
 \t\t\tws.close(code, reason)
 \t\t}
 
@@ -3813,7 +3938,7 @@ function sdkClientCreateTypedWebSocket(): string {
 \t\t\tlet wrapped: EventListener
 \t\t\tswitch (event) {
 \t\t\t\tcase "message":
-\t\t\t\t\twrapped = (e: Event) => (handler as (data: string) => void)((e as MessageEvent).data)
+\t\t\t\t\twrapped = (e: Event) => (handler as (data: unknown) => void)((e as MessageEvent).data)
 \t\t\t\t\tbreak
 \t\t\t\tcase "open":
 \t\t\t\t\twrapped = () => (handler as () => void)()
@@ -3827,28 +3952,36 @@ function sdkClientCreateTypedWebSocket(): string {
 \t\t\t\tdefault:
 \t\t\t\t\treturn
 \t\t\t}
-\t\t\tlistenerMap.set(handler, wrapped)
+\t\t\tlet byHandler = listenerMap.get(event)
+\t\t\tif (!byHandler) {
+\t\t\t\tbyHandler = new WeakMap()
+\t\t\t\tlistenerMap.set(event, byHandler)
+\t\t\t}
+\t\t\tbyHandler.set(handler, wrapped)
 \t\t\tws.addEventListener(event, wrapped)
 \t\t}
 
 \t\tfunction off(event: string, handler: (...args: never[]) => void): void {
-\t\t\tconst wrapped = listenerMap.get(handler)
+\t\t\tconst byHandler = listenerMap.get(event)
+\t\t\tconst wrapped = byHandler?.get(handler)
 \t\t\tif (wrapped) {
 \t\t\t\tws.removeEventListener(event, wrapped)
-\t\t\t\tlistenerMap.delete(handler)
+\t\t\t\tbyHandler?.delete(handler)
 \t\t\t}
 \t\t}
 
 \t\tfunction send(data: ArrayBuffer | ArrayBufferView | object | string) {
-\t\t\tlet payload: ArrayBuffer | ArrayBufferView | string
+\t\t\tlet payload: ArrayBuffer | ArrayBufferView | string | Blob
 \t\t\tif (typeof data === "string") {
 \t\t\t\tpayload = data
 \t\t\t} else if (data instanceof ArrayBuffer || ArrayBuffer.isView(data)) {
 \t\t\t\tpayload = data
+\t\t\t} else if (typeof Blob !== "undefined" && data instanceof Blob) {
+\t\t\t\tpayload = data
 \t\t\t} else {
 \t\t\t\tpayload = JSON.stringify(data)
 \t\t\t}
-\t\t\tif (buffering) { sendBuffer.push(payload) } else { ws.send(payload as Parameters<WebSocket["send"]>[0]) }
+\t\t\tif (buffering) { sendBuffer.push(payload as ArrayBuffer | ArrayBufferView | string) } else if (ws.readyState === 1) { ws.send(payload as Parameters<WebSocket["send"]>[0]) }
 \t\t}
 
 \t\tconst typed: _TypedWebSocket = { close, off, on, get readyState() { return ws.readyState }, send }
@@ -3906,12 +4039,15 @@ function sdkClientResolveBaseURL(): string {
 function sdkClientBuildURL(): string {
 	return `
 \t#buildURL(path: string, opts: _RequestOptions): string {
-\t\tlet resolvedPath = path
-\t\tif (opts.params) resolvedPath = this.#interpolatePath(path, opts.params)
+\t\tconst resolvedPath = this.#interpolatePath(path, opts.params)
 \t\tconst baseUrl = this.#resolveBaseURL(this.#config.baseURL)
 \t\tconst basePath = baseUrl.pathname.endsWith("/") ? baseUrl.pathname : \`\${baseUrl.pathname}/\`
 \t\tconst relative = resolvedPath.startsWith("/") ? resolvedPath.slice(1) : resolvedPath
 \t\tconst url = new URL(\`\${basePath}\${relative}\`, baseUrl)
+\t\t/* a request (and its credentials) never leaves the configured origin */
+\t\tif (url.origin !== baseUrl.origin) {
+\t\t\tthrow new _PathParamError(\`Invalid path param: \${JSON.stringify(path)} resolves outside \${baseUrl.origin}\`)
+\t\t}
 \t\tfor (const [k, v] of baseUrl.searchParams.entries()) url.searchParams.append(k, v)
 \t\tif (opts.search) {
 \t\t\tconst sp = this.#searchSerializer(opts.search)
@@ -3963,9 +4099,14 @@ function sdkClientBuildHeaders(): string {
 \t\t\t}
 \t\t}
 
+\t\t/* a token from onAuthExpired replaces the configured one until the next refresh */
+\t\tif (this.#token !== null) {
+\t\t\theaders.set(this.#config.authHeaderName ?? "Authorization", \`\${this.#config.authHeaderPrefix ?? "Bearer "}\${this.#token}\`)
+\t\t}
+
 \t\tif (opts.headers) {
 \t\t\tfor (const [k, v] of Object.entries(opts.headers)) {
-\t\t\t\theaders.set(k, v)
+\t\t\t\tif (v !== undefined) headers.set(k, v)
 \t\t\t}
 \t\t}
 
@@ -3990,24 +4131,16 @@ function sdkClientBuildHeaders(): string {
 
 function sdkClientDoRequest(): string {
 	return `
-\tasync #doRequest(
-\t\tmethod: string,
-\t\tpath: string,
-\t\topts: _RequestOptions,
-\t\tisRetry: boolean,
-\t\trequestMeta?: _RequestMeta,
-\t): Promise<{ response: Response }> {
-\t\tconst url = this.#buildURL(path, opts)
-\t\tconst headers = await this.#buildHeaders(opts, { method, path })
-\t\tlet body: BodyInit | undefined
-
+\t/* the body of a request, and the content-type it needs — shared by plain requests and SSE */
+\t#buildBody(opts: _RequestOptions, headers: Headers): BodyInit | undefined {
 \t\tif (opts.body !== undefined) {
-\t\t\theaders.set("content-type", "application/octet-stream")
-\t\t\tbody = opts.body as BodyInit
-\t\t} else if (opts.json !== undefined) {
+\t\t\tif (!headers.has("content-type")) headers.set("content-type", "application/octet-stream")
+\t\t\treturn opts.body as BodyInit
+\t\t}
+\t\tif (opts.json !== undefined) {
 \t\t\theaders.set("content-type", "application/json")
 \t\t\ttry {
-\t\t\t\tbody = JSON.stringify(opts.json)
+\t\t\t\treturn JSON.stringify(opts.json)
 \t\t\t} catch (e) {
 \t\t\t\tthrow new _ClientError({
 \t\t\t\t\tbody: opts.json,
@@ -4017,50 +4150,75 @@ function sdkClientDoRequest(): string {
 \t\t\t\t\tstatus: 0,
 \t\t\t\t})
 \t\t\t}
-\t\t} else if (opts.form !== undefined) {
-\t\t\tconst hasFiles = Object.values(opts.form).some(
-\t\t\t\t(v) =>
-\t\t\t\t\t(typeof File !== "undefined" && v instanceof File) ||
-\t\t\t\t\t(typeof Blob !== "undefined" && v instanceof Blob) ||
-\t\t\t\t\t(typeof FileList !== "undefined" && v instanceof FileList) ||
-\t\t\t\t\t(Array.isArray(v) &&
-\t\t\t\t\t\tv.some(
-\t\t\t\t\t\t\t(item) =>
-\t\t\t\t\t\t\t\t(typeof File !== "undefined" && item instanceof File) ||
-\t\t\t\t\t\t\t\t(typeof Blob !== "undefined" && item instanceof Blob),
-\t\t\t\t\t\t)),
-\t\t\t)
-
-\t\t\tif (hasFiles) {
-\t\t\t\tconst fd = new FormData()
-\t\t\t\tfor (const [k, v] of Object.entries(opts.form)) {
-\t\t\t\t\tif (v === undefined || v === null) continue
-\t\t\t\t\tif (typeof FileList !== "undefined" && v instanceof FileList) {
-\t\t\t\t\t\tfor (let i = 0; i < v.length; i++) { const f = v[i]; if (f) fd.append(k, f) }
-\t\t\t\t\t} else if (Array.isArray(v)) {
-\t\t\t\t\t\tfor (const item of v) {
-\t\t\t\t\t\t\tif (item instanceof File || item instanceof Blob) fd.append(k, item)
-\t\t\t\t\t\t\telse fd.append(k, String(item))
-\t\t\t\t\t\t}
-\t\t\t\t\t} else if (v instanceof File || v instanceof Blob) {
-\t\t\t\t\t\tfd.append(k, v)
-\t\t\t\t\t} else {
-\t\t\t\t\t\tfd.append(k, String(v))
-\t\t\t\t\t}
+\t\t}
+\t\tif (opts.form === undefined) return undefined
+\t\tconst isFile = (v: unknown) =>
+\t\t\t(typeof File !== "undefined" && v instanceof File) || (typeof Blob !== "undefined" && v instanceof Blob)
+\t\tconst hasFiles = Object.values(opts.form).some(
+\t\t\t(v) =>
+\t\t\t\tisFile(v) ||
+\t\t\t\t(typeof FileList !== "undefined" && v instanceof FileList) ||
+\t\t\t\t(Array.isArray(v) && v.some(isFile)),
+\t\t)
+\t\tconst text = (v: unknown): string | null => {
+\t\t\tif (v === undefined || v === null || typeof v === "symbol") return null
+\t\t\tif (v instanceof Date) return v.toISOString()
+\t\t\tif (typeof v === "object") throw new TypeError("form: nested objects cannot be form-encoded; send json instead")
+\t\t\treturn String(v)
+\t\t}
+\t\tif (hasFiles) {
+\t\t\tconst fd = new FormData()
+\t\t\tfor (const [k, v] of Object.entries(opts.form)) {
+\t\t\t\tif (typeof FileList !== "undefined" && v instanceof FileList) {
+\t\t\t\t\tfor (let i = 0; i < v.length; i++) { const f = v[i]; if (f) fd.append(k, f) }
+\t\t\t\t\tcontinue
 \t\t\t\t}
-\t\t\t\tbody = fd
-\t\t\t} else {
-\t\t\t\theaders.set("content-type", "application/x-www-form-urlencoded")
-\t\t\t\tconst sp = new URLSearchParams()
-\t\t\t\tfor (const [k, v] of Object.entries(opts.form)) {
-\t\t\t\t\tif (v === undefined || v === null) continue
-\t\t\t\t\tif (v instanceof Date) { sp.set(k, v.toISOString()); continue }
-\t\t\t\t\tif (typeof v === "symbol") continue
-\t\t\t\t\tsp.set(k, String(v))
+\t\t\t\tfor (const item of Array.isArray(v) ? v : [v]) {
+\t\t\t\t\tif (isFile(item)) fd.append(k, item as Blob)
+\t\t\t\t\telse {
+\t\t\t\t\t\tconst s = text(item)
+\t\t\t\t\t\tif (s !== null) fd.append(k, s)
+\t\t\t\t\t}
 \t\t\t\t}
-\t\t\t\tbody = sp.toString()
 \t\t\t}
+\t\t\treturn fd
+\t\t}
+\t\theaders.set("content-type", "application/x-www-form-urlencoded")
+\t\tconst sp = new URLSearchParams()
+\t\t/* arrays repeat the key, as they do in multipart and in the query */
+\t\tfor (const [k, v] of Object.entries(opts.form)) {
+\t\t\tfor (const item of Array.isArray(v) ? v : [v]) {
+\t\t\t\tconst s = text(item)
+\t\t\t\tif (s !== null) sp.append(k, s)
+\t\t\t}
+\t\t}
+\t\treturn sp.toString()
+\t}
+
+\t/* a stream body is sent once and needs duplex: "half" (Node's fetch throws without it) */
+\t#requestInit(init: RequestInit): RequestInit {
+\t\tif (typeof ReadableStream !== "undefined" && init.body instanceof ReadableStream) {
+\t\t\t;(init as RequestInit & { duplex?: string }).duplex = "half"
 \t\t}
+\t\treturn init
+\t}
+
+\t/* the Request a response hook sees; a stream body was consumed by the send, so it is left off */
+\t#hookRequest(url: string, init: RequestInit): Request {
+\t\tconst consumed = typeof ReadableStream !== "undefined" && init.body instanceof ReadableStream
+\t\treturn new Request(url, consumed ? { ...init, body: null } : init)
+\t}
+
+\tasync #doRequest(
+\t\tmethod: string,
+\t\tpath: string,
+\t\topts: _RequestOptions,
+\t\tisRetry: boolean,
+\t\trequestMeta?: _RequestMeta,
+\t): Promise<{ done: () => void; response: Response }> {
+\t\tconst url = this.#buildURL(path, opts)
+\t\tconst headers = await this.#buildHeaders(opts, { method, path })
+\t\tlet body = this.#buildBody(opts, headers)
 
 \t\tif (this.#config.onRequest) {
 \t\t\tconst reqCtx: { body?: BodyInit; headers: Headers; invalidatedBy?: string[]; isStale?: boolean; method: string; path: string; selector?: string; state: Record<string, unknown>; url: string } = { body, headers, method, path, state: this.#config.state ?? {}, url }
@@ -4076,7 +4234,7 @@ function sdkClientDoRequest(): string {
 \t\t}
 
 \t\tconst { signal, cleanup } = this.#buildSignal(opts)
-\t\tconst init: RequestInit = { body, headers, method, signal }
+\t\tconst init = this.#requestInit({ body, headers, method, signal })
 \t\tif (this.#config.credentials) init.credentials = this.#config.credentials
 \t\tif (this.#config.mode) init.mode = this.#config.mode
 
@@ -4086,7 +4244,7 @@ function sdkClientDoRequest(): string {
 
 \t\ttry {
 \t\t\tsignal?.throwIfAborted()
-\t\t\tlet response = await this.#fetchFn(url, init)
+\t\t\tlet response = await this.#send(url, init)
 
 \t\t\t/* FormData, Blob, and strings can be sent again; a stream was consumed by the first attempt */
 \t\t\tif (response.status === 401 && this.#config.onAuthExpired && !isRetry && !(body instanceof ReadableStream)) {
@@ -4094,11 +4252,12 @@ function sdkClientDoRequest(): string {
 \t\t\t\tconst authPrefix = this.#config.authHeaderPrefix ?? "Bearer "
 \t\t\t\tconst sent = new Headers(headers).get(authName)
 \t\t\t\tconst rejectedToken = sent?.startsWith(authPrefix) ? sent.slice(authPrefix.length) : (sent ?? null)
-\t\t\t\tconst newToken = await this.#config.onAuthExpired({ rejectedToken })
-\t\t\t\tif (newToken !== null && newToken !== undefined) {
+\t\t\t\tconst newToken = await this.#refreshToken(rejectedToken)
+\t\t\t\tif (newToken !== null) {
 \t\t\t\t\tconst retryHeaders = new Headers(headers)
 \t\t\t\t\tretryHeaders.set(authName, \`\${authPrefix}\${newToken}\`)
-\t\t\t\t\tresponse = await this.#fetchFn(url, { ...init, headers: retryHeaders })
+\t\t\t\t\tawait response.body?.cancel().catch(() => {})
+\t\t\t\t\tresponse = await this.#send(url, { ...init, headers: retryHeaders })
 \t\t\t\t}
 \t\t\t}
 
@@ -4115,12 +4274,14 @@ function sdkClientDoRequest(): string {
 \t\t\t\t\tisRetry,
 \t\t\t\t\tmethod,
 \t\t\t\t\tpath,
-\t\t\t\t\trequest: new Request(url, init),
+\t\t\t\t\trequest: this.#hookRequest(url, init),
 \t\t\t\t\tresponse,
 \t\t\t\t\tretry: () => {
 \t\t\t\t\t\tif (isRetry) throw new Error("Max 1 retry per request")
+\t\t\t\t\t\tif (body instanceof ReadableStream) throw new Error("A streamed request body cannot be sent again")
 \t\t\t\t\t\treturn this.#doRequest(method, path, opts, true, requestMeta)
 \t\t\t\t\t\t\t.then(async (r) => {
+\t\t\t\t\t\t\t\tr.done()
 \t\t\t\t\t\t\t\tif (!r.response.ok) throw await this.#parseAsClientError(r.response)
 \t\t\t\t\t\t\t\treturn r.response
 \t\t\t\t\t\t\t})
@@ -4142,8 +4303,10 @@ function sdkClientDoRequest(): string {
 \t\t\t\t}
 \t\t\t}
 
-\t\t\treturn { response }
+\t\t\t/* the caller releases the timer after reading the body: the timeout covers the whole exchange */
+\t\t\treturn { done: cleanup, response }
 \t\t} catch (err) {
+\t\t\tcleanup()
 \t\t\tconst _errStatus = typeof (err as { status?: unknown })?.status === "number" ? (err as { status: number }).status : undefined
 \t\t\tthis.#config.onLog?.({
 \t\t\t\tduration_ms: Date.now() - _logStart,
@@ -4154,8 +4317,82 @@ function sdkClientDoRequest(): string {
 \t\t\t\t...(_errStatus !== undefined ? { status: _errStatus } : {}),
 \t\t\t})
 \t\t\tthrow err
-\t\t} finally {
-\t\t\tcleanup()
+\t\t}
+\t}
+
+\t/* one refresh for every 401 in flight; the new token is kept for later requests */
+\t#refreshToken(rejectedToken: string | null): Promise<string | null> {
+\t\tconst hook = this.#config.onAuthExpired
+\t\tif (!hook) return Promise.resolve(null)
+\t\tif (rejectedToken !== null && this.#token !== null && rejectedToken !== this.#token) {
+\t\t\t/* another request already refreshed past the rejected token */
+\t\t\treturn Promise.resolve(this.#token)
+\t\t}
+\t\tthis.#refreshing ??= Promise.resolve()
+\t\t\t.then(() => hook({ rejectedToken }))
+\t\t\t.then((token) => {
+\t\t\t\tthis.#token = typeof token === "string" && token.length > 0 ? token : null
+\t\t\t\treturn this.#token
+\t\t\t})
+\t\t\t.finally(() => {
+\t\t\t\tthis.#refreshing = null
+\t\t\t})
+\t\treturn this.#refreshing
+\t}
+
+\t/* Same rules as client/http.ts; the cross-origin header allowlist comes from
+\t   client/redirect-policy.ts. "same-origin" (default) follows a redirect only while it stays on
+\t   the base URL's origin; "follow" also follows cross-origin ones, carrying only allowlisted
+\t   headers and never a replayed body.
+\t   Browsers hide redirect targets from script, so there the platform follows. */
+\tasync #send(url: string, init: RequestInit): Promise<Response> {
+\t\tconst policy = this.#config.redirect ?? "same-origin"
+\t\tconst g = globalThis as { document?: unknown; WorkerGlobalScope?: unknown }
+\t\tconst platformFollows = typeof g.document !== "undefined" || typeof g.WorkerGlobalScope !== "undefined"
+\t\tif (policy === "manual" || policy === "error" || platformFollows) {
+\t\t\treturn this.#fetchFn(url, policy === "same-origin" ? init : { ...init, redirect: policy })
+\t\t}
+\t\tconst origin = new URL(url).origin
+\t\tlet current = new URL(url)
+\t\tlet currentInit: RequestInit = { ...init, redirect: "manual" }
+\t\tconst replayable = (b: unknown) =>
+\t\t\tb == null || typeof b === "string" || (typeof Blob !== "undefined" && b instanceof Blob) || (typeof FormData !== "undefined" && b instanceof FormData) || b instanceof URLSearchParams || b instanceof ArrayBuffer || ArrayBuffer.isView(b)
+\t\tfor (let hop = 0; ; hop++) {
+\t\t\tconst response = await this.#fetchFn(current.toString(), currentInit)
+\t\t\tconst location = response.headers.get("location")
+\t\t\tif (![301, 302, 303, 307, 308].includes(response.status) || location === null || hop >= 20) return response
+\t\t\tlet target: URL
+\t\t\ttry {
+\t\t\t\ttarget = new URL(location, current)
+\t\t\t} catch {
+\t\t\t\treturn response
+\t\t\t}
+\t\t\tif (target.protocol !== "http:" && target.protocol !== "https:") return response
+\t\t\tconst crossOrigin = target.origin !== origin
+\t\t\tif (crossOrigin && policy !== "follow") return response
+\t\t\tconst nextInit: RequestInit = { ...currentInit, headers: new Headers(currentInit.headers) }
+\t\t\tif (response.status === 307 || response.status === 308) {
+\t\t\t\tif (currentInit.body != null && (crossOrigin || !replayable(currentInit.body))) return response
+\t\t\t} else {
+\t\t\t\tconst method = (currentInit.method ?? "GET").toUpperCase()
+\t\t\t\tif (response.status === 303 ? method !== "HEAD" : method === "POST") {
+\t\t\t\t\tnextInit.method = "GET"
+\t\t\t\t\tnextInit.body = undefined
+\t\t\t\t\t;(nextInit.headers as Headers).delete("content-type")
+\t\t\t\t}
+\t\t\t}
+\t\t\tif (crossOrigin) {
+\t\t\t\t/* only allowlisted headers cross: no credential, configured, per-call or hook header */
+\t\t\t\tconst safe = new Headers()
+\t\t\t\tfor (const name of [${CROSS_ORIGIN_SAFE_HEADERS.map((h) => JSON.stringify(h)).join(", ")}]) {
+\t\t\t\t\tconst value = (nextInit.headers as Headers).get(name)
+\t\t\t\t\tif (value !== null) safe.set(name, value)
+\t\t\t\t}
+\t\t\t\tnextInit.headers = safe
+\t\t\t}
+\t\t\tawait response.body?.cancel().catch(() => {})
+\t\t\tcurrent = target
+\t\t\tcurrentInit = nextInit
 \t\t}
 \t}
 `
@@ -4174,7 +4411,8 @@ function sdkClientParseBody(): string {
 \t\tif (ct === "application/octet-stream" || ct === "application/pdf") {
 \t\t\treturn response.arrayBuffer()
 \t\t}
-\t\tif (ct.startsWith("text/")) return response.text()
+\t\t/* the classes the generated types use: text/*, XML, otherwise bytes */
+\t\tif (ct.startsWith("text/") || ct === "application/xml" || ct.endsWith("+xml")) return response.text()
 \t\t/* unknown content type \u2014 binary-safe fallback */
 \t\treturn response.arrayBuffer()
 \t}
@@ -4258,11 +4496,13 @@ function sdkClientRequestThrow(): string {
 \t\topts: _RequestOptions,
 \t\trequestMeta?: _RequestMeta,
 \t): Promise<unknown> {
-\t\tconst { response } = await this.#doRequest(method, path, opts, false, requestMeta)
-\t\tif (!response.ok) {
-\t\t\tthrow await this.#parseAsClientError(response)
+\t\tconst { done, response } = await this.#doRequest(method, path, opts, false, requestMeta)
+\t\ttry {
+\t\t\tif (!response.ok) throw await this.#parseAsClientError(response)
+\t\t\treturn await this.#parseBody(response)
+\t\t} finally {
+\t\t\tdone()
 \t\t}
-\t\treturn this.#parseBody(response)
 \t}
 `
 }
@@ -4280,33 +4520,34 @@ function sdkClientRequestSafe(): string {
 \t\tresponse: Response
 \t\tstatus: number
 \t}> {
-\t\tlet doResponse: { response: Response }
+\t\tlet doResponse: { done: () => void; response: Response }
 \t\ttry {
 \t\t\tdoResponse = await this.#doRequest(method, path, opts, false, requestMeta)
 \t\t} catch (e) {
 \t\t\tif (e instanceof _ClientError) return { data: null, error: e, response: e.response, status: e.status }
 \t\t\tthrow e
 \t\t}
-\t\tconst { response } = doResponse
-
-\t\tif (!response.ok) {
-\t\t\tconst preserved = response.clone()
-\t\t\tconst error = await this.#parseErrorBody(response)
-\t\t\treturn {
-\t\t\t\tdata: null,
-\t\t\t\terror,
-\t\t\t\tresponse: preserved,
-\t\t\t\tstatus: response.status,
-\t\t\t}
-\t\t}
-
-\t\tlet data: unknown
+\t\tconst { done, response } = doResponse
 \t\ttry {
-\t\t\tdata = await this.#parseBody(response)
-\t\t} catch (e) {
-\t\t\treturn { data: null, error: e, response, status: response.status }
+\t\t\tif (!response.ok) {
+\t\t\t\tconst preserved = response.clone()
+\t\t\t\tconst parsed = await this.#parseErrorBody(response)
+\t\t\t\t/* a failed request always has a truthy error: the JSON body, or a ClientError for any other body */
+\t\t\t\tconst error = parsed !== undefined && parsed !== null && parsed !== false && parsed !== "" && parsed !== 0
+\t\t\t\t\t? parsed
+\t\t\t\t\t: await this.#parseAsClientError(preserved.clone())
+\t\t\t\treturn { data: null, error, response: preserved, status: response.status }
+\t\t\t}
+\t\t\tlet data: unknown
+\t\t\ttry {
+\t\t\t\tdata = await this.#parseBody(response)
+\t\t\t} catch (e) {
+\t\t\t\treturn { data: null, error: e, response, status: response.status }
+\t\t\t}
+\t\t\treturn { data, error: null, response, status: response.status }
+\t\t} finally {
+\t\t\tdone()
 \t\t}
-\t\treturn { data, error: null, response, status: response.status }
 \t}
 `
 }
@@ -4314,33 +4555,33 @@ function sdkClientRequestSafe(): string {
 function sdkClientRequest(): string {
 	return `
 \tasync #request(entry: _ServiceEntry, input: Record<string, unknown>): Promise<unknown> {
-\t\tconst path = this.#toColonParams(entry.path)
+\t\tconst path = this.#toColonParams(entry.path, entry.wildcard)
 \t\tconst method = entry.method
-\t\tconst opts = input as _RequestOptions
+\t\t/* a copy: the caller's input object is never written to, so reusing it never reuses a key */
+\t\tconst opts = { ...input } as _RequestOptions
 \t\tif (entry.idempotent) {
 \t\t\tconst existing = opts.headers?.["Idempotency-Key"] ?? opts.headers?.["idempotency-key"]
 \t\t\tif (existing === undefined) {
-\t\t\t\tconst key = opts.idempotencyKey ?? crypto.randomUUID()
+\t\t\t\tconst key = opts.idempotencyKey ?? this.#newRequestId()
 \t\t\t\topts.headers = { ...(opts.headers ?? {}), "Idempotency-Key": key }
 \t\t\t}
 \t\t}
 \t\tconst params = opts.params
-\t\tif (entry.params) {
-\t\t\tfor (const p of entry.params) {
-\t\t\t\tif (!params || params[p] === undefined) {
-\t\t\t\t\tconst err = new _ClientError({
-\t\t\t\t\t\tbody: null,
-\t\t\t\t\t\tdata: null,
-\t\t\t\t\t\tmessage: \`Missing required path param \\\`\${p}\\\` for \${method} \${entry.path}\`,
-\t\t\t\t\t\tresponse: new Response(null, { status: 0 }),
-\t\t\t\t\t\tstatus: 0,
-\t\t\t\t\t})
-\t\t\t\t\tif (!this.#config.throwOnError) return { data: null, error: err, response: err.response, status: 0 }
-\t\t\t\t\tthrow err
-\t\t\t\t}
-\t\t\t}
+\t\tlet cp: string
+\t\ttry {
+\t\t\tcp = this.#interpolatePath(path, params)
+\t\t} catch (e) {
+\t\t\tif (!(e instanceof _PathParamError)) throw e
+\t\t\tconst err = new _ClientError({
+\t\t\t\tbody: null,
+\t\t\t\tdata: null,
+\t\t\t\tmessage: \`\${e.message} for \${method} \${entry.path}\`,
+\t\t\t\tresponse: Response.error(),
+\t\t\t\tstatus: 0,
+\t\t\t})
+\t\t\tif (!this.#config.throwOnError) return { data: null, error: err, response: err.response, status: 0 }
+\t\t\tthrow err
 \t\t}
-\t\tconst cp = params ? this.#interpolatePath(path, params) : path
 \t\tconst cs = \`\${method} \${cp}\`
 \t\tconst requestMeta = this.#buildRequestMeta(cs, cp, method)
 \t\tif (!this.#config.throwOnError) {
@@ -4370,16 +4611,16 @@ function sdkClientRequestSSE(): string {
 function sdkClientConnectWS(): string {
 	return `
 \t#connectWS(entry: _ServiceEntry, path: string, opts: _RequestOptions): _TypedWebSocket {
-\t\tlet url = this.#buildURL(path, opts).replace(/^https:\\/\\//, "wss://").replace(/^http:\\/\\//, "ws://")
-\t\tif (opts.reconnectToken) {
-\t\t\tconst sep = url.includes("?") ? "&" : "?"
-\t\t\turl = \`\${url}\${sep}reconnect_token=\${encodeURIComponent(opts.reconnectToken)}\`
-\t\t}
-\t\tconst ws = this.#createTypedWebSocket(url, opts.protocols)
+\t\tconst built = new URL(this.#buildURL(path, opts))
+\t\t/* only the scheme changes: an https URL elsewhere in the query is left alone */
+\t\tif (built.protocol === "https:") built.protocol = "wss:"
+\t\telse if (built.protocol === "http:") built.protocol = "ws:"
+\t\tif (opts.reconnectToken) built.searchParams.append("reconnect_token", opts.reconnectToken)
+\t\tconst ws = this.#createTypedWebSocket(built.toString(), opts.protocols)
 \t\tif (entry.invalidate && entry.invalidate.length > 0) {
 \t\t\tconst invalidate = entry.invalidate
 \t\t\tconst params = opts.params
-\t\t\tconst cs = \`WS \${params ? this.#interpolatePath(path, params) : path}\`
+\t\t\tconst cs = \`WS \${this.#interpolatePath(path, params)}\`
 \t\t\tws.on("open", () => this.#markStale(invalidate, params, cs))
 \t\t}
 \t\treturn ws
@@ -4401,43 +4642,66 @@ function sdkClientBuildRequestMeta(): string {
 function sdkClientMarkStale(): string {
 	return `
 \t#markStale(invalidate: readonly string[], params: Record<string, string> | undefined, mutationSelector: string): void {
-\t\tif (!this.#staleUntil || invalidate.length === 0) return
+\t\tconst exactTable = this.#staleUntil
+\t\tif (!exactTable || invalidate.length === 0) return
 \t\tconst seq = ++this.#invalidationSeq
 \t\tconst until = Date.now() + this.#staleTime
-\t\tconst resolved = this.#resolveInvalidationTargets(invalidate, params)
-\t\tfor (const target of resolved) {
-\t\t\tconst existing = this.#staleUntil.get(target)
+\t\tfor (const target of this.#resolveInvalidationTargets(invalidate, params)) {
+\t\t\tconst spaceIdx = target.indexOf(" ")
+\t\t\tconst method = target.slice(0, spaceIdx)
+\t\t\tconst isPattern = this.#hasPlaceholder(target.slice(spaceIdx + 1))
+\t\t\tlet table: Map<string, _StaleEntry>
+\t\t\tif (isPattern) {
+\t\t\t\ttable = this.#stalePatterns.get(method) ?? new Map<string, _StaleEntry>()
+\t\t\t\tthis.#stalePatterns.set(method, table)
+\t\t\t} else {
+\t\t\t\ttable = exactTable
+\t\t\t}
+\t\t\tconst existing = table.get(target)
 \t\t\tif (existing) {
-\t\t\t\tif (!existing.by.includes(mutationSelector) && existing.by.length < this.#maxSourcesPerTarget) existing.by.push(mutationSelector)
+\t\t\t\tif (!existing.by.includes(mutationSelector)) {
+\t\t\t\t\texisting.by.push(mutationSelector)
+\t\t\t\t\tif (existing.by.length > this.#maxSourcesPerTarget) existing.by.shift()
+\t\t\t\t}
 \t\t\t\texisting.until = until
 \t\t\t\texisting.seq = seq
-\t\t\t} else { this.#staleUntil.set(target, { by: [mutationSelector], seq, until }) }
+\t\t\t\t/* a new mutation re-marks every instance */
+\t\t\t\texisting.refreshed?.clear()
+\t\t\t} else {
+\t\t\t\ttable.set(target, { by: [mutationSelector], refreshed: isPattern ? new Set<string>() : undefined, seq, until })
+\t\t\t}
+\t\t}
+\t\tif (exactTable.size > this.#staleMaxEntries) {
+\t\t\tconst now = Date.now()
+\t\t\tfor (const [k, entry] of exactTable) if (entry.until <= now) exactTable.delete(k)
+\t\t\t/* still over: drop the oldest marks */
+\t\t\tfor (const k of exactTable.keys()) {
+\t\t\t\tif (exactTable.size <= this.#staleMaxEntries) break
+\t\t\t\texactTable.delete(k)
+\t\t\t}
 \t\t}
-\t\tif (this.#staleUntil.size > this.#staleMaxEntries)
-\t\t\tfor (const [k, entry] of this.#staleUntil)
-\t\t\t\tif (entry.until <= Date.now()) this.#staleUntil.delete(k)
 \t}
 `
 }
 
 function sdkClientClearStale(): string {
 	return `
+\t/* a successful stale read clears that resource only: its exact mark, and this path's share of a pattern mark */
 \t#clearStale(concreteSelector: string, concretePath: string, method: string, seqSnapshot: number): void {
 \t\tif (!this.#staleUntil) return
 \t\tconst exact = this.#staleUntil.get(concreteSelector)
 \t\tif (exact && exact.seq <= seqSnapshot) this.#staleUntil.delete(concreteSelector)
-\t\tconst toDelete: string[] = []
-\t\tfor (const [key, entry] of this.#staleUntil) {
-\t\t\tif (entry.seq > seqSnapshot) continue
-\t\t\tif (!key.includes(":")) continue
-\t\t\tconst spaceIdx = key.indexOf(" ")
-\t\t\tconst keyMethod = key.slice(0, spaceIdx)
-\t\t\tconst keyPattern = key.slice(spaceIdx + 1)
-\t\t\tif (keyMethod === method && this.#pathMatchesPattern(concretePath, keyPattern)) {
-\t\t\t\ttoDelete.push(key)
+\t\tconst table = this.#stalePatterns.get(method)
+\t\tif (!table) return
+\t\tfor (const [key, entry] of table) {
+\t\t\tif (entry.seq > seqSnapshot || !entry.refreshed) continue
+\t\t\tif (!this.#pathMatchesPattern(concretePath, key.slice(key.indexOf(" ") + 1))) continue
+\t\t\tif (entry.refreshed.size >= 1024) {
+\t\t\t\tconst oldest = entry.refreshed.values().next().value
+\t\t\t\tif (oldest !== undefined) entry.refreshed.delete(oldest)
 \t\t\t}
+\t\t\tentry.refreshed.add(concretePath)
 \t\t}
-\t\tfor (const key of toDelete) this.#staleUntil.delete(key)
 \t}
 `
 }
@@ -4449,6 +4713,7 @@ function sdkClientDispose(): string {
 \t\tthis.#disposed = true
 \t\tthis.#disposeCtrl.abort()
 \t\tthis.#staleUntil?.clear()
+\t\tthis.#stalePatterns.clear()
 \t\tthis.#resourceCache.clear()
 \t\tthis.#patternRegexCache.clear()
 \t}
@@ -4465,23 +4730,25 @@ function sdkClientDoSSE(): string {
 \t\tif (opts.lastEventId) {
 \t\t\theaders.set("last-event-id", opts.lastEventId)
 \t\t}
+\t\t/* a streamed operation carries its body like any other request */
+\t\tlet body = this.#buildBody(opts, headers)
 \t\tconst { signal, cleanup } = this.#buildSignal(opts, true)
-\t\tlet reader: ReadableStreamDefaultReader<Uint8Array> | undefined
 \t\ttry {
 \t\t\tif (this.#config.onRequest) {
-\t\t\t\tconst reqCtx: { headers: Headers; invalidatedBy?: string[]; isStale?: boolean; method: string; path: string; selector?: string; state: Record<string, unknown>; url: string } = { headers, method, path, state: this.#config.state ?? {}, url }
+\t\t\t\tconst reqCtx: { body?: BodyInit; headers: Headers; invalidatedBy?: string[]; isStale?: boolean; method: string; path: string; selector?: string; state: Record<string, unknown>; url: string } = { body, headers, method, path, state: this.#config.state ?? {}, url }
 \t\t\t\tfor (const hook of this.#config.onRequest) {
 \t\t\t\t\tawait hook(reqCtx)
 \t\t\t\t}
+\t\t\t\tif (reqCtx.body !== body) body = reqCtx.body
 \t\t\t}
-\t\t\tconst sseInit: RequestInit = { headers, method, signal }
+\t\t\tconst sseInit = this.#requestInit({ body, headers, method, signal })
 \t\t\tif (this.#config.credentials) sseInit.credentials = this.#config.credentials
 \t\t\tif (this.#config.mode) sseInit.mode = this.#config.mode
 \t\t\tsignal?.throwIfAborted()
 \t\t\tlet response = await this.#fetchFn(url, sseInit)
 \t\t\tif (this.#config.onResponse) {
 \t\t\t\tconst resCtx: { invalidatedBy?: string[]; isRetry: boolean; isStale?: boolean; method: string; path: string; request: Request; response: Response; retry: () => Promise<Response>; selector?: string; state: Record<string, unknown>; url: string } = {
-\t\t\t\t\tisRetry: false, method, path, request: new Request(url, sseInit), response,
+\t\t\t\t\tisRetry: false, method, path, request: this.#hookRequest(url, sseInit), response,
 \t\t\t\t\tretry: () => { throw new Error("SSE streams do not support retry") },
 \t\t\t\t\tstate: this.#config.state ?? {}, url,
 \t\t\t\t}
@@ -4494,36 +4761,12 @@ function sdkClientDoSSE(): string {
 \t\t\t\tthrow await this.#parseAsClientError(response)
 \t\t\t}
 \t\t\tif (entry.invalidate && entry.invalidate.length > 0) {
-\t\t\t\tconst cs = \`\${method} \${opts.params ? this.#interpolatePath(path, opts.params) : path}\`
+\t\t\t\tconst cs = \`\${method} \${this.#interpolatePath(path, opts.params)}\`
 \t\t\t\tthis.#markStale(entry.invalidate, opts.params, cs)
 \t\t\t}
 \t\t\tif (!response.body) return
-\t\t\tconst decoder = new TextDecoder()
-\t\t\treader = response.body.getReader()
-\t\t\tlet buffer = ""
-\t\t\tconst maxBuffer = this.#sseMaxBufferChars
-\t\t\twhile (true) {
-\t\t\t\tconst { done, value } = await reader.read()
-\t\t\t\tif (done) break
-\t\t\t\tbuffer += decoder.decode(value, { stream: true })
-\t\t\t\tif (buffer.length > maxBuffer) throw new Error(\`SSE buffer exceeded \${maxBuffer} characters\`)
-\t\t\t\tconst blocks = buffer.split(/\\r\\n\\r\\n|\\r\\n\\r|\\r\\n\\n|\\r\\r\\n|\\n\\r\\n|\\n\\r|\\r\\r|\\n\\n/)
-\t\t\t\tbuffer = blocks.pop() ?? ""
-\t\t\t\tfor (const block of blocks) {
-\t\t\t\t\tif (block.trim() === "") continue
-\t\t\t\t\tconst event = this.#parseSSEBlock(block)
-\t\t\t\t\tif (event) yield event
-\t\t\t\t}
-\t\t\t}
-\t\t\tif (buffer.trim() !== "") {
-\t\t\t\tconst event = this.#parseSSEBlock(buffer)
-\t\t\t\tif (event) yield event
-\t\t\t}
+\t\t\tyield* this.#parseSSE(response.body)
 \t\t} finally {
-\t\t\tif (reader) {
-\t\t\t\ttry { await reader.cancel() } catch {}
-\t\t\t\treader.releaseLock()
-\t\t\t}
 \t\t\tcleanup()
 \t\t}
 \t}
@@ -4532,50 +4775,101 @@ function sdkClientDoSSE(): string {
 
 function sdkClientParseSSEBlock(): string {
 	return `
-\t#parseSSEBlock(block: string): _SSEEvent | undefined {
-\t\tconst lines = block.split(/\\r\\n|\\r|\\n/)
-\t\tlet isComment = true
-\t\tlet data: string | undefined
+\t/* Keep in sync with client/sse.ts — the WHATWG event-stream rules: lines end at CRLF, LF or CR;
+\t   a leading BOM is skipped; id is sticky and ignored if it holds NUL; retry is digits only; an
+\t   event still open when the stream ends is discarded, never dispatched. */
+\tasync *#parseSSE(stream: ReadableStream<Uint8Array>): AsyncGenerator<_SSEEvent> {
+\t\tconst decoder = new TextDecoder()
+\t\tconst reader = stream.getReader()
+\t\tconst maxBuffer = this.#sseMaxBufferChars
+\t\tlet pending = ""
+\t\tlet first = true
+\t\tlet data: string[] = []
+\t\tlet dataSize = 0
+\t\tlet hasData = false
 \t\tlet event: string | undefined
-\t\tlet id: string | undefined
+\t\tlet lastId = ""
 \t\tlet retry: number | undefined
-\t\tfor (const line of lines) {
-\t\t\tif (line.startsWith(":")) continue
-\t\t\tisComment = false
-\t\t\tconst colonIdx = line.indexOf(":")
-\t\t\tlet field: string
-\t\t\tlet val: string
-\t\t\tif (colonIdx === -1) {
-\t\t\t\tfield = line
-\t\t\t\tval = ""
-\t\t\t} else {
-\t\t\t\tfield = line.slice(0, colonIdx)
-\t\t\t\tval = line.slice(colonIdx + 1)
-\t\t\t\tif (val.startsWith(" ")) val = val.slice(1)
+\t\tconst dispatch = (): _SSEEvent | undefined => {
+\t\t\tconst out: _SSEEvent | undefined = hasData ? { data: data.join("\\n") } : undefined
+\t\t\tif (out) {
+\t\t\t\tif (event !== undefined && event !== "") out.event = event
+\t\t\t\tif (lastId !== "") out.id = lastId
+\t\t\t\tif (retry !== undefined) out.retry = retry
+\t\t\t\tretry = undefined
 \t\t\t}
+\t\t\tdata = []
+\t\t\tdataSize = 0
+\t\t\thasData = false
+\t\t\tevent = undefined
+\t\t\treturn out
+\t\t}
+\t\tconst processLine = (line: string): void => {
+\t\t\tif (line.charCodeAt(0) === 58) return
+\t\t\tconst colon = line.indexOf(":")
+\t\t\tconst field = colon === -1 ? line : line.slice(0, colon)
+\t\t\tlet value = colon === -1 ? "" : line.slice(colon + 1)
+\t\t\tif (value.charCodeAt(0) === 32) value = value.slice(1)
 \t\t\tswitch (field) {
 \t\t\t\tcase "data":
-\t\t\t\t\tdata = data === undefined ? val : \`\${data}\\n\${val}\`
+\t\t\t\t\tdataSize += value.length + 1
+\t\t\t\t\tif (dataSize > maxBuffer) throw new Error(\`SSE event exceeded \${maxBuffer} characters\`)
+\t\t\t\t\tdata.push(value)
+\t\t\t\t\thasData = true
 \t\t\t\t\tbreak
 \t\t\t\tcase "event":
-\t\t\t\t\tevent = val
+\t\t\t\t\tevent = value
 \t\t\t\t\tbreak
 \t\t\t\tcase "id":
-\t\t\t\t\tif (!val.includes("\\0")) id = val
+\t\t\t\t\tif (!value.includes("\\0")) lastId = value
 \t\t\t\t\tbreak
-\t\t\t\tcase "retry": {
-\t\t\t\t\tconst nr = Number(val)
-\t\t\t\t\tif (Number.isFinite(nr) && nr >= 0) retry = nr
+\t\t\t\tcase "retry":
+\t\t\t\t\tif (/^\\d+$/.test(value)) retry = Number(value)
 \t\t\t\t\tbreak
+\t\t\t}
+\t\t}
+\t\ttry {
+\t\t\twhile (true) {
+\t\t\t\tconst { done, value } = await reader.read()
+\t\t\t\tif (done) break
+\t\t\t\tpending += decoder.decode(value, { stream: true })
+\t\t\t\tif (first && pending.length > 0) {
+\t\t\t\t\tif (pending.charCodeAt(0) === 0xfeff) pending = pending.slice(1)
+\t\t\t\t\tfirst = false
+\t\t\t\t}
+\t\t\t\tlet start = 0
+\t\t\t\twhile (start < pending.length) {
+\t\t\t\t\tlet end = start
+\t\t\t\t\twhile (end < pending.length) {
+\t\t\t\t\t\tconst c = pending.charCodeAt(end)
+\t\t\t\t\t\tif (c === 10 || c === 13) break
+\t\t\t\t\t\tend++
+\t\t\t\t\t}
+\t\t\t\t\tif (end === pending.length) break
+\t\t\t\t\t/* a CR as the last character may be the first half of CRLF */
+\t\t\t\t\tif (pending.charCodeAt(end) === 13 && end === pending.length - 1) break
+\t\t\t\t\tconst line = pending.slice(start, end)
+\t\t\t\t\tstart = end + (pending.charCodeAt(end) === 13 && pending.charCodeAt(end + 1) === 10 ? 2 : 1)
+\t\t\t\t\tif (line === "") {
+\t\t\t\t\t\tconst out = dispatch()
+\t\t\t\t\t\tif (out) yield out
+\t\t\t\t\t} else {
+\t\t\t\t\t\tprocessLine(line)
+\t\t\t\t\t}
 \t\t\t\t}
+\t\t\t\tpending = pending.slice(start)
+\t\t\t\tif (pending.length > maxBuffer) throw new Error(\`SSE buffer exceeded \${maxBuffer} characters\`)
+\t\t\t}
+\t\t\t/* a lone CR held back at the end of the stream still terminates its line */
+\t\t\tif (pending === "\\r") {
+\t\t\t\tconst out = dispatch()
+\t\t\t\tif (out) yield out
 \t\t\t}
+\t\t\t/* anything else still open is an incomplete event: discard it */
+\t\t} finally {
+\t\t\tawait reader.cancel().catch(() => {})
+\t\t\treader.releaseLock()
 \t\t}
-\t\tif (isComment || data === undefined) return undefined
-\t\tconst evt: _SSEEvent = { data }
-\t\tif (event !== undefined) evt.event = event
-\t\tif (id !== undefined) evt.id = id
-\t\tif (retry !== undefined) evt.retry = retry
-\t\treturn evt
 \t}
 `
 }
@@ -4596,108 +4890,152 @@ export function isClientError(e: unknown): e is _ClientError {
 `
 }
 
-export function collectSDKMethods(spec: OpenApiSpecInput): {
+/** The IR every TypeScript SDK emitter reads: refs inlined, derived ids, duplicate ids refused. */
+export function sdkIR(spec: OpenApiSpecInput): IR {
+	return toIR(resolveRefs(spec), { deriveOperationIds: true, duplicateOperationIds: "throw" })
+}
+
+/** Flat `resource → action → entry` map of every operation, for SDK result objects. */
+export function serviceMapOf(ir: IR): Record<string, Record<string, ServiceEntry>> {
+	/* null-prototype: an operationId of "__proto__.x" must not reach Object.prototype */
+	const serviceMap: Record<string, Record<string, ServiceEntry>> = Object.create(null)
+	for (const op of ir.operations) {
+		const segments = op.id.split(".")
+		const resource = segments.length === 1 ? op.id : (segments[0] ?? op.id)
+		const action = segments.length === 1 ? "_call" : segments.slice(1).join(".")
+		if (!Object.hasOwn(serviceMap, resource)) serviceMap[resource] = Object.create(null)
+		serviceMap[resource][action] = buildServiceEntryForOp(op)
+	}
+	return serviceMap
+}
+
+export function collectSDKMethods(
+	spec: OpenApiSpecInput,
+	/* toIR validates namespace collisions; an operation without an operationId gets a derived
+	   one instead of silently vanishing from the SDK */
+	ir = sdkIR(spec),
+): {
 	serviceMap: Record<string, Record<string, ServiceEntry>>
 	nestedMap: Map<string, NestedServiceNode>
 	methods: SDKMethod[]
 } {
-	/* toIR validates duplicates + collision; throws before any codegen runs */
-	const ir = toIR(spec)
-	const resolved = resolveRefs(spec)
-	const serviceMap: Record<string, Record<string, ServiceEntry>> = {}
+	const resolve = irResolver(ir.schemas)
 	const methods: SDKMethod[] = []
 
-	for (const [path, pathMethods] of Object.entries(resolved.paths)) {
-		for (const [method, operation] of Object.entries(pathMethods)) {
-			const op = operation as Record<string, unknown>
-			const operationId = op.operationId as string | undefined
-			if (!operationId) continue
-
-			const segments = operationId.split(".")
-			const isTopLevel = segments.length === 1
-			const resource = isTopLevel ? operationId : (segments[0] ?? operationId)
-			const action = isTopLevel ? "_call" : segments.slice(1).join(".")
-
-			if (serviceMap[resource] === undefined) {
-				serviceMap[resource] = {}
-			}
-
-			const params = extractOpenApiPathParams(path)
-			const entry: ServiceEntry = {
-				method: method.toUpperCase(),
-				path,
-			}
-			if (params.length > 0) entry.params = params
-			const sse = isSSEOperation(op)
-			if (sse) entry.sse = true
-			if (op["x-websocket"] === true) entry.ws = true
-			if (op["x-realtime"] === true) entry.realtime = true
-			if (op["x-idempotency-key"] === true) entry.idempotent = true
-			const xinv = op["x-invalidate"]
-			if (Array.isArray(xinv) && xinv.length > 0) entry.invalidate = xinv as string[]
-
-			serviceMap[resource][action] = entry
-			const isWs = op["x-websocket"] === true
-			const isRealtime = op["x-realtime"] === true
-			const inputResult = emitSDKInputType(op, path)
-			methods.push({
-				action,
-				errorsByStatusType: emitSDKErrorsByStatusType(op),
-				inputHasMandatory: inputResult.hasMandatory,
-				inputType: inputResult.type,
-				realtime: isRealtime,
-				resource,
-				responseType: emitSDKResponseType(op),
-				sse,
-				ws: isWs,
-			})
-		}
+	for (const op of ir.operations) {
+		const operationId = op.id
+		const segments = operationId.split(".")
+		const isTopLevel = segments.length === 1
+		const resource = isTopLevel ? operationId : (segments[0] ?? operationId)
+		const action = isTopLevel ? "_call" : segments.slice(1).join(".")
+
+		const inputResult = emitSDKInputType(op)
+		methods.push({
+			action,
+			errorsByStatusType: emitSDKErrorsByStatusType(op, resolve),
+			id: operationId,
+			inputHasMandatory: inputResult.hasMandatory,
+			inputType: inputResult.type,
+			realtime: op.extensions.realtime === true,
+			resource,
+			responseType: emitSDKResponseType(op),
+			sse: op.extensions.sse === true,
+			ws: op.extensions.websocket === true,
+		})
 	}
 
-	const nestedMap = buildNestedServiceMap(ir.tree, resolved, spec)
-	return { methods, nestedMap, serviceMap }
+	const nestedMap = buildNestedServiceMap(safeMemberTree(ir.tree, true))
+	return { methods, nestedMap, serviceMap: serviceMapOf(ir) }
 }
 
-function buildServiceEntryForOp(op: Record<string, unknown>, path: string, method: string): ServiceEntry {
-	const params = extractOpenApiPathParams(path)
-	const entry: ServiceEntry = { method: method.toUpperCase(), path }
+function buildServiceEntryForOp(op: IROperation): ServiceEntry {
+	const params = openApiPathParams(op.path)
+	const entry: ServiceEntry = { method: op.method, path: op.path }
 	if (params.length > 0) entry.params = params
-	const sse = isSSEOperation(op)
-	if (sse) entry.sse = true
-	if (op["x-websocket"] === true) entry.ws = true
-	if (op["x-realtime"] === true) entry.realtime = true
-	if (op["x-idempotency-key"] === true) entry.idempotent = true
-	const xinv = op["x-invalidate"]
-	if (Array.isArray(xinv) && xinv.length > 0) entry.invalidate = xinv as string[]
+	const wildcard = op.params.path.find((p) => p.wildcard === true)
+	if (wildcard) entry.wildcard = wildcard.name
+	if (op.extensions.sse) entry.sse = true
+	if (op.extensions.websocket) entry.ws = true
+	if (op.extensions.realtime) entry.realtime = true
+	if (op.extensions.idempotencyKey) entry.idempotent = true
+	const inv = op.extensions.invalidates
+	if (inv && inv.length > 0) entry.invalidate = inv
 	return entry
 }
 
-function buildNestedServiceMap(
-	ns: IRNamespace,
-	resolved: ReturnType<typeof resolveRefs>,
-	_spec: OpenApiSpecInput,
-): Map<string, NestedServiceNode> {
-	/* build a lookup from operationId → (op record, path, method) for leaf nodes */
-	const opLookup = new Map<string, { op: Record<string, unknown>; path: string; method: string }>()
-	for (const [path, pathMethods] of Object.entries(resolved.paths)) {
-		for (const [method, operation] of Object.entries(pathMethods)) {
-			const op = operation as Record<string, unknown>
-			const operationId = op.operationId as string | undefined
-			if (operationId) opLookup.set(operationId, { method, op, path })
+/** Members a generated client already has; a resource of the same name would hide them. */
+const SDK_ROOT_MEMBERS = new Set(["dispose", "state"])
+
+/**
+ * Names JavaScript machinery reads off any object: a `then` member makes the client a
+ * thenable, `toString` breaks `String(sdk)`, `__proto__` sets the prototype.
+ */
+const SDK_OBJECT_MEMBERS = new Set([
+	"__defineGetter__",
+	"__defineSetter__",
+	"__lookupGetter__",
+	"__lookupSetter__",
+	"__proto__",
+	"constructor",
+	"hasOwnProperty",
+	"isPrototypeOf",
+	"propertyIsEnumerable",
+	"then",
+	"toJSON",
+	"toLocaleString",
+	"toString",
+	"valueOf",
+])
+
+/**
+ * The resource tree with every member name a client can expose. A name that would shadow a
+ * client member or an `Object.prototype` name gets a trailing `_` (`state` → `state_`), the
+ * same rename in the interface and the service map, so types and runtime agree.
+ */
+function safeMemberTree(ns: IRNamespace, root: boolean): IRNamespace {
+	const entries = new Map<string, IRNamespace["entries"] extends Map<string, infer E> ? E : never>()
+	const sorted = [...ns.entries.entries()].sort(([a], [b]) => compareCodeUnits(a, b))
+	for (const [key, entry] of sorted) {
+		let name = key
+		if ((root && SDK_ROOT_MEMBERS.has(key)) || SDK_OBJECT_MEMBERS.has(key)) {
+			name = `${key}_`
+			while (ns.entries.has(name) || entries.has(name)) name += "_"
+		}
+		entries.set(name, entry.kind === "namespace" ? { kind: "namespace", ns: safeMemberTree(entry.ns, false) } : entry)
+	}
+	return { entries }
+}
+
+/**
+ * The member path of every operation on a generated TypeScript client, after the renames
+ * `safeMemberTree` applies: `["state_", "get"]` for an operation `state.get`. A namespace whose
+ * only method is `_call` is callable itself, so its path ends at the namespace.
+ */
+export function sdkMemberPaths(ir: IR): Map<string, string[]> {
+	const out = new Map<string, string[]>()
+	const walk = (ns: IRNamespace, prefix: string[]): void => {
+		const methods = methodsOf(ns)
+		for (const [key, entry] of ns.entries) {
+			if (entry.kind === "namespace") {
+				walk(entry.ns, [...prefix, key])
+			} else if (key !== "_call") {
+				out.set(entry.op.id, [...prefix, key])
+			} else if (methods.length === 1) {
+				/* the interface promotes a lone `_call` to the namespace itself and drops any other */
+				out.set(entry.op.id, prefix)
+			}
 		}
 	}
+	walk(safeMemberTree(ir.tree, true), [])
+	return out
+}
 
+function buildNestedServiceMap(ns: IRNamespace): Map<string, NestedServiceNode> {
 	function walkNs(namespace: IRNamespace): Map<string, NestedServiceNode> {
 		const map = new Map<string, NestedServiceNode>()
-		for (const [key, entry] of [...namespace.entries.entries()].sort(([a], [b]) => a.localeCompare(b))) {
-			if (entry.kind === "method") {
-				const found = opLookup.get(entry.op.id)
-				if (!found) continue
-				const serviceEntry = buildServiceEntryForOp(found.op, found.path, found.method)
-				map.set(key, { entry: serviceEntry, kind: "leaf" })
-			} else {
-				map.set(key, { children: walkNs(entry.ns), kind: "ns" })
-			}
+		for (const [key, entry] of [...namespace.entries.entries()].sort(([a], [b]) => compareCodeUnits(a, b))) {
+			if (entry.kind === "method") map.set(key, { entry: buildServiceEntryForOp(entry.op), kind: "leaf" })
+			else map.set(key, { children: walkNs(entry.ns), kind: "ns" })
 		}
 		return map
 	}
@@ -4705,19 +5043,29 @@ function buildNestedServiceMap(
 	return walkNs(ns)
 }
 
+const TS_IDENTIFIER = /^[A-Za-z_$][A-Za-z0-9_$]*$/
+
+/** The SDK class name lands in source, the stem in import specifiers and file names. */
+function validateSdkNames(name: string, stem: string): void {
+	if (!TS_IDENTIFIER.test(name) || SDK_TS_RESERVED.has(name)) {
+		throw new Error(`generateSDK: name ${JSON.stringify(name)} is not a TypeScript identifier`)
+	}
+	if (!/^[A-Za-z0-9_-][A-Za-z0-9._-]*$/.test(stem)) {
+		throw new Error(
+			`generateSDK: stem ${JSON.stringify(stem)} must be a plain file name (letters, digits, ".", "_", "-")`,
+		)
+	}
+}
+
 export function generateSDK(spec: OpenApiSpecInput, options?: { name?: string; stem?: string }): GeneratedSDK {
 	const sdkName = options?.name ?? "SDK"
 	const stem = options?.stem ?? "sdk"
-	const { methods: sdkMethods, nestedMap, serviceMap } = collectSDKMethods(spec)
+	validateSdkNames(sdkName, stem)
+	const ir = sdkIR(spec)
+	const { methods: sdkMethods, nestedMap, serviceMap } = collectSDKMethods(spec, ir)
 	const hasRealtime = sdkMethods.some((m) => m.realtime)
-
-	const ir = toIR(spec)
-	/* lookup by full operationId — action is already the rest after first segment, joined with "." */
 	const fullMethodLookup = new Map<string, SDKMethod>()
-	for (const m of sdkMethods) {
-		const opId = m.action === "_call" ? m.resource : `${m.resource}.${m.action}`
-		fullMethodLookup.set(opId, m)
-	}
+	for (const m of sdkMethods) fullMethodLookup.set(m.id, m)
 
 	return {
 		files: {
@@ -4725,7 +5073,7 @@ export function generateSDK(spec: OpenApiSpecInput, options?: { name?: string; s
 			index: buildSDKIndex(sdkName, stem),
 			map: buildSDKMap(nestedMap),
 			runtime: hasRealtime ? buildSDKRuntime() : null,
-			types: buildSDKTypes(sdkName, sdkMethods, ir.tree, fullMethodLookup),
+			types: buildSDKTypes(sdkName, sdkMethods, safeMemberTree(ir.tree, true), fullMethodLookup),
 		},
 		serviceMap,
 	}