@lovrozagar/honey 0.6.5 → 0.7.0

package/src/tree.ts

@@ -1,92 +1,146 @@
+import type { RouteId, Segment } from "./pattern.ts"
+import { canonical, expandOptional, parsePattern, routeId } from "./pattern.ts"
 import type { HttpMethod, InputSchemasDef, OutputSchemaDef } from "./types.ts"
 import type { WSHandler } from "./ws/cloudflare.ts"
+import type { WSOriginPolicy } from "./ws-origin.ts"
 
-export type { HttpMethod }
+export type { HttpMethod, RouteId }
 
 export type OutputValidator = (statusKey: string, data: unknown) => Promise<void>
 
-export type RouteHandler = {
-	/** cached compiled middleware chain (set lazily at first request) */
-	_compiled?: (ctx: object) => Response | Promise<Response>
-	/** internal route — excluded from codegen output */
+type ChainMiddleware = (
+	ctx: Record<string, unknown>,
+	next: (additions?: Record<string, unknown>) => Promise<Response>,
+) => Promise<Response>
+
+/**
+ * What a route was registered with, before the app resolves it. Finalize derives the
+ * resolved fields (`ek`, `mt`, `mw`, `bek`, `ef`) from these, so they never depend on the
+ * order of registration and are recomputed whenever the route graph changes.
+ */
+type RecordSource = {
+	/** chain middleware captured at registration (plus any mounting chain) */
+	cm?: ChainMiddleware[]
+	/** `.context()` values of the registering handle (merged with the mounting handle's) */
+	cv?: Record<string, unknown> | null
+	/** error keys the route declared itself (`.errors()`, `.boundary()`) */
+	dk?: Set<string>
+	/** the settings of the app the route was registered on — opaque here */
+	own?: unknown
+	/** route-level boundary key (`.boundary()`) */
+	rb?: string | null
+	/** route-level middleware (`.get(...).use(mw)`) */
+	rm?: ChainMiddleware[]
+	/** explicit meta: chain `.meta()` overlaid by route `.meta()` */
+	xm?: Record<string, unknown> | null
+}
+
+/**
+ * A route record — everything one registered route runs. Records live in a per-app table
+ * keyed by `RouteId`; the tree only holds ids, so two apps that load the same tree never
+ * share a record.
+ */
+export type RouteHandler = RecordSource & {
+	/** internal route (spec, docs, manifest) — excluded from codegen output, never mounted into a parent */
 	_skip?: boolean
 	/** boundary error key — wraps undeclared/unexpected errors (null = use default or internal_server_error) */
 	bek: string | null
-	/** pre-computed error factory subset (omit/`null` = use global factory) */
+	/** gateway catch-all: dispatches delegated routes, never matched for a path of its own */
+	ca?: boolean
+	/** delegated route: a tree leaf with no local handler, served by the gateway catch-all */
+	dl?: boolean
+	/** resolved error factory subset exposed as `ctx.errors` (omit/`null` = none) */
 	ef?: Record<string, (...args: never[]) => unknown> | null
-	/** declared error keys for this route — used for runtime enforcement */
+	/** declared error keys — resolved at finalize from the route, its middleware and the app defaults */
 	ek: Set<string>
+	/** resolved error factory — the route's own app's, or the serving app's */
+	fac?: Record<string, (...args: never[]) => unknown> | null
 	/** handler function */
 	fn: (ctx: unknown) => Response | Promise<Response>
-	/** input validation schemas — intern trees omit; missing/`null` = no validation */
+	/** route identity: `METHOD /canonical/pattern` */
+	id?: RouteId
+	/** input validation schemas — missing/`null` = no validation */
 	iv?: InputSchemasDef | null
 	/** route metadata — frozen object, accessible via ctx.meta */
 	mt: Record<string, unknown> | null
-	/** middleware chain — same as RuntimeMiddleware, inlined to avoid circular dep */
-	mw: Array<
-		(
-			ctx: Record<string, unknown>,
-			next: (additions?: Record<string, unknown>) => Promise<Response>,
-		) => Promise<Response>
-	>
-	/** output schemas by content-type — intern trees omit; missing/`null` = no validation */
+	/** resolved middleware chain, in run order: chain, scoped, route */
+	mw: ChainMiddleware[]
+	/** output schemas by content-type — missing/`null` = no validation */
 	os?: OutputSchemaDef | null
 	/** output validator function — validates response body against schema */
 	ov?: OutputValidator | null
-	/** registered path pattern (e.g. "/users/:id"); intern trees omit this */
+	/** canonical route pattern (e.g. "/users/:id") */
 	rp?: string
 }
 
 export type { OutputSchemaDef }
 
-export type WSRouteHandler = {
+export type WSRouteHandler = RecordSource & {
 	bek: string | null
 	ek: Set<string>
+	ef?: Record<string, (...args: never[]) => unknown> | null
+	fac?: Record<string, (...args: never[]) => unknown> | null
 	fn: WSHandler<unknown>
+	id?: RouteId
 	iv: InputSchemasDef | null
 	mt: Record<string, unknown> | null
-	mw: Array<
-		(
-			ctx: Record<string, unknown>,
-			next: (additions?: Record<string, unknown>) => Promise<Response>,
-		) => Promise<Response>
-	>
-	/** registered ws path pattern — used by scoped-mw prefix filter */
+	mw: ChainMiddleware[]
+	/** browser origins allowed to open the socket (`.origins()`); `null` = same-origin when credentialed */
+	og?: WSOriginPolicy | null
+	/** canonical ws path pattern */
 	rp: string
 }
 
+/**
+ * Router topology. Leaves are `RouteId`s, never handler objects: what a leaf runs is looked
+ * up in the serving app's own route table.
+ */
 export type TreeNode = {
 	/** dynamic param child — { n: param name, c: child subtree } */
 	d: { c: TreeNode; n: string } | null
-	/** route-graph generation — bumped on insert/merge so served specs can invalidate */
-	g?: number
-	/** method handlers — maps HTTP method (or ALL) to route handler */
-	m: Record<HttpMethod | "ALL", RouteHandler> | null
-	/** static children — maps literal path segment to child subtree */
+	/** method → route id at this exact path */
+	m: Record<string, RouteId> | null
+	/** static children — maps literal path segment to child subtree (null-prototype) */
 	s: Record<string, TreeNode>
-	/** wildcard handler — { n: wildcard name, m: method→handler map } */
-	w: { m: Record<HttpMethod | "ALL", RouteHandler>; n: string } | null
-	/** websocket handler for this path */
-	ws: WSRouteHandler | null
+	/** wildcard — { n: wildcard name, m: method → route id } */
+	w: { m: Record<string, RouteId>; n: string } | null
+	/** websocket route id for this path */
+	ws: RouteId | null
 }
 
-export function bumpGeneration(root: TreeNode): number {
-	const next = (root.g ?? 0) + 1
-	root.g = next
-	return next
+/** Descriptive data for one route in a tree. Generated files carry only this. */
+export type RouteEntry = {
+	/** boundary error key */
+	bek?: string | null
+	/** declared error keys */
+	ek?: readonly string[]
+	/** live record — only in `app.toRouteTree()` snapshots, never in generated files */
+	h?: RouteHandler | WSRouteHandler
+	/** internal route (spec, docs, manifest) */
+	i?: 1 | true
+	/** input schemas — only in live snapshots */
+	iv?: InputSchemasDef | null
+	/** route meta */
+	mt?: Record<string, unknown> | null
+	/** output schemas — only in live snapshots */
+	os?: OutputSchemaDef | null
 }
 
 export type MatchResult =
 	| { allowed: HttpMethod[]; matched: false }
-	| { handler: RouteHandler; matched: true; params: Record<string, string> }
+	| { id: RouteId; matched: true; params: Record<string, string> }
 	| null
 
 export interface RouteMeta {}
 
+/** Format of route trees: topology + per-route data. */
+export const ROUTE_TREE_VERSION = 2
+
 export type RouteTree = {
-	handlers?: Record<string, RouteHandler>
 	meta: Record<string, RouteMeta>
 	root: TreeNode
+	routes: Record<RouteId, RouteEntry>
+	v?: number
 }
 
 function decode(s: string): string {
@@ -98,385 +152,403 @@ function decode(s: string): string {
 	}
 }
 
+function dict<T>(): Record<string, T> {
+	return Object.create(null) as Record<string, T>
+}
+
 export function createNode(): TreeNode {
-	return {
-		d: null,
-		m: null,
-		s: Object.create(null) as Record<string, TreeNode>,
-		w: null,
-		ws: null,
-	}
+	return { d: null, m: null, s: dict<TreeNode>(), w: null, ws: null }
 }
 
-function splitSegments(path: string): string[] {
-	return path.split("/").filter((s) => s.length > 0)
+function describe(method: string, path: string): string {
+	return method === "WS" ? `WebSocket route ${path}` : `route: ${method} ${path}`
 }
 
-export function insertRoute(root: TreeNode, method: HttpMethod | "ALL", path: string, handler: RouteHandler): void {
-	bumpGeneration(root)
-	const segments = splitSegments(path)
+/**
+ * Put `id` at the leaf for `segments` × `method` (`"WS"` for the websocket slot). The same id
+ * already there is a no-op; any other id is a duplicate. Optional params must be expanded by
+ * the caller — every call places exactly one leaf.
+ */
+export function insertLeaf(root: TreeNode, segments: readonly Segment[], method: string, id: RouteId): void {
+	const path = canonical(segments)
 	let node = root
-
 	for (const seg of segments) {
-		if (seg.startsWith("*")) {
-			const name = seg.length > 1 ? seg.slice(1) : "*"
-			if (node.w !== null && node.w.n !== name) {
-				throw new Error(`Wildcard name conflict: "${node.w.n}" vs "${name}"`)
-			}
-			if (node.w === null) {
-				node.w = {
-					m: Object.create(null) as Record<HttpMethod | "ALL", RouteHandler>,
-					n: name,
-				}
-			}
-			if (method in node.w.m) {
-				throw new Error(`Duplicate route: ${method} ${path}`)
+		if (seg.k === "wildcard") {
+			if (method === "WS") throw new Error("Wildcard segments not supported for WebSocket routes")
+			if (node.w !== null && node.w.n !== seg.n) {
+				throw new Error(`Wildcard name conflict: "${node.w.n}" vs "${seg.n}"`)
 			}
-			node.w.m[method] = handler
+			if (node.w === null) node.w = { m: dict<RouteId>(), n: seg.n }
+			const prev = node.w.m[method]
+			if (prev !== undefined && prev !== id) throw new Error(`Duplicate ${describe(method, path)}`)
+			node.w.m[method] = id
 			return
 		}
-
-		if (seg.startsWith(":")) {
-			const name = seg.endsWith("?") ? seg.slice(1, -1) : seg.slice(1)
-			if (node.d !== null && node.d.n !== name) {
-				throw new Error(`Route "${path}": param name conflict — expected ":${node.d.n}" but got ":${name}"`)
-			}
-			if (node.d === null) {
-				node.d = { c: createNode(), n: name }
+		if (seg.k === "param") {
+			if (node.d !== null && node.d.n !== seg.n) {
+				throw new Error(`Route "${path}": param name conflict — expected ":${node.d.n}" but got ":${seg.n}"`)
 			}
-
-			if (seg.endsWith("?")) {
-				/* optional param — register handler on parent too */
-				if (node.m === null) {
-					node.m = Object.create(null) as Record<HttpMethod | "ALL", RouteHandler>
-				}
-				if (method in node.m) {
-					throw new Error(`Duplicate route: ${method} ${path}`)
-				}
-				node.m[method] = handler
-			}
-
+			if (node.d === null) node.d = { c: createNode(), n: seg.n }
 			node = node.d.c
 			continue
 		}
-
-		/* static segment */
-		const staticChild = node.s[seg]
-		if (staticChild !== undefined) {
-			node = staticChild
-			continue
+		let child = node.s[seg.v]
+		if (child === undefined) {
+			child = createNode()
+			node.s[seg.v] = child
 		}
-		const nextNode = createNode()
-		node.s[seg] = nextNode
-		node = nextNode
-	}
-
-	/* terminal node */
-	if (node.m === null) {
-		node.m = Object.create(null) as Record<HttpMethod | "ALL", RouteHandler>
+		node = child
 	}
-	if (method in node.m) {
-		throw new Error(`Duplicate route: ${method} ${path}`)
+	if (method === "WS") {
+		if (node.ws !== null && node.ws !== id) throw new Error(`Duplicate WebSocket route: ${path}`)
+		node.ws = id
+		return
 	}
-	node.m[method] = handler
+	if (node.m === null) node.m = dict<RouteId>()
+	const prev = node.m[method]
+	if (prev !== undefined && prev !== id) throw new Error(`Duplicate ${describe(method, path)}`)
+	node.m[method] = id
 }
 
-function resolveMethod(
-	handlers: Record<HttpMethod | "ALL", RouteHandler>,
-	method: HttpMethod,
-	params: Record<string, string>,
-): MatchResult {
-	if (method in handlers) {
-		return { handler: handlers[method], matched: true, params }
-	}
-	/* HEAD falls back to GET handler */
-	if (method === "HEAD" && "GET" in handlers) {
-		return { handler: handlers["GET"], matched: true, params }
-	}
-	if ("ALL" in handlers) {
-		return { handler: handlers["ALL"], matched: true, params }
+/**
+ * Place a route's leaves by pattern (an optional last param places two). The leaf holds
+ * `id`, by default the route's `RouteId`, which is returned.
+ */
+export function insertRoute(root: TreeNode, method: HttpMethod | "ALL", path: string, id?: RouteId): RouteId {
+	const segments = parsePattern(path)
+	const rid = id ?? routeId(method, canonical(segments))
+	for (const v of expandOptional(segments)) {
+		if (findLeaf(root, v, method) !== undefined) throw new Error(`Duplicate route: ${method} ${canonical(v)}`)
+		insertLeaf(root, v, method, rid)
 	}
-	const allowed = Object.keys(handlers).filter((k) => k !== "ALL") as HttpMethod[]
-	return { allowed, matched: false }
+	return rid
 }
 
-export function matchRoute(root: TreeNode, method: HttpMethod, path: string): MatchResult {
-	let node = root
-	const params: Record<string, string> = Object.create(null)
-	const len = path.length
-
-	/* skip leading slash */
-	let pos = path.charCodeAt(0) === 47 ? 1 : 0
-
-	while (pos < len) {
-		/* find next slash or end */
-		let end = pos
-		while (end < len && path.charCodeAt(end) !== 47) end++
-		if (end === pos) {
-			pos++
-			continue
-		}
-		const seg = path.substring(pos, end)
-		pos = end + 1
+/** Place a websocket route's leaf by pattern; returns its `RouteId`. */
+export function insertWsRoute(root: TreeNode, path: string, id?: RouteId): RouteId {
+	const segments = parsePattern(path)
+	const rid = id ?? routeId("WS", canonical(segments))
+	for (const v of expandOptional(segments)) {
+		if (findLeaf(root, v, "WS") !== undefined) throw new Error(`Duplicate WebSocket route: ${canonical(v)}`)
+		insertLeaf(root, v, "WS", rid)
+	}
+	return rid
+}
 
-		/* 1. static child */
-		const staticChild = node.s[seg]
-		if (staticChild !== undefined) {
-			node = staticChild
-			continue
+/** Exact lookup: the id at the leaf for `segments` × `method`, without matching params against values. */
+export function findLeaf(root: TreeNode, segments: readonly Segment[], method: string): RouteId | undefined {
+	let node: TreeNode | undefined = root
+	for (const seg of segments) {
+		if (node === undefined) return undefined
+		if (seg.k === "wildcard") {
+			if (node.w === null || node.w.n !== seg.n) return undefined
+			return node.w.m[method]
 		}
-
-		/* 2. dynamic param */
-		if (node.d !== null) {
-			params[node.d.n] = decode(seg)
+		if (seg.k === "param") {
+			if (node.d === null || node.d.n !== seg.n) return undefined
 			node = node.d.c
 			continue
 		}
-
-		/* 3. wildcard — consumes remaining */
-		if (node.w !== null) {
-			params[node.w.n] = decode(pos <= len ? `${seg}/${path.substring(pos)}` : seg)
-			return resolveMethod(node.w.m, method, params)
-		}
-
-		return null
-	}
-
-	/* terminal node */
-	if (node.m !== null) {
-		return resolveMethod(node.m, method, params)
+		node = node.s[seg.v]
 	}
+	if (node === undefined) return undefined
+	if (method === "WS") return node.ws ?? undefined
+	return node.m?.[method]
+}
 
-	/* check wildcard for empty remainder */
-	if (node.w !== null) {
-		params[node.w.n] = ""
-		return resolveMethod(node.w.m, method, params)
+function pickMethod(m: Record<string, RouteId>, method: string): RouteId | undefined {
+	const exact = m[method]
+	if (exact !== undefined) return exact
+	if (method === "HEAD") {
+		const get = m["GET"]
+		if (get !== undefined) return get
 	}
+	return m["ALL"]
+}
 
-	return null
+type MatchState = {
+	allowed: Set<string> | null
+	method: string
+	names: string[]
+	path: string
+	values: string[]
 }
 
-export function insertWsRoute(root: TreeNode, path: string, handler: WSRouteHandler): void {
-	bumpGeneration(root)
-	const segments = splitSegments(path)
-	let node = root
+function addAllowed(st: MatchState, m: Record<string, RouteId>): void {
+	if (st.allowed === null) st.allowed = new Set()
+	for (const k in m) if (k !== "ALL") st.allowed.add(k)
+}
 
-	for (const seg of segments) {
-		if (seg.startsWith("*")) {
-			throw new Error("Wildcard segments not supported for WebSocket routes")
+/*
+ * Depth-first in precedence order — static, then param, then wildcard — retrying the next
+ * branch on a dead end and on a method miss. A trie node sits at one depth, so each node is
+ * visited at most once per request: the walk is linear in the route set, and recursion depth
+ * is bounded by the deepest registered route, not by the request path.
+ */
+function walk(node: TreeNode, pos: number, st: MatchState): RouteId | undefined {
+	const path = st.path
+	const len = path.length
+	while (pos < len && path.charCodeAt(pos) === 47) pos++
+	if (pos >= len) {
+		if (node.m !== null) {
+			const id = pickMethod(node.m, st.method)
+			if (id !== undefined) return id
+			addAllowed(st, node.m)
 		}
-
-		if (seg.startsWith(":")) {
-			const name = seg.slice(1)
-			if (node.d !== null && node.d.n !== name) {
-				throw new Error(`Route "${path}": param name conflict — expected ":${node.d.n}" but got ":${name}"`)
-			}
-			if (node.d === null) {
-				node.d = { c: createNode(), n: name }
+		if (node.w !== null) {
+			const id = pickMethod(node.w.m, st.method)
+			if (id !== undefined) {
+				st.names.push(node.w.n)
+				st.values.push("")
+				return id
 			}
-			node = node.d.c
-			continue
+			addAllowed(st, node.w.m)
 		}
-
-		const staticChild = node.s[seg]
-		if (staticChild !== undefined) {
-			node = staticChild
-			continue
+		return undefined
+	}
+	let end = path.indexOf("/", pos)
+	if (end === -1) end = len
+	const seg = path.substring(pos, end)
+
+	const staticChild = node.s[seg]
+	if (staticChild !== undefined) {
+		const id = walk(staticChild, end, st)
+		if (id !== undefined) return id
+	}
+	if (node.d !== null) {
+		const depth = st.names.length
+		st.names.push(node.d.n)
+		st.values.push(decode(seg))
+		const id = walk(node.d.c, end, st)
+		if (id !== undefined) return id
+		st.names.length = depth
+		st.values.length = depth
+	}
+	if (node.w !== null) {
+		const id = pickMethod(node.w.m, st.method)
+		if (id !== undefined) {
+			st.names.push(node.w.n)
+			st.values.push(decode(path.substring(pos)))
+			return id
 		}
-		const nextNode = createNode()
-		node.s[seg] = nextNode
-		node = nextNode
+		addAllowed(st, node.w.m)
 	}
+	return undefined
+}
 
-	if (node.ws !== null) {
-		throw new Error(`Duplicate WebSocket route: ${path}`)
+function buildParams(st: MatchState): Record<string, string> {
+	const params = dict<string>()
+	for (let i = 0; i < st.names.length; i++) params[st.names[i]] = st.values[i]
+	return params
+}
+
+export function matchRoute(root: TreeNode, method: HttpMethod | string, path: string): MatchResult {
+	const st: MatchState = { allowed: null, method, names: [], path, values: [] }
+	const id = walk(root, 0, st)
+	if (id !== undefined) return { id, matched: true, params: buildParams(st) }
+	if (st.allowed !== null && st.allowed.size > 0) {
+		return { allowed: [...st.allowed] as HttpMethod[], matched: false }
 	}
-	node.ws = handler
+	return null
 }
 
-export function matchWsRoute(
-	root: TreeNode,
-	path: string,
-): { handler: WSRouteHandler; params: Record<string, string> } | null {
-	let node = root
-	const params: Record<string, string> = Object.create(null)
+function walkWs(node: TreeNode, pos: number, st: MatchState): RouteId | undefined {
+	const path = st.path
 	const len = path.length
+	while (pos < len && path.charCodeAt(pos) === 47) pos++
+	if (pos >= len) return node.ws ?? undefined
+	let end = path.indexOf("/", pos)
+	if (end === -1) end = len
+	const seg = path.substring(pos, end)
+	const staticChild = node.s[seg]
+	if (staticChild !== undefined) {
+		const id = walkWs(staticChild, end, st)
+		if (id !== undefined) return id
+	}
+	if (node.d !== null) {
+		const depth = st.names.length
+		st.names.push(node.d.n)
+		st.values.push(decode(seg))
+		const id = walkWs(node.d.c, end, st)
+		if (id !== undefined) return id
+		st.names.length = depth
+		st.values.length = depth
+	}
+	return undefined
+}
 
-	let pos = path.charCodeAt(0) === 47 ? 1 : 0
+export function matchWsRoute(root: TreeNode, path: string): { id: RouteId; params: Record<string, string> } | null {
+	const st: MatchState = { allowed: null, method: "WS", names: [], path, values: [] }
+	const id = walkWs(root, 0, st)
+	if (id === undefined) return null
+	return { id, params: buildParams(st) }
+}
 
-	while (pos < len) {
-		let end = pos
-		while (end < len && path.charCodeAt(end) !== 47) end++
-		if (end === pos) {
-			pos++
-			continue
-		}
-		const seg = path.substring(pos, end)
-		pos = end + 1
+/** True when the tree holds at least one websocket leaf. */
+export function hasWsLeaf(node: TreeNode): boolean {
+	if (node.ws !== null) return true
+	for (const k in node.s) if (hasWsLeaf(node.s[k])) return true
+	return node.d !== null && hasWsLeaf(node.d.c)
+}
 
-		const staticChild = node.s[seg]
-		if (staticChild !== undefined) {
-			node = staticChild
-			continue
-		}
+/** Every leaf, with its concrete path pattern (optional params already expanded by insertion). */
+export function forEachLeaf(
+	node: TreeNode,
+	cb: (method: string, path: string, id: RouteId) => void,
+	prefix = "",
+): void {
+	if (node.m !== null) for (const method in node.m) cb(method, prefix || "/", node.m[method])
+	if (node.ws !== null) cb("WS", prefix || "/", node.ws)
+	for (const seg in node.s) forEachLeaf(node.s[seg], cb, `${prefix}/${seg}`)
+	if (node.d !== null) forEachLeaf(node.d.c, cb, `${prefix}/:${node.d.n}`)
+	if (node.w !== null) {
+		const w = node.w.n === "*" ? "*" : `*${node.w.n}`
+		for (const method in node.w.m) cb(method, `${prefix}/${w}`, node.w.m[method])
+	}
+}
 
-		if (node.d !== null) {
-			params[node.d.n] = decode(seg)
-			node = node.d.c
-			continue
-		}
+/** Deep copy into fresh null-prototype nodes. */
+export function cloneTree(node: TreeNode): TreeNode {
+	const out = createNode()
+	for (const seg in node.s) out.s[seg] = cloneTree(node.s[seg])
+	if (node.m !== null) out.m = Object.assign(dict<RouteId>(), node.m)
+	if (node.d !== null) out.d = { c: cloneTree(node.d.c), n: node.d.n }
+	if (node.w !== null) out.w = { m: Object.assign(dict<RouteId>(), node.w.m), n: node.w.n }
+	out.ws = node.ws
+	return out
+}
 
-		return null
+/** Deep-freeze a loaded tree so no app can mutate a module other apps also import. */
+export function freezeTree(node: TreeNode): TreeNode {
+	if (Object.isFrozen(node)) return node
+	for (const seg in node.s) freezeTree(node.s[seg])
+	Object.freeze(node.s)
+	if (node.m !== null) Object.freeze(node.m)
+	if (node.d !== null) {
+		freezeTree(node.d.c)
+		Object.freeze(node.d)
 	}
-
-	if (node.ws !== null) {
-		return { handler: node.ws, params }
+	if (node.w !== null) {
+		Object.freeze(node.w.m)
+		Object.freeze(node.w)
 	}
-
-	return null
+	return Object.freeze(node)
 }
 
-function mergeNodes(target: TreeNode, source: TreeNode, path: string): void {
-	/* merge method handlers */
-	if (source.m !== null && source.m !== undefined) {
-		if (target.m === null || target.m === undefined) {
-			target.m = Object.create(null) as Record<HttpMethod | "ALL", RouteHandler>
-		}
-		for (const [method, handler] of Object.entries(source.m)) {
-			const prev = target.m[method as HttpMethod | "ALL"]
-			if (prev !== undefined) {
-				if (prev._skip && handler._skip) continue
-				throw new Error(`Merge conflict: duplicate ${method} ${path}`)
-			}
-			target.m[method as HttpMethod | "ALL"] = handler
+/**
+ * Reject a tree whose leaves are not route ids — a `routes.gen.ts` written by an older honey
+ * holds handler objects there.
+ */
+export function assertTreeFormat(tree: { root?: unknown; routes?: unknown; v?: unknown }): void {
+	const stale = (): never => {
+		throw new Error(
+			"routeTree(): this route tree was generated by an older honey (leaves are handler objects, not route ids). Run `honey generate`.",
+		)
+	}
+	if (tree === null || typeof tree !== "object" || tree.root === null || typeof tree.root !== "object") stale()
+	if (tree.routes === null || typeof tree.routes !== "object") stale()
+	const check = (node: TreeNode): void => {
+		if (node.m !== null && typeof node.m === "object")
+			for (const k in node.m) if (typeof node.m[k] !== "string") stale()
+		if (node.w !== null && typeof node.w === "object") {
+			for (const k in node.w.m) if (typeof node.w.m[k] !== "string") stale()
 		}
+		if (node.ws !== null && node.ws !== undefined && typeof node.ws !== "string") stale()
+		if (node.s === null || typeof node.s !== "object") stale()
+		for (const seg in node.s) check(node.s[seg])
+		if (node.d !== null && node.d !== undefined) check(node.d.c)
 	}
+	check(tree.root as TreeNode)
+}
 
-	/* merge static children — shallow-copy s to avoid mutating shared empty objects */
-	if (source.s && Object.keys(source.s).length > 0) {
-		let detached = false
-		for (const [seg, child] of Object.entries(source.s)) {
-			const targetChild = target.s[seg]
-			if (targetChild !== undefined) {
-				mergeNodes(targetChild, child, `${path}/${seg}`)
-			} else {
-				if (!detached) {
-					target.s = Object.assign(Object.create(null) as Record<string, TreeNode>, target.s)
-					detached = true
-				}
-				target.s[seg] = child
-			}
-		}
+function mergeMethodMap(
+	target: Record<string, RouteId>,
+	source: Record<string, RouteId>,
+	path: string,
+): Record<string, RouteId> {
+	for (const method in source) {
+		if (target[method] !== undefined) throw new Error(`Merge conflict: duplicate ${method} ${path}`)
+		target[method] = source[method]
 	}
+	return target
+}
 
-	/* merge dynamic param */
-	if (source.d !== null && source.d !== undefined) {
-		if (target.d !== null && target.d !== undefined) {
+function mergeNodes(target: TreeNode, source: TreeNode, path: string): void {
+	if (source.m !== null) {
+		if (target.m === null) target.m = dict<RouteId>()
+		mergeMethodMap(target.m, source.m, path || "/")
+	}
+	for (const seg in source.s) {
+		const child = source.s[seg]
+		const existing = target.s[seg]
+		if (existing !== undefined) mergeNodes(existing, child, `${path}/${seg}`)
+		else target.s[seg] = cloneTree(child)
+	}
+	if (source.d !== null) {
+		if (target.d !== null) {
 			if (target.d.n !== source.d.n) {
 				throw new Error(`Merge conflict: param name mismatch at ${path}: "${target.d.n}" vs "${source.d.n}"`)
 			}
 			mergeNodes(target.d.c, source.d.c, `${path}/:${target.d.n}`)
 		} else {
-			target.d = source.d
+			target.d = { c: cloneTree(source.d.c), n: source.d.n }
 		}
 	}
-
-	/* merge wildcard */
-	if (source.w !== null && source.w !== undefined) {
-		if (target.w !== null && target.w !== undefined) {
+	if (source.w !== null) {
+		if (target.w !== null) {
 			if (target.w.n !== source.w.n) {
 				throw new Error(`Merge conflict: wildcard name mismatch at ${path}: "${target.w.n}" vs "${source.w.n}"`)
 			}
-			for (const [method, handler] of Object.entries(source.w.m)) {
-				if (method in target.w.m) {
-					throw new Error(`Merge conflict: duplicate ${method} ${path}/*${target.w.n}`)
-				}
-				target.w.m[method as HttpMethod | "ALL"] = handler
-			}
+			mergeMethodMap(target.w.m, source.w.m, `${path}/*${target.w.n}`)
 		} else {
-			target.w = source.w
+			target.w = { m: Object.assign(dict<RouteId>(), source.w.m), n: source.w.n }
 		}
 	}
-
-	/* merge websocket */
-	if (source.ws !== null && source.ws !== undefined) {
-		if (target.ws !== null && target.ws !== undefined) {
-			throw new Error(`Merge conflict: duplicate WebSocket handler at ${path}`)
-		}
+	if (source.ws !== null) {
+		if (target.ws !== null) throw new Error(`Merge conflict: duplicate WebSocket handler at ${path || "/"}`)
 		target.ws = source.ws
 	}
 }
 
-function withSchemas(
-	target: Record<HttpMethod | "ALL", RouteHandler>,
-	source: Record<HttpMethod | "ALL", RouteHandler>,
-): Record<HttpMethod | "ALL", RouteHandler> {
-	let next = target
-	for (const [method, handler] of Object.entries(target) as Array<[HttpMethod | "ALL", RouteHandler]>) {
-		const from = source[method]
-		if (from === undefined) continue
-		const iv = handler.iv ?? from.iv
-		const os = handler.os ?? from.os
-		if (iv === handler.iv && os === handler.os) continue
-		/* intern trees share handler objects across routes — copy instead of mutating */
-		if (next === target) next = { ...target }
-		next[method] = { ...handler, iv, os }
-	}
-	return next
-}
-
-/**
- * Copy input/output schemas from `source` onto matching routes in `target` that lack them.
- * Generate-time only: a gateway app serves an intern tree (no schemas) while its merge source
- * (`mergeTree` over downstream `app.toRouteTree()`) still carries them for OpenAPI.
- */
-export function overlaySchemas(target: TreeNode, source: TreeNode): void {
-	if (target.m !== null && source.m !== null) target.m = withSchemas(target.m, source.m)
-	if (target.w !== null && source.w !== null) target.w = { ...target.w, m: withSchemas(target.w.m, source.w.m) }
-	for (const [seg, child] of Object.entries(target.s)) {
-		const from = source.s[seg]
-		if (from !== undefined) overlaySchemas(child, from)
-	}
-	if (target.d !== null && source.d !== null) overlaySchemas(target.d.c, source.d.c)
-}
-
-/** Merge source tree nodes into target tree (mutates target) */
+/** Merge `source` topology into `target` (mutates target; never shares source nodes). */
 export function mergeInto(target: TreeNode, source: TreeNode): void {
-	bumpGeneration(target)
 	mergeNodes(target, source, "")
 }
 
 type TreeInput = RouteTree | [RouteTree, Record<string, unknown>]
 
-function tagHandlerMeta(node: TreeNode, extra: Record<string, unknown>): void {
-	if (node.m !== null) {
-		for (const handler of Object.values(node.m) as RouteHandler[]) {
-			handler.mt = handler.mt ? { ...handler.mt, ...extra } : { ...extra }
-		}
-	}
-	for (const child of Object.values(node.s)) {
-		tagHandlerMeta(child, extra)
-	}
-	if (node.d) tagHandlerMeta(node.d.c, extra)
-	if (node.w !== null) {
-		for (const handler of Object.values(node.w.m) as RouteHandler[]) {
-			handler.mt = handler.mt ? { ...handler.mt, ...extra } : { ...extra }
-		}
-	}
+function withExtraMeta(entry: RouteEntry, extra: Record<string, unknown> | undefined): RouteEntry {
+	if (extra === undefined) return { ...entry }
+	const mt = Object.freeze(entry.mt ? { ...entry.mt, ...extra } : { ...extra })
+	const out: RouteEntry = { ...entry, mt }
+	if (entry.h !== undefined) out.h = { ...entry.h, mt } as RouteHandler
+	return out
 }
 
+/**
+ * Merge several trees into a new one. Inputs are never mutated; extra meta given per tree is
+ * applied to copies of its route entries.
+ */
 export function mergeTree(...trees: TreeInput[]): RouteTree {
-	const merged: RouteTree = {
-		meta: {},
-		root: createNode(),
-	}
-
-	for (const entry of trees) {
-		const [tree, extra] = Array.isArray(entry) ? entry : [entry, undefined]
-		if (extra) tagHandlerMeta(tree.root, extra)
+	const merged: RouteTree = { meta: {}, root: createNode(), routes: dict<RouteEntry>(), v: ROUTE_TREE_VERSION }
+	for (const input of trees) {
+		const [tree, extra] = Array.isArray(input) ? input : [input, undefined]
+		assertTreeFormat(tree)
 		mergeNodes(merged.root, tree.root, "")
+		for (const id in tree.routes) {
+			if (id in merged.routes) throw new Error(`Merge conflict: duplicate ${id}`)
+			merged.routes[id] = withExtraMeta(tree.routes[id], extra)
+		}
 		Object.assign(merged.meta, tree.meta)
 	}
-
 	return merged
 }
+
+/**
+ * Copy input/output schemas from `source` onto `target`'s routes that lack them.
+ * Generate-time only: a gateway app serves its generated tree (no schemas) while its merge
+ * source (`mergeTree` over downstream `app.toRouteTree()`) still carries them for OpenAPI.
+ */
+export function overlaySchemas(target: { _overlaySchemas(source: RouteTree): void }, source: RouteTree): void {
+	target._overlaySchemas(source)
+}