@nifrajs/core 1.12.0 → 1.13.0

package/dist/server/server.js

@@ -4,6 +4,7 @@ import { canonicalizeIdempotencyBody, computeIdempotencyFingerprint, DEFAULT_IDE
 import { CAPABILITY_GUARD, createCapabilityGuard, normalizeRouteCapabilities, } from "../internal/capability-runtime.js";
 import { assuranceDeclarationsOf, assuranceEvidenceFor, NIFRA_ASSURANCE_IDS, } from "../internal/route-assurance.js";
 import { attachEffectLedger, createRequestLedger, DEFAULT_MAX_ENTRIES, } from "../ledger.js";
+import { compileRoutePattern, decodeRouteParams, } from "../router/pattern.js";
 import { EMPTY_PARAMS, Router } from "../router/router.js";
 import { drainCapped, parseContentLength, readBoundedBytes } from "./body.js";
 import { parseCookies, serializeCookie } from "./cookies.js";
@@ -35,6 +36,57 @@ function isResponseResult(value) {
 const fallbackWaitUntil = (promise) => {
     void promise.catch(() => { });
 };
+/**
+ * Runtime route catalog. Single-route registration mutates directly; multi-route registration replays
+ * the existing catalog plus the candidate batch into a staged router, then swaps the complete state only
+ * after every route validates. Failed `implement()`/`merge()` batches therefore leave matching and
+ * reflection unchanged.
+ */
+class RouteCatalog {
+    matcher = new Router();
+    records = [];
+    /** Allocation-free reflection view for the common no-assurance case. Derived only at commit time. */
+    descriptors = [];
+    assurancePresent = false;
+    add(route) {
+        this.matcher.add(route.method, route.pattern, route.entry);
+        this.records.push(route);
+        this.descriptors.push(route.descriptor);
+        if (route.assurance.length > 0)
+            this.assurancePresent = true;
+    }
+    addBatch(routes) {
+        if (routes.length === 0)
+            return;
+        const nextRecords = this.records.concat(routes);
+        const nextDescriptors = this.descriptors.concat(routes.map(({ descriptor }) => descriptor));
+        const nextAssurancePresent = this.assurancePresent || routes.some((route) => route.assurance.length > 0);
+        const staged = new Router();
+        for (const route of this.records)
+            staged.add(route.method, route.pattern, route.entry);
+        for (const route of routes)
+            staged.add(route.method, route.pattern, route.entry);
+        this.matcher = staged;
+        this.records = nextRecords;
+        this.descriptors = nextDescriptors;
+        this.assurancePresent = nextAssurancePresent;
+    }
+    find(method, path) {
+        return this.matcher.find(method, path);
+    }
+    entries() {
+        return this.records;
+    }
+    routeDescriptors() {
+        return this.descriptors;
+    }
+    lastDescriptor() {
+        return this.records[this.records.length - 1]?.descriptor;
+    }
+    hasAssurance() {
+        return this.assurancePresent;
+    }
+}
 const WS_PASS = { kind: "pass" };
 /** `app.ws()` (and everything downstream of it) needs the runtime `@nifrajs/core/ws` registers. */
 function requireWsRuntime() {
@@ -270,27 +322,6 @@ async function readBoundedForm(req, maxBytes) {
     }
     return out;
 }
-function decodeParams(raw) {
-    let out;
-    for (const key in raw) {
-        const value = raw[key];
-        // `decodeURIComponent` only changes strings containing `%`; for the common
-        // unencoded param (`/users/123`) skip the call and its throw-check entirely —
-        // semantically identical (no `%` ⇒ no escapes to decode), ~3× cheaper on that path. If every
-        // param is already plain, return the router's per-request object directly and skip a clone.
-        if (!value.includes("%")) {
-            continue;
-        }
-        try {
-            out ??= { ...raw };
-            out[key] = decodeURIComponent(value);
-        }
-        catch {
-            return null;
-        }
-    }
-    return out ?? raw;
-}
 function hasReplacementParam(params) {
     for (const key in params) {
         if (params[key].includes("\uFFFD"))
@@ -645,7 +676,7 @@ function appendCookiesToNodeHeaders(headers, cookies) {
  *      .get("/me", (c) => c.user)            // c.user + c.db are typed
  */
 export class Server {
-    router;
+    catalog;
     /** WebSocket routes, matched separately at upgrade time (a GET + `Upgrade: websocket`). */
     wsRouter;
     wsRouteCount;
@@ -653,7 +684,6 @@ export class Server {
      * Created by the first `app.ws()` via the `@nifrajs/core/ws` runtime — `undefined` until then, so a
      * no-WebSocket app never constructs (or bundles) it. */
     topics;
-    routeList;
     maxBodyBytes;
     wsMaxPayloadBytes;
     requestTimeoutMs;
@@ -673,6 +703,7 @@ export class Server {
     /** App-wide validation-error fallback; a route's own `schema.onValidationError` takes precedence. */
     defaultOnValidationError;
     bunServer;
+    sealed;
     derives;
     decorations;
     beforeHandleHooks;
@@ -692,19 +723,11 @@ export class Server {
     /** App-declared MCP resources / prompts (via {@link resource} / {@link prompt}), read by `nifra mcp`. */
     mcpResourceList;
     mcpPromptList;
-    /**
-     * Every registered route's raw router entry + descriptor, in order — the replay source for
-     * {@link merge}. The entry already carries the chains captured at registration (derives,
-     * decorations, before/after/around/onError), so a merged route behaves exactly as it did on
-     * the server that defined it.
-     */
-    rawEntries;
     constructor(options = {}) {
-        this.router = new Router();
+        this.catalog = new RouteCatalog();
         this.wsRouter = new Router();
         this.wsRouteCount = 0;
         this.topics = undefined;
-        this.routeList = [];
         this.maxBodyBytes = options.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES;
         this.wsMaxPayloadBytes = options.wsMaxPayloadBytes ?? this.maxBodyBytes;
         this.requestTimeoutMs = options.requestTimeoutMs ?? 0;
@@ -746,6 +769,7 @@ export class Server {
         this.logger = options.logger ?? jsonLogger();
         this.defaultOnValidationError = options.onValidationError;
         this.bunServer = undefined;
+        this.sealed = false;
         this.derives = [];
         this.decorations = {};
         this.beforeHandleHooks = [];
@@ -761,15 +785,21 @@ export class Server {
         this.globalAssurance = [];
         this.mcpResourceList = [];
         this.mcpPromptList = [];
-        this.rawEntries = [];
+    }
+    assertConfigurable(operation) {
+        if (this.sealed) {
+            throw new FrameworkError("SERVER_SEALED", `server configuration is sealed after listen(); call ${operation} before listen()`);
+        }
     }
     /** Add a per-request, computed context extension for subsequent routes. */
     derive(fn) {
+        this.assertConfigurable("derive()");
         this.derives.push(fn);
         return this;
     }
     /** Add a static context value for subsequent routes. */
     decorate(key, value) {
+        this.assertConfigurable("decorate()");
         this.decorations[key] = value;
         return this;
     }
@@ -778,11 +808,13 @@ export class Server {
      * `Request` to continue routing with a rewritten method/URL/headers. Global.
      */
     onRequest(fn) {
+        this.assertConfigurable("onRequest()");
         this.onRequestHooks.push(fn);
         return this;
     }
     /** Run after validation, before the handler; a non-`undefined` return short-circuits. Order-scoped. */
     beforeHandle(fn) {
+        this.assertConfigurable("beforeHandle()");
         this.beforeHandleHooks.push(fn);
         return this;
     }
@@ -792,30 +824,36 @@ export class Server {
      * a Web `Response`. The first registered wrapper is outermost.
      */
     around(fn) {
+        this.assertConfigurable("around()");
         this.aroundHooks.push(fn);
         return this;
     }
     /** Transform the handler's result before it is serialized. Order-scoped. */
     afterHandle(fn) {
+        this.assertConfigurable("afterHandle()");
         this.afterHandleHooks.push(fn);
         return this;
     }
     /** Handle a thrown error; a non-`undefined` return becomes the response (else the default 500). Order-scoped. */
     onError(fn) {
+        this.assertConfigurable("onError()");
         this.onErrorHooks.push(fn);
         return this;
     }
     /** Transform every outgoing response — success, error, 404, 405, short-circuit. Global. */
     onResponse(fn) {
+        this.assertConfigurable("onResponse()");
         this.onResponseHooks.push(fn);
         return this;
     }
     /** Observe the terminal response after all transformations. Observers are ordered and fail-open. */
     onResponseFinalized(fn) {
+        this.assertConfigurable("onResponseFinalized()");
         this.onResponseFinalizedHooks.push(fn);
         return this;
     }
     use(arg) {
+        this.assertConfigurable("use()");
         if (typeof arg === "function") {
             const name = arg.pluginName;
             if (name !== undefined) {
@@ -918,7 +956,7 @@ export class Server {
         this.register("POST", path, routeSchema, run);
         // Tag the just-registered descriptor as an MCP tool. `tool` is readonly on RouteDescriptor (an
         // introspection field), so write it through a narrow mutable view — not `any`.
-        const lastRoute = this.routeList[this.routeList.length - 1];
+        const lastRoute = this.catalog.lastDescriptor();
         if (lastRoute) {
             ;
             lastRoute.tool = {
@@ -936,6 +974,7 @@ export class Server {
      * for the resource half of MCP.
      */
     resource(uri, config, read) {
+        this.assertConfigurable("resource()");
         this.mcpResourceList.push({
             uri,
             name: config.name,
@@ -950,6 +989,7 @@ export class Server {
      * `handler` receives the caller's arguments and returns the rendered messages.
      */
     prompt(name, config, handler) {
+        this.assertConfigurable("prompt()");
         this.mcpPromptList.push({
             name,
             description: config.description,
@@ -976,6 +1016,7 @@ export class Server {
      *   app.ws("/chat", { open: (ws) => ws.send("hi"), message: (ws, data) => ws.send(data) })
      */
     ws(path, handler) {
+        this.assertConfigurable("ws()");
         // Boot-time guard: the WS runtime is a subpath (`@nifrajs/core/ws`) so no-WebSocket apps don't
         // bundle it. Registration is the loud, early failure point — never the first connection.
         const runtime = requireWsRuntime();
@@ -1019,6 +1060,18 @@ export class Server {
      * is the "compiled", order-scoped per-route chain.
      */
     register(method, path, schema, handler) {
+        this.assertConfigurable("route registration");
+        this.catalog.add(this.prepareRoute(method, path, schema, handler));
+    }
+    /** Register a contract/group route batch atomically. Every route captures the same current chain it
+     * would capture through {@link register}; no route becomes visible unless the full batch validates. */
+    registerBatch(routes) {
+        this.assertConfigurable("route registration");
+        const staged = routes.map(({ method, path, schema, handler }) => this.prepareRoute(method, path, schema, handler));
+        this.catalog.addBatch(staged);
+    }
+    prepareRoute(method, path, schema, handler) {
+        const pattern = compileRoutePattern(path);
         const capabilities = normalizeRouteCapabilities(schema?.capabilities);
         const handlerAssurance = assuranceDeclarationsOf(handler);
         const invalidHandlerScope = handlerAssurance.find((declaration) => declaration.scope !== "plugin");
@@ -1052,6 +1105,25 @@ export class Server {
         const fusedWeb = bare && this.aroundHooks.length === 0
             ? this.buildFusedWeb(handler, hasDecorations ? routeDecorations : undefined, isContextlessNoArgArrow(handler))
             : undefined;
+        const contextless = bare && this.aroundHooks.length === 0 && isContextlessNoArgArrow(handler);
+        const lane = bare
+            ? "bare"
+            : schema?.body !== undefined &&
+                schema.query === undefined &&
+                this.derives.length === 0 &&
+                this.beforeHandleHooks.length === 0 &&
+                this.afterHandleHooks.length === 0 &&
+                this.onErrorHooks.length === 0
+                ? "body"
+                : schema?.body === undefined &&
+                    schema?.query !== undefined &&
+                    this.derives.length === 0 &&
+                    this.beforeHandleHooks.length === 0 &&
+                    this.afterHandleHooks.length === 0 &&
+                    this.onErrorHooks.length === 0
+                    ? "query"
+                    : "lifecycle";
+        const execution = this.compileExecutionPlan(lane, contextless, this.aroundHooks.length > 0, ledgered !== undefined, fusedWeb);
         const entry = {
             // (context: never) => unknown -> InternalHandler: the framework invokes it
             // with the concrete RawContext the typed handler expects, so this is sound.
@@ -1059,7 +1131,6 @@ export class Server {
             schema,
             idempotent,
             ledgered,
-            fusedWeb,
             derives: [...this.derives],
             decorations: routeDecorations,
             hasDecorations,
@@ -1067,33 +1138,14 @@ export class Server {
             afterHandle: [...this.afterHandleHooks],
             onError: [...this.onErrorHooks],
             around: [...this.aroundHooks],
-            // Sync-fast-path eligibility (see RouteEntry.bare). Validation + every hook kind must be absent;
-            // decorations and generic around wrappers are fine: around wraps the inner bare route in
-            // `routeAndRun`, while the inner validation/derive/before/after/onError lifecycle remains empty.
-            // Most GET/no-schema routes qualify.
-            bare,
-            contextlessBare: bare && this.aroundHooks.length === 0 && isContextlessNoArgArrow(handler),
-            bodyOnly: schema?.body !== undefined &&
-                schema.query === undefined &&
-                this.derives.length === 0 &&
-                this.beforeHandleHooks.length === 0 &&
-                this.afterHandleHooks.length === 0 &&
-                this.onErrorHooks.length === 0,
-            queryOnly: schema?.body === undefined &&
-                schema?.query !== undefined &&
-                this.derives.length === 0 &&
-                this.beforeHandleHooks.length === 0 &&
-                this.afterHandleHooks.length === 0 &&
-                this.onErrorHooks.length === 0,
+            execution,
         };
-        this.router.add(method, path, entry);
         const descriptor = {
             method,
             path,
             schema,
             ...(capabilities.length > 0 ? { capabilities } : {}),
         };
-        this.routeList.push(descriptor);
         const routeAssurance = [...this.activeAssurance, ...handlerAssurance];
         if (schema?.body !== undefined) {
             routeAssurance.push(Object.freeze({
@@ -1111,13 +1163,62 @@ export class Server {
                 scope: "plugin",
             }));
         }
-        this.rawEntries.push({
+        return {
             method,
             path,
+            pattern,
             entry,
             descriptor,
             assurance: Object.freeze(routeAssurance),
-        });
+        };
+    }
+    /** Collapse route-invariant lifecycle decisions into one runner at registration. The request path
+     * performs no eligibility ladder: it supplies request state to this already-selected plan. */
+    compileExecutionPlan(lane, contextless, hasAround, hasLedger, fusedWeb) {
+        if (contextless) {
+            const run = (runtime, entry, source, params, search, signal, budget, platform, finalize, wrapResponse) => runtime.runContextlessBare(entry, source, params, search, signal, budget, platform, finalize, wrapResponse);
+            return Object.freeze({ run, fusedWeb });
+        }
+        let inner;
+        switch (lane) {
+            case "bare":
+                inner = (runtime, entry, _source, ctx, finalize, wrapResponse) => runtime.runBare(entry, ctx, finalize, wrapResponse);
+                break;
+            case "body":
+                inner = (runtime, entry, source, ctx, finalize, wrapResponse) => runtime.runBodyOnly(entry, source, ctx, finalize, wrapResponse);
+                break;
+            case "query":
+                inner = (runtime, entry, _source, ctx, finalize, wrapResponse) => runtime.runQueryOnly(entry, ctx, finalize, wrapResponse);
+                break;
+            default:
+                inner = (runtime, entry, source, ctx, finalize, wrapResponse) => runtime.runLifecycle(entry, source, ctx, finalize, wrapResponse);
+        }
+        const execute = hasAround
+            ? (runtime, entry, source, ctx, finalize, wrapResponse) => runtime.runWithAround(entry, ctx, () => inner(runtime, entry, source, ctx, finalize, wrapResponse), finalize, wrapResponse)
+            : inner;
+        const run = (runtime, entry, source, params, search, signal, budget, platform, finalize, wrapResponse) => {
+            const ctx = new RequestContext(source, params, search, signal, budget, platform, runtime.maxBodyBytes);
+            let ledger;
+            if (hasLedger) {
+                const resolved = entry.ledgered;
+                ledger = createRequestLedger({
+                    method: resolved.method,
+                    path: resolved.path,
+                    declared: resolved.declared,
+                    maxEntries: resolved.maxEntries,
+                    chain: resolved.chain,
+                });
+                attachEffectLedger(ctx, ledger);
+            }
+            let outcome = execute(runtime, entry, source, ctx, finalize, wrapResponse);
+            if (ledger !== undefined) {
+                const active = ledger;
+                const resolved = entry.ledgered;
+                outcome = (outcome instanceof Promise ? outcome : Promise.resolve(outcome)).then((value) => runtime.settleEffectLedger(active, resolved, value));
+            }
+            return outcome;
+        };
+        return Object.freeze({ run, fusedWeb });
     }
     /** Resolve a route's declared idempotency into a pinned store + defaults, or `undefined` when off. */
     resolveIdempotency(schema, authenticated) {
@@ -1191,15 +1292,12 @@ export class Server {
      * those on the parent).
      */
     merge(other) {
+        this.assertConfigurable("merge()");
         const source = other;
         if (source.wsRouteCount > 0) {
             throw new RouteConfigError("INVALID_PATH", "merge() does not carry WebSocket routes — register .ws() routes on the parent server");
         }
-        for (const { method, path, entry, descriptor, assurance } of source.rawEntries) {
-            this.router.add(method, path, entry); // throws RouteConfigError on a duplicate — fail closed
-            this.routeList.push(descriptor); // shared ref on purpose: carries later .tool() tagging
-            this.rawEntries.push({ method, path, entry, descriptor, assurance });
-        }
+        this.catalog.addBatch(source.catalog.entries().map((route) => this.bindFusedRuntime(route)));
         this.onRequestHooks.push(...source.onRequestHooks);
         this.onResponseHooks.push(...source.onResponseHooks);
         this.onResponseFinalizedHooks.push(...source.onResponseFinalizedHooks);
@@ -1208,6 +1306,21 @@ export class Server {
         this.mcpPromptList.push(...source.mcpPromptList);
         return this;
     }
+    /** A fused renderer closes over runtime services to keep its seven-argument JSC fast path. Merging
+     * rebinds that closure once to the executing server; generic plans already receive the runtime. */
+    bindFusedRuntime(route) {
+        const { entry } = route;
+        if (entry.execution.fusedWeb === undefined)
+            return route;
+        const fusedWeb = this.buildFusedWeb(entry.handler, entry.hasDecorations ? entry.decorations : undefined, isContextlessNoArgArrow(entry.handler));
+        return {
+            ...route,
+            entry: {
+                ...entry,
+                execution: Object.freeze({ ...entry.execution, fusedWeb }),
+            },
+        };
+    }
     /**
      * Enumerate the registered routes (method, path, input schemas), in registration
      * order. Powers `toOpenAPI` and other introspection; the router trie itself no
@@ -1215,11 +1328,11 @@ export class Server {
      */
     routes() {
         if (this.activeAssurance.length === 0 && this.globalAssurance.length === 0) {
-            const anyRouteEvidence = this.rawEntries.some((entry) => entry.assurance.length > 0);
-            if (!anyRouteEvidence)
-                return this.routeList;
+            if (!this.catalog.hasAssurance()) {
+                return this.catalog.routeDescriptors();
+            }
         }
-        return this.rawEntries.map(({ method, path, descriptor, assurance }) => {
+        return this.catalog.entries().map(({ method, path, descriptor, assurance }) => {
             const effective = assuranceEvidenceFor([...assurance, ...this.globalAssurance], method, path);
             return effective.length > 0 ? { ...descriptor, assurance: effective } : descriptor;
         });
@@ -1242,7 +1355,7 @@ export class Server {
     }
     fetchSourceInner(source, platform) {
         // Non-`async` on purpose: `dispatch` may return a `Response` *synchronously* (the bare-route fast
-        // path, see RouteEntry.bare), and an `async fetch` would wrap every such result in a redundant
+        // path, selected by the compiled execution plan), and an `async fetch` would wrap every such result in a redundant
         // promise + microtask. Returning `Response | Promise<Response>` matches Web/edge handlers, while
         // `await app.fetch(...)` continues to work exactly as before.
         const outcome = this.dispatch(source, platform, toResponse, IDENTITY_RESPONSE, RESPONSE_TIMEOUT, true);
@@ -1332,7 +1445,7 @@ export class Server {
                 ? response.then((settled) => ({ kind: "response", response: settled }))
                 : { kind: "response", response };
         }
-        // May resolve **synchronously** for a bare route + sync handler (RouteEntry.bare) — the `@nifrajs/node`
+        // May resolve **synchronously** for a compiled bare route + sync handler - the `@nifrajs/node`
         // adapter `await`s the result, so it transparently handles either; the sync case allocates no promise
         // at all on the Node hot path.
         return this.dispatch(source, platform, toNodeOutcome, NODE_FROM_RESPONSE, NODE_TIMEOUT, false);
@@ -1356,7 +1469,7 @@ export class Server {
             return WS_PASS; // upgrade header, no WS route here → normal routing decides
         // Inspect only captured values for escapes. Scanning the full pathname repeated work the router
         // already did and made every plain dynamic route pay for unrelated static path bytes.
-        const params = match.params === EMPTY_PARAMS ? match.params : decodeParams(match.params);
+        const params = match.params === EMPTY_PARAMS ? match.params : decodeRouteParams(match.params);
         if (params === null)
             return { kind: "reject", response: jsonError(400, "malformed_path") };
         const handler = match.payload.handler;
@@ -1495,12 +1608,12 @@ export class Server {
     }
     /**
      * Route → build context → run. Synchronous through to the handler for a **bare** route
-     * ({@link RouteEntry.bare}), so a sync handler produces its result with zero promise allocations;
+     * (selected by its compiled plan), so a sync handler produces its result with zero promise allocations;
      * routes with validation/hooks keep the full async {@link runLifecycle}, unchanged.
      */
     routeAndRun(source, platform, finalize, wrapResponse, onTimeout, webFast) {
         const url = urlPartsOf(source.url);
-        const match = this.router.find(source.method, url.pathname);
+        const match = this.catalog.find(source.method, url.pathname);
         if (!match.found) {
             if (match.reason === "method-not-allowed") {
                 return wrapResponse(jsonError(405, "method_not_allowed", { Allow: match.allowed.join(", ") }));
@@ -1509,7 +1622,7 @@ export class Server {
         }
         // Inspect only captured values for escapes. Scanning the full pathname repeated work the router
         // already did and made every plain dynamic route pay for unrelated static path bytes.
-        const params = match.params === EMPTY_PARAMS ? match.params : decodeParams(match.params);
+        const params = match.params === EMPTY_PARAMS ? match.params : decodeRouteParams(match.params);
         if (params === null) {
             return wrapResponse(jsonError(400, "malformed_path"));
         }
@@ -1627,7 +1740,7 @@ export class Server {
         }
         return wrapResponse(response);
     }
-    /** Run a matched route through its selected execution lane (fused/bare/bodyOnly/queryOnly/lifecycle). */
+    /** Supply request-specific deadline state to the route's precompiled execution plan. */
     runMatchedLanes(source, platform, entry, params, search, finalize, wrapResponse, onTimeout, webFast) {
         // Translate the absolute wire deadline once, clamp it to local policy, then use the resulting
         // duration for both c.signal and c.budget. A client can only shorten work, never extend it.
@@ -1661,62 +1774,10 @@ export class Server {
         const budget = controller === undefined
             ? getUnboundedRequestBudget()
             : createRequestBudget({ deadline: admission.deadline, signal });
-        // A bare route runs synchronously (no schema/derives/hooks); everything else keeps the full async
-        // lifecycle. `runBare` returns a value directly for a sync handler — no promise.
-        let outcome;
-        if (webFast && entry.fusedWeb !== undefined) {
-            // Fused Web lane (bare route, no around): one closure end to end. Sound cast — webFast is
-            // passed only by the `fetch` path, where T = Response by construction.
-            outcome = entry.fusedWeb(source, params, search, signal, budget, platform, false);
-        }
-        else if (entry.contextlessBare) {
-            outcome = this.runContextlessBare(entry, source, params, search, signal, budget, platform, finalize, wrapResponse);
-        }
-        else {
-            // Build the context up front so `onError` always has it. Query, cookies, headers, and body helpers
-            // stay lazy, but their accessors live on the prototype instead of allocating per-request closures.
-            const ctx = new RequestContext(source, params, search, signal, budget, platform, this.maxBodyBytes);
-            // Ledgered routes (capabilities + effectLedger) carry a bounded per-request ledger; the
-            // `useCapability` beacon appends to it, and the settle step below seals + sinks it. The route
-            // was forced off the fused/contextless lanes at registration, so this branch always runs.
-            let ledger;
-            if (entry.ledgered !== undefined) {
-                ledger = createRequestLedger({
-                    method: entry.ledgered.method,
-                    path: entry.ledgered.path,
-                    declared: entry.ledgered.declared,
-                    maxEntries: entry.ledgered.maxEntries,
-                    chain: entry.ledgered.chain,
-                });
-                attachEffectLedger(ctx, ledger);
-            }
-            if (entry.around.length === 0) {
-                outcome = entry.bare
-                    ? this.runBare(entry, ctx, finalize, wrapResponse)
-                    : entry.bodyOnly
-                        ? this.runBodyOnly(entry, source, ctx, finalize, wrapResponse)
-                        : entry.queryOnly
-                            ? this.runQueryOnly(entry, ctx, finalize, wrapResponse)
-                            : this.runLifecycle(entry, source, ctx, finalize, wrapResponse);
-            }
-            else {
-                outcome = this.runWithAround(entry, ctx, () => entry.bare
-                    ? this.runBare(entry, ctx, finalize, wrapResponse)
-                    : entry.bodyOnly
-                        ? this.runBodyOnly(entry, source, ctx, finalize, wrapResponse)
-                        : entry.queryOnly
-                            ? this.runQueryOnly(entry, ctx, finalize, wrapResponse)
-                            : this.runLifecycle(entry, source, ctx, finalize, wrapResponse), finalize, wrapResponse);
-            }
-            // Settle step: seal the ledger and hand it to the sink BEFORE the response is released, on
-            // success and error responses alike (partial work is exactly what an audit must capture). The
-            // lanes above resolve handler errors to responses, so a plain resolve arm is sufficient.
-            if (ledger !== undefined) {
-                const resolved = entry.ledgered;
-                const active = ledger;
-                outcome = (outcome instanceof Promise ? outcome : Promise.resolve(outcome)).then((value) => this.settleEffectLedger(active, resolved, value));
-            }
-        }
+        const plan = entry.execution;
+        const outcome = webFast && plan.fusedWeb !== undefined
+            ? plan.fusedWeb(source, params, search, signal, budget, platform, false)
+            : plan.run(this, entry, source, params, search, signal, budget, platform, finalize, wrapResponse);
         // The request timeout only bounds work that is actually pending — a synchronous (bare) result is
         // already complete and can't time out, so it's returned as-is (no 503 race, no promise).
         if (controller !== undefined && outcome instanceof Promise) {
@@ -1775,7 +1836,7 @@ export class Server {
         return wrapResponse(jsonError(500, "internal_error"));
     }
     /**
-     * The synchronous fast path for a {@link RouteEntry.bare} route: apply static decorations, call the
+     * The synchronous fast path selected by a route's execution plan: apply static decorations, call the
      * handler, render the result — **no `await`** unless the handler itself returns a promise. It mirrors
      * the bare slice of {@link runLifecycle} (which a bare route would otherwise no-op through) and shares
      * {@link logRequestError}; a bare route has no `onError` hooks, so error handling is fully synchronous
@@ -1801,14 +1862,13 @@ export class Server {
     /** Bare-route error rendering — identical to {@link runLifecycle}'s catch minus the (absent) onError
      * loop: a thrown `Response` is returned as deliberate control flow; anything else is logged + 500. */
     /**
-     * Build a route's fused Web lane (see {@link RouteEntry.fusedWeb}). Composition happens once at
+     * Build a route's fused Web renderer. Composition happens once at
      * registration; the returned closure is what every request to the route runs. Behavior is
      * byte-identical to the generic `runBare`/`runContextlessBare` + `toResponse` pair — same
      * decoration order, same error routing (thrown `Response` = control flow; anything else logs and
      * 500s), same respond semantics (the lifecycle parity suite pins it).
      */
     buildFusedWeb(handler, decorations, contextless) {
-        const maxBodyBytes = this.maxBodyBytes;
         const logError = (err, ctx) => {
             if (err instanceof Response)
                 return err;
@@ -1826,21 +1886,21 @@ export class Server {
                 }
                 catch (err) {
                     return logError(err, nativeContext
-                        ? RequestContext.native(source, params, maxBodyBytes)
-                        : new RequestContext(source, params, search, signal, budget, platform, maxBodyBytes));
+                        ? RequestContext.native(source, params, this.maxBodyBytes)
+                        : new RequestContext(source, params, search, signal, budget, platform, this.maxBodyBytes));
                 }
                 if (result instanceof Promise) {
                     return result.then(fusedRespondNoSet, (err) => logError(err, nativeContext
-                        ? RequestContext.native(source, params, maxBodyBytes)
-                        : new RequestContext(source, params, search, signal, budget, platform, maxBodyBytes)));
+                        ? RequestContext.native(source, params, this.maxBodyBytes)
+                        : new RequestContext(source, params, search, signal, budget, platform, this.maxBodyBytes)));
                 }
                 return fusedRespondNoSet(result);
             };
         }
         return (source, params, search, signal, budget, platform, nativeContext) => {
             const ctx = nativeContext
-                ? RequestContext.native(source, params, maxBodyBytes)
-                : new RequestContext(source, params, search, signal, budget, platform, maxBodyBytes);
+                ? RequestContext.native(source, params, this.maxBodyBytes)
+                : new RequestContext(source, params, search, signal, budget, platform, this.maxBodyBytes);
             if (decorations !== undefined)
                 Object.assign(ctx, decorations);
             let result;
@@ -2180,7 +2240,7 @@ export class Server {
     async runLifecycle(entry, source, ctx, finalize, wrapResponse) {
         try {
             if (entry.schema?.body !== undefined) {
-                const bodyError = await this.readAndValidateBody(source, entry.schema.body, ctx);
+                const bodyError = await this.readAndValidateBody(source, entry, ctx);
                 if (bodyError !== undefined)
                     return wrapResponse(bodyError);
             }
@@ -2190,9 +2250,9 @@ export class Server {
                 // validateStandard wrapper alloc.
                 const validation = entry.schema.query["~standard"].validate(queryObjectOf(ctx[CONTEXT_SEARCH]));
                 const result = validation instanceof Promise ? await validation : validation;
-                if (result.issues !== undefined)
-                    return wrapResponse(validationError(result.issues));
-                ctx.query = result.value;
+                const queryError = await this.applyLifecycleValidation(entry, result, ctx, "query");
+                if (queryError !== undefined)
+                    return wrapResponse(queryError);
             }
             // Context extensions: static decorations, then per-request derives.
             // Each hook below only awaits when it actually returns a Promise — a sync hook
@@ -2262,7 +2322,7 @@ export class Server {
             stack: err instanceof Error ? err.stack : undefined,
         });
     }
-    async readAndValidateBody(req, schema, ctx) {
+    async readAndValidateBody(req, entry, ctx) {
         const contentType = headerOf(req, "content-type") ?? "";
         let parsed;
         if (contentType === "application/json" || contentType.includes("application/json")) {
@@ -2282,11 +2342,38 @@ export class Server {
             // fit a value schema; use a schema-less route + @nifrajs/uploads helpers for those.
             return jsonError(415, "unsupported_media_type");
         }
-        const validation = schema["~standard"].validate(parsed);
+        const validation = entry.schema.body["~standard"].validate(parsed);
         const result = validation instanceof Promise ? await validation : validation;
-        if (result.issues !== undefined)
+        return this.applyLifecycleValidation(entry, result, ctx, "body");
+    }
+    /** Apply validation and its recovery hook on the generic lifecycle lane. Recovery is completed
+     * before derives/beforeHandle run, matching the body-only and query-only execution lanes. */
+    async applyLifecycleValidation(entry, result, ctx, kind) {
+        if (result.issues === undefined) {
+            if (kind === "body")
+                ctx.body = result.value;
+            else
+                ctx.query = result.value;
+            return undefined;
+        }
+        const hook = entry.schema?.onValidationError ?? this.defaultOnValidationError;
+        if (hook === undefined)
             return validationError(result.issues);
-        ctx.body = result.value;
+        const attempted = hook(result.issues, ctx, kind);
+        const recovery = attempted instanceof Promise ? await attempted : attempted;
+        if (recovery === undefined)
+            return validationError(result.issues);
+        if (recovery instanceof Response)
+            return recovery;
+        const schema = kind === "body" ? entry.schema?.body : entry.schema?.query;
+        const retried = schema["~standard"].validate(recovery);
+        const settled = retried instanceof Promise ? await retried : retried;
+        if (settled.issues !== undefined)
+            return validationError(settled.issues);
+        if (kind === "body")
+            ctx.body = settled.value;
+        else
+            ctx.query = settled.value;
         return undefined;
     }
     /**
@@ -2306,6 +2393,48 @@ export class Server {
     async readBoundedJson(req) {
         return readBoundedJsonSource(req, this.maxBodyBytes);
     }
+    /** Adapt one route's compiled execution plan to Bun's already-matched request shape. Route
+     * semantics remain in the plan; this closure only supplies native params and deadline fallback. */
+    compileBunNativeHandler(entry, paramNames, fused, signal, budget) {
+        if (paramNames.length === 0) {
+            if (fused === undefined) {
+                return (request) => this.fetchMatched(request, entry, EMPTY_PARAMS);
+            }
+            if (this.acceptInboundDeadlines) {
+                return (request) => request.headers.get(NIFRA_DEADLINE_HEADER) !== null
+                    ? this.fetchMatched(request, entry, EMPTY_PARAMS)
+                    : fused(request, EMPTY_PARAMS, undefined, signal, budget, undefined, true);
+            }
+            return (request) => fused(request, EMPTY_PARAMS, undefined, signal, budget, undefined, true);
+        }
+        const malformed = paramNames.length === 1
+            ? (params) => params[paramNames[0]]?.includes("\uFFFD") === true
+            : hasReplacementParam;
+        if (fused === undefined) {
+            return (request) => {
+                const params = request.params ?? EMPTY_PARAMS;
+                if (malformed(params))
+                    return this.fetchSource(request);
+                return this.fetchMatched(request, entry, params);
+            };
+        }
+        if (this.acceptInboundDeadlines) {
+            return (request) => {
+                const params = request.params ?? EMPTY_PARAMS;
+                if (malformed(params))
+                    return this.fetchSource(request);
+                return request.headers.get(NIFRA_DEADLINE_HEADER) !== null
+                    ? this.fetchMatched(request, entry, params)
+                    : fused(request, params, undefined, signal, budget, undefined, true);
+            };
+        }
+        return (request) => {
+            const params = request.params ?? EMPTY_PARAMS;
+            if (malformed(params))
+                return this.fetchSource(request);
+            return fused(request, params, undefined, signal, budget, undefined, true);
+        };
+    }
     /** Compile portable route registrations into Bun's native route table. Apps with request-rewrite
      * hooks or WebSockets retain the single portable dispatcher because those features must run before
      * route selection/upgrade. Named wildcards also stay on the fallback until Bun exposes their raw
@@ -2323,119 +2452,17 @@ export class Server {
         const unboundedSignal = mayUseFusedNative ? getNeverAbortSignal() : undefined;
         const unboundedBudget = mayUseFusedNative ? getUnboundedRequestBudget() : undefined;
         let count = 0;
-        for (const { method, path, entry } of this.rawEntries) {
-            if (path.includes("*"))
+        for (const { method, path, pattern, entry } of this.catalog.entries()) {
+            if (pattern.segments.some((segment) => segment.kind === "wildcard"))
                 continue;
             let methods = routes[path];
             if (methods === undefined) {
                 methods = Object.create(null);
                 routes[path] = methods;
             }
-            const paramNames = path
-                .split("/")
-                .filter((segment) => segment.charCodeAt(0) === 58 /* : */)
-                .map((segment) => segment.slice(1));
-            const fused = mayUseFusedNative ? entry.fusedWeb : undefined;
-            if (fused !== undefined) {
-                // Deliberately choose deadline-aware vs zero-admission closures HERE instead of branching on
-                // `acceptInboundDeadlines` per request. JSC can then flatten the default closure through the
-                // handler + Response.json; retaining that route-invariant branch cost ~7% on a dynamic GET.
-                if (paramNames.length === 0) {
-                    methods[method] = this.acceptInboundDeadlines
-                        ? (request) => request.headers.get(NIFRA_DEADLINE_HEADER) !== null
-                            ? this.fetchMatched(request, entry, EMPTY_PARAMS)
-                            : fused(request, EMPTY_PARAMS, undefined, unboundedSignal, unboundedBudget, undefined, true)
-                        : (request) => fused(request, EMPTY_PARAMS, undefined, unboundedSignal, unboundedBudget, undefined, true);
-                }
-                else if (paramNames.length === 1) {
-                    const paramName = paramNames[0];
-                    const handler = entry.handler;
-                    const decorations = entry.hasDecorations ? entry.decorations : undefined;
-                    const fail = (error, ctx) => {
-                        if (error instanceof Response)
-                            return error;
-                        this.logRequestError(error, ctx);
-                        return jsonError(500, "internal_error");
-                    };
-                    methods[method] = this.acceptInboundDeadlines
-                        ? (request) => {
-                            const params = request.params ?? EMPTY_PARAMS;
-                            if (params[paramName]?.includes("\uFFFD") === true)
-                                return this.fetchSource(request);
-                            if (request.headers.get(NIFRA_DEADLINE_HEADER) !== null) {
-                                return this.fetchMatched(request, entry, params);
-                            }
-                            const ctx = RequestContext.native(request, params, this.maxBodyBytes);
-                            if (decorations !== undefined)
-                                Object.assign(ctx, decorations);
-                            let result;
-                            try {
-                                result = handler(ctx);
-                            }
-                            catch (error) {
-                                return fail(error, ctx);
-                            }
-                            return result instanceof Promise
-                                ? result.then((value) => fusedRespond(value, ctx), (error) => fail(error, ctx))
-                                : fusedRespond(result, ctx);
-                        }
-                        : (request) => {
-                            const params = request.params ?? EMPTY_PARAMS;
-                            if (params[paramName]?.includes("\uFFFD") === true)
-                                return this.fetchSource(request);
-                            const ctx = RequestContext.native(request, params, this.maxBodyBytes);
-                            if (decorations !== undefined)
-                                Object.assign(ctx, decorations);
-                            let result;
-                            try {
-                                result = handler(ctx);
-                            }
-                            catch (error) {
-                                return fail(error, ctx);
-                            }
-                            return result instanceof Promise
-                                ? result.then((value) => fusedRespond(value, ctx), (error) => fail(error, ctx))
-                                : fusedRespond(result, ctx);
-                        };
-                }
-                else {
-                    methods[method] = this.acceptInboundDeadlines
-                        ? (request) => {
-                            const params = request.params ?? EMPTY_PARAMS;
-                            if (hasReplacementParam(params))
-                                return this.fetchSource(request);
-                            return request.headers.get(NIFRA_DEADLINE_HEADER) !== null
-                                ? this.fetchMatched(request, entry, params)
-                                : fused(request, params, undefined, unboundedSignal, unboundedBudget, undefined, true);
-                        }
-                        : (request) => {
-                            const params = request.params ?? EMPTY_PARAMS;
-                            if (hasReplacementParam(params))
-                                return this.fetchSource(request);
-                            return fused(request, params, undefined, unboundedSignal, unboundedBudget, undefined, true);
-                        };
-                }
-            }
-            else if (paramNames.length === 0) {
-                methods[method] = (request) => this.fetchMatched(request, entry, EMPTY_PARAMS);
-            }
-            else if (paramNames.length === 1) {
-                const paramName = paramNames[0];
-                methods[method] = (request) => {
-                    const params = request.params ?? EMPTY_PARAMS;
-                    if (params[paramName]?.includes("\uFFFD") === true)
-                        return this.fetchSource(request);
-                    return this.fetchMatched(request, entry, params);
-                };
-            }
-            else {
-                methods[method] = (request) => {
-                    const params = request.params ?? EMPTY_PARAMS;
-                    if (hasReplacementParam(params))
-                        return this.fetchSource(request);
-                    return this.fetchMatched(request, entry, params);
-                };
-            }
+            const paramNames = pattern.paramNames;
+            const fused = mayUseFusedNative ? entry.execution.fusedWeb : undefined;
+            methods[method] = this.compileBunNativeHandler(entry, paramNames, fused, unboundedSignal, unboundedBudget);
             count += 1;
         }
         return count === 0 ? undefined : routes;
@@ -2507,6 +2534,7 @@ export class Server {
                 },
             }));
         this.bunServer = running;
+        this.sealed = true;
         if (this.gracefulSignals)
             this.installSignalHandlers();
         return running;