@lovrozagar/honey 0.6.5 → 0.7.0

package/src/index.ts

@@ -1,23 +1,52 @@
-import { HoneyContext } from "./context.ts"
+import { bodyKind, headResponse, isProducedStream, rawBodyOf } from "./body-kind.ts"
+import { clientInfo, HoneyContext } from "./context.ts"
+import { dict } from "./dict.ts"
+import { normalizePath, pathOfUrl, searchOfUrl } from "./request-path.ts"
+import { BUN_URL_FROM_HOST, hasValidHost, TRUST_OFF, type TrustSetting } from "./client-info.ts"
+import type { TrustProxy } from "./trust.ts"
+import { loadFeature, requireFeature } from "./feature-slots.ts"
 import { HoneyError } from "./error.ts"
 import { ERROR_META } from "./errors.ts"
-import type { MiddlewareFn, RuntimeMiddleware } from "./middleware.ts"
-import { collectMiddlewareMeta } from "./middleware.ts"
-import { compileChain, executeChain } from "./middleware.ts"
+import type { ChainErrorConverter, MiddlewareFn, RuntimeMiddleware } from "./middleware.ts"
+import { collectMiddlewareMeta, compileChain, RESERVED_CTX_KEYS } from "./middleware.ts"
 import type { ProxyConfig } from "./proxy.ts"
-import { createProxyHandler } from "./proxy.ts"
 import type { CustomErrorFormatter, ErrorFormatter, ResponseOptions, TypedResponse } from "./response.ts"
 import { createErrorResponse, type HoneyRes } from "./response.ts"
-import type { OutputValidator, RouteHandler, RouteTree, TreeNode, WSRouteHandler } from "./tree.ts"
-import { createNode, insertRoute, insertWsRoute, matchRoute, matchWsRoute, mergeInto } from "./tree.ts"
-import { createBus } from "./realtime/bus.ts"
+import type { RouteId, Segment } from "./pattern.ts"
+import {
+	canonical,
+	expandOptional,
+	isStaticPattern,
+	joinPatterns,
+	normalizePattern,
+	parsePattern,
+	pathInScope,
+	routeId,
+	scopeCoverage,
+	splitRouteId,
+} from "./pattern.ts"
+import type { OutputValidator, RouteEntry, RouteHandler, RouteTree, TreeNode, WSRouteHandler } from "./tree.ts"
+import {
+	assertTreeFormat,
+	cloneTree,
+	createNode,
+	findLeaf,
+	forEachLeaf,
+	freezeTree,
+	hasWsLeaf,
+	insertLeaf,
+	matchRoute,
+	matchWsRoute,
+	ROUTE_TREE_VERSION,
+} from "./tree.ts"
 import type { RealtimeBus } from "./realtime/bus.ts"
