@lovrozagar/honey 0.6.8 → 0.7.0

package/dist/index.d.ts

@@ -1,19 +1,29 @@
 import { HoneyContext } from "./context.ts";
+import { type TrustSetting } from "./client-info.ts";
+import type { TrustProxy } from "./trust.ts";
 import { HoneyError } from "./error.ts";
 import { ERROR_META } from "./errors.ts";
-import type { MiddlewareFn, RuntimeMiddleware } from "./middleware.ts";
+import type { ChainErrorConverter, MiddlewareFn, RuntimeMiddleware } from "./middleware.ts";
 import type { ProxyConfig } from "./proxy.ts";
 import type { CustomErrorFormatter, ErrorFormatter, ResponseOptions, TypedResponse } from "./response.ts";
 import { type HoneyRes } from "./response.ts";
-import type { RouteHandler, RouteTree, TreeNode } from "./tree.ts";
+import type { RouteId, Segment } from "./pattern.ts";
+import type { RouteEntry, RouteHandler, RouteTree, TreeNode, WSRouteHandler } from "./tree.ts";
 import type { RealtimeBus } from "./realtime/bus.ts";
-import type { RealtimeRouteOpts } from "./realtime/route.ts";
-import type { ComputeErrorsByStatus, DefaultMeta, ExtractSchemas, HttpMethod, InferInputMap, InferOutput, HoneyMetaSpec, InputSchemasDef, MergePath, MergeRoute, MetaSpecConfig, OutputSchemaDef, ParamsFromPath, StandardSchemaLike, TapContext } from "./types.ts";
+import type { RealtimeConfig, RealtimeRouteOpts } from "./realtime/route.ts";
+import type { RealtimePublisher } from "./realtime/server.ts";
+import type { ComputeErrorsByStatus, DefaultMeta, ExtractSchemas, HttpMethod, InferInputMap, InferOutput, HoneyMetaSpec, InputSchemasDef, MergePath, MergeRoute, MetaSpecConfig, OutputSchemaDef, ParamsFromPath, PrefixRoutes, StandardSchemaLike, TapContext } from "./types.ts";
 import type { WSAdapter, WSHandler } from "./ws/cloudflare.ts";
+import { type WSOriginPolicy } from "./ws-origin.ts";
+import type { MetaSpecSource } from "./meta-spec-merge.ts";
 import type { HoneyServeOptions, ServeHandle } from "./serve.ts";
-export { HoneyContext } from "./context.ts";
+export { clientInfo, HoneyContext } from "./context.ts";
+export { toFetchRequest } from "./fetch-request.ts";
+export type { WSOriginPolicy } from "./ws-origin.ts";
+export type { ClientInfo } from "./client-info.ts";
+export type { TrustProxy } from "./trust.ts";
 /** HoneyContext without internal backing fields — use this for consumer-facing types */
-export type HoneyCtx<TEnv = Record<string, unknown>> = Omit<import("./context.ts").HoneyContext<TEnv>, "_errorToResponse" | "_isErrorResponse" | "_lzCookies" | "_lzHeaders" | "_lzSearch" | "_lzSearchAll" | "_lzUrlFn" | "_setErrors">;
+export type HoneyCtx<TEnv = Record<string, unknown>> = Omit<import("./context.ts").HoneyContext<TEnv>, "_errorToResponse" | "_isErrorResponse" | "_lzClient" | "_lzCookies" | "_lzHeaders" | "_lzSearch" | "_lzSearchAll" | "_lzUrlFn" | "_rq" | "_setErrors">;
 export { HoneyError } from "./error.ts";
 export { defineErrors, ERROR_META } from "./errors.ts";
 export type { ErrorMetaEntry } from "./errors.ts";
@@ -24,9 +34,10 @@ export type { PendingTap, TapContext, TapHandler } from "./types.ts";
 export type { CookieOptions, CustomErrorFormatter, ErrorFormatter, ResponseOptions, SSEEvent, SSEOptions, SSEStream, TypedResponse, } from "./response.ts";
 export { createErrorResponse, HoneyRes } from "./response.ts";
 export { mergeTree } from "./tree.ts";
-export type { DefaultMeta, HoneyCodegen, HoneyMeta, InferBasePath, InferCtx, InferEnv, InferErrorFactory, InferInputMap, InferMeta, InferMethods, InferOutput, InferRouteCtx, InferRouteErrors, InferRouteInput, InferRouteMeta, InferRouteMethods, InferRouteOutput, InferRoutePaths, InferRoutes, InputSchemasDef, MergePath, HoneyMetaSpec, MetaSpecConfig, MetaSpecContext, MetaSpecEntry, MetaSpecMergeConflict, MetaSpecExpand, MetaSpecProfile, MetaSpecSchemaEntry, MetaSpecSchemaSearch, MetaSpecSchemaSource, MetaSpecSingle, MetaSpecStrictness, MetaSpecTarget, OpenApiMeta, OutputSchemaDef, Overwrite, ComputeErrorsByStatus, RouteRecord, StandardSchemaLike, StatusKey, SuccessStatusKey, } from "./types.ts";
-export type { WSAdapter, WSContext, WSHandler, WSPreUpgrade } from "./ws/cloudflare.ts";
-export type { ConnContext, RealtimeRouteOpts } from "./realtime/route.ts";
+export type { DefaultMeta, HoneyCodegen, HoneyMeta, InferBasePath, InferCtx, InferEnv, InferErrorFactory, InferInputMap, InferMeta, InferMethods, InferOutput, InferRouteCtx, InferRouteErrors, InferRouteInput, InferRouteMeta, InferRouteMethods, InferRouteOutput, InferRoutePaths, InferRoutes, InputSchemasDef, MergePath, PrefixRoutes, HoneyMetaSpec, MetaSpecConfig, MetaSpecContext, MetaSpecEntry, MetaSpecMergeConflict, MetaSpecExpand, MetaSpecProfile, MetaSpecSchemaEntry, MetaSpecSchemaSearch, MetaSpecSchemaSource, MetaSpecSingle, MetaSpecStrictness, MetaSpecTarget, OpenApiMeta, OutputSchemaDef, Overwrite, ComputeErrorsByStatus, RouteRecord, StandardSchemaLike, StatusKey, SuccessStatusKey, } from "./types.ts";
+export type { WSAdapter, WSAdapterOptions, WSContext, WSHandler, WSPreUpgrade } from "./ws/cloudflare.ts";
+export type { ConnContext, RealtimeLimits, RealtimeRouteOpts } from "./realtime/route.ts";
+export type { RealtimePublisher } from "./realtime/server.ts";
 export type { RealtimeBus } from "./realtime/bus.ts";
 export type { HoneyServeOptions, ServeHandle } from "./serve.ts";
 export type { ServeRuntime } from "./detect-runtime.ts";
