@beignet/core 0.0.2 → 0.0.4

package/src/server/server.ts

@@ -7,70 +7,151 @@ import {
   methodSupportsRequestBody,
   parsePathTemplate,
   type StandardSchema,
-} from "../contracts";
+} from "../contracts/index.js";
+import {
+  comparePathParamsToTemplate,
+  formatPathParamsMismatch,
+  getObjectSchemaShape,
+} from "../contracts/schema-shape.js";
 import {
   createErrorResponseBody,
+  httpErrors,
   isAppError,
   isErrorResponseBody,
   toErrorResponseBody,
-} from "../errors";
-import type { AnyPorts } from "../ports";
-import { AuthUnauthorizedError, GateAuthorizationError } from "../ports";
+} from "../errors/index.js";
+import {
+  IdempotencyConflictError,
+  IdempotencyInProgressError,
+} from "../idempotency/index.js";
+import type { AnyPorts } from "../ports/index.js";
+import {
+  AuthUnauthorizedError,
+  GateAuthorizationError,
+  isUnboundPort,
+  TenantRequiredError,
+} from "../ports/index.js";
 import type {
-  ProvidedPortsOfList,
+  InferProviderPorts,
   ProviderSetupResult,
   ServiceProvider,
-} from "../providers";
-import type { ContractLike, ResolveContract } from "./contract-like";
-import { resolveContract } from "./contract-like";
-import { getRequestIdFromContext } from "./hooks/utils";
+} from "../providers/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,
   ResolvedRoute,
+  RouteHook,
   ServerCaughtErrorHook,
   ServerHook,
   ServerUnhandledErrorMapper,
-} from "./http";
+} from "./http.js";
+import type { ServerInstrumentationOptions } from "./instrumentation.js";
+import { createServerInstrumentation } from "./instrumentation.js";
 import {
   loadProviderConfig,
   parseStandardSchema,
   SchemaValidationError,
-} from "./providers";
+} from "./providers/index.js";
+import type { ActiveRequestContext } from "./request-context.js";
+import {
+  enterActiveRequestContext,
+  readContextActor,
+  readContextTenant,
+  setActiveRequestIdentity,
+} from "./request-context.js";
+import type {
+  AnyUseCaseLike,
+  AnyUseCaseRouteDef,
+  UseCaseRouteDef,
+  ValidatedRouteInputs,
+} from "./use-case-route.js";
+import {
+  createUseCaseRouteHandler,
+  isUseCaseRouteDef,
+} from "./use-case-route.js";
 
 /**
- * Route registration for one contract.
+ * Route registration that connects a contract to the handler implementing it.
  *
- * Route definitions connect a contract to the handler that implements it. Most
- * apps keep these in `features/<feature>/routes.ts` and compose them with
- * `defineRoutes(...)`.
+ * Most apps keep route definitions in `features/<feature>/routes.ts` and
+ * compose them with `defineRoutes(...)`.
  */
-export type RouteDef<Ctx, CLike extends ContractLike = ContractLike> = {
+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, ResolveContract<CLike>>;
+  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 are an organization helper only. `defineRoutes(...)` flattens
- * them before server registration.
+ * 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,
-  // biome-ignore lint/suspicious/noExplicitAny: route contract types are erased at this level
-  Routes extends readonly RouteDef<Ctx, any>[] = readonly RouteDef<Ctx, any>[],
+  Routes extends readonly AnyRouteDef[] = readonly AnyRouteDef[],
 > = {
   /**
    * Internal marker used by `defineRoutes(...)`.
@@ -80,6 +161,10 @@ export type RouteGroup<
    * Human-readable group name.
    */
   name: string;
+  /**
+   * Hooks applied to every route in this group.
+   */
+  hooks?: readonly RouteHook<Ctx, object>[];
   /**
    * Route definitions in this group.
    */
@@ -87,24 +172,45 @@ export type RouteGroup<
 };
 
 type RouteInput<Ctx> =
-  // biome-ignore lint/suspicious/noExplicitAny: route contract types are erased at this level
-  | RouteDef<Ctx, any>
-  // biome-ignore lint/suspicious/noExplicitAny: route contract types are erased at this level
-  | RouteGroup<Ctx, readonly RouteDef<Ctx, any>[]>;
+  | 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> =
-  // biome-ignore lint/suspicious/noExplicitAny: route contract types are erased at this level
-  Input extends RouteGroup<any, infer Routes>
+  Input extends RouteGroup<infer _Ctx, infer Routes>
     ? Routes
-    : // biome-ignore lint/suspicious/noExplicitAny: route contract types are erased at this level
-      Input extends RouteDef<any, any>
+    : Input extends AnyRouteDef
       ? readonly [Input]
       : readonly [];
 
 type FlattenRouteInputs<Inputs extends readonly unknown[]> =
   number extends Inputs["length"]
-    ? // biome-ignore lint/suspicious/noExplicitAny: route contract types are erased at this level
-      readonly RouteDef<any, any>[]
+    ? readonly AnyRouteDef[]
     : Inputs extends readonly [infer First, ...infer Rest]
       ? readonly [...RoutesFromInput<First>, ...FlattenRouteInputs<Rest>]
       : readonly [];
@@ -122,20 +228,62 @@ type ContractsFromRouteList<
     : never;
 };
 
