@nextrush/types 3.0.7 → 4.0.0-beta.1

package/dist/index.d.ts

@@ -159,6 +159,32 @@ type ContentTypeValue = (typeof ContentType)[keyof typeof ContentType];
  * This enables runtime-specific optimizations while maintaining a unified API.
  */
 type Runtime = 'node' | 'bun' | 'deno' | 'deno-deploy' | 'cloudflare-workers' | 'vercel-edge' | 'edge' | 'unknown';
+/**
+ * Named serverless/edge deployment platform, orthogonal to {@link Runtime}.
+ *
+ * @remarks
+ * `Runtime` answers "which JS engine" (node/bun/deno/edge); `PlatformId`
+ * answers "which vendor platform" (Lambda, GCF, Azure, Cloudflare Workers,
+ * Vercel Edge, Netlify Edge) — two independent questions that `Runtime`
+ * conflating would make into one. Exposed as `ctx.platform` alongside the
+ * unchanged `ctx.runtime`.
+ *
+ * @see RFC-026
+ */
+type PlatformId = 'lambda' | 'gcf' | 'azure' | 'cloudflare-workers' | 'vercel-edge' | 'netlify-edge';
+/**
+ * Proxy-trust specification for client-IP resolution (RFC-030, SEC-01).
+ *
+ * @remarks
+ * `false` trusts nothing — the direct socket peer is always `ctx.ip`.
+ * A `number` trusts exactly that many proxy hops, selecting the
+ * corresponding `X-Forwarded-For` entry counting from the right rather than
+ * the client-authored leftmost entry. A `string[]` of CIDR ranges/literal
+ * IPs trusts only a direct peer (and every hop it names) falling inside the
+ * set. `true` and `0` are rejected at boot — see `resolveClientIp` in
+ * `@nextrush/runtime`.
+ */
+type ProxyTrust = false | number | string[];
 /**
  * Runtime feature capabilities
  *
@@ -181,6 +207,10 @@ interface RuntimeCapabilities {
     cryptoSubtle: boolean;
     /** Supports Web Workers / Worker Threads */
     workers: boolean;
+    /** Supports TLS (HTTPS) — the runtime can terminate TLS connections */
+    secureServing: boolean;
+    /** Supports HTTP/2 negotiation via ALPN (requires secureServing) */
+    http2: boolean;
 }
 /**
  * Runtime information object
@@ -222,12 +252,17 @@ interface BodySource {
      */
     text(): Promise<string>;
     /**
-     * Read the body as a Uint8Array buffer
+     * Read the body as a Uint8Array buffer.
      *
+     * @param limit - Optional per-read byte limit. When provided, it is the value
+     *   enforced for both the Content-Length pre-check and the incremental
+     *   streaming check (taking precedence over the source's construction-time
+     *   limit); when omitted, the construction-time limit governs. See
+     *   docs/RFC/request-data/017-body-source-limit-propagation.md.
      * @returns Promise resolving to the body as Uint8Array
      * @throws Error if body has already been consumed
      */
-    buffer(): Promise<Uint8Array>;
+    buffer(limit?: number): Promise<Uint8Array>;
     /**
      * Read the body as JSON
      *
@@ -279,6 +314,130 @@ interface BodySourceOptions {
     encoding?: 'utf-8' | 'utf8' | 'ascii' | 'latin1' | 'iso-8859-1' | 'utf-16le' | 'utf-16be';
 }
 
+/**
+ * @nextrush/types - Response Streaming Contracts
+ *
+ * Pure type contracts for runtime-agnostic response streaming (text/SSE/NDJSON).
+ * The implementation lives in `@nextrush/stream`; these interfaces live here so
+ * the `Context` interface can reference them without `@nextrush/types` depending
+ * on any higher-tier package.
+ *
+ * See `docs/RFC/request-data/003-stream.md`.
+ *
+ * @packageDocumentation
+ */
+/**
+ * A single Server-Sent Event.
+ *
+ * @remarks
+ * `data` is the only required field. Objects are serialized with `JSON.stringify`;
+ * strings are sent verbatim. The framework handles all wire-format framing
+ * (multi-line `data:` escaping, `event:`/`id:`/`retry:` fields, terminating blank line).
+ */
+interface SSEEvent {
+    /** Event payload. Objects are JSON-serialized; strings are sent as-is. */
+    data: unknown;
+    /** SSE `event:` field — lets the client dispatch to a named listener. */
+    event?: string;
+    /** SSE `id:` field — enables client auto-reconnect from the last-seen id. */
+    id?: string;
+    /** SSE `retry:` field, in milliseconds — client reconnection delay hint. */
+    retry?: number;
+}
+/**
+ * Capabilities shared by every response-stream writer, regardless of protocol.
+ *
+ * @remarks
+ * Concrete writers ({@link TextStreamWriter}, {@link SSEStreamWriter},
+ * {@link NDJSONStreamWriter}) add a protocol-specific `write()` on top of this.
+ */
+interface BaseStreamWriter {
+    /**
+     * `true` once the client has disconnected.
+     *
+     * @remarks
+     * Use as a loop guard for long-running streams. Writing after this is `true`
+     * throws `StreamAbortedError`.
+     */
+    readonly aborted: boolean;
+    /**
+     * Fires when the client disconnects.
+     *
+     * @remarks
+     * Pass this straight into an upstream SDK's own abort option
+     * (e.g. `{ signal: writer.signal }`) so the upstream call is cancelled the
+     * instant the client goes away.
+     */
+    readonly signal: AbortSignal;
+    /**
+     * Register a cleanup callback invoked once when the client disconnects.
+     *
+     * @param fn - Cleanup callback (e.g. abort an upstream request, release a resource).
+     */
+    onAbort(fn: () => void): void;
+}
+/**
+ * Source shapes accepted by a writer's `consume()` method.
+ *
+ * @remarks
+ * Normalized internally to a single async-iterator path — callers never branch
+ * on the concrete shape.
+ */
+type StreamSource<T> = AsyncIterable<T> | ReadableStream<T>;
+/**
+ * Writer for a raw text/byte stream (`ctx.stream()`).
+ */
+interface TextStreamWriter extends BaseStreamWriter {
+    /**
+     * Write text or bytes.
+     * @throws StreamAbortedError if the client has already disconnected.
+     */
+    write(chunk: string | Uint8Array): Promise<void>;
+    /**
+     * Consume an existing producer as this response's body.
+     * @param source - An `AsyncIterable` or Web `ReadableStream` of strings/bytes.
+     * @throws StreamAbortedError if the client disconnects mid-consume.
+     */
+    consume(source: StreamSource<string | Uint8Array>): Promise<void>;
+}
+/**
+ * Writer for a Server-Sent Events stream (`ctx.sse()`).
+ */
+interface SSEStreamWriter extends BaseStreamWriter {
+    /**
+     * Write one Server-Sent Event. The framework handles all wire-format framing.
+     * @throws StreamAbortedError if the client has already disconnected.
+     */
+    write(event: SSEEvent): Promise<void>;
+    /**
+     * Consume an existing producer; each yielded chunk is sent as `{ data: chunk }`.
+     * @throws StreamAbortedError if the client disconnects mid-consume.
+     */
+    consume(source: StreamSource<string | Uint8Array>): Promise<void>;
+}
+/**
+ * Writer for a newline-delimited JSON stream (`ctx.ndjson()`).
+ */
+interface NDJSONStreamWriter extends BaseStreamWriter {
+    /**
+     * Write one JSON-serializable value as a single NDJSON line.
+     * @throws StreamAbortedError if the client has already disconnected.
+     */
+    write(value: unknown): Promise<void>;
+    /**
+     * Consume an existing producer of JSON-serializable values, one line each.
+     * @throws StreamAbortedError if the client disconnects mid-consume.
+     */
+    consume(source: StreamSource<unknown>): Promise<void>;
+}
+/**
+ * A streaming callback that receives a protocol-specific writer.
+ *
+ * @remarks
+ * The connection auto-closes when this callback resolves.
+ */
+type StreamRun<W extends BaseStreamWriter> = (writer: W) => Promise<void>;
+
 /**
  * @nextrush/types - Context Type Definitions
  *
@@ -337,11 +496,26 @@ interface Context {
      */
     readonly url: string;
     /**
-     * Request path without query string
+     * Request path without query string, canonicalized by the router (case
+     * folded per `caseSensitive`, structurally normalized) — the value the
+     * router actually matched on, and the one path-based policy middleware
+     * should compare against instead of hand-rolling its own normalization
+     * (RFC-029). See {@link originalPath} for the untouched raw target.
      * @example '/users/123'
      * @readonly
      */
     readonly path: string;