@@ -38,10 +49,12 @@ type TelemetryAdapter = {
         method: string;
         path: string;
     }): void;
+    /** `path` is the request path; `route` the matched pattern (`/users/:id`). */
     onHandler?(ctx: {
         duration: number;
         method: string;
         path: string;
+        route: string;
         status: number;
     }): void;
     onMethodNotAllowed?(ctx: {
@@ -64,16 +77,19 @@ type TelemetryAdapter = {
         env: unknown;
         req: Request;
     }): void;
+    /** Fires exactly once per request that fired `onRequest`, whichever way it exits. */
     onResponse?(ctx: {
         duration: number;
         req: Request;
         status: number;
     }): void;
+    /** `path` is the request path; `route` the matched pattern (`/users/:id`). */
     onRoute?(ctx: {
         method: string;
         params: Record<string, string>;
         path: string;
         req: Request;
+        route: string;
     }): void;
 };
 type ErrorI18nConfig<TEnv> = {
@@ -92,13 +108,144 @@ type ErrorI18nConfig<TEnv> = {
 type Logger = {
     warn?(objOrMsg: Record<string, unknown> | string, msg?: string): void;
 };
+type ErrorCtx<TEnv> = {
+    env: TEnv;
+    jsonFromError: (err: HoneyError) => Response;
+    req: Request;
+};
+type OnErrorFn<TEnv> = (error: unknown, ctx: ErrorCtx<TEnv>) => HoneyError | Response | Promise<HoneyError | Response | undefined | void> | undefined | void;
+type OnMethodNotAllowedFn<TEnv> = (ctx: ErrorCtx<TEnv> & {
+    allowed: string[];
+}) => Response | Promise<Response>;
+type OnNotFoundFn<TEnv> = (ctx: ErrorCtx<TEnv>) => Response | Promise<Response>;
+type TapFn<TEnv> = (ctx: TapContext<TEnv>, payload: unknown) => void | Promise<void>;
+type ErrorFactoryRecord = Record<string, (...args: never[]) => unknown>;
+type OutputValidationMode = "always" | "dev" | "off";
+/**
+ * Settings of one app — shared by every handle derived from it (`use()`, `basePath()`,
+ * `context()`, `meta()`), so a setter called on any handle applies to all of them and
+ * serving any handle behaves the same. Records point at the settings of the app they were
+ * registered on, so a mounted sub-app's routes keep their own error factory, default errors,
+ * boundary and output validation.
+ */
+type AppSettings<TEnv = unknown> = {
+    customErrorFormatter: CustomErrorFormatter | null;
+    customErrorSchema: StandardSchemaLike | null;
+    defaultBoundaryKey: string | null;
+    defaultErrorKeys: Set<string>;
+    errorFactory: ErrorFactoryRecord | null;
+    errorFormatter: ErrorFormatterFn;
+    errorI18n: ErrorI18nConfig<TEnv> | null;
+    errorSchema: StandardSchemaLike | null;
+    logger: Logger | null;
+    onError: OnErrorFn<TEnv> | null;
+    onMethodNotAllowed: OnMethodNotAllowedFn<TEnv> | null;
+    onNotFound: OnNotFoundFn<TEnv> | null;
+    /** null = never set: a mounted route follows the mounting app's mode */
+    outputValidation: OutputValidationMode | null;
+    stripPrefix: string | null;
+    taps: Map<string, TapFn<TEnv>> | null;
+    telemetry: TelemetryAdapter | null;
+    trailingSlash: "enforce" | "ignore" | "strip";
+    encodedSlashes: "allow" | "reject";
+    trust: TrustSetting;
+    wsAdapter: WSAdapter | null;
+};
+/**
+ * Everything a matched route runs, compiled once at finalize: the record (with its resolved
+ * error keys, meta and chain) and one function that runs chain + handler and never rejects.
+ */
+type Plan = {
+    /** `.context()` values copied onto each request context */
+    cv: Record<string, unknown> | null;
+    /** declared error keys are enforced (the route, its middleware or the app declared any) */
+    enf: boolean;
+    /** preflight runner — chain without input validation or handler; compiled on first preflight */
+    pf: CompiledChain | null;
+    /** what the preflight runner runs */
+    pfChain: RuntimeMiddleware[];
+    r: RouteHandler | WSRouteHandler;
+    /** realtime route config when this is a realtime route */
+    rt: RealtimeConfig | null;
+    run: CompiledChain;
+    /** taps of the serving app, plus those of the app the route came from */
+    taps: Map<string, TapFn<unknown>> | null;
+};
+type CompiledChain = (ctx: object) => Response | Promise<Response>;
+/** What one app graph serves, resolved at finalize from records and the loaded tree. */
+type FinalTable = {
+    byId: Map<RouteId, RouteHandler>;
+    convert: ChainErrorConverter;
+    epoch: number;
+    /** 404 / 405: the middleware every route runs, plus the scopes covering the request path */
+    miss: Plan;
+    plans: Map<RouteId, Plan>;
+    /** `METHOD /path` → plan, for routes without params or wildcards */
+    statics: Record<string, Plan>;
+    wsById: Map<RouteId, WSRouteHandler>;
+    wsPlans: Map<RouteId, Plan>;
+};
+/** One `app.use(mw)` — the handle it returns has to register a route, or `mw` runs nowhere. */
+type ChainNode = {
+    mw: RuntimeMiddleware;
+    parent: ChainNode | null;
+    used: boolean;
+};
+/** A route builder still waiting for `.handler()` — reported at finalize. */
+type PendingRoute = {
+    id: string;
+};
+/** @internal — runtime entry for a scoped middleware */
+type ScopedEntry = {
+    /** cached from mw.errors at registration; undefined when none */
+    errors: readonly string[] | undefined;
+    /** the middleware behind a request-path check, for routes the scope covers only partly */
+    guard: RuntimeMiddleware;
+    mw: RuntimeMiddleware;
+    /** canonical full-path pattern (already rebased against basePath at .use time) */
+    prefix: string;
+    segs: Segment[];
+};
+/**
+ * One app graph — shared by every handle derived with `use()`, `basePath()`, `context()`,
+ * `meta()`. Records are per graph, keyed by `RouteId`; the tree holds ids only, so a loaded
+ * (shared, frozen) tree never carries another app's handlers.
+ */
 type HoneyGraph = {
-    handlerMap: Record<string, RouteHandler> | null;
-    hasRouteTree: boolean;
-    /** Codegen-time meta → OpenAPI policy. Never read on the request path */
+    /** metaSpec policies of mounted sub-apps, merged under `metaSpec` when codegen reads it */
+    absorbedMetaSpecs: MetaSpecSource[];
+    /** gateway catch-alls by method — root wildcards registered over a loaded tree that lacks them */
+    catchAll: Map<string, RouteHandler>;
+    /** every `use(mw)` handle — one that never registers a route is reported at finalize */
+    chains: ChainNode[];
+    /** bumped by every registration; finalize re-runs when it moves */
+    epoch: number;
+    final: FinalTable | null;
+    /** app-wide middleware that runs before every chain (serve({ cors })), keyed so a re-serve replaces it */
+    global: Map<string, RuntimeMiddleware>;
+    hasWs: boolean;
+    /** route data of the loaded tree (per-graph copies) — null when no tree was loaded */
+    loaded: Map<RouteId, RouteEntry> | null;
+    /** Codegen-time meta → OpenAPI policy declared on this app. Never read on the request path */
     metaSpec: MetaSpecConfig | null;
+    /** route builders still waiting for `.handler()` */
+    pending: Set<PendingRoute>;
     realtimeBus: RealtimeBus | null;
+    /** `ctx.realtime`, shared by every request of this graph */
+    realtimeCtx: RealtimePublisher | null;
+    realtimeRoutes: Map<string, RealtimeConfig>;
+    records: Map<RouteId, RouteHandler>;
     root: TreeNode;
+    /** root is a loaded tree (frozen, possibly shared by other apps) — copy before inserting */
+    rootShared: boolean;
+    /** path-scoped middleware, in registration order */
+    scoped: ScopedEntry[];
+    /** chains of the handles that served a request — decide what 404 and 405 run when there are no routes */
+    served: Set<RuntimeMiddleware[]>;
+    settings: AppSettings<unknown>;
+    /** registered after routeTree() with no leaf in the loaded tree — stale generated file */
+    unexpected: Set<RouteId>;
+    wsRecords: Map<RouteId, WSRouteHandler>;
 };
 type ErrorFormatterFn = ErrorFormatter;
 export declare class Honey<TEnv, TCtx = HoneyContext<TEnv>, TRoutes = {}, TMeta = never, TErrorFactory = never, TDefaultErrors extends string = never, TBasePath extends string = "/", TTaps extends Record<string, unknown> = {}, TScopedMw extends readonly ScopedMwEntry[] = []> {
@@ -110,111 +257,108 @@ export declare class Honey<TEnv, TCtx = HoneyContext<TEnv>, TRoutes = {}, TMeta
     readonly $routes: TRoutes;
     readonly $taps: TTaps;
     private _basePath;
-    private _defaultBoundaryKey;
-    private _defaultErrorKeys;
-    private _errorFactory;
-    private _errorSchema;
-    private _customErrorFormatter;
-    private _customErrorSchema;
+    private _chain;
     private _chainMeta;
-    private _chainMiddlewares;
-    private _scopedMiddlewares;
     private _contextValues;
-    private _errorFormatter;
-    private _errorI18n;
-    private _globalMiddlewares;
     private _graph;
-    private _hasWsRoutes;
-    private _logger;
-    private _outputValidation;
-    private _staticRoutes;
-    private _stripPrefix;
-    private _trailingSlash;
-    private _wsAdapter;
-    private _openApiCache;
-    private _openApiYamlCache;
-    private _manifestCache;
-    private _onError;
-    private _onMethodNotAllowed;
-    private _onNotFound;
-    private _taps;
-    private _telemetry;
-    private _realtimeRoutes;
+    /** the `use(mw)` call that created this chain — null on the root handle */
+    private _node;
     constructor(opts?: {
-        chainMiddlewares?: RuntimeMiddleware[];
-        defaultErrorKeys?: Set<string>;
-        globalMiddlewares?: RuntimeMiddleware[];
         graph?: HoneyGraph;
-        handlerMap?: Record<string, RouteHandler> | null;
-        root?: TreeNode;
-        scopedMiddlewares?: ScopedEntry[];
     });
-    private get _handlerMap();
-    private set _handlerMap(value);
-    private get _hasRouteTree();
-    private set _hasRouteTree(value);
-    /** @internal — read by codegen */
-    private get _metaSpec();
-    private set _metaSpec(value);
+    private get _s();
+    /**
+     * @internal — read by codegen through `metaSpecOf()`: the declared policy and every mounted
+     * sub-app's, unmerged. Merged on read, so `metaSpec()` may come before or after `route(sub)`;
+     * the merge lives with codegen so a served app never loads it.
+     */
+    private get _metaSpecSource();
+    /** @internal — read by codegen and OpenAPI */
+    get _errorFactory(): ErrorFactoryRecord | null;
+    set _errorFactory(factory: ErrorFactoryRecord | null);
+    /** @internal — read by OpenAPI */
+    get _errorSchema(): StandardSchemaLike | null;
+    /** @internal — read by OpenAPI */
+    get _customErrorSchema(): StandardSchemaLike | null;
     private get _root();
-    private set _root(value);
-    /** @internal — used by codegen */
-    private get _tree();
     private get _realtimeBus();
-    private set _realtimeBus(value);
-    /** @internal — mark that this app has WS routes */
-    _markWsRoutes(): void;
-    /** @internal — register a static route for O(1) lookup */
-    _registerStatic(key: string, handler: RouteHandler): void;
+    /** A new handle on the same graph, carrying this handle's view. */
+    private _derive;
+    /** This handle registers, mounts or serves — every `use()` on its way here is in use. */
+    private _markUsed;
     /** @internal — used by RouteBuilder for pre-filtered error factory */
     get _factory(): unknown;
     /** @internal — used by runtime error boundary */
     get _boundaryKey(): string | null;
-    /** Convert unknown thrown value to error Response — used in WS, 404, 405 catch blocks */
+    /** Convert an unknown thrown value to a plain error Response — no boundary, no onError. */
     private _toErrorResponse;
     private _createBoundaryError;
     private _createError;
-    /** Apply error keys from a single scoped entry to every matching handler currently in the tree */
-    private _applyScopedEntryErrors;
     /**
-     * Meta contributed by every middleware that will run for `routePath`, in runtime order:
-     * global, chain, then scoped entries matching the path. Route-level `.use()` is folded in
-     * later, by the builder. Resolved here — at registration — because the precompiled route
-     * tree bakes `mt` as a literal, so a per-request derivation would diverge from it.
+     * The i18n-resolved copy of `honeyError`: message from the locale's template for its
+     * errorKey, field paths from the locale's field names. Returns `honeyError` itself when
+     * i18n is not configured or nothing matches. Never mutates it: an error instance can be
+     * thrown again, on another request, in another locale.
      */
-    private _contributedMetaFor;
+    private _resolveI18n;
     /**
-     * Back-fill meta from one scoped entry onto handlers already in the tree. Mirrors
-     * `_applyScopedEntryErrors` — `.use("/prefix", mw)` may be registered after the routes it
-     * covers, and a tag missing where enforcement happens is the worst failure direction.
-     * `mt` is frozen at registration, so this replaces the object rather than mutating it.
+     * The error boundary of every `next()`: turns what a handler or middleware threw into the
+     * Response that replaces it, so every middleware around it sees a Response. Never rejects.
      */
-    private _applyScopedEntryMeta;
-    /** Apply error keys from every scoped entry on this chain to every matching handler in the tree */
-    private _applyAllScopedErrors;
-    /** Return scoped middleware functions that match the given route path */
-    private _filterScopedForPath;
-    /** Mutates `honeyError.message` in-place with the i18n-resolved template for its errorKey.
-     * No-op when i18n is not configured or when no template matches. */
-    private _resolveI18n;
+    private _convertError;
+    /** Last resort when even the configured formatter throws. */
+    private _safeErrorResponse;
     /**
-     * Convert thrown value into an error Response — resolves boundary wrapping,
-     * i18n translation, onError callback, and telemetry.
-     * Called from the handler wrapper so errors flow back through middleware.
+     * Convert thrown value into an error Response — resolves boundary wrapping, i18n
+     * translation, the onError callback, and error telemetry. `onResponse` telemetry is not
+     * fired here: the request fires it exactly once, on the way out.
      */
     private _resolveErrorResponse;
     basePath<P extends string>(prefix: P): Honey<TEnv, TCtx, TRoutes, TMeta, TErrorFactory, TDefaultErrors, MergePath<TBasePath, P>, TTaps, TScopedMw>;
     context<TAdds extends Record<string, unknown>>(values: TAdds): Honey<TEnv, TCtx & Readonly<TAdds>, TRoutes, TMeta, TErrorFactory, TDefaultErrors, TBasePath, TTaps, TScopedMw>;
     logger(logger: Logger): this;
-    outputValidation(mode: "always" | "dev" | "off"): this;
+    outputValidation(mode: OutputValidationMode): this;
     trailingSlash(mode: "enforce" | "ignore" | "strip"): this;
+    /**
+     * Request paths containing an encoded `/` or `\` (`%2F`, `%5C`) answer 400 by default.
+     * `"allow"` keeps them encoded in the path, so they decode into a param value
+     * (`/repos/:id` with `/repos/group%2Fproject` gives `id === "group/project"`). Only allow
+     * them when nothing downstream (a `proxy()` upstream, a file resolver) treats a decoded
+     * slash as a separator.
+     */
+    encodedSlashes(mode: "allow" | "reject"): this;
+    /**
+     * Which reverse proxies in front of the app to believe. Decides `ctx.ip`, `clientInfo()`,
+     * `ipRestrict`, and every other feature that needs the client's address, scheme or host.
+     *
+     * - `false` (default): the peer address the runtime reports is the client; `X-Forwarded-*`
+     *   headers are ignored, since any client can send them.
+     * - a hop count: exactly that many proxies, each appending its peer to `X-Forwarded-For`
+     *   (nginx `$proxy_add_x_forwarded_for`, most load balancers). The client is the entry the
+     *   outermost proxy wrote.
+     * - addresses and CIDR ranges of your proxies: hops from those addresses are skipped; the
+     *   first other address is the client.
+     *
+     * A hop count or list needs `import "@lovrozagar/honey/trust"` in the app entry.
+     */
+    trustProxy(value: TrustProxy): this;
     /** Strip a URL path prefix before route matching — boundary-safe (won't strip partial segments), paths without the prefix pass through unchanged */
     stripPrefix(prefix: string): this;
     wsAdapter(adapter: WSAdapter): this;
+    /**
+     * Serve this app's OpenAPI document at `${path}.json`, `.yaml` and `.yml` (default
+     * `/openapi`), and optionally a docs UI. Each call serves its own document: two calls with
+     * different options (say an internal and a public profile) never share a cache. Documents
+     * are generated once per route change, serialized once, and sent with an `ETag` and
+     * `Cache-Control: no-cache`. Pass `enabled: false` (for example in production) to mount
+     * nothing while keeping the call in place.
+     */
     openapi(options: {
         description?: string;
         docs?: "scalar" | "swagger";
         docsPath?: string;
+        /** Mount the document and docs routes. Default `true`. */
+        enabled?: boolean;
         filterRoutes?: (route: {
             meta: unknown;
             method: string;
@@ -227,40 +371,135 @@ export declare class Honey<TEnv, TCtx = HoneyContext<TEnv>, TRoutes = {}, TMeta
         title: string;
         version: string;
     }): 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?: {
+        enabled?: boolean;
         path?: string;
     }): this;
+    /** Mount a served document; a path another route or an earlier call owns is an error. */
+    private _mountArtifact;
     serve(options?: HoneyServeOptions): Promise<ServeHandle>;
-    private _lookupGet;
-    /** Mount an internal GET. Returns false when a user route already owns the path. */
+    /**
+     * Mount an internal GET (spec, docs, manifest). Reports who owns the path when it cannot:
+     * a user route (`"user"`) or an earlier internal mount (`"internal"`). Only an exact leaf
+     * counts: a `/:slug` or `/*rest` route does not block a static internal path, which wins
+     * over it on precedence, with backtracking, in both the runtime and a loaded tree.
+     */
     private _mountInternalGet;
+    private _bumpEpoch;
+    /** Place `id` at every leaf of `segments`, copying a shared (loaded) root first. */
+    private _placeLeaves;
+    /**
+     * @internal — register one route record. Over a loaded tree the record binds to the leaf
+     * the tree already holds for its id; a root wildcard the tree lacks becomes the gateway
+     * catch-all; any other unknown route marks the tree as stale (reported at finalize).
+     */
+    _addRoute(method: string, segments: readonly Segment[], record: RouteHandler): void;
+    /** @internal — register one websocket (or realtime) route record. */
+    _addWsRoute(segments: readonly Segment[], record: WSRouteHandler): void;
+    /**
+     * Resolve what this graph serves: registered records, live records carried by a loaded
+     * snapshot, and delegated leaves the gateway catch-all serves. Then resolve every record —
+     * its full chain (`chain → scoped → route → input validation`), error keys, meta and error
+     * factory — and compile it once. Re-runs whenever the graph's epoch moved. Throws, naming
+     * every route, when a loaded tree and the registered routes disagree (the generated file is
+     * stale), and when a `use(mw)` handle or a route builder was left unused (the middleware or
+     * route would silently be missing).
+     */
+    _finalize(): FinalTable;
+    /** `use(mw)` handles that never registered, mounted or served, and builders without `.handler()`. */
+    private _assertNothingDiscarded;
+    /**
+     * Resolve a record against this graph: chain = captured chain, the scopes that cover its
+     * pattern (behind a request-path check where only some of its paths are inside), then its
+     * route middleware. Error keys and contributed meta come from that chain, in run order.
+     * The error factory, default errors and boundary come from the app the route was
+     * registered on when that app has a factory, else from this one.
+     */
+    private _resolve;
+    /** Wrap each middleware for `telemetry.onMiddleware`, once per finalize. */
+    private _timed;
+    private _planRoute;
+    private _planWs;
+    /**
+     * 404 and 405 run through the same pipeline as a route: the middleware every route of this
+     * graph starts with (with no routes: every handle that served a request), then every scope
+     * (behind its request-path check), then the 404/405 answer. So a logger or CORS policy on the whole app also covers unknown paths, and a
+     * scope's guard answers before "not found" leaks what exists under it.
+     */
+    private _planMiss;
+    /**
+     * @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?: boolean): Array<{
+        handler: RouteHandler;
+        method: string;
+        path: string;
+    }>;
+    /** @internal — websocket routes, one entry per leaf. */
+    _collectWsRoutes(): Array<{
+        handler: WSRouteHandler;
+        path: string;
+    }>;
+    /** @internal — the route-graph epoch; served documents cache against it. */
+    get _epoch(): number;
     defaultErrorFormatter<TSchema extends StandardSchemaLike>(schema: TSchema, fn: (error: HoneyError) => InferOutput<TSchema>): this;
     defaultErrorFormatter(fn: ErrorFormatterFn): this;
     customErrorFormatter<TSchema extends StandardSchemaLike>(schema: TSchema, fn: (error: HoneyError, data: Record<string, unknown>) => InferOutput<TSchema>): this;
     customErrorFormatter(fn: CustomErrorFormatter): this;
     errorI18n(config: ErrorI18nConfig<TEnv>): this;
-    onError(handler: (error: unknown, ctx: {
-        env: TEnv;
-        jsonFromError: (err: HoneyError) => Response;
-        req: Request;
-    }) => HoneyError | Response | Promise<HoneyError | Response | undefined | void> | undefined | void): this;
-    onMethodNotAllowed(handler: (ctx: {
-        allowed: string[];
-        env: TEnv;
-        jsonFromError: (err: HoneyError) => Response;
-        req: Request;
-    }) => Response | Promise<Response>): this;
-    onNotFound(handler: (ctx: {
-        env: TEnv;
-        jsonFromError: (err: HoneyError) => Response;
-        req: Request;
-    }) => Response | Promise<Response>): this;
+    onError(handler: OnErrorFn<TEnv>): this;
+    onMethodNotAllowed(handler: OnMethodNotAllowedFn<TEnv>): this;
+    onNotFound(handler: OnNotFoundFn<TEnv>): this;
     /** Register a tap handler keyed by name — fires after successful handler response */
     tap<K extends string>(key: K, handler: (ctx: TapContext<TEnv>, payload: K extends keyof TTaps ? TTaps[K] : unknown) => void | Promise<void>): this;
     telemetry(adapter: TelemetryAdapter): this;
+    /**
+     * Load a route tree — a generated `routes.gen.ts`, an `app.toRouteTree()` snapshot, or a
+     * `mergeTree()` of either. The tree supplies the router topology; what each route runs
+     * comes from the routes this app registers afterwards (bound by `RouteId`), from live
+     * records in a snapshot, or — for leaves with neither — from a root wildcard the app
+     * registers as its gateway catch-all. Must be called before any route is registered.
+     */
     routeTree(tree: RouteTree): this;
+    /**
+     * Snapshot this app's routes as a tree: a copy of the topology plus, per route, its data
+     * and its live record. Internal routes (spec, docs, manifest) are left out. Loading the
+     * snapshot into another app serves these records; nothing in it is shared with this app.
+     * Each record keeps this app's settings (error factory, defaults, boundary) and context
+     * values, and carries the scoped middleware that covers it here as part of its chain —
+     * scopes themselves do not travel in a tree.
+     */
     toRouteTree(): RouteTree;
+    /** A resolved record as a standalone source: its resolved chain minus route middleware becomes its chain. */
+    private _bake;
+    /**
+     * @internal — generate-time: copy input/output schemas from `source` onto this app's
+     * routes that lack them (a gateway serves its generated tree, which carries none).
+     */
+    _overlaySchemas(source: RouteTree): void;
+    /**
+     * @internal — generate-time: the route tree a gateway serves. `source` is the merged
+     * downstream tree (`codegen.mergeTree`); the gateway's own registered routes join it as
+     * ordinary leaves, while its root wildcards stay out of the tree — they are the catch-all
+     * the downstream leaves delegate to. An own route that is also a downstream route, or
+     * whose topology conflicts with one, throws here instead of at request time. The app is
+     * rebound to the result, so codegen that runs next (OpenAPI, manifest) sees what it serves.
+     */
+    _gatewayTree(source: RouteTree): RouteTree;
+    /** @internal — swap the loaded tree, re-binding every registered route to it. */
+    _replaceLoadedTree(tree: RouteTree): void;
+    /**
+     * Set the app's error factory. Like every app setting it applies to every handle of this
+     * app, whenever it is called; routes mounted from another app keep that app's factory.
+     */
     errorFactory<TFactory extends Record<string, (...args: never[]) => unknown>>(factory: TFactory): Honey<TEnv, TCtx, TRoutes, TMeta, TFactory, TDefaultErrors, TBasePath, TTaps, TScopedMw>;
+    /** Error keys every route of this app declares — applies to routes registered before and after the call. */
     defaultErrors<TKeys extends ([TErrorFactory] extends [never] ? never : keyof TErrorFactory & string)>(...keys: TKeys[]): Honey<TEnv, TCtx, TRoutes, TMeta, TErrorFactory, TDefaultErrors | TKeys, TBasePath, TTaps, TScopedMw>;
     defaultBoundary<TKey extends ([TErrorFactory] extends [never] ? never : keyof TErrorFactory & string)>(key: TKey): Honey<TEnv, TCtx, TRoutes, TMeta, TErrorFactory, TDefaultErrors | TKey, TBasePath, TTaps, TScopedMw>;
     /** Phantom overload — constrains what route-level .meta() accepts */
@@ -274,19 +513,6 @@ export declare class Honey<TEnv, TCtx = HoneyContext<TEnv>, TRoutes = {}, TMeta
      * Codegen-time only — never consulted on the request path. See docs/meta-spec.md.
      */
     metaSpec<TSpec extends HoneyMetaSpec<TMeta>>(spec: TSpec): this;
-    /**
-     * Merge a mounted sub-app's policy into this one.
-     *
-     * The parent wins on conflict, so one gateway keeps one answer for its aggregate document —
-     * with a single exception. A sub entry of `false` wins over anything the parent says, because
-     * hiding is a safety claim and the strictest claim has to survive composition: a worker that
-     * declares a field unpublishable must not have the gateway publish it. Wrongly hidden is a
-     * visible gap; wrongly published is a leak.
-     *
-     * Every other disagreement is recorded and reported at codegen. Silently dropping a sub's
-     * entry is how someone ends up diffing two documents to find out why they differ.
-     */
-    private _absorbMetaSpec;
     /** Declare tap payload types — auto-extends meta with Partial<T> for meta-driven taps */
     taps<TNewTaps extends Record<string, unknown>>(): Honey<TEnv, Omit<TCtx, "tap"> & {
         tap<K extends keyof TNewTaps>(key: K, payload: TNewTaps[K]): void;
@@ -298,8 +524,26 @@ export declare class Honey<TEnv, TCtx = HoneyContext<TEnv>, TRoutes = {}, TMeta
         readonly path: MergePath<TBasePath, TPath>;
         readonly adds: TAdds;
     }]>;
-    route<TSubRoutes, TSubMeta, TSubErrorFactory, TSubDefaultErrors extends string, TSubBasePath extends string>(sub: Honey<TEnv, TCtx, TSubRoutes, TSubMeta, TSubErrorFactory, TSubDefaultErrors, TSubBasePath>): Honey<TEnv, TCtx, TRoutes & TSubRoutes, TMeta, TErrorFactory, TDefaultErrors, TBasePath, TTaps, TScopedMw>;
+    /**
+     * Mount a sub-app: its routes are served under this handle's basePath (and under `prefix`
+     * when given — `app.route("/v1", sub)` is `app.basePath("/v1").route(sub)`), and this
+     * handle's chain runs before theirs. The sub's own basePath stays part of each path.
+     */
+    route<TSubRoutes, TSubMeta, TSubErrorFactory, TSubDefaultErrors extends string, TSubBasePath extends string>(sub: Honey<TEnv, TCtx, TSubRoutes, TSubMeta, TSubErrorFactory, TSubDefaultErrors, TSubBasePath>): Honey<TEnv, TCtx, TRoutes & PrefixRoutes<TBasePath, TSubRoutes>, TMeta, TErrorFactory, TDefaultErrors, TBasePath, TTaps, TScopedMw>;
+    route<const TPrefix extends string, TSubRoutes, TSubMeta, TSubErrorFactory, TSubDefaultErrors extends string, TSubBasePath extends string>(prefix: TPrefix, sub: Honey<TEnv, TCtx, TSubRoutes, TSubMeta, TSubErrorFactory, TSubDefaultErrors, TSubBasePath>): Honey<TEnv, TCtx, TRoutes & PrefixRoutes<MergePath<TBasePath, TPrefix>, TSubRoutes>, TMeta, TErrorFactory, TDefaultErrors, TBasePath, TTaps, TScopedMw>;
+    private _mount;
+    private _setBus;
     private _registerRoute;
+    /** @internal — set (or clear, with null) one app-wide middleware; used by `serve()` */
+    _setGlobal(key: string, mw: RuntimeMiddleware | null): void;
+    /** @internal — what a route registered through this handle captures */
+    _view(): {
+        chain: RuntimeMiddleware[];
+        cv: Record<string, unknown> | null;
+        own: AppSettings<unknown>;
+    };
+    /** @internal — a builder got its handler (or was abandoned on purpose) */
+    _settle(pending: PendingRoute): void;
     on<const TPath extends string, const TMethods extends readonly [HttpMethod | "ALL", ...(HttpMethod | "ALL")[]]>(methods: TMethods, path: TPath): BuilderChain<TEnv, TCtx & ApplyScoped<TScopedMw, MergePath<TBasePath, TPath>>, {}, never, {}, MergePath<TBasePath, TPath>, TMethods[number], TRoutes, never, TCtx, TMeta, InitAccMeta<TMeta>, TErrorFactory, TDefaultErrors, TBasePath, TTaps, TScopedMw>;
     all<const TPath extends string>(path: TPath): BuilderChain<TEnv, TCtx & ApplyScoped<TScopedMw, MergePath<TBasePath, TPath>>, {}, never, {}, MergePath<TBasePath, TPath>, "ALL", TRoutes, never, TCtx, TMeta, InitAccMeta<TMeta>, TErrorFactory, TDefaultErrors, TBasePath, TTaps, TScopedMw>;
     delete<const TPath extends string>(path: TPath): BuilderChain<TEnv, TCtx & ApplyScoped<TScopedMw, MergePath<TBasePath, TPath>>, {}, never, {}, MergePath<TBasePath, TPath>, "DELETE", TRoutes, never, TCtx, TMeta, InitAccMeta<TMeta>, TErrorFactory, TDefaultErrors, TBasePath, TTaps, TScopedMw>;
@@ -310,7 +554,7 @@ export declare class Honey<TEnv, TCtx = HoneyContext<TEnv>, TRoutes = {}, TMeta
     post<const TPath extends string>(path: TPath): BuilderChain<TEnv, TCtx & ApplyScoped<TScopedMw, MergePath<TBasePath, TPath>>, {}, never, {}, MergePath<TBasePath, TPath>, "POST", TRoutes, never, TCtx, TMeta, InitAccMeta<TMeta>, TErrorFactory, TDefaultErrors, TBasePath, TTaps, TScopedMw>;
     put<const TPath extends string>(path: TPath): BuilderChain<TEnv, TCtx & ApplyScoped<TScopedMw, MergePath<TBasePath, TPath>>, {}, never, {}, MergePath<TBasePath, TPath>, "PUT", TRoutes, never, TCtx, TMeta, InitAccMeta<TMeta>, TErrorFactory, TDefaultErrors, TBasePath, TTaps, TScopedMw>;
     ws<const TPath extends string>(path: TPath): WSRouteBuilder<TEnv, TCtx & ApplyScoped<TScopedMw, MergePath<TBasePath, TPath>>, {}, never, Honey<TEnv, TCtx, TRoutes, TMeta, TErrorFactory, TDefaultErrors, TBasePath, TTaps, TScopedMw>>;
-    realtime(path: string, opts: RealtimeRouteOpts): this;
+    realtime<const TPath extends string>(path: TPath, opts: RealtimeRouteOpts<TCtx & ApplyScoped<TScopedMw, MergePath<TBasePath, TPath>>>): this;
     /**
      * Deno must call `Deno.upgradeWebSocket` in the same turn as the serve
      * callback. When the adapter implements `preUpgrade`, we do that here
@@ -319,21 +563,44 @@ export declare class Honey<TEnv, TCtx = HoneyContext<TEnv>, TRoutes = {}, TMeta
     fetch(request: Request, env: TEnv, executionCtx?: {
         waitUntil?: (p: Promise<unknown>) => void;
     }): Response | Promise<Response>;
-    private pathFromRequest;
+    /** @internal 400 for a request path the normalization policy rejects (see `normalizePath`), or an invalid `Host`. */
+    _badRequestTarget(): Response;
     private trailingSlashRedirects;
     private pathAfterPrefix;
     private _doFetch;
+    private _route;
+    private _matchWs;
+    private _dispatchRecord;
     private _makeErrorCtx;
+    /** A request context for `plan`: route data, context values, `ctx.errors`, `ctx.realtime`. */
+    private _newCtx;
     private _handleWs;
-    private _handleRealtime;
-    private _handle404;
-    private _preflightFallbackMethod;
-    /** Run the existing method's middleware for a CORS preflight. Do not invoke the route handler. */
-    private _handleCorsPreflight;
-    private _handle405;
+    /** Reject a cross-origin upgrade the route's origin policy does not allow (403). */
+    /** The websocket session runtime; a cross-origin upgrade the route does not allow is a 403. */
+    private _wsSession;
+    private _wsUpgrade;
+    /** Terminal of a realtime route's chain: identify, upgrade, and attach the connection to the bus. */
+    private _realtimeUpgrade;
+    /**
+     * 404 (`allowed === null`) and 405: one pipeline with a synthetic record — full context,
+     * the app-wide middleware and the scopes covering the path run once, telemetry fires once.
+     */
+    private _handleMiss;
+    /** Fire `onResponse` once for the request's one exit and return. A dispatch that rejects
+     * (an adapter failure past every error boundary) still ends the request: it reports 500. */
+    private _withOnResponse;
+    private _make404;
+    private _make405;
+    /**
+     * CORS preflight for a path that has no OPTIONS route: run the chain of the route the
+     * preflight asks about (`Access-Control-Request-Method`) — chain, scoped and route
+     * middleware, never input validation or the handler. Middleware that answers the
+     * preflight (cors) short-circuits; otherwise the answer is the 405 with `Allow`.
+     */
+    private _handlePreflight;
     private _handleMatched;
-    private _afterMatched;
-    private _validateThenFinish;
+    /** Output validation, inside the chain: an invalid body becomes an error response the middleware sees. */
+    private _validateOutput;
     private _finishMatched;
 }
 /**
@@ -384,14 +651,6 @@ type ApplyScoped<TScopedMw extends readonly ScopedMwEntry[], TFullPath extends s
     infer Head extends ScopedMwEntry,
     ...infer Rest extends readonly ScopedMwEntry[]
 ] ? (string extends Head["path"] ? {} : TFullPath extends Head["path"] ? Head["adds"] : TFullPath extends `${Head["path"] & string}/${string}` ? Head["adds"] : {}) & ApplyScoped<Rest, TFullPath> : {};
-/** @internal — runtime entry for a scoped middleware */
-type ScopedEntry = {
-    /** merged full-path prefix (already rebased against basePath at .use time) */
-    prefix: string;
-    mw: RuntimeMiddleware;
-    /** cached from mw.errors at registration; undefined when none */
-    errors: readonly string[] | undefined;
-};
 /** Apply typed params — override params with specific keys when route has :param segments */
 type ApplyParams<TCtx, TParams> = [keyof TParams] extends [string] ? string extends keyof TParams ? TCtx : TCtx & {
     readonly params: TParams;
@@ -415,20 +674,21 @@ type HandlerCtx<TCtx, TInput, TOutput, TParams, TAccMeta = {}, TErrorFactory = n
 }) & TypedTap<TTaps>, TOutput>;
 type RouteBuilderState<TParent> = {
     boundaryErrorKey: string | null;
+    /** keys the route declares itself (`.errors()`, `.boundary()`) */
     errorKeys: Set<string>;
     extraMethods: (HttpMethod | "ALL")[] | null;
-    handlerMap: Record<string, RouteHandler> | null;
     inputSchemas: InputSchemasDef | null;
+    /** explicit meta — chain `.meta()` overlaid by route `.meta()` */
     meta: Record<string, unknown> | null;
-    /** meta contributed by middleware — kept apart so explicit .meta() always outranks it */
-    mwMeta: Record<string, unknown> | null;
     method: HttpMethod | "ALL";
+    /** route-level middleware */
     middlewares: RuntimeMiddleware[];
     outputSchemas: OutputSchemaDef | null;
     parent: TParent;
-    parentMiddlewares: RuntimeMiddleware[];
+    /** canonical full pattern */
     path: string;
-    root: TreeNode;
+    /** reported at finalize until `.handler()` runs */
+    pending: PendingRoute;
 };
 /** Honey.TMeta defaults to never; never & X is never, so start acc meta at {}. */
 type InitAccMeta<TMeta> = [TMeta] extends [never] ? {} : TMeta;
@@ -454,28 +714,28 @@ declare class RouteBuilder<TEnv, TCtx, TInput = {}, _TErrorKeys extends string =
     use<TAdds>(mw: MiddlewareFn<TCtx, TAdds>): BuilderChain<TEnv, TCtx & TAdds, TInput, _TErrorKeys, TOutput, TPath, TMethod, TRoutes, TUsed, TBaseCtx, TMeta, TAccMeta, TErrorFactory, TDefaultErrors, TBasePath, TTaps, TScopedMw>;
 }
 type WSRouteBuilderState<TParent> = {
-    mwMeta?: Record<string, unknown> | null;
-    boundaryErrorKey: string | null;
     errorKeys: Set<string>;
     inputSchemas: InputSchemasDef | null;
+    origins: WSOriginPolicy | null;
     meta: Record<string, unknown> | null;
     middlewares: RuntimeMiddleware[];
     parent: TParent;
-    parentMiddlewares: RuntimeMiddleware[];
     path: string;
-    root: TreeNode;
+    pending: PendingRoute;
 };
