@daloyjs/core 1.0.0-beta.5 → 1.0.0-beta.7

package/README.md

@@ -509,7 +509,7 @@ The core only ever sees `Request → Response`. Adapters live at the edge.
 
 ## Status
 
-DaloyJS is now in the **`1.0.0` beta** (`1.0.0-beta.5`). The public API is feature-complete and stable for the 1.0 line; from `1.0.0` onward, breaking changes follow SemVer and deprecations get at least one minor cycle. Small adjustments are still possible before the `1.0.0` GA if beta feedback surfaces something. The framework is already in use for production trials.
+DaloyJS is now in the **`1.0.0` beta** (`1.0.0-beta.7`). The public API is feature-complete and stable for the 1.0 line; from `1.0.0` onward, breaking changes follow SemVer and deprecations get at least one minor cycle. Small adjustments are still possible before the `1.0.0` GA if beta feedback surfaces something. The framework is already in use for production trials.
 
 **Release quality bar.** Every release ships with **≥90% line + function coverage and ≥90% branch coverage**, strict TypeScript, OpenSSF Scorecard, CodeQL + Opengrep dual SAST, zizmor workflow linting, and npm provenance. Coverage was relaxed from a former 100% gate so complex security work isn't blocked chasing throwaway tests for unreachable defensive branches or tsx source-map phantoms; see [AGENTS.md](AGENTS.md) for the policy.
 
@@ -520,6 +520,7 @@ DaloyJS is now in the **`1.0.0` beta** (`1.0.0-beta.5`). The public API is featu
 - Zero-config OpenAPI `info` autofill from `package.json` (Node / Bun) or `deno.json` / `deno.jsonc` (Deno); explicit `openapi.info` values always win.
 - RFC 7231 + RFC 5789 HTTP-method allowlist enforced inside `app.route()` (WebDAV, `TRACE`, `CONNECT` rejected at the framework boundary).
 - AI-friendly route metadata via optional `meta: { examples, extensions, summary, description, tags }`; examples are validated against your schemas at build time, surfaced as OpenAPI `examples` + `x-daloy-*` extensions, and dumped as `routes.json` / `routes.yaml` via `daloy inspect --ai`.
+- Dependency-free MCP Streamable HTTP server helpers at `@daloyjs/core/mcp`: `createMcpHandler()` exposes tools (with `outputSchema`, `annotations`, and icons), resources, RFC 6570 resource templates, and prompts (with required-argument enforcement) over JSON-RPC 2.0 and validates `Origin` against DNS rebinding (with an `allowedOrigins` allowlist), while `mcpRoutes("/mcp", handler)` mounts the POST / GET / OPTIONS Daloy routes — with the JSON-RPC envelope schema surfaced in OpenAPI — for a dedicated MCP service with the same auth, rate-limit, body-limit, and timeout middleware as any other app.
 - API lifecycle and breaking-change detection: mark routes `deprecated` or give them a `sunset` date to emit RFC 8594 `Deprecation` / `Sunset` headers and an `x-sunset` OpenAPI extension, then gate CI with `diffOpenAPI()` / the `daloy diff` command, which fail on a breaking change versus the last published spec.
 - In-process test client (`app.request()`), contract-test runner (gated in CI via `daloy inspect --check` and shipped as a default test in every `create-daloy` template), in-process typed client, and Hey API codegen via `pnpm gen`.
 

package/dist/adapters/bun.d.ts