+    /**
+     * The raw request target as received, before router canonicalization —
+     * still query-string-free, but not case-folded or structurally normalized.
+     * Optional: populated once the router's dispatch middleware runs; absent
+     * (or equal to {@link path}) when no router has run yet, or when a caller
+     * constructs a `Context` directly (e.g. a test double) without one. Prefer
+     * `path` for any security- or routing-relevant comparison (RFC-029).
+     * @example '/Users/123' when a request for '/USERS/123' matched '/users/:id'
+     * @readonly
+     */
+    readonly originalPath?: string;
     /**
      * Parsed query string parameters
      * @example { include: 'posts', limit: '10' }
@@ -584,6 +758,25 @@ interface Context {
      * ```
      */
     readonly runtime: Runtime;
+    /**
+     * Named deployment platform, when known — orthogonal to {@link runtime}.
+     *
+     * @remarks
+     * `undefined` on adapters/runtimes with no named platform to report (e.g.
+     * plain Node.js, Bun, Deno). On `@nextrush/adapter-edge` and
+     * `@nextrush/adapter-serverless`, set when the platform is detectable
+     * (Cloudflare Workers, Vercel Edge, Netlify Edge) or explicitly known by
+     * the Tier-1 handler that built this context (AWS Lambda, Google Cloud
+     * Functions, Azure Functions).
+     *
+     * @example
+     * ```typescript
+     * if (ctx.platform === 'lambda') {
+     *   // AWS Lambda-specific behavior
+     * }
+     * ```
+     */
+    readonly platform: PlatformId | undefined;
     /**
      * Body source for cross-runtime body reading
      *
@@ -600,6 +793,72 @@ interface Context {
      * ```
      */
     readonly bodySource: BodySource;
