@beignet/core 0.0.2 → 0.0.4

package/dist/server/server.js

@@ -1,10 +1,29 @@
-import { BEIGNET_ERROR_OWNER_HEADER, getContractHeaderSchemas, methodSupportsRequestBody, parsePathTemplate, } from "../contracts";
-import { createErrorResponseBody, isAppError, isErrorResponseBody, toErrorResponseBody, } from "../errors";
-import { AuthUnauthorizedError, GateAuthorizationError } from "../ports";
-import { resolveContract } from "./contract-like";
-import { getRequestIdFromContext } from "./hooks/utils";
-import { loadProviderConfig, parseStandardSchema, SchemaValidationError, } from "./providers";
+import { BEIGNET_ERROR_OWNER_HEADER, getContractHeaderSchemas, methodSupportsRequestBody, parsePathTemplate, } 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 { AuthUnauthorizedError, GateAuthorizationError, isUnboundPort, TenantRequiredError, } from "../ports/index.js";
+import { createContextFinalizer, resolveServerContext } from "./context.js";
+import { resolveContract } from "./contract-like.js";
+import { getRequestIdFromContext } from "./hooks/utils.js";
+import { createServerInstrumentation } from "./instrumentation.js";
+import { loadProviderConfig, parseStandardSchema, SchemaValidationError, } from "./providers/index.js";
+import { enterActiveRequestContext, readContextActor, readContextTenant, setActiveRequestIdentity, } from "./request-context.js";
+import { createUseCaseRouteHandler, isUseCaseRouteDef, } from "./use-case-route.js";
 const ROUTE_GROUP_KIND = "beignet.route-group";