@@ -18,7 +18,9 @@ export interface BunTLSOptions {
 }
 /** Options forwarded to `Bun.serve` by {@link serve}. */
 export interface BunServeOptions {
+    /** TCP port to listen on. Ignored when `unix` is set. Defaults to `3000`. */
     port?: number;
+    /** Interface to bind. Ignored when `unix` is set. Defaults to `"0.0.0.0"`. */
     hostname?: string;
     /** Maximum request body bytes (Bun-level cap). Default: 16 MiB. */
     maxRequestBodySize?: number;
@@ -33,9 +35,19 @@ export interface BunServeOptions {
 }
 /** Handle returned by {@link serve} for shutdown and listener introspection. */
 export interface BunServerHandle {
+    /** Port the server is actually listening on (as reported by Bun). */
     port: number;
+    /** Server URL as reported by `Bun.serve` (e.g. for startup logging), if available. */
     url: URL | undefined;
+    /** Graceful stop: drains {@link App.shutdown} hooks first, then force-stops the Bun server. */
     stop: () => Promise<void>;
 }
-/** Start `Bun.serve` bound to the given {@link App}, wiring HTTP and WebSocket routes. */
+/**
+ * Start `Bun.serve` bound to the given {@link App}, wiring HTTP and WebSocket routes.
+ *
+ * @param app - The DaloyJS {@link App} whose `fetch` (and WebSocket routes) serve requests.
+ * @param opts - Listener options forwarded to `Bun.serve`; see {@link BunServeOptions}.
+ * @returns A {@link BunServerHandle} exposing the bound `port`, `url`, and a graceful `stop()`.
+ * @throws Error when the Bun runtime (`globalThis.Bun.serve`) is not detected.
+ */
 export declare function serve(app: App, opts?: BunServeOptions): BunServerHandle;

package/dist/adapters/bun.js

@@ -1,5 +1,12 @@
 import { WS_READY_STATE, WS_CLOSE_CODE, WS_MAX_CONTROL_PAYLOAD, encodeSendPayload, parseSubprotocols, validateSelectedSubprotocol, checkWebSocketOrigin, WebSocketProtocolError, } from "../websocket.js";
-/** Start `Bun.serve` bound to the given {@link App}, wiring HTTP and WebSocket routes. */
+/**
+ * Start `Bun.serve` bound to the given {@link App}, wiring HTTP and WebSocket routes.
+ *
+ * @param app - The DaloyJS {@link App} whose `fetch` (and WebSocket routes) serve requests.
+ * @param opts - Listener options forwarded to `Bun.serve`; see {@link BunServeOptions}.
+ * @returns A {@link BunServerHandle} exposing the bound `port`, `url`, and a graceful `stop()`.
+ * @throws Error when the Bun runtime (`globalThis.Bun.serve`) is not detected.
+ */
 export function serve(app, opts = {}) {
     const Bun = globalThis.Bun;
     if (!Bun?.serve)

package/dist/adapters/cloudflare.d.ts

@@ -18,12 +18,18 @@
 import type { App } from "../app.js";
 /** Module shape expected by the Cloudflare Workers runtime as `export default`. */
 export interface ExportedFetchHandler<Env = unknown> {
+    /** Worker entry point: forwards the request to {@link App.fetch}. `env`/`ctx` are accepted but unused by the adapter. */
     fetch: (request: Request, env?: Env, ctx?: ExecutionContextLike) => Promise<Response>;
 }
 interface ExecutionContextLike {
     waitUntil?: (promise: Promise<unknown>) => void;
     passThroughOnException?: () => void;
 }
-/** Wrap an {@link App} in the `{ fetch }` object expected by Cloudflare Workers and other web-standard hosts. */
+/**
+ * Wrap an {@link App} in the `{ fetch }` object expected by Cloudflare Workers and other web-standard hosts.
+ *
+ * @param app - The DaloyJS {@link App} that serves each incoming request.
+ * @returns An {@link ExportedFetchHandler} suitable as the module's `export default`.
+ */
 export declare function toFetchHandler<Env = unknown>(app: App): ExportedFetchHandler<Env>;
 export {};

package/dist/adapters/cloudflare.js

@@ -1,4 +1,9 @@
-/** Wrap an {@link App} in the `{ fetch }` object expected by Cloudflare Workers and other web-standard hosts. */
+/**
+ * Wrap an {@link App} in the `{ fetch }` object expected by Cloudflare Workers and other web-standard hosts.
+ *
+ * @param app - The DaloyJS {@link App} that serves each incoming request.
+ * @returns An {@link ExportedFetchHandler} suitable as the module's `export default`.
+ */
 export function toFetchHandler(app) {
     return {
         fetch: (req) => app.fetch(req),

package/dist/adapters/deno.d.ts

@@ -9,7 +9,9 @@
 import type { App } from "../app.js";
 /** Options forwarded to `Deno.serve` by {@link serve}. */
 export interface DenoServeOptions {
+    /** TCP port to listen on. Defaults to `3000`. */
     port?: number;
+    /** Interface to bind. Defaults to `"0.0.0.0"`. */
     hostname?: string;
     /** Optional external signal that triggers graceful shutdown. */
     signal?: AbortSignal;
@@ -31,7 +33,15 @@ export interface DenoServeOptions {
 }
 /** Handle returned by {@link serve}; call `shutdown()` to drain. */
 export interface DenoServerHandle {
+    /** Graceful shutdown: drains {@link App.shutdown} hooks, then stops the Deno server. Idempotent. */
     shutdown: () => Promise<void>;
 }
-/** Start `Deno.serve` bound to the given {@link App} with graceful-shutdown wiring. */
+/**
+ * Start `Deno.serve` bound to the given {@link App} with graceful-shutdown wiring.
+ *
+ * @param app - The DaloyJS {@link App} whose `fetch` serves each request.
+ * @param opts - Listener/TLS/shutdown options; see {@link DenoServeOptions}.
+ * @returns A {@link DenoServerHandle} whose `shutdown()` drains in-flight requests.
+ * @throws Error when the Deno runtime (`globalThis.Deno.serve`) is not detected.
+ */
 export declare function serve(app: App, opts?: DenoServeOptions): DenoServerHandle;

package/dist/adapters/deno.js

@@ -1,4 +1,11 @@
-/** Start `Deno.serve` bound to the given {@link App} with graceful-shutdown wiring. */
+/**
+ * Start `Deno.serve` bound to the given {@link App} with graceful-shutdown wiring.
+ *
+ * @param app - The DaloyJS {@link App} whose `fetch` serves each request.
+ * @param opts - Listener/TLS/shutdown options; see {@link DenoServeOptions}.
+ * @returns A {@link DenoServerHandle} whose `shutdown()` drains in-flight requests.
+ * @throws Error when the Deno runtime (`globalThis.Deno.serve`) is not detected.
+ */
 export function serve(app, opts = {}) {
     const D = globalThis.Deno;
     const denoServe = D?.serve;

package/dist/adapters/fastly.d.ts

@@ -18,7 +18,17 @@
  * multipart helpers that rely on `node:stream`).
  */
 import type { App } from "../app.js";
-/** Wrap an {@link App} in a `(req) => Promise<Response>` function suitable for Fastly Compute. */
+/**
+ * Wrap an {@link App} in a `(req) => Promise<Response>` function suitable for Fastly Compute.
+ *
+ * @param app - The DaloyJS {@link App} that serves each incoming request.
+ * @returns A web-standard handler delegating to {@link App.fetch}.
+ */
 export declare function toFastlyHandler(app: App): (req: Request) => Promise<Response>;
-/** Register a Fastly Compute `fetch` event listener that delegates to the given {@link App}. */
+/**
+ * Register a Fastly Compute `fetch` event listener that delegates to the given {@link App}.
+ *
+ * @param app - The DaloyJS {@link App} that serves each incoming request.
+ * @throws Error when `globalThis.addEventListener` is missing (not a Fastly Compute runtime).
+ */
 export declare function installFastlyListener(app: App): void;

package/dist/adapters/fastly.js

@@ -1,8 +1,18 @@
-/** Wrap an {@link App} in a `(req) => Promise<Response>` function suitable for Fastly Compute. */
+/**
+ * Wrap an {@link App} in a `(req) => Promise<Response>` function suitable for Fastly Compute.
+ *
+ * @param app - The DaloyJS {@link App} that serves each incoming request.
+ * @returns A web-standard handler delegating to {@link App.fetch}.
+ */
 export function toFastlyHandler(app) {
     return (req) => app.fetch(req);
 }
-/** Register a Fastly Compute `fetch` event listener that delegates to the given {@link App}. */
+/**
+ * Register a Fastly Compute `fetch` event listener that delegates to the given {@link App}.
+ *
+ * @param app - The DaloyJS {@link App} that serves each incoming request.
+ * @throws Error when `globalThis.addEventListener` is missing (not a Fastly Compute runtime).
+ */
 export function installFastlyListener(app) {
     const g = globalThis;
     if (typeof g.addEventListener !== "function") {

package/dist/adapters/lambda.d.ts

@@ -13,28 +13,45 @@ import type { App } from "../app.js";
  * The adapter performs no Node-only I/O, so it is safe in any runtime that
  * provides the standard `Request`/`Response`/`atob`/`btoa` globals.
  */
+/** API Gateway REST API event (payload format v1.0). */
 export interface LambdaEventV1 {
+    /** Payload format version; `"1.0"` or absent for REST API events. */
     version?: "1.0" | string;
+    /** URL path of the request (e.g. `/users/42`). */
     path?: string;
+    /** HTTP method (e.g. `GET`). */
     httpMethod?: string;
+    /** Request headers, one value per name (last value wins in v1.0). */
     headers?: Record<string, string | undefined>;
+    /** Request headers with every value per name; `cookie` values are re-joined with `; `. */
     multiValueHeaders?: Record<string, string[] | undefined>;
+    /** Query parameters, one value per name. Used only when the multi-value map is empty. */
     queryStringParameters?: Record<string, string | undefined> | null;
+    /** Query parameters with every value per name; preferred over the single-value map. */
     multiValueQueryStringParameters?: Record<string, string[] | undefined> | null;
+    /** Request context; `domainName` is the host fallback and `path` the path fallback. */
     requestContext?: {
         domainName?: string;
         path?: string;
     };
+    /** Raw request body; base64-encoded when {@link LambdaEventV1.isBase64Encoded} is true. */
     body?: string;
+    /** True when `body` is base64-encoded (binary payloads). */
     isBase64Encoded?: boolean;
 }
 /** API Gateway HTTP API or Lambda Function URL event (payload format v2.0). */
 export interface LambdaEventV2 {
+    /** Payload format version; `"2.0"` for HTTP API / Function URL events. */
     version?: string;
+    /** URL path of the request, without the query string. */
     rawPath?: string;
+    /** Raw query string without the leading `?` (empty string when none). */
     rawQueryString?: string;
+    /** Request headers; multi-value headers arrive comma-joined in v2.0. */
     headers?: Record<string, string | undefined>;
+    /** Request cookies as individual strings; re-joined with `; ` into a `cookie` header. */
     cookies?: string[];
+    /** Request context; `http.method`/`http.path` carry the method and path, `domainName` the host fallback. */
     requestContext?: {
         http?: {
             method?: string;
@@ -42,32 +59,51 @@ export interface LambdaEventV2 {
         };
         domainName?: string;
     };
+    /** Raw request body; base64-encoded when {@link LambdaEventV2.isBase64Encoded} is true. */
     body?: string;
+    /** True when `body` is base64-encoded (binary payloads). */
     isBase64Encoded?: boolean;
 }
 /** Either payload format accepted by {@link toLambdaHandler}. */
 export type LambdaEvent = LambdaEventV1 | LambdaEventV2;
 /** Lambda response shape required by API Gateway REST API (payload format v1.0). */
 export interface LambdaResponseV1 {
+    /** HTTP status code of the response. */
     statusCode: number;
+    /** Response headers, one value per name (`set-cookie` excluded; see `multiValueHeaders`). */
     headers: Record<string, string>;
+    /** Multi-value headers; used to carry each `set-cookie` value separately in v1.0. */
     multiValueHeaders?: Record<string, string[]>;
+    /** Never present in v1.0 responses; cookies travel via `multiValueHeaders`. */
     cookies?: never;
+    /** Response body; base64-encoded when {@link LambdaResponseV1.isBase64Encoded} is true. */
     body: string;
+    /** True when `body` is base64-encoded (non-text content types). */
     isBase64Encoded: boolean;
 }
 /** Lambda response shape required by API Gateway HTTP API and Function URLs (payload format v2.0). */
 export interface LambdaResponseV2 {
+    /** HTTP status code of the response. */
     statusCode: number;
+    /** Response headers, one value per name (`set-cookie` excluded; see `cookies`). */
     headers: Record<string, string>;
+    /** Response cookies, one `set-cookie` value per entry (v2.0's cookie channel). */
     cookies?: string[];
+    /** Never present in v2.0 responses; cookies travel via `cookies`. */
     multiValueHeaders?: never;
+    /** Response body; base64-encoded when {@link LambdaResponseV2.isBase64Encoded} is true. */
     body: string;
+    /** True when `body` is base64-encoded (non-text content types). */
     isBase64Encoded: boolean;
 }
 /** Either response shape produced by {@link toLambdaHandler}, chosen automatically per event. */
 export type LambdaResponse = LambdaResponseV1 | LambdaResponseV2;
 /** Async handler shape consumed by AWS Lambda / Netlify Functions runtimes. */
 export type LambdaHandler = (event: LambdaEvent) => Promise<LambdaResponse>;
-/** Wrap an {@link App} as a Lambda/Netlify handler accepting either v1.0 or v2.0 event payloads. */
+/**
+ * Wrap an {@link App} as a Lambda/Netlify handler accepting either v1.0 or v2.0 event payloads.
+ *
+ * @param app - The DaloyJS {@link App} that serves each translated request.
+ * @returns A {@link LambdaHandler} that converts the event to a `Request`, calls {@link App.fetch}, and emits the matching v1.0/v2.0 response shape.
+ */
 export declare function toLambdaHandler(app: App): LambdaHandler;

package/dist/adapters/lambda.js

@@ -1,5 +1,10 @@
 const TEXT_TYPE_RE = /^(text\/|application\/(json|xml|javascript|x-www-form-urlencoded|.*\+json|.*\+xml))/i;
-/** Wrap an {@link App} as a Lambda/Netlify handler accepting either v1.0 or v2.0 event payloads. */
+/**
+ * Wrap an {@link App} as a Lambda/Netlify handler accepting either v1.0 or v2.0 event payloads.
+ *
+ * @param app - The DaloyJS {@link App} that serves each translated request.
+ * @returns A {@link LambdaHandler} that converts the event to a `Request`, calls {@link App.fetch}, and emits the matching v1.0/v2.0 response shape.
+ */
 export function toLambdaHandler(app) {
     return async (event) => {
         const request = eventToRequest(event);

package/dist/adapters/node.d.ts

@@ -6,7 +6,9 @@ import { type Server } from "node:http";
 import type { App } from "../app.js";
 /** Options for the Node.js {@link serve} entry point. */
 export interface NodeServerOptions {
+    /** TCP port to listen on. Defaults to `3000`. */
     port?: number;
+    /** Interface to bind. Defaults to `"0.0.0.0"`. */
     hostname?: string;
     /**
      * Connection-level timeout in ms, applied to BOTH `headersTimeout` and
@@ -72,9 +74,18 @@ export interface NodeServerOptions {
 }
 /** Handle returned by {@link serve} exposing the underlying Node `Server` plus a `close()` for graceful shutdown. */
 export interface NodeServerHandle {
+    /** The underlying `node:http` `Server` instance, for advanced wiring (extra listeners, address introspection). */
     server: Server;
+    /** Port the server was asked to listen on ({@link NodeServerOptions.port}, default `3000`). */
     port: number;
+    /** Graceful shutdown: drains {@link App.shutdown} hooks, destroys WebSocket sockets, then closes the server. Idempotent. */
     close(): Promise<void>;
 }
-/** Start a Node.js HTTP (and optional WebSocket) server bound to the given {@link App}. */
+/**
+ * Start a Node.js HTTP (and optional WebSocket) server bound to the given {@link App}.
+ *
+ * @param app - The DaloyJS {@link App} whose `fetch` (and WebSocket routes) serve requests.
+ * @param opts - Listener, timeout, proxy-trust, and hardening options; see {@link NodeServerOptions}.
+ * @returns A {@link NodeServerHandle} exposing the Node `Server`, the `port`, and a graceful `close()`.
+ */
 export declare function serve(app: App, opts?: NodeServerOptions): NodeServerHandle;

package/dist/adapters/node.js

@@ -7,7 +7,13 @@ import { Readable } from "node:stream";
 import { DALOY_RAW_BODY, DALOY_RAW_STREAM, DALOY_REQUEST_RAW_BODY } from "../app.js";
 import { setClientCertificate, normalizePeerCertificate, } from "../mtls.js";
 import { FrameSink, encodeFrame, encodeClosePayload, encodeSendPayload, validateUpgrade, validateSelectedSubprotocol, checkWebSocketOrigin, WS_OPCODE, WS_CLOSE_CODE, WS_READY_STATE, WS_MAX_CONTROL_PAYLOAD, WebSocketProtocolError, WebSocketPayloadTooLargeError, } from "../websocket.js";
-/** Start a Node.js HTTP (and optional WebSocket) server bound to the given {@link App}. */
+/**
+ * Start a Node.js HTTP (and optional WebSocket) server bound to the given {@link App}.
+ *
+ * @param app - The DaloyJS {@link App} whose `fetch` (and WebSocket routes) serve requests.
+ * @param opts - Listener, timeout, proxy-trust, and hardening options; see {@link NodeServerOptions}.
+ * @returns A {@link NodeServerHandle} exposing the Node `Server`, the `port`, and a graceful `close()`.
+ */
 export function serve(app, opts = {}) {
     const trustProxy = opts.trustProxy === true;
     const bufferedBodyMaxBytes = typeof opts.bufferedBodyMaxBytes === "number" && opts.bufferedBodyMaxBytes >= 0

package/dist/adapters/vercel.d.ts

@@ -23,16 +23,25 @@ import type { App } from "../app.js";
 export type WebHandler = (req: Request) => Promise<Response>;
 /** Default export shape for Vercel's web-standard `{ fetch }` runtime. */
 export interface FetchHandler {
+    /** Request entry point: forwards the request to {@link App.fetch}. */
     fetch: WebHandler;
 }
 declare const NEXT_METHODS: readonly ["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS", "HEAD"];
 /** Record of per-method handlers expected by a Next.js App Router `route.ts` file. */
 export type RouteHandlers = Record<(typeof NEXT_METHODS)[number], WebHandler>;
-/** Wrap an {@link App} as a single web-standard fetch handler. */
+/**
+ * Wrap an {@link App} as a single web-standard fetch handler.
+ *
+ * @param app - The DaloyJS {@link App} that serves each incoming request.
+ * @returns A {@link WebHandler} delegating to {@link App.fetch}.
+ */
 export declare function toWebHandler(app: App): WebHandler;
 /**
  * Build the default `{ fetch }` export expected by Vercel Node.js Functions
  * in the `/api` directory.
+ *
+ * @param app - The DaloyJS {@link App} that serves each incoming request.
+ * @returns A {@link FetchHandler} object suitable as the module's `export default`.
  */
 export declare function toFetchHandler(app: App): FetchHandler;
 /** Backward-compatible alias for {@link toWebHandler}. */
@@ -40,6 +49,9 @@ export declare const toEdgeHandler: typeof toWebHandler;
 /**
  * Build the `{ GET, POST, ... }` object expected by Next.js App Router
  * `route.ts` files when a DaloyJS app is mounted inside an existing Next app.
+ *
+ * @param app - The DaloyJS {@link App} that serves each incoming request.
+ * @returns A {@link RouteHandlers} record mapping every supported HTTP method to the same {@link WebHandler}.
  */
 export declare function toRouteHandlers(app: App): RouteHandlers;
 export {};

package/dist/adapters/vercel.js

@@ -1,11 +1,19 @@
 const NEXT_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS", "HEAD"];
-/** Wrap an {@link App} as a single web-standard fetch handler. */
+/**
+ * Wrap an {@link App} as a single web-standard fetch handler.
+ *
+ * @param app - The DaloyJS {@link App} that serves each incoming request.
+ * @returns A {@link WebHandler} delegating to {@link App.fetch}.
+ */
 export function toWebHandler(app) {
     return (req) => app.fetch(req);
 }
 /**
  * Build the default `{ fetch }` export expected by Vercel Node.js Functions
  * in the `/api` directory.
+ *
+ * @param app - The DaloyJS {@link App} that serves each incoming request.
+ * @returns A {@link FetchHandler} object suitable as the module's `export default`.
  */
 export function toFetchHandler(app) {
     return { fetch: toWebHandler(app) };
@@ -15,6 +23,9 @@ export const toEdgeHandler = toWebHandler;
 /**
  * Build the `{ GET, POST, ... }` object expected by Next.js App Router
  * `route.ts` files when a DaloyJS app is mounted inside an existing Next app.
+ *
+ * @param app - The DaloyJS {@link App} that serves each incoming request.
+ * @returns A {@link RouteHandlers} record mapping every supported HTTP method to the same {@link WebHandler}.
  */
 export function toRouteHandlers(app) {
     const handler = toWebHandler(app);

package/dist/app.d.ts

@@ -51,7 +51,9 @@ export type SecurityPreset = "internal-service";
 export interface AppOptions {
     /** OpenAPI document metadata */
     title?: string;
+    /** OpenAPI `info.version`. Falls back to the host package manifest version, then `"0.0.0"`. */
     version?: string;
+    /** OpenAPI `info.description`. Falls back to the host package manifest description. */
     description?: string;
     /**
      * Topology-aware security posture preset. See {@link SecurityPreset}.
@@ -350,9 +352,13 @@ export interface AppOptions {
  * @since 0.3.0
  */
 export interface AppOpenAPIOptions {
+    /** OpenAPI `info` object. `title`/`version` fall back to {@link AppOptions.title} / {@link AppOptions.version}, then the host package manifest. */
     info?: Partial<OpenAPIInfo>;
+    /** `servers` array published in the generated document. */
     servers?: OpenAPIOptions["servers"];
+    /** Security schemes stitched into `components.securitySchemes`. */
     securitySchemes?: OpenAPIOptions["securitySchemes"];
+    /** OpenAPI 3.1 top-level `webhooks` operations, keyed by webhook name. */
     webhooks?: OpenAPIOptions["webhooks"];
 }
 /**
@@ -684,18 +690,31 @@ export interface CspReportRouteOptions {
  * @since 0.1.0
  */
 export interface IntrospectedRoute {
+    /** HTTP method the route responds to (e.g. `"GET"`). */
     method: HttpMethod;
+    /** Route path pattern as registered, including any group prefix (e.g. `/users/:id`). */
     path: string;
+    /** OpenAPI operationId, when declared on the route. */
     operationId?: string;
+    /** OpenAPI tags, when declared on the route or inherited from a group. */
     tags?: string[];
+    /** One-line OpenAPI summary, when declared. */
     summary?: string;
+    /** Longer OpenAPI description, when declared. */
     description?: string;
+    /** `true` when the route is marked deprecated in OpenAPI. */
     deprecated?: boolean;
+    /** Whether the route declares a request body schema. */
     hasBody: boolean;
+    /** Whether the route declares a query-string schema. */
     hasQuery: boolean;
+    /** Whether the route declares a path-params schema. */
     hasParams: boolean;
+    /** Whether the route declares a request-headers schema. */
     hasHeaders: boolean;
+    /** Declared response status codes (e.g. `[200, 404]`). */
     responses: number[];
+    /** Security scheme name and required scopes, when the route declares `auth`. */
     auth?: {
         scheme: string;
         scopes?: string[];
@@ -799,10 +818,28 @@ export declare const DALOY_RAW_STREAM: unique symbol;
  */
 type AppendRoute<Routes extends readonly RouteDefinition<any, any, any, any>[], R extends RouteDefinition<any, any, any, any>> = readonly RouteDefinition<any, any, any, any>[] extends Routes ? readonly [R] : readonly [...Routes, R];
 /**
+ * The DaloyJS application: a contract-first router plus a web-standard
+ * `fetch(Request): Promise<Response>` handler that runs unchanged on Node,
+ * Bun, Deno, Cloudflare Workers, and Vercel via the adapters.
+ *
+ * Routes registered with {@link App.route} are validated against their
+ * declared schemas on the way in and out, accumulate in the typed
+ * {@link App.routes} tuple (powering OpenAPI generation and the typed
+ * client), and are served with secure defaults: body limits, request
+ * timeouts, security headers, and prod-mode error redaction.
+ *
+ * @typeParam Routes - Compile-time tuple of registered route definitions,
+ * grown by each {@link App.route} call.
  * @since 0.1.0
  */
 export declare class App<Routes extends readonly RouteDefinition<any, any, any, any>[] = readonly RouteDefinition<any, any, any, any>[]> {
+    /**
+     * Resolved constructor options. The security-relevant trio is always
+     * populated: `validateResponses` (default `true`), `bodyLimitBytes`
+     * (default 1 MiB), and `requestTimeoutMs` (default 30_000 ms).
+     */
     readonly options: Required<Pick<AppOptions, "validateResponses" | "bodyLimitBytes" | "requestTimeoutMs">> & AppOptions;
+    /** Structured logger for the app. Defaults to a JSON-lines console logger; override via `options.logger`. */
     readonly log: Logger;
     /**
      * Public registry: enables OpenAPI gen, typed-client gen, dead-route detection.
@@ -1312,6 +1349,14 @@ export declare class App<Routes extends readonly RouteDefinition<any, any, any,
      * @returns This `App` instance for chaining.
      */
     use(hooks: Hooks): this;
+    /**
+     * Apply an ordered list of plugin extensions to the
+     * group-level hook chain. Each extension's `handler` is wrapped into a
+     * single-event {@link Hooks} bundle so subsequent route registrations
+     * pick it up via the normal hook composition path.
+     * @internal
+     */
+    private applyExtensions;
     /**
      * Decorate `ctx.state` with a value available inside every handler and hook.
      *
@@ -1334,16 +1379,10 @@ export declare class App<Routes extends readonly RouteDefinition<any, any, any,
      *
      * @param key - Property name on `ctx.state`.
      * @param value - Value bound to that property on every request.
+     * @param opts - Pass `{ override: true }` to replace an existing decoration (logged as a warning).
      * @returns This `App` instance for chaining.
+     * @throws Error if `key` is already decorated and `opts.override` is not `true`.
      */
-    /**
-     * Apply an ordered list of plugin extensions to the
-     * group-level hook chain. Each extension's `handler` is wrapped into a
-     * single-event {@link Hooks} bundle so subsequent route registrations
-     * pick it up via the normal hook composition path.
-     * @internal
-     */
-    private applyExtensions;
     decorate<K extends string, V>(key: K, value: V, opts?: {
         override?: boolean;
     }): this;
@@ -1474,13 +1513,6 @@ export declare class App<Routes extends readonly RouteDefinition<any, any, any,
      * @returns Fulfills with the `Response` produced by the matching handler.
      */
     request(input: string | URL | Request, init?: RequestInit): Promise<Response>;
-    /**
-     * Return a JSON-serializable summary of every registered route. Useful for
-     * dead-route detection, dashboards, and tests that want to assert against
-     * the route table without parsing the OpenAPI document.
-     *
-     * @returns Array of one {@link IntrospectedRoute} per registered route.
-     */
     /**
      * Emit a one-time development warning when any route declares a `2xx`
      * response without a body schema, because response-field stripping
@@ -1490,6 +1522,13 @@ export declare class App<Routes extends readonly RouteDefinition<any, any, any,
      * `secureDefaults: false`. See {@link findRoutesMissingResponseBodySchema}.
      */
     private warnMissingResponseBodySchemas;
+    /**
+     * Return a JSON-serializable summary of every registered route. Useful for
+     * dead-route detection, dashboards, and tests that want to assert against
+     * the route table without parsing the OpenAPI document.
+     *
+     * @returns Array of one {@link IntrospectedRoute} per registered route.
+     */
     introspect(): IntrospectedRoute[];
     /**
      * Begin graceful shutdown.
@@ -1532,6 +1571,12 @@ export declare class App<Routes extends readonly RouteDefinition<any, any, any,
 /**
  * Topological sort of plugin extensions. Refuses-at-call
  * on cyclic ordering with a structured error naming the cycle.
+ *
+ * @param exts - Extensions to order by their `before` / `after` constraints (Kahn's algorithm).
+ * @returns The extensions in a valid execution order.
+ * @throws Error on duplicate extension names, on a `before`/`after` cycle
+ * (naming the members), or when two extensions mutate the same response
+ * header without declaring an ordering between each other.
  * @internal
  */
 export declare function topoSortExtensions(exts: ReadonlyArray<PluginExtension>): PluginExtension[];
@@ -1550,13 +1595,16 @@ export declare function topoSortExtensions(exts: ReadonlyArray<PluginExtension>)
  * It powers both the `daloy doctor` `audit.response.bodySchema` finding and
  * the development-mode boot warning emitted on the first request. The result
  * is advisory — a route may legitimately return no body — so callers treat
- * it as a `warn`, never a hard error.
+ * it as a `warn`, never a hard error. Routes that set
+ * `acknowledgeNoResponseBodySchema: true` (including the framework-mounted
+ * docs, AsyncAPI, health, and metrics routes, whose bodies DaloyJS itself
+ * serializes) are skipped: the missing schema is declared intentional.
  *
  * @param routes - Route definitions to inspect (typically `app.routes`).
  * @returns One entry per offending route with the affected `2xx` status codes.
  * @since 0.40.0
  */
-export declare function findRoutesMissingResponseBodySchema(routes: readonly Pick<RouteDefinition<any, any, any, any>, "method" | "path" | "responses">[]): Array<{
+export declare function findRoutesMissingResponseBodySchema(routes: readonly Pick<RouteDefinition<any, any, any, any>, "method" | "path" | "responses" | "acknowledgeNoResponseBodySchema">[]): Array<{
     method: string;
     path: string;
     statuses: number[];
@@ -1575,6 +1623,8 @@ export declare function findRoutesMissingResponseBodySchema(routes: readonly Pic
  * for ergonomics and matches the factory pattern used by Express, Fastify,
  * and Hono adapters.
  *
+ * @param options - Same {@link AppOptions} accepted by the `App` constructor. Default: `{}`.
+ * @returns A new {@link App} instance.
  * @since 0.3.0
  */
 export declare function createApp(options?: AppOptions): App;