+    /**
+     * Abort signal that fires when the client disconnects mid-response.
+     *
+     * @internal
+     * @remarks
+     * Adapter-level primitive consumed by `@nextrush/stream`. Handlers should use
+     * `writer.signal` inside `ctx.stream()`/`ctx.sse()`/`ctx.ndjson()` instead of
+     * accessing this directly. Synthesized on Node from response `close`/request
+     * `aborted`; passed through natively on Bun/Deno/Edge from `Request.signal`.
+     */
+    readonly signal: AbortSignal;
+    /**
+     * Send a raw byte stream as the response body.
+     *
+     * @internal
+     * @remarks
+     * Adapter-level transport primitive consumed by `@nextrush/stream`. Not
+     * intended for direct handler use — use `ctx.stream()`/`ctx.sse()`/
+     * `ctx.ndjson()`. Resolves when the stream is fully flushed (Node) or once the
+     * response body is wired (Bun/Deno/Edge).
+     *
+     * @param source - A Web `ReadableStream` of bytes to stream to the client.
+     */
+    sendStream(source: ReadableStream<Uint8Array>): Promise<void>;
+    /**
+     * Stream a raw text/byte response. The connection closes automatically when
+     * the callback resolves.
+     *
+     * @param run - Callback that receives a {@link TextStreamWriter}.
+     *
+     * @example
+     * ```typescript
+     * await ctx.stream(async (writer) => {
+     *   await writer.write('Loading...\n');
+     *   await writer.write('Done.\n');
+     * });
+     * ```
+     */
+    stream(run: StreamRun<TextStreamWriter>): Promise<void>;
+    /**
+     * Stream a Server-Sent Events (`text/event-stream`) response.
+     *
+     * @param run - Callback that receives an {@link SSEStreamWriter}.
+     *
+     * @example
+     * ```typescript
+     * await ctx.sse(async (writer) => {
+     *   for await (const token of llm) await writer.write({ data: token });
+     * });
+     * ```
+     */
+    sse(run: StreamRun<SSEStreamWriter>): Promise<void>;
+    /**
+     * Stream a newline-delimited JSON (`application/x-ndjson`) response.
+     *
+     * @param run - Callback that receives an {@link NDJSONStreamWriter}.
+     *
+     * @example
+     * ```typescript
+     * await ctx.ndjson(async (writer) => {
+     *   await writer.write({ step: 'search' });
+     *   await writer.write({ step: 'done' });
+     * });
+     * ```
+     */
+    ndjson(run: StreamRun<NDJSONStreamWriter>): Promise<void>;
 }
 /**
  * Next function type (traditional Koa-style)
@@ -645,133 +904,579 @@ interface ContextOptions {
 }
 
 /**
- * @nextrush/types - Plugin Type Definitions
+ * @nextrush/types - Adapter Context Contracts (F-13)
+ *
+ * The concrete adapter context classes expose transport/lifecycle primitives
+ * that are not part of the runtime-neutral {@link Context} contract:
+ * `markResponded()` (all adapters), and `getResponse()` / `waitUntil()` / `env`
+ * (the Web/fetch adapters). Consumers typed as `Context` cannot see these, so
+ * `@nextrush/stream` and the adapters resort to structural access.
  *
- * Plugins are the extension mechanism for NextRush.
- * They allow adding functionality without bloating the core.
+ * These interfaces model that surface **additively** — they extend `Context`,
+ * they never weaken it. Adapters (and `@nextrush/stream`) can depend on these
+ * instead of coupling to the concrete context classes.
  *
  * @packageDocumentation
  */
 
 /**
- * Minimal Application interface for plugin registration
- * The full Application class is in @nextrush/core
+ * A {@link Context} plus the lifecycle primitive every adapter exposes.
+ *
+ * @remarks
+ * `markResponded()` lets the transport/streaming layer flag that a response has
+ * been committed out-of-band (e.g. after wiring a stream), so the adapter's
+ * "not responded" fallback path is skipped.
  */
