@setu-ts/kernel 0.0.0-stage → 0.10.0

package/src/application/application.ts

@@ -0,0 +1,2326 @@
+/**
+ * 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 type {
+  CliCommandHandler,
+  DecoratorHandler,
+  EnvVarSpec,
+  FormBody,
+  HealthIndicatorFn,
+  IApplication,
+  IConfig,
+  IContainer,
+  IDiagnosticsSource,
+  IErrorResponder,
+  IHttpAdapter,
+  ILogger,
+  IMetadataStore,
+  IMiddlewareApi,
+  IPlugin,
+  IPluginContext,
+  IRequest,
+  IRequestContext,
+  IRouterApi,
+  IRuntimeServices,
+  ITelemetryService,
+  IWebSocketService,
+  MetricConfig,
+  RouteDefinition,
+  StartOptions,
+  WebSocketUpgradeDecision,
+} from '@setu-ts/common';
+import type { IGrpcService } from '@setu-ts/common';
+
+import { MiddlewarePipeline } from '../pipeline/middleware-pipeline.ts';
+import { executeChain } from '../pipeline/execute-chain.ts';
+import type { ChainObserver } from '../pipeline/execute-chain.ts';
+import { findUnsatisfiedConsumers, resolvePluginOrder } from '../registry/plugin-resolver.ts';
+import { ServiceRegistry } from '../registry/service-registry.ts';
+import { Router } from '../router/router.ts';
+import type { RouteEntry } from '../router/router.ts';
+import { isPathDecodable } from '../router/route-matcher.ts';
+import { LifecycleManager } from '../lifecycle/lifecycle-manager.ts';
+import { createRequestContext } from '../context/request-context.ts';
+import type { RequestContextHandle } from '../context/request-context.ts';
+import { coerceInjectBody } from './inject-body.ts';
+import { ResponseBuilder } from '../context/response.ts';
+import { DiagnosticsCollector } from '../diagnostics/collector.ts';
+import { compileLabelAllowlists } from '../diagnostics/projection.ts';
+import type {
+  KernelDiagnosticsLabelOptions,
+  KernelDiagnosticsOptions,
+} from '../diagnostics/projection.ts';
+import type {
+  DiagnosticsBatch,
+  DiagnosticsEventOutcome,
+  DiagnosticsSnapshot,
+} from '@setu-ts/common';
+
+export type { KernelDiagnosticsLabelOptions, KernelDiagnosticsOptions };
+
+/**
+ * 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<IApplication, DiagnosticsCollector>();
+
+/**
+ * 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: IApplication): DiagnosticsCollector | undefined {
+  return COLLECTORS.get(app);
+}
+
+/** Options for {@linkcode createApplication}. */
+export interface ApplicationOptions {
+  /** Plugins to pre-register before {@linkcode IApplication.start}. */
+  plugins?: IPlugin[];
+  /**
+   * Explicit kernel diagnostics activation. An omitted option leaves
+   * {@linkcode IApplication.diagnostics} absent and creates no collector,
+   * metadata mirror, ring buffer, or timer anywhere in the kernel; supplying
+   * an object (even `{}`) enables collection. Malformed label allowlists
+   * reject construction — the one diagnostics failure that may.
+   *
+   * @since 0.8.0
+   */
+  diagnostics?: KernelDiagnosticsOptions;
+}
+
+/**
+ * Inject request shape for {@linkcode IKernelApplication.inject}.
+ *
+ * @since 0.1.0
+ */
+export interface InjectRequest {
+  /** Socket peer to carry into `IRequest.ip`; omitted by default. */
+  ip?: string;
+  /** HTTP method. */
+  method: string;
+  /** Full request URL. */
+  url: string;
+  /** Request headers. */
+  headers?: Record<string, string> | Headers;
+  /**
+   * Request body. Carried VERBATIM for every byte-ish shape, but the
+   * content-type default differs between them: a `Uint8Array` and an
+   * `ArrayBuffer` get NONE, since only the caller knows whether those bytes
+   * are multipart, JSON, or an image, while a `Blob` DECLARES its own and
+   * contributes a non-empty `.type` as the default — matching the platform,
+   * whose `new Request(url, { body: blob })` sets the header from it and omits
+   * it when the blob has none. A `URLSearchParams` is serialised with its own
+   * `toString()` and defaults the content type to
+   * `application/x-www-form-urlencoded`; a plain object is JSON-serialised and
+   * a bare `string` is carried as-is, both defaulting to `application/json`.
+   * An explicitly supplied content type always wins, and the default is
+   * written onto a COPY of `headers`, so a `Headers` instance reused across
+   * two injected requests is never mutated.
+   *
+   * Any other shape — an array, a `Date`, a class instance, a number — is
+   * REFUSED with a `TypeError` naming the received type, rather than silently
+   * JSON-stringified as before (which turned a `Uint8Array` into
+   * `{"0":97,…}` and every other non-string into `{}`).
+   *
+   * The last arm is deliberately `Record<string, unknown>`, not `object`:
+   * `object` admits arrays, `Date`s, streams and every class instance, so the
+   * union would go on accepting exactly the values that used to silently
+   * JSON-coerce.
+   */
+  body?: string | Uint8Array | ArrayBuffer | Blob | URLSearchParams | Record<string, unknown>;
+}
+
+/**
+ * Inject response shape returned by {@linkcode IKernelApplication.inject}.
+ *
+ * @since 0.1.0
+ */
+export interface InjectResponse {
+  /** Response status code. */
+  readonly statusCode: number;
+  /** Response headers. */
+  readonly headers: Headers;
+  /**
+   * Raw response body as text. A byte body (from `response.send(bytes)`) is
+   * UTF-8 decoded; `null` only when the response genuinely has no body.
+   */
+  readonly body: string | null;
+  /**
+   * Parses the response body as JSON.
+   *
+   * @throws {Error} If the response has no body
+   * @throws {SyntaxError} If the body is not valid JSON
+   */
+  json<T>(): T;
+}
+
+/** Kernel application extends IApplication with inject() capability. */
+export interface IKernelApplication extends IApplication {
+  /**
+   * Synthesizes an incoming request and runs it through the full pipeline
+   * without requiring a listening server.
+   *
+   * @param request - The synthetic request
+   * @returns The inject response
+   */
+  inject(request: InjectRequest): Promise<InjectResponse>;
+  /**
+   * Removes a pending plugin by name before the application starts.
+   *
+   * Plugins do not run until `start()`, so removing one here means its
+   * `register()` — and any eager side effect inside it, such as a database
+   * adapter's `connect()` — never happens at all. That is the one thing
+   * overriding a capability cannot do: an override replaces what consumers
+   * resolve, after the real plugin has already run.
+   *
+   * Removing a plugin another plugin declares in `dependencies` is not
+   * refused here; `start()` reports it — naming the dependent plugin and the unsatisfied
+   * capability, though not the removed plugin's own name when the two differ
+   * (`database-plugin` provides `database`).
+   *
+   * Removes **every** pending plugin carrying the name, not the first. Two may
+   * share one — the kernel refuses duplicates at `start()`, not at `register()`
+   * — and dropping one would leave the other running while the caller was told
+   * the name was gone.
+   *
+   * @param name - The plugin's `name`, as declared on `IPlugin`
+   * @returns `true` when at least one plugin was removed, `false` when none carried that name
+   * @throws {Error} If startup has begun — including after a `start()` that
+   * FAILED, since the plugins that ran before the failure cannot be un-run
+   * @example
+   * ```typescript
+   * const app = createApp();            // the project's own composition root
+   * app.unregister('database');         // the real adapter never connects
+   * await app.start();
+   * ```
+   * @since 0.6.0
+   */
+  unregister(name: string): boolean;
+  /**
+   * Reports whether a plugin carrying this name is pending.
+   *
+   * A pure read — it neither resolves nor constructs anything. It exists so a
+   * caller applying several exclusions can validate the whole set BEFORE
+   * removing any of them: `unregister` mutates immediately, so removing as you
+   * go leaves earlier exclusions applied when a later name turns out to be
+   * misspelled, handing a caller that catches the error a silently altered
+   * application.
+   *
+   * Answers against the registered plugin list, which startup does NOT clear — so
+   * after `start()` it still reports `true` for a plugin that has already run.
+   * Its purpose is pre-`start()` validation, and `unregister` throws once any
+   * plugin has registered, so a later answer is not actionable either way.
+   *
+   * @param name - The plugin's `name`, as declared on `IPlugin`
+   * @returns `true` when at least one pending plugin carries that name
+   * @since 0.6.0
+   */
+  hasPlugin(name: string): boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Application class (internal — not exported from index)
+// ---------------------------------------------------------------------------
+
+class Application implements IKernelApplication {
+  readonly #registry = new ServiceRegistry();
+  readonly #pipeline = new MiddlewarePipeline();
+  #registeringPlugin: string | undefined;
+  readonly #router = new Router(() => this.#registeringPlugin);
+  readonly #lifecycle = new LifecycleManager();
+  readonly #plugins: IPlugin[] = [];
+  readonly #envSpecs: {
+    name: string;
+    spec: Readonly<Record<string, EnvVarSpec>>;
+  }[] = [];
+  #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: readonly IPlugin[] = [];
+  #serverHandle: unknown = null;
+  #inFlight = 0;
+  #stopping = false;
+  /** Cached in-flight/completed shutdown, so stop() runs its side effects once. */
+  #stopPromise: Promise<void> | null = 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.
+   */
+  readonly #collector: DiagnosticsCollector | undefined;
+  /**
+   * 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.
+   */
+  readonly #diagnostics: IDiagnosticsSource | undefined;
+
+  constructor(diagnostics?: KernelDiagnosticsOptions) {
+    // 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: (): DiagnosticsSnapshot => collector.snapshot(),
+      read: (after: number, limit?: number): DiagnosticsBatch => 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<IRuntimeServices>(CAPABILITIES.RUNTIME);
+          if (runtime !== undefined) {
+            collector.initializeRuntime(runtime, () =>
+              this.#registry.peekResolved<ITelemetryService>(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(): IDiagnosticsSource | undefined {
+    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: IErrorResponder | undefined = undefined;
+
+  get services() {
+    return this.#registry;
+  }
+
+  get middleware(): IMiddlewareApi {
+    return this.#pipeline;
+  }
+
+  get router(): IRouterApi {
+    return this.#router;
+  }
+
+  register(plugin: IPlugin): IApplication {
+    if (this.#started) {
+      throw new Error('Cannot register plugins after the application has started.');
+    }
+    this.#plugins.push(plugin);
+    return this;
+  }
+
+  hasPlugin(name: string): boolean {
+    return this.#plugins.some((plugin) => plugin.name === name);
+  }
+
+  unregister(name: string): boolean {
+    // `#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: string): string | undefined {
+    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?: StartOptions): Promise<void> {
+    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?: StartOptions): Promise<void> {
+    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 = (): string | undefined => 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: Omit<IPluginContext, 'config' | 'logger' | 'metadata' | 'container' | 'runtime'> = {
+      services: registry,
+      middleware: this.#pipeline,
+      router: this.#router,
+      lifecycle: this.#lifecycle,
+      health: {
+        register(name: string, indicator: HealthIndicatorFn): void {
+          registry.register(
+            CAPABILITIES.HEALTH_INDICATOR,
+            { name, check: indicator },
+            { multi: true },
+          );
+        },
+      },
+      metrics: {
+        register(name: string, config: MetricConfig): void {
+          registry.register(CAPABILITIES.METRIC_REGISTRATION, { name, config }, { multi: true });
+        },
+      },
+      openapi: {
+        addSchema(name: string, schema: unknown): void {
+          registry.register(CAPABILITIES.OPENAPI_SCHEMA, { name, schema }, { multi: true });
+        },
+      },
+      decorators: {
+        register(name: string, handler: DecoratorHandler): void {
+          registry.register(CAPABILITIES.DECORATOR_HANDLER, { name, handler }, { multi: true });
+        },
+      },
+      cli: {
+        register(name: string, handler: CliCommandHandler): void {
+          registry.register(CAPABILITIES.CLI_COMMAND, { name, handler }, { multi: true });
+        },
+      },
+      environment: {
+        validate(spec: Readonly<Record<string, EnvVarSpec>>): void {
+          // 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: Record<string, () => object> = {
+      runtime: () => registry.get<IRuntimeServices>(CAPABILITIES.RUNTIME),
+      config: () => registry.get<IConfig>(CAPABILITIES.CONFIG),
+      logger: () => registry.get<ILogger>(CAPABILITIES.LOGGER),
+      metadata: () => registry.get<IMetadataStore>(CAPABILITIES.METADATA_STORE),
+      container: () => registry.get<IContainer>(CAPABILITIES.DI_CONTAINER),
+    };
+    const lazyAvailable: Record<string, () => boolean> = {
+      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: IPluginContext = new Proxy(base as Record<string, unknown>, {
+      get(target, prop: string, receiver) {
+        if (prop in lazyGetters) {
+          return lazyAvailable[prop]() ? lazyGetters[prop]() : undefined;
+        }
+        return Reflect.get(target, prop, receiver);
+      },
+      has(target, prop: string) {
+        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: string) {
+        if (prop in lazyGetters) {
+          if (!lazyAvailable[prop]()) {
+            return undefined;
+          }
+          return {
+            enumerable: true,
+            configurable: true,
+            writable: false,
+            value: lazyGetters[prop](),
+          };
+        }
+        return Reflect.getOwnPropertyDescriptor(target, prop);
+      },
+    }) as unknown as IPluginContext;
+
+    // 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<IRuntimeServices>(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<ITelemetryService>(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<IHttpAdapter>(CAPABILITIES.HTTP_ADAPTER);
+      adapter.setHandler((request: IRequest) => 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<IHttpAdapter>(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');
+      }
+      this.#announceListening(options.port, options.hostname);
+    }
+  }
+
+  stop(): Promise<void> {
+    // 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(): Promise<void> {
+    // 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(): Promise<void> {
+    // 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: { readonly cause: unknown } | null = 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<IHttpAdapter>(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: Request): Promise<Response> {
+    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<IHttpAdapter>(CAPABILITIES.HTTP_ADAPTER);
+    return await adapter.fetch(request);
+  }
+
+  /** Synthesizes an inject request and runs it through the full pipeline. */
+  async inject(request: InjectRequest): Promise<InjectResponse> {
+    // 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: Request | undefined;
+    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: Promise<FormBody> | undefined;
+
+    const syntheticRequest: IRequest = {
+      ...(request.ip !== undefined ? { ip: request.ip } : {}),
+      method: request.method as IRequest['method'],
+      url: fullUrl,
+      get path() {
+        return new URL(fullUrl).pathname;
+      },
+      headers,
+      ...(raw !== undefined ? { raw } : {}),
+      json<T>(): Promise<T> {
+        // 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),
+            ) as T,
+        );
+      },
+      text(): Promise<string> {
+        return Promise.resolve(bodyBytes === undefined ? '' : new TextDecoder().decode(bodyBytes));
+      },
+      bytes(): Promise<Uint8Array> {
+        return Promise.resolve(bodyBytes ?? new Uint8Array(0));
+      },
+      formData(): Promise<FormBody> {
+        // 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<T>(): T {
+        if (body === null) {
+          throw new Error('No JSON body available');
+        }
+        return JSON.parse(body);
+      },
+    };
+  }
+
+  // ---------------------------------------------------------------------------
+  // Private methods
+  // ---------------------------------------------------------------------------
+
+  #handleRequest(request: IRequest): ResponseBuilder | Promise<ResponseBuilder> {
+    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<string, unknown>();
+      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<IRuntimeServices>(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: RequestContextHandle;
+    let path: string;
+    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 as ResponseBuilder;
+      }
+      return pending.then(
+        () => {
+          this.#inFlight--;
+          this.#completeRequest(ctx, 'ok');
+          return ctx.response as ResponseBuilder;
+        },
+        (error: unknown) => 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: IRequestContext, outcome: DiagnosticsEventOutcome): void {
+    this.#collector?.endRequestOperation(ctx, {
+      outcome,
+      statusCode: (ctx.response as ResponseBuilder).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: IRequestContext,
+    handle: RequestContextHandle,
+    path: string,
+    request: IRequest,
+  ): undefined | Promise<unknown> {
+    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: IRequestContext,
+    handle: RequestContextHandle,
+    path: string,
+    request: IRequest,
+    requestHooks: readonly ((ctx: IRequestContext) => void | Promise<void>)[],
+    responseHooks: readonly ((ctx: IRequestContext) => void | Promise<void>)[],
+  ): Promise<void> {
+    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: 'request-hook' | 'response-hook' | 'error-hook',
+    parentOperationId: string | undefined,
+    run: () => void | Promise<void>,
+  ): Promise<void> {
+    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: 'global' | 'route',
+    parentOperationId: string | undefined,
+    routeEntryIndex: number | undefined,
+  ): ChainObserver | undefined {
+    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: IRequestContext,
+    handle: RequestContextHandle,
+    path: string,
+    request: IRequest,
+  ): undefined | Promise<unknown> {
+    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: IRequestContext,
+    handle: RequestContextHandle,
+    path: string,
+    request: IRequest,
+  ): Promise<void> {
+    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: IRequestContext,
+    stage: 'websocket-upgrade' | 'grpc-dispatch',
+    run: () => Promise<boolean>,
+  ): Promise<boolean> {
+    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 as ResponseBuilder).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: IRequestContext,
+    handle: RequestContextHandle,
+    path: string,
+    request: IRequest,
+  ): undefined | Promise<unknown> {
+    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 as ResponseBuilder).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: IRequestContext,
+    entry: RouteEntry,
+    definition: RouteDefinition,
+  ): undefined | Promise<unknown> {
+    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: ReturnType<typeof definition.handler>;
+    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 as ResponseBuilder).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 as ResponseBuilder).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: IRequestContext,
+    entry: RouteEntry,
+    run: () => Promise<void>,
+  ): Promise<void> {
+    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 as ResponseBuilder).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: unknown, ctx: IRequestContext): ResponseBuilder | Promise<ResponseBuilder> {
+    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: Error, ctx: IRequestContext): ResponseBuilder {
+    // 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 as ResponseBuilder;
+  }
+
+  /**
+   * 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: IRequestContext): Promise<boolean> {
+    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<IWebSocketService>(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: WebSocketUpgradeDecision | null;
+    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: number;
+    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: IRequestContext): Promise<boolean> {
+    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<IGrpcService>(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 as unknown as BodyInit } : {}),
+    });
+
+    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: IRequestContext, response: Response): Promise<void> {
+    const snapshot = await response.arrayBuffer();
+    const builder = ctx.response as ResponseBuilder;
+    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: readonly unknown[]): IErrorResponder | undefined {
+    let responder: IErrorResponder | undefined;
+    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: IRequest): ResponseBuilder {
+    const builder = new ResponseBuilder();
+    const state = new Map<string, unknown>();
+    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: IRequest): { request?: { readonly path: string } } {
+    let path: string | undefined;
+    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: unknown): void {
+    try {
+      if (!this.#registry.has(CAPABILITIES.LOGGER)) {
+        return;
+      }
+      const logger = this.#registry.get<ILogger>(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: 'override' | 'unregister',
+    token: string,
+    plugin: string | undefined,
+  ): void {
+    try {
+      if (!this.#registry.has(CAPABILITIES.LOGGER)) {
+        return;
+      }
+      const logger = this.#registry.get<ILogger>(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: unknown): void {
+    try {
+      if (!this.#registry.has(CAPABILITIES.LOGGER)) {
+        return;
+      }
+      const logger = this.#registry.get<ILogger>(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: Error, ctx: IRequestContext): void {
+    try {
+      if (!this.#registry.has(CAPABILITIES.LOGGER)) {
+        // `msg` carries the label and `message` the error's own text, the same
+        // two keys the console logger writes for the branch below.
+        this.#registry.get<IRuntimeServices>(CAPABILITIES.RUNTIME).reportError?.({
+          level: 'error',
+          msg: 'Unhandled request error',
+          ...serializeError(error),
+          requestId: ctx.id,
+          method: ctx.request.method,
+          path: ctx.request.path,
+        });
+        return;
+      }
+      const logger = this.#registry.get<ILogger>(CAPABILITIES.LOGGER);
+      logger.error('Unhandled request error', {
+        ...serializeError(error),
+        requestId: ctx.id,
+        method: ctx.request.method,
+        path: ctx.request.path,
+      });
+    } catch {
+      // Reporting must never replace the original request failure.
+    }
+  }
+
+  /**
+   * 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(): void {
+    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<ILogger>(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.
+    }
+  }
+
+  /**
+   * Announces a successful `adapter.listen` through the registered logger.
+   *
+   * Node and Bun print nothing of their own, so before this a booted project
+   * looked the same whether it had bound a socket or was still starting. Deno
+   * also prints its native "Listening on" banner; this line is additive there,
+   * and both are accurate. A `port: 0` request reports an ephemeral port rather
+   * than the literal zero. A missing or itself-broken logger degrades silently:
+   * it must never turn a successful start into a failure.
+   *
+   * @param port - The port `adapter.listen` was asked for
+   * @param hostname - The configured hostname, absent when none was supplied
+   */
+  #announceListening(port: number, hostname?: string): void {
+    try {
+      if (!this.#registry.has(CAPABILITIES.LOGGER)) {
+        return;
+      }
+      const logger = this.#registry.get<ILogger>(CAPABILITIES.LOGGER);
+      if (port === 0) {
+        logger.info('Server listening on an ephemeral port');
+        return;
+      }
+      logger.info('Server listening', hostname === undefined ? { port } : { port, hostname });
+    } catch {
+      // The logger itself failed or none is resolvable — no safe channel
+      // remains without violating the no-console rule; degrade silently.
+    }
+  }
+
+  #validateEnvironment(runtime: IRuntimeServices): void {
+    const violations: string[] = [];
+
+    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(): Promise<void> {
+    const runtime = this.#registry.get<IRuntimeServices>(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<void>((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?: ApplicationOptions): IKernelApplication {
+  const app = new Application(options?.diagnostics);
+  if (options?.plugins) {
+    for (const plugin of options.plugins) {
+      app.register(plugin);
+    }
+  }
+  return app;
+}