@lovrozagar/honey 0.7.2 → 1.0.0-rc.1

package/dist/index.js

@@ -1,2365 +1,14 @@
-import { bodyKind, headResponse, isProducedStream, rawBodyOf } from "./body-kind.js";
-import { clientInfo, HoneyContext } from "./context.js";
-import { dict } from "./dict.js";
-import { normalizePath, pathOfUrl, searchOfUrl } from "./request-path.js";
-import { BUN_URL_FROM_HOST, hasValidHost, TRUST_OFF } from "./client-info.js";
-import { loadFeature, requireFeature } from "./feature-slots.js";
-import { HoneyError } from "./error.js";
-import { ERROR_META } from "./errors.js";
-import { collectMiddlewareMeta, compileChain, RESERVED_CTX_KEYS } from "./middleware.js";
-import { createErrorResponse } from "./response.js";
-import { canonical, expandOptional, isStaticPattern, joinPatterns, normalizePattern, parsePattern, pathInScope, routeId, scopeCoverage, splitRouteId, } from "./pattern.js";
-import { assertTreeFormat, cloneTree, createNode, findLeaf, forEachLeaf, freezeTree, hasWsLeaf, insertLeaf, matchRoute, matchWsRoute, ROUTE_TREE_VERSION, } from "./tree.js";
-import { codeToStatusKey, EK, EMPTY_OBJ, SK } from "./types.js";
-import { assertBodySchemaAllowed, assertRequestContentType, validateInput, validateOutput } from "./validation.js";
-import { validateOriginPolicy } from "./ws-origin.js";
-import { loadHoneyFeature } from "./feature-load.js";
-import { getI18nRuntime } from "./i18n-slot.js";
-import { bindInternalHandler, epochCached, getOpenApiRuntime } from "./openapi/spec-factory.js";
-import { getServeRuntime, isCodegenProcess } from "./serve-slot.js";
-export { clientInfo, HoneyContext } from "./context.js";
-export { toFetchRequest } from "./fetch-request.js";
-export { HoneyError } from "./error.js";
-export { defineErrors, ERROR_META } from "./errors.js";
-export { createMiddleware, defineMiddleware } from "./middleware.js";
-export { createErrorResponse, HoneyRes } from "./response.js";
-export { mergeTree } from "./tree.js";
-export { detectRuntime } from "./detect-runtime.js";
-function createSettings() {
-    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, path) {
-    return joinPatterns(base, path);
-}
-function createGraph() {
-    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(),
-        unloadIfStale: false,
-        wsRecords: new Map(),
-    };
-}
-/** Fresh copy of a record for another graph — sources are copied, resolved fields recomputed there. */
-function copyRecord(r) {
-    const out = { ...r, ek: new Set(r.ek) };
-    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.ca;
-    return out;
-}
-/** Every leaf a pattern occupies: an optional last param places two. */
-function leafVariants(segments) {
-    return expandOptional(segments);
-}
-/** Record the error behind an error response on `ctx.error` (read-only for user code). */
-function setCtxError(ctx, error) {
-    ;
-    ctx["error"] = error;
-}
-/** What `ctx.error` holds for a throw the boundary could not resolve: the 500 it became. */
-function asHoneyError(thrown) {
-    return thrown instanceof HoneyError
-        ? thrown
-        : new HoneyError({ cause: thrown, errorKey: EK.internal_server_error, status: SK.internal_server_error });
-}
-function patternOf(id) {
-    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 = () => {
-    throw new Error("honey: unserved route reached its handler");
-};
-function isRootWildcard(segments) {
-    return segments.length === 1 && segments[0].k === "wildcard";
-}
-const EMPTY_PARAMS = EMPTY_OBJ;
-function requestIsWsUpgrade(request) {
-    try {
-        return request.headers.get("upgrade")?.toLowerCase() === "websocket";
-    }
-    catch {
-        /* Deno closes the Request after upgradeWebSocket */
-        return false;
-    }
-}
-/** The info object `Deno.serve` passes as the second handler argument. */
-function isDenoServeInfo(env) {
-    return env !== null && typeof env === "object" && env.remoteAddr !== undefined;
-}
-/** `obj[key]` for an own key only; `undefined` for inherited names such as `constructor`. */
-function safeFire(fn, logger) {
-    if (fn === undefined)
-        return;
-    try {
-        const result = fn();
-        if (result && typeof result === "object" && "catch" in result) {
-            ;
-            result.catch((e) => {
-                logger?.warn?.({ err: e }, "telemetry callback failed");
-            });
-        }
-    }
-    catch (e) {
-        logger?.warn?.({ err: e }, "telemetry callback failed");
-    }
-}
-function requestWithHeaders(req, headers) {
-    return new Proxy(req, {
-        get(target, prop) {
-            if (prop === "headers")
-                return headers;
-            const value = Reflect.get(target, prop, target);
-            return typeof value === "function" ? value.bind(target) : value;
-        },
-    });
-}
-function ctxRequest(fc) {
-    if (!fc.headerSnap)
-        return fc.request;
-    try {
-        void fc.request.headers.get("upgrade");
-        return fc.request;
-    }
-    catch {
-        return requestWithHeaders(fc.request, fc.headerSnap);
-    }
-}
-function defaultErrorFormatter(_error, defaultShape) {
-    return defaultShape;
-}
-/* errorKeys the framework throws on its own behalf — input/output validation, content negotiation,
- * routing, and the shipped middleware. Always passes the boundary check; users never declare these via .errors(). */
-const FRAMEWORK_EKS = new Set([
-    EK.validation_failed,
-    EK.output_validation_failed,
-    EK.output_content_type_mismatch,
-    EK.unsupported_media_type,
-    EK.content_too_large,
-    EK.method_not_allowed,
-    EK.not_found,
-    EK.too_many_requests,
-    EK.request_timeout,
-    EK.gateway_timeout,
-    EK.bad_gateway,
-    EK.forbidden,
-    EK.bad_request,
-    EK.malformed_body,
-]);
-function shouldValidateOutput(mode) {
-    if (mode === "always")
-        return true;
-    if (mode === "off")
-        return false;
-    return globalThis.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, mw) {
-    const guard = (ctx, next) => (pathInScope(ctx["path"], segs) ? mw(ctx, next) : next());
-    Object.defineProperty(guard, "name", { configurable: true, value: mw.name });
-    const tagged = mw;
-    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, onMw, log) {
-    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) {
-    return mw.errors;
-}
-/** Longest run of middleware every record starts its chain with — what 404 and 405 run. */
-function commonPrefix(chains) {
-    if (chains.length === 0)
-        return [];
-    let out = [...chains[0]];
-    for (let i = 1; i < chains.length && out.length > 0; i++) {
-        const c = chains[i];
-        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) {
-    return mw.name ? `"${mw.name}"` : "an anonymous middleware";
-}
-export class Honey {
-    /* view state — what routes registered through this handle capture */
-    _basePath;
-    _chain;
-    _chainMeta;
-    _contextValues;
-    _graph;
-    /** the `use(mw)` call that created this chain — null on the root handle */
-    _node;
-    constructor(opts) {
-        this._basePath = "/";
-        this._chain = [];
-        this._chainMeta = null;
-        this._contextValues = null;
-        this._graph = opts?.graph ?? createGraph();
-        this._node = null;
-    }
-    get _s() {
-        return this._graph.settings;
-    }
-    /**
-     * @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.
-     */
-    get _metaSpecSource() {
-        return { absorbed: this._graph.absorbedMetaSpecs, declared: this._graph.metaSpec };
-    }
-    /** @internal — read by codegen and OpenAPI */
-    get _errorFactory() {
-        return this._graph.settings.errorFactory;
-    }
-    set _errorFactory(factory) {
-        this._graph.settings.errorFactory = factory;
-        this._bumpEpoch();
-    }
-    /** @internal — read by OpenAPI */
-    get _errorSchema() {
-        return this._graph.settings.errorSchema;
-    }
-    /** @internal — read by OpenAPI */
-    get _customErrorSchema() {
-        return this._graph.settings.customErrorSchema;
-    }
-    get _root() {
-        return this._graph.root;
-    }
-    get _realtimeBus() {
-        return this._graph.realtimeBus;
-    }
-    /** A new handle on the same graph, carrying this handle's view. */
-    _derive(chain = this._chain) {
-        const next = new Honey({ graph: this._graph });
-        next._basePath = this._basePath;
-        next._chain = chain;
-        next._chainMeta = this._chainMeta;
-        next._contextValues = this._contextValues;
-        next._node = this._node;
-        return next;
-    }
-    /** This handle registers, mounts or serves — every `use()` on its way here is in use. */
-    _markUsed() {
-        let node = this._node;
-        while (node !== null && !node.used) {
-            node.used = true;
-            node = node.parent;
-        }
-    }
-    /** @internal — used by RouteBuilder for pre-filtered error factory */
-    get _factory() {
-        return this._graph.settings.errorFactory;
-    }
-    /** @internal — used by runtime error boundary */
-    get _boundaryKey() {
-        return this._graph.settings.defaultBoundaryKey;
-    }
-    /** Convert an unknown thrown value to a plain error Response — no boundary, no onError. */
-    _toErrorResponse(thrown) {
-        const error = thrown instanceof HoneyError
-            ? thrown
-            : new HoneyError({
-                cause: thrown,
-                errorKey: EK.internal_server_error,
-                status: SK.internal_server_error,
-            });
-        const s = this._s;
-        return createErrorResponse(error, s.errorFormatter, s.customErrorFormatter);
-    }
-    _createBoundaryError(errorKey, cause, fac) {
-        const factory = fac;
-        const factoryFn = factory?.[errorKey];
-        if (factoryFn) {
-            /* check if this is a custom schema error via ERROR_META — boundary must use standard errors only */
-            const meta = factory?.[ERROR_META];
-            if (meta?.[errorKey]?.schema) {
-                /* custom schema error — cannot be used as boundary, fall through to manual construction */
-            }
-            else {
-                return factoryFn({ cause });
-            }
-        }
-        return new HoneyError({
-            cause,
-            errorKey,
-            status: SK.internal_server_error,
-        });
-    }
-    _createError(errorKey, statusKey) {
-        const factory = this._s.errorFactory;
-        const factoryFn = factory?.[errorKey];
-        if (factoryFn) {
-            return factoryFn();
-        }
-        return new HoneyError({ errorKey, status: statusKey });
-    }
-    /**
-     * 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.
-     */
-    async _resolveI18n(honeyError, ctx, env, request, log) {
-        const i18n = this._s.errorI18n;
-        if (!i18n)
-            return honeyError;
-        try {
-            const locale = await i18n.resolveLocale({
-                cookies: ctx.cookies,
-                env,
-                headers: ctx.headers,
-                params: ctx.params,
-                req: request,
-                search: ctx.search,
-            });
-            await loadHoneyFeature("i18n");
-            return getI18nRuntime().translateError(honeyError, i18n, locale);
-        }
-        catch (e) {
-            log?.warn?.({ err: e }, "i18n resolution failed");
-            return honeyError;
-        }
-    }
-    /**
-     * 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.
-     */
-    _convertError(thrown, ctx) {
-        const fc = ctx._rq;
-        const plan = fc?.plan;
-        if (fc === null || fc === undefined || plan === null || plan === undefined) {
-            setCtxError(ctx, asHoneyError(thrown));
-            return this._safeErrorResponse(thrown);
-        }
-        const fallback = (e) => {
-            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) {
-            return fallback(e);
-        }
-    }
-    /** Last resort when even the configured formatter throws. */
-    _safeErrorResponse(thrown) {
-        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, the onError callback, and error telemetry. `onResponse` telemetry is not
-     * fired here: the request fires it exactly once, on the way out.
-     */
-    async _resolveErrorResponse(thrown, plan, fc, ctx) {
-        const { env, log, request, startTime, method, path } = fc;
-        const s = this._s;
-        const record = plan.r;
-        const fac = (record.fac ?? null);
-        let honeyError;
-        const boundaryKey = record.bek;
-        if (thrown instanceof HoneyError) {
-            /* framework-managed errorKeys (input/output validation, content negotiation, etc.) are always allowed
-             * 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 {
-            honeyError = boundaryKey
-                ? this._createBoundaryError(boundaryKey, thrown, fac)
-                : new HoneyError({ cause: thrown, errorKey: EK.internal_server_error, status: SK.internal_server_error });
-        }
-        honeyError = await this._resolveI18n(honeyError, ctx, env, request, log);
-        if (s.onError) {
-            try {
-                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 the default response path */
-                    honeyError = await this._resolveI18n(customResult, ctx, env, request, log);
-                }
-                else if (customResult) {
-                    safeFire(() => 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 (e) {
-                log?.warn?.({ err: e }, "onError failed");
-            }
-        }
-        safeFire(() => s.telemetry?.onError?.({ duration: performance.now() - startTime, error: honeyError, method, path }), log);
-        setCtxError(ctx, honeyError);
-        ctx._isErrorResponse = true;
-        return this._makeErrorCtx(fc).jsonFromError(honeyError);
-    }
-    basePath(prefix) {
-        const next = this._derive();
-        next._basePath = mergePath(this._basePath, prefix);
-        return next;
-    }
-    context(values) {
-        for (const key in values) {
-            if (RESERVED_CTX_KEYS.has(key)) {
-                throw new Error(`context() cannot set reserved key "${key}"`);
-            }
-        }
-        const next = this._derive();
-        next._contextValues = this._contextValues ? { ...this._contextValues, ...values } : { ...values };
-        return next;
-    }
-    logger(logger) {
-        this._s.logger = logger;
-        return this;
-    }
-    outputValidation(mode) {
-        this._s.outputValidation = mode;
-        this._bumpEpoch();
-        return 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) {
-        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) {
-        this._s.trust =
-            value === false || value === 0 ? TRUST_OFF : requireFeature("trust", "app.trustProxy()").compileTrust(value);
-        return this;
-    }
-    /** Strip a URL path prefix before route matching — boundary-safe (won't strip partial segments), paths without the prefix pass through unchanged */
-    stripPrefix(prefix) {
-        let normalized = prefix.replace(/\/+$/, "");
-        if (normalized.length > 0 && normalized.charCodeAt(0) !== 47) {
-            normalized = `/${normalized}`;
-        }
-        this._s.stripPrefix = normalized === "" || normalized === "/" ? null : normalized;
-        return 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) {
-        if (options.enabled === false)
-            return this;
-        const stem = options.path ?? "/openapi";
-        const epochOf = () => 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 docs = options.docs;
-            const specPath = mergePath(this._basePath, jsonPath);
-            const ui = async (ctx) => {
-                await loadHoneyFeature("openapi");
-                /* 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);
-            };
-            /* without an explicit docsPath, a user route at /docs moves the UI to /reference */
-            const candidates = options.docsPath ? [options.docsPath] : ["/docs", "/reference"];
-            let mounted = "user";
-            let tried = candidates[0];
-            for (const p of candidates) {
-                tried = p;
-                mounted = this._mountInternalGet(p, ui);
-                if (mounted !== "user")
-                    break;
-            }
-            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;
-    }
-    /**
-     * 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) {
-        if (options?.enabled === false)
-            return this;
-        const epochOf = () => 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. */
-    _mountArtifact(owner, path, load) {
-        const result = this._mountInternalGet(path, async (ctx) => {
-            const c = ctx;
-            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) {
-        await loadHoneyFeature("serve");
-        return getServeRuntime()(this, options);
-    }
-    /**
-     * 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.
-     */
-    _mountInternalGet(path, fn) {
-        const fullPath = mergePath(this._basePath, path);
-        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 = {
-            _skip: true,
-            bek: null,
-            cm: [...this._chain],
-            cv: this._contextValues,
-            dk: new Set(),
-            ek: new Set(),
-            fn: (ctx) => fn(ctx),
-            iv: null,
-            mt: null,
-            mw: [],
-            os: null,
-            ov: null,
-            own: g.settings,
-            rb: null,
-            rm: [],
-            xm: null,
-        };
-        this._markUsed();
-        this._addRoute("GET", segments, routeHandler);
-        return "mounted";
-    }
-    _bumpEpoch() {
-        this._graph.epoch++;
-    }
-    /** Place `id` at every leaf of `segments`, copying a shared (loaded) root first. */
-    _placeLeaves(segments, method, id) {
-        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;
-        }
-        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, segments, record) {
-        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, record) {
-        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() {
-        const g = this._graph;
-        if (g.final !== null && g.final.epoch === g.epoch)
-            return g.final;
-        this._assertNothingDiscarded();
-        const byId = new Map();
-        const wsById = new Map();
-        for (const [id, r] of g.records)
-            byId.set(id, r);
-        for (const [id, r] of g.wsRecords)
-            wsById.set(id, r);
-        const problems = [];
-        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);
-                        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);
-                    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) {
-            /* generation rewrites this file from the registered routes; serving it stale is the error */
-            if (g.unloadIfStale) {
-                this._unloadTree();
-                return this._finalize();
-            }
-            throw new Error(`Route tree out of date — regenerate it (\`honey generate\`):\n  ${problems.join("\n  ")}`);
-        }
-        const convert = (thrown, ctx) => this._convertError(thrown, ctx);
-        const plans = new Map();
-        const wsPlans = new Map();
-        const statics = Object.create(null);
-        const userChains = [];
-        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()`. */
-    _assertNothingDiscarded() {
-        const g = this._graph;
-        const problems = [];
-        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.
-     */
-    _resolve(r, everyScope = false) {
-        const s = this._graph.settings;
-        const own = r.own ?? s;
-        const src = own.errorFactory !== null ? own : s;
-        const segments = parsePattern(r.rp ?? "/");
-        const scoped = [];
-        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(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 = fac;
-        if (fac !== null && enf) {
-            const subset = Object.create(null);
-            for (const key of ek) {
-                if (key in fac)
-                    subset[key] = fac[key];
-            }
-            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. */
-    _timed(chain) {
-        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));
-    }
-    _planRoute(r, convert) {
-        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"], ctx["params"], ctx).then((validated) => {
-                ctx["input"] = validated;
-                return next();
-            }));
-        }
-        const fn = r.fn;
-        const handler = 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, v))
-                    : this._validateOutput(r, ctx, res);
-            }
-            : fn;
-        return {
-            cv: r.cv ?? null,
-            enf,
-            pf: null,
-            pfChain: base,
-            r,
-            rt: null,
-            run: compileChain(chain, handler, convert),
-            taps,
-        };
-    }
-    _planWs(r, convert) {
-        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"], ctx["params"], ctx).then((validated) => {
-                ctx["input"] = validated;
-                return next();
-            }));
-        }
-        const terminal = rt !== null
-            ? (ctx) => this._realtimeUpgrade(ctx, rt)
-            : (ctx) => this._wsUpgrade(ctx);
-        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.
-     */
-    _planMiss(prefix, convert) {
-        const r = {
-            bek: null,
-            cm: prefix,
-            dk: new Set(),
-            ek: new Set(),
-            fn: (ctx) => {
-                const fc = ctx._rq;
-                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, 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) {
-        const final = this._finalize();
-        const out = [];
-        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() {
-        const final = this._finalize();
-        const out = [];
-        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() {
-        return this._graph.epoch;
-    }
-    defaultErrorFormatter(schemaOrFn, maybeFn) {
-        const s = this._s;
-        if (typeof schemaOrFn === "function") {
-            s.errorSchema = null;
-            s.errorFormatter = schemaOrFn;
-        }
-        else {
-            s.errorSchema = schemaOrFn;
-            const mapper = maybeFn;
-            s.errorFormatter = (error) => mapper(error);
-        }
-        return this;
-    }
-    customErrorFormatter(schemaOrFn, maybeFn) {
-        const s = this._s;
-        if (typeof schemaOrFn === "function") {
-            s.customErrorSchema = null;
-            s.customErrorFormatter = schemaOrFn;
-        }
-        else {
-            s.customErrorSchema = schemaOrFn;
-            const mapper = maybeFn;
-            s.customErrorFormatter = (error, data) => mapper(error, data);
-        }
-        return this;
-    }
-    errorI18n(config) {
-        this._s.errorI18n = config;
-        return this;
-    }
-    onError(handler) {
-        this._s.onError = handler;
-        return this;
-    }
-    onMethodNotAllowed(handler) {
-        this._s.onMethodNotAllowed = handler;
-        return this;
-    }
-    onNotFound(handler) {
-        this._s.onNotFound = handler;
-        return this;
-    }
-    /** Register a tap handler keyed by name — fires after successful handler response */
-    tap(key, handler) {
-        const s = this._s;
-        if (s.taps === null)
-            s.taps = new Map();
-        s.taps.set(key, handler);
-        this._bumpEpoch();
-        return 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) {
-        /* `honey generate` loads the app that imports the very file it is about to rewrite: a tree
-           from an older honey is ignored there, and the routes the app registers are used instead */
-        const generating = isCodegenProcess();
-        if (generating) {
-            try {
-                assertTreeFormat(tree);
-            }
-            catch {
-                return this;
-            }
-        }
-        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();
-        g.unloadIfStale = generating;
-        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);
-            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() {
-        this._markUsed();
-        const final = this._finalize();
-        const routes = Object.create(null);
-        const keep = new Set();
-        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. */
-    _bake(r) {
-        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) {
-        const g = this._graph;
-        for (const [id, entry] of Object.entries(source.routes)) {
-            const iv = entry.iv ?? entry.h?.iv ?? null;
-            const os = entry.os ?? entry.h?.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) {
-        assertTreeFormat(source);
-        const g = this._graph;
-        const root = cloneTree(source.root);
-        const routes = dict();
-        for (const id of Object.keys(source.routes)) {
-            const { bek, ek, i, mt } = source.routes[id];
-            routes[id] = { bek, ek, i, mt };
-        }
-        const own = [];
-        /* every route id this app serves, root wildcards included */
-        const served = new Set();
-        for (const r of [...g.records.values(), ...g.catchAll.values(), ...g.wsRecords.values()]) {
-            if (r._skip === true)
-                continue;
-            const id = r.id;
-            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 = { meta: { ...source.meta }, root, routes, v: ROUTE_TREE_VERSION };
-        this._replaceLoadedTree(tree);
-        return tree;
-    }
-    /** @internal — drop the loaded tree and route by the registered routes alone. */
-    _unloadTree() {
-        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.unloadIfStale = false;
-        g.root = createNode();
-        g.rootShared = false;
-        g.hasWs = false;
-        for (const r of http) {
-            delete r.ca;
-            const { method, segments } = patternOf(r.id);
-            this._addRoute(method, segments, r);
-        }
-        for (const r of ws)
-            this._addWsRoute(patternOf(r.id).segments, r);
-        this._bumpEpoch();
-    }
-    /** @internal — swap the loaded tree, re-binding every registered route to it. */
-    _replaceLoadedTree(tree) {
-        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);
-            this._addRoute(method, segments, r);
-        }
-        for (const r of ws)
-            this._addWsRoute(patternOf(r.id).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(factory) {
-        this._s.errorFactory = factory;
-        this._bumpEpoch();
-        return this;
-    }
-    /** Error keys every route of this app declares — applies to routes registered before and after the call. */
-    defaultErrors(...keys) {
-        for (const k of keys)
-            this._s.defaultErrorKeys.add(k);
-        this._bumpEpoch();
-        return this;
-    }
-    defaultBoundary(key) {
-        this._s.defaultBoundaryKey = key;
-        this._s.defaultErrorKeys.add(key);
-        this._bumpEpoch();
-        return this;
-    }
-    meta(values) {
-        if (values === undefined) {
-            /* phantom overload — type-only, no runtime effect */
-            return this;
-        }
-        /* chain-level meta — copy-on-write */
-        const next = this._derive();
-        next._chainMeta = this._chainMeta ? { ...this._chainMeta, ...values } : { ...values };
-        return next;
-    }
-    /**
-     * Declare what flows from route meta and route schemas into the OpenAPI document.
-     * Codegen-time only — never consulted on the request path. See docs/meta-spec.md.
-     */
-    metaSpec(spec) {
-        if (this._graph.metaSpec !== null) {
-            throw new Error("metaSpec() was already declared on this app — declare the whole policy in one call");
-        }
-        this._graph.metaSpec = spec;
-        return this;
-    }
-    /** Declare tap payload types — auto-extends meta with Partial<T> for meta-driven taps */
-    taps() {
-        return this;
-    }
-    /* oxlint-disable-next-line typescript/no-explicit-any -- overload impl requires erased types */
-    use(pathOrMw, maybeMw) {
-        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;
-            const node = { 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;
-        const segs = parsePattern(prefix);
-        this._graph.scoped.push({
-            errors: errorsOf(mw) ? [...errorsOf(mw)] : undefined,
-            guard: scopeGuard(segs, mw),
-            mw,
-            prefix,
-            segs,
-        });
-        this._bumpEpoch();
-        return this._derive();
-    }
-    route(prefixOrSub, maybeSub) {
-        if (typeof prefixOrSub === "string") {
-            if (!(maybeSub instanceof Honey))
-                throw new TypeError("honey: route(prefix, sub) needs the sub-app");
-            this._markUsed();
-            this.basePath(prefixOrSub)._mount(maybeSub);
-            return this;
-        }
-        return this._mount(prefixOrSub);
-    }
-    _mount(sub) {
-        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 = (r) => {
-                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) => (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));
-            }
-            /* 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;
-                }
-                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 [subPath, cfg] of sub._graph.realtimeRoutes) {
-                const path = at(subPath);
-                if (g.realtimeRoutes.has(path)) {
-                    throw new Error(`Duplicate realtime route: ${path}`);
-                }
-                /* 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 (!g.realtimeBus && sub._graph.realtimeBus) {
-                this._setBus(sub._graph.realtimeBus);
-            }
-            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);
-                }
-            }
-            this._bumpEpoch();
-        }
-        return this;
-    }
-    _setBus(bus) {
-        const g = this._graph;
-        g.realtimeBus = bus;
-        g.realtimeCtx = requireFeature("realtime", "app.realtime()").createRealtimePublisher(bus, () => [...g.realtimeRoutes.values()].map((cfg) => cfg.namespace));
-        return bus;
-    }
-    _registerRoute(method, path, extraMethods) {
-        const fullPath = mergePath(this._basePath, path);
-        const pending = { id: `${[method, ...(extraMethods ?? [])].join(",")} ${fullPath}` };
-        this._graph.pending.add(pending);
-        return new RouteBuilder({
-            boundaryErrorKey: null,
-            errorKeys: new Set(),
-            extraMethods: extraMethods ?? null,
-            inputSchemas: null,
-            meta: this._chainMeta ? { ...this._chainMeta } : null,
-            method,
-            middlewares: [],
-            outputSchemas: null,
-            parent: this,
-            path: fullPath,
-            pending,
-        });
-    }
-    /** @internal — set (or clear, with null) one app-wide middleware; used by `serve()` */
-    _setGlobal(key, mw) {
-        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() {
-        return { chain: this._chain, cv: this._contextValues, own: this._graph.settings };
-    }
-    /** @internal — a builder got its handler (or was abandoned on purpose) */
-    _settle(pending) {
-        this._graph.pending.delete(pending);
-        this._markUsed();
-    }
-    on(methods, path) {
-        const [first, ...rest] = methods;
-        return this._registerRoute(first, path, rest.length > 0 ? rest : undefined);
-    }
-    all(path) {
-        return this._registerRoute("ALL", path);
-    }
-    delete(path) {
-        return this._registerRoute("DELETE", path);
-    }
-    get(path) {
-        return this._registerRoute("GET", path);
-    }
-    head(path) {
-        return this._registerRoute("HEAD", path);
-    }
-    options(path) {
-        return this._registerRoute("OPTIONS", path);
-    }
-    patch(path) {
-        return this._registerRoute("PATCH", path);
-    }
-    post(path) {
-        return this._registerRoute("POST", path);
-    }
-    put(path) {
-        return this._registerRoute("PUT", path);
-    }
-    ws(path) {
-        const fullPath = mergePath(this._basePath, path);
-        const pending = { id: `WS ${fullPath}` };
-        this._graph.pending.add(pending);
-        return new WSRouteBuilder({
-            errorKeys: new Set(),
-            inputSchemas: null,
-            meta: this._chainMeta ? { ...this._chainMeta } : null,
-            middlewares: [],
-            origins: null,
-            parent: this,
-            path: fullPath,
-            pending,
-        });
-    }
-    realtime(path, opts) {
-        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}`);
-        }
-        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: [],
-            own: g.settings,
-            rb: null,
-            rm: (opts.use ?? []).map((fn) => fn),
-            rp: fullPath,
-            xm: this._chainMeta ? { ...this._chainMeta } : null,
-        });
-        return this;
-    }
-    /**
-     * Deno must call `Deno.upgradeWebSocket` in the same turn as the serve
-     * callback. When the adapter implements `preUpgrade`, we do that here
-     * and return the 101 response before any middleware Promise.
-     */
-    fetch(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 canPreUpgrade = isWsUpgrade &&
-            wsAdapter?.preUpgrade !== undefined &&
-            !this.trailingSlashRedirects(path) &&
-            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;
-        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;
-        try {
-            work = this._doFetch(request, env, executionCtx, path, isWsUpgrade === true, headerSnap);
-        }
-        catch (err) {
-            work = Promise.reject(err);
-        }
-        if (!pre)
-            return work;
-        void Promise.resolve(work)
-            .then((res) => {
-            if (res.status === 101)
-                return;
-            const code = res.status === 401 ? 4401 : 1008;
-            const reason = res.status === 401 ? "unauthorized" : "upgrade rejected";
-            const reject = () => {
-                try {
-                    pre.socket.close(code, reason);
-                }
-                catch {
-                    /* already closed */
-                }
-            };
-            if (pre.whenOpen)
-                pre.whenOpen(reject);
-            else
-                reject();
-        })
-            .catch(() => {
-            try {
-                pre.socket.close(1011, "internal error");
-            }
-            catch {
-                /* already closed */
-            }
-        });
-        return pre.response;
-    }
-    /** @internal 400 for a request path the normalization policy rejects (see `normalizePath`), or an invalid `Host`. */
-    _badRequestTarget() {
-        return this._toErrorResponse(this._createError(EK.bad_request, SK.bad_request));
-    }
-    trailingSlashRedirects(path) {
-        if (path.length <= 1)
-            return false;
-        const mode = this._graph.settings.trailingSlash;
-        if (mode === "strip" && path.endsWith("/"))
-            return true;
-        if (mode === "enforce" && !path.endsWith("/"))
-            return true;
-        return false;
-    }
-    pathAfterPrefix(path) {
-        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;
-    }
-    _doFetch(request, env, executionCtx, fullPath, knownWsUpgrade = false, headerSnap) {
-        const startTime = performance.now();
-        const final = this._finalize();
-        const s = this._graph.settings;
-        const rawUrl = request.url;
-        /* lazily create URL only when actually needed (search params, redirects) */
-        let _url;
-        const getUrl = () => {
-            if (_url === undefined)
-                _url = new URL(rawUrl);
-            return _url;
-        };
-        const log = s.logger ?? undefined;
-        const method = request.method.toUpperCase();
-        const fc = {
-            allowed: null,
-            env,
-            executionCtx,
-            headerSnap,
-            log,
-            method,
-            path: fullPath,
-            plan: null,
-            request,
-            startTime,
-            trust: s.trust,
-            url: getUrl,
-            ws: null,
-            wsUpgrade: knownWsUpgrade,
-        };
-        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));
-    }
-    _route(fc, final, fullPath, rawUrl, knownWsUpgrade) {
-        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 */
-        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 = this._matchWs(final, path);
-            if (wsMatch !== null) {
-                return this._handleWs(fc, wsMatch);
-            }
-        }
-        /* 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);
-        }
-        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 new Response("Upgrade Required", {
-                        headers: { connection: "Upgrade", upgrade: "websocket" },
-                        status: 426,
-                    });
-                }
-            }
-            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._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);
-    }
-    _matchWs(final, path) {
-        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 };
-    }
-    _dispatchRecord(fc, plan, params) {
-        const record = plan.r;
-        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, plan, params);
-    }
-    _makeErrorCtx(fc, allowed) {
-        const s = this._s;
-        return {
-            env: fc.env,
-            jsonFromError: (err) => createErrorResponse(err, s.errorFormatter, s.customErrorFormatter),
-            req: fc.request,
-            ...(allowed ? { allowed } : {}),
-        };
-    }
-    /** A request context for `plan`: route data, context values, `ctx.errors`, `ctx.realtime`. */
-    _newCtx(fc, plan, params, req) {
-        fc.plan = plan;
-        const r = plan.r;
-        const ctx = new HoneyContext({
-            env: fc.env,
-            executionCtx: fc.executionCtx,
-            meta: r.mt ?? undefined,
-            params,
-            path: fc.path,
-            req: req ?? fc.request,
-            routePattern: r.rp ?? "",
-            urlFn: fc.url,
-        });
-        if (plan.cv !== null)
-            Object.assign(ctx, plan.cv);
-        const rt = this._graph.realtimeCtx;
-        if (rt !== null)
-            ctx.realtime = rt;
-        if (r.ef)
-            ctx._setErrors(r.ef);
-        ctx._rq = fc;
-        return ctx;
-    }
-    _handleWs(fc, wsMatch) {
-        const plan = this._finalize().wsPlans.get(wsMatch.handler.id);
-        if (plan === undefined)
-            return this._handleMiss(fc, null);
-        const isUpgrade = fc.wsUpgrade === true || requestIsWsUpgrade(fc.request);
-        if (!isUpgrade) {
-            return new Response(null, {
-                headers: { upgrade: "websocket" },
-                status: 426,
-            });
-        }
-        if (!this._graph.settings.wsAdapter) {
-            fc.log?.warn?.("WebSocket adapter not configured — call .wsAdapter()");
-            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. */
-    async _wsSession(finalCtx, policy) {
-        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).host, credentialed)) {
-            throw this._createError(EK.forbidden, SK.forbidden);
-        }
-        return ws;
-    }
-    async _wsUpgrade(finalCtx) {
-        const fc = finalCtx._rq;
-        const wsMatch = fc.ws;
-        const ws = await this._wsSession(finalCtx, wsMatch.handler.og ?? null);
-        const wsAdapter = this._graph.settings.wsAdapter;
-        const handler = ws.createWsSession({
-            callbacks: wsMatch.handler.fn,
-            ctx: finalCtx,
-            log: (this._graph.settings.logger ?? null),
-            reconnectToken: fc.url().searchParams.get("reconnect_token"),
-            route: wsMatch.handler.rp,
-        });
-        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. */
-    async _realtimeUpgrade(finalCtx, config) {
-        const fc = finalCtx._rq;
-        await this._wsSession(finalCtx, config.allowedOrigins);
-        const wsAdapter = this._graph.settings.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;
-    }
-    /**
-     * 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.
-     */
-    _handleMiss(fc, allowed) {
-        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);
-    }
-    /** 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. */
-    _withOnResponse(fc, res) {
-        const s = this._graph.settings;
-        if (s.telemetry?.onResponse === undefined)
-            return res;
-        const fire = (status) => {
-            safeFire(() => s.telemetry?.onResponse?.({ duration: performance.now() - fc.startTime, req: fc.request, status }), fc.log);
-        };
-        if (!(res instanceof Promise)) {
-            fire(res.status);
-            return res;
-        }
-        return res.then((r) => {
-            fire(r.status);
-            return r;
-        }, (error) => {
-            fire(500);
-            throw error;
-        });
-    }
-    _make404(fc) {
-        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));
-    }
-    async _make405(fc, allowed) {
-        const s = this._s;
-        const res = s.onMethodNotAllowed
-            ? await s.onMethodNotAllowed(this._makeErrorCtx(fc, allowed))
-            : 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,
-        });
-    }
-    /**
-     * 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`.
-     */
-    _handlePreflight(fc, plan, params, allowed) {
-        fc.allowed = allowed;
-        const ctx = this._newCtx(fc, plan, params);
-        const final = this._finalize();
-        plan.pf ??= compileChain(plan.pfChain, (c) => {
-            const rq = c._rq;
-            return this._make405(rq, rq.allowed ?? []);
-        }, final.convert);
-        return plan.pf(ctx);
-    }
-    _handleMatched(fc, plan, params) {
-        const ctx = this._newCtx(fc, plan, params);
-        const telemetry = this._graph.settings.telemetry;
-        if (telemetry !== null && telemetry.onRoute !== undefined) {
-            try {
-                telemetry.onRoute({ method: fc.method, params, path: fc.path, req: fc.request, route: plan.r.rp ?? "" });
-            }
-            catch {
-                /* telemetry must not crash request */
-            }
-        }
-        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);
-    }
-    /** Output validation, inside the chain: an invalid body becomes an error response the middleware sees. */
-    async _validateOutput(handler, ctx, 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 */
-        if (ct && handler.os) {
-            const declaredTypes = Object.keys(handler.os);
-            const matches = declaredTypes.some((t) => ct.startsWith(t));
-            if (!matches) {
-                throw new HoneyError({
-                    errorKey: EK.output_content_type_mismatch,
-                    status: SK.internal_server_error,
-                });
-            }
-        }
-        /* 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 = await response.json();
-                await handler.ov(sk, data);
-                return forReturn;
-            }
-        }
-        return response;
-    }
-    _finishMatched(fc, plan, ctx, response) {
-        const s = this._graph.settings;
-        const handler = plan.r;
-        /* taps — fire after successful handler, non-blocking */
-        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 */
-            if (handler.mt !== null) {
-                for (const [key, tapFn] of taps) {
-                    const metaValue = handler.mt[key];
-                    if (metaValue !== undefined) {
-                        ctx.background(Promise.resolve()
-                            .then(() => tapFn(ctx, metaValue))
-                            .catch((e) => log?.warn?.({ err: e, tap: key }, "tap failed")));
-                    }
-                }
-            }
-            /* dynamic taps — fire for each c.tap() call */
-            if (ctx._pendingTaps !== null) {
-                for (const pending of ctx._pendingTaps) {
-                    const tapFn = taps.get(pending.key);
-                    if (tapFn !== undefined) {
-                        ctx.background(Promise.resolve()
-                            .then(() => tapFn(ctx, pending.payload))
-                            .catch((e) => log?.warn?.({ err: e, tap: pending.key }, "tap failed")));
-                    }
-                }
-                ctx._pendingTaps = null;
-            }
-        }
-        if (s.telemetry !== null) {
-            try {
-                const duration = performance.now() - fc.startTime;
-                s.telemetry.onHandler?.({
-                    duration,
-                    method: fc.method,
-                    path: fc.path,
-                    route: handler.rp ?? "",
-                    status: response.status,
-                });
-            }
-            catch {
-                /* telemetry must never crash the response path */
-            }
-        }
-        if (fc.method === "HEAD")
-            return headResponse(response);
-        return response;
-    }
-}
 /**
- * Route meta = middleware-contributed meta, overlaid by everything stated explicitly
- * (chain `.meta()`, then route `.meta()`). Explicit always wins.
+ * `@lovrozagar/honey`: the app (`honey()`), its context, errors, middleware and responses, the tree merge, and the
+ * types an app is read through. Everything optional is its own subpath; nothing here registers itself (H23).
  */