+/**
+ * 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() {
+    function define(route) {
+        return route;
+    }
+    return define;
+}
 class PathDecodeError extends Error {
     constructor() {
         super("Malformed URL path");
@@ -55,6 +74,35 @@ function errorResponse(status, code, message, details) {
         body: createErrorResponseBody({ code, message, details }),
     };
 }
+function contractDiagnostics(contract) {
+    return {
+        contract: contract.name,
+        method: contract.method,
+        path: contract.path,
+    };
+}
+function requestValidationDetails(contract, location, error) {
+    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, status, code, message, location, error) {
+    return errorResponse(status, code, message, requestValidationDetails(contract, location, error));
+}
 function normalizeResponse(res) {
     return {
         status: res.status,
@@ -126,6 +174,42 @@ function responseForHooks(res) {
         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, originalHeaders, finalHeaders) {
+    const originalByLowerKey = new Map();
+    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) {
     return (!isWebResponse(value) &&
         typeof value === "object" &&
@@ -143,6 +227,25 @@ class ResponseContractViolationError extends Error {
         this.details = args.details;
     }
 }
+function responseContractViolationMessage(contract, status) {
+    return (`Response validation failed for ${contract.method} ${contract.path} ` +
+        `(status ${status}, contract: ${contract.name})`);
+}
+function declaredResponseStatuses(contract) {
+    return Object.keys(contract.responses)
+        .map((status) => Number(status))
+        .filter((status) => Number.isFinite(status))
+        .sort((a, b) => a - b);
+}
+function responseContractViolationDetails(contract, status, details) {
+    return {
+        ...contractDiagnostics(contract),
+        location: "response",
+        status,
+        declaredStatuses: declaredResponseStatuses(contract),
+        ...details,
+    };
+}
 function getDeclaredCatalogErrorsForStatus(contract, status) {
     const errors = contract.metadata?.errors;
     if (typeof errors !== "object" || errors === null)
@@ -165,16 +268,15 @@ async function validateCatalogErrorResponse(contract, res) {
     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: `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) {
@@ -185,16 +287,17 @@ async function validateCatalogErrorResponse(contract, res) {
             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;
         }
     }
 }
-async function validateResponseAgainstContract(contract, res) {
+async function validateResponseAgainstContract(contract, res, responseValidationExemptStatus) {
     const statusKey = String(res.status);
     const hasDeclaredStatus = Object.hasOwn(contract.responses, statusKey);
     if (!hasDeclaredStatus) {
@@ -204,10 +307,9 @@ async function validateResponseAgainstContract(contract, res) {
             code: "UNDECLARED_RESPONSE_STATUS",
             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,
+            }),
         });
     }
     const responseSchema = contract.responses[res.status];
@@ -215,21 +317,25 @@ async function validateResponseAgainstContract(contract, res) {
         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;
     }
     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);
@@ -238,17 +344,18 @@ async function validateResponseAgainstContract(contract, res) {
         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;
     }
 }
-async function finalizeResponse(contract, res) {
+async function finalizeResponse(contract, res, responseValidationExemptStatus) {
     const normalized = normalizeResponse(res);
-    await validateResponseAgainstContract(contract, normalized);
+    await validateResponseAgainstContract(contract, normalized, responseValidationExemptStatus);
     return normalized;
 }
 function toContractViolationResponse(error) {
@@ -301,11 +408,19 @@ async function parseBody(req) {
         return undefined;
     }
 }
-function buildHandler(
+/**
+ * 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(
 // biome-ignore lint/suspicious/noExplicitAny: Options are generic and need to work with any routes
-options, finalPorts, contract, userHandler, hooks, optionsOverrides) {
-    const compiled = compilePath(contract.path);
-    return async (req, preMatchedParams) => {
+options, finalPorts, contextRuntime, hooks, routeHooks = [], optionsOverrides) {
+    const warnedNativeReplacementHooks = new WeakSet();
+    return async (target, req, preMatchedParams) => {
+        const { contract, handler: userHandler } = target;
         let baseCtx;
         let pathValue;
         let queryValue;
@@ -372,6 +487,36 @@ options, finalPorts, contract, userHandler, hooks, optionsOverrides) {
                     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,
@@ -450,8 +595,10 @@ options, finalPorts, contract, userHandler, hooks, optionsOverrides) {
                 matchedParams = preMatchedParams;
             }
             else {
-                const match = compiled.pattern.exec(url.pathname);
-                if (!match ||
+                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");
                 }
@@ -466,11 +613,49 @@ options, finalPorts, contract, userHandler, hooks, optionsOverrides) {
                 }
             }
             const rawHeaders = requestHeadersToRecord(req.headers);
-            const applyTransformHooks = async (initialResult, allowRetry) => {
-                if (isWebResponse(initialResult.response)) {
-                    return initialResult;
+            const runNativeBeforeSend = async (initialResult, nativeResponse) => {
+                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, allowRetry) => {
                 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)
@@ -532,11 +717,7 @@ options, finalPorts, contract, userHandler, hooks, optionsOverrides) {
                 if (optionsOverrides?.skipRoutePreparation) {
                     let createdCtx;
                     try {
-                        createdCtx = await options.createContext({
-                            req,
-                            ports: finalPorts,
-                            contract,
-                        });
+                        createdCtx = await contextRuntime.createRequestContext(req, contract);
                         baseCtx = createdCtx;
                     }
                     catch (error) {
@@ -576,16 +757,10 @@ options, finalPorts, contract, userHandler, hooks, optionsOverrides) {
                             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.message),
-                                        owner: "framework",
-                                    };
+                            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
@@ -595,16 +770,10 @@ options, finalPorts, contract, userHandler, hooks, optionsOverrides) {
                             path = await parseStandardSchema(contract.pathParams, 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.message),
-                                        owner: "framework",
-                                    };
+                            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
@@ -615,16 +784,10 @@ options, finalPorts, contract, userHandler, hooks, optionsOverrides) {
                             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.message),
-                                        owner: "framework",
-                                    };
+                            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
@@ -633,9 +796,9 @@ options, finalPorts, contract, userHandler, hooks, optionsOverrides) {
                         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",
                             };
                         }
@@ -648,21 +811,15 @@ options, finalPorts, contract, userHandler, hooks, optionsOverrides) {
                             if (body === undefined &&
                                 error instanceof SchemaValidationError) {
                                 result = {
-                                    response: errorResponse(400, "MISSING_BODY", "Request body is required"),
+                                    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.message),
-                                            owner: "framework",
-                                        };
+                                result = {
+                                    response: requestValidationError(contract, 422, "VALIDATION_ERROR", "Invalid request body", "body", error),
+                                    owner: "framework",
+                                };
                             }
                         }
                     }
@@ -673,11 +830,7 @@ options, finalPorts, contract, userHandler, hooks, optionsOverrides) {
                         bodyValue = body;
                         let createdCtx;
                         try {
-                            createdCtx = await options.createContext({
-                                req,
-                                ports: finalPorts,
-                                contract,
-                            });
+                            createdCtx = await contextRuntime.createRequestContext(req, contract);
                             baseCtx = createdCtx;
                         }
                         catch (error) {
@@ -724,7 +877,7 @@ options, finalPorts, contract, userHandler, hooks, optionsOverrides) {
                                         break;
                                     }
                                     if (hookResult?.ctx !== undefined) {
-                                        currentCtx = hookResult.ctx;
+                                        currentCtx = contextRuntime.finalizeContext(hookResult.ctx);
                                     }
                                     if (hookResult?.response) {
                                         const response = normalizeHttpResponse(hookResult.response);
@@ -742,6 +895,39 @@ options, finalPorts, contract, userHandler, hooks, optionsOverrides) {
                                 }
                             }
                             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,
+                                                ...additions,
+                                            });
+                                        }
+                                    }
+                                    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,
@@ -760,9 +946,11 @@ options, finalPorts, contract, userHandler, hooks, optionsOverrides) {
             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) {
@@ -820,6 +1008,18 @@ options, finalPorts, contract, userHandler, hooks, optionsOverrides) {
         }
     };
 }
+function buildHandler(
+// biome-ignore lint/suspicious/noExplicitAny: Options are generic and need to work with any routes
+options, finalPorts, contextRuntime, contract, userHandler, hooks, routeHooks = [], optionsOverrides, responseValidationExemptStatus) {
+    const execute = createRequestExecutor(options, finalPorts, contextRuntime, hooks, routeHooks, optionsOverrides);
+    const executionTarget = {
+        contract,
+        compiled: compilePath(contract.path),
+        handler: userHandler,
+        responseValidationExemptStatus,
+    };
+    return (req, preMatchedParams) => execute(executionTarget, req, preMatchedParams);
+}
 /**
  * Create a Beignet server instance.
  *
@@ -828,19 +1028,80 @@ options, finalPorts, contract, userHandler, hooks, optionsOverrides) {
  * 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(options) {
     const registry = [];
+    // 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;
     const providers = (options.providers ?? []);
     const env = options.providerEnv ?? process.env;
     const overrides = options.providerConfig ?? {};
     const providerResults = [];
     const finalPorts = { ...options.ports };
-    const hooks = [...(options.hooks ?? [])];
+    const instrumentation = createServerInstrumentation(options.instrumentation);
+    const hooks = [
+        ...(instrumentation.hook
+            ? [instrumentation.hook]
+            : []),
+        ...(options.hooks ?? []),
+    ];
     const contracts = options.routes ? contractsFromRoutes(options.routes) : [];
+    const resolvedContext = resolveServerContext(options.context);
+    const finalizeContext = createContextFinalizer(resolvedContext, () => finalPorts);
+    const createRequestContext = async (req, contract) => {
+        const { requestId, trace } = instrumentation.prepareRequest(req);
+        return finalizeContext(await resolvedContext.request({
+            req,
+            ports: finalPorts,
+            contract,
+            requestId,
+            trace,
+        }));
+    };
+    const createServiceContext = async (...args) => {
+        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 = {
+            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],
+            requestId,
+            trace,
+        }));
+        ambient.actor = readContextActor(ctx);
+        ambient.tenant = readContextTenant(ctx);
+        return ctx;
+    };
+    const contextRuntime = {
+        createRequestContext,
+        finalizeContext,
+    };
+    let serviceContextsAvailable = false;
+    const lifecycleCreateServiceContext = async (input) => {
+        if (!serviceContextsAvailable) {
+            throw new Error("Service contexts are unavailable until providers have started.");
+        }
+        return createServiceContext(...[input]);
+    };
     let stopped = false;
     const stop = async () => {
         if (stopped)
@@ -852,6 +1113,7 @@ export async function createServer(options) {
             try {
                 await result?.stop?.({
                     ports: finalPorts,
+                    createServiceContext: lifecycleCreateServiceContext,
                 });
             }
             catch (err) {
@@ -864,7 +1126,8 @@ export async function createServer(options) {
     };
     const registeredPaths = new Set();
     const registeredShapes = new Map();
-    const registerRoute = (contract, handler) => {
+    const registeredNames = new Map();
+    const registerRoute = (contract, handler, routeHooks = [], responseValidationExemptStatus) => {
         if (contract.body && !methodSupportsRequestBody(contract.method)) {
             throw new Error(`Request bodies are not supported for ${contract.method} contracts. Use POST, PUT, or PATCH for contract request bodies.`);
         }
@@ -879,12 +1142,31 @@ export async function createServer(options) {
         if (conflictingRoute) {
             throw new Error(`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);
-        const builtHandler = buildHandler(options, finalPorts, contract, handler, hooks);
+        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()) {
@@ -896,11 +1178,11 @@ export async function createServer(options) {
                 return { matched: true };
             },
         });
-        registry.sort((a, b) => compareRouteSpecificity(a.compiled, b.compiled));
+        registryNeedsSort = true;
     };
     const createBuilder = (contract, shouldRegister) => ({
         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;
@@ -910,7 +1192,21 @@ export async function createServer(options) {
         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(contract, route);
+                    registerRoute(contract, handler, route.hooks, responseValidationExemptStatus);
+                }
+                else {
+                    registerRoute(contract, route.handle, route.hooks);
+                }
             }
         }
         catch (error) {
@@ -929,6 +1225,7 @@ export async function createServer(options) {
             const result = await provider.setup({
                 ports: finalPorts,
                 config: cfg,
+                createServiceContext: lifecycleCreateServiceContext,
             });
             if (result.ports) {
                 Object.assign(finalPorts, result.ports);
@@ -940,8 +1237,25 @@ export async function createServer(options) {
                 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[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 {
@@ -952,27 +1266,62 @@ export async function createServer(options) {
         }
         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(options, finalPorts, contextRuntime, hooks, [], {
+        skipRoutePreparation: true,
+    });
+    const fallbackContract = (name, method, path) => ({
+        kind: "http",
+        name,
+        method: method,
+        path,
+        pathParams: null,
+        query: null,
+        body: null,
+        responses: {},
+        metadata: {},
+    });
+    const notFoundHandler = async () => errorResponse(404, "NOT_FOUND", "Not found");
     const api = async (req) => {
+        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;
         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 = {
-            kind: "http",
-            name: "notFound",
-            method: req.method.toUpperCase(),
-            path: url.pathname || "/",
-            pathParams: null,
-            query: null,
-            body: null,
-            responses: {},
-            metadata: {},
-        };
-        const notFoundHandler = buildHandler(options, finalPorts, notFoundContract, async () => errorResponse(404, "NOT_FOUND", "Not found"), hooks, { skipRoutePreparation: true });
-        return await notFoundHandler(req);
+        const pathname = url.pathname || "/";
+        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 executeFallback({
+            contract: fallbackContract("notFound", method, pathname),
+            handler: notFoundHandler,
+        }, req, {});
     };
     return {
         api,
@@ -980,29 +1329,23 @@ export async function createServer(options) {
             const contract = resolveContract(contractLike);
             return createBuilder(contract, true);
         },
+        createRequestContext: (req) => createRequestContext(req),
+        createServiceContext,
         contracts,
         stop,
         ports: finalPorts,
     };
 }
-/**
- * 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, handle: async ({ ctx }) => ctx.posts.list() },
- * ]);
- * ```
- */
 export function defineRoutes(routes) {
     const flattened = [];
     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);
@@ -1019,26 +1362,20 @@ export function defineRoutes(routes) {
 export function contractsFromRoutes(routes) {
     return routes.map((route) => resolveContract(route.contract));
 }
-/**
- * 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.
- *
- * @example
- * ```ts
- * const todoRoutes = defineRouteGroup<AppContext>({
- *   name: "todos",
- *   routes: [
- *     { contract: listTodos, handle: async ({ ctx }) => ctx.todos.list() },
- *   ]
- * });
- * ```
- */
 export function defineRouteGroup(group) {
+    const createGroup = (input) => ({
+        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,
     };
 }