-import { createConnContext } from "./realtime/route.ts"
-import type { RealtimeRouteOpts } from "./realtime/route.ts"
+import type { RealtimeConfig, RealtimeRouteOpts } from "./realtime/route.ts"
+import type { RealtimePublisher } from "./realtime/server.ts"
 import type {
 	ComputeErrorsByStatus,
 	DefaultMeta,
 	ExtractSchemas,
+	FieldError,
 	HttpMethod,
 	InferInputMap,
 	InferOutput,
@@ -26,34 +55,43 @@ import type {
 	MergePath,
 	MergeRoute,
 	MetaSpecConfig,
-	MetaSpecEntry,
-	MetaSpecMergeConflict,
 	OutputSchemaDef,
 	ParamsFromPath,
+	PrefixRoutes,
 	StandardSchemaLike,
 	StatusKey,
 	TapContext,
 } from "./types.ts"
 import { codeToStatusKey, EK, EMPTY_OBJ, SK } from "./types.ts"
-import { assertRequestContentType, validateInput, validateOutput } from "./validation.ts"
+import { assertBodySchemaAllowed, assertRequestContentType, validateInput, validateOutput } from "./validation.ts"
 import type { WSAdapter, WSContext, WSHandler } from "./ws/cloudflare.ts"
+import type { InvokeLogger } from "./invoke-user.ts"
+import { type WSOriginPolicy, validateOriginPolicy } from "./ws-origin.ts"
 import { loadHoneyFeature } from "./feature-load.ts"
 import { getI18nRuntime } from "./i18n-slot.ts"
-import { getOpenApiRuntime } from "./openapi/spec-factory.ts"
+import { bindInternalHandler, epochCached, getOpenApiRuntime } from "./openapi/spec-factory.ts"
+import type { ServedArtifact } from "./openapi/spec-factory.ts"
+import type { MetaSpecSource } from "./meta-spec-merge.ts"
 import { getServeRuntime } from "./serve-slot.ts"
 import type { HoneyServeOptions, ServeHandle } from "./serve.ts"
 
-export { HoneyContext } from "./context.ts"
+export { clientInfo, HoneyContext } from "./context.ts"
+export { toFetchRequest } from "./fetch-request.ts"
+export type { WSOriginPolicy } from "./ws-origin.ts"
+export type { ClientInfo } from "./client-info.ts"
+export type { TrustProxy } from "./trust.ts"
 /** HoneyContext without internal backing fields — use this for consumer-facing types */
 export type HoneyCtx<TEnv = Record<string, unknown>> = Omit<
 	import("./context.ts").HoneyContext<TEnv>,
 	| "_errorToResponse"
 	| "_isErrorResponse"
+	| "_lzClient"
 	| "_lzCookies"
 	| "_lzHeaders"
 	| "_lzSearch"
 	| "_lzSearchAll"
 	| "_lzUrlFn"
+	| "_rq"
 	| "_setErrors"
 >
 export { HoneyError } from "./error.ts"
@@ -97,6 +135,7 @@ export type {
 	InferRoutes,
 	InputSchemasDef,
 	MergePath,
+	PrefixRoutes,
 	HoneyMetaSpec,
 	MetaSpecConfig,
 	MetaSpecContext,
@@ -119,29 +158,26 @@ export type {
 	StatusKey,
 	SuccessStatusKey,
 } from "./types.ts"
-export type { WSAdapter, WSContext, WSHandler, WSPreUpgrade } from "./ws/cloudflare.ts"
-export type { ConnContext, RealtimeRouteOpts } from "./realtime/route.ts"
+export type { WSAdapter, WSAdapterOptions, WSContext, WSHandler, WSPreUpgrade } from "./ws/cloudflare.ts"
+export type { ConnContext, RealtimeLimits, RealtimeRouteOpts } from "./realtime/route.ts"
+export type { RealtimePublisher } from "./realtime/server.ts"
 export type { RealtimeBus } from "./realtime/bus.ts"
 export type { HoneyServeOptions, ServeHandle } from "./serve.ts"
 export type { ServeRuntime } from "./detect-runtime.ts"
 export { detectRuntime } from "./detect-runtime.ts"
 
-/** Type predicate for incoming wire-protocol msg frames from the realtime client. */
-function isMsgFrame(value: unknown): value is { data: unknown; t: "msg" } {
-	if (typeof value !== "object" || value === null || Array.isArray(value)) return false
-	if (!("t" in value) || !("data" in value)) return false
-	return value.t === "msg"
-}
-
 type TelemetryAdapter = {
 	onError?(ctx: { duration: number; error: HoneyError; method: string; path: string }): void
-	onHandler?(ctx: { duration: number; method: string; path: string; status: number }): void
+	/** `path` is the request path; `route` the matched pattern (`/users/:id`). */
+	onHandler?(ctx: { duration: number; method: string; path: string; route: string; status: number }): void
 	onMethodNotAllowed?(ctx: { allowed: string[]; method: string; path: string; req: Request }): void
 	onMiddleware?(ctx: { duration: number; error?: unknown; name: string }): void
 	onNotFound?(ctx: { method: string; path: string; req: Request }): void
 	onRequest?(ctx: { env: unknown; req: Request }): void
+	/** Fires exactly once per request that fired `onRequest`, whichever way it exits. */
 	onResponse?(ctx: { duration: number; req: Request; status: number }): void
-	onRoute?(ctx: { method: string; params: Record<string, string>; path: string; req: Request }): void
+	/** `path` is the request path; `route` the matched pattern (`/users/:id`). */
+	onRoute?(ctx: { method: string; params: Record<string, string>; path: string; req: Request; route: string }): void
 }
 
 type ErrorI18nConfig<TEnv> = {
@@ -157,57 +193,257 @@ type ErrorI18nConfig<TEnv> = {
 	}) => string | Promise<string>
 }
 
+/** The warn side of a structured logger (`warn(obj, msg)` or `warn(msg)`), e.g. honey/logger. */
 type Logger = {
-	warn?(msg: string, ...args: unknown[]): void
+	warn?(objOrMsg: Record<string, unknown> | string, msg?: string): void
+}
+
+type ErrorCtx<TEnv> = { env: TEnv; jsonFromError: (err: HoneyError) => Response; req: Request }
+
+type OnErrorFn<TEnv> = (
+	error: unknown,
+	ctx: ErrorCtx<TEnv>,
+) => HoneyError | Response | Promise<HoneyError | Response | undefined | void> | undefined | void
+
+type OnMethodNotAllowedFn<TEnv> = (ctx: ErrorCtx<TEnv> & { allowed: string[] }) => Response | Promise<Response>
+
+type OnNotFoundFn<TEnv> = (ctx: ErrorCtx<TEnv>) => Response | Promise<Response>
+
+type TapFn<TEnv> = (ctx: TapContext<TEnv>, payload: unknown) => void | Promise<void>
+
+type ErrorFactoryRecord = Record<string, (...args: never[]) => unknown>
+
+type OutputValidationMode = "always" | "dev" | "off"
+
+/**
+ * Settings of one app — shared by every handle derived from it (`use()`, `basePath()`,
+ * `context()`, `meta()`), so a setter called on any handle applies to all of them and
+ * serving any handle behaves the same. Records point at the settings of the app they were
+ * registered on, so a mounted sub-app's routes keep their own error factory, default errors,
+ * boundary and output validation.
+ */
+type AppSettings<TEnv = unknown> = {
+	customErrorFormatter: CustomErrorFormatter | null
+	customErrorSchema: StandardSchemaLike | null
+	defaultBoundaryKey: string | null
+	defaultErrorKeys: Set<string>
+	errorFactory: ErrorFactoryRecord | null
+	errorFormatter: ErrorFormatterFn
+	errorI18n: ErrorI18nConfig<TEnv> | null
+	errorSchema: StandardSchemaLike | null
+	logger: Logger | null
+	onError: OnErrorFn<TEnv> | null
+	onMethodNotAllowed: OnMethodNotAllowedFn<TEnv> | null
+	onNotFound: OnNotFoundFn<TEnv> | null
+	/** null = never set: a mounted route follows the mounting app's mode */
+	outputValidation: OutputValidationMode | null
+	stripPrefix: string | null
+	taps: Map<string, TapFn<TEnv>> | null
+	telemetry: TelemetryAdapter | null
+	trailingSlash: "enforce" | "ignore" | "strip"
+	encodedSlashes: "allow" | "reject"
+	trust: TrustSetting
+	wsAdapter: WSAdapter | null
 }
 
+function createSettings<TEnv>(): AppSettings<TEnv> {
+	return {
+		customErrorFormatter: null,
+		customErrorSchema: null,
+		defaultBoundaryKey: null,
+		defaultErrorKeys: new Set(),
+		errorFactory: null,
+		errorFormatter: defaultErrorFormatter,
+		errorI18n: null,
+		errorSchema: null,
+		logger: null,
+		onError: null,
+		onMethodNotAllowed: null,
+		onNotFound: null,
+		outputValidation: null,
+		stripPrefix: null,
+		taps: null,
+		telemetry: null,
+		trailingSlash: "ignore",
+		encodedSlashes: "reject",
+		trust: TRUST_OFF,
+		wsAdapter: null,
+	}
+}
+
+/** Join a base path and a route or scope path into one canonical pattern. */
 function mergePath(base: string, path: string): string {
-	if (base === "/") return path
-	if (path === "/") return base
-	return `${base}${path}`
+	return joinPatterns(base, path)
+}
+
+/**
+ * Everything a matched route runs, compiled once at finalize: the record (with its resolved
+ * error keys, meta and chain) and one function that runs chain + handler and never rejects.
+ */
+type Plan = {
+	/** `.context()` values copied onto each request context */
+	cv: Record<string, unknown> | null
+	/** declared error keys are enforced (the route, its middleware or the app declared any) */
+	enf: boolean
+	/** preflight runner — chain without input validation or handler; compiled on first preflight */
+	pf: CompiledChain | null
+	/** what the preflight runner runs */
+	pfChain: RuntimeMiddleware[]
+	r: RouteHandler | WSRouteHandler
+	/** realtime route config when this is a realtime route */
+	rt: RealtimeConfig | null
+	run: CompiledChain
+	/** taps of the serving app, plus those of the app the route came from */
+	taps: Map<string, TapFn<unknown>> | null
 }
 
-/** Normalize a scope prefix: ensure leading slash, strip trailing slash (except "/"). */
-function normalizeScopePath(raw: string): string {
-	let p = raw
-	if (p.length === 0) return "/"
-	if (p.charCodeAt(0) !== 47) p = `/${p}`
-	if (p.length > 1 && p.endsWith("/")) p = p.slice(0, -1)
-	return p
+type CompiledChain = (ctx: object) => Response | Promise<Response>
+
+/** What one app graph serves, resolved at finalize from records and the loaded tree. */
+type FinalTable = {
+	byId: Map<RouteId, RouteHandler>
+	convert: ChainErrorConverter
+	epoch: number
+	/** 404 / 405: the middleware every route runs, plus the scopes covering the request path */
+	miss: Plan
+	plans: Map<RouteId, Plan>
+	/** `METHOD /path` → plan, for routes without params or wildcards */
+	statics: Record<string, Plan>
+	wsById: Map<RouteId, WSRouteHandler>
+	wsPlans: Map<RouteId, Plan>
 }
 
-/** Check whether fullPath falls under scope prefix — exact match or next char is '/'. */
-function scopeMatches(prefix: string, fullPath: string): boolean {
-	if (prefix === "/") return true
-	if (fullPath === prefix) return true
-	if (fullPath.length <= prefix.length) return false
-	if (fullPath.charCodeAt(prefix.length) !== 47) return false
-	return fullPath.startsWith(prefix)
+/** One `app.use(mw)` — the handle it returns has to register a route, or `mw` runs nowhere. */
+type ChainNode = { mw: RuntimeMiddleware; parent: ChainNode | null; used: boolean }
+
+/** A route builder still waiting for `.handler()` — reported at finalize. */
+type PendingRoute = { id: string }
+
+/** @internal — runtime entry for a scoped middleware */
+type ScopedEntry = {
+	/** cached from mw.errors at registration; undefined when none */
+	errors: readonly string[] | undefined
+	/** the middleware behind a request-path check, for routes the scope covers only partly */
+	guard: RuntimeMiddleware
+	mw: RuntimeMiddleware
+	/** canonical full-path pattern (already rebased against basePath at .use time) */
+	prefix: string
+	segs: Segment[]
 }
 
+/**
+ * One app graph — shared by every handle derived with `use()`, `basePath()`, `context()`,
+ * `meta()`. Records are per graph, keyed by `RouteId`; the tree holds ids only, so a loaded
+ * (shared, frozen) tree never carries another app's handlers.
+ */
 type HoneyGraph = {
-	handlerMap: Record<string, RouteHandler> | null
-	hasRouteTree: boolean
-	/** Codegen-time meta → OpenAPI policy. Never read on the request path */
+	/** metaSpec policies of mounted sub-apps, merged under `metaSpec` when codegen reads it */
+	absorbedMetaSpecs: MetaSpecSource[]
+	/** gateway catch-alls by method — root wildcards registered over a loaded tree that lacks them */
+	catchAll: Map<string, RouteHandler>
+	/** every `use(mw)` handle — one that never registers a route is reported at finalize */
+	chains: ChainNode[]
+	/** bumped by every registration; finalize re-runs when it moves */
+	epoch: number
+	final: FinalTable | null
+	/** app-wide middleware that runs before every chain (serve({ cors })), keyed so a re-serve replaces it */
+	global: Map<string, RuntimeMiddleware>
+	hasWs: boolean
+	/** route data of the loaded tree (per-graph copies) — null when no tree was loaded */
+	loaded: Map<RouteId, RouteEntry> | null
+	/** Codegen-time meta → OpenAPI policy declared on this app. Never read on the request path */
 	metaSpec: MetaSpecConfig | null
+	/** route builders still waiting for `.handler()` */
+	pending: Set<PendingRoute>
 	realtimeBus: RealtimeBus | null
+	/** `ctx.realtime`, shared by every request of this graph */
+	realtimeCtx: RealtimePublisher | null
+	realtimeRoutes: Map<string, RealtimeConfig>
+	records: Map<RouteId, RouteHandler>
 	root: TreeNode
+	/** root is a loaded tree (frozen, possibly shared by other apps) — copy before inserting */
+	rootShared: boolean
+	/** path-scoped middleware, in registration order */
+	scoped: ScopedEntry[]
+	/** chains of the handles that served a request — decide what 404 and 405 run when there are no routes */
+	served: Set<RuntimeMiddleware[]>
+	settings: AppSettings<unknown>
+	/** registered after routeTree() with no leaf in the loaded tree — stale generated file */
+	unexpected: Set<RouteId>
+	wsRecords: Map<RouteId, WSRouteHandler>
 }
 
-function walkTreeHandlers(root: TreeNode, cb: (h: RouteHandler) => void, wsCb?: (h: WSRouteHandler) => void): void {
-	if (root.m) {
-		for (const h of Object.values(root.m) as RouteHandler[]) cb(h)
+/** Outcome of mounting an internal route: done, or who already owns the path. */
+type MountResult = "internal" | "mounted" | "user"
+
+function createGraph(): HoneyGraph {
+	return {
+		absorbedMetaSpecs: [],
+		catchAll: new Map(),
+		chains: [],
+		epoch: 0,
+		final: null,
+		global: new Map(),
+		hasWs: false,
+		loaded: null,
+		metaSpec: null,
+		pending: new Set(),
+		realtimeBus: null,
+		realtimeCtx: null,
+		realtimeRoutes: new Map(),
+		records: new Map(),
+		root: createNode(),
+		rootShared: false,
+		scoped: [],
+		served: new Set(),
+		settings: createSettings(),
+		unexpected: new Set(),
+		wsRecords: new Map(),
 	}
-	if (root.w) {
-		for (const h of Object.values(root.w.m) as RouteHandler[]) cb(h)
-	}
-	if (root.ws && wsCb) wsCb(root.ws)
-	for (const child of Object.values(root.s)) walkTreeHandlers(child, cb, wsCb)
-	if (root.d) walkTreeHandlers(root.d.c, cb, wsCb)
+}
+
+/** Fresh copy of a record for another graph — sources are copied, resolved fields recomputed there. */
+function copyRecord<T extends RouteHandler | WSRouteHandler>(r: T): T {
+	const out = { ...r, ek: new Set(r.ek) } as T
+	if (r.dk !== undefined) out.dk = new Set(r.dk)
+	if (r.cm !== undefined) out.cm = [...r.cm]
+	if (r.rm !== undefined) out.rm = [...r.rm]
+	delete (out as RouteHandler).ca
+	return out
+}
+
+/** Every leaf a pattern occupies: an optional last param places two. */
+function leafVariants(segments: readonly Segment[]): Segment[][] {
+	return expandOptional(segments)
+}
+
+/** Record the error behind an error response on `ctx.error` (read-only for user code). */
+function setCtxError(ctx: HoneyContext<unknown>, error: HoneyError): void {
+	;(ctx as unknown as Record<string, unknown>)["error"] = error
+}
+
+/** What `ctx.error` holds for a throw the boundary could not resolve: the 500 it became. */
+function asHoneyError(thrown: unknown): HoneyError {
+	return thrown instanceof HoneyError
+		? thrown
+		: new HoneyError({ cause: thrown, errorKey: EK.internal_server_error, status: SK.internal_server_error })
+}
+
+function patternOf(id: RouteId): { method: string; segments: Segment[] } {
+	const { method, pattern } = splitRouteId(id)
+	return { method, segments: parsePattern(pattern) }
+}
+
+/** `fn` of a tree leaf no handler serves — dispatch answers 404, codegen still documents it. */
+const NOT_SERVED: RouteHandler["fn"] = () => {
+	throw new Error("honey: unserved route reached its handler")
+}
+
+function isRootWildcard(segments: readonly Segment[]): boolean {
+	return segments.length === 1 && segments[0].k === "wildcard"
 }
 
 const EMPTY_PARAMS = EMPTY_OBJ as Record<string, string>
-const EMPTY_MW: RuntimeMiddleware[] = []
 
 function requestIsWsUpgrade(request: Request): boolean {
 	try {
@@ -218,37 +454,43 @@ function requestIsWsUpgrade(request: Request): boolean {
 	}
 }
 
-/** Find first '?' or '#' in url starting from pos */
-function findSearchOrHash(url: string, pos: number): number {
-	for (let i = pos; i < url.length; i++) {
-		const c = url.charCodeAt(i)
-		if (c === 63 || c === 35) return i
-	}
-	return -1
+/** The info object `Deno.serve` passes as the second handler argument. */
+function isDenoServeInfo(env: unknown): boolean {
+	return env !== null && typeof env === "object" && (env as { remoteAddr?: unknown }).remoteAddr !== undefined
 }
 
+/** `obj[key]` for an own key only; `undefined` for inherited names such as `constructor`. */
 function safeFire(fn: (() => unknown) | undefined, logger?: Logger): void {
 	if (fn === undefined) return
 	try {
 		const result = fn()
 		if (result && typeof result === "object" && "catch" in result) {
 			;(result as Promise<unknown>).catch((e: unknown) => {
-				logger?.warn?.("telemetry callback failed", e)
+				logger?.warn?.({ err: e }, "telemetry callback failed")
 			})
 		}
 	} catch (e) {
-		logger?.warn?.("telemetry callback failed", e)
+		logger?.warn?.({ err: e }, "telemetry callback failed")
 	}
 }
 
-/** Internal context shared across extracted fetch sub-methods */
+/** Per-request state, shared by the dispatcher, the error boundary and terminal handlers. */
 type FetchCtx<TEnv> = {
+	/** methods a 405 lists; also marks the miss pipeline as a 405 */
+	allowed: string[] | null
 	env: TEnv
 	executionCtx: { waitUntil?: (p: Promise<unknown>) => void } | undefined
 	log: Logger | undefined
+	method: string
+	path: string
+	plan: Plan | null
 	request: Request
 	startTime: number
+	/** the app's trustProxy() setting, read by ctx.ip and clientInfo() */
+	trust: TrustSetting
 	url: () => URL
+	/** matched websocket route, for the upgrade terminal */
+	ws: { handler: WSRouteHandler; params: Record<string, string> } | null
 	/** Already known from fetch() before Deno.upgradeWebSocket consumes the request. */
 	wsUpgrade?: boolean
 	/** Headers copied before Deno.upgradeWebSocket closes the Request. */
@@ -281,11 +523,9 @@ function defaultErrorFormatter(_error: HoneyError, defaultShape: Record<string,
 
 type ErrorFormatterFn = ErrorFormatter
 
-const STATIC_CTX_RESERVED = new Set(["background", "cookies", "env", "headers", "params", "req", "res", "search"])
-
 /* errorKeys the framework throws on its own behalf — input/output validation, content negotiation,
- * routing. Always passes the boundary check; users never declare these via .errors(). */
-const FRAMEWORK_EKS = new Set<(typeof EK)[keyof typeof EK]>([
+ * routing, and the shipped middleware. Always passes the boundary check; users never declare these via .errors(). */
+const FRAMEWORK_EKS = new Set<string>([
 	EK.validation_failed,
 	EK.output_validation_failed,
 	EK.output_content_type_mismatch,
@@ -297,8 +537,68 @@ const FRAMEWORK_EKS = new Set<(typeof EK)[keyof typeof EK]>([
 	EK.request_timeout,
 	EK.gateway_timeout,
 	EK.bad_gateway,
+	EK.forbidden,
+	EK.bad_request,
+	EK.malformed_body,
 ])
 
+function shouldValidateOutput(mode: OutputValidationMode): boolean {
+	if (mode === "always") return true
+	if (mode === "off") return false
+	return (globalThis as { process?: { env?: { NODE_ENV?: string } } }).process?.env?.NODE_ENV !== "production"
+}
+
+/** The scoped middleware behind a request-path check: runs only when the path is inside the scope. */
+function scopeGuard(segs: readonly Segment[], mw: RuntimeMiddleware): RuntimeMiddleware {
+	const guard: RuntimeMiddleware = (ctx, next) => (pathInScope(ctx["path"] as string, segs) ? mw(ctx, next) : next())
+	Object.defineProperty(guard, "name", { configurable: true, value: mw.name })
+	const tagged = mw as { errors?: readonly string[]; meta?: Readonly<Record<string, unknown>> }
+	if (tagged.errors) Object.defineProperty(guard, "errors", { value: tagged.errors })
+	if (tagged.meta) Object.defineProperty(guard, "meta", { value: tagged.meta })
+	return guard
+}
+
+/** Wrap a middleware so telemetry sees its own duration and its own throw. Built once at finalize. */
+function timedMiddleware(
+	mw: RuntimeMiddleware,
+	onMw: NonNullable<TelemetryAdapter["onMiddleware"]>,
+	log: Logger | undefined,
+): RuntimeMiddleware {
+	const name = mw.name || "anonymous"
+	return async (ctx, next) => {
+		const start = performance.now()
+		try {
+			const res = await mw(ctx, next)
+			safeFire(() => onMw({ duration: performance.now() - start, name }), log)
+			return res
+		} catch (error) {
+			safeFire(() => onMw({ duration: performance.now() - start, error, name }), log)
+			throw error
+		}
+	}
+}
+
+function errorsOf(mw: RuntimeMiddleware): readonly string[] | undefined {
+	return (mw as { errors?: readonly string[] }).errors
+}
+
+/** Longest run of middleware every record starts its chain with — what 404 and 405 run. */
+function commonPrefix(chains: ReadonlyArray<readonly RuntimeMiddleware[]>): RuntimeMiddleware[] {
+	if (chains.length === 0) return []
+	let out = [...(chains[0] as readonly RuntimeMiddleware[])]
+	for (let i = 1; i < chains.length && out.length > 0; i++) {
+		const c = chains[i] as readonly RuntimeMiddleware[]
+		let n = 0
+		while (n < out.length && n < c.length && out[n] === c[n]) n++
+		out = out.slice(0, n)
+	}
+	return out
+}
+
+function describeMw(mw: RuntimeMiddleware): string {
+	return mw.name ? `"${mw.name}"` : "an anonymous middleware"
+}
+
 export class Honey<
 	TEnv,
 	TCtx = HoneyContext<TEnv>,
@@ -317,172 +617,95 @@ export class Honey<
 	declare readonly $meta: TMeta
 	declare readonly $routes: TRoutes
 	declare readonly $taps: TTaps
+	/* view state — what routes registered through this handle capture */
 	private _basePath: string
-	private _defaultBoundaryKey: string | null
-	private _defaultErrorKeys: Set<string>
-	private _errorFactory: unknown
-	private _errorSchema: StandardSchemaLike | null
-	private _customErrorFormatter: CustomErrorFormatter | null
-	private _customErrorSchema: StandardSchemaLike | null
+	private _chain: RuntimeMiddleware[]
 	private _chainMeta: Record<string, unknown> | null
-	private _chainMiddlewares: RuntimeMiddleware[]
-	private _scopedMiddlewares: ScopedEntry[]
 	private _contextValues: Record<string, unknown> | null
-	private _errorFormatter: ErrorFormatterFn
-	private _errorI18n: ErrorI18nConfig<TEnv> | null
-	private _globalMiddlewares: RuntimeMiddleware[]
 	private _graph: HoneyGraph
-	private _hasWsRoutes: boolean
-	private _logger: Logger | null
-	private _outputValidation: "always" | "dev" | "off"
-	private _staticRoutes: { map: Record<string, RouteHandler> | null }
-	private _stripPrefix: string | null
-	private _trailingSlash: "enforce" | "ignore" | "strip"
-	private _wsAdapter: WSAdapter | null
-	private _openApiCache: { epoch: number; value: Promise<unknown> } | null
-	private _openApiYamlCache: { epoch: number; value: Promise<string> } | null
-	private _manifestCache: { epoch: number; value: Promise<unknown> } | null
-	private _onError:
-		| ((
-				error: unknown,
-				ctx: {
-					env: TEnv
-					jsonFromError: (err: HoneyError) => Response
-					req: Request
-				},
-		  ) => HoneyError | Response | Promise<HoneyError | Response | undefined | void> | undefined | void)
-		| null
-	private _onMethodNotAllowed:
-		| ((ctx: {
-				allowed: string[]
-				env: TEnv
-				jsonFromError: (err: HoneyError) => Response
-				req: Request
-		  }) => Response | Promise<Response>)
-		| null
-	private _onNotFound:
-		| ((ctx: { env: TEnv; jsonFromError: (err: HoneyError) => Response; req: Request }) => Response | Promise<Response>)
-		| null
-	private _taps: Map<string, (ctx: TapContext<TEnv>, payload: unknown) => void | Promise<void>> | null
-	private _telemetry: TelemetryAdapter | null
-	private _realtimeRoutes: Map<
-		string,
-		{ handler: RealtimeRouteOpts["handler"]; middlewares?: RealtimeRouteOpts["use"]; reconnectBuffer?: number }
-	>
+	/** the `use(mw)` call that created this chain — null on the root handle */
+	private _node: ChainNode | null
 
-	constructor(opts?: {
-		chainMiddlewares?: RuntimeMiddleware[]
-		defaultErrorKeys?: Set<string>
-		globalMiddlewares?: RuntimeMiddleware[]
-		graph?: HoneyGraph
-		handlerMap?: Record<string, RouteHandler> | null
-		root?: TreeNode
-		scopedMiddlewares?: ScopedEntry[]
-	}) {
+	constructor(opts?: { graph?: HoneyGraph }) {
 		this._basePath = "/"
-		this._graph = opts?.graph ?? {
-			handlerMap: opts?.handlerMap ?? null,
-			hasRouteTree: false,
-			metaSpec: null,
-			realtimeBus: null,
-			root: opts?.root ?? createNode(),
-		}
-		this._globalMiddlewares = opts?.globalMiddlewares ?? []
-		this._scopedMiddlewares = opts?.scopedMiddlewares ?? []
+		this._chain = []
 		this._chainMeta = null
-		this._chainMiddlewares = opts?.chainMiddlewares ?? []
 		this._contextValues = null
-		this._defaultBoundaryKey = null
-		this._defaultErrorKeys = opts?.defaultErrorKeys ?? new Set()
-		this._errorFactory = null
-		this._errorSchema = null
-		this._customErrorFormatter = null
-		this._customErrorSchema = null
-		this._errorFormatter = defaultErrorFormatter
-		this._errorI18n = null
-		this._hasWsRoutes = false
-		this._logger = null
-		this._outputValidation = "off"
-		this._staticRoutes = { map: null }
-		this._stripPrefix = null
-		this._trailingSlash = "ignore"
-		this._wsAdapter = null
-		this._openApiCache = null
-		this._openApiYamlCache = null
-		this._manifestCache = null
-		this._onError = null
-		this._onNotFound = null
-		this._onMethodNotAllowed = null
-		this._taps = null
-		this._telemetry = null
-		this._realtimeRoutes = new Map()
-	}
-
-	private get _handlerMap(): Record<string, RouteHandler> | null {
-		return this._graph.handlerMap
-	}
-	private set _handlerMap(value: Record<string, RouteHandler> | null) {
-		this._graph.handlerMap = value
-	}
-
-	private get _hasRouteTree(): boolean {
-		return this._graph.hasRouteTree
-	}
-	private set _hasRouteTree(value: boolean) {
-		this._graph.hasRouteTree = value
-	}
-
-	/** @internal — read by codegen */
-	private get _metaSpec(): MetaSpecConfig | null {
-		return this._graph.metaSpec
-	}
-	private set _metaSpec(value: MetaSpecConfig | null) {
-		this._graph.metaSpec = value
+		this._graph = opts?.graph ?? createGraph()
+		this._node = null
 	}
 
-	private get _root(): TreeNode {
-		return this._graph.root
+	private get _s(): AppSettings<TEnv> {
+		return this._graph.settings as AppSettings<TEnv>
+	}
+
+	/**
+	 * @internal — read by codegen through `metaSpecOf()`: the declared policy and every mounted
+	 * sub-app's, unmerged. Merged on read, so `metaSpec()` may come before or after `route(sub)`;
+	 * the merge lives with codegen so a served app never loads it.
+	 */
+	private get _metaSpecSource(): MetaSpecSource {
+		return { absorbed: this._graph.absorbedMetaSpecs, declared: this._graph.metaSpec }
 	}
-	private set _root(value: TreeNode) {
-		this._graph.root = value
+
+	/** @internal — read by codegen and OpenAPI */
+	get _errorFactory(): ErrorFactoryRecord | null {
+		return this._graph.settings.errorFactory
+	}
+	set _errorFactory(factory: ErrorFactoryRecord | null) {
+		this._graph.settings.errorFactory = factory
+		this._bumpEpoch()
+	}
+
+	/** @internal — read by OpenAPI */
+	get _errorSchema(): StandardSchemaLike | null {
+		return this._graph.settings.errorSchema
 	}
 
-	/** @internal — used by codegen */
-	private get _tree(): TreeNode {
-		return this._root
+	/** @internal — read by OpenAPI */
+	get _customErrorSchema(): StandardSchemaLike | null {
+		return this._graph.settings.customErrorSchema
+	}
+
+	private get _root(): TreeNode {
+		return this._graph.root
 	}
 
 	private get _realtimeBus(): RealtimeBus | null {
 		return this._graph.realtimeBus
 	}
-	private set _realtimeBus(value: RealtimeBus | null) {
-		this._graph.realtimeBus = value
-	}
 
-	/** @internal — mark that this app has WS routes */
-	_markWsRoutes(): void {
-		this._hasWsRoutes = true
+	/** A new handle on the same graph, carrying this handle's view. */
+	private _derive(chain: RuntimeMiddleware[] = this._chain): Honey<TEnv> {
+		const next = new Honey<TEnv>({ graph: this._graph })
+		next._basePath = this._basePath
+		next._chain = chain
+		next._chainMeta = this._chainMeta
+		next._contextValues = this._contextValues
+		next._node = this._node
+		return next
 	}
 
-	/** @internal — register a static route for O(1) lookup */
-	_registerStatic(key: string, handler: RouteHandler): void {
-		if (this._staticRoutes.map === null) {
-			this._staticRoutes.map = Object.create(null) as Record<string, RouteHandler>
+	/** This handle registers, mounts or serves — every `use()` on its way here is in use. */
+	private _markUsed(): void {
+		let node = this._node
+		while (node !== null && !node.used) {
+			node.used = true
+			node = node.parent
 		}
-		this._staticRoutes.map[key] = handler
 	}
 
 	/** @internal — used by RouteBuilder for pre-filtered error factory */
 	get _factory(): unknown {
-		return this._errorFactory
+		return this._graph.settings.errorFactory
 	}
 
 	/** @internal — used by runtime error boundary */
 	get _boundaryKey(): string | null {
-		return this._defaultBoundaryKey
+		return this._graph.settings.defaultBoundaryKey
 	}
 
-	/** Convert unknown thrown value to error Response — used in WS, 404, 405 catch blocks */
+	/** Convert an unknown thrown value to a plain error Response — no boundary, no onError. */
 	private _toErrorResponse(thrown: unknown): Response {
 		const error =
 			thrown instanceof HoneyError
@@ -492,14 +715,12 @@ export class Honey<
 						errorKey: EK.internal_server_error,
 						status: SK.internal_server_error,
 					})
-		return createErrorResponse(error, this._errorFormatter, this._customErrorFormatter)
+		const s = this._s
+		return createErrorResponse(error, s.errorFormatter, s.customErrorFormatter)
 	}
 
-	private _createBoundaryError(errorKey: string, cause: unknown): HoneyError {
-		const factory = this._errorFactory as Record<
-			string,
-			((opts?: { cause?: unknown }) => HoneyError) | undefined
-		> | null
+	private _createBoundaryError(errorKey: string, cause: unknown, fac: ErrorFactoryRecord | null): HoneyError {
+		const factory = fac as Record<string, ((opts?: { cause?: unknown }) => HoneyError) | undefined> | null
 		const factoryFn = factory?.[errorKey]
 		if (factoryFn) {
 			/* check if this is a custom schema error via ERROR_META — boundary must use standard errors only */
@@ -518,7 +739,7 @@ export class Honey<
 	}
 
 	private _createError(errorKey: string, statusKey: StatusKey): HoneyError {
-		const factory = this._errorFactory as Record<string, (() => HoneyError) | undefined> | null
+		const factory = this._s.errorFactory as Record<string, (() => HoneyError) | undefined> | null
 		const factoryFn = factory?.[errorKey]
 		if (factoryFn) {
 			return factoryFn()
@@ -526,85 +747,23 @@ export class Honey<
 		return new HoneyError({ errorKey, status: statusKey })
 	}
 
-	/** Apply error keys from a single scoped entry to every matching handler currently in the tree */
-	private _applyScopedEntryErrors(entry: ScopedEntry): void {
-		const errors = entry.errors
-		if (!errors || errors.length === 0) return
-		walkTreeHandlers(
-			this._root,
-			(h) => {
-				if (scopeMatches(entry.prefix, h.rp ?? "")) {
-					for (const k of errors) h.ek.add(k)
-				}
-			},
-			(wh) => {
-				if (scopeMatches(entry.prefix, wh.rp)) {
-					for (const k of errors) wh.ek.add(k)
-				}
-			},
-		)
-	}
-
 	/**
-	 * Meta contributed by every middleware that will run for `routePath`, in runtime order:
-	 * global, chain, then scoped entries matching the path. Route-level `.use()` is folded in
-	 * later, by the builder. Resolved here — at registration — because the precompiled route
-	 * tree bakes `mt` as a literal, so a per-request derivation would diverge from it.
+	 * The i18n-resolved copy of `honeyError`: message from the locale's template for its
+	 * errorKey, field paths from the locale's field names. Returns `honeyError` itself when
+	 * i18n is not configured or nothing matches. Never mutates it: an error instance can be
+	 * thrown again, on another request, in another locale.
 	 */
-	private _contributedMetaFor(routePath: string): Record<string, unknown> | null {
-		const scoped: RuntimeMiddleware[] = []
-		for (const entry of this._scopedMiddlewares) {
-			if (scopeMatches(entry.prefix, routePath)) scoped.push(entry.mw)
-		}
-		return collectMiddlewareMeta([this._globalMiddlewares, this._chainMiddlewares, scoped])
-	}
-
-	/**
-	 * Back-fill meta from one scoped entry onto handlers already in the tree. Mirrors
-	 * `_applyScopedEntryErrors` — `.use("/prefix", mw)` may be registered after the routes it
-	 * covers, and a tag missing where enforcement happens is the worst failure direction.
-	 * `mt` is frozen at registration, so this replaces the object rather than mutating it.
-	 */
-	private _applyScopedEntryMeta(entry: ScopedEntry): void {
-		const meta = (entry.mw as { meta?: Record<string, unknown> }).meta
-		if (!meta) return
-		const apply = (h: { mt: Record<string, unknown> | null; rp?: string }): void => {
-			if (!scopeMatches(entry.prefix, h.rp ?? "")) return
-			/* contributed meta never overwrites what the route or chain stated explicitly */
-			h.mt = Object.freeze(h.mt ? { ...meta, ...h.mt } : { ...meta })
-		}
-		walkTreeHandlers(this._root, apply, apply)
-	}
-
-	/** Apply error keys from every scoped entry on this chain to every matching handler in the tree */
-	private _applyAllScopedErrors(): void {
-		for (const entry of this._scopedMiddlewares) {
-			this._applyScopedEntryErrors(entry)
-		}
-	}
-
-	/** Return scoped middleware functions that match the given route path */
-	private _filterScopedForPath(routePath: string): RuntimeMiddleware[] {
-		if (this._scopedMiddlewares.length === 0) return EMPTY_MW
-		const out: RuntimeMiddleware[] = []
-		for (const s of this._scopedMiddlewares) {
-			if (scopeMatches(s.prefix, routePath)) out.push(s.mw)
-		}
-		return out
-	}
-
-	/** Mutates `honeyError.message` in-place with the i18n-resolved template for its errorKey.
-	 * No-op when i18n is not configured or when no template matches. */
 	private async _resolveI18n(
 		honeyError: HoneyError,
 		ctx: HoneyContext<TEnv>,
 		env: TEnv,
 		request: Request,
 		log?: Logger,
-	): Promise<void> {
-		if (!this._errorI18n) return
+	): Promise<HoneyError> {
+		const i18n = this._s.errorI18n
+		if (!i18n) return honeyError
 		try {
-			const locale = await this._errorI18n.resolveLocale({
+			const locale = await i18n.resolveLocale({
 				cookies: ctx.cookies,
 				env,
 				headers: ctx.headers,
@@ -612,195 +771,121 @@ export class Honey<
 				req: request,
 				search: ctx.search,
 			})
-			const translations = this._errorI18n.errors?.[locale]
-			if (translations) {
-				const template = translations[honeyError.errorKey]
-				if (template) {
-					await loadHoneyFeature("i18n")
-					honeyError.message = getI18nRuntime().interpolate(template, honeyError.vars ?? {})
-				}
-			}
+			await loadHoneyFeature("i18n")
+			return getI18nRuntime().translateError(honeyError, i18n, locale)
+		} catch (e) {
+			log?.warn?.({ err: e }, "i18n resolution failed")
+			return honeyError
+		}
+	}
 
-			const fieldTranslations = this._errorI18n.fieldNames?.[locale]
-			if (fieldTranslations && Object.keys(honeyError.fields).length > 0) {
-				for (const fieldErrors of Object.values(honeyError.fields)) {
-					for (const fe of fieldErrors) {
-						let candidate = fe.path
-						while (candidate) {
-							const translated = fieldTranslations[candidate]
-							if (translated) {
-								fe.path = translated
-								break
-							}
-							const dotIdx = candidate.indexOf(".")
-							if (dotIdx === -1) break
-							candidate = candidate.slice(dotIdx + 1)
-						}
-					}
-				}
-			}
+	/**
+	 * The error boundary of every `next()`: turns what a handler or middleware threw into the
+	 * Response that replaces it, so every middleware around it sees a Response. Never rejects.
+	 */
+	private _convertError(thrown: unknown, ctx: HoneyContext<TEnv>): Response | Promise<Response> {
+		const fc = ctx._rq as FetchCtx<TEnv> | null
+		const plan = fc?.plan
+		if (fc === null || fc === undefined || plan === null || plan === undefined) {
+			setCtxError(ctx, asHoneyError(thrown))
+			return this._safeErrorResponse(thrown)
+		}
+		const fallback = (e: unknown): Response => {
+			fc.log?.warn?.({ err: e }, "error response failed")
+			setCtxError(ctx, asHoneyError(thrown))
+			return this._safeErrorResponse(thrown)
+		}
+		try {
+			return this._resolveErrorResponse(thrown, plan, fc, ctx).catch(fallback)
 		} catch (e) {
-			log?.warn?.("i18n resolution failed", e)
+			return fallback(e)
+		}
+	}
+
+	/** Last resort when even the configured formatter throws. */
+	private _safeErrorResponse(thrown: unknown): Response {
+		try {
+			return this._toErrorResponse(thrown instanceof HoneyError ? thrown : undefined)
+		} catch {
+			return new Response(JSON.stringify({ error: { errorKey: EK.internal_server_error } }), {
+				headers: { "content-type": "application/json" },
+				status: 500,
+			})
 		}
 	}
 
 	/**
-	 * Convert thrown value into an error Response — resolves boundary wrapping,
-	 * i18n translation, onError callback, and telemetry.
-	 * Called from the handler wrapper so errors flow back through middleware.
+	 * Convert thrown value into an error Response — resolves boundary wrapping, i18n
+	 * translation, the onError callback, and error telemetry. `onResponse` telemetry is not
+	 * fired here: the request fires it exactly once, on the way out.
 	 */
 	private async _resolveErrorResponse(
 		thrown: unknown,
-		handler: RouteHandler,
+		plan: Plan,
 		fc: FetchCtx<TEnv>,
-		method: string,
-		path: string,
 		ctx: HoneyContext<TEnv>,
 	): Promise<Response> {
-		const { env, log, request, startTime } = fc
+		const { env, log, request, startTime, method, path } = fc
+		const s = this._s
+		const record = plan.r
+		const fac = (record.fac ?? null) as ErrorFactoryRecord | null
 		let honeyError: HoneyError
-		const boundaryKey = handler.bek ?? this._defaultBoundaryKey
+		const boundaryKey = record.bek
 
 		if (thrown instanceof HoneyError) {
 			/* framework-managed errorKeys (input/output validation, content negotiation, etc.) are always allowed
-			 * regardless of handler.ek — users never declare them, the framework owns them. */
-			const isFrameworkEk = FRAMEWORK_EKS.has(thrown.errorKey as (typeof EK)[keyof typeof EK])
-			if (!isFrameworkEk && handler.ek.size > 0 && !handler.ek.has(thrown.errorKey)) {
-				if (boundaryKey) {
-					honeyError = this._createBoundaryError(boundaryKey, thrown)
-				} else {
-					honeyError = new HoneyError({
-						cause: thrown,
-						errorKey: EK.internal_server_error,
-						status: SK.internal_server_error,
-					})
-				}
+			 * regardless of the declared keys — users never declare them, the framework owns them. */
+			if (plan.enf && !FRAMEWORK_EKS.has(thrown.errorKey) && !record.ek.has(thrown.errorKey)) {
+				honeyError = boundaryKey
+					? this._createBoundaryError(boundaryKey, thrown, fac)
+					: new HoneyError({ cause: thrown, errorKey: EK.internal_server_error, status: SK.internal_server_error })
 			} else {
 				honeyError = thrown
 			}
 		} else {
-			if (boundaryKey) {
-				honeyError = this._createBoundaryError(boundaryKey, thrown)
-			} else {
-				honeyError = new HoneyError({
-					cause: thrown,
-					errorKey: EK.internal_server_error,
-					status: SK.internal_server_error,
-				})
-			}
+			honeyError = boundaryKey
+				? this._createBoundaryError(boundaryKey, thrown, fac)
+				: new HoneyError({ cause: thrown, errorKey: EK.internal_server_error, status: SK.internal_server_error })
 		}
 
-		await this._resolveI18n(honeyError, ctx, env, request, log)
+		honeyError = await this._resolveI18n(honeyError, ctx, env, request, log)
 
-		/* onError handler */
-		if (this._onError) {
+		if (s.onError) {
 			try {
-				const customResult = await this._onError(thrown, this._makeErrorCtx(fc))
+				const customResult = await s.onError(thrown, this._makeErrorCtx(fc))
 				if (customResult instanceof HoneyError) {
 					/* user-mapped boundary error — re-run i18n against new errorKey,
-					 * then fall through to default response path so telemetry +
-					 * jsonFromError run exactly once. */
-					honeyError = customResult
-					await this._resolveI18n(honeyError, ctx, env, request, log)
+					 * then fall through to the default response path */
+					honeyError = await this._resolveI18n(customResult, ctx, env, request, log)
 				} else if (customResult) {
 					safeFire(
-						() =>
-							this._telemetry?.onError?.({
-								duration: performance.now() - startTime,
-								error: honeyError,
-								method,
-								path,
-							}),
-						log,
-					)
-					safeFire(
-						() =>
-							this._telemetry?.onResponse?.({
-								duration: performance.now() - startTime,
-								req: request,
-								status: customResult.status,
-							}),
+						() => s.telemetry?.onError?.({ duration: performance.now() - startTime, error: honeyError, method, path }),
 						log,
 					)
+					setCtxError(ctx, honeyError)
 					ctx._isErrorResponse = true
 					return customResult
 				}
 				/* customResult === undefined | void → fall through to default path */
-			} catch {
-				/* swallow onError errors */
+			} catch (e) {
+				log?.warn?.({ err: e }, "onError failed")
 			}
 		}
 
-		/* default error response */
 		safeFire(
-			() =>
-				this._telemetry?.onError?.({
-					duration: performance.now() - startTime,
-					error: honeyError,
-					method,
-					path,
-				}),
-			log,
-		)
-		const res = this._makeErrorCtx(fc).jsonFromError(honeyError)
-		safeFire(
-			() =>
-				this._telemetry?.onResponse?.({
-					duration: performance.now() - startTime,
-					req: request,
-					status: res.status,
-				}),
+			() => s.telemetry?.onError?.({ duration: performance.now() - startTime, error: honeyError, method, path }),
 			log,
 		)
+		setCtxError(ctx, honeyError)
 		ctx._isErrorResponse = true
-		return res
+		return this._makeErrorCtx(fc).jsonFromError(honeyError)
 	}
 
 	basePath<P extends string>(
 		prefix: P,
 	): Honey<TEnv, TCtx, TRoutes, TMeta, TErrorFactory, TDefaultErrors, MergePath<TBasePath, P>, TTaps, TScopedMw> {
-		const next = new Honey<
-			TEnv,
-			TCtx,
-			TRoutes,
-			TMeta,
-			TErrorFactory,
-			TDefaultErrors,
-			MergePath<TBasePath, P>,
-			TTaps,
-			TScopedMw
-		>({
-			chainMiddlewares: this._chainMiddlewares,
-			defaultErrorKeys: this._defaultErrorKeys,
-			globalMiddlewares: this._globalMiddlewares,
-			graph: this._graph,
-			scopedMiddlewares: this._scopedMiddlewares,
-		})
+		const next = this._derive()
 		next._basePath = mergePath(this._basePath, prefix)
-		next._defaultBoundaryKey = this._defaultBoundaryKey
-		next._errorFactory = this._errorFactory
-		next._errorSchema = this._errorSchema
-		next._customErrorFormatter = this._customErrorFormatter
-		next._customErrorSchema = this._customErrorSchema
-		next._errorFormatter = this._errorFormatter
-		next._errorI18n = this._errorI18n
-		next._logger = this._logger
-		next._outputValidation = this._outputValidation
-		next._stripPrefix = this._stripPrefix
-		next._trailingSlash = this._trailingSlash
-		next._wsAdapter = this._wsAdapter
-		next._onError = this._onError
-		next._onNotFound = this._onNotFound
-		next._onMethodNotAllowed = this._onMethodNotAllowed
-		next._chainMeta = this._chainMeta
-		next._contextValues = this._contextValues
-		next._taps = this._taps
-		next._telemetry = this._telemetry
-		next._realtimeBus = this._realtimeBus
-		next._realtimeRoutes = this._realtimeRoutes
-		next._staticRoutes = this._staticRoutes
-		next._hasRouteTree = this._hasRouteTree
-		next._hasWsRoutes = this._hasWsRoutes
 		return next as unknown as Honey<
 			TEnv,
 			TCtx,
@@ -818,52 +903,12 @@ export class Honey<
 		values: TAdds,
 	): Honey<TEnv, TCtx & Readonly<TAdds>, TRoutes, TMeta, TErrorFactory, TDefaultErrors, TBasePath, TTaps, TScopedMw> {
 		for (const key in values) {
-			if (STATIC_CTX_RESERVED.has(key)) {
+			if (RESERVED_CTX_KEYS.has(key)) {
 				throw new Error(`context() cannot set reserved key "${key}"`)
 			}
 		}
-		const next = new Honey<
-			TEnv,
-			TCtx & Readonly<TAdds>,
-			TRoutes,
-			TMeta,
-			TErrorFactory,
-			TDefaultErrors,
-			TBasePath,
-			TTaps,
-			TScopedMw
-		>({
-			chainMiddlewares: this._chainMiddlewares,
-			defaultErrorKeys: this._defaultErrorKeys,
-			globalMiddlewares: this._globalMiddlewares,
-			graph: this._graph,
-			scopedMiddlewares: this._scopedMiddlewares,
-		})
-		next._basePath = this._basePath
-		next._chainMeta = this._chainMeta
+		const next = this._derive()
 		next._contextValues = this._contextValues ? { ...this._contextValues, ...values } : { ...values }
-		next._defaultBoundaryKey = this._defaultBoundaryKey
-		next._errorFactory = this._errorFactory
-		next._errorSchema = this._errorSchema
-		next._customErrorFormatter = this._customErrorFormatter
-		next._customErrorSchema = this._customErrorSchema
-		next._errorFormatter = this._errorFormatter
-		next._errorI18n = this._errorI18n
-		next._logger = this._logger
-		next._outputValidation = this._outputValidation
-		next._stripPrefix = this._stripPrefix
-		next._trailingSlash = this._trailingSlash
-		next._wsAdapter = this._wsAdapter
-		next._onError = this._onError
-		next._onNotFound = this._onNotFound
-		next._onMethodNotAllowed = this._onMethodNotAllowed
-		next._taps = this._taps
-		next._telemetry = this._telemetry
-		next._realtimeBus = this._realtimeBus
-		next._realtimeRoutes = this._realtimeRoutes
-		next._staticRoutes = this._staticRoutes
-		next._hasRouteTree = this._hasRouteTree
-		next._hasWsRoutes = this._hasWsRoutes
 		return next as unknown as Honey<
 			TEnv,
 			TCtx & Readonly<TAdds>,
@@ -878,17 +923,50 @@ export class Honey<
 	}
 
 	logger(logger: Logger): this {
-		this._logger = logger
+		this._s.logger = logger
 		return this
 	}
 
-	outputValidation(mode: "always" | "dev" | "off"): this {
-		this._outputValidation = mode
+	outputValidation(mode: OutputValidationMode): this {
+		this._s.outputValidation = mode
+		this._bumpEpoch()
 		return this
 	}
 
 	trailingSlash(mode: "enforce" | "ignore" | "strip"): this {
-		this._trailingSlash = mode
+		this._s.trailingSlash = mode
+		return this
+	}
+
+	/**
+	 * Request paths containing an encoded `/` or `\` (`%2F`, `%5C`) answer 400 by default.
+	 * `"allow"` keeps them encoded in the path, so they decode into a param value
+	 * (`/repos/:id` with `/repos/group%2Fproject` gives `id === "group/project"`). Only allow
+	 * them when nothing downstream (a `proxy()` upstream, a file resolver) treats a decoded
+	 * slash as a separator.
+	 */
+	encodedSlashes(mode: "allow" | "reject"): this {
+		this._s.encodedSlashes = mode
+		return this
+	}
+
+	/**
+	 * Which reverse proxies in front of the app to believe. Decides `ctx.ip`, `clientInfo()`,
+	 * `ipRestrict`, and every other feature that needs the client's address, scheme or host.
+	 *
+	 * - `false` (default): the peer address the runtime reports is the client; `X-Forwarded-*`
+	 *   headers are ignored, since any client can send them.
+	 * - a hop count: exactly that many proxies, each appending its peer to `X-Forwarded-For`
+	 *   (nginx `$proxy_add_x_forwarded_for`, most load balancers). The client is the entry the
+	 *   outermost proxy wrote.
+	 * - addresses and CIDR ranges of your proxies: hops from those addresses are skipped; the
+	 *   first other address is the client.
+	 *
+	 * A hop count or list needs `import "@lovrozagar/honey/trust"` in the app entry.
+	 */
+	trustProxy(value: TrustProxy): this {
+		this._s.trust =
+			value === false || value === 0 ? TRUST_OFF : requireFeature("trust", "app.trustProxy()").compileTrust(value)
 		return this
 	}
 
@@ -898,19 +976,29 @@ export class Honey<
 		if (normalized.length > 0 && normalized.charCodeAt(0) !== 47) {
 			normalized = `/${normalized}`
 		}
-		this._stripPrefix = normalized === "" || normalized === "/" ? null : normalized
+		this._s.stripPrefix = normalized === "" || normalized === "/" ? null : normalized
 		return this
 	}
 
 	wsAdapter(adapter: WSAdapter): this {
-		this._wsAdapter = adapter
+		this._s.wsAdapter = adapter
 		return this
 	}
 
+	/**
+	 * Serve this app's OpenAPI document at `${path}.json`, `.yaml` and `.yml` (default
+	 * `/openapi`), and optionally a docs UI. Each call serves its own document: two calls with
+	 * different options (say an internal and a public profile) never share a cache. Documents
+	 * are generated once per route change, serialized once, and sent with an `ETag` and
+	 * `Cache-Control: no-cache`. Pass `enabled: false` (for example in production) to mount
+	 * nothing while keeping the call in place.
+	 */
 	openapi(options: {
 		description?: string
 		docs?: "scalar" | "swagger"
 		docsPath?: string
+		/** Mount the document and docs routes. Default `true`. */
+		enabled?: boolean
 		filterRoutes?: (route: { meta: unknown; method: string; path: string }) => boolean
 		path?: string
 		/** Named metaSpec profile selecting which emitted keys this document carries */
@@ -919,134 +1007,548 @@ export class Honey<
 		title: string
 		version: string
 	}): this {
+		if (options.enabled === false) return this
 		const stem = options.path ?? "/openapi"
-		const yamlHeaders = { headers: { "content-type": "application/yaml; charset=utf-8" } }
-		const loadJson = (): Promise<unknown> => {
-			const epoch = this._root.g ?? 0
-			if (this._openApiCache && this._openApiCache.epoch === epoch) {
-				return this._openApiCache.value
-			}
-			let pending: Promise<unknown>
-			pending = loadHoneyFeature("openapi")
-				.then(() =>
-					getOpenApiRuntime().generateOpenApi(this, {
-						filterRoutes: options.filterRoutes,
-						info: {
-							description: options.description,
-							title: options.title,
-							version: options.version,
-						},
-						/* a served document is not an authoring moment — the check belongs to `honey generate` */
-						invalidate: "off",
-						profile: options.profile,
-						securitySchemes: options.securitySchemes,
-					}),
-				)
-				.catch((err: unknown) => {
-					if (this._openApiCache?.value === pending) this._openApiCache = null
-					throw err
-				})
-			this._openApiCache = { epoch, value: pending }
-			return pending
-		}
-		const loadYaml = (): Promise<string> => {
-			const epoch = this._root.g ?? 0
-			if (this._openApiYamlCache && this._openApiYamlCache.epoch === epoch) {
-				return this._openApiYamlCache.value
-			}
-			let pending: Promise<string>
-			pending = Promise.resolve()
-				.then(async () => getOpenApiRuntime().toYaml(await loadJson()))
-				.catch((err: unknown) => {
-					if (this._openApiYamlCache?.value === pending) this._openApiYamlCache = null
-					throw err
-				})
-			this._openApiYamlCache = { epoch, value: pending }
-			return pending
-		}
-		this._mountInternalGet(`${stem}.json`, async (ctx) => ctx.res.json("ok", await loadJson()))
-		this._mountInternalGet(`${stem}.yml`, async (ctx) => ctx.res.text("ok", await loadYaml(), yamlHeaders))
-		this._mountInternalGet(`${stem}.yaml`, async (ctx) => ctx.res.text("ok", await loadYaml(), yamlHeaders))
+		const epochOf = (): number => this._graph.epoch
+		/* per call, not per app: each openapi() serves the document its own options describe */
+		const document = epochCached(epochOf, async () => {
+			await loadHoneyFeature("openapi")
+			return getOpenApiRuntime().generateOpenApi(this, {
+				filterRoutes: options.filterRoutes,
+				info: { description: options.description, title: options.title, version: options.version },
+				/* a served document is not an authoring moment — the check belongs to `honey generate` */
+				invalidate: "off",
+				profile: options.profile,
+				securitySchemes: options.securitySchemes,
+			})
+		})
+		/* the document first: it loads the runtime the serializers come from */
+		const json = epochCached(epochOf, async () => {
+			const doc = await document()
+			return getOpenApiRuntime().toServedArtifact(JSON.stringify(doc), "application/json")
+		})
+		const yaml = epochCached(epochOf, async () => {
+			const doc = await document()
+			const runtime = getOpenApiRuntime()
+			return runtime.toServedArtifact(runtime.toYaml(doc), "application/yaml; charset=utf-8")
+		})
+		const jsonPath = `${stem}.json`
+		this._mountArtifact("openapi", jsonPath, json)
+		this._mountArtifact("openapi", `${stem}.yml`, yaml)
+		this._mountArtifact("openapi", `${stem}.yaml`, yaml)
 		if (options.docs) {
-			const specUrl = mergePath(this._basePath, `${stem}.json`)
 			const docs = options.docs
+			const specPath = mergePath(this._basePath, jsonPath)
 			const ui = async (ctx: { res: HoneyRes }) => {
 				await loadHoneyFeature("openapi")
-				return getOpenApiRuntime().docsUi(docs, specUrl)(ctx)
+				/* the browser asks for the URL it sees: a stripped prefix is part of it */
+				const prefix = this._s.stripPrefix ?? ""
+				return getOpenApiRuntime().docsUi(docs, prefix + specPath)(ctx)
 			}
-			const preferred = options.docsPath ?? "/docs"
-			const candidates = options.docsPath ? [preferred] : [preferred, "/reference"]
-			let mounted = false
+			/* without an explicit docsPath, a user route at /docs moves the UI to /reference */
+			const candidates = options.docsPath ? [options.docsPath] : ["/docs", "/reference"]
+			let mounted: MountResult = "user"
+			let tried = candidates[0]
 			for (const p of candidates) {
-				if (this._mountInternalGet(p, ui)) {
-					mounted = true
-					break
-				}
+				tried = p
+				mounted = this._mountInternalGet(p, ui)
+				if (mounted !== "user") break
 			}
-			if (!mounted) {
-				throw new Error(`Honey.openapi({ docs }) cannot mount at ${preferred}: already registered. Pass docsPath.`)
+			if (mounted !== "mounted") {
+				const at = mergePath(this._basePath, tried)
+				throw new Error(
+					mounted === "internal"
+						? `Honey.openapi({ docs }) cannot mount at ${at}: an earlier openapi() or manifest() serves it. Pass docsPath.`
+						: `Honey.openapi({ docs }) cannot mount at ${at}: a route already owns it. Pass docsPath.`,
+				)
 			}
 		}
 		return this
 	}
 
-	manifest(options?: { path?: string }): this {
-		const path = options?.path ?? "/manifest.json"
-		const load = (): Promise<unknown> => {
-			const epoch = this._root.g ?? 0
-			if (this._manifestCache && this._manifestCache.epoch === epoch) {
-				return this._manifestCache.value
-			}
-			let pending: Promise<unknown>
-			pending = loadHoneyFeature("openapi")
-				.then(() => getOpenApiRuntime().generateManifest(this))
-				.catch((err: unknown) => {
-					if (this._manifestCache?.value === pending) this._manifestCache = null
-					throw err
-				})
-			this._manifestCache = { epoch, value: pending }
-			return pending
-		}
-		this._mountInternalGet(path, async (ctx) => ctx.res.json("ok", await load()))
+	/**
+	 * Serve the route manifest at `path` (default `/manifest.json`), filtered by the same
+	 * visibility policy as the OpenAPI document. Cached per route change, sent with an `ETag`.
+	 * `enabled: false` mounts nothing.
+	 */
+	manifest(options?: { enabled?: boolean; path?: string }): this {
+		if (options?.enabled === false) return this
+		const epochOf = (): number => this._graph.epoch
+		const artifact = epochCached(epochOf, async () => {
+			await loadHoneyFeature("openapi")
+			const runtime = getOpenApiRuntime()
+			return runtime.toServedArtifact(JSON.stringify(await runtime.generateManifest(this)), "application/json")
+		})
+		this._mountArtifact("manifest", options?.path ?? "/manifest.json", artifact)
 		return this
 	}
 
+	/** Mount a served document; a path another route or an earlier call owns is an error. */
+	private _mountArtifact(owner: "manifest" | "openapi", path: string, load: () => Promise<ServedArtifact>): void {
+		const result = this._mountInternalGet(path, async (ctx) => {
+			const c = ctx as unknown as { req: Request; res: HoneyRes }
+			const artifact = await load()
+			return c.res.raw(getOpenApiRuntime().artifactResponse(c.req, artifact))
+		})
+		if (result === "mounted") return
+		const at = mergePath(this._basePath, path)
+		throw new Error(
+			result === "internal"
+				? `Honey.${owner}() cannot mount GET ${at}: an earlier openapi() or manifest() serves it. Pass a different path.`
+				: `Honey.${owner}() cannot mount GET ${at}: a route already owns it. Pass a different path.`,
+		)
+	}
+
 	async serve(options?: HoneyServeOptions): Promise<ServeHandle> {
 		await loadHoneyFeature("serve")
 		return getServeRuntime()(this, options)
 	}
 
-	private _lookupGet(fullPath: string): RouteHandler | null {
-		const fromStatic = this._staticRoutes.map?.[`GET ${fullPath}`]
-		if (fromStatic) return fromStatic
-		const hit = matchRoute(this._root, "GET", fullPath)
-		if (hit !== null && hit.matched) return hit.handler
-		return null
-	}
-
-	/** Mount an internal GET. Returns false when a user route already owns the path. */
-	private _mountInternalGet(path: string, fn: (ctx: { res: HoneyRes }) => Response | Promise<Response>): boolean {
+	/**
+	 * Mount an internal GET (spec, docs, manifest). Reports who owns the path when it cannot:
+	 * a user route (`"user"`) or an earlier internal mount (`"internal"`). Only an exact leaf
+	 * counts: a `/:slug` or `/*rest` route does not block a static internal path, which wins
+	 * over it on precedence, with backtracking, in both the runtime and a loaded tree.
+	 */
+	private _mountInternalGet(path: string, fn: (ctx: { res: HoneyRes }) => Response | Promise<Response>): MountResult {
 		const fullPath = mergePath(this._basePath, path)
-		const existing = this._lookupGet(fullPath)
-		if (existing) return existing._skip === true
+		const segments = parsePattern(fullPath)
+		const id = routeId("GET", fullPath)
+		const g = this._graph
+		const existing = g.records.get(id)
+		if (existing) return existing._skip === true ? "internal" : "user"
+		const leaf = findLeaf(g.root, segments, "GET")
+		if (leaf !== undefined && leaf !== id) return "user"
+		if (findLeaf(g.root, segments, "ALL") !== undefined) return "user"
+		/* a leaf the loaded tree holds for a user route the app has yet to register */
+		if (leaf === id && g.loaded?.has(id)) return "user"
 		const routeHandler: RouteHandler = {
 			_skip: true,
-			bek: this._defaultBoundaryKey,
-			ef: null,
-			ek: this._defaultErrorKeys,
+			bek: null,
+			cm: [...this._chain],
+			cv: this._contextValues,
+			dk: new Set(),
+			ek: new Set(),
 			fn: (ctx) => fn(ctx as { res: HoneyRes }),
 			iv: null,
 			mt: null,
-			mw: [...this._chainMiddlewares],
+			mw: [],
 			os: null,
 			ov: null,
-			rp: fullPath,
+			own: g.settings,
+			rb: null,
+			rm: [],
+			xm: null,
 		}
-		insertRoute(this._root, "GET", fullPath, routeHandler)
-		if (!fullPath.includes(":") && !fullPath.includes("*")) {
-			this._registerStatic(`GET ${fullPath}`, routeHandler)
+		this._markUsed()
+		this._addRoute("GET", segments, routeHandler)
+		return "mounted"
+	}
+
+	private _bumpEpoch(): void {
+		this._graph.epoch++
+	}
+
+	/** Place `id` at every leaf of `segments`, copying a shared (loaded) root first. */
+	private _placeLeaves(segments: readonly Segment[], method: string, id: RouteId): void {
+		const g = this._graph
+		const variants = leafVariants(segments)
+		if (variants.every((v) => findLeaf(g.root, v, method) === id)) return
+		if (g.rootShared) {
+			g.root = cloneTree(g.root)
+			g.rootShared = false
 		}
-		return true
+		for (const v of variants) insertLeaf(g.root, v, method, id)
+	}
+
+	/**
+	 * @internal — register one route record. Over a loaded tree the record binds to the leaf
+	 * the tree already holds for its id; a root wildcard the tree lacks becomes the gateway
+	 * catch-all; any other unknown route marks the tree as stale (reported at finalize).
+	 */
+	_addRoute(method: string, segments: readonly Segment[], record: RouteHandler): void {
+		const pattern = canonical(segments)
+		const id = routeId(method, pattern)
+		const g = this._graph
+		if (g.records.has(id) || (isRootWildcard(segments) && g.catchAll.has(method))) {
+			throw new Error(`Duplicate route: ${id}`)
+		}
+		record.id = id
+		record.rp = pattern
+		if (g.loaded !== null && record._skip !== true) {
+			const known = leafVariants(segments).every((v) => findLeaf(g.root, v, method) === id)
+			if (!known) {
+				if (isRootWildcard(segments)) {
+					record.ca = true
+					g.catchAll.set(method, record)
+					this._bumpEpoch()
+					return
+				}
+				g.unexpected.add(id)
+			}
+		}
+		this._placeLeaves(segments, method, id)
+		g.records.set(id, record)
+		this._bumpEpoch()
+	}
+
+	/** @internal — register one websocket (or realtime) route record. */
+	_addWsRoute(segments: readonly Segment[], record: WSRouteHandler): void {
+		const pattern = canonical(segments)
+		const id = routeId("WS", pattern)
+		const g = this._graph
+		if (g.wsRecords.has(id)) throw new Error(`Duplicate WebSocket route: ${pattern}`)
+		record.id = id
+		record.rp = pattern
+		if (g.loaded !== null && leafVariants(segments).some((v) => findLeaf(g.root, v, "WS") !== id)) {
+			g.unexpected.add(id)
+		}
+		this._placeLeaves(segments, "WS", id)
+		g.wsRecords.set(id, record)
+		g.hasWs = true
+		this._bumpEpoch()
+	}
+
+	/**
+	 * Resolve what this graph serves: registered records, live records carried by a loaded
+	 * snapshot, and delegated leaves the gateway catch-all serves. Then resolve every record —
+	 * its full chain (`chain → scoped → route → input validation`), error keys, meta and error
+	 * factory — and compile it once. Re-runs whenever the graph's epoch moved. Throws, naming
+	 * every route, when a loaded tree and the registered routes disagree (the generated file is
+	 * stale), and when a `use(mw)` handle or a route builder was left unused (the middleware or
+	 * route would silently be missing).
+	 */
+	_finalize(): FinalTable {
+		const g = this._graph
+		if (g.final !== null && g.final.epoch === g.epoch) return g.final
+		this._assertNothingDiscarded()
+		const byId = new Map<RouteId, RouteHandler>()
+		const wsById = new Map<RouteId, WSRouteHandler>()
+		for (const [id, r] of g.records) byId.set(id, r)
+		for (const [id, r] of g.wsRecords) wsById.set(id, r)
+		const problems: string[] = []
+		if (g.loaded !== null) {
+			for (const id of g.unexpected) problems.push(`${id} is registered but missing from the loaded route tree`)
+			let delegated = 0
+			for (const [id, entry] of g.loaded) {
+				const { method, pattern } = splitRouteId(id)
+				if (method === "WS") {
+					if (wsById.has(id)) continue
+					if (entry.h !== undefined) {
+						const live = copyRecord(entry.h as WSRouteHandler)
+						live.id = id
+						live.rp = pattern
+						wsById.set(id, live)
+					}
+					/* a websocket leaf nothing serves is not upgraded: the request falls through to HTTP */
+					continue
+				}
+				if (byId.has(id)) continue
+				if (entry.h !== undefined) {
+					const live = copyRecord(entry.h as RouteHandler)
+					live.id = id
+					live.rp = pattern
+					byId.set(id, live)
+					continue
+				}
+				const ca = g.catchAll.get(method) ?? g.catchAll.get("ALL")
+				if (ca !== undefined) {
+					const dl = copyRecord(ca)
+					dl.dl = true
+					dl.id = id
+					dl.rp = pattern
+					dl.xm = entry.mt ? { ...entry.mt } : null
+					dl.iv = entry.iv ?? null
+					dl.os = entry.os ?? null
+					dl.dk = new Set([...(ca.dk ?? []), ...(entry.ek ?? [])])
+					if (entry.bek !== undefined && entry.bek !== null) dl.rb = entry.bek
+					byId.set(id, dl)
+					delegated++
+					continue
+				}
+				/* no handler anywhere: documented (served specs list it) but answered with 404 */
+				byId.set(id, {
+					bek: null,
+					cm: [],
+					dk: new Set(entry.ek ?? []),
+					dl: true,
+					ek: new Set(),
+					fn: NOT_SERVED,
+					id,
+					iv: entry.iv ?? null,
+					mt: null,
+					mw: [],
+					os: entry.os ?? null,
+					rb: entry.bek ?? null,
+					rm: [],
+					rp: pattern,
+					xm: entry.mt ? { ...entry.mt } : null,
+				})
+			}
+			if (g.catchAll.size > 0 && delegated === 0) {
+				for (const id of g.catchAll.keys()) {
+					problems.push(`ALL root wildcard (${g.catchAll.get(id)?.id}) is missing from the loaded route tree`)
+				}
+			}
+		}
+		if (problems.length > 0) {
+			throw new Error(`Route tree out of date — regenerate it (\`honey generate\`):\n  ${problems.join("\n  ")}`)
+		}
+
+		const convert: ChainErrorConverter = (thrown, ctx) => this._convertError(thrown, ctx as HoneyContext<TEnv>)
+		const plans = new Map<RouteId, Plan>()
+		const wsPlans = new Map<RouteId, Plan>()
+		const statics = Object.create(null) as Record<string, Plan>
+		const userChains: RuntimeMiddleware[][] = []
+		for (const [id, r] of byId) {
+			const plan = this._planRoute(r, convert)
+			plans.set(id, plan)
+			if (r._skip !== true && r.dl !== true) userChains.push(r.cm ?? [])
+			const { method, segments } = patternOf(id)
+			for (const v of leafVariants(segments)) {
+				if (isStaticPattern(v)) statics[`${method} ${canonical(v)}`] = plan
+			}
+		}
+		for (const [id, r] of wsById) {
+			wsPlans.set(id, this._planWs(r, convert))
+			userChains.push(r.cm ?? [])
+		}
+		/* an app with no routes (static files only) has nothing but the handles that serve it */
+		if (userChains.length === 0) for (const chain of g.served) userChains.push(chain)
+		const miss = this._planMiss(commonPrefix(userChains), convert)
+		g.final = { byId, convert, epoch: g.epoch, miss, plans, statics, wsById, wsPlans }
+		return g.final
+	}
+
+	/** `use(mw)` handles that never registered, mounted or served, and builders without `.handler()`. */
+	private _assertNothingDiscarded(): void {
+		const g = this._graph
+		const problems: string[] = []
+		for (const node of g.chains) {
+			if (node.used) continue
+			problems.push(
+				`app.use(${describeMw(node.mw)}) returned a handle that never registers a route, so the middleware runs nowhere. ` +
+					"use() does not change the handle it is called on: keep the returned value and register routes on it " +
+					"(`const authed = app.use(auth); authed.get(...)`), or chain it (`honey().use(mw).get(...)`).",
+			)
+		}
+		for (const p of g.pending) {
+			problems.push(`${p.id} was declared but never got a .handler() (or .proxy()), so the route is not registered.`)
+		}
+		if (problems.length > 0) throw new Error(`honey: ${problems.join("\n  ")}`)
+	}
+
+	/**
+	 * Resolve a record against this graph: chain = captured chain, the scopes that cover its
+	 * pattern (behind a request-path check where only some of its paths are inside), then its
+	 * route middleware. Error keys and contributed meta come from that chain, in run order.
+	 * The error factory, default errors and boundary come from the app the route was
+	 * registered on when that app has a factory, else from this one.
+	 */
+	private _resolve(
+		r: RouteHandler | WSRouteHandler,
+		everyScope = false,
+	): { enf: boolean; own: AppSettings<unknown>; taps: Map<string, TapFn<unknown>> | null } {
+		const s = this._graph.settings
+		const own = (r.own as AppSettings<unknown> | undefined) ?? s
+		const src = own.errorFactory !== null ? own : s
+		const segments = parsePattern(r.rp ?? "/")
+		const scoped: RuntimeMiddleware[] = []
+		for (const entry of this._graph.scoped) {
+			if (everyScope) {
+				scoped.push(entry.guard)
+				continue
+			}
+			const cov = scopeCoverage(segments, entry.segs)
+			if (cov === "all") scoped.push(entry.mw)
+			else if (cov === "some") scoped.push(entry.guard)
+		}
+		const mw = [...this._graph.global.values(), ...(r.cm ?? []), ...scoped, ...(r.rm ?? [])]
+		/* app defaults, then what the middleware declares in run order, then the route's own */
+		const ek = new Set<string>(src.defaultErrorKeys)
+		for (const m of mw) {
+			const errs = errorsOf(m)
+			if (errs) for (const k of errs) ek.add(k)
+		}
+		if (r.dk !== undefined) for (const k of r.dk) ek.add(k)
+		const bek = r.rb ?? src.defaultBoundaryKey
+		if (bek !== null) ek.add(bek)
+		const enf = ek.size > 0
+		const fac = src.errorFactory
+		let ef: ErrorFactoryRecord | null = fac
+		if (fac !== null && enf) {
+			const subset = Object.create(null) as ErrorFactoryRecord
+			for (const key of ek) {
+				if (key in fac) subset[key] = fac[key] as ErrorFactoryRecord[string]
+			}
+			ef = Object.freeze(subset)
+		}
+		r.mw = mw
+		r.ek = ek
+		r.bek = bek
+		r.fac = fac
+		r.ef = ef
+		r.mt = mergeContributedMeta(collectMiddlewareMeta([mw]), r.xm ? { ...r.xm } : null)
+		/* the serving app's taps win; a route from another app keeps that app's for the rest */
+		const taps =
+			own === s || own.taps === null ? s.taps : s.taps === null ? own.taps : new Map([...own.taps, ...s.taps])
+		return { enf, own, taps }
+	}
+
+	/** Wrap each middleware for `telemetry.onMiddleware`, once per finalize. */
+	private _timed(chain: RuntimeMiddleware[]): RuntimeMiddleware[] {
+		const onMw = this._graph.settings.telemetry?.onMiddleware
+		if (onMw === undefined) return chain
+		const log = this._graph.settings.logger ?? undefined
+		return chain.map((m) => timedMiddleware(m, onMw, log))
+	}
+
+	private _planRoute(r: RouteHandler, convert: ChainErrorConverter): Plan {
+		const { enf, own, taps } = this._resolve(r)
+		const s = this._graph.settings
+		const ovm = own.outputValidation ?? s.outputValidation ?? "off"
+		const base = this._timed(r.mw)
+		const chain = [...base]
+		/* a delegated route's schemas document it; the body is forwarded, never validated here */
+		const iv = r.iv
+		if (iv && r.dl !== true) {
+			chain.push((ctx, next) =>
+				validateInput(
+					iv,
+					ctx["req"] as Request,
+					ctx["params"] as Record<string, string>,
+					ctx as { searchAll?: Record<string, string[]> },
+				).then((validated) => {
+					ctx["input"] = validated
+					return next()
+				}),
+			)
+		}
+		const fn = r.fn
+		const handler: CompiledChain =
+			r.os && ovm !== "off"
+				? (ctx) => {
+						const res = fn(ctx)
+						if (!shouldValidateOutput(ovm)) return res
+						return res instanceof Promise
+							? res.then((v) => this._validateOutput(r, ctx as HoneyContext<TEnv>, v))
+							: this._validateOutput(r, ctx as HoneyContext<TEnv>, res)
+					}
+				: (fn as CompiledChain)
+		return {
+			cv: r.cv ?? null,
+			enf,
+			pf: null,
+			pfChain: base,
+			r,
+			rt: null,
+			run: compileChain(chain, handler, convert),
+			taps,
+		}
+	}
+
+	private _planWs(r: WSRouteHandler, convert: ChainErrorConverter): Plan {
+		const { enf } = this._resolve(r)
+		const rt = this._graph.realtimeRoutes.get(r.rp) ?? null
+		const chain = this._timed(r.mw)
+		const iv = r.iv
+		if (iv) {
+			chain.push((ctx, next) =>
+				validateInput(
+					iv,
+					ctx["req"] as Request,
+					ctx["params"] as Record<string, string>,
+					ctx as { searchAll?: Record<string, string[]> },
+				).then((validated) => {
+					ctx["input"] = validated
+					return next()
+				}),
+			)
+		}
+		const terminal: CompiledChain =
+			rt !== null
+				? (ctx) => this._realtimeUpgrade(ctx as HoneyContext<TEnv>, rt)
+				: (ctx) => this._wsUpgrade(ctx as HoneyContext<TEnv>)
+		return {
+			cv: r.cv ?? null,
+			enf,
+			pf: null,
+			pfChain: [],
+			r,
+			rt,
+			run: compileChain(chain, terminal, convert),
+			taps: null,
+		}
+	}
+
+	/**
+	 * 404 and 405 run through the same pipeline as a route: the middleware every route of this
+	 * graph starts with (with no routes: every handle that served a request), then every scope
+	 * (behind its request-path check), then the 404/405 answer. So a logger or CORS policy on the whole app also covers unknown paths, and a
+	 * scope's guard answers before "not found" leaks what exists under it.
+	 */
+	private _planMiss(prefix: RuntimeMiddleware[], convert: ChainErrorConverter): Plan {
+		const r: RouteHandler = {
+			bek: null,
+			cm: prefix,
+			dk: new Set(),
+			ek: new Set(),
+			fn: (ctx) => {
+				const fc = (ctx as HoneyContext<TEnv>)._rq as FetchCtx<TEnv>
+				return fc.allowed !== null ? this._make405(fc, fc.allowed) : this._make404(fc)
+			},
+			mt: null,
+			mw: [],
+			rm: [],
+			rp: "",
+			xm: null,
+		}
+		/* every scope, each behind its path check — the request path decides */
+		const { enf } = this._resolve(r, true)
+		return {
+			cv: null,
+			enf,
+			pf: null,
+			pfChain: [],
+			r,
+			rt: null,
+			run: compileChain(this._timed(r.mw), r.fn as CompiledChain, convert),
+			taps: null,
+		}
+	}
+
+	/**
+	 * @internal — every served route as one entry per leaf (an optional param yields two
+	 * paths), in tree order. Codegen and OpenAPI read routes through this.
+	 */
+	_collectRoutes(includeSkipped = false): Array<{ handler: RouteHandler; method: string; path: string }> {
+		const final = this._finalize()
+		const out: Array<{ handler: RouteHandler; method: string; path: string }> = []
+		forEachLeaf(this._root, (method, path, id) => {
+			if (method === "WS") return
+			const handler = final.byId.get(id)
+			if (handler === undefined) return
+			if (handler._skip && !includeSkipped) return
+			out.push({ handler, method, path })
+		})
+		return out
+	}
+
+	/** @internal — websocket routes, one entry per leaf. */
+	_collectWsRoutes(): Array<{ handler: WSRouteHandler; path: string }> {
+		const final = this._finalize()
+		const out: Array<{ handler: WSRouteHandler; path: string }> = []
+		forEachLeaf(this._root, (method, path, id) => {
+			if (method !== "WS") return
+			const handler = final.wsById.get(id)
+			if (handler !== undefined) out.push({ handler, path })
+		})
+		return out
+	}
+
+	/** @internal — the route-graph epoch; served documents cache against it. */
+	get _epoch(): number {
+		return this._graph.epoch
 	}
 
 	defaultErrorFormatter<TSchema extends StandardSchemaLike>(
@@ -1058,13 +1560,14 @@ export class Honey<
 		schemaOrFn: ErrorFormatterFn | StandardSchemaLike,
 		maybeFn?: (error: HoneyError) => unknown,
 	): this {
+		const s = this._s
 		if (typeof schemaOrFn === "function") {
-			this._errorSchema = null
-			this._errorFormatter = schemaOrFn
+			s.errorSchema = null
+			s.errorFormatter = schemaOrFn
 		} else {
-			this._errorSchema = schemaOrFn
+			s.errorSchema = schemaOrFn
 			const mapper = maybeFn as (error: HoneyError) => Record<string, unknown>
-			this._errorFormatter = (error) => mapper(error)
+			s.errorFormatter = (error) => mapper(error)
 		}
 		return this
 	}
@@ -1078,56 +1581,35 @@ export class Honey<
 		schemaOrFn: CustomErrorFormatter | StandardSchemaLike,
 		maybeFn?: (error: HoneyError, data: Record<string, unknown>) => unknown,
 	): this {
+		const s = this._s
 		if (typeof schemaOrFn === "function") {
-			this._customErrorSchema = null
-			this._customErrorFormatter = schemaOrFn
+			s.customErrorSchema = null
+			s.customErrorFormatter = schemaOrFn
 		} else {
-			this._customErrorSchema = schemaOrFn
+			s.customErrorSchema = schemaOrFn
 			const mapper = maybeFn as (error: HoneyError, data: Record<string, unknown>) => Record<string, unknown>
-			this._customErrorFormatter = (error, data) => mapper(error, data)
+			s.customErrorFormatter = (error, data) => mapper(error, data)
 		}
 		return this
 	}
 
 	errorI18n(config: ErrorI18nConfig<TEnv>): this {
-		this._errorI18n = config
+		this._s.errorI18n = config
 		return this
 	}
 
-	onError(
-		handler: (
-			error: unknown,
-			ctx: {
-				env: TEnv
-				jsonFromError: (err: HoneyError) => Response
-				req: Request
-			},
-		) => HoneyError | Response | Promise<HoneyError | Response | undefined | void> | undefined | void,
-	): this {
-		this._onError = handler
+	onError(handler: OnErrorFn<TEnv>): this {
+		this._s.onError = handler
 		return this
 	}
 
-	onMethodNotAllowed(
-		handler: (ctx: {
-			allowed: string[]
-			env: TEnv
-			jsonFromError: (err: HoneyError) => Response
-			req: Request
-		}) => Response | Promise<Response>,
-	): this {
-		this._onMethodNotAllowed = handler
+	onMethodNotAllowed(handler: OnMethodNotAllowedFn<TEnv>): this {
+		this._s.onMethodNotAllowed = handler
 		return this
 	}
 
-	onNotFound(
-		handler: (ctx: {
-			env: TEnv
-			jsonFromError: (err: HoneyError) => Response
-			req: Request
-		}) => Response | Promise<Response>,
-	): this {
-		this._onNotFound = handler
+	onNotFound(handler: OnNotFoundFn<TEnv>): this {
+		this._s.onNotFound = handler
 		return this
 	}
 
@@ -1136,51 +1618,227 @@ export class Honey<
 		key: K,
 		handler: (ctx: TapContext<TEnv>, payload: K extends keyof TTaps ? TTaps[K] : unknown) => void | Promise<void>,
 	): this {
-		if (this._taps === null) {
-			this._taps = new Map()
-		}
-		this._taps.set(key, handler as (ctx: TapContext<TEnv>, payload: unknown) => void | Promise<void>)
+		const s = this._s
+		if (s.taps === null) s.taps = new Map()
+		s.taps.set(key, handler as TapFn<TEnv>)
+		this._bumpEpoch()
 		return this
 	}
 
 	telemetry(adapter: TelemetryAdapter): this {
-		this._telemetry = adapter
+		this._s.telemetry = adapter
+		/* onMiddleware wraps the compiled chains */
+		this._bumpEpoch()
 		return this
 	}
 
+	/**
+	 * Load a route tree — a generated `routes.gen.ts`, an `app.toRouteTree()` snapshot, or a
+	 * `mergeTree()` of either. The tree supplies the router topology; what each route runs
+	 * comes from the routes this app registers afterwards (bound by `RouteId`), from live
+	 * records in a snapshot, or — for leaves with neither — from a root wildcard the app
+	 * registers as its gateway catch-all. Must be called before any route is registered.
+	 */
 	routeTree(tree: RouteTree): this {
-		this._root = tree.root
-		this._handlerMap = tree.handlers ?? null
-		this._hasRouteTree = true
+		assertTreeFormat(tree)
+		const g = this._graph
+		if (g.loaded !== null) throw new Error("routeTree() was already called on this app")
+		for (const r of g.records.values()) {
+			if (r._skip !== true) throw new Error(`routeTree() must be called before routes are registered (${r.id} is)`)
+		}
+		if (g.wsRecords.size > 0 || g.catchAll.size > 0) {
+			throw new Error("routeTree() must be called before routes are registered")
+		}
+		forEachLeaf(tree.root, (method, path, id) => {
+			if (!(id in tree.routes)) throw new Error(`routeTree(): leaf ${method} ${path} has no route entry (${id})`)
+		})
+		const internals = [...g.records.values()]
+		g.records.clear()
+		g.root = freezeTree(tree.root)
+		g.rootShared = true
+		g.loaded = new Map()
+		for (const id of Object.keys(tree.routes)) g.loaded.set(id, { ...tree.routes[id] })
+		if (hasWsLeaf(g.root)) g.hasWs = true
+		/* internal routes mounted before the tree was loaded move onto the loaded topology */
+		for (const r of internals) {
+			const { method, segments } = patternOf(r.id as RouteId)
+			this._addRoute(method, segments, r)
+		}
+		this._bumpEpoch()
 		return this
 	}
 
+	/**
+	 * Snapshot this app's routes as a tree: a copy of the topology plus, per route, its data
+	 * and its live record. Internal routes (spec, docs, manifest) are left out. Loading the
+	 * snapshot into another app serves these records; nothing in it is shared with this app.
+	 * Each record keeps this app's settings (error factory, defaults, boundary) and context
+	 * values, and carries the scoped middleware that covers it here as part of its chain —
+	 * scopes themselves do not travel in a tree.
+	 */
 	toRouteTree(): RouteTree {
-		return { meta: {}, root: this._root }
+		this._markUsed()
+		const final = this._finalize()
+		const routes = Object.create(null) as Record<RouteId, RouteEntry>
+		const keep = new Set<RouteId>()
+		for (const [id, r] of final.byId) {
+			if (r._skip) continue
+			keep.add(id)
+			routes[id] = {
+				bek: r.bek,
+				ek: [...r.ek],
+				h: this._bake(r),
+				iv: r.iv ?? null,
+				mt: r.mt,
+				os: r.os ?? null,
+			}
+		}
+		for (const [id, r] of final.wsById) {
+			keep.add(id)
+			routes[id] = { bek: r.bek, ek: [...r.ek], h: this._bake(r), iv: r.iv, mt: r.mt }
+		}
+		const root = createNode()
+		forEachLeaf(this._root, (method, path, id) => {
+			if (keep.has(id)) insertLeaf(root, parsePattern(path), method, id)
+		})
+		return { meta: {}, root, routes, v: ROUTE_TREE_VERSION }
 	}
 
+	/** A resolved record as a standalone source: its resolved chain minus route middleware becomes its chain. */
+	private _bake<T extends RouteHandler | WSRouteHandler>(r: T): T {
+		const h = copyRecord(r)
+		const rm = r.rm ?? []
+		/* app-wide middleware stays with the app; scopes travel as part of the chain */
+		h.cm = r.mw.slice(this._graph.global.size, r.mw.length - rm.length)
+		h.rm = [...rm]
+		h.dk = new Set(r.ek)
+		h.rb = r.bek
+		h.xm = r.mt ? { ...r.mt } : null
+		h.own = r.own ?? this._graph.settings
+		return h
+	}
+
+	/**
+	 * @internal — generate-time: copy input/output schemas from `source` onto this app's
+	 * routes that lack them (a gateway serves its generated tree, which carries none).
+	 */
+	_overlaySchemas(source: RouteTree): void {
+		const g = this._graph
+		for (const [id, entry] of Object.entries(source.routes)) {
+			const iv = entry.iv ?? (entry.h as RouteHandler | undefined)?.iv ?? null
+			const os = entry.os ?? (entry.h as RouteHandler | undefined)?.os ?? null
+			if (iv === null && os === null) continue
+			const record = g.records.get(id)
+			if (record !== undefined) {
+				record.iv ??= iv
+				record.os ??= os
+				continue
+			}
+			const loaded = g.loaded?.get(id)
+			if (loaded !== undefined) {
+				loaded.iv ??= iv
+				loaded.os ??= os
+			}
+		}
+		this._bumpEpoch()
+	}
+
+	/**
+	 * @internal — generate-time: the route tree a gateway serves. `source` is the merged
+	 * downstream tree (`codegen.mergeTree`); the gateway's own registered routes join it as
+	 * ordinary leaves, while its root wildcards stay out of the tree — they are the catch-all
+	 * the downstream leaves delegate to. An own route that is also a downstream route, or
+	 * whose topology conflicts with one, throws here instead of at request time. The app is
+	 * rebound to the result, so codegen that runs next (OpenAPI, manifest) sees what it serves.
+	 */
+	_gatewayTree(source: RouteTree): RouteTree {
+		assertTreeFormat(source)
+		const g = this._graph
+		const root = cloneTree(source.root)
+		const routes = dict<RouteEntry>()
+		for (const id of Object.keys(source.routes)) {
+			const { bek, ek, i, mt } = source.routes[id]
+			routes[id] = { bek, ek, i, mt }
+		}
+		const own: { method: string; segments: Segment[]; id: RouteId }[] = []
+		/* every route id this app serves, root wildcards included */
+		const served = new Set<string>()
+		for (const r of [...g.records.values(), ...g.catchAll.values(), ...g.wsRecords.values()]) {
+			if ((r as RouteHandler)._skip === true) continue
+			const id = r.id as RouteId
+			served.add(id)
+			const { method, segments } = patternOf(id)
+			if (!isRootWildcard(segments)) own.push({ id, method, segments })
+		}
+		const overlap = own.filter((o) => o.id in routes)
+		/* a merge source built from this app itself (`app.toRouteTree()`) holds exactly the routes
+		   this app serves; anything else that overlaps is a gateway route shadowing a downstream
+		   one — judged by the route sets, never by how many routes overlap */
+		const sourceIds = Object.keys(routes)
+		const isSelf = own.length > 0 && overlap.length === own.length && sourceIds.every((id) => served.has(id))
+		if (overlap.length > 0 && !isSelf) {
+			throw new Error(
+				`Gateway routes are also downstream routes in the merged tree: ${overlap.map((o) => o.id).join(", ")}`,
+			)
+		}
+		if (isSelf) own.length = 0
+		for (const { id, method, segments } of own) {
+			for (const v of leafVariants(segments)) insertLeaf(root, v, method, id)
+			routes[id] = {}
+		}
+		this._replaceLoadedTree({ meta: { ...source.meta }, root, routes, v: ROUTE_TREE_VERSION })
+		/* own routes resolved over the rebound tree carry their final error keys and meta */
+		const snapshot = this.toRouteTree()
+		for (const { id } of own) {
+			const { bek, ek, mt } = snapshot.routes[id]
+			routes[id] = { bek, ek, mt }
+		}
+		const tree: RouteTree = { meta: { ...source.meta }, root, routes, v: ROUTE_TREE_VERSION }
+		this._replaceLoadedTree(tree)
+		return tree
+	}
+
+	/** @internal — swap the loaded tree, re-binding every registered route to it. */
+	_replaceLoadedTree(tree: RouteTree): void {
+		const g = this._graph
+		const http = [...g.records.values(), ...g.catchAll.values()]
+		const ws = [...g.wsRecords.values()]
+		g.records.clear()
+		g.catchAll.clear()
+		g.wsRecords.clear()
+		g.unexpected.clear()
+		g.loaded = null
+		g.root = createNode()
+		g.rootShared = false
+		g.hasWs = false
+		this.routeTree(tree)
+		for (const r of http) {
+			delete r.ca
+			const { method, segments } = patternOf(r.id as RouteId)
+			this._addRoute(method, segments, r)
+		}
+		for (const r of ws) this._addWsRoute(patternOf(r.id as RouteId).segments, r)
+	}
+
+	/**
+	 * Set the app's error factory. Like every app setting it applies to every handle of this
+	 * app, whenever it is called; routes mounted from another app keep that app's factory.
+	 */
 	errorFactory<TFactory extends Record<string, (...args: never[]) => unknown>>(
 		factory: TFactory,
 	): Honey<TEnv, TCtx, TRoutes, TMeta, TFactory, TDefaultErrors, TBasePath, TTaps, TScopedMw> {
-		const next = this as unknown as Honey<
-			TEnv,
-			TCtx,
-			TRoutes,
-			TMeta,
-			TFactory,
-			TDefaultErrors,
-			TBasePath,
-			TTaps,
-			TScopedMw
-		>
-		next._errorFactory = factory
-		return next
+		this._s.errorFactory = factory
+		this._bumpEpoch()
+		return this as unknown as Honey<TEnv, TCtx, TRoutes, TMeta, TFactory, TDefaultErrors, TBasePath, TTaps, TScopedMw>
 	}
 
+	/** Error keys every route of this app declares — applies to routes registered before and after the call. */
 	defaultErrors<TKeys extends ([TErrorFactory] extends [never] ? never : keyof TErrorFactory & string)>(
 		...keys: TKeys[]
 	): Honey<TEnv, TCtx, TRoutes, TMeta, TErrorFactory, TDefaultErrors | TKeys, TBasePath, TTaps, TScopedMw> {
-		const next = this as unknown as Honey<
+		for (const k of keys) this._s.defaultErrorKeys.add(k)
+		this._bumpEpoch()
+		return this as unknown as Honey<
 			TEnv,
 			TCtx,
 			TRoutes,
@@ -1191,16 +1849,15 @@ export class Honey<
 			TTaps,
 			TScopedMw
 		>
-		for (const k of keys) {
-			next._defaultErrorKeys.add(k)
-		}
-		return next
 	}
 
 	defaultBoundary<TKey extends ([TErrorFactory] extends [never] ? never : keyof TErrorFactory & string)>(
 		key: TKey,
 	): Honey<TEnv, TCtx, TRoutes, TMeta, TErrorFactory, TDefaultErrors | TKey, TBasePath, TTaps, TScopedMw> {
-		const next = this as unknown as Honey<
+		this._s.defaultBoundaryKey = key
+		this._s.defaultErrorKeys.add(key)
+		this._bumpEpoch()
+		return this as unknown as Honey<
 			TEnv,
 			TCtx,
 			TRoutes,
@@ -1211,9 +1868,6 @@ export class Honey<
 			TTaps,
 			TScopedMw
 		>
-		next._defaultBoundaryKey = key
-		next._defaultErrorKeys.add(key)
-		return next
 	}
 
 	/** Phantom overload — constrains what route-level .meta() accepts */
@@ -1244,39 +1898,19 @@ export class Honey<
 			return this as Honey<TEnv, TCtx, TRoutes, unknown, TErrorFactory, TDefaultErrors, TBasePath, TTaps, TScopedMw>
 		}
 		/* chain-level meta — copy-on-write */
-		const next = new Honey<TEnv, TCtx, TRoutes, unknown, TErrorFactory, TDefaultErrors, TBasePath, TTaps, TScopedMw>({
-			chainMiddlewares: this._chainMiddlewares,
-			defaultErrorKeys: this._defaultErrorKeys,
-			globalMiddlewares: this._globalMiddlewares,
-			graph: this._graph,
-			scopedMiddlewares: this._scopedMiddlewares,
-		})
-		next._basePath = this._basePath
+		const next = this._derive()
 		next._chainMeta = this._chainMeta ? { ...this._chainMeta, ...values } : { ...values }
-		next._contextValues = this._contextValues
-		next._defaultBoundaryKey = this._defaultBoundaryKey
-		next._errorFactory = this._errorFactory
-		next._errorSchema = this._errorSchema
-		next._customErrorFormatter = this._customErrorFormatter
-		next._customErrorSchema = this._customErrorSchema
-		next._errorFormatter = this._errorFormatter
-		next._errorI18n = this._errorI18n
-		next._logger = this._logger
-		next._outputValidation = this._outputValidation
-		next._stripPrefix = this._stripPrefix
-		next._trailingSlash = this._trailingSlash
-		next._wsAdapter = this._wsAdapter
-		next._onError = this._onError
-		next._onNotFound = this._onNotFound
-		next._onMethodNotAllowed = this._onMethodNotAllowed
-		next._taps = this._taps
-		next._telemetry = this._telemetry
-		next._realtimeBus = this._realtimeBus
-		next._realtimeRoutes = this._realtimeRoutes
-		next._staticRoutes = this._staticRoutes
-		next._hasRouteTree = this._hasRouteTree
-		next._hasWsRoutes = this._hasWsRoutes
-		return next
+		return next as unknown as Honey<
+			TEnv,
+			TCtx,
+			TRoutes,
+			unknown,
+			TErrorFactory,
+			TDefaultErrors,
+			TBasePath,
+			TTaps,
+			TScopedMw
+		>
 	}
 
 	/**
@@ -1284,68 +1918,13 @@ export class Honey<
 	 * Codegen-time only — never consulted on the request path. See docs/meta-spec.md.
 	 */
 	metaSpec<TSpec extends HoneyMetaSpec<TMeta>>(spec: TSpec): this {
-		if (this._metaSpec !== null) {
+		if (this._graph.metaSpec !== null) {
 			throw new Error("metaSpec() was already declared on this app — declare the whole policy in one call")
 		}
-		this._metaSpec = spec as MetaSpecConfig
+		this._graph.metaSpec = spec as MetaSpecConfig
 		return this
 	}
 
-	/**
-	 * Merge a mounted sub-app's policy into this one.
-	 *
-	 * The parent wins on conflict, so one gateway keeps one answer for its aggregate document —
-	 * with a single exception. A sub entry of `false` wins over anything the parent says, because
-	 * hiding is a safety claim and the strictest claim has to survive composition: a worker that
-	 * declares a field unpublishable must not have the gateway publish it. Wrongly hidden is a
-	 * visible gap; wrongly published is a leak.
-	 *
-	 * Every other disagreement is recorded and reported at codegen. Silently dropping a sub's
-	 * entry is how someone ends up diffing two documents to find out why they differ.
-	 */
-	private _absorbMetaSpec(sub: MetaSpecConfig | null): void {
-		if (!sub) return
-		const own = this._metaSpec
-		if (!own) {
-			this._metaSpec = sub
-			return
-		}
-		const conflicts: MetaSpecMergeConflict[] = [...(own.conflicts ?? []), ...(sub.conflicts ?? [])]
-
-		const mergeMeta = (): Record<string, MetaSpecEntry> => {
-			const merged: Record<string, MetaSpecEntry> = { ...sub.meta, ...own.meta }
-			for (const [key, subEntry] of Object.entries(sub.meta ?? {})) {
-				const ownEntry = own.meta?.[key]
-				if (ownEntry === undefined || ownEntry === subEntry) continue
-				if (subEntry === false && ownEntry !== false) {
-					merged[key] = false
-					conflicts.push({ key, resolution: "hidden", section: "meta" })
-					continue
-				}
-				conflicts.push({ key, resolution: "parent", section: "meta" })
-			}
-			return merged
-		}
-
-		const recordOverlap = (section: "profiles" | "schema", subSide: object, ownSide: object): void => {
-			for (const [key, subEntry] of Object.entries(subSide)) {
-				const ownEntry = (ownSide as Record<string, unknown>)[key]
-				if (ownEntry === undefined || ownEntry === subEntry) continue
-				conflicts.push({ key, resolution: "parent", section })
-			}
-		}
-		recordOverlap("schema", sub.schema ?? {}, own.schema ?? {})
-		recordOverlap("profiles", sub.profiles ?? {}, own.profiles ?? {})
-
-		this._metaSpec = {
-			conflicts,
-			meta: mergeMeta(),
-			profiles: { ...sub.profiles, ...own.profiles },
-			schema: { ...sub.schema, ...own.schema },
-			strict: own.strict ?? sub.strict,
-		}
-	}
-
 	/** Declare tap payload types — auto-extends meta with Partial<T> for meta-driven taps */
 	taps<TNewTaps extends Record<string, unknown>>(): Honey<
 		TEnv,
@@ -1393,139 +1972,164 @@ export class Honey<
 	/* oxlint-disable-next-line typescript/no-explicit-any -- overload impl requires erased types */
 	use(pathOrMw: string | MiddlewareFn<any, any>, maybeMw?: MiddlewareFn<any, any>): any {
 		if (typeof pathOrMw !== "string") {
+			/*
+			 * Chain middleware: a new handle whose routes run `mw`. This handle is unchanged —
+			 * a handle that never registers a route is reported at finalize.
+			 */
 			const mw = pathOrMw as RuntimeMiddleware
-			const newChain = new Honey<TEnv>({
-				chainMiddlewares: [...this._chainMiddlewares, mw],
-				defaultErrorKeys: this._defaultErrorKeys,
-				globalMiddlewares: this._globalMiddlewares,
-				graph: this._graph,
-				scopedMiddlewares: this._scopedMiddlewares,
-			})
-			newChain._basePath = this._basePath
-			newChain._chainMeta = this._chainMeta
-			newChain._contextValues = this._contextValues
-			newChain._defaultBoundaryKey = this._defaultBoundaryKey
-			newChain._errorFactory = this._errorFactory
-			newChain._errorSchema = this._errorSchema
-			newChain._customErrorFormatter = this._customErrorFormatter
-			newChain._customErrorSchema = this._customErrorSchema
-			newChain._errorFormatter = this._errorFormatter
-			newChain._errorI18n = this._errorI18n
-			newChain._logger = this._logger
-			newChain._outputValidation = this._outputValidation
-			newChain._stripPrefix = this._stripPrefix
-			newChain._trailingSlash = this._trailingSlash
-			newChain._wsAdapter = this._wsAdapter
-			newChain._onError = this._onError
-			newChain._onNotFound = this._onNotFound
-			newChain._onMethodNotAllowed = this._onMethodNotAllowed
-			newChain._taps = this._taps
-			newChain._telemetry = this._telemetry
-			newChain._realtimeBus = this._realtimeBus
-			newChain._realtimeRoutes = this._realtimeRoutes
-			newChain._staticRoutes = this._staticRoutes
-			newChain._hasRouteTree = this._hasRouteTree
-			newChain._hasWsRoutes = this._hasWsRoutes
-			return newChain
-		}
-
-		/* scoped path */
-		const normalizedPrefix = normalizeScopePath(pathOrMw)
-		const fullPrefix = mergePath(this._basePath, normalizedPrefix)
+			const node: ChainNode = { mw, parent: this._node, used: false }
+			this._graph.chains.push(node)
+			const next = this._derive([...this._chain, mw])
+			next._node = node
+			return next
+		}
+
+		/* scoped: guards every request path under the prefix, whichever handle registered the route */
+		const prefix = mergePath(this._basePath, normalizePattern(pathOrMw))
 		const mw = maybeMw as RuntimeMiddleware
-		const mwWithErrors = maybeMw as MiddlewareFn<unknown, unknown>
-		const entry: ScopedEntry = {
-			errors: mwWithErrors.errors ? [...mwWithErrors.errors] : undefined,
+		const segs = parsePattern(prefix)
+		this._graph.scoped.push({
+			errors: errorsOf(mw) ? [...(errorsOf(mw) as readonly string[])] : undefined,
+			guard: scopeGuard(segs, mw),
 			mw,
-			prefix: fullPrefix,
-		}
-		this._scopedMiddlewares.push(entry)
-		const newChain = new Honey<TEnv>({
-			chainMiddlewares: this._chainMiddlewares,
-			defaultErrorKeys: this._defaultErrorKeys,
-			globalMiddlewares: this._globalMiddlewares,
-			graph: this._graph,
-			scopedMiddlewares: this._scopedMiddlewares,
+			prefix,
+			segs,
 		})
-		newChain._basePath = this._basePath
-		newChain._chainMeta = this._chainMeta
-		newChain._contextValues = this._contextValues
-		newChain._defaultBoundaryKey = this._defaultBoundaryKey
-		newChain._errorFactory = this._errorFactory
-		newChain._errorSchema = this._errorSchema
-		newChain._customErrorFormatter = this._customErrorFormatter
-		newChain._customErrorSchema = this._customErrorSchema
-		newChain._errorFormatter = this._errorFormatter
-		newChain._errorI18n = this._errorI18n
-		newChain._logger = this._logger
-		newChain._outputValidation = this._outputValidation
-		newChain._stripPrefix = this._stripPrefix
-		newChain._trailingSlash = this._trailingSlash
-		newChain._wsAdapter = this._wsAdapter
-		newChain._onError = this._onError
-		newChain._onNotFound = this._onNotFound
-		newChain._onMethodNotAllowed = this._onMethodNotAllowed
-		newChain._taps = this._taps
-		newChain._telemetry = this._telemetry
-		newChain._realtimeBus = this._realtimeBus
-		newChain._realtimeRoutes = this._realtimeRoutes
-		newChain._staticRoutes = this._staticRoutes
-		newChain._hasRouteTree = this._hasRouteTree
-		newChain._hasWsRoutes = this._hasWsRoutes
-		newChain._applyScopedEntryErrors(entry)
-		newChain._applyScopedEntryMeta(entry)
-		return newChain
+		this._bumpEpoch()
+		return this._derive()
 	}
 
+	/**
+	 * Mount a sub-app: its routes are served under this handle's basePath (and under `prefix`
+	 * when given — `app.route("/v1", sub)` is `app.basePath("/v1").route(sub)`), and this
+	 * handle's chain runs before theirs. The sub's own basePath stays part of each path.
+	 */
 	route<TSubRoutes, TSubMeta, TSubErrorFactory, TSubDefaultErrors extends string, TSubBasePath extends string>(
 		sub: Honey<TEnv, TCtx, TSubRoutes, TSubMeta, TSubErrorFactory, TSubDefaultErrors, TSubBasePath>,
-	): Honey<TEnv, TCtx, TRoutes & TSubRoutes, TMeta, TErrorFactory, TDefaultErrors, TBasePath, TTaps, TScopedMw> {
-		/* skip self-merge: .handler() already inserted into shared _root */
-		if (sub._tree !== this._root) {
-			mergeInto(this._root, sub._tree)
-			this._absorbMetaSpec(sub._metaSpec)
-			if (sub._hasWsRoutes) this._hasWsRoutes = true
-			if (sub._hasRouteTree) this._hasRouteTree = true
-			/* carry sub's scoped mw entries into parent's runtime list (parent scopes run first) */
-			for (const entry of sub._scopedMiddlewares) {
-				this._scopedMiddlewares.push(entry)
+	): Honey<
+		TEnv,
+		TCtx,
+		TRoutes & PrefixRoutes<TBasePath, TSubRoutes>,
+		TMeta,
+		TErrorFactory,
+		TDefaultErrors,
+		TBasePath,
+		TTaps,
+		TScopedMw
+	>
+	route<
+		const TPrefix extends string,
+		TSubRoutes,
+		TSubMeta,
+		TSubErrorFactory,
+		TSubDefaultErrors extends string,
+		TSubBasePath extends string,
+	>(
+		prefix: TPrefix,
+		sub: Honey<TEnv, TCtx, TSubRoutes, TSubMeta, TSubErrorFactory, TSubDefaultErrors, TSubBasePath>,
+	): Honey<
+		TEnv,
+		TCtx,
+		TRoutes & PrefixRoutes<MergePath<TBasePath, TPrefix>, TSubRoutes>,
+		TMeta,
+		TErrorFactory,
+		TDefaultErrors,
+		TBasePath,
+		TTaps,
+		TScopedMw
+	>
+	route(prefixOrSub: unknown, maybeSub?: unknown): unknown {
+		type Sub = Honey<TEnv, TCtx, unknown, unknown, unknown, string, string>
+		if (typeof prefixOrSub === "string") {
+			if (!(maybeSub instanceof Honey)) throw new TypeError("honey: route(prefix, sub) needs the sub-app")
+			this._markUsed()
+			;(this.basePath(prefixOrSub) as unknown as Honey<TEnv, TCtx>)._mount(maybeSub as Sub)
+			return this
+		}
+		return this._mount(prefixOrSub as Sub)
+	}
+
+	private _mount(sub: Honey<TEnv, TCtx, unknown, unknown, unknown, string, string>): this {
+		this._markUsed()
+		/* skip self-merge: .handler() already registered into the shared graph */
+		if (sub._graph !== this._graph) {
+			/*
+			 * Re-register the sub's records under this handle: this handle's chain runs first,
+			 * its context values and chain meta apply under the sub's own. Nothing is shared by
+			 * reference, so routes the sub registers later stay its own, and two parents
+			 * mounting one sub each get their own records. Each record keeps the settings of
+			 * the sub (error factory, defaults, boundary, output validation). Internal routes
+			 * (spec, docs, manifest) never travel.
+			 */
+			sub._markUsed()
+			const subFinal = sub._finalize()
+			const subSettings = sub._graph.settings
+			const mount = <T extends RouteHandler | WSRouteHandler>(r: T): T => {
+				const c = copyRecord(r)
+				c.cm = [...this._chain, ...(r.cm ?? [])]
+				if (this._contextValues) c.cv = { ...this._contextValues, ...r.cv }
+				if (this._chainMeta) c.xm = { ...this._chainMeta, ...r.xm }
+				c.own = r.own ?? subSettings
+				return c
+			}
+			/* the sub's paths land under this handle's basePath, like Hono's `route("/v1", sub)` */
+			const base = this._basePath
+			const at = (pattern: string): string => (base === "/" ? pattern : mergePath(base, pattern))
+			for (const [id, r] of subFinal.byId) {
+				if (r._skip) continue
+				const { method, pattern } = splitRouteId(id)
+				this._addRoute(method, parsePattern(at(pattern)), mount(r))
+			}
+			for (const [id, r] of subFinal.wsById) {
+				const { pattern } = splitRouteId(id)
+				this._addWsRoute(parsePattern(at(pattern)), mount(r))
 			}
-			if (sub._staticRoutes.map !== null) {
-				if (this._staticRoutes.map === null) {
-					this._staticRoutes.map = Object.create(null) as Record<string, RouteHandler>
+			/* merged when codegen reads the policy (see `metaSpecOf`): the parent wins
+			 * conflicts and keeps its resolved strictness, a sub's `false` still hides */
+			const subSource = sub._metaSpecSource
+			this._graph.absorbedMetaSpecs.push({ absorbed: [...subSource.absorbed], declared: subSource.declared })
+			/* the sub's scopes guard the paths it brought — appended after this app's own */
+			const g = this._graph
+			for (const entry of sub._graph.scoped) {
+				if (base === "/") {
+					if (!g.scoped.includes(entry)) g.scoped.push(entry)
+					continue
 				}
-				Object.assign(this._staticRoutes.map, sub._staticRoutes.map)
+				const prefix = at(entry.prefix)
+				if (g.scoped.some((e) => e.mw === entry.mw && e.prefix === prefix)) continue
+				const segs = parsePattern(prefix)
+				g.scoped.push({ errors: entry.errors, guard: scopeGuard(segs, entry.mw), mw: entry.mw, prefix, segs })
 			}
-			for (const [path, cfg] of sub._realtimeRoutes) {
-				if (this._realtimeRoutes.has(path)) {
+			for (const [subPath, cfg] of sub._graph.realtimeRoutes) {
+				const path = at(subPath)
+				if (g.realtimeRoutes.has(path)) {
 					throw new Error(`Duplicate realtime route: ${path}`)
 				}
-				this._realtimeRoutes.set(path, cfg)
+				/* a default namespace is the route's full path, so it follows the mount; a named one is kept */
+				g.realtimeRoutes.set(path, { ...cfg, namespace: cfg.namespaceExplicit ? cfg.namespace : path, path })
 			}
-			if (!this._realtimeBus && sub._realtimeBus) {
-				this._realtimeBus = sub._realtimeBus
+			if (!g.realtimeBus && sub._graph.realtimeBus) {
+				this._setBus(sub._graph.realtimeBus)
 			}
-			if (sub._taps !== null) {
-				if (this._taps === null) this._taps = new Map()
-				for (const [key, fn] of sub._taps) {
-					if (!this._taps.has(key)) this._taps.set(key, fn)
+			if (subSettings.taps !== null) {
+				const s = this._graph.settings
+				if (s.taps === null) s.taps = new Map()
+				for (const [key, fn] of subSettings.taps) {
+					if (!s.taps.has(key)) s.taps.set(key, fn)
 				}
 			}
-			/* walk tree and apply all scoped error keys + contributed meta to matching handlers */
-			this._applyAllScopedErrors()
-			for (const entry of this._scopedMiddlewares) this._applyScopedEntryMeta(entry)
+			this._bumpEpoch()
 		}
-		return this as unknown as Honey<
-			TEnv,
-			TCtx,
-			TRoutes & TSubRoutes,
-			TMeta,
-			TErrorFactory,
-			TDefaultErrors,
-			TBasePath,
-			TTaps,
-			TScopedMw
-		>
+		return this
+	}
+
+	private _setBus(bus: RealtimeBus): RealtimeBus {
+		const g = this._graph
+		g.realtimeBus = bus
+		g.realtimeCtx = requireFeature("realtime", "app.realtime()").createRealtimePublisher(bus, () =>
+			[...g.realtimeRoutes.values()].map((cfg) => cfg.namespace),
+		)
+		return bus
 	}
 
 	private _registerRoute<TPath extends string, TMethod extends HttpMethod | "ALL">(
@@ -1552,12 +2156,8 @@ export class Honey<
 		TScopedMw
 	> {
 		const fullPath = mergePath(this._basePath, path)
-		const errorKeys = new Set(this._defaultErrorKeys)
-		for (const entry of this._scopedMiddlewares) {
-			if (entry.errors && scopeMatches(entry.prefix, fullPath)) {
-				for (const k of entry.errors) errorKeys.add(k)
-			}
-		}
+		const pending: PendingRoute = { id: `${[method, ...(extraMethods ?? [])].join(",")} ${fullPath}` }
+		this._graph.pending.add(pending)
 		return new RouteBuilder<
 			TEnv,
 			TCtx & ApplyScoped<TScopedMw, MergePath<TBasePath, TPath>>,
@@ -1577,20 +2177,17 @@ export class Honey<
 			TTaps,
 			TScopedMw
 		>({
-			boundaryErrorKey: this._defaultBoundaryKey,
-			errorKeys,
+			boundaryErrorKey: null,
+			errorKeys: new Set(),
 			extraMethods: extraMethods ?? null,
-			handlerMap: this._handlerMap,
 			inputSchemas: null,
 			meta: this._chainMeta ? { ...this._chainMeta } : null,
 			method,
 			middlewares: [],
-			mwMeta: this._contributedMetaFor(fullPath),
 			outputSchemas: null,
 			parent: this,
-			parentMiddlewares: this._chainMiddlewares,
 			path: fullPath,
-			root: this._root,
+			pending,
 		}) as unknown as BuilderChain<
 			TEnv,
 			TCtx & ApplyScoped<TScopedMw, MergePath<TBasePath, TPath>>,
@@ -1612,6 +2209,27 @@ export class Honey<
 		>
 	}
 
+	/** @internal — set (or clear, with null) one app-wide middleware; used by `serve()` */
+	_setGlobal(key: string, mw: RuntimeMiddleware | null): void {
+		if (mw === null) {
+			if (!this._graph.global.delete(key)) return
+		} else {
+			this._graph.global.set(key, mw)
+		}
+		this._bumpEpoch()
+	}
+
+	/** @internal — what a route registered through this handle captures */
+	_view(): { chain: RuntimeMiddleware[]; cv: Record<string, unknown> | null; own: AppSettings<unknown> } {
+		return { chain: this._chain, cv: this._contextValues, own: this._graph.settings }
+	}
+
+	/** @internal — a builder got its handler (or was abandoned on purpose) */
+	_settle(pending: PendingRoute): void {
+		this._graph.pending.delete(pending)
+		this._markUsed()
+	}
+
 	on<const TPath extends string, const TMethods extends readonly [HttpMethod | "ALL", ...(HttpMethod | "ALL")[]]>(
 		methods: TMethods,
 		path: TPath,
@@ -1676,6 +2294,9 @@ export class Honey<
 		never,
 		Honey<TEnv, TCtx, TRoutes, TMeta, TErrorFactory, TDefaultErrors, TBasePath, TTaps, TScopedMw>
 	> {
+		const fullPath = mergePath(this._basePath, path)
+		const pending: PendingRoute = { id: `WS ${fullPath}` }
+		this._graph.pending.add(pending)
 		return new WSRouteBuilder<
 			TEnv,
 			TCtx & ApplyScoped<TScopedMw, MergePath<TBasePath, TPath>>,
@@ -1683,54 +2304,47 @@ export class Honey<
 			never,
 			Honey<TEnv, TCtx, TRoutes, TMeta, TErrorFactory, TDefaultErrors, TBasePath, TTaps, TScopedMw>
 		>({
-			boundaryErrorKey: this._defaultBoundaryKey,
 			errorKeys: new Set(),
 			inputSchemas: null,
-			meta: null,
+			meta: this._chainMeta ? { ...this._chainMeta } : null,
 			middlewares: [],
-			mwMeta: this._contributedMetaFor(mergePath(this._basePath, path)),
+			origins: null,
 			parent: this,
-			parentMiddlewares: this._chainMiddlewares,
-			path: mergePath(this._basePath, path),
-			root: this._root,
+			path: fullPath,
+			pending,
 		})
 	}
 
-	realtime(path: string, opts: RealtimeRouteOpts): this {
-		const fullPath = mergePath(this._basePath, path) || "/"
-
-		if (!this._realtimeBus) {
-			this._realtimeBus = createBus()
-		}
-
-		if (this._realtimeRoutes.has(fullPath)) {
+	realtime<const TPath extends string>(
+		path: TPath,
+		opts: RealtimeRouteOpts<TCtx & ApplyScoped<TScopedMw, MergePath<TBasePath, TPath>>>,
+	): this {
+		const fullPath = mergePath(this._basePath, path)
+		const g = this._graph
+		const rt = requireFeature("realtime", "app.realtime()")
+		const config = rt.resolveRealtimeConfig(fullPath, opts)
+		if (g.realtimeRoutes.has(fullPath)) {
 			throw new Error(`Duplicate realtime route: ${fullPath}`)
 		}
-
-		this._realtimeRoutes.set(fullPath, {
-			handler: opts.handler,
-			middlewares: opts.use,
-			reconnectBuffer: opts.reconnectBuffer,
-		})
-
-		const mw: RuntimeMiddleware[] = []
-		if (opts.use) {
-			for (const fn of opts.use) {
-				mw.push(fn as RuntimeMiddleware)
-			}
-		}
-
-		insertWsRoute(this._root, fullPath, {
-			bek: this._defaultBoundaryKey,
+		if (!g.realtimeBus) this._setBus(rt.createBus())
+		g.realtimeRoutes.set(fullPath, config)
+		this._markUsed()
+		this._addWsRoute(parsePattern(fullPath), {
+			bek: null,
+			cm: [...this._chain],
+			cv: this._contextValues,
+			dk: new Set(),
 			ek: new Set(),
 			fn: Object.create(null),
 			iv: null,
 			mt: null,
-			mw: [...this._chainMiddlewares, ...mw],
+			mw: [],
+			own: g.settings,
+			rb: null,
+			rm: (opts.use ?? []).map((fn) => fn as RuntimeMiddleware),
 			rp: fullPath,
+			xm: this._chainMeta ? { ...this._chainMeta } : null,
 		})
-
-		this._hasWsRoutes = true
 		return this
 	}
 
@@ -1744,23 +2358,44 @@ export class Honey<
 		env: TEnv,
 		executionCtx?: { waitUntil?: (p: Promise<unknown>) => void },
 	): Response | Promise<Response> {
-		if (this._wsAdapter === null && !this._hasWsRoutes) {
-			return this._doFetch(request, env, executionCtx)
+		if (!this._graph.served.has(this._chain)) {
+			this._markUsed()
+			this._graph.served.add(this._chain)
+			this._bumpEpoch()
+		}
+		const wsAdapter = this._graph.settings.wsAdapter
+		const path = normalizePath(pathOfUrl(request.url), this._graph.settings.encodedSlashes)
+		if (path === null) return this._badRequestTarget()
+		/* Deno and Bun before 1.4 build request.url by concatenating Host and the target, so a
+		 * `Host: x/admin?` would choose the routed path. `serve()` checks Host on Deno; this covers
+		 * `Deno.serve(app.fetch)`, which passes its serve info as env, and every Bun entry point on
+		 * an affected version. Node's adapter checks it; Bun 1.4+ routes on the target. */
+		if ((BUN_URL_FROM_HOST || isDenoServeInfo(env)) && !hasValidHost(request)) return this._badRequestTarget()
+		/* an adapter alone (serve() always installs one) does not need the websocket path */
+		if (!this._graph.hasWs) {
+			return this._doFetch(request, env, executionCtx, path)
 		}
 		const isWsUpgrade = request.headers.get("upgrade")?.toLowerCase() === "websocket"
-		const headerSnap = isWsUpgrade ? new Headers(request.headers) : undefined
-		const path = this.pathFromRequest(request)
 		const canPreUpgrade =
 			isWsUpgrade &&
-			this._wsAdapter?.preUpgrade !== undefined &&
+			wsAdapter?.preUpgrade !== undefined &&
 			!this.trailingSlashRedirects(path) &&
-			matchWsRoute(this._root, this.pathAfterPrefix(path)) !== null
-		const pre = canPreUpgrade ? this._wsAdapter?.preUpgrade?.(request) : undefined
+			this._matchWs(this._finalize(), this.pathAfterPrefix(path)) !== null
+		/* Deno closes the Request in preUpgrade: snapshot the headers the chain will read first */
+		const headerSnap = canPreUpgrade ? new Headers(request.headers) : undefined
+		let pre: ReturnType<NonNullable<WSAdapter["preUpgrade"]>>
+		try {
+			pre = canPreUpgrade ? wsAdapter?.preUpgrade?.(request) : undefined
+		} catch (err) {
+			/* the runtime refused the handshake: answer through the normal path, which fails the upgrade */
+			this._graph.settings.logger?.warn?.({ err }, "websocket preUpgrade failed")
+			pre = undefined
+		}
 		/* After Deno.upgradeWebSocket the Request is closed. A sync throw here
 		 * used to be boxed by async _doFetch; keep 101 returning either way. */
 		let work: Response | Promise<Response>
 		try {
-			work = this._doFetch(request, env, executionCtx, isWsUpgrade === true, headerSnap)
+			work = this._doFetch(request, env, executionCtx, path, isWsUpgrade === true, headerSnap)
 		} catch (err) {
 			work = Promise.reject(err)
 		}
@@ -1790,28 +2425,25 @@ export class Honey<
 		return pre.response
 	}
 
-	private pathFromRequest(request: Request): string {
-		const rawUrl = request.url
-		const protoEnd = rawUrl.indexOf("//")
-		const pathStart = protoEnd === -1 ? 0 : rawUrl.indexOf("/", protoEnd + 2)
-		const searchOrHash = pathStart === -1 ? -1 : findSearchOrHash(rawUrl, pathStart)
-		if (pathStart === -1) return "/"
-		if (searchOrHash === -1) return rawUrl.substring(pathStart)
-		return rawUrl.substring(pathStart, searchOrHash)
+	/** @internal 400 for a request path the normalization policy rejects (see `normalizePath`), or an invalid `Host`. */
+	_badRequestTarget(): Response {
+		return this._toErrorResponse(this._createError(EK.bad_request, SK.bad_request))
 	}
 
 	private trailingSlashRedirects(path: string): boolean {
 		if (path.length <= 1) return false
-		if (this._trailingSlash === "strip" && path.endsWith("/")) return true
-		if (this._trailingSlash === "enforce" && !path.endsWith("/")) return true
+		const mode = this._graph.settings.trailingSlash
+		if (mode === "strip" && path.endsWith("/")) return true
+		if (mode === "enforce" && !path.endsWith("/")) return true
 		return false
 	}
 
 	private pathAfterPrefix(path: string): string {
-		if (this._stripPrefix === null) return path
-		if (path === this._stripPrefix) return "/"
-		if (path.startsWith(this._stripPrefix) && path.charCodeAt(this._stripPrefix.length) === 47) {
-			return path.slice(this._stripPrefix.length)
+		const prefix = this._graph.settings.stripPrefix
+		if (prefix === null) return path
+		if (path === prefix) return "/"
+		if (path.startsWith(prefix) && path.charCodeAt(prefix.length) === 47) {
+			return path.slice(prefix.length)
 		}
 		return path
 	}
@@ -1819,25 +2451,15 @@ export class Honey<
 	private _doFetch(
 		request: Request,
 		env: TEnv,
-		executionCtx?: { waitUntil?: (p: Promise<unknown>) => void },
+		executionCtx: { waitUntil?: (p: Promise<unknown>) => void } | undefined,
+		fullPath: string,
 		knownWsUpgrade = false,
 		headerSnap?: Headers,
 	): Response | Promise<Response> {
 		const startTime = performance.now()
-
-		/* fast path extraction — avoids expensive new URL() allocation */
+		const final = this._finalize()
+		const s = this._graph.settings
 		const rawUrl = request.url
-		const protoEnd = rawUrl.indexOf("//")
-		const pathStart = protoEnd === -1 ? 0 : rawUrl.indexOf("/", protoEnd + 2)
-		const searchOrHash = pathStart === -1 ? -1 : findSearchOrHash(rawUrl, pathStart)
-		let path: string
-		if (pathStart === -1) {
-			path = "/"
-		} else if (searchOrHash === -1) {
-			path = rawUrl.substring(pathStart)
-		} else {
-			path = rawUrl.substring(pathStart, searchOrHash)
-		}
 
 		/* lazily create URL only when actually needed (search params, redirects) */
 		let _url: URL | undefined
@@ -1846,296 +2468,176 @@ export class Honey<
 			return _url
 		}
 
-		const log = this._logger ?? undefined
+		const log = s.logger ?? undefined
+		const method = request.method.toUpperCase() as HttpMethod
 		const fc: FetchCtx<TEnv> = {
+			allowed: null,
 			env,
 			executionCtx,
+			headerSnap,
 			log,
+			method,
+			path: fullPath,
+			plan: null,
 			request,
 			startTime,
+			trust: s.trust,
 			url: getUrl,
+			ws: null,
 			wsUpgrade: knownWsUpgrade,
-			headerSnap,
 		}
 
-		if (this._telemetry !== null) {
-			safeFire(() => this._telemetry?.onRequest?.({ env, req: request }), log)
-		}
+		if (s.telemetry === null) return this._route(fc, final, fullPath, rawUrl, knownWsUpgrade)
+		safeFire(() => s.telemetry?.onRequest?.({ env, req: request }), log)
+		/* every exit after onRequest — redirects, 426, upgrades, misses, preflights, handlers —
+		 * fires onResponse exactly once, here */
+		return this._withOnResponse(fc, this._route(fc, final, fullPath, rawUrl, knownWsUpgrade))
+	}
 
-		/* trailing slash handling */
-		if (path.length > 1) {
-			if (this._trailingSlash === "strip" && path.endsWith("/")) {
-				const redirectUrl = getUrl()
-				redirectUrl.pathname = path.slice(0, -1)
-				return new Response(null, {
-					headers: { location: redirectUrl.toString() },
-					status: 308,
-				})
-			}
-			if (this._trailingSlash === "enforce" && !path.endsWith("/")) {
-				const redirectUrl = getUrl()
-				redirectUrl.pathname = `${path}/`
-				return new Response(null, {
-					headers: { location: redirectUrl.toString() },
-					status: 308,
-				})
-			}
+	private _route(
+		fc: FetchCtx<TEnv>,
+		final: FinalTable,
+		fullPath: string,
+		rawUrl: string,
+		knownWsUpgrade: boolean,
+	): Response | Promise<Response> {
+		const s = this._graph.settings
+		const { method, request } = fc
+
+		/* trailing slash handling — a relative Location: the scheme, host and port the client
+		 * used are the ones it keeps, whatever proxy terminated TLS in front of the app */
+		if (this.trailingSlashRedirects(fullPath)) {
+			const target = s.trailingSlash === "strip" ? fullPath.slice(0, -1) : `${fullPath}/`
+			return new Response(null, {
+				headers: { location: target + searchOfUrl(rawUrl) },
+				status: 308,
+			})
 		}
 
 		/* prefix stripping — must run AFTER trailing slash so redirects preserve the full prefixed URL */
-		if (this._stripPrefix !== null) {
-			if (path === this._stripPrefix) {
-				path = "/"
-			} else if (path.startsWith(this._stripPrefix) && path.charCodeAt(this._stripPrefix.length) === 47) {
-				path = path.slice(this._stripPrefix.length)
-			}
-		}
+		const path = this.pathAfterPrefix(fullPath)
+		fc.path = path
+		const root = this._graph.root
 
 		/* WebSocket route check — do not re-read headers after Deno.upgradeWebSocket */
 		const isWsUpgrade = knownWsUpgrade || requestIsWsUpgrade(request)
 		if (isWsUpgrade) {
-			const wsMatch = matchWsRoute(this._root, path)
+			const wsMatch = this._matchWs(final, path)
 			if (wsMatch !== null) {
 				return this._handleWs(fc, wsMatch)
 			}
-		} else if (this._realtimeRoutes.size > 0) {
-			/* Non-upgrade request hitting a realtime-only path → 426 Upgrade Required */
-			const wsMatch = matchWsRoute(this._root, path)
-			if (wsMatch !== null && this._realtimeRoutes.has(wsMatch.handler.rp)) {
-				return new Response(null, { headers: { upgrade: "websocket" }, status: 426 })
-			}
 		}
 
-		const method = request.method.toUpperCase() as HttpMethod
-
-		/* fn:null fallthrough — tree match sets meta/iv, catch-all dispatches */
-		let fnNullMeta: Record<string, unknown> | null = null
-		let fnNullParams: Record<string, string> | null = null
-		let fnNullIv: InputSchemasDef | null = null
-		let fnNullHit = false
-
-		/* Tier 2: O(1) static route lookup — checks both precompiled and runtime maps */
-		const smap = this._staticRoutes.map ?? this._handlerMap
-		if (smap !== null) {
-			const key = `${method} ${path}`
-			const staticHandler = smap[key]
-			if (staticHandler) {
-				if (staticHandler.fn === null) {
-					fnNullMeta = staticHandler.mt
-					fnNullParams = EMPTY_PARAMS
-					fnNullIv = staticHandler.iv ?? null
-					fnNullHit = true
-				} else {
-					return this._handleMatched(fc, method, path, staticHandler, EMPTY_PARAMS)
-				}
-			}
-			/* HEAD falls back to GET */
-			if (!fnNullHit && method === "HEAD") {
-				const getHandler = smap[`GET ${path}`]
-				if (getHandler) {
-					if (getHandler.fn === null) {
-						fnNullMeta = getHandler.mt
-						fnNullParams = EMPTY_PARAMS
-						fnNullIv = getHandler.iv ?? null
-						fnNullHit = true
-					} else {
-						return this._handleMatched(fc, method, path, getHandler, EMPTY_PARAMS)
-					}
-				}
-			}
+		/* O(1) static route lookup — patterns without params or wildcards only */
+		const staticHit =
+			final.statics[`${method} ${path}`] ?? (method === "HEAD" ? final.statics[`GET ${path}`] : undefined)
+		if (staticHit !== undefined) {
+			return this._dispatchRecord(fc, staticHit, EMPTY_PARAMS)
 		}
 
-		if (!fnNullHit) {
-			const result = matchRoute(this._root, method, path)
-
-			if (result?.matched) {
-				/*
-				 * routeTree loaded → wildcard matches for unknown paths must 404.
-				 * Only fn:null fallthroughs (known routes) should reach the catch-all.
-				 * Detect wildcard: handler has no mt and fn is NOT null (builder-registered catch-all).
-				 */
-				const isWildcardCatchAll =
-					this._hasRouteTree &&
-					this._root.w !== null &&
-					result.handler.fn !== null &&
-					(this._root.w.m[method] === result.handler || this._root.w.m["ALL"] === result.handler)
-
-				if (isWildcardCatchAll) {
-					/* path not in routeTree — 404 */
-					return this._handle404(fc, method, path)
-				}
-
-				if (result.handler.fn === null) {
-					fnNullMeta = result.handler.mt
-					fnNullParams = result.params
-					fnNullIv = result.handler.iv ?? null
-					fnNullHit = true
-				} else {
-					return this._handleMatched(fc, method, path, result.handler, result.params)
-				}
-			}
-
-			if (!fnNullHit) {
-				if (result === null) {
-					if (!isWsUpgrade) {
-						const wsMatch = matchWsRoute(this._root, path)
-						if (wsMatch !== null) {
-							return new Response("Upgrade Required", {
-								headers: { connection: "Upgrade", upgrade: "websocket" },
-								status: 426,
-							})
-						}
+		const result = matchRoute(root, method, path)
+		if (result === null) {
+			/* no HTTP route: a websocket or realtime route on this path asks for an upgrade */
+			if (!isWsUpgrade && this._graph.hasWs) {
+				const wsMatch = this._matchWs(final, path)
+				if (wsMatch !== null) {
+					if (this._graph.realtimeRoutes.has(wsMatch.handler.rp)) {
+						return new Response(null, { headers: { upgrade: "websocket" }, status: 426 })
 					}
-					return this._handle404(fc, method, path)
+					return new Response("Upgrade Required", {
+						headers: { connection: "Upgrade", upgrade: "websocket" },
+						status: 426,
+					})
 				}
-
-				if (!result.matched) {
-					if (
-						method === "OPTIONS" &&
-						fc.request.headers.has("access-control-request-method") &&
-						result.allowed.length > 0
-					) {
-						const fallback = this._preflightFallbackMethod(result.allowed)
-						const retry = matchRoute(this._root, fallback, path)
-						if (retry?.matched && retry.handler.fn !== null) {
-							return this._handleCorsPreflight(fc, path, retry.handler, retry.params, result.allowed)
-						}
+			}
+			return this._handleMiss(fc, null)
+		}
+		if (!result.matched) {
+			if (method === "OPTIONS") {
+				const requested = request.headers.get("access-control-request-method")
+				if (requested) {
+					/* a preflight asks about one method: run that route's own chain */
+					const hit = matchRoute(root, requested.trim().toUpperCase(), path)
+					const plan = hit?.matched ? final.plans.get(hit.id) : undefined
+					if (hit?.matched && plan !== undefined && plan.r.fn !== NOT_SERVED) {
+						return this._handlePreflight(fc, plan, hit.params, result.allowed)
 					}
-					return this._handle405(fc, method, path, result.allowed)
 				}
 			}
+			return this._handleMiss(fc, result.allowed)
 		}
+		const plan = final.plans.get(result.id)
+		if (plan === undefined) return this._handleMiss(fc, null)
+		return this._dispatchRecord(fc, plan, result.params)
+	}
 
-		/* fn:null hit — find catch-all/wildcard to dispatch with stashed meta */
-		const wildcardResult = matchRoute(this._root, method, "/*")
-		if (wildcardResult?.matched && wildcardResult.handler.fn !== null) {
-			/* 415 from matched iv before middleware that waits on the body */
-			if (fnNullIv !== null) {
-				try {
-					assertRequestContentType(fnNullIv, fc.request)
-				} catch (thrown) {
-					return this._toErrorResponse(thrown)
-				}
+	private _matchWs(
+		final: FinalTable,
+		path: string,
+	): { handler: WSRouteHandler; params: Record<string, string> } | null {
+		const hit = matchWsRoute(this._graph.root, path)
+		if (hit === null) return null
+		const handler = final.wsById.get(hit.id)
+		return handler === undefined ? null : { handler, params: hit.params }
+	}
+
+	private _dispatchRecord(
+		fc: FetchCtx<TEnv>,
+		plan: Plan,
+		params: Record<string, string>,
+	): Response | Promise<Response> {
+		const record = plan.r as RouteHandler
+		if (record.fn === NOT_SERVED) return this._handleMiss(fc, null)
+		/* a delegated route keeps its own input schemas for docs and the 415 check; the body
+		 * itself belongs to whatever the catch-all forwards it to */
+		if (record.dl === true && record.iv) {
+			try {
+				assertRequestContentType(record.iv, fc.request)
+			} catch (thrown) {
+				return this._toErrorResponse(thrown)
 			}
-			return this._handleMatched(fc, method, path, wildcardResult.handler, fnNullParams ?? EMPTY_PARAMS, fnNullMeta)
 		}
-
-		return this._handle404(fc, method, path)
+		return this._handleMatched(fc, plan, params)
 	}
 
 	private _makeErrorCtx(fc: FetchCtx<TEnv>, allowed?: string[]) {
+		const s = this._s
 		return {
 			env: fc.env,
-			jsonFromError: (err: HoneyError) => createErrorResponse(err, this._errorFormatter, this._customErrorFormatter),
+			jsonFromError: (err: HoneyError) => createErrorResponse(err, s.errorFormatter, s.customErrorFormatter),
 			req: fc.request,
 			...(allowed ? { allowed } : {}),
 		}
 	}
 
-	private async _handleWs(
-		fc: FetchCtx<TEnv>,
-		wsMatch: { handler: WSRouteHandler; params: Record<string, string> },
-	): Promise<Response> {
-		/* Dispatch to realtime handler if this path is registered as a realtime route */
-		const realtimeConfig = this._realtimeRoutes.get(wsMatch.handler.rp)
-		if (realtimeConfig) {
-			return this._handleRealtime(fc, wsMatch, realtimeConfig)
-		}
-
-		const isUpgrade = fc.wsUpgrade === true || requestIsWsUpgrade(fc.request)
-		if (!isUpgrade) {
-			return new Response(null, {
-				headers: { upgrade: "websocket" },
-				status: 426,
-			})
-		}
-
-		const wsAdapter = this._wsAdapter
-		if (!wsAdapter) {
-			fc.log?.warn?.("WebSocket adapter not configured — call .wsAdapter()")
-			return createErrorResponse(
-				this._createError(EK.internal_server_error, SK.internal_server_error),
-				this._errorFormatter,
-				this._customErrorFormatter,
-			)
-		}
-
-		const wsCtx = new HoneyContext({
+	/** A request context for `plan`: route data, context values, `ctx.errors`, `ctx.realtime`. */
+	private _newCtx(fc: FetchCtx<TEnv>, plan: Plan, params: Record<string, string>, req?: Request): HoneyContext<TEnv> {
+		fc.plan = plan
+		const r = plan.r
+		const ctx = new HoneyContext<TEnv>({
 			env: fc.env,
 			executionCtx: fc.executionCtx,
-			params: wsMatch.params,
-			req: ctxRequest(fc),
+			meta: r.mt ?? undefined,
+			params,
+			path: fc.path,
+			req: req ?? fc.request,
+			routePattern: r.rp ?? "",
 			urlFn: fc.url,
 		})
-		if (this._contextValues) Object.assign(wsCtx, this._contextValues)
-
-		/*
-		 * WS ordering: [global → scoped → chain+handler-route-specific]
-		 * WS bakes chain mw into handler.mw at registration, so scoped runs before chain.
-		 * This is an unavoidable inconsistency vs HTTP (where chain runs before scoped).
-		 */
-		const scopedForPath = this._filterScopedForPath(wsMatch.handler.rp)
-		const allWsMw: RuntimeMiddleware[] = [...this._globalMiddlewares, ...scopedForPath, ...wsMatch.handler.mw]
-
-		try {
-			return await executeChain(allWsMw, wsCtx, async (finalCtx) => {
-				const userHandler = wsMatch.handler.fn
-				let messageQueue: Promise<void> = Promise.resolve()
-
-				const onOpenFn = userHandler.onOpen
-				const onMsgFn = userHandler.onMessage
-				const onCloseFn = userHandler.onClose
-				const onErrorFn = userHandler.onError
-				const onReconnectFn = userHandler.onReconnect
-				const reconnectToken = fc.url().searchParams.get("reconnect_token")
-
-				const wrappedHandler: WSHandler<unknown> = {}
-
-				if (reconnectToken && onReconnectFn) {
-					wrappedHandler.onOpen = (_ctx, ws) => {
-						onReconnectFn(finalCtx, ws, reconnectToken)
-					}
-				} else if (onOpenFn) {
-					wrappedHandler.onOpen = (_ctx, ws) => {
-						onOpenFn(finalCtx, ws)
-					}
-				}
-
-				if (onMsgFn) {
-					wrappedHandler.onMessage = (_ctx, ws, data) => {
-						messageQueue = messageQueue
-							.then(() => onMsgFn(finalCtx, ws, data))
-							.catch((err: unknown) => {
-								onErrorFn?.(finalCtx, ws, err)
-							})
-					}
-				}
-
-				if (onCloseFn) {
-					wrappedHandler.onClose = (_ctx, ws, code, reason) => {
-						onCloseFn(finalCtx, ws, code, reason)
-					}
-				}
-
-				if (onErrorFn) {
-					wrappedHandler.onError = (_ctx, ws, error) => {
-						onErrorFn(finalCtx, ws, error)
-					}
-				}
-
-				const upgradeResult = await wsAdapter.upgrade(fc.request, fc.env, wrappedHandler)
-				return upgradeResult.response
-			})
-		} catch (thrown) {
-			return this._toErrorResponse(thrown)
-		}
+		if (plan.cv !== null) Object.assign(ctx, plan.cv)
+		const rt = this._graph.realtimeCtx
+		if (rt !== null) (ctx as { realtime: unknown }).realtime = rt
+		if (r.ef) ctx._setErrors(r.ef)
+		ctx._rq = fc
+		return ctx
 	}
 
-	private async _handleRealtime(
+	private _handleWs(
 		fc: FetchCtx<TEnv>,
 		wsMatch: { handler: WSRouteHandler; params: Record<string, string> },
-		config: { handler: RealtimeRouteOpts["handler"]; middlewares?: RealtimeRouteOpts["use"]; reconnectBuffer?: number },
-	): Promise<Response> {
+	): Response | Promise<Response> {
+		const plan = this._finalize().wsPlans.get(wsMatch.handler.id as RouteId)
+		if (plan === undefined) return this._handleMiss(fc, null)
 		const isUpgrade = fc.wsUpgrade === true || requestIsWsUpgrade(fc.request)
 		if (!isUpgrade) {
 			return new Response(null, {
@@ -2143,485 +2645,172 @@ export class Honey<
 				status: 426,
 			})
 		}
-
-		const wsAdapter = this._wsAdapter
-		if (!wsAdapter) {
+		if (!this._graph.settings.wsAdapter) {
 			fc.log?.warn?.("WebSocket adapter not configured — call .wsAdapter()")
-			return createErrorResponse(
-				this._createError(EK.internal_server_error, SK.internal_server_error),
-				this._errorFormatter,
-				this._customErrorFormatter,
-			)
-		}
-
-		/* Lazily create bus if not yet initialized (happens when realtime() was called on a child chain) */
-		if (!this._realtimeBus) {
-			this._realtimeBus = createBus()
-		}
-		const bus = this._realtimeBus
-
-		const ctx = new HoneyContext({
-			env: fc.env,
-			executionCtx: fc.executionCtx,
-			params: wsMatch.params,
-			req: ctxRequest(fc),
-			urlFn: fc.url,
+			return this._toErrorResponse(this._createError(EK.internal_server_error, SK.internal_server_error))
+		}
+		fc.ws = wsMatch
+		const ctx = this._newCtx(fc, plan, wsMatch.params, ctxRequest(fc))
+		return plan.run(ctx)
+	}
+
+	/** Reject a cross-origin upgrade the route's origin policy does not allow (403). */
+	/** The websocket session runtime; a cross-origin upgrade the route does not allow is a 403. */
+	private async _wsSession(finalCtx: HoneyContext<TEnv>, policy: WSOriginPolicy | null) {
+		const ws = await loadFeature("ws", "a websocket route")
+		const headers = finalCtx.req.headers
+		const origin = headers.get("origin")
+		if (origin === null || policy === "*") return ws
+		const credentialed = headers.has("cookie") || headers.has("authorization")
+		if (!ws.originAllowed(policy, origin, clientInfo(finalCtx as unknown as HoneyContext).host, credentialed)) {
+			throw this._createError(EK.forbidden, SK.forbidden)
+		}
+		return ws
+	}
+
+	private async _wsUpgrade(finalCtx: HoneyContext<TEnv>): Promise<Response> {
+		const fc = finalCtx._rq as FetchCtx<TEnv>
+		const wsMatch = fc.ws as { handler: WSRouteHandler; params: Record<string, string> }
+		const ws = await this._wsSession(finalCtx, wsMatch.handler.og ?? null)
+		const wsAdapter = this._graph.settings.wsAdapter as WSAdapter
+		const handler = ws.createWsSession({
+			callbacks: wsMatch.handler.fn,
+			ctx: finalCtx,
+			log: (this._graph.settings.logger ?? null) as InvokeLogger | null,
+			reconnectToken: fc.url().searchParams.get("reconnect_token"),
+			route: wsMatch.handler.rp,
 		})
-		if (this._contextValues) Object.assign(ctx, this._contextValues)
-		Object.assign(ctx, {
-			realtime: { publish: (topic: string, data: unknown) => bus.publish(topic, data) },
-		})
-
-		const scopedForPath = this._filterScopedForPath(wsMatch.handler.rp)
-		const allMw: RuntimeMiddleware[] = [...this._globalMiddlewares, ...scopedForPath, ...wsMatch.handler.mw]
-
-		try {
-			return await executeChain(allMw, ctx, async (finalCtx) => {
-				const connId = crypto.randomUUID()
-
-				let socket: WSContext<unknown> | null = null
-				let conn: ReturnType<typeof createConnContext> | null = null
-
-				/*
-				 * initConn creates the ConnContext and calls the user handler.
-				 * Called from onOpen (for Bun where socket arrives later)
-				 * or inline after upgrade (for Node/CF where socket is immediate).
-				 */
-				const initConn = (ws: WSContext<unknown>) => {
-					socket = ws
-					conn = createConnContext({
-						bus,
-						closeFn: (reason) => {
-							if (socket) socket.close(1000, reason)
-						},
-						id: connId,
-						sendFn: (payload) => {
-							if (socket)
-								socket.send(typeof payload === "object" && payload !== null ? JSON.stringify(payload) : String(payload))
-						},
-						transport: "ws",
-						userId: null,
-					})
-
-					bus.onMessage(connId, (data) => {
-						if (socket) {
-							socket.send(typeof data === "object" && data !== null ? JSON.stringify(data) : String(data))
-						}
-					})
-
-					config.handler(finalCtx, conn)
-				}
-
-				const wrappedHandler: WSHandler<unknown> = {
-					onClose: (_ctx, _ws, _code, reason) => {
-						if (!conn) return
-						const handlers = conn._handlers
-						if (handlers.close) {
-							handlers.close(reason || "normal")
-						}
-						bus.unsubscribeAll(connId)
-						bus.removeHandler(connId)
-					},
-					onMessage: (_ctx, _ws, data) => {
-						if (!conn) return
-						const handlers = conn._handlers
-						if (handlers.message && typeof data === "string") {
-							try {
-								const parsed: unknown = JSON.parse(data)
-								if (isMsgFrame(parsed)) {
-									handlers.message(parsed.data)
-								}
-							} catch {
-								/* ignore malformed frames */
-							}
-						}
-					},
-					onOpen: (_ctx, ws) => {
-						if (!socket) initConn(ws)
-					},
-				}
-
-				const upgradeResult = await wsAdapter.upgrade(fc.request, fc.env, wrappedHandler)
-
-				/* Node/CF adapters return the socket from upgrade(); Bun returns undefined (socket comes via onOpen).
-				 * Deno pre-upgrade may still be CONNECTING — wait for onOpen so the first send is not dropped. */
-				if (upgradeResult.socket && !socket && upgradeResult.socket.readyState === 1) {
-					initConn(upgradeResult.socket)
-				}
+		const upgradeResult = await wsAdapter.upgrade(fc.request, fc.env, handler)
+		return upgradeResult.response
+	}
+
+	/** Terminal of a realtime route's chain: identify, upgrade, and attach the connection to the bus. */
+	private async _realtimeUpgrade(finalCtx: HoneyContext<TEnv>, config: RealtimeConfig): Promise<Response> {
+		const fc = finalCtx._rq as FetchCtx<TEnv>
+		await this._wsSession(finalCtx, config.allowedOrigins)
+		const wsAdapter = this._graph.settings.wsAdapter as WSAdapter
+		const rt = requireFeature("realtime", "app.realtime()")
+		const bus = this._graph.realtimeBus ?? this._setBus(rt.createBus())
+		/* a throwing identify rejects the upgrade through the chain's error boundary */
+		const userId = config.identify === null ? null : ((await config.identify(finalCtx)) ?? null)
+		const session = rt.createRealtimeSession({ bus, config, ctx: finalCtx, log: fc.log, userId })
+		const upgradeResult = await wsAdapter.upgrade(fc.request, fc.env, session.handler)
+		/* Node/CF return an open socket from upgrade(); Bun and Deno deliver it through onOpen */
+		if (upgradeResult.socket && upgradeResult.socket.readyState === 1) session.attach(upgradeResult.socket)
+		return upgradeResult.response
+	}
 
-				return upgradeResult.response
-			})
-		} catch (thrown) {
-			return this._toErrorResponse(thrown)
+	/**
+	 * 404 (`allowed === null`) and 405: one pipeline with a synthetic record — full context,
+	 * the app-wide middleware and the scopes covering the path run once, telemetry fires once.
+	 */
+	private _handleMiss(fc: FetchCtx<TEnv>, allowed: string[] | null): Response | Promise<Response> {
+		const s = this._graph.settings
+		const { method, path, request } = fc
+		if (allowed === null) {
+			safeFire(() => s.telemetry?.onNotFound?.({ method, path, req: request }), fc.log)
+		} else {
+			safeFire(() => s.telemetry?.onMethodNotAllowed?.({ allowed, method, path, req: request }), fc.log)
 		}
+		fc.allowed = allowed
+		const plan = this._finalize().miss
+		const ctx = this._newCtx(fc, plan, EMPTY_PARAMS)
+		return plan.run(ctx)
 	}
 
-	private async _handle404(fc: FetchCtx<TEnv>, method: string, path: string): Promise<Response> {
-		safeFire(() => this._telemetry?.onNotFound?.({ method, path, req: fc.request }), fc.log)
-		const make404 = () => {
-			if (this._onNotFound) {
-				return this._onNotFound(this._makeErrorCtx(fc))
-			}
-			return this._makeErrorCtx(fc).jsonFromError(this._createError(EK.not_found, SK.not_found))
-		}
-		try {
-			const ctx404 = new HoneyContext({
-				env: fc.env,
-				executionCtx: fc.executionCtx,
-				params: {},
-				req: fc.request,
-				urlFn: fc.url,
-			})
-			if (this._contextValues) Object.assign(ctx404, this._contextValues)
-			const res =
-				this._chainMiddlewares.length > 0
-					? await executeChain(this._chainMiddlewares, ctx404, make404)
-					: await make404()
+	/** Fire `onResponse` once for the request's one exit and return. A dispatch that rejects
+	 * (an adapter failure past every error boundary) still ends the request: it reports 500. */
+	private _withOnResponse(fc: FetchCtx<TEnv>, res: Response | Promise<Response>): Response | Promise<Response> {
+		const s = this._graph.settings
+		if (s.telemetry?.onResponse === undefined) return res
+		const fire = (status: number): void => {
 			safeFire(
-				() =>
-					this._telemetry?.onResponse?.({
-						duration: performance.now() - fc.startTime,
-						req: fc.request,
-						status: res.status,
-					}),
+				() => s.telemetry?.onResponse?.({ duration: performance.now() - fc.startTime, req: fc.request, status }),
 				fc.log,
 			)
+		}
+		if (!(res instanceof Promise)) {
+			fire(res.status)
 			return res
-		} catch (thrown) {
-			return this._toErrorResponse(thrown)
 		}
+		return res.then(
+			(r) => {
+				fire(r.status)
+				return r
+			},
+			(error: unknown) => {
+				fire(500)
+				throw error
+			},
+		)
 	}
 
-	private _preflightFallbackMethod(allowed: string[]): HttpMethod {
-		if (allowed.includes("GET")) return "GET"
-		if (allowed.includes("HEAD")) return "HEAD"
-		if (allowed.includes("POST")) return "POST"
-		return allowed[0] as HttpMethod
+	private _make404(fc: FetchCtx<TEnv>): Response | Promise<Response> {
+		const s = this._s
+		if (s.onNotFound) return s.onNotFound(this._makeErrorCtx(fc))
+		return this._makeErrorCtx(fc).jsonFromError(this._createError(EK.not_found, SK.not_found))
 	}
 
-	/** Run the existing method's middleware for a CORS preflight. Do not invoke the route handler. */
-	private async _handleCorsPreflight(
-		fc: FetchCtx<TEnv>,
-		path: string,
-		handler: RouteHandler,
-		params: Record<string, string>,
-		allowed: string[],
-	): Promise<Response> {
-		const ctx = new HoneyContext({
-			env: fc.env,
-			executionCtx: fc.executionCtx,
-			meta: handler.mt ? Object.freeze(handler.mt) : undefined,
-			params,
-			path,
-			req: fc.request,
-			routePattern: handler.rp ?? "",
-			urlFn: fc.url,
+	private async _make405(fc: FetchCtx<TEnv>, allowed: string[]): Promise<Response> {
+		const s = this._s
+		const res = s.onMethodNotAllowed
+			? await s.onMethodNotAllowed(this._makeErrorCtx(fc, allowed) as ErrorCtx<TEnv> & { allowed: string[] })
+			: this._makeErrorCtx(fc).jsonFromError(this._createError(EK.method_not_allowed, SK.method_not_allowed))
+		const responseHeaders = new Headers(res.headers)
+		responseHeaders.set("allow", allowed.join(", "))
+		return new Response(res.body, {
+			headers: responseHeaders,
+			status: res.status,
 		})
-		if (this._contextValues) Object.assign(ctx, this._contextValues)
-		try {
-			return await executeChain([...this._globalMiddlewares, ...handler.mw], ctx, () =>
-				this._handle405(fc, "OPTIONS", path, allowed),
-			)
-		} catch (thrown) {
-			return this._toErrorResponse(thrown)
-		}
-	}
-
-	private async _handle405(fc: FetchCtx<TEnv>, method: string, path: string, allowed: string[]): Promise<Response> {
-		safeFire(
-			() =>
-				this._telemetry?.onMethodNotAllowed?.({
-					allowed,
-					method,
-					path,
-					req: fc.request,
-				}),
-			fc.log,
-		)
-		const make405 = async () => {
-			if (this._onMethodNotAllowed) {
-				const res = await this._onMethodNotAllowed(
-					this._makeErrorCtx(fc, allowed) as {
-						allowed: string[]
-						env: TEnv
-						jsonFromError: (err: HoneyError) => Response
-						req: Request
-					},
-				)
-				const responseHeaders = new Headers(res.headers)
-				responseHeaders.set("allow", allowed.join(", "))
-				return new Response(res.body, {
-					headers: responseHeaders,
-					status: res.status,
-				})
-			}
-			const err = this._createError(EK.method_not_allowed, SK.method_not_allowed)
-			const res = this._makeErrorCtx(fc).jsonFromError(err)
-			const responseHeaders = new Headers(res.headers)
-			responseHeaders.set("allow", allowed.join(", "))
-			return new Response(res.body, {
-				headers: responseHeaders,
-				status: res.status,
-			})
-		}
-		try {
-			const ctx405 = new HoneyContext({
-				env: fc.env,
-				executionCtx: fc.executionCtx,
-				params: {},
-				req: fc.request,
-				urlFn: fc.url,
-			})
-			if (this._contextValues) Object.assign(ctx405, this._contextValues)
-			const finalRes =
-				this._chainMiddlewares.length > 0
-					? await executeChain(this._chainMiddlewares, ctx405, make405)
-					: await make405()
-			safeFire(
-				() =>
-					this._telemetry?.onResponse?.({
-						duration: performance.now() - fc.startTime,
-						req: fc.request,
-						status: finalRes.status,
-					}),
-				fc.log,
-			)
-			return finalRes
-		} catch (thrown) {
-			return this._toErrorResponse(thrown)
-		}
 	}
 
-	private _handleMatched(
+	/**
+	 * CORS preflight for a path that has no OPTIONS route: run the chain of the route the
+	 * preflight asks about (`Access-Control-Request-Method`) — chain, scoped and route
+	 * middleware, never input validation or the handler. Middleware that answers the
+	 * preflight (cors) short-circuits; otherwise the answer is the 405 with `Allow`.
+	 */
+	private _handlePreflight(
 		fc: FetchCtx<TEnv>,
-		method: HttpMethod,
-		path: string,
-		handler: RouteHandler,
+		plan: Plan,
 		params: Record<string, string>,
-		stashedMeta?: Record<string, unknown> | null,
+		allowed: string[],
 	): Response | Promise<Response> {
-		const { env, executionCtx, log, request } = fc
-
-		/* resolve error factory — pre-computed ef preferred, else build/use global */
-		let errors: Record<string, (...args: never[]) => unknown> | undefined
-		if (handler.ef != null) {
-			errors = handler.ef
-		} else if (this._errorFactory !== null) {
-			if (handler.ek.size > 0) {
-				const factory = this._errorFactory as Record<string, (...args: never[]) => unknown>
-				const subset = Object.create(null) as Record<string, unknown>
-				for (const key of handler.ek) {
-					if (key in factory) {
-						subset[key] = factory[key]
-					}
-				}
-				errors = Object.freeze(subset) as Record<string, (...args: never[]) => unknown>
-			} else {
-				errors = this._errorFactory as Record<string, (...args: never[]) => unknown>
-			}
-		}
-
-		/* meta: stashed meta from fn:null tree match takes priority over handler meta */
-		const resolvedMeta = stashedMeta ?? handler.mt
-
-		const ctx = new HoneyContext({
-			env,
-			executionCtx,
-			meta: resolvedMeta ?? undefined,
-			params,
-			path,
-			req: request,
-			routePattern: handler.rp ?? "",
-			urlFn: fc.url,
-		})
-		if (this._contextValues) Object.assign(ctx, this._contextValues)
-		if (this._realtimeBus) {
-			const rtBus = this._realtimeBus
-			Object.assign(ctx, {
-				realtime: { publish: (topic: string, data: unknown) => rtBus.publish(topic, data) },
-			})
-		}
-		if (errors) {
-			ctx._setErrors(errors)
-		}
+		fc.allowed = allowed
+		const ctx = this._newCtx(fc, plan, params)
+		const final = this._finalize()
+		plan.pf ??= compileChain(
+			plan.pfChain,
+			(c) => {
+				const rq = (c as HoneyContext<TEnv>)._rq as FetchCtx<TEnv>
+				return this._make405(rq, rq.allowed ?? [])
+			},
+			final.convert,
+		)
+		return plan.pf(ctx)
+	}
 
-		if (this._telemetry !== null) {
+	private _handleMatched(fc: FetchCtx<TEnv>, plan: Plan, params: Record<string, string>): Response | Promise<Response> {
+		const ctx = this._newCtx(fc, plan, params)
+		const telemetry = this._graph.settings.telemetry
+		if (telemetry !== null && telemetry.onRoute !== undefined) {
 			try {
-				this._telemetry.onRoute?.({ method, params, path, req: request })
+				telemetry.onRoute({ method: fc.method, params, path: fc.path, req: fc.request, route: plan.r.rp ?? "" })
 			} catch {
 				/* telemetry must not crash request */
 			}
 		}
-
-		/*
-		 * Tier 3: Use pre-compiled chain when possible.
-		 * Compiled chains are cached on the handler — created once, reused per request.
-		 * Falls back to dynamic assembly when telemetry wrapping, input validation, or
-		 * scoped middleware is in play (scoped mw cannot be baked into the compiled cache
-		 * because each route may match a different subset).
-		 */
-		const hasTelemetryMw = this._telemetry?.onMiddleware !== undefined
-		const hasInputValidation = handler.iv != null
-
-		/*
-		 * Error resolver — stored on ctx so the cached handler wrapper can read it.
-		 * Converts handler errors into error Responses inside the middleware chain,
-		 * allowing all post-next() middleware code (headers, logging, timing) to run.
-		 */
-		ctx._errorToResponse = (thrown: unknown) => this._resolveErrorResponse(thrown, handler, fc, method, path, ctx)
-
-		const onError = (thrown: unknown): Response | Promise<Response> => {
-			if (ctx._errorToResponse) return ctx._errorToResponse(thrown)
-			return this._toErrorResponse(thrown)
-		}
-
-		const after = (response: Response): Response | Promise<Response> => {
-			try {
-				const done = this._afterMatched(fc, method, path, handler, ctx, response)
-				if (done instanceof Promise) return done.catch(onError)
-				return done
-			} catch (thrown) {
-				return onError(thrown)
-			}
-		}
-
-		try {
-			if (!hasTelemetryMw && !hasInputValidation && this._scopedMiddlewares.length === 0) {
-				if (!handler._compiled) {
-					const chainMw = this._chainMiddlewares
-					const handlerHasChain = chainMw.length > 0 && chainMw.every((mw, i) => handler.mw[i] === mw)
-					const allMw = handlerHasChain
-						? [...this._globalMiddlewares, ...handler.mw]
-						: [...this._globalMiddlewares, ...chainMw, ...handler.mw]
-					handler._compiled = compileChain(allMw, (c) => {
-						try {
-							const result = handler.fn(c)
-							if (result instanceof Promise) {
-								return result.catch((thrown: unknown) => {
-									const hCtx = c as HoneyContext<TEnv>
-									if (hCtx._errorToResponse) return hCtx._errorToResponse(thrown)
-									throw thrown
-								})
-							}
-							return result
-						} catch (thrown) {
-							const hCtx = c as HoneyContext<TEnv>
-							if (hCtx._errorToResponse) return hCtx._errorToResponse(thrown)
-							throw thrown
-						}
-					})
-				}
-				const result = handler._compiled(ctx)
-				if (result instanceof Promise) return result.then(after, onError)
-				return after(result)
-			}
-
-			const scopedForPath = this._filterScopedForPath(handler.rp ?? "")
-			const chainMw = this._chainMiddlewares
-			const handlerHasChain = chainMw.length > 0 && chainMw.every((mw, i) => handler.mw[i] === mw)
-			/*
-			 * Ordering: [global → chain → scoped → handler-route-specific]
-			 * When handlerHasChain, handler.mw = [chain..., routeSpecific...].
-			 * Scoped must go after chain but before route-specific, so we split.
-			 */
-			let allMiddlewares: RuntimeMiddleware[] = handlerHasChain
-				? [
-						...this._globalMiddlewares,
-						...handler.mw.slice(0, chainMw.length),
-						...scopedForPath,
-						...handler.mw.slice(chainMw.length),
-					]
-				: [...this._globalMiddlewares, ...chainMw, ...scopedForPath, ...handler.mw]
-
-			if (hasTelemetryMw) {
-				const onMw = this._telemetry?.onMiddleware
-				if (onMw) {
-					allMiddlewares = allMiddlewares.map((mw) => {
-						const name = mw.name || "anonymous"
-						const wrapped: RuntimeMiddleware = async (wCtx, wNext) => {
-							const mwStart = performance.now()
-							try {
-								const res = await mw(wCtx, wNext)
-								safeFire(() => onMw({ duration: performance.now() - mwStart, name }), log)
-								return res
-							} catch (error) {
-								safeFire(
-									() =>
-										onMw({
-											duration: performance.now() - mwStart,
-											error,
-											name,
-										}),
-									log,
-								)
-								throw error
-							}
-						}
-						return wrapped
-					})
-				}
-			}
-
-			if (hasInputValidation) {
-				const schemas = handler.iv
-				if (schemas) {
-					const inputMw: RuntimeMiddleware = async (inputCtx, inputNext) => {
-						const validated = await validateInput(schemas, inputCtx["req"] as Request, params)
-						return inputNext({ input: validated })
-					}
-					allMiddlewares.push(inputMw)
-				}
-			}
-
-			return executeChain(allMiddlewares, ctx, (finalCtx) => {
-				try {
-					const result = handler.fn(finalCtx)
-					if (result instanceof Promise) {
-						return result.catch((thrown: unknown) => {
-							const hCtx = finalCtx as HoneyContext<TEnv>
-							if (hCtx._errorToResponse) return hCtx._errorToResponse(thrown)
-							throw thrown
-						})
-					}
-					return result
-				} catch (thrown) {
-					const hCtx = finalCtx as HoneyContext<TEnv>
-					if (hCtx._errorToResponse) return hCtx._errorToResponse(thrown)
-					throw thrown
-				}
-			}).then(after, onError)
-		} catch (thrown) {
-			/* safety net — middleware-level errors (input validation, middleware crash) */
-			return onError(thrown)
-		}
-	}
-
-	private _afterMatched(
-		fc: FetchCtx<TEnv>,
-		method: HttpMethod,
-		path: string,
-		handler: RouteHandler,
-		ctx: HoneyContext<TEnv>,
-		response: Response,
-	): Response | Promise<Response> {
-		const validateOut =
-			this._outputValidation === "always" ||
-			(this._outputValidation === "dev" &&
-				(globalThis as { process?: { env?: { NODE_ENV?: string } } }).process?.env?.NODE_ENV !== "production")
-		if (handler.os && validateOut && response.body !== null && !ctx._isErrorResponse) {
-			return this._validateThenFinish(fc, method, path, handler, ctx, response)
-		}
-		return this._finishMatched(fc, method, path, handler, ctx, response)
+		const res = plan.run(ctx)
+		if (res instanceof Promise) return res.then((r) => this._finishMatched(fc, plan, ctx, r))
+		return this._finishMatched(fc, plan, ctx, res)
 	}
 
-	private async _validateThenFinish(
-		fc: FetchCtx<TEnv>,
-		method: HttpMethod,
-		path: string,
-		handler: RouteHandler,
-		ctx: HoneyContext<TEnv>,
-		response: Response,
-	): Promise<Response> {
+	/** Output validation, inside the chain: an invalid body becomes an error response the middleware sees. */
+	private async _validateOutput(handler: RouteHandler, ctx: HoneyContext<TEnv>, response: Response): Promise<Response> {
+		if (response === undefined || response === null || ctx._isErrorResponse) return response
+		/* read the creation tag, never `response.body`: on Node that would build a stream per response */
+		const kind = bodyKind(response)
+		if (kind === "empty") return response
 		const ct = response.headers.get("content-type")
 
 		/* content-type mismatch check */
@@ -2636,30 +2825,33 @@ export class Honey<
 			}
 		}
 
-		/* JSON schema validation — read original, return clone (Bun clone() drains original) */
-		if (ct?.startsWith("application/json") && handler.ov) {
+		/* JSON schema validation. A body Honey built from a string is validated from that string
+		 * (no stream, no tee); anything else is read from a clone (Bun clone() drains the original).
+		 * A stream Honey created (sse, stream, generate) is never buffered: it may never end. */
+		if (ct?.startsWith("application/json") && handler.ov && !isProducedStream(response)) {
 			const sk = codeToStatusKey[response.status]
 			if (sk) {
+				const raw = rawBodyOf(response)
+				if (raw !== null) {
+					const text = typeof raw === "string" ? raw : new TextDecoder().decode(raw)
+					await handler.ov(sk, text.length === 0 ? null : JSON.parse(text))
+					return response
+				}
 				const forReturn = response.clone()
 				const data: unknown = await response.json()
 				await handler.ov(sk, data)
-				response = forReturn
+				return forReturn
 			}
 		}
-		return this._finishMatched(fc, method, path, handler, ctx, response)
+		return response
 	}
 
-	private _finishMatched(
-		fc: FetchCtx<TEnv>,
-		method: HttpMethod,
-		path: string,
-		handler: RouteHandler,
-		ctx: HoneyContext<TEnv>,
-		response: Response,
-	): Response {
+	private _finishMatched(fc: FetchCtx<TEnv>, plan: Plan, ctx: HoneyContext<TEnv>, response: Response): Response {
+		const s = this._graph.settings
+		const handler = plan.r
 		/* taps — fire after successful handler, non-blocking */
-		if (this._taps !== null && !ctx._isErrorResponse) {
-			const taps = this._taps
+		if (plan.taps !== null && !ctx._isErrorResponse) {
+			const taps = plan.taps
 			const log = fc.log
 
 			/* meta-driven taps — fire for each registered key found in route meta */
@@ -2669,8 +2861,8 @@ export class Honey<
 					if (metaValue !== undefined) {
 						ctx.background(
 							Promise.resolve()
-								.then(() => tapFn(ctx, metaValue))
-								.catch((e) => log?.warn?.("tap failed", key, e)),
+								.then(() => tapFn(ctx as unknown as TapContext<unknown>, metaValue))
+								.catch((e) => log?.warn?.({ err: e, tap: key }, "tap failed")),
 						)
 					}
 				}
@@ -2683,8 +2875,8 @@ export class Honey<
 					if (tapFn !== undefined) {
 						ctx.background(
 							Promise.resolve()
-								.then(() => tapFn(ctx, pending.payload))
-								.catch((e) => log?.warn?.("tap failed", pending.key, e)),
+								.then(() => tapFn(ctx as unknown as TapContext<unknown>, pending.payload))
+								.catch((e) => log?.warn?.({ err: e, tap: pending.key }, "tap failed")),
 						)
 					}
 				}
@@ -2692,31 +2884,21 @@ export class Honey<
 			}
 		}
 
-		if (this._telemetry !== null) {
+		if (s.telemetry !== null) {
 			try {
 				const duration = performance.now() - fc.startTime
-				this._telemetry.onHandler?.({
-					duration,
-					method,
-					path,
-					status: response.status,
-				})
-				this._telemetry.onResponse?.({
+				s.telemetry.onHandler?.({
 					duration,
-					req: fc.request,
+					method: fc.method,
+					path: fc.path,
+					route: handler.rp ?? "",
 					status: response.status,
 				})
 			} catch {
 				/* telemetry must never crash the response path */
 			}
 		}
-		/* HEAD responses must have empty body — preserve headers + status */
-		if (method === "HEAD") {
-			return new Response(null, {
-				headers: response.headers,
-				status: response.status,
-			})
-		}
+		if (fc.method === "HEAD") return headResponse(response)
 		return response
 	}
 }
@@ -2810,15 +2992,6 @@ type ApplyScoped<TScopedMw extends readonly ScopedMwEntry[], TFullPath extends s
 			ApplyScoped<Rest, TFullPath>
 	: {}
 
-/** @internal — runtime entry for a scoped middleware */
-type ScopedEntry = {
-	/** merged full-path prefix (already rebased against basePath at .use time) */
-	prefix: string
-	mw: RuntimeMiddleware
-	/** cached from mw.errors at registration; undefined when none */
-	errors: readonly string[] | undefined
-}
-
 /** Apply typed params — override params with specific keys when route has :param segments */
 type ApplyParams<TCtx, TParams> = [keyof TParams] extends [string]
 	? string extends keyof TParams
@@ -2859,27 +3032,30 @@ type HandlerCtx<
 
 /** @internal — exposes private Honey members for RouteBuilder/WSRouteBuilder access */
 type HoneyInternal = {
+	_addRoute(method: string, segments: readonly Segment[], record: RouteHandler): void
+	_addWsRoute(segments: readonly Segment[], record: WSRouteHandler): void
 	_factory: unknown
-	_markWsRoutes(): void
-	_registerStatic(key: string, handler: RouteHandler): void
+	_settle(pending: PendingRoute): void
+	_view(): { chain: RuntimeMiddleware[]; cv: Record<string, unknown> | null; own: unknown }
 }
 
 type RouteBuilderState<TParent> = {
 	boundaryErrorKey: string | null
+	/** keys the route declares itself (`.errors()`, `.boundary()`) */
 	errorKeys: Set<string>
 	extraMethods: (HttpMethod | "ALL")[] | null
-	handlerMap: Record<string, RouteHandler> | null
 	inputSchemas: InputSchemasDef | null
+	/** explicit meta — chain `.meta()` overlaid by route `.meta()` */
 	meta: Record<string, unknown> | null
-	/** meta contributed by middleware — kept apart so explicit .meta() always outranks it */
-	mwMeta: Record<string, unknown> | null
 	method: HttpMethod | "ALL"
+	/** route-level middleware */
 	middlewares: RuntimeMiddleware[]
 	outputSchemas: OutputSchemaDef | null
 	parent: TParent
-	parentMiddlewares: RuntimeMiddleware[]
+	/** canonical full pattern */
 	path: string
-	root: TreeNode
+	/** reported at finalize until `.handler()` runs */
+	pending: PendingRoute
 }
 
 /**
@@ -3224,84 +3400,38 @@ class RouteBuilder<
 		}
 
 		const isInternal = Symbol.for("honey.internal") in fn
-		if (isInternal) {
-			Object.defineProperty(fn, Symbol.for("honey.app"), { value: this._s.parent })
-		}
+		/* a bound copy per app: one `spec()` or docs handler may be mounted on several apps */
+		if (isInternal) fn = bindInternalHandler(fn, this._s.parent)
 
-		const routeHandler: RouteHandler = {
+		const parent = this._s.parent as unknown as HoneyInternal
+		const view = parent._view()
+		const base: RouteHandler = {
 			_skip: isInternal || undefined,
-			bek: this._s.boundaryErrorKey,
-			ef: null,
-			ek: this._s.errorKeys,
+			bek: null,
+			cm: [...view.chain],
+			cv: view.cv,
+			dk: new Set(this._s.errorKeys),
+			/* provisional until finalize resolves scopes and app defaults */
+			ek: new Set(this._s.errorKeys),
 			fn: fn as (ctx: unknown) => Response | Promise<Response>,
 			iv: this._s.inputSchemas,
-			mt: mergeContributedMeta(this._s.mwMeta, this._s.meta),
-			mw: [...this._s.parentMiddlewares, ...this._s.middlewares],
+			mt: mergeContributedMeta(collectMiddlewareMeta([view.chain, this._s.middlewares]), this._s.meta),
+			mw: [],
 			os: this._s.outputSchemas,
 			ov,
-			rp: this._s.path,
-		}
-
-		/* patch mode: if handler map has this route, patch existing handler instead of insertRoute */
-		const handlerMap = this._s.handlerMap
-		if (handlerMap) {
-			const key = `${this._s.method} ${this._s.path}`
-			const existing = handlerMap[key]
-			if (existing) {
-				existing.fn = routeHandler.fn
-				existing.mw = routeHandler.mw
-				existing.iv = routeHandler.iv
-				existing.os = routeHandler.os
-				existing.ov = routeHandler.ov
-				/* pre-compute filtered error factory */
-				const factory = (this._s.parent as unknown as HoneyInternal)._factory
-				if (factory !== null && existing.ek.size > 0) {
-					const ef = Object.create(null) as Record<string, (...args: never[]) => unknown>
-					const fac = factory as Record<string, (...args: never[]) => unknown>
-					for (const k of existing.ek) {
-						const factoryFn = fac[k]
-						if (factoryFn !== undefined) {
-							ef[k] = factoryFn
-						}
-					}
-					existing.ef = Object.freeze(ef)
-				}
-				return this._s.parent as HandlerReturn<
-					TEnv,
-					TBaseCtx,
-					TRoutes,
-					TPath,
-					TMethod,
-					TInput,
-					TOutput,
-					TCtx,
-					TAccMeta,
-					TErrorFactory,
-					_TErrorKeys,
-					TDefaultErrors,
-					TMeta,
-					TBasePath,
-					TTaps,
-					TScopedMw
-				>
-			}
+			own: view.own,
+			rb: this._s.boundaryErrorKey,
+			rm: [...this._s.middlewares],
+			xm: this._s.meta ? { ...this._s.meta } : null,
 		}
 
-		insertRoute(this._s.root, this._s.method, this._s.path, routeHandler)
-
-		/* .on() extra methods — insert same handler for each additional method */
-		if (this._s.extraMethods) {
-			for (const m of this._s.extraMethods) {
-				insertRoute(this._s.root, m, this._s.path, routeHandler)
-				if (!this._s.path.includes(":") && !this._s.path.includes("*")) {
-					;(this._s.parent as unknown as HoneyInternal)._registerStatic(`${m} ${this._s.path}`, routeHandler)
-				}
-			}
-		}
-
-		/* populate static route map for O(1) lookup on non-parameterized routes */
-		if (!this._s.path.includes(":") && !this._s.path.includes("*")) {
-			;(this._s.parent as unknown as HoneyInternal)._registerStatic(`${this._s.method} ${this._s.path}`, routeHandler)
+		/* one record per method — `.on([...])` registers each under its own RouteId */
+		parent._settle(this._s.pending)
+		const segments = parsePattern(this._s.path)
+		const methods = [this._s.method, ...(this._s.extraMethods ?? [])]
+		for (const method of methods) assertBodySchemaAllowed(this._s.inputSchemas, method, this._s.path)
+		for (let i = 0; i < methods.length; i++) {
+			parent._addRoute(methods[i], segments, i === 0 ? base : copyRecord(base))
 		}
 		return this._s.parent as HandlerReturn<
 			TEnv,
@@ -3355,7 +3485,7 @@ class RouteBuilder<
 		TTaps,
 		TScopedMw
 	> {
-		const proxyHandler = createProxyHandler(config)
+		const proxyHandler = requireFeature("proxy", ".proxy()").createProxyHandler(config)
 		return this.handler(
 			proxyHandler as (
 				ctx: HandlerCtx<
@@ -3536,11 +3666,6 @@ class RouteBuilder<
 		TTaps,
 		TScopedMw
 	> {
-		if (mw.errors) {
-			for (const k of mw.errors) {
-				this._s.errorKeys.add(k)
-			}
-		}
 		return new RouteBuilder<
 			TEnv,
 			TCtx & TAdds,
@@ -3562,31 +3687,22 @@ class RouteBuilder<
 		>({
 			...this._s,
 			middlewares: [...this._s.middlewares, mw as RuntimeMiddleware],
-			mwMeta: mw.meta ? { ...this._s.mwMeta, ...mw.meta } : this._s.mwMeta,
 		})
 	}
 }
 
 type WSRouteBuilderState<TParent> = {
-	mwMeta?: Record<string, unknown> | null
-	boundaryErrorKey: string | null
 	errorKeys: Set<string>
 	inputSchemas: InputSchemasDef | null
+	origins: WSOriginPolicy | null
 	meta: Record<string, unknown> | null
 	middlewares: RuntimeMiddleware[]
 	parent: TParent
-	parentMiddlewares: RuntimeMiddleware[]
 	path: string
-	root: TreeNode
+	pending: PendingRoute
 }
 
-class WSRouteBuilder<
-	TEnv,
-	TCtx,
-	TInput = {},
-	_TErrorKeys extends string = never,
-	TParent extends { _markWsRoutes(): void } = { _markWsRoutes(): void },
-> {
+class WSRouteBuilder<TEnv, TCtx, TInput = {}, _TErrorKeys extends string = never, TParent = unknown> {
 	private _s: WSRouteBuilderState<TParent>
 
 	constructor(state: WSRouteBuilderState<TParent>) {
@@ -3608,17 +3724,27 @@ class WSRouteBuilder<
 	}
 
 	handler(wsHandler: WSHandler<TCtx>): TParent {
+		const parent = this._s.parent as unknown as HoneyInternal
+		const view = parent._view()
 		const routeHandler: WSRouteHandler = {
-			bek: this._s.boundaryErrorKey,
-			ek: this._s.errorKeys,
+			bek: null,
+			cm: [...view.chain],
+			cv: view.cv,
+			dk: new Set(this._s.errorKeys),
+			ek: new Set(),
 			fn: wsHandler as WSHandler<unknown>,
 			iv: this._s.inputSchemas,
-			mt: mergeContributedMeta(this._s.mwMeta, this._s.meta),
-			mw: [...this._s.parentMiddlewares, ...this._s.middlewares],
+			mt: null,
+			mw: [],
+			og: this._s.origins,
+			own: view.own,
+			rb: null,
+			rm: [...this._s.middlewares],
 			rp: this._s.path,
+			xm: this._s.meta ? { ...this._s.meta } : null,
 		}
-		insertWsRoute(this._s.root, this._s.path, routeHandler)
-		;(this._s.parent as unknown as HoneyInternal)._markWsRoutes()
+		parent._settle(this._s.pending)
+		parent._addWsRoute(parsePattern(this._s.path), routeHandler)
 		return this._s.parent
 	}
 
@@ -3632,20 +3758,26 @@ class WSRouteBuilder<
 	}
 
 	meta(meta: Record<string, unknown>): this {
-		this._s.meta = meta
+		this._s.meta = { ...this._s.meta, ...meta }
 		return this
 	}
 
+	/**
+	 * Browser origins allowed to open this socket: `"*"`, a list of origins
+	 * (`https://app.example.com`), or a predicate. Same-origin always passes. Without it, a
+	 * cross-origin upgrade that carries `Cookie` or `Authorization` gets 403.
+	 */
+	origins(policy: WSOriginPolicy): WSRouteBuilder<TEnv, TCtx, TInput, _TErrorKeys, TParent> {
+		return new WSRouteBuilder<TEnv, TCtx, TInput, _TErrorKeys, TParent>({
+			...this._s,
+			origins: validateOriginPolicy(policy),
+		})
+	}
+
 	use<TAdds>(mw: MiddlewareFn<TCtx, TAdds>): WSRouteBuilder<TEnv, TCtx & TAdds, TInput, _TErrorKeys, TParent> {
-		if (mw.errors) {
-			for (const k of mw.errors) {
-				this._s.errorKeys.add(k)
-			}
-		}
 		return new WSRouteBuilder<TEnv, TCtx & TAdds, TInput, _TErrorKeys, TParent>({
 			...this._s,
 			middlewares: [...this._s.middlewares, mw as RuntimeMiddleware],
-			mwMeta: mw.meta ? { ...this._s.mwMeta, ...mw.meta } : this._s.mwMeta,
 		})
 	}
 }