@beignet/core 0.0.33 → 0.0.35

package/src/server/server.ts

@@ -1,72 +1,33 @@
 import type { StandardSchemaV1 } from "@standard-schema/spec";
 import {
-  BEIGNET_ERROR_OWNER_HEADER,
-  type ContractErrorDefinition,
-  getContractHeaderSchemas,
   type HttpContractConfig,
   methodSupportsRequestBody,
-  parsePathTemplate,
-  type StandardSchema,
 } from "../contracts/index.js";
 import {
   comparePathParamsToTemplate,
   formatPathParamsMismatch,
   getObjectSchemaShape,
 } from "../contracts/schema-shape.js";
-import {
-  createErrorResponseBody,
-  httpErrors,
-  isAppError,
-  isErrorResponseBody,
-  toErrorResponseBody,
-} from "../errors/index.js";
-import {
-  IdempotencyConflictError,
-  IdempotencyInProgressError,
-} from "../idempotency/index.js";
-import {
-  type MemoInstrumentationEvent,
-  runWithMemoScope,
-} from "../memo/index.js";
+import { createErrorResponseBody } from "../errors/index.js";
+import { runWithMemoScope } from "../memo/index.js";
 import type { AnyPorts } from "../ports/index.js";
-import {
-  AuthUnauthorizedError,
-  EntitlementRequiredError,
-  GateAuthorizationError,
-  isUnboundPort,
-  TenantRequiredError,
-} from "../ports/index.js";
-import {
-  createProviderInstrumentation,
-  type InferProviderPorts,
-  type ProviderInstrumentationTarget,
-  type ProviderSetupResult,
-  resolveProviderInstrumentationPort,
-  type ServiceProvider,
+import { isUnboundPort } from "../ports/index.js";
+import type {
+  InferProviderPorts,
+  ProviderSetupResult,
+  ServiceProvider,
 } from "../providers/index.js";
-import {
-  parseTraceparent,
-  resolveTracingPort,
-  runWithTracing,
-  type TraceContextInput,
-} from "../tracing/index.js";
 import type {
-  ContextSeed,
   ServerContextConfig,
   ServiceContextInputArgs,
 } from "./context.js";
 import { createContextFinalizer, resolveServerContext } from "./context.js";
 import type { ContractLike, ResolveContract } from "./contract-like.js";
 import { resolveContract } from "./contract-like.js";
-import { getRequestIdFromContext } from "./hooks/utils.js";
 import type {
-  AddedCtxFromHooks,
   Handler,
-  HandlerArgs,
   HttpRequestLike,
   HttpResponse,
-  HttpResponseLike,
-  RequestStageTimings,
   ResolvedRoute,
   RouteHook,
   ServerCaughtErrorHook,
@@ -75,209 +36,54 @@ import type {
 } from "./http.js";
 import type { ServerInstrumentationOptions } from "./instrumentation.js";
 import { createServerInstrumentation } from "./instrumentation.js";
-import {
-  getResponseFinalizerHook,
-  type ResponseFinalizerResponseOwner,
-  type ResponseFinalizerValidationState,
-} from "./internal-hooks.js";
-import {
-  loadProviderConfig,
-  parseStandardSchema,
-  SchemaValidationError,
-} from "./providers/index.js";
+import { loadProviderConfig } from "./providers/index.js";
 import type { ActiveRequestContext } from "./request-context.js";
 import {
   enterActiveRequestContext,
   readContextActor,
   readContextTenant,
   runWithActiveRequestContext,
-  setActiveRequestIdentity,
 } from "./request-context.js";
+import {
+  buildHandler,
+  createMemoScopeRecorder,
+  createRequestExecutor,
+} from "./request-executor.js";
+import type { RequestBodyOptions } from "./request-preparation.js";
+import { errorResponse } from "./response-finalization.js";
+import {
+  contractsFromRoutes,
+  createRoutes,
+  defineRoutes,
+  type HandlerRouteDef,
+  type RouteDef,
+  type RouteDefinitionBuilder,
+  type RouteGroup,
+  type RouteGroupBuilder,
+  type Routes,
+} from "./route-definitions.js";
+import {
+  type CompiledPath,
+  compareRouteSpecificity,
+  compilePath,
+} from "./route-matching.js";
 import type { RuntimeIntegrityCheck } from "./runtime-integrity.js";
 import { runRuntimeIntegrityCheck } from "./runtime-integrity.js";
-import type {
-  AnyUseCaseLike,
-  AnyUseCaseRouteDef,
-  UseCaseRouteDef,
-  ValidatedRouteInputs,
-} from "./use-case-route.js";
 import {
   createUseCaseRouteHandler,
   isUseCaseRouteDef,
 } from "./use-case-route.js";
 
-/**
- * Route registration that connects a contract to the handler implementing it.
- *
- * Most apps keep route definitions in `features/<feature>/routes.ts` and
- * compose them with `defineRoutes(...)`.
- */
-export type HandlerRouteDef<
-  Ctx,
-  CLike extends ContractLike = ContractLike,
-  Hooks extends readonly RouteHook<Ctx, object>[] = readonly RouteHook<
-    Ctx,
-    object
-  >[],
-> = {
-  /**
-   * Contract builder or plain contract config for this route.
-   */
-  contract: CLike;
-  /**
-   * Route-scoped hooks that run after group hooks and before the handler.
-   */
-  hooks?: Hooks;
-  /**
-   * Handler that implements the contract.
-   */
-  handle: Handler<Ctx & AddedCtxFromHooks<Hooks>, ResolveContract<CLike>>;
-  useCase?: never;
-  input?: never;
-  status?: never;
-};
-
-/**
- * Route registration for one contract.
- *
- * Routes either bind the contract directly to a use case (`{ contract,
- * useCase }`) or implement a full handler (`{ contract, handle }`). The full
- * handler form is the escape hatch for response headers, streaming, native
- * `Response` values, and multi-status handling.
- */
-export type RouteDef<
-  Ctx,
-  CLike extends ContractLike = ContractLike,
-  Hooks extends readonly RouteHook<Ctx, object>[] = readonly RouteHook<
-    Ctx,
-    object
-  >[],
-> = HandlerRouteDef<Ctx, CLike, Hooks> | AnyUseCaseRouteDef<Ctx, CLike, Hooks>;
-
-// biome-ignore lint/suspicious/noExplicitAny: route contract types are erased at collection boundaries
-type AnyRouteDef = RouteDef<any, any>;
-
-// biome-ignore lint/suspicious/noExplicitAny: route contract types are erased at collection boundaries
-type PlainRouteDef<Ctx> = RouteDef<Ctx, any, readonly []>;
-
-// biome-ignore lint/suspicious/noExplicitAny: route contract types are erased at collection boundaries
-type AnyContractRouteDef<Ctx> = RouteDef<Ctx, any>;
-
-const ROUTE_GROUP_KIND = "beignet.route-group";
-
-/**
- * Named collection of related route registrations.
- *
- * Route groups colocate feature routes and can apply scoped route hooks to
- * every route in the group. `defineRoutes(...)` flattens them before server
- * registration while preserving those hooks.
- */
-export type RouteGroup<
-  Ctx,
-  Routes extends readonly AnyRouteDef[] = readonly AnyRouteDef[],
-> = {
-  /**
-   * Internal marker used by `defineRoutes(...)`.
-   */
-  kind: typeof ROUTE_GROUP_KIND;
-  /**
-   * Human-readable group name.
-   */
-  name: string;
-  /**
-   * Hooks applied to every route in this group.
-   */
-  hooks?: readonly RouteHook<Ctx, object>[];
-  /**
-   * Route definitions in this group.
-   */
-  routes: Routes;
-};
-
-type RouteInput<Ctx> =
-  | AnyContractRouteDef<Ctx>
-  | AnyRouteDef
-  | RouteGroup<Ctx, readonly AnyRouteDef[]>;
-
-type ContextualRouteInput<Ctx> =
-  | PlainRouteDef<Ctx>
-  | RouteGroup<Ctx, readonly AnyRouteDef[]>;
-
-type RouteGroupBuilder<Ctx> = {
-  <
-    const GroupHooks extends readonly RouteHook<Ctx, object>[] = readonly [],
-    const R extends readonly PlainRouteDef<
-      Ctx & AddedCtxFromHooks<GroupHooks>
-    >[] = readonly PlainRouteDef<Ctx & AddedCtxFromHooks<GroupHooks>>[],
-  >(group: {
-    name: string;
-    hooks?: GroupHooks;
-    routes: R & ValidatedRouteInputs<Ctx & AddedCtxFromHooks<GroupHooks>, R>;
-  }): RouteGroup<Ctx, R>;
-  <
-    const GroupHooks extends readonly RouteHook<Ctx, object>[] = readonly [],
-    const R extends readonly AnyRouteDef[] = readonly AnyRouteDef[],
-  >(group: {
-    name: string;
-    hooks?: GroupHooks;
-    routes: R & ValidatedRouteInputs<Ctx & AddedCtxFromHooks<GroupHooks>, R>;
-  }): RouteGroup<Ctx, R>;
-};
-
-type RoutesFromInput<Input> =
-  Input extends RouteGroup<infer _Ctx, infer Routes>
-    ? Routes
-    : Input extends AnyRouteDef
-      ? readonly [Input]
-      : readonly [];
-
-type FlattenRouteInputs<Inputs extends readonly unknown[]> =
-  number extends Inputs["length"]
-    ? readonly AnyRouteDef[]
-    : Inputs extends readonly [infer First, ...infer Rest]
-      ? readonly [...RoutesFromInput<First>, ...FlattenRouteInputs<Rest>]
-      : readonly [];
-
-type ContractsFromRouteList<
-  // biome-ignore lint/suspicious/noExplicitAny: route contract types are erased at this level
-  Routes extends readonly RouteDef<any, any>[],
-> = {
-  readonly [Index in keyof Routes]: Routes[Index] extends RouteDef<
-    // biome-ignore lint/suspicious/noExplicitAny: route contract types are erased at this level
-    any,
-    infer CLike
-  >
-    ? ResolveContract<CLike>
-    : never;
+export type {
+  HandlerRouteDef,
+  RequestBodyOptions,
+  RouteDef,
+  RouteDefinitionBuilder,
+  RouteGroup,
+  RouteGroupBuilder,
+  Routes,
 };
-
-/**
- * Define one route registration with hook-aware handler typing.
- *
- * Direct route objects are still supported. Use this helper when route-scoped
- * hooks enrich `ctx` for a single handler and you want TypeScript to infer the
- * added fields.
- */
-export function defineRoute<Ctx>() {
-  function define<
-    CLike extends ContractLike,
-    UC extends AnyUseCaseLike,
-    const Hooks extends readonly RouteHook<Ctx, object>[] = readonly [],
-  >(
-    route: UseCaseRouteDef<Ctx, CLike, UC, Hooks>,
-  ): UseCaseRouteDef<Ctx, CLike, UC, Hooks>;
-  function define<
-    CLike extends ContractLike,
-    const Hooks extends readonly RouteHook<Ctx, object>[] = readonly [],
-  >(
-    route: HandlerRouteDef<Ctx, CLike, Hooks>,
-  ): HandlerRouteDef<Ctx, CLike, Hooks>;
-  function define(route: unknown): unknown {
-    return route;
-  }
-
-  return define;
-}
+export { contractsFromRoutes, createRoutes, defineRoutes };
 
 /**
  * Loosely typed provider list element.
@@ -297,18 +103,6 @@ type AnyServiceProvider = ServiceProvider<
   any
 >;
 
-/**
- * Request body limits enforced before contract body validation.
- */
-export interface RequestBodyOptions {
-  /**
-   * Maximum request body size in bytes for JSON/text route bodies.
-   *
-   * @default 1048576
-   */
-  maxBytes?: number;
-}
-
 /**
  * Options for creating a Beignet server instance.
  */
@@ -537,1779 +331,6 @@ export interface ServerInstance<
   ports: Ports;
 }
 
-type ExecutionResult<Ctx> = {
-  ctx?: Ctx;
-  response: HttpResponse;
-  error?: unknown;
-  owner?: ResponseOwner;
-};
-
-type ResponseOwner = ResponseFinalizerResponseOwner;
-
-type CompiledPath = {
-  keys: string[];
-  pattern: RegExp;
-  segments: ReturnType<typeof parsePathTemplate>["segments"];
-  normalizedPath: string;
-  shapeKey: string;
-};
-
-class PathDecodeError extends Error {
-  constructor() {
-    super("Malformed URL path");
-    this.name = "PathDecodeError";
-  }
-}
-
-function compilePath(path: string) {
-  const parsed = parsePathTemplate(path);
-  const regexParts = parsed.segments.map((segment) =>
-    segment.kind === "dynamic"
-      ? "([^/]+)"
-      : segment.value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"),
-  );
-  const pattern = new RegExp(`^/${regexParts.join("/")}$`);
-  return { ...parsed, pattern };
-}
-
-function decodeMatchedParams(
-  keys: string[],
-  match: RegExpExecArray,
-): Record<string, string> {
-  const params: Record<string, string> = {};
-  try {
-    keys.forEach((key, index) => {
-      params[key] = decodeURIComponent(match[index + 1]);
-    });
-  } catch (error) {
-    if (error instanceof URIError) {
-      throw new PathDecodeError();
-    }
-    throw error;
-  }
-  return params;
-}
-
-function compareRouteSpecificity(a: CompiledPath, b: CompiledPath): number {
-  const maxLength = Math.max(a.segments.length, b.segments.length);
-  for (let index = 0; index < maxLength; index++) {
-    const aSegment = a.segments[index];
-    const bSegment = b.segments[index];
-
-    if (!aSegment) return 1;
-    if (!bSegment) return -1;
-
-    if (aSegment.kind === bSegment.kind) continue;
-    return aSegment.kind === "static" ? -1 : 1;
-  }
-
-  return 0;
-}
-
-function errorResponse(
-  status: number,
-  code: string,
-  message: string,
-  details?: unknown,
-): HttpResponseLike {
-  return {
-    status,
-    body: createErrorResponseBody({ code, message, details }),
-  };
-}
-
-type RequestValidationLocation = "query" | "path" | "headers" | "body";
-
-function contractDiagnostics(contract: HttpContractConfig) {
-  return {
-    contract: contract.name,
-    method: contract.method,
-    path: contract.path,
-  };
-}
-
-function requestValidationDetails(
-  contract: HttpContractConfig,
-  location: RequestValidationLocation,
-  error?: unknown,
-) {
-  const details = {
-    ...contractDiagnostics(contract),
-    location,
-  };
-
-  if (error instanceof SchemaValidationError) {
-    return {
-      ...details,
-      issues: error.issues,
-    };
-  }
-
-  if (error instanceof Error) {
-    return {
-      ...details,
-      message: error.message,
-    };
-  }
-
-  return details;
-}
-
-function requestValidationError(
-  contract: HttpContractConfig,
-  status: number,
-  code: string,
-  message: string,
-  location: RequestValidationLocation,
-  error?: unknown,
-): HttpResponseLike {
-  return errorResponse(
-    status,
-    code,
-    message,
-    requestValidationDetails(contract, location, error),
-  );
-}
-
-function normalizeResponse(res: HttpResponseLike): HttpResponseLike {
-  return {
-    status: res.status,
-    headers: res.headers,
-    body: res.body,
-  };
-}
-
-function isWebResponse(value: unknown): value is Response {
-  return typeof Response !== "undefined" && value instanceof Response;
-}
-
-function normalizeHttpResponse(res: HttpResponse): HttpResponse {
-  return isWebResponse(res) ? res : normalizeResponse(res);
-}
-
-function withFrameworkErrorOwnerHeader(
-  res: HttpResponseLike,
-  owner: ResponseOwner,
-): HttpResponseLike {
-  if (
-    owner !== "framework" ||
-    res.status < 400 ||
-    !isErrorResponseBody(res.body)
-  ) {
-    return res;
-  }
-
-  return {
-    ...res,
-    headers: {
-      ...(res.headers ?? {}),
-      [BEIGNET_ERROR_OWNER_HEADER]: "framework",
-    },
-  };
-}
-
-function responseOwnerFor(
-  res: HttpResponse,
-  owner?: ResponseOwner,
-): ResponseOwner {
-  if (isWebResponse(res)) return "transport";
-  return owner ?? "route";
-}
-
-function headersToRecord(headers: Headers): Record<string, string> {
-  const record: Record<string, string> = {};
-  headers.forEach((value, key) => {
-    record[key] = value;
-  });
-  return record;
-}
-
-function requestHeadersToRecord(headers: Headers): Record<string, string> {
-  const record: Record<string, string> = {};
-  headers.forEach((value, key) => {
-    record[key.toLowerCase()] = value;
-  });
-  return record;
-}
-
-async function parseHeaderSchemas(
-  schemas: readonly StandardSchema[],
-  rawHeaders: Record<string, string>,
-): Promise<Record<string, unknown>> {
-  let parsedHeaders: Record<string, unknown> = rawHeaders;
-
-  for (const schema of schemas) {
-    const parsed = await parseStandardSchema(schema, rawHeaders);
-    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
-      parsedHeaders = {
-        ...parsedHeaders,
-        ...(parsed as Record<string, unknown>),
-      };
-    } else {
-      parsedHeaders = parsed as Record<string, unknown>;
-    }
-  }
-
-  return parsedHeaders;
-}
-
-function responseForHooks(res: HttpResponse): HttpResponseLike {
-  if (!isWebResponse(res)) {
-    return normalizeResponse(res);
-  }
-
-  return {
-    status: res.status,
-    headers: headersToRecord(res.headers),
-  };
-}
-
-/**
- * Merge hook-applied header changes onto a native web Response.
- *
- * Starts from the native response's `Headers` so `set-cookie` multiplicity is
- * preserved, then applies headers the beforeSend chain added or changed
- * relative to the original headers-only view. The body stream passes through
- * untouched; status and statusText are preserved.
- */
-function mergeNativeResponseHeaders(
-  nativeResponse: Response,
-  originalHeaders: Record<string, string>,
-  finalHeaders: Record<string, string>,
-): Response {
-  const originalByLowerKey = new Map<string, string>();
-  for (const [key, value] of Object.entries(originalHeaders)) {
-    originalByLowerKey.set(key.toLowerCase(), value);
-  }
-
-  let changed = false;
-  const merged = new Headers(nativeResponse.headers);
-  for (const [key, value] of Object.entries(finalHeaders)) {
-    const lowerKey = key.toLowerCase();
-    if (originalByLowerKey.get(lowerKey) === value) continue;
-    changed = true;
-    if (lowerKey === "set-cookie") {
-      merged.append(lowerKey, value);
-    } else {
-      merged.set(key, value);
-    }
-  }
-
-  if (!changed) {
-    return nativeResponse;
-  }
-
-  return new Response(nativeResponse.body, {
-    status: nativeResponse.status,
-    statusText: nativeResponse.statusText,
-    headers: merged,
-  });
-}
-
-function isHttpResponseLike(value: unknown): value is HttpResponseLike {
-  return (
-    !isWebResponse(value) &&
-    typeof value === "object" &&
-    value !== null &&
-    "status" in value &&
-    typeof (value as { status?: unknown }).status === "number"
-  );
-}
-
-class ResponseContractViolationError extends Error {
-  readonly code: "RESPONSE_VALIDATION_ERROR" | "UNDECLARED_RESPONSE_STATUS";
-  readonly details?: unknown;
-
-  constructor(args: {
-    code: "RESPONSE_VALIDATION_ERROR" | "UNDECLARED_RESPONSE_STATUS";
-    message: string;
-    details?: unknown;
-  }) {
-    super(args.message);
-    this.name = "ResponseContractViolationError";
-    this.code = args.code;
-    this.details = args.details;
-  }
-}
-
-function responseContractViolationMessage(
-  contract: HttpContractConfig,
-  status: number,
-): string {
-  return (
-    `Response validation failed for ${contract.method} ${contract.path} ` +
-    `(status ${status}, contract: ${contract.name})`
-  );
-}
-
-function declaredResponseStatuses(contract: HttpContractConfig): number[] {
-  return Object.keys(contract.responses)
-    .map((status) => Number(status))
-    .filter((status) => Number.isFinite(status))
-    .sort((a, b) => a - b);
-}
-
-function responseContractViolationDetails(
-  contract: HttpContractConfig,
-  status: number,
-  details?: Record<string, unknown>,
-) {
-  return {
-    ...contractDiagnostics(contract),
-    location: "response",
-    status,
-    declaredStatuses: declaredResponseStatuses(contract),
-    ...details,
-  };
-}
-
-function getDeclaredCatalogErrorsForStatus(
-  contract: HttpContractConfig,
-  status: number,
-): ContractErrorDefinition[] {
-  const errors = contract.metadata?.errors;
-  if (typeof errors !== "object" || errors === null) return [];
-
-  return Object.values(errors).filter(
-    (error): error is ContractErrorDefinition =>
-      typeof error === "object" &&
-      error !== null &&
-      typeof (error as { code?: unknown }).code === "string" &&
-      typeof (error as { status?: unknown }).status === "number" &&
-      typeof (error as { message?: unknown }).message === "string" &&
-      (error as { status: number }).status === status,
-  );
-}
-
-async function validateCatalogErrorResponse<C extends HttpContractConfig>(
-  contract: C,
-  res: HttpResponseLike,
-): Promise<void> {
-  const body = res.body;
-  if (res.status < 400 || !isErrorResponseBody(body)) return;
-
-  const declaredErrors = getDeclaredCatalogErrorsForStatus(
-    contract,
-    res.status,
-  );
-  if (declaredErrors.length === 0) return;
-
-  const matchingError = declaredErrors.find(
-    (error) => error.code === body.code,
-  );
-  if (!matchingError) {
-    throw new ResponseContractViolationError({
-      code: "RESPONSE_VALIDATION_ERROR",
-      message: responseContractViolationMessage(contract, res.status),
-      details: responseContractViolationDetails(contract, res.status, {
-        issues: [
-          {
-            message:
-              `Error response code "${body.code}" is not declared for status ${res.status}. ` +
-              `Expected one of: ${declaredErrors.map((error) => error.code).join(", ")}.`,
-          },
-        ],
-      }),
-    });
-  }
-
-  if (matchingError.details && body.details !== undefined) {
-    try {
-      await parseStandardSchema(matchingError.details, body.details);
-    } catch (error) {
-      if (error instanceof SchemaValidationError) {
-        throw new ResponseContractViolationError({
-          code: "RESPONSE_VALIDATION_ERROR",
-          message: responseContractViolationMessage(contract, res.status),
-          details: responseContractViolationDetails(contract, res.status, {
-            issues: error.issues,
-          }),
-        });
-      }
-      throw error;
-    }
-  }
-}
-
-async function validateResponseAgainstContract<C extends HttpContractConfig>(
-  contract: C,
-  res: HttpResponseLike,
-  responseValidationExemptStatus?: number,
-): Promise<void> {
-  const statusKey = String(res.status);
-  const hasDeclaredStatus = Object.hasOwn(contract.responses, statusKey);
-
-  if (!hasDeclaredStatus) {
-    if (Object.keys(contract.responses).length === 0) return;
-
-    throw new ResponseContractViolationError({
-      code: "UNDECLARED_RESPONSE_STATUS",
-      message:
-        `Handler returned undeclared status ${res.status} for ` +
-        `${contract.method} ${contract.path} (contract: ${contract.name})`,
-      details: responseContractViolationDetails(contract, res.status, {
-        returnedStatus: res.status,
-      }),
-    });
-  }
-
-  const responseSchema = contract.responses[res.status];
-  if (responseSchema === null) {
-    if (res.body !== undefined && res.body !== null) {
-      throw new ResponseContractViolationError({
-        code: "RESPONSE_VALIDATION_ERROR",
-        message: responseContractViolationMessage(contract, res.status),
-        details: responseContractViolationDetails(contract, res.status, {
-          issues: [
-            {
-              message:
-                "Response body must be empty for a null response schema.",
-            },
-          ],
-        }),
-      });
-    }
-    return;
-  }
-
-  if (!responseSchema) return;
-
-  // Binder routes whose use case output schema is the same object as the
-  // declared success response schema skip the redundant success-status parse.
-  // Error statuses and undeclared statuses are validated unchanged.
-  if (res.status === responseValidationExemptStatus) return;
-
-  try {
-    await parseStandardSchema(responseSchema, res.body);
-    await validateCatalogErrorResponse(contract, res);
-  } catch (error) {
-    if (error instanceof SchemaValidationError) {
-      throw new ResponseContractViolationError({
-        code: "RESPONSE_VALIDATION_ERROR",
-        message: responseContractViolationMessage(contract, res.status),
-        details: responseContractViolationDetails(contract, res.status, {
-          issues: error.issues,
-        }),
-      });
-    }
-    throw error;
-  }
-}
-
-async function finalizeResponse<C extends HttpContractConfig>(
-  contract: C,
-  res: HttpResponseLike,
-  responseValidationExemptStatus?: number,
-): Promise<HttpResponseLike> {
-  const normalized = normalizeResponse(res);
-  await validateResponseAgainstContract(
-    contract,
-    normalized,
-    responseValidationExemptStatus,
-  );
-  return normalized;
-}
-
-function toContractViolationResponse(
-  error: ResponseContractViolationError,
-): HttpResponseLike {
-  return {
-    status: 500,
-    body: createErrorResponseBody({
-      code: error.code,
-      message: error.message,
-      details: error.details,
-    }),
-  };
-}
-
-function defaultErrorResponse(err: unknown, ctx?: unknown): HttpResponseLike {
-  const requestId = getRequestIdFromContext(ctx);
-  return {
-    status: 500,
-    body: createErrorResponseBody({
-      code: "INTERNAL_SERVER_ERROR",
-      message: "Internal server error",
-      requestId,
-      details:
-        process.env.NODE_ENV !== "production" && err instanceof Error
-          ? {
-              error: {
-                message: err.message,
-                stack: err.stack,
-              },
-            }
-          : undefined,
-    }),
-  };
-}
-
-const DEFAULT_REQUEST_BODY_MAX_BYTES = 1024 * 1024;
-
-class RequestBodyTooLargeError extends Error {
-  readonly maxBytes: number;
-  readonly actualBytes?: number;
-
-  constructor(maxBytes: number, actualBytes?: number) {
-    super("Request body exceeds the configured size limit.");
-    this.name = "RequestBodyTooLargeError";
-    this.maxBytes = maxBytes;
-    this.actualBytes = actualBytes;
-  }
-}
-
-function requestBodyLimit(options: RequestBodyOptions | undefined): number {
-  const maxBytes = options?.maxBytes ?? DEFAULT_REQUEST_BODY_MAX_BYTES;
-
-  if (!Number.isFinite(maxBytes) || maxBytes <= 0) {
-    throw new Error(
-      "createServer requestBody.maxBytes must be a positive number.",
-    );
-  }
-
-  return maxBytes;
-}
-
-function assertContentLengthWithinLimit(
-  headers: Headers,
-  maxBytes: number,
-): void {
-  const contentLength = headers.get("content-length");
-  if (contentLength === null) return;
-
-  const actualBytes = Number(contentLength);
-  if (!Number.isFinite(actualBytes) || actualBytes < 0) return;
-  if (actualBytes > maxBytes) {
-    throw new RequestBodyTooLargeError(maxBytes, actualBytes);
-  }
-}
-
-async function readLimitedRequestText(
-  req: HttpRequestLike,
-  maxBytes: number,
-): Promise<string> {
-  assertContentLengthWithinLimit(req.headers, maxBytes);
-
-  const body = req.raw?.body;
-  if (!body) {
-    const text = await req.text();
-    const actualBytes = new TextEncoder().encode(text).byteLength;
-    if (actualBytes > maxBytes) {
-      throw new RequestBodyTooLargeError(maxBytes, actualBytes);
-    }
-    return text;
-  }
-
-  const reader = body.getReader();
-  const decoder = new TextDecoder();
-  let received = 0;
-  let text = "";
-
-  try {
-    while (true) {
-      const result = await reader.read();
-      if (result.done) break;
-      received += result.value.byteLength;
-      if (received > maxBytes) {
-        throw new RequestBodyTooLargeError(maxBytes, received);
-      }
-      text += decoder.decode(result.value, { stream: true });
-    }
-    text += decoder.decode();
-  } finally {
-    reader.releaseLock();
-  }
-
-  return text;
-}
-
-async function parseBody(
-  req: HttpRequestLike,
-  maxBytes: number,
-): Promise<unknown> {
-  const method = req.method.toUpperCase() as HttpContractConfig["method"];
-  if (!methodSupportsRequestBody(method)) {
-    return undefined;
-  }
-
-  const bodyReq = req.clone?.() ?? req;
-  const contentType = req.headers.get("content-type") || "";
-  if (contentType.includes("application/json")) {
-    const text = await readLimitedRequestText(bodyReq, maxBytes);
-    if (text === "") return undefined;
-    return JSON.parse(text);
-  }
-
-  try {
-    const text = await readLimitedRequestText(bodyReq, maxBytes);
-    return text === "" ? undefined : text;
-  } catch (error) {
-    if (error instanceof RequestBodyTooLargeError) throw error;
-    return undefined;
-  }
-}
-
-type ExecutionTarget<Ctx, C extends HttpContractConfig> = {
-  contract: C;
-  /**
-   * Compiled route pattern. Only required when the executor is invoked
-   * without pre-matched params.
-   */
-  compiled?: CompiledPath;
-  handler: Handler<Ctx, C>;
-  /**
-   * Success status whose response schema validation is skipped because the
-   * use case bound to this route already validated its output against the
-   * same schema object.
-   */
-  responseValidationExemptStatus?: number;
-};
-
-/**
- * Build the per-request execution pipeline once.
- *
- * The returned executor takes the contract, compiled pattern, and user handler
- * per invocation so fallback responses (404/405) can reuse a single pipeline
- * across requests instead of rebuilding it per unmatched request.
- */
-function createRequestExecutor<
-  Ctx,
-  Ports extends AnyPorts,
-  C extends HttpContractConfig,
-  Providers extends readonly AnyServiceProvider[] = readonly [],
-  FinalPorts extends Ports & InferProviderPorts<Providers> = Ports &
-    InferProviderPorts<Providers>,
->(
-  // biome-ignore lint/suspicious/noExplicitAny: Options are generic and need to work with any routes
-  options: CreateServerOptions<Ctx, Ports, any, any, Providers>,
-  finalPorts: FinalPorts,
-  contextRuntime: {
-    createRequestContext: (
-      req: HttpRequestLike,
-      contract: HttpContractConfig,
-    ) => Promise<Ctx>;
-    finalizeContext: (seed: ContextSeed<Ctx> | Ctx) => Ctx;
-  },
-  hooks: ServerHook<Ctx, FinalPorts>[],
-  routeHooks: readonly RouteHook<unknown, object>[] = [],
-  optionsOverrides?: {
-    skipRoutePreparation?: boolean;
-    /**
-     * Run the route through the full hook pipeline without contract
-     * preparation: no query/path/header/body parsing or validation, and the
-     * request body is left unconsumed for the handler.
-     */
-    rawRoute?: boolean;
-  },
-): (
-  target: ExecutionTarget<Ctx, C>,
-  req: HttpRequestLike,
-  preMatchedParams?: Record<string, string>,
-) => Promise<HttpResponse> {
-  const warnedNativeReplacementHooks = new WeakSet<object>();
-  const maxRequestBodyBytes = requestBodyLimit(options.requestBody);
-
-  const executeRequest = async (
-    target: ExecutionTarget<Ctx, C>,
-    req: HttpRequestLike,
-    preMatchedParams?: Record<string, string>,
-  ) => {
-    const { contract, handler: userHandler } = target;
-    let baseCtx: Ctx | undefined;
-    let pathValue: HandlerArgs<Ctx, C>["path"] | undefined;
-    let queryValue: HandlerArgs<Ctx, C>["query"] | undefined;
-    let headersValue: HandlerArgs<Ctx, C>["headers"] | undefined;
-    let bodyValue: HandlerArgs<Ctx, C>["body"] | undefined;
-    const startedAt = Date.now();
-    // Stage timings accumulate because retries re-enter the send phase and
-    // beforeHandle spans the route-hook and server-hook loops.
-    const stages: RequestStageTimings = {
-      onRequestMs: 0,
-      parseMs: 0,
-      contextMs: 0,
-      beforeHandleMs: 0,
-      handlerMs: 0,
-      sendMs: 0,
-    };
-    const timeStage = async <T>(
-      stage: keyof RequestStageTimings,
-      run: () => Promise<T> | T,
-    ): Promise<T> => {
-      const stageStartedAt = performance.now();
-      try {
-        return await run();
-      } finally {
-        stages[stage] += performance.now() - stageStartedAt;
-      }
-    };
-
-    const resolveErrorResult = async (
-      error: unknown,
-      ctx?: Ctx,
-      path?: HandlerArgs<Ctx, C>["path"],
-      query?: HandlerArgs<Ctx, C>["query"],
-      headers?: HandlerArgs<Ctx, C>["headers"],
-      body?: HandlerArgs<Ctx, C>["body"],
-      resultOptions?: {
-        owner?: ResponseOwner;
-      },
-    ): Promise<ExecutionResult<Ctx>> => {
-      let currentError = error;
-
-      const notifyCaughtError = async (caught: unknown) => {
-        const args = {
-          err: caught,
-          req,
-          ctx,
-          contract,
-          path,
-          query,
-          headers,
-          body,
-        };
-        for (const hook of hooks) {
-          if (!hook.onCaughtError) continue;
-          try {
-            await hook.onCaughtError(args);
-          } catch {
-            // Observers must not change response behavior.
-          }
-        }
-        if (options.onCaughtError) {
-          try {
-            await options.onCaughtError(args);
-          } catch {
-            // Observers must not change response behavior.
-          }
-        }
-      };
-
-      await notifyCaughtError(currentError);
-
-      if (currentError instanceof ResponseContractViolationError) {
-        return {
-          ctx,
-          response: toContractViolationResponse(currentError),
-          error: currentError,
-          owner: "framework",
-        };
-      }
-
-      if (isAppError(currentError)) {
-        return {
-          ctx,
-          response: {
-            status: currentError.status,
-            ...(currentError.headers
-              ? { headers: { ...currentError.headers } }
-              : {}),
-            body: toErrorResponseBody(currentError),
-          },
-          error: currentError,
-          owner: resultOptions?.owner ?? "route",
-        };
-      }
-
-      if (currentError instanceof AuthUnauthorizedError) {
-        return {
-          ctx,
-          response: errorResponse(401, currentError.code, currentError.message),
-          error: currentError,
-          owner: "framework",
-        };
-      }
-
-      if (currentError instanceof TenantRequiredError) {
-        return {
-          ctx,
-          response: errorResponse(
-            currentError.status,
-            currentError.code,
-            currentError.message,
-          ),
-          error: currentError,
-          owner: "framework",
-        };
-      }
-
-      if (currentError instanceof IdempotencyConflictError) {
-        return {
-          ctx,
-          response: errorResponse(
-            httpErrors.IdempotencyConflict.status,
-            httpErrors.IdempotencyConflict.code,
-            currentError.message,
-            {
-              namespace: currentError.namespace,
-              key: currentError.key,
-            },
-          ),
-          error: currentError,
-          owner: "framework",
-        };
-      }
-
-      if (currentError instanceof IdempotencyInProgressError) {
-        return {
-          ctx,
-          response: errorResponse(
-            httpErrors.IdempotencyInProgress.status,
-            httpErrors.IdempotencyInProgress.code,
-            currentError.message,
-            {
-              namespace: currentError.namespace,
-              key: currentError.key,
-            },
-          ),
-          error: currentError,
-          owner: "framework",
-        };
-      }
-
-      if (currentError instanceof GateAuthorizationError) {
-        return {
-          ctx,
-          response: errorResponse(
-            currentError.status,
-            currentError.code,
-            currentError.message,
-            currentError.details,
-          ),
-          error: currentError,
-          owner: "framework",
-        };
-      }
-
-      if (currentError instanceof EntitlementRequiredError) {
-        return {
-          ctx,
-          response: errorResponse(
-            currentError.status,
-            currentError.code,
-            currentError.message,
-            currentError.details,
-          ),
-          error: currentError,
-          owner: "framework",
-        };
-      }
-
-      for (const hook of hooks) {
-        if (!hook.mapUnhandledError) continue;
-        try {
-          const handled = await hook.mapUnhandledError({
-            err: currentError,
-            req,
-            ctx,
-            contract,
-            path,
-            query,
-            headers,
-            body,
-          });
-          if (handled) {
-            const response = normalizeHttpResponse(handled);
-            return {
-              ctx,
-              response,
-              error: currentError,
-              owner: responseOwnerFor(response, "framework"),
-            };
-          }
-        } catch (hookError) {
-          currentError = hookError;
-          await notifyCaughtError(currentError);
-        }
-      }
-
-      if (options.mapUnhandledError) {
-        try {
-          const handled = await options.mapUnhandledError({
-            err: currentError,
-            req,
-            ctx,
-            contract,
-            path,
-            query,
-            headers,
-            body,
-          });
-          if (handled) {
-            const response = normalizeHttpResponse(handled);
-            return {
-              ctx,
-              response,
-              error: currentError,
-              owner: responseOwnerFor(response, "framework"),
-            };
-          }
-        } catch (hookError) {
-          currentError = hookError;
-          await notifyCaughtError(currentError);
-        }
-      }
-
-      return {
-        ctx,
-        response: defaultErrorResponse(currentError, ctx),
-        error: currentError,
-        owner: "framework",
-      };
-    };
-
-    try {
-      const url = new URL(req.url);
-
-      let matchedParams: Record<string, string>;
-      if (preMatchedParams) {
-        matchedParams = preMatchedParams;
-      } else {
-        const compiled = target.compiled;
-        const match = compiled ? compiled.pattern.exec(url.pathname) : null;
-        if (
-          !compiled ||
-          !match ||
-          contract.method.toUpperCase() !== req.method.toUpperCase()
-        ) {
-          return errorResponse(404, "NOT_FOUND", "Not found");
-        }
-        try {
-          matchedParams = decodeMatchedParams(compiled.keys, match);
-        } catch (error) {
-          if (error instanceof PathDecodeError) {
-            return errorResponse(400, "INVALID_PATH", "Malformed URL path");
-          }
-          throw error;
-        }
-      }
-      const rawHeaders = requestHeadersToRecord(req.headers);
-
-      const runNativeBeforeSend = async (
-        initialResult: ExecutionResult<Ctx>,
-        nativeResponse: Response,
-      ): Promise<Response> => {
-        const originalView = responseForHooks(nativeResponse);
-        const originalHeaders = originalView.headers ?? {};
-        let transformed = originalView;
-        for (const hook of hooks) {
-          if (!hook.beforeSend) continue;
-          const nextResponse = await hook.beforeSend({
-            req,
-            ctx: initialResult.ctx,
-            contract,
-            path: pathValue,
-            query: queryValue,
-            headers: headersValue,
-            body: bodyValue,
-            response: transformed,
-            error: initialResult.error,
-            native: true,
-          });
-          if (nextResponse) {
-            if (
-              (nextResponse.status !== nativeResponse.status ||
-                nextResponse.body !== undefined) &&
-              !warnedNativeReplacementHooks.has(hook) &&
-              process.env.NODE_ENV !== "production"
-            ) {
-              warnedNativeReplacementHooks.add(hook);
-              console.warn(
-                `[beignet] beforeSend hook "${hook.name ?? "(anonymous)"}" returned a replacement status or body for a native Response on ${contract.method} ${contract.path}. Native responses are headers-only in beforeSend; status and body changes are ignored.`,
-              );
-            }
-            transformed = {
-              status: nativeResponse.status,
-              headers: nextResponse.headers,
-            };
-          }
-        }
-        return mergeNativeResponseHeaders(
-          nativeResponse,
-          originalHeaders,
-          transformed.headers ?? {},
-        );
-      };
-
-      const applyTransformHooks = async (
-        initialResult: ExecutionResult<Ctx>,
-        allowRetry: boolean,
-      ): Promise<ExecutionResult<Ctx>> => {
-        try {
-          if (isWebResponse(initialResult.response)) {
-            return {
-              ...initialResult,
-              response: await runNativeBeforeSend(
-                initialResult,
-                initialResult.response,
-              ),
-            };
-          }
-
-          let transformed = normalizeResponse(initialResult.response);
-          for (const hook of hooks) {
-            if (!hook.beforeSend) continue;
-            const nextResponse = await hook.beforeSend({
-              req,
-              ctx: initialResult.ctx,
-              contract,
-              path: pathValue,
-              query: queryValue,
-              headers: headersValue,
-              body: bodyValue,
-              response: transformed,
-              error: initialResult.error,
-            });
-            if (nextResponse) {
-              transformed = normalizeResponse(nextResponse);
-            }
-          }
-          return {
-            ...initialResult,
-            response: transformed,
-          };
-        } catch (error) {
-          const mapped = await resolveErrorResult(
-            error,
-            initialResult.ctx,
-            pathValue,
-            queryValue,
-            headersValue,
-            bodyValue,
-            { owner: "framework" },
-          );
-          if (!allowRetry) {
-            return mapped;
-          }
-          return applyTransformHooks(mapped, false);
-        }
-      };
-
-      const applyResponseFinalizerHooks = async (
-        initialResult: ExecutionResult<Ctx>,
-        allowRetry: boolean,
-        responseValidation: ResponseFinalizerValidationState,
-      ): Promise<ExecutionResult<Ctx>> => {
-        const response = normalizeHttpResponse(initialResult.response);
-        const native = isWebResponse(response);
-        const owner = responseOwnerFor(response, initialResult.owner);
-
-        try {
-          for (const hook of hooks) {
-            const finalizer = getResponseFinalizerHook<Ctx>(hook);
-            if (!finalizer) continue;
-            await finalizer({
-              req,
-              ctx: initialResult.ctx,
-              contract,
-              path: pathValue,
-              query: queryValue,
-              headers: headersValue,
-              body: bodyValue,
-              response: responseForHooks(response),
-              error: initialResult.error,
-              native: native ? true : undefined,
-              owner,
-              responseValidation,
-            });
-          }
-
-          return {
-            ...initialResult,
-            response,
-          };
-        } catch (error) {
-          const mapped = await resolveErrorResult(
-            error,
-            initialResult.ctx,
-            pathValue,
-            queryValue,
-            headersValue,
-            bodyValue,
-            { owner: "framework" },
-          );
-          if (!allowRetry) {
-            return mapped;
-          }
-          const transformed = await applyTransformHooks(mapped, true);
-          return applyResponseFinalizerHooks(
-            transformed,
-            false,
-            "not-applicable",
-          );
-        }
-      };
-
-      let result: ExecutionResult<Ctx> | undefined;
-
-      const onRequestStartedAt = performance.now();
-      for (const hook of hooks) {
-        if (!hook.onRequest) continue;
-        try {
-          const hookResult = await hook.onRequest({
-            req,
-            ports: finalPorts,
-            contract,
-            params: matchedParams,
-          });
-          if (hookResult) {
-            const response = normalizeHttpResponse(hookResult);
-            result = {
-              response,
-              owner: responseOwnerFor(response, "framework"),
-            };
-            break;
-          }
-        } catch (error) {
-          result = await resolveErrorResult(
-            error,
-            undefined,
-            undefined,
-            undefined,
-            undefined,
-            undefined,
-            { owner: "framework" },
-          );
-          break;
-        }
-      }
-      stages.onRequestMs = performance.now() - onRequestStartedAt;
-
-      if (!result) {
-        if (optionsOverrides?.skipRoutePreparation) {
-          let createdCtx!: Ctx;
-          try {
-            createdCtx = await timeStage("contextMs", () =>
-              contextRuntime.createRequestContext(req, contract),
-            );
-            baseCtx = createdCtx;
-          } catch (error) {
-            result = await resolveErrorResult(
-              error,
-              undefined,
-              undefined,
-              undefined,
-              undefined,
-              undefined,
-              { owner: "framework" },
-            );
-          }
-
-          if (!result) {
-            try {
-              result = {
-                ctx: createdCtx,
-                response: normalizeHttpResponse(
-                  await timeStage("handlerMs", () =>
-                    userHandler({
-                      req,
-                      ctx: createdCtx,
-                      contract,
-                      path: {} as HandlerArgs<Ctx, C>["path"],
-                      query: {} as HandlerArgs<Ctx, C>["query"],
-                      headers: rawHeaders as HandlerArgs<Ctx, C>["headers"],
-                      body: undefined as HandlerArgs<Ctx, C>["body"],
-                    }),
-                  ),
-                ),
-                owner: "framework",
-              };
-            } catch (error) {
-              result = await resolveErrorResult(
-                error,
-                createdCtx,
-                undefined,
-                undefined,
-                undefined,
-                undefined,
-                { owner: "framework" },
-              );
-            }
-          }
-        } else {
-          const parseStartedAt = performance.now();
-          const rawQuery: Record<string, string | string[]> = {};
-          for (const key of new Set(url.searchParams.keys())) {
-            const values = url.searchParams.getAll(key);
-            rawQuery[key] = values.length === 1 ? values[0] : values;
-          }
-
-          // biome-ignore lint/suspicious/noExplicitAny: type is narrowed by schema validation below
-          let query: any = rawQuery;
-          if (contract.query) {
-            try {
-              query = await parseStandardSchema(contract.query, query);
-            } catch (error) {
-              result = {
-                response: requestValidationError(
-                  contract,
-                  422,
-                  "VALIDATION_ERROR",
-                  "Invalid query parameters",
-                  "query",
-                  error,
-                ),
-                owner: "framework",
-              };
-            }
-          }
-
-          // biome-ignore lint/suspicious/noExplicitAny: Type will be narrowed by schema validation
-          let path: any = matchedParams;
-          if (!result && contract.pathParams) {
-            try {
-              path = await parseStandardSchema(
-                contract.pathParams,
-                matchedParams,
-              );
-            } catch (error) {
-              result = {
-                response: requestValidationError(
-                  contract,
-                  422,
-                  "VALIDATION_ERROR",
-                  "Invalid path parameters",
-                  "path",
-                  error,
-                ),
-                owner: "framework",
-              };
-            }
-          }
-
-          // biome-ignore lint/suspicious/noExplicitAny: Type will be narrowed by schema validation
-          let headers: any = rawHeaders;
-          const headerSchemas = getContractHeaderSchemas(contract.headers);
-          if (!result && headerSchemas.length > 0) {
-            try {
-              headers = await parseHeaderSchemas(headerSchemas, rawHeaders);
-            } catch (error) {
-              result = {
-                response: requestValidationError(
-                  contract,
-                  422,
-                  "VALIDATION_ERROR",
-                  "Invalid request headers",
-                  "headers",
-                  error,
-                ),
-                owner: "framework",
-              };
-            }
-          }
-
-          // biome-ignore lint/suspicious/noExplicitAny: Type will be narrowed by schema validation
-          let body: any;
-          // Raw routes own body consumption: the handler reads `req` itself,
-          // for example to verify a webhook signature over the exact bytes.
-          if (!result && !optionsOverrides?.rawRoute) {
-            try {
-              body = await parseBody(req, maxRequestBodyBytes);
-            } catch (error) {
-              if (error instanceof RequestBodyTooLargeError) {
-                result = {
-                  response: requestValidationError(
-                    contract,
-                    413,
-                    "PAYLOAD_TOO_LARGE",
-                    "Request body is too large",
-                    "body",
-                    error,
-                  ),
-                  owner: "framework",
-                };
-              } else {
-                result = {
-                  response: requestValidationError(
-                    contract,
-                    400,
-                    "INVALID_BODY",
-                    "Malformed JSON",
-                    "body",
-                    error,
-                  ),
-                  owner: "framework",
-                };
-              }
-            }
-          }
-
-          if (!result && contract.body) {
-            try {
-              body = await parseStandardSchema(contract.body, body);
-            } catch (error) {
-              if (
-                body === undefined &&
-                error instanceof SchemaValidationError
-              ) {
-                result = {
-                  response: requestValidationError(
-                    contract,
-                    400,
-                    "MISSING_BODY",
-                    "Request body is required",
-                    "body",
-                    error,
-                  ),
-                  owner: "framework",
-                };
-              } else {
-                result = {
-                  response: requestValidationError(
-                    contract,
-                    422,
-                    "VALIDATION_ERROR",
-                    "Invalid request body",
-                    "body",
-                    error,
-                  ),
-                  owner: "framework",
-                };
-              }
-            }
-          }
-
-          stages.parseMs = performance.now() - parseStartedAt;
-
-          if (!result) {
-            pathValue = path;
-            queryValue = query;
-            headersValue = headers;
-            bodyValue = body;
-
-            let createdCtx!: Ctx;
-            try {
-              createdCtx = await timeStage("contextMs", () =>
-                contextRuntime.createRequestContext(req, contract),
-              );
-              baseCtx = createdCtx;
-            } catch (error) {
-              result = await resolveErrorResult(
-                error,
-                undefined,
-                pathValue,
-                queryValue,
-                headersValue,
-                bodyValue,
-                { owner: "framework" },
-              );
-            }
-
-            if (!result) {
-              const baseArgs: HandlerArgs<Ctx, C> = {
-                req,
-                ctx: createdCtx,
-                contract,
-                path,
-                query,
-                headers,
-                body,
-              };
-
-              let currentCtx = createdCtx;
-              const beforeHandleStartedAt = performance.now();
-              for (const hook of routeHooks) {
-                try {
-                  const additions = await hook.resolve({
-                    req,
-                    ctx: currentCtx,
-                    contract,
-                    path,
-                    query,
-                    headers,
-                    body,
-                  });
-                  if (additions && typeof additions === "object") {
-                    currentCtx = contextRuntime.finalizeContext({
-                      ...(currentCtx as object),
-                      ...additions,
-                    } as Ctx);
-                  }
-                } catch (error) {
-                  result = await resolveErrorResult(
-                    error,
-                    currentCtx,
-                    pathValue,
-                    queryValue,
-                    headersValue,
-                    bodyValue,
-                    { owner: "framework" },
-                  );
-                  break;
-                }
-              }
-
-              if (!result) {
-                for (const hook of hooks) {
-                  if (!hook.beforeHandle) continue;
-                  try {
-                    const hookResult = await hook.beforeHandle({
-                      req,
-                      ctx: currentCtx,
-                      contract,
-                      path,
-                      query,
-                      headers,
-                      body,
-                    });
-                    if (isWebResponse(hookResult)) {
-                      result = {
-                        ctx: currentCtx,
-                        response: hookResult,
-                        owner: "transport",
-                      };
-                      break;
-                    }
-                    if (isHttpResponseLike(hookResult)) {
-                      result = {
-                        ctx: currentCtx,
-                        response: normalizeResponse(hookResult),
-                        owner: "framework",
-                      };
-                      break;
-                    }
-                    if (hookResult?.ctx !== undefined) {
-                      currentCtx = contextRuntime.finalizeContext(
-                        hookResult.ctx,
-                      );
-                    }
-                    if (hookResult?.response) {
-                      const response = normalizeHttpResponse(
-                        hookResult.response,
-                      );
-                      result = {
-                        ctx: currentCtx,
-                        response,
-                        owner: responseOwnerFor(response, "framework"),
-                      };
-                      break;
-                    }
-                  } catch (error) {
-                    result = await resolveErrorResult(
-                      error,
-                      currentCtx,
-                      pathValue,
-                      queryValue,
-                      headersValue,
-                      bodyValue,
-                      { owner: "framework" },
-                    );
-                    break;
-                  }
-                }
-              }
-              stages.beforeHandleMs = performance.now() - beforeHandleStartedAt;
-
-              if (!result) {
-                // Hooks may have elevated the actor or resolved a tenant.
-                // Refresh the ambient request context so record-time
-                // consumers such as createAmbientAuditLog see the finalized
-                // identity.
-                setActiveRequestIdentity({
-                  actor: readContextActor(currentCtx),
-                  tenant: readContextTenant(currentCtx),
-                });
-                try {
-                  result = {
-                    ctx: currentCtx,
-                    response: normalizeHttpResponse(
-                      await timeStage("handlerMs", () =>
-                        userHandler({ ...baseArgs, ctx: currentCtx }),
-                      ),
-                    ),
-                  };
-                } catch (error) {
-                  result = await resolveErrorResult(
-                    error,
-                    currentCtx,
-                    pathValue,
-                    queryValue,
-                    headersValue,
-                    bodyValue,
-                  );
-                }
-              }
-            }
-          }
-        }
-      }
-
-      const sendStartedAt = performance.now();
-      result = await applyTransformHooks(result, true);
-
-      let finalResponse = normalizeHttpResponse(result.response);
-      let finalError = result.error;
-      let finalOwner = responseOwnerFor(finalResponse, result.owner);
-      let responseValidation: ResponseFinalizerValidationState =
-        "not-applicable";
-      if (
-        finalOwner === "route" &&
-        !isWebResponse(finalResponse) &&
-        !(options.validateResponses ?? true)
-      ) {
-        responseValidation = "disabled";
-      } else if (
-        finalOwner === "route" &&
-        !isWebResponse(finalResponse) &&
-        (options.validateResponses ?? true)
-      ) {
-        try {
-          finalResponse = await finalizeResponse(
-            contract,
-            finalResponse,
-            target.responseValidationExemptStatus,
-          );
-          result = {
-            ...result,
-            response: finalResponse,
-          };
-          responseValidation = "validated";
-        } catch (error) {
-          if (error instanceof ResponseContractViolationError) {
-            result = {
-              ctx: result.ctx,
-              response: toContractViolationResponse(error),
-              error,
-              owner: "framework",
-            };
-            finalResponse = normalizeHttpResponse(result.response);
-            finalError = result.error;
-            finalOwner = responseOwnerFor(finalResponse, result.owner);
-            result = await applyTransformHooks(result, true);
-            finalResponse = normalizeHttpResponse(result.response);
-            finalError = result.error;
-            finalOwner = responseOwnerFor(finalResponse, result.owner);
-            responseValidation = "not-applicable";
-          } else {
-            throw error;
-          }
-        }
-      }
-
-      result = await applyResponseFinalizerHooks(
-        result,
-        true,
-        responseValidation,
-      );
-      finalResponse = normalizeHttpResponse(result.response);
-      finalError = result.error;
-      finalOwner = responseOwnerFor(finalResponse, result.owner);
-
-      if (!isWebResponse(finalResponse)) {
-        finalResponse = withFrameworkErrorOwnerHeader(
-          finalResponse,
-          finalOwner,
-        );
-      }
-      stages.sendMs = performance.now() - sendStartedAt;
-
-      const durationMs = Date.now() - startedAt;
-      const stageTimings = roundStageTimings(stages);
-      for (const hook of hooks) {
-        if (!hook.afterSend) continue;
-        try {
-          await hook.afterSend({
-            req,
-            ctx: result.ctx,
-            contract,
-            path: pathValue,
-            query: queryValue,
-            headers: headersValue,
-            body: bodyValue,
-            response: responseForHooks(finalResponse),
-            error: finalError,
-            durationMs,
-            stages: stageTimings,
-          });
-        } catch {
-          // Ignore after-response hook failures; they should never change the response.
-        }
-      }
-
-      return finalResponse;
-    } catch (error) {
-      const result = await resolveErrorResult(
-        error,
-        baseCtx,
-        pathValue,
-        queryValue,
-        headersValue,
-        bodyValue,
-        {
-          owner: "framework",
-        },
-      );
-      const response = normalizeHttpResponse(result.response);
-      if (isWebResponse(response)) {
-        return response;
-      }
-      return withFrameworkErrorOwnerHeader(
-        response,
-        responseOwnerFor(response, result.owner),
-      );
-    }
-  };
-
-  return async (
-    target: ExecutionTarget<Ctx, C>,
-    req: HttpRequestLike,
-    preMatchedParams?: Record<string, string>,
-  ) => {
-    const tracing = resolveTracingPort(finalPorts);
-    const instrumentationOptions =
-      options.instrumentation === false ? undefined : options.instrumentation;
-    const pathname = (() => {
-      try {
-        return new URL(req.url).pathname;
-      } catch {
-        return req.url;
-      }
-    })();
-    const ignored = (
-      instrumentationOptions?.ignorePaths ?? ["/api/devtools"]
-    ).some((prefix) => {
-      const normalized = prefix.replace(/\/+$/, "");
-      return pathname === normalized || pathname.startsWith(`${normalized}/`);
-    });
-
-    if (!tracing || ignored) {
-      return executeRequest(target, req, preMatchedParams);
-    }
-
-    const traceContextHeader =
-      instrumentationOptions?.traceContextHeader ?? "traceparent";
-    const active = tracing.current();
-    const parsedTraceparent =
-      traceContextHeader === false
-        ? undefined
-        : parseTraceparent(req.headers.get(traceContextHeader));
-    const parent: TraceContextInput | undefined = active
-      ? undefined
-      : !parsedTraceparent
-        ? undefined
-        : {
-            traceparent: parsedTraceparent.traceparent,
-            tracestate: req.headers.get("tracestate") ?? undefined,
-          };
-    const traceAttributes = {
-      "beignet.contract.name": target.contract.name,
-      "http.request.method": req.method.toUpperCase(),
-      "http.route": target.contract.path,
-    } as const;
-
-    return await runWithTracing(
-      tracing,
-      {
-        name: `beignet.request ${target.contract.name}`,
-        type: "request",
-        kind: active ? "internal" : "server",
-        parent,
-        attributes: traceAttributes,
-        metricAttributes: traceAttributes,
-      },
-      async (span) => {
-        const response = await executeRequest(target, req, preMatchedParams);
-        span?.setAttribute("http.response.status_code", response.status);
-        if (response.status >= 500) span?.setStatus("error");
-        return response;
-      },
-    );
-  };
-}
-
-/**
- * Build a memo instrumentation recorder from the app ports, or undefined when
- * no instrumentation sink is wired.
- *
- * Resolved per execution rather than at route-build time because providers
- * contribute `ports.instrumentation`/`ports.devtools` during setup, after
- * routes are registered.
- */
-function createMemoScopeRecorder(
-  ports: AnyPorts,
-): ((event: MemoInstrumentationEvent) => void) | undefined {
-  const target = ports as ProviderInstrumentationTarget;
-  if (!resolveProviderInstrumentationPort(target)) return undefined;
-
-  const instrumentation = createProviderInstrumentation(target, {
-    providerName: "memo",
-    watcher: "memo",
-  });
-  return (event) => {
-    instrumentation.custom({
-      name: `memo.${event.kind}`,
-      label: event.kind === "hit" ? "Memo hit" : "Memo fill",
-      summary: `Memo ${event.kind} for ${event.memo}`,
-      details: {
-        memo: event.memo,
-        key: event.key,
-        ...(event.durationMs !== undefined
-          ? { durationMs: event.durationMs }
-          : {}),
-        ...(event.failed ? { failed: true } : {}),
-      },
-    });
-  };
-}
-
-function buildHandler<
-  Ctx,
-  Ports extends AnyPorts,
-  C extends HttpContractConfig,
-  Providers extends readonly AnyServiceProvider[] = readonly [],
-  FinalPorts extends Ports & InferProviderPorts<Providers> = Ports &
-    InferProviderPorts<Providers>,
->(
-  // biome-ignore lint/suspicious/noExplicitAny: Options are generic and need to work with any routes
-  options: CreateServerOptions<Ctx, Ports, any, any, Providers>,
-  finalPorts: FinalPorts,
-  contextRuntime: {
-    createRequestContext: (
-      req: HttpRequestLike,
-      contract: HttpContractConfig,
-    ) => Promise<Ctx>;
-    finalizeContext: (seed: ContextSeed<Ctx> | Ctx) => Ctx;
-  },
-  contract: C,
-  userHandler: Handler<Ctx, C>,
-  hooks: ServerHook<Ctx, FinalPorts>[],
-  routeHooks: readonly RouteHook<unknown, object>[] = [],
-  optionsOverrides?: {
-    skipRoutePreparation?: boolean;
-    /**
-     * Run the route through the full hook pipeline without contract
-     * preparation: no query/path/header/body parsing or validation, and the
-     * request body is left unconsumed for the handler.
-     */
-    rawRoute?: boolean;
-  },
-  responseValidationExemptStatus?: number,
-): (
-  req: HttpRequestLike,
-  preMatchedParams?: Record<string, string>,
-) => Promise<HttpResponse> {
-  const execute = createRequestExecutor<Ctx, Ports, C, Providers, FinalPorts>(
-    options,
-    finalPorts,
-    contextRuntime,
-    hooks,
-    routeHooks,
-    optionsOverrides,
-  );
-  const executionTarget: ExecutionTarget<Ctx, C> = {
-    contract,
-    compiled: compilePath(contract.path),
-    handler: userHandler,
-    responseValidationExemptStatus,
-  };
-
-  // Every HTTP execution runs inside a fresh memo scope so createMemo(...)
-  // wrappers dedupe lookups for exactly one request.
-  return (req, preMatchedParams) =>
-    runWithMemoScope({ record: createMemoScopeRecorder(finalPorts) }, () =>
-      execute(executionTarget, req, preMatchedParams),
-    );
-}
-
 /**
  * Create a Beignet server instance.
  *
@@ -2726,9 +747,8 @@ export async function createServer<
   // 405s) is assembled per unmatched request.
   const executeFallback = createRequestExecutor<
     Ctx,
-    Ports,
-    HttpContractConfig,
-    Providers
+    FinalPorts,
+    HttpContractConfig
   >(options, finalPorts, contextRuntime, hooks, [], {
     skipRoutePreparation: true,
   });
@@ -2762,15 +782,35 @@ export async function createServer<
     const method = req.method.toUpperCase();
 
     let pathMatchedMethods: Set<string> | undefined;
+    let headCandidate: RegisteredRoute | undefined;
     for (const entry of registry) {
       if (!entry.compiled.pattern.test(url.pathname)) continue;
-      if (entry.method === method) {
+      if (method !== "HEAD" && entry.method === method) {
         return await entry.handler(req);
       }
       if (!pathMatchedMethods) {
         pathMatchedMethods = new Set();
       }
       pathMatchedMethods.add(entry.method);
+      if (method === "HEAD" && entry.method === "HEAD") {
+        if (
+          !headCandidate ||
+          (headCandidate.method === "GET" &&
+            headCandidate.compiled.shapeKey === entry.compiled.shapeKey)
+        ) {
+          headCandidate = entry;
+        }
+      }
+      if (entry.method === "GET") {
+        pathMatchedMethods.add("HEAD");
+        if (method === "HEAD" && !headCandidate) {
+          headCandidate = entry;
+        }
+      }
+    }
+
+    if (headCandidate) {
+      return await headCandidate.handler(req);
     }
 
     const pathname = url.pathname || "/";
@@ -2838,18 +878,6 @@ export async function createServer<
   };
 }
 
-function roundStageTimings(stages: RequestStageTimings): RequestStageTimings {
-  const round = (value: number) => Math.round(value * 100) / 100;
-  return {
-    onRequestMs: round(stages.onRequestMs),
-    parseMs: round(stages.parseMs),
-    contextMs: round(stages.contextMs),
-    beforeHandleMs: round(stages.beforeHandleMs),
-    handlerMs: round(stages.handlerMs),
-    sendMs: round(stages.sendMs),
-  };
-}
-
 function rawRouteContract(init: RawRouteInit): HttpContractConfig {
   return {
     kind: "http",
@@ -2863,139 +891,3 @@ function rawRouteContract(init: RawRouteInit): HttpContractConfig {
     metadata: init.metadata ?? {},
   };
 }
-
-/**
- * Define and flatten route registrations with strong type inference.
- *
- * Pass route definitions and route groups here before `createServer(...)`.
- * Group entries are flattened so downstream tooling receives one route list.
- *
- * @example
- * ```ts
- * const routes = defineRoutes<AppContext>([
- *   { contract: listPosts, useCase: listPostsUseCase },
- * ]);
- * ```
- */
-export function defineRoutes<
-  Ctx,
-  const R extends
-    readonly ContextualRouteInput<Ctx>[] = readonly ContextualRouteInput<Ctx>[],
->(routes: R & ValidatedRouteInputs<Ctx, R>): FlattenRouteInputs<R>;
-export function defineRoutes<
-  Ctx,
-  const R extends readonly RouteInput<Ctx>[] = readonly RouteInput<Ctx>[],
->(routes: R & ValidatedRouteInputs<Ctx, R>): FlattenRouteInputs<R>;
-export function defineRoutes<
-  Ctx,
-  const R extends readonly RouteInput<Ctx>[] = readonly RouteInput<Ctx>[],
->(routes: R): FlattenRouteInputs<R> {
-  const flattened: RouteDef<Ctx>[] = [];
-
-  for (const route of routes) {
-    if (isRouteGroup(route)) {
-      for (const groupRoute of route.routes) {
-        flattened.push({
-          ...groupRoute,
-          hooks: [...(route.hooks ?? []), ...(groupRoute.hooks ?? [])],
-        });
-      }
-    } else {
-      flattened.push(route);
-    }
-  }
-
-  return flattened as unknown as FlattenRouteInputs<R>;
-}
-
-/**
- * Extract contract configs from a route list.
- *
- * Use this to drive clients, OpenAPI, and docs from the same route list passed
- * to `createServer(...)`.
- */
-export function contractsFromRoutes<
-  // biome-ignore lint/suspicious/noExplicitAny: route contract types are erased at this level
-  const R extends readonly RouteDef<any, any>[],
->(routes: R): ContractsFromRouteList<R> {
-  return routes.map((route) =>
-    resolveContract(route.contract),
-  ) as unknown as ContractsFromRouteList<R>;
-}
-
-/**
- * Define a named group of related route registrations.
- *
- * Route groups are flattened by defineRoutes, so createServer still receives
- * a regular route list while app code can keep feature route wiring and scoped
- * hooks colocated.
- *
- * @example
- * ```ts
- * const todoRoutes = defineRouteGroup<AppContext>()({
- *   name: "todos",
- *   hooks: [auth.optional()],
- *   routes: [
- *     { contract: listTodos, useCase: listTodosUseCase },
- *   ]
- * });
- * ```
- */
-export function defineRouteGroup<Ctx>(): RouteGroupBuilder<Ctx>;
-/**
- * @deprecated Prefer `defineRouteGroup<Ctx>()({ ... })`. TypeScript cannot
- * infer the route tuple generic when callers provide only `Ctx`, so the direct
- * form preserves context checking but erases per-route contract output checks.
- */
-export function defineRouteGroup<
-  Ctx,
-  // biome-ignore lint/suspicious/noExplicitAny: route contract types are erased at this level
-  const R extends readonly RouteDef<Ctx, any>[] = readonly RouteDef<Ctx, any>[],
->(group: {
-  name: string;
-  hooks?: readonly RouteHook<Ctx, object>[];
-  routes: R & ValidatedRouteInputs<Ctx, R>;
-}): RouteGroup<Ctx, R>;
-export function defineRouteGroup<
-  Ctx,
-  // biome-ignore lint/suspicious/noExplicitAny: route contract types are erased at this level
-  const R extends readonly RouteDef<any, any>[] = readonly RouteDef<any, any>[],
->(group?: {
-  name: string;
-  hooks?: readonly RouteHook<Ctx, object>[];
-  routes: R;
-}): RouteGroup<Ctx, R> | RouteGroupBuilder<Ctx> {
-  const createGroup = <
-    const GroupHooks extends readonly RouteHook<Ctx, object>[] = readonly [],
-    const GroupRoutes extends readonly AnyRouteDef[] = readonly AnyRouteDef[],
-  >(input: {
-    name: string;
-    hooks?: GroupHooks;
-    routes: GroupRoutes;
-  }): RouteGroup<Ctx, GroupRoutes> => ({
-    kind: ROUTE_GROUP_KIND,
-    name: input.name,
-    hooks: input.hooks,
-    routes: input.routes,
-  });
-
-  if (!group) {
-    return createGroup;
-  }
-
-  return {
-    kind: ROUTE_GROUP_KIND,
-    name: group.name,
-    hooks: group.hooks,
-    routes: group.routes,
-  };
-}
-
-function isRouteGroup<Ctx>(route: RouteInput<Ctx>): route is RouteGroup<Ctx> {
-  return (
-    typeof route === "object" &&
-    route !== null &&
-    "kind" in route &&
-    route.kind === ROUTE_GROUP_KIND
-  );
-}