+/**
+ * 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;
+}
+
+/**
+ * Loosely typed provider list element.
+ *
+ * Required-port, app-context, and service-input generics are erased here so
+ * providers created with the typed `createProvider<Requires, Context,
+ * ServiceInput>()` form stay assignable to server provider lists.
+ */
+type AnyServiceProvider = ServiceProvider<
+  unknown,
+  // biome-ignore lint/suspicious/noExplicitAny: provider config types are erased at this level
+  StandardSchemaV1<any, any>,
+  AnyPorts,
+  // biome-ignore lint/suspicious/noExplicitAny: provider context types are erased at this level
+  any,
+  // biome-ignore lint/suspicious/noExplicitAny: provider service-input types are erased at this level
+  any
+>;
+
 /**
  * Options for creating a Beignet server instance.
  */
 export type CreateServerOptions<
   Ctx,
   Ports extends AnyPorts,
+  ServiceInput = void,
   // biome-ignore lint/suspicious/noExplicitAny: route contract types are erased at this level
-  Routes extends readonly RouteDef<Ctx, any>[] = readonly RouteDef<Ctx, any>[],
-  Providers extends readonly ServiceProvider<
-    unknown,
-    // biome-ignore lint/suspicious/noExplicitAny: provider config types are erased at this level
-    StandardSchemaV1<any, any>,
-    AnyPorts
-  >[] = readonly [],
+  Routes extends readonly RouteDef<any, any>[] = readonly RouteDef<any, any>[],
+  Providers extends readonly AnyServiceProvider[] = readonly [],
 > = {
   /**
    * App-owned ports available to context creation, hooks, and handlers.
@@ -159,24 +307,64 @@ export type CreateServerOptions<
   providerConfig?: Record<string, unknown>;
 
   /**
-   * Create request context after a route is matched.
+   * Context blueprint for request and service contexts.
+   *
+   * Gate-less contexts may pass a plain request factory. Contexts with a
+   * `gate` property must use the blueprint form
+   * `{ gate: (ports) => ports.gate, request, service }` so the server owns
+   * gate attachment and identity changes can never go stale.
    *
    * The `ports` argument includes app ports plus ports provided during server
    * startup.
    */
-  createContext: (args: {
-    req: HttpRequestLike;
-    ports: Ports & ProvidedPortsOfList<Providers>;
-    contract?: HttpContractConfig;
-  }) => Ctx | Promise<Ctx>;
+  context: ServerContextConfig<
+    Ctx,
+    Ports & InferProviderPorts<Providers>,
+    ServiceInput
+  >;
   /**
    * Server hooks that wrap every registered route.
    */
-  hooks?: ServerHook<Ctx, Ports & ProvidedPortsOfList<Providers>>[];
+  hooks?: ServerHook<Ctx, Ports & InferProviderPorts<Providers>>[];
+  /**
+   * Server-owned request instrumentation.
+   *
+   * The server resolves a request ID and W3C trace context for every request
+   * before user hooks and context creation, writes `x-request-id` and
+   * `traceparent` response headers, and records request and error events into
+   * the resolved provider instrumentation port (`ports.instrumentation`, then
+   * `ports.devtools`) when one is installed.
+   *
+   * Pass `false` to disable headers and event recording. Context factories
+   * still receive `requestId` and `trace` arguments.
+   */
+  instrumentation?: ServerInstrumentationOptions<Ctx> | false;
+  /**
+   * Whether route-owned responses are validated against the contract's
+   * declared statuses and response schemas before they are sent.
+   *
+   * Disable this to trade response guarantees for throughput, mirroring the
+   * client-side `validateResponses` option.
+   *
+   * @default true
+   */
+  validateResponses?: boolean;
   /**
    * Route list to register up front.
    */
   routes?: Routes;
+  /**
+   * How to handle ports that are still unbound after all providers have
+   * started.
+   *
+   * Ports declared as `deferred` in `definePorts(...)` boot as throwing
+   * placeholders until a provider contributes them. The default `"error"`
+   * fails startup and lists the unbound port keys. Apps that bind every port
+   * directly are unaffected.
+   *
+   * @default "error"
+   */
+  onUnboundPorts?: "error" | "warn" | "ignore";
   /**
    * Global caught-error observer.
    */
@@ -196,7 +384,11 @@ interface RouteBuilder<Ctx, C extends HttpContractConfig> {
 /**
  * Runtime server object returned by `createServer(...)`.
  */
-export interface ServerInstance<Ctx, Ports extends AnyPorts = AnyPorts> {
+export interface ServerInstance<
+  Ctx,
+  Ports extends AnyPorts = AnyPorts,
+  ServiceInput = void,
+> {
   /**
    * Catch-all request handler for platform adapters.
    */
@@ -207,6 +399,22 @@ export interface ServerInstance<Ctx, Ports extends AnyPorts = AnyPorts> {
   route: <CLike extends ContractLike>(
     contractLike: CLike,
   ) => RouteBuilder<Ctx, ResolveContract<CLike>>;
+  /**
+   * Build a fully assembled request context from a framework-neutral request.
+   *
+   * Use this for adapter entry points outside the route pipeline, such as
+   * server components or upload routes.
+   */
+  createRequestContext: (req: HttpRequestLike) => Promise<Ctx>;
+  /**
+   * Build a fully assembled service context for schedules, outbox drains,
+   * tasks, and background work.
+   *
+   * Requires `context.service` to be declared in `createServer(...)`.
+   */
+  createServiceContext: (
+    ...args: ServiceContextInputArgs<ServiceInput>
+  ) => Promise<Ctx>;
   /**
    * Contract configs registered through the `routes` option.
    */
@@ -302,6 +510,59 @@ function errorResponse(
   };
 }
 
+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,
@@ -395,6 +656,48 @@ function responseForHooks(res: HttpResponse): HttpResponseLike {
   };
 }
 
+/**
+ * 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) &&
@@ -421,6 +724,37 @@ class ResponseContractViolationError extends Error {
   }
 }
 
+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,
@@ -458,10 +792,8 @@ async function validateCatalogErrorResponse<C extends HttpContractConfig>(
   if (!matchingError) {
     throw new ResponseContractViolationError({
       code: "RESPONSE_VALIDATION_ERROR",
-      message:
-        `Response validation failed for ${contract.method} ${contract.path} ` +
-        `(status ${res.status}, contract: ${contract.name})`,
-      details: {
+      message: responseContractViolationMessage(contract, res.status),
+      details: responseContractViolationDetails(contract, res.status, {
         issues: [
           {
             message:
@@ -469,7 +801,7 @@ async function validateCatalogErrorResponse<C extends HttpContractConfig>(
               `Expected one of: ${declaredErrors.map((error) => error.code).join(", ")}.`,
           },
         ],
-      },
+      }),
     });
   }
 
@@ -480,10 +812,10 @@ async function validateCatalogErrorResponse<C extends HttpContractConfig>(
       if (error instanceof SchemaValidationError) {
         throw new ResponseContractViolationError({
           code: "RESPONSE_VALIDATION_ERROR",
-          message:
-            `Response validation failed for ${contract.method} ${contract.path} ` +
-            `(status ${res.status}, contract: ${contract.name})`,
-          details: { issues: error.issues },
+          message: responseContractViolationMessage(contract, res.status),
+          details: responseContractViolationDetails(contract, res.status, {
+            issues: error.issues,
+          }),
         });
       }
       throw error;
@@ -494,6 +826,7 @@ async function validateCatalogErrorResponse<C extends HttpContractConfig>(
 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);
@@ -506,10 +839,9 @@ async function validateResponseAgainstContract<C extends HttpContractConfig>(
       message:
         `Handler returned undeclared status ${res.status} for ` +
         `${contract.method} ${contract.path} (contract: ${contract.name})`,
-      details: {
-        status: res.status,
-        body: res.body,
-      },
+      details: responseContractViolationDetails(contract, res.status, {
+        returnedStatus: res.status,
+      }),
     });
   }
 
@@ -518,17 +850,15 @@ async function validateResponseAgainstContract<C extends HttpContractConfig>(
     if (res.body !== undefined && res.body !== null) {
       throw new ResponseContractViolationError({
         code: "RESPONSE_VALIDATION_ERROR",
-        message:
-          `Response validation failed for ${contract.method} ${contract.path} ` +
-          `(status ${res.status}, contract: ${contract.name})`,
-        details: {
+        message: responseContractViolationMessage(contract, res.status),
+        details: responseContractViolationDetails(contract, res.status, {
           issues: [
             {
               message:
                 "Response body must be empty for a null response schema.",
             },
           ],
-        },
+        }),
       });
     }
     return;
@@ -536,6 +866,11 @@ async function validateResponseAgainstContract<C extends HttpContractConfig>(
 
   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);
@@ -543,10 +878,10 @@ async function validateResponseAgainstContract<C extends HttpContractConfig>(
     if (error instanceof SchemaValidationError) {
       throw new ResponseContractViolationError({
         code: "RESPONSE_VALIDATION_ERROR",
-        message:
-          `Response validation failed for ${contract.method} ${contract.path} ` +
-          `(status ${res.status}, contract: ${contract.name})`,
-        details: { issues: error.issues },
+        message: responseContractViolationMessage(contract, res.status),
+        details: responseContractViolationDetails(contract, res.status, {
+          issues: error.issues,
+        }),
       });
     }
     throw error;
@@ -556,9 +891,14 @@ async function validateResponseAgainstContract<C extends HttpContractConfig>(
 async function finalizeResponse<C extends HttpContractConfig>(
   contract: C,
   res: HttpResponseLike,
+  responseValidationExemptStatus?: number,
 ): Promise<HttpResponseLike> {
   const normalized = normalizeResponse(res);
-  await validateResponseAgainstContract(contract, normalized);
+  await validateResponseAgainstContract(
+    contract,
+    normalized,
+    responseValidationExemptStatus,
+  );
   return normalized;
 }
 
@@ -618,38 +958,65 @@ async function parseBody(req: HttpRequestLike): Promise<unknown> {
   }
 }
 
-function buildHandler<
+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 ServiceProvider<
-    unknown,
-    // biome-ignore lint/suspicious/noExplicitAny: provider config types are erased at this level
-    StandardSchemaV1<any, any>,
-    AnyPorts
-  >[] = readonly [],
-  FinalPorts extends Ports & ProvidedPortsOfList<Providers> = Ports &
-    ProvidedPortsOfList<Providers>,
+  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, Providers>,
+  options: CreateServerOptions<Ctx, Ports, any, any, Providers>,
   finalPorts: FinalPorts,
-  contract: C,
-  userHandler: Handler<Ctx, C>,
+  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;
   },
 ): (
+  target: ExecutionTarget<Ctx, C>,
   req: HttpRequestLike,
   preMatchedParams?: Record<string, string>,
 ) => Promise<HttpResponse> {
-  const compiled = compilePath(contract.path);
+  const warnedNativeReplacementHooks = new WeakSet<object>();
 
   return 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;
@@ -730,6 +1097,53 @@ function buildHandler<
         };
       }
 
+      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,
@@ -814,8 +1228,10 @@ function buildHandler<
       if (preMatchedParams) {
         matchedParams = preMatchedParams;
       } else {
-        const match = compiled.pattern.exec(url.pathname);
+        const compiled = target.compiled;
+        const match = compiled ? compiled.pattern.exec(url.pathname) : null;
         if (
+          !compiled ||
           !match ||
           contract.method.toUpperCase() !== req.method.toUpperCase()
         ) {
@@ -832,15 +1248,67 @@ function buildHandler<
       }
       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>> => {
-        if (isWebResponse(initialResult.response)) {
-          return initialResult;
-        }
-
         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;
@@ -917,11 +1385,10 @@ function buildHandler<
         if (optionsOverrides?.skipRoutePreparation) {
           let createdCtx!: Ctx;
           try {
-            createdCtx = await options.createContext({
+            createdCtx = await contextRuntime.createRequestContext(
               req,
-              ports: finalPorts,
               contract,
-            });
+            );
             baseCtx = createdCtx;
           } catch (error) {
             result = await resolveErrorResult(
@@ -977,26 +1444,17 @@ function buildHandler<
             try {
               query = await parseStandardSchema(contract.query, query);
             } catch (error) {
-              result =
-                error instanceof SchemaValidationError
-                  ? {
-                      response: errorResponse(
-                        422,
-                        "VALIDATION_ERROR",
-                        "Invalid query parameters",
-                        { issues: error.issues },
-                      ),
-                      owner: "framework",
-                    }
-                  : {
-                      response: errorResponse(
-                        422,
-                        "VALIDATION_ERROR",
-                        "Invalid query parameters",
-                        (error as Error).message,
-                      ),
-                      owner: "framework",
-                    };
+              result = {
+                response: requestValidationError(
+                  contract,
+                  422,
+                  "VALIDATION_ERROR",
+                  "Invalid query parameters",
+                  "query",
+                  error,
+                ),
+                owner: "framework",
+              };
             }
           }
 
@@ -1009,26 +1467,17 @@ function buildHandler<
                 matchedParams,
               );
             } catch (error) {
-              result =
-                error instanceof SchemaValidationError
-                  ? {
-                      response: errorResponse(
-                        422,
-                        "VALIDATION_ERROR",
-                        "Invalid path parameters",
-                        { issues: error.issues },
-                      ),
-                      owner: "framework",
-                    }
-                  : {
-                      response: errorResponse(
-                        422,
-                        "VALIDATION_ERROR",
-                        "Invalid path parameters",
-                        (error as Error).message,
-                      ),
-                      owner: "framework",
-                    };
+              result = {
+                response: requestValidationError(
+                  contract,
+                  422,
+                  "VALIDATION_ERROR",
+                  "Invalid path parameters",
+                  "path",
+                  error,
+                ),
+                owner: "framework",
+              };
             }
           }
 
@@ -1039,26 +1488,17 @@ function buildHandler<
             try {
               headers = await parseHeaderSchemas(headerSchemas, rawHeaders);
             } catch (error) {
-              result =
-                error instanceof SchemaValidationError
-                  ? {
-                      response: errorResponse(
-                        422,
-                        "VALIDATION_ERROR",
-                        "Invalid request headers",
-                        { issues: error.issues },
-                      ),
-                      owner: "framework",
-                    }
-                  : {
-                      response: errorResponse(
-                        422,
-                        "VALIDATION_ERROR",
-                        "Invalid request headers",
-                        (error as Error).message,
-                      ),
-                      owner: "framework",
-                    };
+              result = {
+                response: requestValidationError(
+                  contract,
+                  422,
+                  "VALIDATION_ERROR",
+                  "Invalid request headers",
+                  "headers",
+                  error,
+                ),
+                owner: "framework",
+              };
             }
           }
 
@@ -1067,9 +1507,16 @@ function buildHandler<
           if (!result) {
             try {
               body = await parseBody(req);
-            } catch {
+            } catch (error) {
               result = {
-                response: errorResponse(400, "INVALID_BODY", "Malformed JSON"),
+                response: requestValidationError(
+                  contract,
+                  400,
+                  "INVALID_BODY",
+                  "Malformed JSON",
+                  "body",
+                  error,
+                ),
                 owner: "framework",
               };
             }
@@ -1084,34 +1531,28 @@ function buildHandler<
                 error instanceof SchemaValidationError
               ) {
                 result = {
-                  response: errorResponse(
+                  response: requestValidationError(
+                    contract,
                     400,
                     "MISSING_BODY",
                     "Request body is required",
+                    "body",
+                    error,
                   ),
                   owner: "framework",
                 };
               } else {
-                result =
-                  error instanceof SchemaValidationError
-                    ? {
-                        response: errorResponse(
-                          422,
-                          "VALIDATION_ERROR",
-                          "Invalid request body",
-                          { issues: error.issues },
-                        ),
-                        owner: "framework",
-                      }
-                    : {
-                        response: errorResponse(
-                          422,
-                          "VALIDATION_ERROR",
-                          "Invalid request body",
-                          (error as Error).message,
-                        ),
-                        owner: "framework",
-                      };
+                result = {
+                  response: requestValidationError(
+                    contract,
+                    422,
+                    "VALIDATION_ERROR",
+                    "Invalid request body",
+                    "body",
+                    error,
+                  ),
+                  owner: "framework",
+                };
               }
             }
           }
@@ -1124,11 +1565,10 @@ function buildHandler<
 
             let createdCtx!: Ctx;
             try {
-              createdCtx = await options.createContext({
+              createdCtx = await contextRuntime.createRequestContext(
                 req,
-                ports: finalPorts,
                 contract,
-              });
+              );
               baseCtx = createdCtx;
             } catch (error) {
               result = await resolveErrorResult(
@@ -1183,7 +1623,7 @@ function buildHandler<
                     break;
                   }
                   if (hookResult?.ctx !== undefined) {
-                    currentCtx = hookResult.ctx;
+                    currentCtx = contextRuntime.finalizeContext(hookResult.ctx);
                   }
                   if (hookResult?.response) {
                     const response = normalizeHttpResponse(hookResult.response);
@@ -1209,6 +1649,47 @@ function buildHandler<
               }
 
               if (!result) {
+                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) {
+                // 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,
@@ -1237,9 +1718,17 @@ function buildHandler<
       let finalResponse = normalizeHttpResponse(result.response);
       let finalError = result.error;
       let finalOwner = responseOwnerFor(finalResponse, result.owner);
-      if (finalOwner === "route" && !isWebResponse(finalResponse)) {
+      if (
+        finalOwner === "route" &&
+        !isWebResponse(finalResponse) &&
+        (options.validateResponses ?? true)
+      ) {
         try {
-          finalResponse = await finalizeResponse(contract, finalResponse);
+          finalResponse = await finalizeResponse(
+            contract,
+            finalResponse,
+            target.responseValidationExemptStatus,
+          );
         } catch (error) {
           if (error instanceof ResponseContractViolationError) {
             result = await applyTransformHooks(
@@ -1312,6 +1801,55 @@ function buildHandler<
   };
 }
 
+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;
+  },
+  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,
+  };
+
+  return (req, preMatchedParams) =>
+    execute(executionTarget, req, preMatchedParams);
+}
+
 /**
  * Create a Beignet server instance.
  *
@@ -1320,42 +1858,128 @@ function buildHandler<
  * Use adapter packages such as `@beignet/next` to expose `server.api` to a
  * specific runtime.
  *
- * @param options - Ports, providers, routes, hooks, context factory, and error
- * mapping hooks for the server.
+ * @param options - Ports, providers, routes, hooks, context blueprint, and
+ * error mapping hooks for the server.
  * @returns A started server instance with final ports and a catch-all handler.
  */
 export async function createServer<
   Ctx,
   Ports extends AnyPorts,
+  ServiceInput = void,
   // biome-ignore lint/suspicious/noExplicitAny: route contract types are erased at this level
-  Routes extends readonly RouteDef<Ctx, any>[] = readonly RouteDef<Ctx, any>[],
-  Providers extends readonly ServiceProvider<
-    unknown,
-    // biome-ignore lint/suspicious/noExplicitAny: provider config types are erased at this level
-    StandardSchemaV1<any, any>,
-    AnyPorts
-  >[] = readonly [],
+  Routes extends readonly RouteDef<any, any>[] = readonly RouteDef<any, any>[],
+  Providers extends readonly AnyServiceProvider[] = readonly [],
 >(
-  options: CreateServerOptions<Ctx, Ports, Routes, Providers>,
-): Promise<ServerInstance<Ctx, Ports & ProvidedPortsOfList<Providers>>> {
+  options: CreateServerOptions<Ctx, Ports, ServiceInput, Routes, Providers>,
+): Promise<
+  ServerInstance<Ctx, Ports & InferProviderPorts<Providers>, ServiceInput>
+> {
   type RegisteredRoute = ResolvedRoute<Ctx, HttpContractConfig> & {
     compiled: CompiledPath;
+    /**
+     * Uppercased contract method, cached for dispatch.
+     */
+    method: string;
   };
   const registry: RegisteredRoute[] = [];
-  type FinalPorts = Ports & ProvidedPortsOfList<Providers>;
-  const providers = (options.providers ?? []) as readonly ServiceProvider<
-    unknown,
-    // biome-ignore lint/suspicious/noExplicitAny: provider config types are erased at this level
-    StandardSchemaV1<any, any>,
-    AnyPorts
-  >[];
+  // Routes can register after startup via server.route(...), so the registry
+  // is re-sorted lazily before the next dispatch instead of on every
+  // registration.
+  let registryNeedsSort = false;
+  type FinalPorts = Ports & InferProviderPorts<Providers>;
+  const providers = (options.providers ?? []) as readonly AnyServiceProvider[];
   const env = options.providerEnv ?? process.env;
   const overrides = options.providerConfig ?? {};
   const providerResults: ProviderSetupResult<AnyPorts>[] = [];
   const finalPorts = { ...options.ports } as FinalPorts;
-  const hooks = [...((options.hooks ?? []) as ServerHook<Ctx, FinalPorts>[])];
+  const instrumentation = createServerInstrumentation<Ctx>(
+    options.instrumentation,
+  );
+  const hooks = [
+    ...(instrumentation.hook
+      ? [instrumentation.hook as ServerHook<Ctx, FinalPorts>]
+      : []),
+    ...((options.hooks ?? []) as ServerHook<Ctx, FinalPorts>[]),
+  ];
   const contracts = options.routes ? contractsFromRoutes(options.routes) : [];
 
+  const resolvedContext = resolveServerContext<Ctx, FinalPorts, ServiceInput>(
+    options.context,
+  );
+  const finalizeContext = createContextFinalizer(
+    resolvedContext,
+    () => finalPorts,
+  );
+  const createRequestContext = async (
+    req: HttpRequestLike,
+    contract?: HttpContractConfig,
+  ): Promise<Ctx> => {
+    const { requestId, trace } = instrumentation.prepareRequest(req);
+    return finalizeContext(
+      await resolvedContext.request({
+        req,
+        ports: finalPorts,
+        contract,
+        requestId,
+        trace,
+      }),
+    );
+  };
+  const createServiceContext = async (
+    ...args: ServiceContextInputArgs<ServiceInput>
+  ): Promise<Ctx> => {
+    const serviceFactory = resolvedContext.service;
+    if (!serviceFactory) {
+      throw new Error(
+        "Define context.service in createServer(...) to create service contexts.",
+      );
+    }
+
+    const { requestId, trace } = instrumentation.createServiceCorrelation();
+    // Enter the ambient context synchronously (before the factory awaits) so
+    // it propagates to the caller's continuation. Identity fields are filled
+    // onto the same object once the context is finalized, so jobs, listeners,
+    // schedules, and tasks observe the service actor/tenant at record time.
+    const ambient: ActiveRequestContext = {
+      requestId,
+      traceId: trace.traceId,
+      spanId: trace.spanId,
+      parentSpanId: trace.parentSpanId,
+      traceparent: trace.traceparent,
+    };
+    enterActiveRequestContext(ambient);
+    const ctx = finalizeContext(
+      await serviceFactory({
+        ports: finalPorts,
+        input: args[0] as ServiceInput,
+        requestId,
+        trace,
+      }),
+    );
+    ambient.actor = readContextActor(ctx);
+    ambient.tenant = readContextTenant(ctx);
+    return ctx;
+  };
+  const contextRuntime = {
+    createRequestContext,
+    finalizeContext,
+  };
+
+  let serviceContextsAvailable = false;
+  const lifecycleCreateServiceContext = async (
+    input?: unknown,
+  ): Promise<unknown> => {
+    if (!serviceContextsAvailable) {
+      throw new Error(
+        "Service contexts are unavailable until providers have started.",
+      );
+    }
+
+    return createServiceContext(
+      ...([input] as ServiceContextInputArgs<ServiceInput>),
+    );
+  };
+
   let stopped = false;
   const stop = async () => {
     if (stopped) return;
@@ -1366,6 +1990,7 @@ export async function createServer<
       try {
         await result?.stop?.({
           ports: finalPorts,
+          createServiceContext: lifecycleCreateServiceContext,
         });
       } catch (err) {
         errors.push(err);
@@ -1378,10 +2003,13 @@ export async function createServer<
 
   const registeredPaths = new Set<string>();
   const registeredShapes = new Map<string, string>();
+  const registeredNames = new Map<string, string>();
 
   const registerRoute = <C extends HttpContractConfig>(
     contract: C,
     handler: Handler<Ctx, C>,
+    routeHooks: readonly RouteHook<unknown, object>[] = [],
+    responseValidationExemptStatus?: number,
   ): void => {
     if (contract.body && !methodSupportsRequestBody(contract.method)) {
       throw new Error(
@@ -1403,19 +2031,46 @@ export async function createServer<
         `Ambiguous route: ${routeKey} conflicts with ${conflictingRoute}. Dynamic parameter names are ignored during routing, so each method + path shape must be unique.`,
       );
     }
+    const conflictingName = registeredNames.get(contract.name);
+    if (conflictingName) {
+      throw new Error(
+        `Duplicate contract name: "${contract.name}" is registered for both ${conflictingName} and ${routeKey}. Contract names must be unique because typed clients, OpenAPI operations, and devtools key on them.`,
+      );
+    }
+    if (contract.pathParams) {
+      const shape = getObjectSchemaShape(contract.pathParams);
+      if (shape) {
+        const { missingKeys, extraKeys } = comparePathParamsToTemplate({
+          pathKeys: compiled.keys,
+          shapeKeys: Object.keys(shape),
+        });
+        if (missingKeys.length > 0 || extraKeys.length > 0) {
+          const details = formatPathParamsMismatch({ missingKeys, extraKeys });
+          throw new Error(
+            `Path parameters for contract "${contract.name}" must match "${contract.path}" (${details}). Path templates and pathParams schemas drive routing, clients, and OpenAPI together.`,
+          );
+        }
+      }
+    }
     registeredPaths.add(routeKey);
     registeredShapes.set(shapeRouteKey, routeKey);
+    registeredNames.set(contract.name, routeKey);
 
     const builtHandler = buildHandler(
       options,
       finalPorts,
+      contextRuntime,
       contract,
       handler,
       hooks,
+      routeHooks,
+      undefined,
+      responseValidationExemptStatus,
     );
     registry.push({
       contract,
       compiled,
+      method: contract.method.toUpperCase(),
       handler: builtHandler,
       match: (method, pathname) => {
         if (contract.method.toUpperCase() !== method.toUpperCase()) {
@@ -1426,7 +2081,7 @@ export async function createServer<
         return { matched: true as const };
       },
     });
-    registry.sort((a, b) => compareRouteSpecificity(a.compiled, b.compiled));
+    registryNeedsSort = true;
   };
 
   const createBuilder = <C extends HttpContractConfig>(
@@ -1434,7 +2089,14 @@ export async function createServer<
     shouldRegister: boolean,
   ): RouteBuilder<Ctx, C> => ({
     handle: (fn) => {
-      const wrapped = buildHandler(options, finalPorts, contract, fn, hooks);
+      const wrapped = buildHandler(
+        options,
+        finalPorts,
+        contextRuntime,
+        contract,
+        fn,
+        hooks,
+      );
       if (shouldRegister) registerRoute(contract, fn);
       return wrapped;
     },
@@ -1444,7 +2106,36 @@ export async function createServer<
     try {
       for (const route of options.routes) {
         const contract = resolveContract(route.contract);
-        registerRoute(contract, route.handle);
+        const hasHandle = typeof route.handle === "function";
+        const hasUseCase = isUseCaseRouteDef(route);
+
+        if (hasHandle && hasUseCase) {
+          throw new Error(
+            `Route for contract "${contract.name}" declares both "handle" and "useCase". Bind the contract to exactly one of them.`,
+          );
+        }
+        if (!hasHandle && !hasUseCase) {
+          throw new Error(
+            `Route for contract "${contract.name}" declares neither "handle" nor "useCase". Bind the contract to a use case or implement a handler.`,
+          );
+        }
+
+        if (isUseCaseRouteDef(route)) {
+          const { handler, responseValidationExemptStatus } =
+            createUseCaseRouteHandler<Ctx, typeof contract>(contract, route);
+          registerRoute(
+            contract,
+            handler,
+            route.hooks as readonly RouteHook<unknown, object>[] | undefined,
+            responseValidationExemptStatus,
+          );
+        } else {
+          registerRoute(
+            contract,
+            route.handle as Handler<Ctx, typeof contract>,
+            route.hooks as readonly RouteHook<unknown, object>[] | undefined,
+          );
+        }
       }
     } catch (error) {
       try {
@@ -1465,6 +2156,7 @@ export async function createServer<
       const result = await provider.setup({
         ports: finalPorts,
         config: cfg,
+        createServiceContext: lifecycleCreateServiceContext,
       });
       if (result.ports) {
         Object.assign(finalPorts, result.ports);
@@ -1476,8 +2168,31 @@ export async function createServer<
       if (!result.start) continue;
       await result.start({
         ports: finalPorts,
+        createServiceContext: lifecycleCreateServiceContext,
       });
     }
+
+    instrumentation.attachPorts(finalPorts);
+
+    const onUnboundPorts = options.onUnboundPorts ?? "error";
+    if (onUnboundPorts !== "ignore") {
+      const unboundKeys = Object.keys(finalPorts).filter((key) =>
+        isUnboundPort((finalPorts as AnyPorts)[key]),
+      );
+      if (unboundKeys.length > 0) {
+        const message =
+          `Unbound ports after provider startup: ${unboundKeys.join(", ")}. ` +
+          "Each port declared as deferred in definePorts(...) must be contributed " +
+          "by a provider (server/providers.ts) or bound in infra/app-ports.ts. " +
+          'Pass onUnboundPorts: "warn" or "ignore" to change this behavior.';
+        if (onUnboundPorts === "error") {
+          throw new Error(message);
+        }
+        console.warn(`[beignet] ${message}`);
+      }
+    }
+
+    serviceContextsAvailable = true;
   } catch (error) {
     try {
       await stop();
@@ -1490,38 +2205,88 @@ export async function createServer<
     throw error;
   }
 
+  // The fallback 404/405 pipeline is built once at server creation. Only the
+  // contract surface that hooks observe (method, path, and the Allow set for
+  // 405s) is assembled per unmatched request.
+  const executeFallback = createRequestExecutor<
+    Ctx,
+    Ports,
+    HttpContractConfig,
+    Providers
+  >(options, finalPorts, contextRuntime, hooks, [], {
+    skipRoutePreparation: true,
+  });
+
+  const fallbackContract = (
+    name: string,
+    method: string,
+    path: string,
+  ): HttpContractConfig => ({
+    kind: "http",
+    name,
+    method: method as HttpContractConfig["method"],
+    path,
+    pathParams: null,
+    query: null,
+    body: null,
+    responses: {},
+    metadata: {},
+  });
+
+  const notFoundHandler: Handler<Ctx, HttpContractConfig> = async () =>
+    errorResponse(404, "NOT_FOUND", "Not found");
+
   const api = async (req: HttpRequestLike) => {
+    if (registryNeedsSort) {
+      registry.sort((a, b) => compareRouteSpecificity(a.compiled, b.compiled));
+      registryNeedsSort = false;
+    }
+
     const url = new URL(req.url);
+    const method = req.method.toUpperCase();
 
+    let pathMatchedMethods: Set<string> | undefined;
     for (const entry of registry) {
-      const result = entry.match(req.method, url.pathname);
-      if (result.matched) {
+      if (!entry.compiled.pattern.test(url.pathname)) continue;
+      if (entry.method === method) {
         return await entry.handler(req);
       }
+      if (!pathMatchedMethods) {
+        pathMatchedMethods = new Set();
+      }
+      pathMatchedMethods.add(entry.method);
     }
 
-    const notFoundContract: HttpContractConfig = {
-      kind: "http",
-      name: "notFound",
-      method: req.method.toUpperCase() as HttpContractConfig["method"],
-      path: url.pathname || "/",
-      pathParams: null,
-      query: null,
-      body: null,
-      responses: {},
-      metadata: {},
-    };
+    const pathname = url.pathname || "/";
 
-    const notFoundHandler = buildHandler(
-      options,
-      finalPorts,
-      notFoundContract,
-      async () => errorResponse(404, "NOT_FOUND", "Not found"),
-      hooks,
-      { skipRoutePreparation: true },
-    );
+    if (pathMatchedMethods) {
+      const allow = [...pathMatchedMethods].sort().join(", ");
+
+      return await executeFallback(
+        {
+          contract: fallbackContract("methodNotAllowed", method, pathname),
+          handler: async () => ({
+            status: 405,
+            headers: { allow },
+            body: createErrorResponseBody({
+              code: "METHOD_NOT_ALLOWED",
+              message: `Method ${method} is not allowed for ${pathname}`,
+            }),
+          }),
+        },
+        req,
+        {},
+      );
+    }
 
-    return await notFoundHandler(req);
+    return await executeFallback(
+      {
+        contract: fallbackContract("notFound", method, pathname),
+        handler: notFoundHandler,
+      },
+      req,
+      {},
+    );
   };
 
   return {
@@ -1530,6 +2295,8 @@ export async function createServer<
       const contract = resolveContract(contractLike);
       return createBuilder(contract, true);
     },
+    createRequestContext: (req) => createRequestContext(req),
+    createServiceContext,
     contracts,
     stop,
     ports: finalPorts,
@@ -1545,10 +2312,19 @@ export async function createServer<
  * @example
  * ```ts
  * const routes = defineRoutes<AppContext>([
- *   { contract: listPosts, handle: async ({ ctx }) => ctx.posts.list() },
+ *   { 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>[],
@@ -1557,7 +2333,12 @@ export function defineRoutes<
 
   for (const route of routes) {
     if (isRouteGroup(route)) {
-      flattened.push(...route.routes);
+      for (const groupRoute of route.routes) {
+        flattened.push({
+          ...groupRoute,
+          hooks: [...(route.hooks ?? []), ...(groupRoute.hooks ?? [])],
+        });
+      }
     } else {
       flattened.push(route);
     }
@@ -1585,26 +2366,61 @@ export function contractsFromRoutes<
  * 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 colocated.
+ * a regular route list while app code can keep feature route wiring and scoped
+ * hooks colocated.
  *
  * @example
  * ```ts
- * const todoRoutes = defineRouteGroup<AppContext>({
+ * const todoRoutes = defineRouteGroup<AppContext>()({
  *   name: "todos",
+ *   hooks: [auth.optional()],
  *   routes: [
- *     { contract: listTodos, handle: async ({ ctx }) => ctx.todos.list() },
+ *     { contract: listTodos, useCase: listTodosUseCase },
  *   ]
  * });
  * ```
  */
+export function defineRouteGroup<Ctx>(): RouteGroupBuilder<Ctx>;
 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; routes: R }): RouteGroup<Ctx, R> {
+>(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,
   };
 }