-declare class WSRouteBuilder<TEnv, TCtx, TInput = {}, _TErrorKeys extends string = never, TParent extends {
-    _markWsRoutes(): void;
-} = {
-    _markWsRoutes(): void;
-}> {
+declare class WSRouteBuilder<TEnv, TCtx, TInput = {}, _TErrorKeys extends string = never, TParent = unknown> {
     private _s;
     constructor(state: WSRouteBuilderState<TParent>);
     errors<TFactory extends Record<string, (...args: never[]) => unknown>>(factory: TFactory, ...keys: Array<keyof TFactory & string>): WSRouteBuilder<TEnv, TCtx, TInput, _TErrorKeys | (keyof TFactory & string), TParent>;
     handler(wsHandler: WSHandler<TCtx>): TParent;
     input<TSchemas extends Pick<InputSchemasDef, "cookies" | "headers" | "search">>(schemas: TSchemas): WSRouteBuilder<TEnv, TCtx, TInput & InferInputMap<TSchemas>, _TErrorKeys, TParent>;
     meta(meta: Record<string, unknown>): this;
+    /**
+     * Browser origins allowed to open this socket: `"*"`, a list of origins
+     * (`https://app.example.com`), or a predicate. Same-origin always passes. Without it, a
+     * cross-origin upgrade that carries `Cookie` or `Authorization` gets 403.
+     */
+    origins(policy: WSOriginPolicy): WSRouteBuilder<TEnv, TCtx, TInput, _TErrorKeys, TParent>;
     use<TAdds>(mw: MiddlewareFn<TCtx, TAdds>): WSRouteBuilder<TEnv, TCtx & TAdds, TInput, _TErrorKeys, TParent>;
 }
 export declare function honey<TEnv>(): Honey<TEnv>;