-interface ApplicationLike {
+interface AdapterContext extends Context {
     /**
-     * Register middleware
+     * Mark the response as already sent.
+     *
+     * @remarks
+     * Used by streaming and adapter transport code when a response is committed
+     * without going through `json()`/`send()`/`html()`/`redirect()`.
      */
-    use(middleware: Middleware): this;
+    markResponded(): void;
+}
+/**
+ * An {@link AdapterContext} for Web/fetch runtimes (Bun, Deno, Edge).
+ *
+ * @remarks
+ * Adds the fetch-specific surface: `getResponse()` (materialize the built
+ * `Response`), and the optional edge primitives `waitUntil()` and `env`
+ * (platform bindings — reachable only on runtimes that provide them, e.g.
+ * Cloudflare Workers).
+ */
+interface FetchContext extends AdapterContext {
     /**
-     * Get installed plugin by name
+     * Build and return the Web `Response` accumulated by the context.
+     *
+     * @returns The `Response` to hand back to the runtime.
      */
-    getPlugin<T extends Plugin>(name: string): T | undefined;
+    getResponse(): Response;
+    /**
+     * Extend the request's lifetime for fire-and-forget work (logging,
+     * analytics, cache writes). Only present on runtimes that expose an
+     * execution context (e.g. Cloudflare Workers, Vercel Edge).
+     *
+     * @param promise - Work that should outlive the response.
+     */
+    waitUntil?(promise: Promise<unknown>): void;
+    /**
+     * Platform bindings passed by the runtime (e.g. Cloudflare `env`: KV, D1, R2,
+     * Durable Objects, secrets). Typed as `unknown` at the contract level; a
+     * concrete adapter may narrow it via a generic.
+     */
+    env?: unknown;
 }
 /**
- * Plugin interface for extending NextRush
+ * The shape of an adapter's context factory.
  *
- * Plugins are installed via app.plugin() and can:
- * - Add middleware
- * - Extend context
- * - Add lifecycle hooks
+ * @remarks
+ * Every adapter builds the per-request context through a factory that takes
+ * platform-specific inputs (e.g. Node's `(req, res, options)`, a fetch runtime's
+ * `(request, options)`) and returns an {@link AdapterContext} over the shared
+ * {@link Context} contract. This type formalizes that invariant — "adapters build
+ * `Context` via a factory and run `app.callback()`" — at the type level, generic
+ * over the platform input tuple so server- and fetch-style factories both conform.
+ *
+ * @typeParam Args - The platform-specific factory argument tuple.
+ * @typeParam Ctx - The concrete {@link AdapterContext} the factory returns.
  *
  * @example
  * ```typescript
- * class LoggerPlugin implements Plugin {
- *   readonly name = 'logger';
- *   readonly version = '1.0.0';
- *
- *   install(app: ApplicationLike) {
- *     app.use(async (ctx, next) => {
- *       const start = Date.now();
- *       await next();
- *       console.log(`${ctx.method} ${ctx.path} - ${Date.now() - start}ms`);
- *     });
- *   }
- * }
+ * // Node adapter
+ * const _factory = createNodeContext satisfies AdapterContextFactory<
+ *   [IncomingMessage, ServerResponse, NodeContextOptions?],
+ *   NodeContext
+ * >;
  * ```
  */
-interface Plugin {
-    /**
-     * Unique plugin name
-     * Used for identification and getPlugin() lookup
-     */
-    readonly name: string;
-    /**
-     * Plugin version (optional)
-     * Follows semver format
-     */
-    readonly version?: string;
+type AdapterContextFactory<Args extends readonly unknown[], Ctx extends AdapterContext = AdapterContext> = (...args: Args) => Ctx;
+
+/**
+ * @nextrush/types - Logger contract
+ *
+ * The structured logging interface shared by the application, adapters, and
+ * extensions. Lives here (the lowest package) so any layer can depend on the
+ * contract without depending on `@nextrush/core`.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Pluggable logger interface.
+ *
+ * Pass `console` for quick development logging, or a structured logger
+ * (pino, winston, `@nextrush/logger`) in production.
+ */
+interface Logger {
+    error(...args: unknown[]): void;
+    warn(...args: unknown[]): void;
+    info(...args: unknown[]): void;
+    debug(...args: unknown[]): void;
+}
+
+/**
+ * @nextrush/types - Adapter Conformance Contract (F-01)
+ *
+ * A light, additive compile-time contract that server- and fetch-style adapters
+ * `satisfies` at export time, so the *shape* of `serve`/`createHandler`/
+ * `createFetchHandler` and the `ServerHandle` cannot drift silently across
+ * adapters. This is the cheap secondary guard; a shared behavioral conformance
+ * suite is the primary one (see the audit's Adapter Conformance Specification).
+ *
+ * The contract is generic over the concrete application type because
+ * `@nextrush/types` sits below `@nextrush/core` in the package hierarchy and
+ * must not import `Application`. Adapters bind `App = Application` when they
+ * `satisfies` these shapes.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * The single canonical network address a server adapter binds to.
+ *
+ * @remarks
+ * Replaces the per-adapter `{ port, host }` vs `{ port, hostname }` divergence
+ * (audit F-05). `host` is the canonical key; adapters normalize internally.
+ */
+interface ServerAddress {
+    /** Port the server is listening on. */
+    readonly port: number;
+    /** Host/address the server is bound to (canonical key). */
+    readonly host: string;
     /**
-     * Install plugin into application
-     * Called when app.plugin() is invoked
+     * Host alias.
      *
-     * @param app - Application instance
+     * @deprecated Use {@link ServerAddress.host}. Retained so Bun/Deno, which
+     * historically returned `{ port, hostname }`, keep working during migration.
      */
-    install(app: ApplicationLike): void | Promise<void>;
-    /**
-     * Cleanup when application shuts down (optional)
-     * Called during graceful shutdown
-     */
-    destroy?(): void | Promise<void>;
+    readonly hostname?: string;
 }
 /**
- * Extended plugin interface with lifecycle hooks
- * For advanced plugins that need deeper integration
+ * Options common to server-style handler factories (node/bun/deno).
+ *
+ * @remarks
+ * Intentionally light. Individual adapters may accept a superset; this pins the
+ * shared, portable subset.
+ */
+interface HandlerOptions {
+    /** Logger for adapter diagnostics. Defaults to the application logger. */
+    logger?: Logger;
+    /** Per-request timeout in milliseconds. */
+    timeout?: number;
+}
+/**
+ * Options for fetch-style handler factories (edge).
  */
-interface PluginWithHooks extends Plugin {
+interface FetchHandlerOptions {
     /**
-     * Called before each request
+     * Per-request timeout in milliseconds. Individual adapters may apply their
+     * own default when omitted (e.g. the edge adapter's `DEFAULT_EDGE_TIMEOUT_MS`,
+     * F-07/ADR-0010) rather than leaving the timeout unenforced — this shared
+     * type only pins the option's shape, not a specific default.
      */
-    onRequest?(ctx: Context): void | Promise<void>;
+    timeout?: number;
     /**
-     * Called after each response
+     * Custom error handler. Receives the error and the fetch context and returns
+     * the `Response` to send.
      */
-    onResponse?(ctx: Context): void | Promise<void>;
+    onError?: (error: Error, ctx: FetchContext) => Response | Promise<Response>;
+}
+/**
+ * A running server instance with one canonical address shape and async close.
+ *
+ * @remarks
+ * The canonical handle every server adapter's `serve()` resolves to. Concrete
+ * adapters may expose additional fields (e.g. the raw `server`) on a subtype.
+ */
+interface ServerHandle {
+    /** The address the server is bound to. */
+    address(): ServerAddress;
+    /** Stop the server, draining in-flight requests. */
+    close(): Promise<void>;
+}
+/**
+ * A fetch handler: maps a Web `Request` (plus an optional runtime execution
+ * context) to a `Response`.
+ *
+ * @typeParam Exec - The runtime execution-context type (e.g. an edge
+ *   `waitUntil` context). Defaults to `unknown`.
+ */
+type FetchHandler<Exec = unknown> = (request: Request, executionContext?: Exec) => Response | Promise<Response>;
+/**
+ * Contract for server-style adapters (node/bun/deno).
+ *
+ * @typeParam App - The application type (adapters bind `Application`).
+ * @typeParam Opts - The adapter's `serve` options type.
+ * @typeParam Instance - The `serve` return type (a {@link ServerHandle} subtype).
+ */
+interface ServerAdapter<App = unknown, Opts = unknown, Instance extends ServerHandle = ServerHandle> {
+    /** Start a server for the application. */
+    serve(app: App, options?: Opts): Promise<Instance>;
+    /** Build a request handler for the application without owning the server. */
+    createHandler(app: App, options?: HandlerOptions): unknown;
+}
+/**
+ * Contract for fetch-style adapters (edge).
+ *
+ * @typeParam App - The application type (adapters bind `Application`).
+ */
+interface FetchAdapter<App = unknown, Exec = unknown> {
+    /** Build a fetch handler for the application. */
+    createFetchHandler(app: App, options?: FetchHandlerOptions): FetchHandler<Exec>;
+}
+
+/**
+ * @nextrush/types - Dependency Injection contract
+ *
+ * The container contract shared by `@nextrush/di` (implementation),
+ * `@nextrush/core` (each app owns one), and consumers. Lives here (the lowest
+ * package) so any layer can reference the contract without depending on `di`.
+ *
+ * @packageDocumentation
+ */
+/** Constructor type for class-based tokens. */
+type Constructor<T = unknown> = new (...args: unknown[]) => T;
+/** Token used to identify a dependency — a class, string, or symbol. */
+type Token<T = unknown> = Constructor<T> | string | symbol;
+/** Provider that uses a class constructor. */
+interface ClassProvider<T> {
+    useClass: Constructor<T>;
+}
+/** Provider that uses a factory function (optionally with injected deps). */
+interface FactoryProvider<T> {
+    useFactory: (...args: unknown[]) => T | Promise<T>;
+    inject?: Token[];
+}
+/** Provider that uses a constant value. */
+interface ValueProvider<T> {
+    useValue: T;
+}
+/** Union of all provider kinds. */
+type Provider<T> = ClassProvider<T> | FactoryProvider<T> | ValueProvider<T>;
+/**
+ * Lifecycle scope for registered services.
+ *
+ * - `'singleton'` — one shared instance for the process lifetime.
+ * - `'transient'` — a fresh instance on every resolve.
+ * - `'request'` — one instance per request, shared within that request. Backed
+ *   by a per-request child container; see RFC-NEXTRUSH-REQUEST-SCOPE.
+ */
+type Scope = 'singleton' | 'transient' | 'request';
+/** Options for service registration. */
+interface ServiceOptions {
+    scope?: Scope;
+}
+/** Registration options for `Container.register()`. */
+interface RegisterOptions {
+    /** Lifecycle scope — defaults to 'transient' if not specified. */
+    scope?: Scope;
+}
+/**
+ * Dependency injection container contract.
+ *
+ * Each NextRush {@link Application} may own one (per-app, not a global
+ * singleton). `@nextrush/di` provides the implementation.
+ */
+interface Container {
+    /** Register a dependency. */
+    register<T>(token: Token<T>, provider: Provider<T>, options?: RegisterOptions): void;
+    /** Resolve a dependency synchronously. */
+    resolve<T>(token: Token<T>): T;
+    /** Resolve a dependency that may have been registered with an async factory. */
+    resolveAsync<T>(token: Token<T>): Promise<T>;
+    /** Bootstrap all factory providers (awaits async factories, caches results). */
+    bootstrap(): Promise<void>;
+    /** Resolve all dependencies registered under a token. */
+    resolveAll<T>(token: Token<T>): T[];
+    /** Check if a token is registered. */
+    isRegistered<T>(token: Token<T>): boolean;
+    /** Clear all registered instances (testing). */
+    clearInstances(): void;
+    /** Reset the container completely (testing). */
+    reset(): void;
+    /** Create a child container with isolated scope. */
+    createChild(): Container;
+}
+
+/**
+ * @nextrush/types - Extension contract
+ *
+ * Extensions are the rare (~0.1%) long-lived runtime services that must attach
+ * state to the app, run async boot, and/or tear down on shutdown — an event bus,
+ * a database pool, a websocket attach. Most framework features are **middleware**
+ * (`app.use`) or plain **registrar** functions, not Extensions.
+ *
+ * See docs/RFC/class-runtime/005-plugin-system.md.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * The subset of `Application` an {@link Extension} may use during `setup()`.
+ *
+ * Kept structural (not the concrete `Application`) so {@link ExtensionContext}
+ * can live in `@nextrush/types` without importing `@nextrush/core`. The
+ * `Application` class implements this interface. Routing methods are added here
+ * when the app-owned router lands (RFC §11.1).
+ */
+interface ExtensionHost {
+    /** Register middleware on the application. */
+    use(middleware: Middleware): this;
+    /** Whether a decoration already occupies `name`. */
+    hasDecorator(name: string): boolean;
+}
+/**
+ * The argument passed to {@link Extension.setup}.
+ *
+ * A context object rather than the bare app, so future fields (`runtime`,
+ * `container`, `config`, …) are **additive** and never break existing
+ * extensions — the same reason VS Code uses `activate(context)`.
+ */
+interface ExtensionContext {
+    /** The application instance — add middleware, read decorations. */
+    readonly app: ExtensionHost;
+    /** The app logger (structured, pluggable). */
+    readonly logger: Logger;
     /**
-     * Called when an error occurs
+     * The app's DI container, if one was configured (per-app, not a global
+     * singleton). Present when the app was created via `nextrush/class` or with
+     * `createApp({ container })`; `undefined` for functional, DI-free apps.
      */
-    onError?(error: Error, ctx: Context): void | Promise<void>;
+    readonly container?: Container;
+    /** Environment mode. */
+    readonly env: 'development' | 'production' | 'test';
+    /** This extension's own name (for scoped diagnostics). */
+    readonly name: string;
     /**
-     * Extend the context object
-     * Add custom properties or methods
+     * Attach a value to the app under `name`. The extension-author primitive for
+     * exposing app-level surface (e.g. `app.events`). Throws if `name` is already
+     * decorated or collides with a core `Application` member.
      */
-    extendContext?(ctx: Context): void;
+    decorate(name: string, value: unknown): void;
 }
 /**
- * Plugin factory function type
- * Allows creating plugins with options
+ * A NextRush Extension.
+ *
+ * Registered via `app.extend()` (queues) and booted once at `app.ready()`
+ * (runs `setup` in registration order). Torn down at `app.close()`.
+ *
+ * @example
+ * ```typescript
+ * export function events(): Extension {
+ *   const emitter = new EventEmitter();
+ *   return {
+ *     name: 'events',
+ *     setup(ctx) { ctx.decorate('events', emitter); },
+ *     destroy() { emitter.clear(); },
+ *   };
+ * }
+ * ```
+ */
+/**
+ * @template TDecorated - Shape decorated onto the app by this extension's
+ * `setup()`. Phantom — never read at runtime, only carried through the type
+ * system so `Application.extend()` can return `this & TDecorated`, giving
+ * `app.<decoratedProperty>` static inference with zero `declare module`
+ * augmentation. Defaults to `{}` so plain, untyped `Extension` usages
+ * (the common case for internal/test extensions) are unaffected.
+ *
+ * @remarks
+ * Two things to know before relying on this:
+ *
+ * - **TypeScript trusts `TDecorated`, it never verifies it.** Nothing checks
+ *   that the declared shape actually matches what `setup()` calls
+ *   `ctx.decorate()` with — `Extension<{ foo: Foo }>` whose `setup()` never
+ *   decorates `foo` still typechecks, and `app.foo` will be `undefined` at
+ *   runtime with no warning. Keep the generic and the `decorate()` call in
+ *   sync by hand.
+ * - **The inferred type is lost on `let` reassignment.** Chain in one
+ *   expression (`const app = createApp().extend(x)`), not
+ *   `let app = createApp(); app = app.extend(x);` — TypeScript widens the
+ *   reassignment to the `let` binding's originally-inferred type, silently
+ *   dropping `TDecorated`. Every example below chains for this reason.
  *
  * @example
  * ```typescript
- * const logger = createLoggerPlugin({ level: 'info' });
- * app.plugin(logger);
+ * function events<T extends EventMap>(): Extension<{ events: EventEmitter<T> }> {
+ *   return {
+ *     name: 'events',
+ *     setup(ctx) { ctx.decorate('events', new EventEmitter<T>()); },
+ *   };
+ * }
+ *
+ * const app = createApp().extend(events<MyEvents>());
+ * app.events.emit('user:created', { id: '1' }); // inferred, no cast
  * ```
  */
-type PluginFactory<TOptions = unknown> = (options?: TOptions) => Plugin;
+interface Extension<TDecorated = Record<string, never>> {
+    /** Unique name — used for collision detection, dependency assertion, diagnostics. */
+    readonly name: string;
+    /**
+     * Names of other extensions that MUST already be registered before this one.
+     * Asserted at `app.ready()` in registration order — not auto-sorted.
+     */
+    readonly needs?: readonly string[];
+    /** Set up the extension. Runs once, at `app.ready()`, in registration order. */
+    setup(ctx: ExtensionContext): void | Promise<void>;
+    /** Tear down on `app.close()`. Runs in reverse registration order. */
+    destroy?(): void | Promise<void>;
+    /**
+     * Phantom marker carrying `TDecorated` through the type system. Never set
+     * at runtime — `TDecorated` has no inhabitant, so no implementation ever
+     * assigns this. Purely what lets `extend()` infer its return type.
+     */
+    readonly __decorated?: TDecorated;
+}
+
 /**
- * Plugin metadata for registration and discovery
+ * @nextrush/types - Standard Schema Contract
+ *
+ * Structural copy of the `@standard-schema/spec` v1 interface
+ * (https://github.com/standard-schema/standard-schema, MIT licensed), vendored
+ * as a type so NextRush stays dependency-free. It lives in `@nextrush/types`
+ * (not in any single consumer) because it is now a shared contract: request
+ * validation, route metadata, and OpenAPI generation all reference it.
+ *
+ * Because TypeScript is structural, any schema implementing Standard Schema —
+ * Zod 3.24+, Valibot 1.0+, ArkType 2.0+, and others — satisfies this interface
+ * without an adapter.
+ *
+ * @packageDocumentation
  */
-interface PluginMeta {
-    /** Plugin name */
-    name: string;
-    /** Plugin version */
-    version: string;
-    /** Plugin description */
-    description?: string;
-    /** Plugin author */
-    author?: string;
-    /** Plugin repository URL */
-    repository?: string;
-    /** Plugin dependencies (other plugin names) */
-    dependencies?: string[];
+/**
+ * A schema that exposes the Standard Schema v1 contract on its `~standard`
+ * property. This is the only surface NextRush depends on.
+ */
+interface StandardSchemaV1<Input = unknown, Output = Input> {
+    readonly '~standard': StandardSchemaProps<Input, Output>;
+}
+/** The `~standard` property contract. */
+interface StandardSchemaProps<Input = unknown, Output = Input> {
+    /** Spec version — always `1`. */
+    readonly version: 1;
+    /** Identifier of the schema library (e.g. `'zod'`, `'valibot'`). */
+    readonly vendor: string;
+    /** Validates and (optionally) coerces `value`; may be sync or async. */
+    readonly validate: (value: unknown) => StandardSchemaResult<Output> | Promise<StandardSchemaResult<Output>>;
+    /** Phantom types for input/output inference; never present at runtime. */
+    readonly types?: {
+        readonly input: Input;
+        readonly output: Output;
+    } | undefined;
+}
+/** Result of a validation: either a success carrying `value`, or a failure carrying `issues`. */
+type StandardSchemaResult<Output> = {
+    readonly value: Output;
+    readonly issues?: undefined;
+} | {
+    readonly issues: readonly StandardSchemaIssue[];
+};
+/** A single validation issue reported by a schema. */
+interface StandardSchemaIssue {
+    /** Human-readable message. */
+    readonly message: string;
+    /** Path to the offending value; segments are keys or `{ key }` objects. */
+    readonly path?: readonly (PropertyKey | StandardSchemaPathSegment)[] | undefined;
+}
+/** A structured path segment. */
+interface StandardSchemaPathSegment {
+    readonly key: PropertyKey;
+}
+/** Infer the validated output type of a Standard Schema. */
+type InferOutput<S extends StandardSchemaV1> = NonNullable<S['~standard']['types']>['output'];
+
+/**
+ * @nextrush/types - Route Metadata Contracts
+ *
+ * `RouteDefinition` is the single source of truth for what a route *is and
+ * means*. The router collects it once at registration; renderers
+ * (`@nextrush/openapi`, and later SDK/Postman/RPC generators) read it. The
+ * router itself is renderer-agnostic — it stores raw schemas and generic
+ * metadata, never OpenAPI shapes.
+ *
+ * See docs/RFC/request-data/002-route-metadata.md.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Well-known symbol by which anything — a middleware function (e.g. `validate()`)
+ * or a pure marker (e.g. `endpoint()`) — contributes metadata to the route it is
+ * registered on. The router reads this symbol off every route entry at
+ * registration and merges the contributions.
+ *
+ * `Symbol.for` (global registry) is used so the identity holds even across
+ * duplicate package instances.
+ */
+declare const ROUTE_METADATA: unique symbol;
+/** A partial metadata contribution; contributions merge in registration order. */
+type MetadataContribution = Partial<RouteMetadata>;
+/**
+ * A pure-metadata marker carried in a route's argument list. Not a middleware —
+ * it has no runtime behavior and never enters the executed chain.
+ */
+interface RouteMetaMarker {
+    readonly [ROUTE_METADATA]: MetadataContribution;
+}
+/** An entry in a route's argument list: behavior (`Middleware`) or pure metadata (a marker). */
+type RouteEntry = Middleware | RouteMetaMarker;
+/**
+ * Generic, renderer-agnostic description of a route's request/response shapes
+ * and documentation facts. Every field is a fact any renderer needs; no
+ * renderer-specific artifacts (e.g. OpenAPI `operationId`) live here.
+ */
+interface RouteMetadata {
+    /** Request shapes — contributed by `validate()`; never hand-written on the golden path. */
+    readonly request?: {
+        readonly body?: StandardSchemaV1;
+        readonly query?: StandardSchemaV1;
+        readonly params?: StandardSchemaV1;
+    };
+    /** Response shapes by numeric status — contributed by `endpoint()`. */
+    readonly responses?: Readonly<Record<number, StandardSchemaV1>>;
+    readonly summary?: string;
+    readonly description?: string;
+    readonly tags?: readonly string[];
+    readonly deprecated?: boolean;
+    /** Cross-renderer intent — an `'internal'` route is excluded from public specs/SDKs. */
+    readonly visibility?: 'public' | 'internal';
+}
+/**
+ * The canonical description of a registered endpoint, produced by the router
+ * and consumed by renderers.
+ */
+interface RouteDefinition {
+    /**
+     * Canonical route key — `${METHOD} ${pathPattern}` (e.g. `"GET /users/:id"`),
+     * the key the router uses internally. Deterministic and stable across
+     * restarts, but it encodes the path, so it changes if the path or a param
+     * name changes — a key, not a rename-stable opaque id.
+     */
+    readonly key: string;
+    readonly method: HttpMethod;
+    /** Full, mount/prefix-resolved path pattern. */
+    readonly path: string;
+    readonly metadata?: RouteMetadata;
+    /**
+     * `true` when this entry represents an any-method route (registered via
+     * `router.all()` / `@All()`), matching every standard HTTP method under a
+     * single introspection row rather than one row per method (T016). `method`
+     * is still a real `HttpMethod` value for structural compatibility with
+     * existing consumers that read `.method` unconditionally — check this flag
+     * first when the distinction matters (e.g. an OpenAPI renderer expanding
+     * one row into per-verb operations). Absent (`undefined`) for every
+     * ordinary single-method route.
+     */
+    readonly isAnyMethod?: boolean;
 }
 
 /**
  * @nextrush/types - Router Type Definitions
  *
  * Types for the NextRush router system.
- * The router uses a radix tree for efficient route matching.
+ * The router matches routes with a segment trie keyed by whole path segments,
+ * giving O(k) lookups where k is the number of path segments.
  *
  * @packageDocumentation
  */
@@ -820,43 +1525,53 @@ interface Router {
     /**
      * Register a GET route
      */
-    get(path: string, ...handlers: RouteHandler[]): this;
+    get(path: string, ...entries: RouteEntry[]): this;
     /**
      * Register a POST route
      */
-    post(path: string, ...handlers: RouteHandler[]): this;
+    post(path: string, ...entries: RouteEntry[]): this;
     /**
      * Register a PUT route
      */
-    put(path: string, ...handlers: RouteHandler[]): this;
+    put(path: string, ...entries: RouteEntry[]): this;
     /**
      * Register a DELETE route
      */
-    delete(path: string, ...handlers: RouteHandler[]): this;
+    delete(path: string, ...entries: RouteEntry[]): this;
     /**
      * Register a PATCH route
      */
-    patch(path: string, ...handlers: RouteHandler[]): this;
+    patch(path: string, ...entries: RouteEntry[]): this;
     /**
      * Register a HEAD route
      */
-    head(path: string, ...handlers: RouteHandler[]): this;
+    head(path: string, ...entries: RouteEntry[]): this;
     /**
      * Register an OPTIONS route
      */
-    options(path: string, ...handlers: RouteHandler[]): this;
+    options(path: string, ...entries: RouteEntry[]): this;
     /**
      * Register a route for any HTTP method
      */
-    all(path: string, ...handlers: RouteHandler[]): this;
+    all(path: string, ...entries: RouteEntry[]): this;
     /**
      * Register a route for specific method
      */
-    route(method: HttpMethod, path: string, ...handlers: RouteHandler[]): this;
+    route(method: HttpMethod, path: string, ...entries: RouteEntry[]): this;
     /**
      * Mount router middleware
      */
-    use(path: string, router: Router): this;
+    /**
+     * Mount middleware.
+     *
+     * @remarks
+     * Sub-router mounting (`router.use(path, subRouter)`) is a concrete
+     * `@nextrush/router` `Router` capability, not part of this structural
+     * interface — mounting needs internal tree access
+     * (`Router.mount()`/the concrete class's own `use()` overload provide it).
+     * Cross-package router composition goes through `Application.route()`
+     * (`Routable`, `routes()`-only) instead.
+     */
     use(middleware: Middleware): this;
     /**
      * Register a redirect from one path to another
@@ -871,6 +1586,12 @@ interface Router {
      * Mount this on the application
      */
     routes(): Middleware;
+    /**
+     * Return every registered route as a read-only list of RouteDefinitions.
+     * Consumed by renderers (`@nextrush/openapi`, SDK/Postman generators).
+     * Doc-generation-time projection — never called on the request hot path.
+     */
+    getRoutes(): readonly RouteDefinition[];
     /**
      * Match a route
      */
@@ -895,6 +1616,13 @@ interface RouterOptions {
      * @default false
      */
     strict?: boolean;
+    /**
+     * Whether to percent-decode extracted param and wildcard values
+     * (via `decodeURIComponent`). Malformed encoding falls back to the raw value
+     * and never throws. Set to `false` to receive raw, undecoded values.
+     * @default true
+     */
+    decode?: boolean;
 }
 /**
  * Supported route pattern types
@@ -912,4 +1640,61 @@ interface RouteParam {
     pattern?: RegExp;
 }
 
-export { type ApplicationLike, type BodySource, type BodySourceOptions, type CommonHttpMethod, ContentType, type ContentTypeValue, type Context, type ContextOptions, type ContextState, HTTP_METHODS, type HttpMethod, HttpStatus, type HttpStatusCode, type IncomingHeaders, type Middleware, type Next, type NodeStreamLike, type OutgoingHeaders, type ParsedBody, type Plugin, type PluginFactory, type PluginMeta, type PluginWithHooks, type QueryParams, type RawHttp, type ResponseBody, type Route, type RouteHandler, type RouteMatch, type RouteParam, type RouteParams, type RoutePattern, type Router, type RouterOptions, type Runtime, type RuntimeCapabilities, type RuntimeInfo, type WebStreamLike };
+/**
+ * @nextrush/types - Security Audit Contribution Contract
+ *
+ * `core` cannot import `@nextrush/{cors,static,cookies,errors}` (lower
+ * packages never import from higher ones — `architecture.instructions.md`),
+ * so `Application` cannot inspect a middleware instance's configuration
+ * directly. This contract lets a middleware factory (`cors()`, `serveStatic()`,
+ * `cookies()`, `errorHandler()`, …) optionally attach a boot-time check to the
+ * `Middleware` function it already returns from `app.use()` — the same
+ * "contribute via a well-known symbol, the owner collects it later" shape as
+ * {@link ROUTE_METADATA}, applied to production-safety auditing instead of
+ * route documentation (RFC gates this in `docs/RFC/` under the
+ * `security-boundaries` capability's boot-audit requirement).
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Well-known symbol by which a middleware factory contributes a security
+ * audit check to the `Middleware` function it returns. `Application.use()`
+ * reads this symbol off every registered middleware and collects any checks
+ * present; `app.ready()` runs the collected set once, in production only.
+ *
+ * `Symbol.for` (global registry) matches {@link ROUTE_METADATA}'s choice, so
+ * identity holds even across duplicate package instances.
+ */
+declare const SECURITY_AUDIT: unique symbol;
+/**
+ * The outcome of one security audit check.
+ *
+ * - `ok` — configuration is safe; nothing is reported.
+ * - `warn` — configuration is unsafe but has a legitimate use; logged once,
+ *   never blocks boot.
+ * - `throw` — configuration has no legitimate production use; boot fails.
+ */
+type SecurityAuditVerdict = {
+    readonly level: 'ok';
+} | {
+    readonly level: 'warn';
+    readonly message: string;
+} | {
+    readonly level: 'throw';
+    readonly message: string;
+};
+/**
+ * A middleware's self-reported boot-time safety check, invoked only when the
+ * application is booting in production. Pure and synchronous — a check
+ * inspects configuration already closed over at construction time, never I/O.
+ */
+type SecurityAuditCheck = () => SecurityAuditVerdict;
+/** A middleware function carrying a {@link SecurityAuditCheck} contribution. */
+interface SecurityAudited {
+    readonly [SECURITY_AUDIT]: SecurityAuditCheck;
+}
+/** A registered middleware, optionally carrying a security audit contribution. */
+type AuditableMiddleware = Middleware & Partial<SecurityAudited>;
+
+export { type AdapterContext, type AdapterContextFactory, type AuditableMiddleware, type BaseStreamWriter, type BodySource, type BodySourceOptions, type ClassProvider, type CommonHttpMethod, type Constructor, type Container, ContentType, type ContentTypeValue, type Context, type ContextOptions, type ContextState, type Extension, type ExtensionContext, type ExtensionHost, type FactoryProvider, type FetchAdapter, type FetchContext, type FetchHandler, type FetchHandlerOptions, HTTP_METHODS, type HandlerOptions, type HttpMethod, HttpStatus, type HttpStatusCode, type IncomingHeaders, type InferOutput, type Logger, type MetadataContribution, type Middleware, type NDJSONStreamWriter, type Next, type NodeStreamLike, type OutgoingHeaders, type ParsedBody, type PlatformId, type Provider, type ProxyTrust, type QueryParams, ROUTE_METADATA, type RawHttp, type RegisterOptions, type ResponseBody, type Route, type RouteDefinition, type RouteEntry, type RouteHandler, type RouteMatch, type RouteMetaMarker, type RouteMetadata, type RouteParam, type RouteParams, type RoutePattern, type Router, type RouterOptions, type Runtime, type RuntimeCapabilities, type RuntimeInfo, SECURITY_AUDIT, type SSEEvent, type SSEStreamWriter, type Scope, type SecurityAuditCheck, type SecurityAuditVerdict, type SecurityAudited, type ServerAdapter, type ServerAddress, type ServerHandle, type ServiceOptions, type StandardSchemaIssue, type StandardSchemaPathSegment, type StandardSchemaProps, type StandardSchemaResult, type StandardSchemaV1, type StreamRun, type StreamSource, type TextStreamWriter, type Token, type ValueProvider, type WebStreamLike };