@setu-ts/kernel 0.0.0-stage → 0.9.0

package/dist/application/application.js

@@ -0,0 +1,1862 @@
+/**
+ * Application — the kernel entry point. Orchestrates plugin registration,
+ * environment validation, middleware pipeline compilation, and request
+ * handling with lifecycle hooks.
+ *
+ * @module
+ */
+import { CAPABILITIES, ERROR_RESPONDER_STATE_KEY, errorResponderOf, isPromiseLike, parseFormBody, parseJsonBody, respondWithError, serializeError, setUpgradeIntent, } from '@setu-ts/common';
+import { MiddlewarePipeline } from "../pipeline/middleware-pipeline.js";
+import { executeChain } from "../pipeline/execute-chain.js";
+import { findUnsatisfiedConsumers, resolvePluginOrder } from "../registry/plugin-resolver.js";
+import { ServiceRegistry } from "../registry/service-registry.js";
+import { Router } from "../router/router.js";
+import { isPathDecodable } from "../router/route-matcher.js";
+import { LifecycleManager } from "../lifecycle/lifecycle-manager.js";
+import { createRequestContext } from "../context/request-context.js";
+import { coerceInjectBody } from "./inject-body.js";
+import { ResponseBuilder } from "../context/response.js";
+import { DiagnosticsCollector } from "../diagnostics/collector.js";
+import { compileLabelAllowlists } from "../diagnostics/projection.js";
+/**
+ * Kernel-internal handle on an application's diagnostics collector.
+ *
+ * `IApplication.diagnostics` deliberately hands out a frozen two-method facade,
+ * so the collector's writer surface is unreachable from a plugin — which is the
+ * point, since `IPluginContext.app` gives every plugin the application. Kernel
+ * tests still need the real object to drive its `safeObserve` boundary, so it
+ * lives here: a module-scoped `WeakMap` that is NOT on the package barrel and
+ * that a plugin cannot enumerate off the instance the way a symbol property
+ * could. The `ServiceRegistry.peekResolved` precedent — an internal seam whose
+ * absence from the public surface is the whole design.
+ *
+ * @internal
+ */
+const COLLECTORS = new WeakMap();
+/**
+ * Returns an application's diagnostics collector, or `undefined` when
+ * diagnostics were not enabled.
+ *
+ * @param app - The application to look up
+ * @returns The collector, or `undefined`
+ * @internal Kernel-internal; never exported from `src/index.ts`.
+ */
+export function collectorOf(app) {
+    return COLLECTORS.get(app);
+}
+// ---------------------------------------------------------------------------
+// Application class (internal — not exported from index)
+// ---------------------------------------------------------------------------
+class Application {
+    #registry = new ServiceRegistry();
+    #pipeline = new MiddlewarePipeline();
+    #registeringPlugin;
+    #router = new Router(() => this.#registeringPlugin);
+    #lifecycle = new LifecycleManager();
+    #plugins = [];
+    #envSpecs = [];
+    #started = false;
+    /**
+     * Whether any plugin has begun registering. Unlike {@linkcode #started} this is
+     * never reset: plugins that already ran cannot be un-run. `start()` rolls
+     * `#started` back on failure, but only a failure BEFORE this flag is set can be
+     * corrected and retried — once a plugin's `register()` has run, its services,
+     * hooks, routes and middleware (and any side effect outside the kernel) survive
+     * the rollback, so `start()` reads this to refuse a retry by name rather than
+     * failing on the leftover state. `unregister` reads it so it can never report
+     * having removed a plugin whose `register()` has already executed.
+     *
+     * Set inside the registration loop rather than on entry to `#runStartup`,
+     * because plugin RESOLUTION can fail before anything runs — and correcting
+     * that failure by removing the offending plugin is exactly what `unregister`
+     * is for.
+     */
+    #registrationStarted = false;
+    /** The plugins in registration order, once `start()` has resolved them. */
+    #ordered = [];
+    #serverHandle = null;
+    #inFlight = 0;
+    #stopping = false;
+    /** Cached in-flight/completed shutdown, so stop() runs its side effects once. */
+    #stopPromise = null;
+    /**
+     * The kernel diagnostics collector — `undefined` unless the application was
+     * created with `diagnostics` explicitly enabled. Every read of this field
+     * gates instrumentation, so the disabled path performs no additional work.
+     */
+    #collector;
+    /**
+     * The frozen read-only facade `diagnostics` hands out. The collector itself
+     * is NEVER exposed: it carries the writer surface (`markClosed`,
+     * `markStartupFailed`, `safeObserve`, every `observe*`), and `ctx.app` gives
+     * every plugin the application, so returning the collector put those methods
+     * one cast away from any plugin in the process. Reproduced before fixing: a
+     * plugin calling `markClosed(false)` through that cast left the reader
+     * permanently `closed` with empty topology while the application went on
+     * serving — the contract's "never a writer" broken with no error anywhere.
+     */
+    #diagnostics;
+    constructor(diagnostics) {
+        // Bound so `fetch` survives being passed around as a bare function. The
+        // Workers entry this framework documents is `export default { fetch:
+        // app.fetch }`, and Cloudflare invokes it as `exported.fetch(request, …)`,
+        // so `this` is the exported object: unbound, the `#registry` read below
+        // threw "Cannot read private member" and every request answered 500.
+        // Measured on workerd. Hono binds its `app.fetch` for the same reason.
+        this.fetch = this.fetch.bind(this);
+        this.#registry.setMissExplanation((token) => this.#explainMissingCapability(token));
+        if (diagnostics === undefined) {
+            return;
+        }
+        // Construction is the ONLY place option validation may reject: malformed
+        // label allowlists throw here, value-free, before any collection exists.
+        const collector = new DiagnosticsCollector(compileLabelAllowlists(diagnostics));
+        this.#collector = collector;
+        // Frozen so the facade cannot be re-pointed either: a consumer holding it
+        // can reach exactly the two contract methods and nothing else.
+        COLLECTORS.set(this, collector);
+        this.#diagnostics = Object.freeze({
+            snapshot: () => collector.snapshot(),
+            read: (after, limit) => collector.read(after, limit),
+        });
+        collector.safeObserve('topology', () => {
+            this.#lifecycle.setLifecycleObserver({
+                clock: () => collector.monotonicMs(),
+                onHook: (observation) => {
+                    collector.observeLifecycleHook(observation);
+                },
+            });
+        });
+        // Diagnostics sinks, installed beside (never instead of) the logging
+        // observer registered at startup. They are installed HERE, at
+        // construction, and NOT in `#runStartup()`: a route or a capability
+        // registered between `createApplication()` and `start()` is registered
+        // before startup runs, and a sink attached later cannot see it. That is
+        // not an edge case — a CLI-scaffolded project's `createApp()` registers
+        // its routes exactly there, through the generated
+        // `registerGeneratedRoutes(app.router, …)` setup call and the hello-world
+        // route, so the snapshot showed NO routes at all for the default template
+        // while the application served them.
+        //
+        // Composition-time registrations carry no owner, because no plugin's
+        // `register()` is running: `#registeringPlugin` is `undefined` and the
+        // node is recorded without an `owns` edge. That is the honest answer —
+        // the application registered it, not a plugin.
+        this.#registry.setDiagnosticsSink((event) => {
+            collector.safeObserve('topology', () => {
+                collector.capabilityRegistrationObserved(event, this.#registeringPlugin);
+                // The runtime capability's OWN registration is the diagnostics
+                // epoch: origin and instance UUID start there — the earliest moment
+                // they can honestly exist — so every later observation carries
+                // timings while earlier ones stay null.
+                if (event.token === CAPABILITIES.RUNTIME && event.kind !== 'unregister') {
+                    const runtime = this.#registry.peekResolved(CAPABILITIES.RUNTIME);
+                    if (runtime !== undefined) {
+                        collector.initializeRuntime(runtime, () => this.#registry.peekResolved(CAPABILITIES.TELEMETRY));
+                    }
+                }
+            });
+        });
+        this.#router.setDiagnosticsSink((event) => {
+            collector.safeObserve('topology', () => {
+                collector.routeRegistered(event);
+            });
+        });
+    }
+    /**
+     * The read-only diagnostics reader when diagnostics are enabled; `undefined`
+     * — never a stub — when they are not. This member is the consumer's whole
+     * access path: pull-only reads, never a registry token, never a writer.
+     *
+     * Returns a frozen two-method facade rather than the collector, so "never a
+     * writer" holds at RUNTIME and not only in the type — see
+     * {@linkcode Application.#diagnostics}.
+     * @since 0.8.0
+     */
+    get diagnostics() {
+        return this.#diagnostics;
+    }
+    /**
+     * The application's resolved error responder, read from the compiled
+     * pipeline's `errorHandler` brand at startup (M70f re-review, findings 1 & 2).
+     *
+     * `errorHandler` publishes its responder into `ctx.state` per request, but
+     * three kernel sites run BEFORE any middleware: the shutdown-drain `503`,
+     * the malformed-request `400`, and the request-lifecycle hooks. Those sites
+     * cannot read `ctx.state` (no context yet, or the context is fresh), so the
+     * kernel seeds the SAME resolved responder into their state from this cache.
+     * `undefined` when no `errorHandler` is registered, in which case every site
+     * keeps the byte-identical no-handler fallback.
+     */
+    #errorResponder = undefined;
+    get services() {
+        return this.#registry;
+    }
+    get middleware() {
+        return this.#pipeline;
+    }
+    get router() {
+        return this.#router;
+    }
+    register(plugin) {
+        if (this.#started) {
+            throw new Error('Cannot register plugins after the application has started.');
+        }
+        this.#plugins.push(plugin);
+        return this;
+    }
+    hasPlugin(name) {
+        return this.#plugins.some((plugin) => plugin.name === name);
+    }
+    unregister(name) {
+        // `#registrationStarted`, not `#started`: a FAILED `start()` rolls `#started`
+        // back, but the plugins that ran before the failure have already run — their `register()` executed and
+        // their services are in the registry. Removing one from the pending list
+        // then could not deliver what this method promises, and returning `true`
+        // would report a removal that did not happen.
+        if (this.#registrationStarted) {
+            throw new Error('Cannot unregister plugins once startup has begun. Plugins that already ' +
+                'registered cannot be un-run, so build a fresh application instead.');
+        }
+        // Removes EVERY match, not the first. Two pending plugins may share a name
+        // — `assertUniqueNames` refuses that at `start()`, not at `register()` — and
+        // removing one would leave the other running while the caller was told the
+        // name was dropped. It also converts that loud startup failure into a
+        // silently-running plugin, since the duplicate is gone by the time the
+        // resolver looks.
+        const before = this.#plugins.length;
+        for (let index = this.#plugins.length - 1; index >= 0; index--) {
+            if (this.#plugins[index]?.name === name) {
+                this.#plugins.splice(index, 1);
+            }
+        }
+        return this.#plugins.length !== before;
+    }
+    /**
+     * Explains a lookup the registry could not satisfy, in the two cases where
+     * the generic advice ("register a plugin that provides it") is wrong:
+     *
+     * - **Before any plugin has registered.** Plugins register their
+     *   capabilities during `start()`, so a lookup at module scope, or anywhere
+     *   before `start()`, finds nothing even when the plugin is listed.
+     * - **During a plugin's `register()`, for a token a later plugin provides.**
+     *   The provider has not run yet; declaring the dependency orders it first.
+     *
+     * Anything else keeps the generic advice: the capability really is absent.
+     *
+     * @param token - The token the lookup missed
+     * @returns The explanation, or `undefined` for the generic advice
+     */
+    #explainMissingCapability(token) {
+        if (!this.#registrationStarted) {
+            return 'The application has not started: plugins register their capabilities during ' +
+                'start(), so a lookup before then finds nothing. Resolve it inside a route handler or ' +
+                'a lifecycle hook, or after `await app.start()`.';
+        }
+        const current = this.#registeringPlugin;
+        if (current === undefined) {
+            return undefined;
+        }
+        const position = this.#ordered.findIndex((plugin) => plugin.name === current);
+        const provider = this.#ordered
+            .slice(position + 1)
+            .find((plugin) => plugin.provides?.includes(token) === true);
+        if (provider === undefined) {
+            return undefined;
+        }
+        // Every plugin implicitly depends on the runtime provider, so a dependency
+        // edge from it to a later plugin would be a cycle, not a fix.
+        if (this.#ordered[position]?.provides?.includes(CAPABILITIES.RUNTIME) === true) {
+            return `Plugin '${provider.name}' provides it, but registers after '${current}', which ` +
+                `provides the runtime and so always registers first. Resolve '${token}' in a lifecycle ` +
+                `hook such as onInit instead of during register().`;
+        }
+        return `Plugin '${provider.name}' provides it, but registers after '${current}'. Add ` +
+            `'${token}' to the dependencies (or optionalDependencies) of '${current}' so it ` +
+            `registers first.`;
+    }
+    async start(options) {
+        if (this.#started) {
+            throw new Error('Application has already been started.');
+        }
+        // A failed start is retryable only if it failed before any plugin ran
+        // `register()` (plugin resolution: a missing runtime provider, an
+        // unsatisfied dependency, a cycle). After that, every plugin that ran left
+        // its services in a registry that may already be sealed, its lifecycle
+        // hooks, its routes and its middleware behind — and possibly a resource its
+        // `onClose` did not release. A second attempt would re-run `register()`
+        // against that state and fail on it (`Capability 'runtime' is already
+        // registered`), so refuse by name instead of pretending it can be undone.
+        if (this.#registrationStarted) {
+            throw new Error('Cannot retry start() after plugins have registered: a previous start() failed ' +
+                'after plugin registration began, and plugins that already ran cannot be un-run. ' +
+                'Create a new application instead.');
+        }
+        // Mark as started up-front so plugins cannot register more plugins during
+        // startup, but roll it back if any startup step throws (see the catch
+        // below) so a start that failed before any plugin registered can be
+        // corrected and retried; later failures are refused above.
+        this.#started = true;
+        try {
+            await this.#runStartup(options);
+            // Startup fully completed (including listen): the application serves.
+            this.#collector?.markRunning();
+        }
+        catch (error) {
+            // Plugins may have connected resources and registered their `onClose`
+            // hook before a later registration, environment validation, or `onInit`
+            // step fails. `stop()` deliberately no-ops after a failed start, so this
+            // is the only lifecycle path that can release those partial-start
+            // resources. Preserve the startup failure: it is the actionable error
+            // the caller needs to correct.
+            try {
+                await this.#lifecycle.runClose();
+            }
+            catch {
+                // Best effort. A broken cleanup must not hide the startup failure, and
+                // later hooks cannot be reached once `runClose()` rejects.
+            }
+            this.#started = false;
+            // Terminal failure state: retained node/edge/event buffers are cleared
+            // inside, while the original error below is preserved untouched.
+            this.#collector?.markStartupFailed();
+            throw error;
+        }
+    }
+    async #runStartup(options) {
+        this.#collector?.markStarting();
+        // 1. Resolve plugin order — throws without runtime provider
+        const resolveOperation = this.#collector?.beginOperation();
+        let ordered;
+        try {
+            ordered = resolvePluginOrder(this.#plugins);
+            this.#ordered = ordered;
+        }
+        catch (error) {
+            if (resolveOperation !== undefined) {
+                this.#collector?.observeLifecycleEvent(resolveOperation, 'resolve', null, 'error');
+            }
+            throw error;
+        }
+        if (resolveOperation !== undefined) {
+            this.#collector?.observeLifecycleEvent(resolveOperation, 'resolve', null, 'ok');
+        }
+        // The optional getters (config/logger/metadata/container) and the
+        // mandatory runtime are resolved lazily via a Proxy. Runtime is fetched
+        // on first access so the runtime-providing plugin (which registers
+        // first) can populate CAPABILITIES.RUNTIME before any other plugin
+        // touches ctx.runtime. Arrow functions below capture `this` lexically.
+        const registry = this.#registry;
+        const envSpecs = this.#envSpecs;
+        const registrationOwner = () => this.#registeringPlugin;
+        registry.setObserver((kind, token) => {
+            this.#reportRegistryMutation(kind, token, this.#registeringPlugin);
+        });
+        // The diagnostics SINKS are installed in the constructor (see there);
+        // this local is the startup path's own handle on the collector.
+        const collector = this.#collector;
+        // Name of the plugin whose `register()` is currently running — read by
+        // `environment.validate` to attribute each env-var declaration. `undefined`
+        // outside the registration loop (e.g. a `validate` call from a lifecycle
+        // hook), which the fallback message covers.
+        const base = {
+            services: registry,
+            middleware: this.#pipeline,
+            router: this.#router,
+            lifecycle: this.#lifecycle,
+            health: {
+                register(name, indicator) {
+                    registry.register(CAPABILITIES.HEALTH_INDICATOR, { name, check: indicator }, { multi: true });
+                },
+            },
+            metrics: {
+                register(name, config) {
+                    registry.register(CAPABILITIES.METRIC_REGISTRATION, { name, config }, { multi: true });
+                },
+            },
+            openapi: {
+                addSchema(name, schema) {
+                    registry.register(CAPABILITIES.OPENAPI_SCHEMA, { name, schema }, { multi: true });
+                },
+            },
+            decorators: {
+                register(name, handler) {
+                    registry.register(CAPABILITIES.DECORATOR_HANDLER, { name, handler }, { multi: true });
+                },
+            },
+            cli: {
+                register(name, handler) {
+                    registry.register(CAPABILITIES.CLI_COMMAND, { name, handler }, { multi: true });
+                },
+            },
+            environment: {
+                validate(spec) {
+                    // Attribute the declaration to the plugin currently registering, so a
+                    // violation message names the plugin that asked for the variable. One
+                    // context object is shared by every plugin, so the declaring plugin is
+                    // read from the registration cursor rather than captured per context.
+                    envSpecs.push({ name: registrationOwner() ?? 'the application', spec });
+                },
+            },
+            options: {},
+            app: this,
+        };
+        const lazyGetters = {
+            runtime: () => registry.get(CAPABILITIES.RUNTIME),
+            config: () => registry.get(CAPABILITIES.CONFIG),
+            logger: () => registry.get(CAPABILITIES.LOGGER),
+            metadata: () => registry.get(CAPABILITIES.METADATA_STORE),
+            container: () => registry.get(CAPABILITIES.DI_CONTAINER),
+        };
+        const lazyAvailable = {
+            runtime: () => registry.has(CAPABILITIES.RUNTIME),
+            config: () => registry.has(CAPABILITIES.CONFIG),
+            logger: () => registry.has(CAPABILITIES.LOGGER),
+            metadata: () => registry.has(CAPABILITIES.METADATA_STORE),
+            container: () => registry.has(CAPABILITIES.DI_CONTAINER),
+        };
+        const ctx = new Proxy(base, {
+            get(target, prop, receiver) {
+                if (prop in lazyGetters) {
+                    return lazyAvailable[prop]() ? lazyGetters[prop]() : undefined;
+                }
+                return Reflect.get(target, prop, receiver);
+            },
+            has(target, prop) {
+                if (prop in lazyGetters) {
+                    return lazyAvailable[prop]();
+                }
+                return Reflect.has(target, prop);
+            },
+            ownKeys(target) {
+                const keys = Reflect.ownKeys(target);
+                for (const k of Object.keys(lazyGetters)) {
+                    if (lazyAvailable[k]() && !keys.includes(k)) {
+                        keys.push(k);
+                    }
+                }
+                return keys;
+            },
+            getOwnPropertyDescriptor(target, prop) {
+                if (prop in lazyGetters) {
+                    if (!lazyAvailable[prop]()) {
+                        return undefined;
+                    }
+                    return {
+                        enumerable: true,
+                        configurable: true,
+                        writable: false,
+                        value: lazyGetters[prop](),
+                    };
+                }
+                return Reflect.getOwnPropertyDescriptor(target, prop);
+            },
+        });
+        // 3. Register each plugin in resolved order, then run the onRegister
+        //    hooks it just added — these run "during the owning plugin's
+        //    registration" (after that plugin, before the next), distinct from
+        //    the onInit hooks that run once all plugins have registered.
+        try {
+            for (const plugin of ordered) {
+                // Set here, not at the top of `#runStartup`: `resolvePluginOrder` above
+                // can throw (an unsatisfied dependency, a cycle, no runtime provider)
+                // before any plugin has run, and that is the most correctable startup
+                // failure there is — gating `unregister` on it would refuse to let the
+                // caller remove the plugin that caused it.
+                this.#registrationStarted = true;
+                this.#registeringPlugin = plugin.name;
+                // Capture the plugin at its registration boundary: node plus DECLARED
+                // edges, before `register()` runs and while the owner attribution is
+                // unambiguous. Labels are projected through the allowlists here.
+                const pluginNodeId = collector?.pluginRegistered({
+                    name: plugin.name,
+                    version: plugin.version,
+                    provides: plugin.provides ?? [],
+                    requires: plugin.dependencies ?? [],
+                    optionalDependencies: plugin.optionalDependencies ?? [],
+                    consumes: plugin.consumes ?? [],
+                });
+                const registerOperation = collector?.beginOperation();
+                try {
+                    await plugin.register(ctx);
+                    await this.#lifecycle.runRegister();
+                }
+                catch (error) {
+                    if (registerOperation !== undefined) {
+                        collector?.observeLifecycleEvent(registerOperation, 'register', pluginNodeId ?? null, 'error');
+                    }
+                    throw error;
+                }
+                if (registerOperation !== undefined) {
+                    collector?.observeLifecycleEvent(registerOperation, 'register', pluginNodeId ?? null, 'ok');
+                }
+            }
+        }
+        finally {
+            this.#registeringPlugin = undefined;
+        }
+        // 4. Validate collected env specs against runtime.env
+        const runtime = this.#registry.get(CAPABILITIES.RUNTIME);
+        // Fallback initialization for a runtime registered as a LAZY factory,
+        // whose registration cannot be observed as a resolved instance at its
+        // mutation. `initializeRuntime` is idempotent, so an application whose
+        // runtime registered normally was already initialized in the sink above.
+        collector?.initializeRuntime(runtime, () => this.#registry.peekResolved(CAPABILITIES.TELEMETRY));
+        this.#validateEnvironment(runtime);
+        // 5. Run init hooks
+        await this.#lifecycle.runInit();
+        // 5b. Warn about consumed capabilities that no plugin provides. Checked
+        //     here — after all plugins have registered and run their init hooks —
+        //     so the live registry reflects every capability, including any
+        //     registered imperatively rather than declared in `provides`.
+        this.#warnUnsatisfiedConsumers();
+        // 6. Compile the middleware pipeline
+        const chain = this.#pipeline.compile();
+        // Capture the compiled global pipeline once, in execution order — the
+        // stable priority sort — so middleware nodes and stage records agree.
+        collector?.middlewareCompiled(this.#pipeline.compiledDescriptors());
+        // 6b. Resolve the application's error responder from the pipeline (M70f
+        //     re-review, findings 1 & 2). `errorHandler` brands its middleware
+        //     function with the responder it built at factory time; the kernel
+        //     caches that ONE instance so the pre-pipeline sites — the drain 503,
+        //     the malformed-request 400, and the request-lifecycle hooks — can
+        //     seed it into their state before they run, where `errorHandler`'s own
+        //     `ctx.state` publication cannot reach them. The LAST branded stage
+        //     in execution order (the innermost, i.e. the highest priority number
+        //     among the selected stages) wins, matching the responder that stage
+        //     publishes into `ctx.state` for in-pipeline sites.
+        this.#errorResponder = this.#resolveErrorResponder(chain);
+        // 7. Run bootstrap hooks
+        await this.#lifecycle.runBootstrap();
+        registry.seal();
+        // 8. Set the handler (always, so app.fetch works even without listen — CF Workers path)
+        if (this.#registry.has(CAPABILITIES.HTTP_ADAPTER)) {
+            const adapter = this.#registry.get(CAPABILITIES.HTTP_ADAPTER);
+            adapter.setHandler((request) => this.#handleRequest(request));
+        }
+        // 9. Listen only if adapter + port are available
+        if (options?.port !== undefined) {
+            if (!this.#registry.has(CAPABILITIES.HTTP_ADAPTER)) {
+                throw new Error(`Cannot start HTTP server on port ${options.port}: no 'http-adapter' capability is registered. ` +
+                    `Register the RuntimePlugin or a custom IHttpAdapter.`);
+            }
+            const adapter = this.#registry.get(CAPABILITIES.HTTP_ADAPTER);
+            const listenOperation = collector?.beginOperation();
+            try {
+                this.#serverHandle = await adapter.listen(options.port, options.hostname);
+            }
+            catch (error) {
+                if (listenOperation !== undefined) {
+                    collector?.observeLifecycleEvent(listenOperation, 'listen', null, 'error');
+                }
+                throw error;
+            }
+            if (listenOperation !== undefined) {
+                collector?.observeLifecycleEvent(listenOperation, 'listen', null, 'ok');
+            }
+        }
+    }
+    stop() {
+        // No-op if the application never started (e.g. a failed start() or a
+        // bare createApplication() used only for inject()). Avoids a confusing
+        // "No service registered for capability 'runtime'" from #drainRequests.
+        if (!this.#started) {
+            return Promise.resolve();
+        }
+        // Idempotent: a second call — concurrent or later — returns the same
+        // shutdown promise instead of re-running the drain and the shutdown/close
+        // hooks. Without this, repeated stop() calls fire onShutdown/onClose more
+        // than once.
+        if (this.#stopPromise !== null) {
+            return this.#stopPromise;
+        }
+        this.#stopPromise = this.#doStop();
+        return this.#stopPromise;
+    }
+    async #doStop() {
+        // Diagnostics state flips to `stopping` as the shutdown begins; the
+        // terminal `closed` transition and the retained-buffer clear run in the
+        // `finally` below, whatever the shutdown outcome — including a rejecting
+        // shutdown or close hook.
+        this.#collector?.markStopping();
+        let shutdownFailed = false;
+        try {
+            await this.#runShutdownSequence();
+        }
+        catch (error) {
+            shutdownFailed = true;
+            throw error;
+        }
+        finally {
+            this.#collector?.markClosed(shutdownFailed);
+        }
+    }
+    async #runShutdownSequence() {
+        // Runs FIRST, while the application is still serving normally, so a hook
+        // can tell the outside world to stop routing here before that becomes
+        // true — deregistering from a service registry, for instance.
+        //
+        // Guarded rather than awaited unconditionally: `await` on an
+        // already-resolved promise still defers everything below by a microtask,
+        // which would move when `#stopping` flips and hand a 404 to a request that
+        // used to get a 503. With no hook registered the flag is still set in the
+        // same synchronous turn as before, so opting out costs nothing.
+        //
+        // A rejection is CAPTURED rather than allowed to propagate from here.
+        // Letting it escape would abort the drain, the socket close, and the
+        // shutdown/close hooks, leaving an application that keeps serving — and
+        // because `#stopPromise` caches the result, one that can never be stopped
+        // at all. The error is still surfaced to the caller, but only after the
+        // shutdown it must not prevent has finished.
+        let stoppingError = null;
+        if (this.#lifecycle.hasStopping()) {
+            try {
+                await this.#lifecycle.runStopping();
+            }
+            catch (error) {
+                stoppingError = { cause: error };
+            }
+        }
+        // Set before the next await so a request arriving during the drain window
+        // sees the shutting-down state and gets a 503.
+        this.#stopping = true;
+        // Wait for in-flight requests to drain (max 10s). A successfully-started
+        // application always has a runtime registered (start() requires a runtime
+        // provider) and stop() short-circuits before this when never started, so
+        // the runtime is always available here.
+        await this.#drainRequests();
+        // Close server if listening
+        if (this.#serverHandle !== null) {
+            const adapter = this.#registry.get(CAPABILITIES.HTTP_ADAPTER);
+            await adapter.close(this.#serverHandle);
+            this.#serverHandle = null;
+        }
+        // Run shutdown hooks (LIFO)
+        await this.#lifecycle.runShutdown();
+        // Run close hooks
+        await this.#lifecycle.runClose();
+        // Surfaced last: the application is fully stopped by now, so the caller
+        // learns the stopping hook failed without that failure having blocked the
+        // shutdown.
+        if (stoppingError !== null) {
+            throw stoppingError.cause;
+        }
+    }
+    /** Delegates a web-standard Request to the registered IHttpAdapter. */
+    // Declared `async` so the no-adapter case REJECTS rather than throwing
+    // synchronously: this method returns a promise, and a sync throw escapes a
+    // caller's `.catch(…)` — including the `export default { fetch: app.fetch }`
+    // Workers entry point, where it would surface as an unhandled exception
+    // instead of a failed request.
+    async fetch(request) {
+        if (!this.#registry.has(CAPABILITIES.HTTP_ADAPTER)) {
+            throw new Error('No HTTP adapter registered. Call register(RuntimePlugin) or provide a custom IHttpAdapter.');
+        }
+        const adapter = this.#registry.get(CAPABILITIES.HTTP_ADAPTER);
+        return await adapter.fetch(request);
+    }
+    /** Synthesizes an inject request and runs it through the full pipeline. */
+    async inject(request) {
+        // Per-shape coercion (M95c §3.9): bytes verbatim, Blob awaited,
+        // URLSearchParams through its own serialisation, JSON only for a plain
+        // object — and a named refusal for anything else, since a JavaScript
+        // caller can still hand `inject()` a value the type cannot see.
+        const { bytes: bodyBytes, defaultContentType } = await coerceInjectBody(request.body);
+        // A COPY, never the caller's own `Headers`. The per-shape default below
+        // WRITES here, and reusing one `Headers` instance across two injected
+        // requests is ordinary in a test: the first request's `content-type` used
+        // to stick to the caller's object, so the second silently inherited it and
+        // `!headers.has('content-type')` then declined to set the right one — a
+        // JSON body following a form body arrived as a form. Same aliasing hazard
+        // the byte copy in `coerceInjectBody` guards, one field over; a handler
+        // mutating `ctx.request.headers` is now contained too.
+        const headers = new Headers(request.headers ?? {});
+        // The default is PER SHAPE: a URLSearchParams body defaulting to
+        // `application/json` would arrive as a non-form and the form parse would
+        // refuse the input this widening exists to carry; a `Uint8Array` or an
+        // `ArrayBuffer` gets NO default at all because only the caller knows its
+        // encoding; and a `Blob` declares its own through `.type` (M99c), the
+        // same header the platform sets for `new Request(url, { body: blob })`.
+        if (bodyBytes !== undefined && defaultContentType !== undefined && !headers.has('content-type')) {
+            headers.set('content-type', defaultContentType);
+        }
+        // Normalize relative paths to a full URL so createRequestContext can parse
+        // query params without throwing.  Only normalize paths starting with `/` —
+        // arbitrary strings like `'not-a-valid-url'` should still reach
+        // createRequestContext so its URL-parse failure is surfaced as a 400.
+        const fullUrl = request.url.startsWith('/') ? `http://localhost${request.url}` : request.url;
+        // An HTTP adapter attaches the undisturbed web `Request` as `IRequest.raw`,
+        // and the terminal handler reads it to decide a WebSocket upgrade or gRPC
+        // dispatch. Omitting it here would make `inject()` structurally unable to
+        // reach either path — the request would silently fall through to the 404
+        // and a test could never tell the difference.
+        //
+        // Built defensively: a malformed URL must still reach
+        // `createRequestContext`, whose parse failure is surfaced as a 400, rather
+        // than throwing out of `inject()` here.
+        let raw;
+        try {
+            // A second copy, deliberately: `coerceInjectBody` already returned bytes
+            // the caller cannot alias, and this keeps `ctx.request.raw`'s body
+            // independent of the array `bytes()` hands the handler, so a handler that
+            // mutates what it read cannot change what `raw` reports. `inject()` is an
+            // in-process test entry point and the pre-M95c path re-encoded the body
+            // on every call, so the copy is not a regression.
+            const requestBody = bodyBytes === undefined ? undefined : new Uint8Array(bodyBytes);
+            raw = new Request(fullUrl, {
+                method: request.method,
+                headers,
+                ...(requestBody !== undefined && request.method !== 'GET' && request.method !== 'HEAD'
+                    ? { body: requestBody }
+                    : {}),
+            });
+        }
+        catch {
+            raw = undefined;
+        }
+        // The form read is memoized like `json()`'s: the in-flight promise is
+        // cached (a rejection with it), so two middleware reading the same
+        // injected body trigger one parse, and a body that is not a form keeps
+        // rejecting identically on a retry.
+        let form;
+        const syntheticRequest = {
+            method: request.method,
+            url: fullUrl,
+            get path() {
+                return new URL(fullUrl).pathname;
+            },
+            headers,
+            ...(raw !== undefined ? { raw } : {}),
+            json() {
+                // The shared parse (X37-1): a malformed body rejects with the
+                // `400`-branded MalformedRequestBodyError, so `inject()` observes the
+                // same failure the served path produces. The empty-body arm keeps its
+                // `{}` default — an in-process inject that sent no body is not a
+                // malformed body.
+                return Promise.resolve().then(() => parseJsonBody(bodyBytes === undefined ? '{}' : new TextDecoder().decode(bodyBytes)));
+            },
+            text() {
+                return Promise.resolve(bodyBytes === undefined ? '' : new TextDecoder().decode(bodyBytes));
+            },
+            bytes() {
+                return Promise.resolve(bodyBytes ?? new Uint8Array(0));
+            },
+            formData() {
+                // The shared parse (M94b): a non-form content-type rejects with the
+                // `415`-branded UnsupportedFormEncodingError, so an injected request
+                // observes what a served request observes. A `Uint8Array` or an
+                // `ArrayBuffer` sets NO default content type (M95c §3.9), so an
+                // injected multipart in those shapes must supply its own — exactly
+                // what a served request requires. A `Blob` supplies it from `.type`
+                // (M99c), as the platform does.
+                form ??= Promise.resolve().then(() => parseFormBody(bodyBytes ?? new Uint8Array(0), headers.get('content-type')));
+                return form;
+            },
+        };
+        const response = await this.#handleRequest(syntheticRequest);
+        const snapshot = response.snapshot();
+        // A streaming response cannot be presented as a `string` body without
+        // draining the live stream, which would consume it. Say so explicitly
+        // rather than reporting `body: null`, which reads as "empty response".
+        if (snapshot.streaming) {
+            throw new Error('inject() cannot read a streaming response body. Call app.fetch() with a web Request ' +
+                'and read the returned Response body stream instead.');
+        }
+        // Decode a byte body (from `response.send(bytes)`) rather than dropping it:
+        // reporting `null` made a non-empty response look empty, and made `json()`
+        // throw "No JSON body available" for a perfectly valid JSON payload sent
+        // as bytes.
+        const body = snapshot.body === null
+            ? null
+            : typeof snapshot.body === 'string'
+                ? snapshot.body
+                : new TextDecoder().decode(snapshot.body);
+        return {
+            statusCode: snapshot.status,
+            headers: snapshot.headers,
+            body,
+            json() {
+                if (body === null) {
+                    throw new Error('No JSON body available');
+                }
+                return JSON.parse(body);
+            },
+        };
+    }
+    // ---------------------------------------------------------------------------
+    // Private methods
+    // ---------------------------------------------------------------------------
+    #handleRequest(request) {
+        if (this.#stopping) {
+            const builder = new ResponseBuilder();
+            // Pre-pipeline: no request context exists yet, so the responder (if any)
+            // is seeded from the startup cache — the same instance `errorHandler`
+            // would publish into `ctx.state` inside the pipeline — into the fresh
+            // state map (M70f re-review, finding 1). With no `errorHandler` the
+            // cache is empty and the framework-default shape is written. The status
+            // is still written here, so metrics keep seeing 503.
+            const state = new Map();
+            if (this.#errorResponder !== undefined) {
+                state.set(ERROR_RESPONDER_STATE_KEY, this.#errorResponder);
+            }
+            respondWithError({ state, response: builder, ...this.#safeRequestTarget(request) }, { status: 503, title: 'Service Unavailable' });
+            return builder;
+        }
+        const runtime = this.#registry.get(CAPABILITIES.RUNTIME);
+        // Build the per-request context and validate the request path BEFORE
+        // entering in-flight accounting. Two client errors are caught here:
+        //   1. A malformed request URL makes `new URL()` throw. The throw is
+        //      caught wherever it surfaces rather than at one assumed site: the
+        //      context resolves its query lazily (M87), so construction no longer
+        //      parses the URL, and for an `inject()`-built request `path` is itself
+        //      a lazy getter that parses. Reading `path` inside the `try` covers
+        //      both, and the adapter path throws earlier still, in its own mapping.
+        //   2. A malformed percent-escape in the path (e.g. `%zz`) would
+        //      otherwise surface as a 500 from the router's decodeURIComponent.
+        // Both are rejected as a 400. Because #inFlight is incremented only
+        // AFTER this succeeds, a rejected request can never leak the counter and
+        // stall shutdown drain (the throw would otherwise escape the finally).
+        let handle;
+        let path;
+        try {
+            handle = createRequestContext(request, this.#registry, runtime);
+            path = handle.ctx.request.path;
+        }
+        catch {
+            return this.#badRequest(request);
+        }
+        if (!isPathDecodable(path)) {
+            return this.#badRequest(request);
+        }
+        const ctx = handle.ctx;
+        // Seed the application's resolved error responder into the fresh context
+        // BEFORE the request-lifecycle hooks run (M70f re-review, finding 2). The
+        // hooks execute before the middleware pipeline, so `errorHandler`'s own
+        // `ctx.state` publication has not happened yet: without this seed, a
+        // throwing `onRequest` hook would fall through to the no-handler fallback
+        // even when an `errorHandler` is registered. `errorHandler` re-publishes
+        // the SAME instance inside the pipeline, so the per-request set is
+        // idempotent and in-pipeline sites are unaffected.
+        if (this.#errorResponder !== undefined) {
+            ctx.state.set(ERROR_RESPONDER_STATE_KEY, this.#errorResponder);
+        }
+        // The request operation is keyed in the collector's private WeakMap —
+        // never in application state, never a caller-supplied id.
+        this.#collector?.beginRequestOperation(ctx);
+        this.#inFlight++;
+        try {
+            const pending = this.#runRequest(ctx, handle, path, request);
+            if (pending === undefined) {
+                this.#inFlight--;
+                this.#completeRequest(ctx, 'ok');
+                return ctx.response;
+            }
+            return pending.then(() => {
+                this.#inFlight--;
+                this.#completeRequest(ctx, 'ok');
+                return ctx.response;
+            }, (error) => this.#failRequest(error, ctx));
+        }
+        catch (error) {
+            return this.#failRequest(error, ctx);
+        }
+    }
+    /**
+     * Emits the request operation's completion record. Reading the status AFTER
+     * the response is final keeps the record honest about what was served; the
+     * operation is unkeyed inside the collector, so a double completion cannot
+     * occur.
+     *
+     * @param ctx - The live request context
+     * @param outcome - How the request completed
+     */
+    #completeRequest(ctx, outcome) {
+        this.#collector?.endRequestOperation(ctx, {
+            outcome,
+            statusCode: ctx.response.statusCode,
+        });
+    }
+    /**
+     * Runs the request body, returning `undefined` when it completed
+     * SYNCHRONOUSLY and a promise otherwise (M87).
+     *
+     * The framework's own layers are the ones being made sync-capable here:
+     * an application registering no lifecycle hooks and no global middleware
+     * previously still paid the full `async`/`await` machinery of this method,
+     * `MiddlewarePipeline.execute` and `executeChain` — several microtask
+     * boundaries per request before any user code ran. Returning `undefined`
+     * rather than a resolved promise is what lets the caller, and ultimately
+     * the HTTP adapter, hand a plain `Response` back to the server: node's
+     * `responseViaCache` fast path is gated on the handler NOT returning a
+     * promise, so a single eagerly-async link anywhere in the chain forecloses
+     * it for every request.
+     *
+     * @param ctx - The live request context
+     * @param handle - The context handle, for installing matched route params
+     * @param path - The request path, already resolved and validated
+     * @param request - The normalized request
+     * @returns `undefined` when complete, else a promise that settles when it is
+     */
+    #runRequest(ctx, handle, path, request) {
+        const requestHooks = this.#lifecycle.getRequestHooks();
+        const responseHooks = this.#lifecycle.getResponseHooks();
+        // `compile()` caches, so this is a null check after the first request.
+        const chain = this.#pipeline.compile();
+        if (requestHooks.length === 0 && responseHooks.length === 0 && chain.length === 0) {
+            return this.#dispatch(ctx, handle, path, request);
+        }
+        return this.#runRequestFull(ctx, handle, path, request, requestHooks, responseHooks);
+    }
+    /**
+     * The general request path: lifecycle hooks and/or global middleware are
+     * registered, so at least one `await` is unavoidable.
+     *
+     * @param ctx - The live request context
+     * @param handle - The context handle, for installing matched route params
+     * @param path - The request path, already resolved and validated
+     * @param request - The normalized request
+     * @param requestHooks - Resolved `onRequest` hooks
+     * @param responseHooks - Resolved `onResponse` hooks
+     */
+    async #runRequestFull(ctx, handle, path, request, requestHooks, responseHooks) {
+        const parentOperationId = this.#collector?.requestOperationIdOf(ctx);
+        for (const hook of requestHooks) {
+            await this.#observeRequestStage('request-hook', parentOperationId, () => hook(ctx));
+        }
+        // Execute pipeline with route dispatch as terminal, observing each global
+        // stage's completion when diagnostics are enabled.
+        await this.#pipeline.execute(ctx, async () => {
+            await this.#dispatch(ctx, handle, path, request);
+        }, this.#chainObserver('global', parentOperationId, undefined));
+        for (const hook of responseHooks) {
+            await this.#observeRequestStage('response-hook', parentOperationId, () => hook(ctx));
+        }
+    }
+    /**
+     * Runs one request-scoped hook (`onRequest`/`onResponse`/`onError`),
+     * observing its completion when diagnostics are enabled. Absent collector —
+     * or no request operation, which cannot happen on a reached path — this is
+     * a bare `await`, so the disabled path is unchanged.
+     *
+     * @param stage - Which hook boundary this is
+     * @param parentOperationId - The request operation, when known
+     * @param run - The hook invocation
+     */
+    async #observeRequestStage(stage, parentOperationId, run) {
+        const collector = this.#collector;
+        if (collector === undefined || parentOperationId === undefined) {
+            await run();
+            return;
+        }
+        const startedAtMs = collector.monotonicMs();
+        try {
+            await run();
+        }
+        catch (error) {
+            collector.observeRequestStage({
+                parentOperationId,
+                stage,
+                outcome: 'error',
+                startedAtMs,
+                durationMs: collector.elapsedSince(startedAtMs),
+            });
+            throw error;
+        }
+        collector.observeRequestStage({
+            parentOperationId,
+            stage,
+            outcome: 'ok',
+            startedAtMs,
+            durationMs: collector.elapsedSince(startedAtMs),
+        });
+    }
+    /**
+     * Builds the chain observer for one chain execution (global or route).
+     * `undefined` when diagnostics are disabled, which keeps the executor's
+     * instrumented path byte-identical to the original one.
+     *
+     * @param scope - Which chain the observer instruments
+     * @param parentOperationId - The request operation the stages belong to
+     * @param routeEntryIndex - The matched route's entry index (route chains)
+     */
+    #chainObserver(scope, parentOperationId, routeEntryIndex) {
+        const collector = this.#collector;
+        if (collector === undefined) {
+            return undefined;
+        }
+        return {
+            clock: () => collector.monotonicMs(),
+            onStage: (stage) => {
+                collector.observeMiddlewareStage({
+                    parentOperationId: parentOperationId ?? '<unkeyed>',
+                    scope,
+                    position: stage.position,
+                    routeEntryIndex,
+                    outcome: stage.outcome,
+                    startedAtMs: stage.startedAtMs,
+                    durationMs: stage.durationMs,
+                });
+            },
+        };
+    }
+    /**
+     * Terminal dispatch: protocol switch first, then HTTP route matching.
+     *
+     * Protocol dispatch runs BEFORE route matching, and after the pipeline.
+     *
+     * "After the pipeline" is the M70a security property: auth, metrics and the
+     * shutdown drain apply to an upgrade and to an RPC exactly as they do to a
+     * `GET /users`.
+     *
+     * "Before route matching" is precedence, and it is not optional. A WebSocket
+     * upgrade is a protocol switch rather than an HTTP route, and a path inside
+     * the gRPC `basePath` belongs to gRPC (M49). Deciding these only when
+     * nothing matched lets ANY catch-all shadow both — and `react-router-plugin`
+     * mounts exactly that, on all seven verbs, for SSR: a full-stack application
+     * would answer a WebSocket client with an HTML page and a gRPC client with
+     * the same.
+     *
+     * Both helpers open with the same two SYNCHRONOUS refusals — no raw
+     * `Request`, or the capability is not registered — but both are `async`, so
+     * an application registering neither still paid a promise allocation and a
+     * microtask apiece on every request (M87). Hoisting those refusals to a
+     * synchronous guard preserves the outcome exactly: absent the token, each
+     * call returned `false` regardless.
+     *
+     * @param ctx - The live request context
+     * @param handle - The context handle, for installing matched route params
+     * @param path - The request path, already resolved and validated
+     * @param request - The normalized request
+     * @returns `undefined` when complete, else a promise that settles when it is
+     */
+    #dispatch(ctx, handle, path, request) {
+        if (ctx.raw !== undefined &&
+            (this.#registry.has(CAPABILITIES.WEBSOCKET) || this.#registry.has(CAPABILITIES.GRPC))) {
+            return this.#dispatchProtocol(ctx, handle, path, request);
+        }
+        return this.#dispatchRoute(ctx, handle, path, request);
+    }
+    /**
+     * Protocol dispatch for an application that registered WebSocket or gRPC,
+     * falling through to HTTP route matching when neither claims the request.
+     *
+     * @param ctx - The live request context
+     * @param handle - The context handle, for installing matched route params
+     * @param path - The request path, already resolved and validated
+     * @param request - The normalized request
+     */
+    async #dispatchProtocol(ctx, handle, path, request) {
+        if (this.#registry.has(CAPABILITIES.WEBSOCKET) &&
+            await this.#observeProtocol(ctx, 'websocket-upgrade', () => this.#tryUpgrade(ctx))) {
+            return;
+        }
+        if (this.#registry.has(CAPABILITIES.GRPC) &&
+            await this.#observeProtocol(ctx, 'grpc-dispatch', () => this.#tryGrpc(ctx))) {
+            return;
+        }
+        await this.#dispatchRoute(ctx, handle, path, request);
+    }
+    /**
+     * Observes one protocol-dispatch boundary (WebSocket upgrade or gRPC
+     * dispatch). A boundary that claims the request records its completion —
+     * never a claim about subsequent socket frames or RPC internals — and a
+     * thrown boundary records `error` and propagates unchanged.
+     *
+     * @param ctx - The live request context
+     * @param stage - Which protocol boundary is being attempted
+     * @param run - The boundary attempt, answering `true` when it claimed the request
+     * @returns The attempt's answer, unchanged
+     */
+    async #observeProtocol(ctx, stage, run) {
+        const collector = this.#collector;
+        if (collector === undefined) {
+            return await run();
+        }
+        const parentOperationId = collector.requestOperationIdOf(ctx) ?? '<unkeyed>';
+        const startedAtMs = collector.monotonicMs();
+        try {
+            const answered = await run();
+            if (answered) {
+                collector.observeHandlerStage({
+                    parentOperationId,
+                    stage,
+                    nodeId: null,
+                    outcome: 'ok',
+                    startedAtMs,
+                    durationMs: collector.elapsedSince(startedAtMs),
+                    statusCode: ctx.response.statusCode,
+                });
+            }
+            return answered;
+        }
+        catch (error) {
+            collector.observeHandlerStage({
+                parentOperationId,
+                stage,
+                nodeId: null,
+                outcome: 'error',
+                startedAtMs,
+                durationMs: collector.elapsedSince(startedAtMs),
+            });
+            throw error;
+        }
+    }
+    /**
+     * HTTP route matching and handler invocation.
+     *
+     * Matching reuses the path resolved by the caller rather than parsing the
+     * URL a second time (M87): the adapter's mapping already parsed it, and the
+     * decodability guard already read it, so `path` is `url.pathname` by
+     * construction on the adapter path and on the `inject()` path alike.
+     *
+     * @param ctx - The live request context
+     * @param handle - The context handle, for installing matched route params
+     * @param path - The request path, already resolved and validated
+     * @param request - The normalized request
+     * @returns `undefined` when complete, else a promise that settles when it is
+     */
+    #dispatchRoute(ctx, handle, path, request) {
+        const routeResult = this.#router.match(request.method, path);
+        if (routeResult === null) {
+            respondWithError(ctx, { status: 404, title: 'Not Found' });
+            return undefined;
+        }
+        // Install matched params via the internal setter (no readonly cast)
+        const { definition, params, entry } = routeResult;
+        handle.setParams(params);
+        // Route middleware uses the same next()-chaining semantics as the global
+        // pipeline: a stage that responds without calling next() short-circuits,
+        // and the handler does not run. Defense-in-depth in executeChain also
+        // stops stages after the response is ended. Positions follow the route's
+        // own middleware array; the terminal observes the handler itself.
+        const routeMiddleware = definition.middleware;
+        if (routeMiddleware !== undefined && routeMiddleware.length > 0) {
+            return executeChain(routeMiddleware, ctx, async () => {
+                await this.#observeHandler(ctx, entry, async () => {
+                    await definition.handler(ctx);
+                });
+            }, undefined, this.#chainObserver('route', this.#collector?.requestOperationIdOf(ctx), entry.index));
+        }
+        // Empty-chain bypass (M87). On an empty chain `executeChain` does exactly
+        // one thing before the terminal: the defense-in-depth `ended` check, which
+        // matters because a global stage may have ended the response AND called
+        // `next()`. Keeping that check and invoking the handler directly is
+        // behaviourally identical, and it removes the executor's two closures and
+        // three microtask boundaries from every route declaring no middleware.
+        if (ctx.response.ended) {
+            return undefined;
+        }
+        return this.#invokeHandlerObserved(ctx, entry, definition);
+    }
+    /**
+     * Invokes a route's handler on the empty-chain bypass, observing its
+     * completion when diagnostics are enabled WITHOUT changing the bypass's
+     * synchronous contract: a sync handler still returns `undefined` from this
+     * method and an async one still returns its promise.
+     *
+     * @param ctx - The live request context
+     * @param entry - The matched route entry, naming the handler's node
+     * @param definition - The route definition holding the handler
+     * @returns `undefined` when complete synchronously, else the handler's promise
+     */
+    #invokeHandlerObserved(ctx, entry, definition) {
+        const collector = this.#collector;
+        if (collector === undefined) {
+            const result = definition.handler(ctx);
+            // Duck-typed, not `instanceof Promise`: a cross-realm or userland promise
+            // satisfies `RouteHandler`'s declared return type structurally but fails
+            // `instanceof`, and treating one as "already finished" would send the
+            // response while the handler was still running (M87 review).
+            // `Promise.resolve` returns a native promise unchanged, so the ordinary
+            // async path allocates nothing extra.
+            return isPromiseLike(result) ? Promise.resolve(result) : undefined;
+        }
+        const parentOperationId = collector.requestOperationIdOf(ctx) ?? '<unkeyed>';
+        const nodeId = collector.routeNodeIdOf(entry.index) ?? null;
+        const startedAtMs = collector.monotonicMs();
+        let result;
+        try {
+            result = definition.handler(ctx);
+        }
+        catch (error) {
+            collector.observeHandlerStage({
+                parentOperationId,
+                stage: 'handler',
+                nodeId,
+                outcome: 'error',
+                startedAtMs,
+                durationMs: collector.elapsedSince(startedAtMs),
+            });
+            throw error;
+        }
+        if (isPromiseLike(result)) {
+            const pending = Promise.resolve(result);
+            // Observation only: the ORIGINAL promise is returned to the caller and
+            // its rejection propagates unchanged — this detached chain never
+            // swallows or re-routes it.
+            void pending.then(() => {
+                collector.observeHandlerStage({
+                    parentOperationId,
+                    stage: 'handler',
+                    nodeId,
+                    outcome: 'ok',
+                    startedAtMs,
+                    durationMs: collector.elapsedSince(startedAtMs),
+                    statusCode: ctx.response.statusCode,
+                });
+            }, () => {
+                collector.observeHandlerStage({
+                    parentOperationId,
+                    stage: 'handler',
+                    nodeId,
+                    outcome: 'error',
+                    startedAtMs,
+                    durationMs: collector.elapsedSince(startedAtMs),
+                });
+            });
+            return pending;
+        }
+        collector.observeHandlerStage({
+            parentOperationId,
+            stage: 'handler',
+            nodeId,
+            outcome: 'ok',
+            startedAtMs,
+            durationMs: collector.elapsedSince(startedAtMs),
+            statusCode: ctx.response.statusCode,
+        });
+        return undefined;
+    }
+    /**
+     * Runs the route chain's terminal handler, observing its completion when
+     * diagnostics are enabled. The terminal is already async, so observation
+     * adds no new microtask boundary to the disabled path.
+     *
+     * @param ctx - The live request context
+     * @param entry - The matched route entry, naming the handler's node
+     * @param run - The handler invocation
+     */
+    async #observeHandler(ctx, entry, run) {
+        const collector = this.#collector;
+        if (collector === undefined) {
+            await run();
+            return;
+        }
+        const parentOperationId = collector.requestOperationIdOf(ctx) ?? '<unkeyed>';
+        const nodeId = collector.routeNodeIdOf(entry.index) ?? null;
+        const startedAtMs = collector.monotonicMs();
+        try {
+            await run();
+            collector.observeHandlerStage({
+                parentOperationId,
+                stage: 'handler',
+                nodeId,
+                outcome: 'ok',
+                startedAtMs,
+                durationMs: collector.elapsedSince(startedAtMs),
+                statusCode: ctx.response.statusCode,
+            });
+        }
+        catch (error) {
+            collector.observeHandlerStage({
+                parentOperationId,
+                stage: 'handler',
+                nodeId,
+                outcome: 'error',
+                startedAtMs,
+                durationMs: collector.elapsedSince(startedAtMs),
+            });
+            throw error;
+        }
+    }
+    /**
+     * Failure path: runs `onError` hooks, reports, and writes the opaque 500.
+     *
+     * Stays synchronous when no `onError` hook is registered, so a throwing
+     * handler in a hook-free application does not force the whole request onto
+     * the microtask queue (M87).
+     *
+     * A hook that throws must not stop the remaining hooks from running, but its
+     * failure must not vanish either: an audit logger, telemetry collector, or
+     * transaction-rollback hook that fails silently leaves security
+     * infrastructure blind. Suppressed errors are surfaced through the
+     * sanctioned logger channel.
+     *
+     * @param error - The thrown value
+     * @param ctx - The live request context
+     * @returns The response, directly or once the hooks have run
+     */
+    #failRequest(error, ctx) {
+        const err = error instanceof Error ? error : new Error(String(error));
+        const hooks = this.#lifecycle.getErrorHooks();
+        if (hooks.length === 0) {
+            return this.#finishFailure(err, ctx);
+        }
+        const parentOperationId = this.#collector?.requestOperationIdOf(ctx);
+        return (async () => {
+            for (const hook of hooks) {
+                try {
+                    await this.#observeRequestStage('error-hook', parentOperationId, () => hook(err, ctx));
+                }
+                catch (hookError) {
+                    this.#reportSuppressedHookError(hookError);
+                }
+            }
+            return this.#finishFailure(err, ctx);
+        })();
+    }
+    /**
+     * Reports the unhandled error and writes the opaque 500, closing out the
+     * request's in-flight accounting.
+     *
+     * X11-2: the unhandled error is visible to the operator. The body stays
+     * opaque — the message is not disclosed to the client (M70b's
+     * `maskInternalErrors` decision applied consistently); only the log carries
+     * it.
+     *
+     * @param err - The normalized error
+     * @param ctx - The live request context
+     * @returns The response builder carrying the 500
+     */
+    #finishFailure(err, ctx) {
+        // Decrement FIRST: the original body did this in a `finally`, so a throw
+        // from the reporting or responder call could not leak the counter and
+        // stall the shutdown drain. Ordering it ahead of both preserves that.
+        this.#inFlight--;
+        this.#reportUnhandledError(err, ctx);
+        respondWithError(ctx, { status: 500, title: 'Internal Server Error' });
+        // Recorded AFTER the response is final, so the status in the record is
+        // the status that was actually served.
+        this.#completeRequest(ctx, 'error');
+        return ctx.response;
+    }
+    /**
+     * Tries a WebSocket upgrade after the middleware pipeline and before route
+     * matching when the request carries a raw `Request`. Consults the
+     * `IWebSocketService`'s upgrade router; when it accepts, brands the
+     * `IRequest` with the intent so the HTTP adapter can perform the handshake
+     * after the framework handler returns.
+     *
+     * The brand goes on the `IRequest`, not `ctx.state`, because the adapter
+     * holds the former and never sees the context — see {@linkcode
+     * UPGRADE_INTENT}.
+     *
+     * @param ctx - The live request context
+     * @returns `true` when this handler answered (intent recorded, or refused)
+     */
+    async #tryUpgrade(ctx) {
+        const raw = ctx.raw;
+        // A custom adapter may omit `raw`; treat that as "no upgrade" and fall
+        // through to the 404 rather than throwing.
+        if (raw === undefined) {
+            return false;
+        }
+        // Resolved optionally — absent the capability, nothing changes. Probed with
+        // `has` rather than a try/catch around `get`, because this now runs on
+        // EVERY request rather than only on an unmatched one, and throw-driven
+        // control flow on the hot path is what AI_GUIDELINES §14 exists to stop.
+        if (!this.#registry.has(CAPABILITIES.WEBSOCKET)) {
+            return false;
+        }
+        const wsService = this.#registry.get(CAPABILITIES.WEBSOCKET);
+        if (wsService.routeUpgrade === undefined) {
+            return false;
+        }
+        // Upgrade detection is the ROUTER's job, not the kernel's — it returns
+        // `null` for anything that is not an upgrade on a route it owns. Doing the
+        // header check here as well would duplicate the rule (§11.1) and, worse,
+        // would move a throwing header read outside the service's own reporting
+        // wrapper, so a routing failure would be logged nowhere.
+        //
+        // This backstop is for a third-party service that does not report: before
+        // M70a the adapter-side `UpgradeRouterStore` caught here, and letting a
+        // routing bug escape into the generic 500 would lose the distinction
+        // between "routing failed" and "the handler threw".
+        let decision;
+        try {
+            // The pipeline has already run (line 643, above), so `ctx.request.user`
+            // carries whatever the authentication band produced. The parameter is
+            // optional on the contract (M73 §3.7): a service written before the
+            // widening simply never receives it.
+            decision = await wsService.routeUpgrade(raw, ctx.request.user);
+        }
+        catch (cause) {
+            // Reported, not swallowed. The pre-M70a backstop in the adapter's
+            // `UpgradeRouterStore` discarded the cause because the adapter holds no
+            // logger; the kernel does, so silence here would be a choice rather than
+            // a constraint.
+            this.#reportUpgradeRouterFailure(cause);
+            respondWithError(ctx, { status: 500, title: 'Internal Server Error' });
+            return true;
+        }
+        if (decision === null) {
+            return false;
+        }
+        if (!decision.accept) {
+            respondWithError(ctx, { status: decision.status, title: 'Upgrade rejected' });
+            return true;
+        }
+        // RFC 6455 §4.1 forbids a body on the handshake. Refusing here makes the
+        // behaviour one thing on all four adapters rather than a runtime-specific
+        // failure inside the upgrade call. Read from the MAPPED body rather than
+        // `content-length`, which is absent both on an in-process `Request` and on
+        // any chunked upload.
+        //
+        // This comment previously also claimed the mapping "has already disturbed
+        // it via `arrayBuffer()`". That is no longer true and the distinction is
+        // load-bearing (M87): the mapping reads the body lazily, and `bytes()`
+        // short-circuits a GET/HEAD carrying neither `content-length` nor
+        // `transfer-encoding` WITHOUT touching the native request. So an ordinary
+        // upgrade now reaches the handshake with its raw `Request` undisturbed —
+        // which is exactly what `Deno.upgradeWebSocket` requires, and the hazard
+        // M46 originally had to intercept the upgrade inside the adapter to avoid.
+        // A handshake that does carry framing headers is disturbed by this read
+        // and then refused below, so no upgrade is ever attempted on it.
+        //
+        // The read itself can REJECT, not merely return a non-empty body:
+        // `RuntimePlugin({ maxBodyBytes })` bounds it, and a body past the cap
+        // rejects with `RequestBodyTooLargeError`. The read is therefore wrapped in
+        // a `try` whose `catch` settles the reserved slot before rethrowing — it is
+        // the only call between the router's accept and `setUpgradeIntent` that can
+        // throw, so nothing else needs the same treatment. Without it a rejection
+        // escapes to the
+        // fallback 500 with `onClose` never called, and since the router claims a
+        // pending slot at accept time, `maxConnections` malformed requests from an
+        // unauthenticated client permanently exhaust the budget — every later
+        // conformant upgrade then gets 503. `websocket-service.ts` states that a
+        // "refused or malformed upgrade can never leak a slot"; this is what makes
+        // that true for a rejecting read as well as a returning one.
+        let bodyLength;
+        try {
+            bodyLength = (await ctx.request.bytes()).length;
+        }
+        catch (cause) {
+            decision.sink.onClose({ code: 1006, reason: 'Upgrade request body could not be read' });
+            // Re-thrown rather than answered here: the body-limit refusal carries its
+            // own status hint (413), and `errorHandler` is what turns that into a
+            // response in the application's configured format. Answering a fixed 400
+            // would discard the hint and report the wrong cause.
+            throw cause;
+        }
+        if (bodyLength > 0) {
+            // The router already accepted, so it may be holding a reserved
+            // connection slot for this socket. RFC 6455 close code 1006 (abnormal
+            // closure) is the honest signal that no connection was ever established.
+            decision.sink.onClose({ code: 1006, reason: 'Upgrade request carried a body' });
+            respondWithError(ctx, { status: 400, title: 'Bad Request' });
+            return true;
+        }
+        setUpgradeIntent(ctx.request, {
+            sink: decision.sink,
+            ...(decision.protocol !== undefined ? { protocol: decision.protocol } : {}),
+        });
+        return true;
+    }
+    /**
+     * Tries gRPC dispatch after the middleware pipeline and before route
+     * matching. Resolves `IGrpcService` from the registry, asks whether it
+     * claims the path, and dispatches with a reconstructed web `Request`.
+     *
+     * @param ctx - The live request context
+     * @returns `true` when gRPC answered (handler should return)
+     */
+    async #tryGrpc(ctx) {
+        const raw = ctx.raw;
+        if (raw === undefined) {
+            return false;
+        }
+        // Resolved optionally — absent the capability, nothing changes. `has`
+        // rather than a try/catch around `get`, for the reason given in
+        // `#tryUpgrade`.
+        if (!this.#registry.has(CAPABILITIES.GRPC)) {
+            return false;
+        }
+        const grpcService = this.#registry.get(CAPABILITIES.GRPC);
+        if (!grpcService.available) {
+            return false;
+        }
+        // Prefix guard, BEFORE dispatch. `handleRequest` returns `Promise<Response>`
+        // and never `null`, so without this every unmatched route in the
+        // application would be answered by gRPC's plain-text 404 instead of the
+        // kernel's own JSON one. An implementor that predates `claims` claims
+        // nothing, which is the safe default.
+        if (grpcService.claims === undefined || !grpcService.claims(raw)) {
+            return false;
+        }
+        // A refusal decidable from HEADERS is answered BEFORE the body is read,
+        // and the ordering is the fix rather than an optimisation (V5-5). A
+        // native `application/grpc` request is refused whatever its body holds,
+        // but a client-streaming or bidirectional call holds its request stream
+        // OPEN — so the read below never resolves and the caller receives no
+        // frames at all instead of the refusal. `grpcurl` opens a bidirectional
+        // reflection stream first, so it hung on every request, which is why
+        // M70i's refusal being correct did not help.
+        //
+        // The kernel does not decide WHAT is refusable: the content types are the
+        // plugin's to know (an exact-match set — `startsWith('application/grpc')`
+        // would also claim `application/grpc-web+proto`, the format that works),
+        // and §2.2 forbids importing it to find out.
+        const refusal = grpcService.refuses?.(raw) ?? null;
+        if (refusal !== null) {
+            await this.#sendRpcResponse(ctx, refusal);
+            return true;
+        }
+        // Reconstruct a web Request from the mapped IRequest. Trailers do not
+        // survive the round trip — M49 records that native gRPC-binary trailers
+        // work on no runtime this plugin runs on.
+        //
+        // This read is what bounds the dispatch to requests whose body ENDS.
+        // Since M87 the mapping is lazy, so the body is still unread here and the
+        // buffering is this line's own doing, not something already spent — the
+        // comment that used to say otherwise predated that change. Passing `raw`
+        // straight through would preserve streaming, but only while nothing in
+        // the pipeline has read the body, and the kernel cannot see whether
+        // anything has; that is left as a named limitation rather than a guess.
+        const bodyBytes = await ctx.request.bytes();
+        const grpcRequest = new Request(ctx.request.url, {
+            method: ctx.request.method,
+            headers: ctx.request.headers,
+            // A `Uint8Array` is a valid `BodyInit`, but its backing `ArrayBufferLike`
+            // is not narrowed to `ArrayBuffer` under this compiler configuration.
+            ...(bodyBytes.length > 0 ? { body: bodyBytes } : {}),
+        });
+        const response = await grpcService.handleRequest(grpcRequest);
+        await this.#sendRpcResponse(ctx, response);
+        return true;
+    }
+    /**
+     * Writes an RPC {@linkcode Response} onto the framework response.
+     *
+     * One implementation for both exits — the header-only refusal and a
+     * dispatched reply — so a refusal cannot come to carry different headers or
+     * a different status mapping from an ordinary answer.
+     *
+     * @param ctx - The request context whose response is written
+     * @param response - The RPC response to copy across
+     */
+    async #sendRpcResponse(ctx, response) {
+        const snapshot = await response.arrayBuffer();
+        const builder = ctx.response;
+        builder.status(response.status);
+        // `appendHeader`, not `header`: `header` delegates to `Headers.set`, and a
+        // Trailers-Only refusal or a Connect reply can carry repeated headers —
+        // `Set-Cookie` above all, which `Headers.entries()` yields once per value
+        // rather than comma-joining. Setting per entry would keep only the last.
+        for (const [key, value] of response.headers.entries()) {
+            builder.appendHeader(key, value);
+        }
+        builder.send(new Uint8Array(snapshot));
+    }
+    /**
+     * Reads the application's resolved error responder off the compiled pipeline
+     * (M70f re-review, findings 1 & 2).
+     *
+     * `errorHandler` brands its middleware function with the responder it built
+     * at factory time (see `brandErrorResponder` in `@setu-ts/common`). The
+     * kernel caches that instance at startup so the pre-pipeline sites — which
+     * run before the pipeline and cannot read `ctx.state` — can seed it into
+     * their state. The LAST branded stage in execution order (the innermost,
+     * i.e. the highest priority number among the selected stages) wins,
+     * because that is the stage whose `ctx.state` publication an in-pipeline
+     * site would see last. `undefined`
+     * when no `errorHandler` is registered, in which case every site keeps the
+     * byte-identical no-handler fallback.
+     *
+     * @param chain - The compiled middleware chain, in execution order
+     */
+    #resolveErrorResponder(chain) {
+        let responder;
+        for (const stage of chain) {
+            // Every compiled stage is a middleware function; `errorResponderOf`
+            // reads a brand off it, so narrow `unknown` to `object` first.
+            if (typeof stage !== 'function') {
+                continue;
+            }
+            const branded = errorResponderOf(stage);
+            if (branded !== undefined) {
+                responder = branded;
+            }
+        }
+        return responder;
+    }
+    /**
+     * Builds a bare `400 Bad Request` response for a client error detected
+     * before request processing begins (a malformed request URL or a
+     * malformed percent-escape in the path). Kept as a helper so both
+     * rejection sites in {@linkcode Application.#handleRequest} produce an
+     * identical body.
+     *
+     * Pre-pipeline: no request context exists yet, so the responder is seeded
+     * from the startup cache ({@linkcode Application.#errorResponder}) into the
+     * fresh state map — the same responder `errorHandler` would publish into
+     * `ctx.state` were this site inside the pipeline. With no `errorHandler`
+     * registered the cache is empty and the framework-default shape is written.
+     *
+     * The target carries a SAFE request ({@linkcode Application.#safeRequestTarget}),
+     * never the raw one: a malformed request URL keeps a throwing `path` getter
+     * on the synthetic `IRequest`, and a Problem Details formatter that reads
+     * `ctx.request.path` for the `instance` member would throw the URL parser
+     * error again inside the responder — turning the configured 400 back into an
+     * unhandled `TypeError: Invalid URL` (M70f re-review round 2, finding 1).
+     */
+    #badRequest(request) {
+        const builder = new ResponseBuilder();
+        const state = new Map();
+        if (this.#errorResponder !== undefined) {
+            state.set(ERROR_RESPONDER_STATE_KEY, this.#errorResponder);
+        }
+        respondWithError({ state, response: builder, ...this.#safeRequestTarget(request) }, { status: 400, title: 'Bad Request' });
+        return builder;
+    }
+    /**
+     * Builds the `request` member of a pre-pipeline {@linkcode respondWithError}
+     * target from a request whose path may be unreadable.
+     *
+     * A formatted error response needs the request path for the Problem Details
+     * `instance` member, and the target's `request` field is typed to supply it.
+     * But a request that failed URL parsing carries a `path` getter that throws
+     * (the synthetic `IRequest` in {@linkcode Application.inject} and the
+     * adapter-mapped requests both derive `path` from `new URL(...)`), so handing
+     * the raw request to the responder would make the formatter re-throw inside
+     * the very response that is supposed to report the failure.
+     *
+     * The safe target therefore carries the path only when it can be read
+     * without throwing — captured once, up front — and omits the `request` field
+     * entirely otherwise, which is the documented shape of
+     * {@linkcode ErrorResponderTarget.request} ("when one exists"). A formatter
+     * that receives no request answers without an `instance` member, which is
+     * the correct RFC 9457 outcome for a request whose path cannot be known.
+     *
+     * @param request - The request that failed pre-pipeline validation
+     * @returns `{ request: { path } }` when the path is readable, `{}` when it is not
+     */
+    #safeRequestTarget(request) {
+        let path;
+        try {
+            path = request.path;
+        }
+        catch {
+            path = undefined;
+        }
+        return path === undefined ? {} : { request: { path } };
+    }
+    /**
+     * Surfaces an exception thrown by an `IWebSocketService`'s upgrade router.
+     *
+     * The framework's own service reports its failures at their source, where it
+     * has route context to add; this covers a third-party service that does not.
+     * Guarded exactly like {@linkcode Application.#reportSuppressedHookError}: a
+     * missing or itself-broken logger must not turn a refused upgrade into a
+     * crashed request.
+     *
+     * @param cause - Whatever the router threw
+     */
+    #reportUpgradeRouterFailure(cause) {
+        try {
+            if (!this.#registry.has(CAPABILITIES.LOGGER)) {
+                return;
+            }
+            const logger = this.#registry.get(CAPABILITIES.LOGGER);
+            const err = cause instanceof Error ? cause : new Error(String(cause));
+            logger.error('WebSocket upgrade router threw and was refused', {
+                error: err.message,
+                stack: err.stack,
+            });
+        }
+        catch {
+            // No safe channel remains — see #reportSuppressedHookError.
+        }
+    }
+    /** Reports a startup-time registry mutation when logging is available. */
+    #reportRegistryMutation(kind, token, plugin) {
+        try {
+            if (!this.#registry.has(CAPABILITIES.LOGGER)) {
+                return;
+            }
+            const logger = this.#registry.get(CAPABILITIES.LOGGER);
+            const owner = plugin ?? 'the application';
+            const message = `Capability '${token}' was ${kind === 'override' ? 'overridden' : 'unregistered'} by ${owner}.`;
+            if (kind === 'override') {
+                logger.info(message);
+            }
+            else {
+                logger.warn(message);
+            }
+        }
+        catch {
+            // No safe channel remains — a mutation must not make startup fail.
+        }
+    }
+    /**
+     * Surfaces an exception thrown by an `onError` hook. The failure is
+     * reported through {@linkcode CAPABILITIES.LOGGER} when a logger is
+     * registered — the sanctioned framework logging channel (AI_GUIDELINES
+     * §11.6 forbids `console` here). The whole method is guarded so a missing
+     * or itself-broken logger can never propagate out of request handling: in
+     * that doubly-degraded case there is no safe channel left and the error is
+     * dropped rather than crashing the request.
+     */
+    #reportSuppressedHookError(hookError) {
+        try {
+            if (!this.#registry.has(CAPABILITIES.LOGGER)) {
+                return;
+            }
+            const logger = this.#registry.get(CAPABILITIES.LOGGER);
+            const err = hookError instanceof Error ? hookError : new Error(String(hookError));
+            logger.error('onError hook threw and was suppressed', {
+                error: err.message,
+                stack: err.stack,
+            });
+        }
+        catch {
+            // The logger itself failed or none is resolvable — no safe channel
+            // remains without violating the no-console rule; degrade silently.
+        }
+    }
+    /**
+     * Surfaces an unhandled request error through the sanctioned logger channel
+     * (X11-2). The response body stays opaque — the message is not disclosed to
+     * the client (M70b's `maskInternalErrors` decision applied consistently) —
+     * but the operator sees the message and stack, with the request identified.
+     *
+     * Guarded exactly like {@linkcode Application.#reportSuppressedHookError}: a
+     * missing or itself-broken logger must not turn an already-failing request
+     * into a crashed one.
+     *
+     * @param error - The unhandled error
+     * @param ctx - The request context it occurred in
+     */
+    #reportUnhandledError(error, ctx) {
+        try {
+            if (!this.#registry.has(CAPABILITIES.LOGGER)) {
+                return;
+            }
+            const logger = this.#registry.get(CAPABILITIES.LOGGER);
+            logger.error('Unhandled request error', {
+                ...serializeError(error),
+                requestId: ctx.id,
+                method: ctx.request.method,
+                path: ctx.request.path,
+            });
+        }
+        catch {
+            // The logger itself failed or none is resolvable — no safe channel
+            // remains without violating the no-console rule; degrade silently.
+        }
+    }
+    /**
+     * Emits a soft `warn`-level diagnostic for each capability a plugin declares
+     * in `consumes` that no registered plugin provides. Unlike a missing
+     * `dependencies` entry (which fails plugin resolution), an unsatisfied
+     * `consumes` does not stop startup — the plugin resolves the capability
+     * lazily at request time — but the deferred `services.get` would then throw
+     * per request, so surfacing it once at startup, naming the consumer, is the
+     * friendlier failure mode.
+     *
+     * Reported through {@linkcode CAPABILITIES.LOGGER} when a logger is
+     * registered — the sanctioned framework logging channel (AI_GUIDELINES §11.6
+     * forbids `console` here). The emission is guarded so a missing or
+     * itself-broken logger degrades silently rather than turning an advisory
+     * warning into a startup failure.
+     */
+    #warnUnsatisfiedConsumers() {
+        const unsatisfied = findUnsatisfiedConsumers(this.#plugins, (token) => this.#registry.has(token));
+        if (unsatisfied.length === 0) {
+            return;
+        }
+        try {
+            if (!this.#registry.has(CAPABILITIES.LOGGER)) {
+                return;
+            }
+            const logger = this.#registry.get(CAPABILITIES.LOGGER);
+            for (const { plugin, capability } of unsatisfied) {
+                logger.warn(`Plugin '${plugin}' consumes capability '${capability}', but no registered plugin provides it. ` +
+                    `Calls to services.get('${capability}') will fail at runtime — register a plugin that provides it.`, { plugin, capability });
+            }
+        }
+        catch {
+            // The logger itself failed or none is resolvable — no safe channel
+            // remains without violating the no-console rule; degrade silently.
+        }
+    }
+    #validateEnvironment(runtime) {
+        const violations = [];
+        for (const { name, spec } of this.#envSpecs) {
+            for (const [key, rules] of Object.entries(spec)) {
+                const value = runtime.env[key];
+                if (value === undefined) {
+                    if (rules.required && rules.default === undefined) {
+                        violations.push(`Required environment variable '${key}' is missing (declared by ${name}).`);
+                    }
+                    continue;
+                }
+                // Type coercion checks
+                if (rules.type === 'number') {
+                    // `Number('')`, `Number('   ')`, and other blank strings coerce to
+                    // 0 (not NaN), so an empty/whitespace value would otherwise pass as
+                    // a valid number. Reject blanks explicitly, and use `isFinite` so
+                    // `Infinity`/`-Infinity` are rejected too.
+                    const num = Number(value);
+                    if (value.trim() === '' || !Number.isFinite(num)) {
+                        violations.push(`Environment variable '${key}' expected number but got '${value}' (declared by ${name}).`);
+                    }
+                }
+                else if (rules.type === 'boolean') {
+                    if (value !== 'true' && value !== 'false') {
+                        violations.push(`Environment variable '${key}' expected boolean but got '${value}' (declared by ${name}).`);
+                    }
+                }
+            }
+        }
+        if (violations.length > 0) {
+            throw new Error(`Environment validation failed with ${violations.length} violation(s):\n` +
+                violations.map((v) => `  - ${v}`).join('\n'));
+        }
+    }
+    async #drainRequests() {
+        const runtime = this.#registry.get(CAPABILITIES.RUNTIME);
+        // Monotonic clock: this is a duration budget, so it must not be measured
+        // with `now()` (wall clock), which an NTP step can move backwards — cutting
+        // the drain short or extending it past the intended 10s.
+        const deadline = runtime.hrtime() + 10_000;
+        // Iteration cap: a manual test clock that never advances would otherwise
+        // spin forever (the deadline never arrives). 200 polls × 50ms ≈ 10s of
+        // real polling under a normal clock, and a hard ceiling regardless.
+        let polls = 0;
+        const MAX_POLLS = 200;
+        while (this.#inFlight > 0 && runtime.hrtime() < deadline && polls < MAX_POLLS) {
+            polls++;
+            // Poll via runtime.setTimeout (max 10s)
+            await new Promise((resolve) => {
+                runtime.setTimeout(() => resolve(), 50);
+            });
+        }
+    }
+}
+/**
+ * Creates a new kernel application instance.
+ *
+ * @param options - Optional application configuration including pre-registered plugins
+ * @returns The kernel application instance with inject() capability
+ * @example
+ * ```typescript
+ * import { createApplication } from '@setu-ts/kernel';
+ *
+ * const app = createApplication({
+ *   plugins: [RuntimePlugin()],
+ * });
+ *
+ * await app.start({ port: 3000 });
+ * ```
+ * @since 0.1.0
+ */
+export function createApplication(options) {
+    const app = new Application(options?.diagnostics);
+    if (options?.plugins) {
+        for (const plugin of options.plugins) {
+            app.register(plugin);
+        }
+    }
+    return app;
+}
+//# sourceMappingURL=application.js.map