-function mergeContributedMeta(contributed, explicit) {
-    if (!contributed)
-        return explicit ? Object.freeze(explicit) : null;
-    return Object.freeze(explicit ? { ...contributed, ...explicit } : { ...contributed });
-}
-class RouteBuilder {
-    _s;
-    constructor(state) {
-        this._s = state;
-    }
-    errors(...args) {
-        const keys = typeof args[0] === "object" && args[0] !== null ? args.slice(1) : args;
-        for (const k of keys) {
-            this._s.errorKeys.add(k);
-        }
-        return new RouteBuilder({
-            ...this._s,
-            errorKeys: this._s.errorKeys,
-        });
-    }
-    boundary(key) {
-        this._s.boundaryErrorKey = key;
-        this._s.errorKeys.add(key);
-        return new RouteBuilder({
-            ...this._s,
-            boundaryErrorKey: key,
-            errorKeys: this._s.errorKeys,
-        });
-    }
-    handler(fn) {
-        let ov = null;
-        const outputSchemas = this._s.outputSchemas;
-        if (outputSchemas) {
-            const jsonSchemas = outputSchemas["application/json"];
-            if (jsonSchemas) {
-                ov = async (statusKey, data) => {
-                    const schema = jsonSchemas[statusKey];
-                    if (schema) {
-                        await validateOutput(schema, statusKey, data);
-                    }
-                };
-            }
-        }
-        const isInternal = Symbol.for("honey.internal") in fn;
-        /* 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 parent = this._s.parent;
-        const view = parent._view();
-        const base = {
-            _skip: isInternal || undefined,
-            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,
-            iv: this._s.inputSchemas,
-            mt: mergeContributedMeta(collectMiddlewareMeta([view.chain, this._s.middlewares]), this._s.meta),
-            mw: [],
-            os: this._s.outputSchemas,
-            ov,
-            own: view.own,
-            rb: this._s.boundaryErrorKey,
-            rm: [...this._s.middlewares],
-            xm: this._s.meta ? { ...this._s.meta } : null,
-        };
-        /* 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;
-    }
-    proxy(config) {
-        const proxyHandler = requireFeature("proxy", ".proxy()").createProxyHandler(config);
-        return this.handler(proxyHandler);
-    }
-    input(schemas) {
-        return new RouteBuilder({
-            ...this._s,
-            inputSchemas: schemas,
-        });
-    }
-    meta(meta) {
-        return new RouteBuilder({
-            ...this._s,
-            meta: (() => {
-                const merged = { ...this._s.meta, ...meta };
-                const inv = merged["invalidate"];
-                if (Array.isArray(inv) && inv.length > 1) {
-                    merged["invalidate"] = [...new Set(inv)];
-                }
-                return merged;
-            })(),
-        });
-    }
-    output(_schemas) {
-        return new RouteBuilder({
-            ...this._s,
-            outputSchemas: _schemas,
-        });
-    }
-    use(mw) {
-        return new RouteBuilder({
-            ...this._s,
-            middlewares: [...this._s.middlewares, mw],
-        });
-    }
-}
-class WSRouteBuilder {
-    _s;
-    constructor(state) {
-        this._s = state;
-    }
-    errors(factory, ...keys) {
-        void factory;
-        for (const k of keys) {
-            this._s.errorKeys.add(k);
-        }
-        return new WSRouteBuilder({
-            ...this._s,
-            errorKeys: this._s.errorKeys,
-        });
-    }
-    handler(wsHandler) {
-        const parent = this._s.parent;
-        const view = parent._view();
-        const routeHandler = {
-            bek: null,
-            cm: [...view.chain],
-            cv: view.cv,
-            dk: new Set(this._s.errorKeys),
-            ek: new Set(),
-            fn: wsHandler,
-            iv: this._s.inputSchemas,
-            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,
-        };
-        parent._settle(this._s.pending);
-        parent._addWsRoute(parsePattern(this._s.path), routeHandler);
-        return this._s.parent;
-    }
-    input(schemas) {
-        return new WSRouteBuilder({
-            ...this._s,
-            inputSchemas: schemas,
-        });
-    }
-    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) {
-        return new WSRouteBuilder({
-            ...this._s,
-            origins: validateOriginPolicy(policy),
-        });
-    }
-    use(mw) {
-        return new WSRouteBuilder({
-            ...this._s,
-            middlewares: [...this._s.middlewares, mw],
-        });
-    }
-}
-export function honey() {
-    return new Honey();
-}
-//# sourceMappingURL=index.js.map
+export { toFetchRequest } from "./adapters/fetch-request.js";
+export { HoneyContext } from "./context/context.js";
+export { HoneyError } from "./errors/error.js";
+export { defineErrors, ERROR_META } from "./errors/errors.js";
+export { createErrorResponse } from "./errors/projector.js";
+export { createMiddleware, defineMiddleware } from "./middleware/middleware.js";
+export { HoneyRes } from "./response/response.js";
+export { Honey, honey } from "./routing/app.js";
+export { mergeTree } from "./routing/tree-merge.js";
+export { detectRuntime } from "./runtime/detect-runtime.js";