@beignet/web 0.0.3 → 0.0.4

package/CHANGELOG.md

@@ -1,5 +1,92 @@
 # @beignet/web
 
+## 0.0.4
+
+### Patch Changes
+
+- 8bcb31f: Mark package READMEs with Beignet's experimental alpha status and 0.0.x stability expectations.
+- d137044: Declare `@beignet/core` as a peer dependency with a lockstep version range in
+  every integration and provider package instead of a regular `"*"` dependency.
+  Installs now always resolve a single shared copy of core, so `instanceof`
+  checks such as `isContractError` and upload error identity keep working, and
+  mixed Beignet versions fail loudly at install time instead of at runtime.
+
+  If your package manager does not install peer dependencies automatically, add
+  `@beignet/core` to your app alongside these packages. `@beignet/nuqs` now also
+  declares `@beignet/react-query` as a peer dependency, and
+  `@beignet/provider-storage-s3` now expects you to install
+  `@aws-sdk/client-s3` and `@aws-sdk/s3-request-presigner` yourself, matching
+  how other providers treat their SDKs.
+
+- ac78cdf: Make `createAuthHooks` the single route-scoped auth hook API. The factory is
+  now curried — `createAuthHooks<AppContext>()({ resolve })` — so added context
+  fields are inferred from `resolve` instead of passed as a type argument, and a
+  new optional `headers` schema validates the raw lowercase request header
+  record before `resolve` runs, giving `resolve` typed credential headers
+  without contract casts. On `required()` hooks a header schema failure returns
+  a framework-owned 401; `optional()` hooks skip auth resolution; `public()`
+  hooks never parse headers. `defineRouteHook` (and the `RouteHookBuilder`
+  types) are removed — write non-auth route hooks as plain `RouteHook` object
+  literals.
+- 1a79090: Emit Node-compatible ESM: all relative imports in published packages now carry explicit .js extensions, fixing ERR_MODULE_NOT_FOUND when running the CLI or importing package dist files under plain Node.
+- 82c48dc: Add canonical test port and context fixtures, and update generated tests to use them.
+- 303ba07: Define the public HTTP adapter contract and expose the Web Fetch adapter implementation.
+- 493d23b: Make the framework own context assembly with a server context blueprint and first-class service contexts.
+
+  - `createServer(...)` (and the Next/Web adapters) replace the `createContext` option with `context`. Gate-less contexts keep the plain request-factory shorthand; contexts that declare a `gate` must use the blueprint form `{ gate: (ports) => ports.gate, request, service }`. Returning `gate` from a context factory or hook addition is now a compile error.
+  - The gate port gains `gate.attach(ctx)`: it attaches a live, non-enumerable `ctx.gate` getter that re-binds against the receiving object on every access, so identity changes (including auth-hook elevation) can never authorize against a stale context, and spread copies drop the gate loudly instead of silently keeping stale identity. `bind(...)` remains the low-level primitive.
+  - Servers expose `createRequestContext(req)` and `createServiceContext(input?)`; the optional `context.service` factory powers schedule, outbox, command, and background contexts. Provider `setup`, `start`, and `stop` receive a late-bound `createServiceContext` so infra providers no longer hand-build background contexts.
+  - `createTestContextFactory(...)` now attaches the gate after all `extra` and override fields merge, fixing a stale-identity bug in tests.
+  - CLI templates, generators, and doctor diagnostics emit and check the new context blueprint and service-context wrappers.
+
+- 89390fe: Decouple devtools from app code with server-owned instrumentation.
+
+  - `@beignet/core/tracing` is a new dependency-free subpath with the W3C trace
+    primitives (`TraceContext`, `createTraceContext`, `createChildTraceContext`,
+    `parseTraceparent`, `createTraceparent`, `createTraceId`, `createSpanId`).
+    App context types now use `Partial<TraceContext>` instead of importing
+    `DevtoolsTraceContext` from `@beignet/devtools`.
+  - `createServer(...)` owns request instrumentation through a new
+    `instrumentation` option (`ServerInstrumentationOptions | false`). The server
+    resolves request IDs and trace context before user hooks and context
+    creation, passes them to context factories as `requestId` and `trace`,
+    writes `x-request-id`/`traceparent` response headers by default, and records
+    request/error events into the instrumentation port resolved from final ports
+    (`ports.instrumentation`, then `ports.devtools`). The ambient request
+    context (`enterActiveRequestContext` and friends) moved into
+    `@beignet/core/server`.
+  - `createUseCase(...)` instruments runs by default, resolving the
+    instrumentation port from `ctx.ports` per run; opt out with
+    `instrumentation: false`. App `onRun` observers run in addition.
+  - `createInstrumentedAuditLog({ audit, instrumentation })` in
+    `@beignet/core/ports` replaces `createDevtoolsAuditLog`.
+  - `createServer(...)` gains `validateResponses` (default `true`) to skip
+    route-owned response validation, mirroring the client option.
+  - Removed from `@beignet/devtools`: `createDevtoolsHooks`,
+    `createDevtoolsUseCaseObserver`, `createDevtoolsAuditLog`, and the
+    trace/request-context modules. Apps now only need `createDevtoolsProvider()`
+    plus the devtools route; deleting both leaves the rest of the app compiling
+    and running unchanged.
+  - `@beignet/next` cron and upload helpers resolve their instrumentation sink
+    with `resolveProviderInstrumentationPort(ctx.ports)` instead of hardcoding
+    `ports.devtools`.
+  - `beignet create` templates generate the decoupled shape.
+
+- e9c3209: Add reusable actor, tenant, audit assertion, and default-header request helpers for production app tests.
+- 493d23b: Add typed provider-contributed ports. `InferProviderPorts` (replacing
+  `ProvidedPortsOfList`) merges the ports a provider list contributes so apps can
+  type `ctx.ports` as `AppPorts & InferProviderPorts<typeof providers>` without
+  casts. The curried `definePorts<AppPorts>()({ bound, deferred })` form replaces
+  throwing stub boilerplate: deferred keys boot as descriptive placeholders and
+  `createServer(...)` fails startup with the unbound key list (configurable via
+  `onUnboundPorts: "error" | "warn" | "ignore"`). App-local providers can declare
+  required ports, app context, and service-context input through the curried
+  `createProvider<Requires, Context, ServiceInput>()` form, which types
+  `setup({ ports, createServiceContext })` and lifecycle contexts end to end.
+  CLI templates and `beignet make` generate and maintain the new forms.
+- 192c6ad: Routes can bind a contract directly to a use case with `{ contract, useCase }` — status is inferred from a sole 2xx response, input defaults to merged path/query/body parts, and validated inputs are not re-parsed when the use case reuses the contract schema by reference. Full `handle` routes remain the escape hatch for headers, streaming, and multi-status responses.
+- 255527d: `createTestApp` defaults `onUnboundPorts` to "ignore" and surfaces unhandled error messages in test responses.
+
 ## 0.0.3
 
 ### Patch Changes

package/README.md

@@ -1,5 +1,9 @@
 # @beignet/web
 
+> [!CAUTION]
+> Beignet is experimental alpha software. The `0.0.x` package line is for early
+> evaluation, and APIs may change between releases while the framework settles.
+
 Web Fetch adapter for Beignet's framework runtime.
 
 Use this package when your runtime accepts a standard `Request` and returns a
@@ -9,7 +13,7 @@ or tests that should avoid a framework-specific adapter.
 ## Installation
 
 ```bash
-npm install @beignet/web
+npm install @beignet/web @beignet/core
 ```
 
 ## Quick start
@@ -21,8 +25,8 @@ import { routes } from "./server/routes";
 export const server = await createFetchServer({
   ports,
   routes,
-  createContext: ({ ports, req }) => ({
-    requestId: req.headers.get("x-request-id") ?? crypto.randomUUID(),
+  context: ({ ports, requestId }) => ({
+    requestId,
     ports,
   }),
   mapUnhandledError: () => ({
@@ -56,6 +60,7 @@ import {
   createFetchHandler,
   toRequestLike,
   toWebResponse,
+  webFetchAdapter,
 } from "@beignet/web";
 ```
 
@@ -65,28 +70,53 @@ import {
   framework-neutral request shape.
 - `toWebResponse(response)` converts a Beignet response to a standard
   `Response`.
+- `webFetchAdapter` is the concrete
+  `HttpAdapter<Request, Response>` implementation for Web Fetch runtimes.
 
 Native `Response` instances returned by handlers are passed through unchanged.
 Plain Beignet responses are serialized as JSON unless the body is `undefined`
 or `null`.
 
+## Adapter contract
+
+`@beignet/core/server` owns framework behavior: route matching, hooks, request
+validation, response validation, error mapping, response ownership, and provider
+lifecycle. `@beignet/web` owns only the Web Fetch edge conversion.
+
+The exported `webFetchAdapter` implements the formal core adapter contract:
+
+```typescript
+import type { HttpAdapter } from "@beignet/core/server";
+
+export const adapter: HttpAdapter<Request, Response> = webFetchAdapter;
+```
+
+Use the same shape for a future runtime adapter with non-Fetch native request
+or response types.
+
 ## Testing
 
 Use `@beignet/web/testing` to exercise routes through the same Web Fetch
-adapter without opening a network port.
+adapter without opening a network port. Use `@beignet/core/testing` beside it
+when the route needs an app-style context and test ports.
 
 ```typescript
+import { createTestContextFactory, createTestPorts } from "@beignet/core/testing";
 import { createTestApp } from "@beignet/web/testing";
 import { getTodo } from "./features/todos/contracts";
 import { routes } from "./server/routes";
 
+const fixture = createTestPorts<AppContext["ports"]>({
+  base: appPorts,
+  overrides: { todos: createInMemoryTodoRepository() },
+});
+const createContext = createTestContextFactory<AppContext, AppContext["ports"]>({
+  ports: fixture.ports,
+});
 const app = await createTestApp({
-  ports,
+  ports: fixture.ports,
   routes,
-  createContext: ({ ports }) => ({
-    requestId: "test-request",
-    ports,
-  }),
+  context: () => createContext(),
 });
 
 const todo = await app.request(getTodo, {
@@ -97,3 +127,43 @@ const todo = await app.request(getTodo, {
 `app.request(contract, args)` uses the same typed call arguments as
 `@beignet/core/client`, while `app.safeRequest(contract, args)` returns a typed
 success/error result instead of throwing.
+
+`createTestApp(...)` applies two test-friendly defaults, and an explicit
+option always wins:
+
+- `onUnboundPorts` defaults to `"ignore"`, so apps with deferred provider
+  ports boot without installing every provider. Reading an unbound port still
+  throws on use. Production servers created with `createFetchServer(...)` keep
+  the strict `"error"` default.
+- `mapUnhandledError` defaults to a mapper that returns
+  `{ status: 500, body: { code: "INTERNAL_SERVER_ERROR", message: err.message } }`,
+  so failing tests show the real error message instead of a generic response.
+
+Apps that declare their context blueprint with `defineServerContext(...)` in
+`server/context.ts` can pass the same value to both the runtime server and
+`createTestApp(...)`:
+
+```typescript
+import { appContext } from "../server/context";
+
+const app = await createTestApp({ ports, routes, context: appContext });
+```
+
+Use `createTestRequester(...)` when a test suite repeats the same auth, tenant,
+or correlation headers:
+
+```typescript
+import { createTestApp, createTestRequester } from "@beignet/web/testing";
+
+const app = await createTestApp({ ports, routes, context: createContext });
+const authedRequest = createTestRequester(app, {
+  headers: {
+    "x-user-id": "user_1",
+    "x-tenant-id": "tenant_1",
+  },
+});
+
+const todo = await authedRequest.request(getTodo, {
+  path: { id: "todo_1" },
+});
+```

package/dist/index.d.ts

@@ -1,20 +1,20 @@
 import type { AnyPorts } from "@beignet/core/ports";
-import type { ProvidedPortsOfList, ServiceProvider } from "@beignet/core/providers";
-import type { ContractLike, CreateServerOptions, Handler, HttpRequestLike, HttpResponse, ResolveContract, RouteDef, ServerInstance } from "@beignet/core/server";
+import type { InferProviderPorts, ServiceProvider } from "@beignet/core/providers";
+import type { ContractLike, CreateServerOptions, Handler, HttpAdapter, HttpRequestLike, HttpResponse, ResolveContract, RouteDef, ServerInstance } from "@beignet/core/server";
 import type { StandardSchemaV1 } from "@standard-schema/spec";
 /**
  * Server types re-exported for Web Fetch apps.
  */
-export type { CreateServerOptions, HttpRequestLike, HttpResponse, RouteDef, RouteGroup, RouteHook, ServerInstance, } from "@beignet/core/server";
+export type { AnyUseCaseLike, CreateServerOptions, HandlerRouteDef, HttpAdapter, HttpAdapterApiHandler, HttpAdapterHandler, HttpRequestLike, HttpResponse, RouteDef, RouteGroup, RouteHook, ServerInstance, UseCaseRouteDef, } from "@beignet/core/server";
 /**
  * Server helpers re-exported for Web Fetch apps.
  */
-export { contractsFromRoutes, createServer, defineRoute, defineRouteGroup, defineRouteHook, defineRoutes, } from "@beignet/core/server";
-type AnyProvider = ServiceProvider<unknown, StandardSchemaV1<any, any>, AnyPorts>;
+export { contractsFromRoutes, createServer, defaultBinderInput, defineRoute, defineRouteGroup, defineRoutes, } from "@beignet/core/server";
+type AnyProvider = ServiceProvider<unknown, StandardSchemaV1<any, any>, AnyPorts, any, any>;
 /**
  * Beignet server adapted to the Web Fetch API.
  */
-export interface FetchServer<Ctx, Ports extends AnyPorts = AnyPorts> {
+export interface FetchServer<Ctx, Ports extends AnyPorts = AnyPorts, ServiceInput = void> {
     /**
      * Catch-all Web Fetch handler.
      */
@@ -29,6 +29,15 @@ export interface FetchServer<Ctx, Ports extends AnyPorts = AnyPorts> {
     route: <CLike extends ContractLike>(contractLike: CLike) => {
         handle: (fn: Handler<Ctx, ResolveContract<CLike>>) => (req: Request) => Promise<Response>;
     };
+    /**
+     * Build a fully assembled request context from a framework-neutral request.
+     */
+    createRequestContext: ServerInstance<Ctx, Ports, ServiceInput>["createRequestContext"];
+    /**
+     * Build a fully assembled service context for schedules, outbox drains,
+     * commands, and background work.
+     */
+    createServiceContext: ServerInstance<Ctx, Ports, ServiceInput>["createServiceContext"];
     /**
      * Registered contract inputs.
      */
@@ -50,6 +59,11 @@ export declare function toRequestLike(req: Request): HttpRequestLike;
  * Convert a Beignet response into a native `Response`.
  */
 export declare function toWebResponse(resLike: HttpResponse): Response;
+/**
+ * Concrete adapter implementation for Web-standard `Request` and `Response`
+ * runtimes.
+ */
+export declare const webFetchAdapter: HttpAdapter<Request, Response>;
 /**
  * Create a Web Fetch handler from a Beignet server or API handler.
  */
@@ -62,5 +76,5 @@ export declare function createFetchHandler(serverOrHandler: Pick<ServerInstance<
  * `@beignet/next`, which builds on the same Web adapter and adds Next-specific
  * helpers.
  */
-export declare function createFetchServer<Ctx, Ports extends AnyPorts = AnyPorts, Routes extends readonly RouteDef<Ctx>[] = readonly RouteDef<Ctx>[], Providers extends readonly AnyProvider[] = readonly AnyProvider[]>(options: CreateServerOptions<Ctx, Ports, Routes, Providers>): Promise<FetchServer<Ctx, Ports & ProvidedPortsOfList<Providers>>>;
+export declare function createFetchServer<Ctx, Ports extends AnyPorts = AnyPorts, ServiceInput = void, Routes extends readonly RouteDef<Ctx>[] = readonly RouteDef<Ctx>[], Providers extends readonly AnyProvider[] = readonly AnyProvider[]>(options: CreateServerOptions<Ctx, Ports, ServiceInput, Routes, Providers>): Promise<FetchServer<Ctx, Ports & InferProviderPorts<Providers>, ServiceInput>>;
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,KAAK,EACV,mBAAmB,EACnB,eAAe,EAChB,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EACV,YAAY,EACZ,mBAAmB,EACnB,OAAO,EACP,eAAe,EACf,YAAY,EACZ,eAAe,EACf,QAAQ,EACR,cAAc,EACf,MAAM,sBAAsB,CAAC;AAE9B,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAE9D;;GAEG;AACH,YAAY,EACV,mBAAmB,EACnB,eAAe,EACf,YAAY,EACZ,QAAQ,EACR,UAAU,EACV,SAAS,EACT,cAAc,GACf,MAAM,sBAAsB,CAAC;AAE9B;;GAEG;AACH,OAAO,EACL,mBAAmB,EACnB,YAAY,EACZ,WAAW,EACX,gBAAgB,EAChB,eAAe,EACf,YAAY,GACb,MAAM,sBAAsB,CAAC;AAE9B,KAAK,WAAW,GAAG,eAAe,CAChC,OAAO,EAEP,gBAAgB,CAAC,GAAG,EAAE,GAAG,CAAC,EAC1B,QAAQ,CACT,CAAC;AAEF;;GAEG;AACH,MAAM,WAAW,WAAW,CAAC,GAAG,EAAE,KAAK,SAAS,QAAQ,GAAG,QAAQ;IACjE;;OAEG;IACH,KAAK,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC3C;;OAEG;IACH,GAAG,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;IACzC;;OAEG;IACH,KAAK,EAAE,CAAC,KAAK,SAAS,YAAY,EAChC,YAAY,EAAE,KAAK,KAChB;QACH,MAAM,EAAE,CACN,EAAE,EAAE,OAAO,CAAC,GAAG,EAAE,eAAe,CAAC,KAAK,CAAC,CAAC,KACrC,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;KAC1C,CAAC;IACF;;OAEG;IACH,SAAS,EAAE,SAAS,YAAY,EAAE,CAAC;IACnC;;OAEG;IACH,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1B;;OAEG;IACH,KAAK,EAAE,KAAK,CAAC;CACd;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG,eAAe,CAa3D;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,YAAY,GAAG,QAAQ,CAc7D;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAChC,eAAe,EACX,IAAI,CAAC,cAAc,CAAC,OAAO,CAAC,EAAE,KAAK,CAAC,GACpC,CAAC,CAAC,GAAG,EAAE,eAAe,KAAK,OAAO,CAAC,YAAY,CAAC,CAAC,GACpD,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CAOrC;AAED;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CACrC,GAAG,EACH,KAAK,SAAS,QAAQ,GAAG,QAAQ,EACjC,MAAM,SAAS,SAAS,QAAQ,CAAC,GAAG,CAAC,EAAE,GAAG,SAAS,QAAQ,CAAC,GAAG,CAAC,EAAE,EAClE,SAAS,SAAS,SAAS,WAAW,EAAE,GAAG,SAAS,WAAW,EAAE,EAEjE,OAAO,EAAE,mBAAmB,CAAC,GAAG,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,CAAC,GAC1D,OAAO,CAAC,WAAW,CAAC,GAAG,EAAE,KAAK,GAAG,mBAAmB,CAAC,SAAS,CAAC,CAAC,CAAC,CAcnE"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,KAAK,EACV,kBAAkB,EAClB,eAAe,EAChB,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EACV,YAAY,EACZ,mBAAmB,EACnB,OAAO,EACP,WAAW,EACX,eAAe,EACf,YAAY,EACZ,eAAe,EACf,QAAQ,EACR,cAAc,EACf,MAAM,sBAAsB,CAAC;AAE9B,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAE9D;;GAEG;AACH,YAAY,EACV,cAAc,EACd,mBAAmB,EACnB,eAAe,EACf,WAAW,EACX,qBAAqB,EACrB,kBAAkB,EAClB,eAAe,EACf,YAAY,EACZ,QAAQ,EACR,UAAU,EACV,SAAS,EACT,cAAc,EACd,eAAe,GAChB,MAAM,sBAAsB,CAAC;AAE9B;;GAEG;AACH,OAAO,EACL,mBAAmB,EACnB,YAAY,EACZ,kBAAkB,EAClB,WAAW,EACX,gBAAgB,EAChB,YAAY,GACb,MAAM,sBAAsB,CAAC;AAE9B,KAAK,WAAW,GAAG,eAAe,CAChC,OAAO,EAEP,gBAAgB,CAAC,GAAG,EAAE,GAAG,CAAC,EAC1B,QAAQ,EAER,GAAG,EAEH,GAAG,CACJ,CAAC;AAEF;;GAEG;AACH,MAAM,WAAW,WAAW,CAC1B,GAAG,EACH,KAAK,SAAS,QAAQ,GAAG,QAAQ,EACjC,YAAY,GAAG,IAAI;IAEnB;;OAEG;IACH,KAAK,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC3C;;OAEG;IACH,GAAG,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;IACzC;;OAEG;IACH,KAAK,EAAE,CAAC,KAAK,SAAS,YAAY,EAChC,YAAY,EAAE,KAAK,KAChB;QACH,MAAM,EAAE,CACN,EAAE,EAAE,OAAO,CAAC,GAAG,EAAE,eAAe,CAAC,KAAK,CAAC,CAAC,KACrC,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;KAC1C,CAAC;IACF;;OAEG;IACH,oBAAoB,EAAE,cAAc,CAClC,GAAG,EACH,KAAK,EACL,YAAY,CACb,CAAC,sBAAsB,CAAC,CAAC;IAC1B;;;OAGG;IACH,oBAAoB,EAAE,cAAc,CAClC,GAAG,EACH,KAAK,EACL,YAAY,CACb,CAAC,sBAAsB,CAAC,CAAC;IAC1B;;OAEG;IACH,SAAS,EAAE,SAAS,YAAY,EAAE,CAAC;IACnC;;OAEG;IACH,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1B;;OAEG;IACH,KAAK,EAAE,KAAK,CAAC;CACd;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG,eAAe,CAa3D;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,YAAY,GAAG,QAAQ,CAc7D;AAED;;;GAGG;AACH,eAAO,MAAM,eAAe,EAAE,WAAW,CAAC,OAAO,EAAE,QAAQ,CAQ1D,CAAC;AAEF;;GAEG;AACH,wBAAgB,kBAAkB,CAChC,eAAe,EACX,IAAI,CAAC,cAAc,CAAC,OAAO,CAAC,EAAE,KAAK,CAAC,GACpC,CAAC,CAAC,GAAG,EAAE,eAAe,KAAK,OAAO,CAAC,YAAY,CAAC,CAAC,GACpD,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CAOrC;AAED;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CACrC,GAAG,EACH,KAAK,SAAS,QAAQ,GAAG,QAAQ,EACjC,YAAY,GAAG,IAAI,EACnB,MAAM,SAAS,SAAS,QAAQ,CAAC,GAAG,CAAC,EAAE,GAAG,SAAS,QAAQ,CAAC,GAAG,CAAC,EAAE,EAClE,SAAS,SAAS,SAAS,WAAW,EAAE,GAAG,SAAS,WAAW,EAAE,EAEjE,OAAO,EAAE,mBAAmB,CAAC,GAAG,EAAE,KAAK,EAAE,YAAY,EAAE,MAAM,EAAE,SAAS,CAAC,GACxE,OAAO,CACR,WAAW,CAAC,GAAG,EAAE,KAAK,GAAG,kBAAkB,CAAC,SAAS,CAAC,EAAE,YAAY,CAAC,CACtE,CAgBA"}

package/dist/index.js

@@ -2,7 +2,7 @@ import { createServer } from "@beignet/core/server";
 /**
  * Server helpers re-exported for Web Fetch apps.
  */
-export { contractsFromRoutes, createServer, defineRoute, defineRouteGroup, defineRouteHook, defineRoutes, } from "@beignet/core/server";
+export { contractsFromRoutes, createServer, defaultBinderInput, defineRoute, defineRouteGroup, defineRoutes, } from "@beignet/core/server";
 /**
  * Convert a native `Request` into Beignet's framework-neutral request shape.
  */
@@ -35,6 +35,16 @@ export function toWebResponse(resLike) {
     // biome-ignore lint/suspicious/noExplicitAny: Body can be any JSON-serializable value.
     return Response.json(body, { status: resLike.status, headers });
 }
+/**
+ * Concrete adapter implementation for Web-standard `Request` and `Response`
+ * runtimes.
+ */
+export const webFetchAdapter = {
+    name: "web-fetch",
+    toRequestLike,
+    toNativeResponse: toWebResponse,
+    createHandler: (handler) => async (req) => webFetchAdapter.toNativeResponse(await handler(webFetchAdapter.toRequestLike(req))),
+};
 /**
  * Create a Web Fetch handler from a Beignet server or API handler.
  */
@@ -42,7 +52,7 @@ export function createFetchHandler(serverOrHandler) {
     const handler = typeof serverOrHandler === "function"
         ? serverOrHandler
         : serverOrHandler.api;
-    return async (req) => toWebResponse(await handler(toRequestLike(req)));
+    return webFetchAdapter.createHandler(handler);
 }
 /**
  * Create a Beignet server adapted to the Web Fetch API.
@@ -61,6 +71,8 @@ export async function createFetchServer(options) {
         route: (contract) => ({
             handle: (fn) => createFetchHandler(runtime.route(contract).handle(fn)),
         }),
+        createRequestContext: runtime.createRequestContext,
+        createServiceContext: runtime.createServiceContext,
         contracts: runtime.contracts,
         stop: () => runtime.stop(),
         ports: runtime.ports,

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAeA,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAgBpD;;GAEG;AACH,OAAO,EACL,mBAAmB,EACnB,YAAY,EACZ,WAAW,EACX,gBAAgB,EAChB,eAAe,EACf,YAAY,GACb,MAAM,sBAAsB,CAAC;AA6C9B;;GAEG;AACH,MAAM,UAAU,aAAa,CAAC,GAAY;IACxC,OAAO;QACL,MAAM,EAAE,GAAG,CAAC,MAAM;QAClB,GAAG,EAAE,GAAG,CAAC,GAAG;QACZ,OAAO,EAAE,IAAI,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC;QACjC,GAAG,EAAE,GAAG;QACR,IAAI,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,IAAI,EAAE;QACtB,IAAI,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,IAAI,EAAE;QACtB,WAAW,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,WAAW,EAAE;QACpC,IAAI,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,IAAI,EAAE;QACtB,QAAQ,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,QAAQ,EAAE;QAC9B,KAAK,EAAE,GAAG,EAAE,CAAC,aAAa,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC;KACxC,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,aAAa,CAAC,OAAqB;IACjD,IAAI,OAAO,YAAY,QAAQ,EAAE,CAAC;QAChC,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,MAAM,OAAO,GAAG,IAAI,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IAC7C,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAE1B,IAAI,IAAI,KAAK,SAAS,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;QACxC,OAAO,IAAI,QAAQ,CAAC,IAAI,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC;IACjE,CAAC;IAED,uFAAuF;IACvF,OAAO,QAAQ,CAAC,IAAI,CAAC,IAAW,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC;AACzE,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,kBAAkB,CAChC,eAEqD;IAErD,MAAM,OAAO,GACX,OAAO,eAAe,KAAK,UAAU;QACnC,CAAC,CAAC,eAAe;QACjB,CAAC,CAAC,eAAe,CAAC,GAAG,CAAC;IAE1B,OAAO,KAAK,EAAE,GAAG,EAAE,EAAE,CAAC,aAAa,CAAC,MAAM,OAAO,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;AACzE,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAMrC,OAA2D;IAE3D,MAAM,OAAO,GAAG,MAAM,YAAY,CAAC,OAAO,CAAC,CAAC;IAC5C,MAAM,KAAK,GAAG,kBAAkB,CAAC,OAAO,CAAC,CAAC;IAE1C,OAAO;QACL,KAAK;QACL,GAAG,EAAE,KAAK;QACV,KAAK,EAAE,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;YACpB,MAAM,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,kBAAkB,CAAC,OAAO,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;SACvE,CAAC;QACF,SAAS,EAAE,OAAO,CAAC,SAAS;QAC5B,IAAI,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,IAAI,EAAE;QAC1B,KAAK,EAAE,OAAO,CAAC,KAAK;KACrB,CAAC;AACJ,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/testing.d.ts

@@ -1,10 +1,10 @@
 import { type CallArgs, type ClientConfig, type EndpointResult, type InferEndpointContractError, type InferSuccessResponse } from "@beignet/core/client";
 import type { AnyPorts } from "@beignet/core/ports";
-import type { ProvidedPortsOfList, ServiceProvider } from "@beignet/core/providers";
+import type { InferProviderPorts, ServiceProvider } from "@beignet/core/providers";
 import type { ContractLike, CreateServerOptions, ResolveContract, RouteDef } from "@beignet/core/server";
 import type { StandardSchemaV1 } from "@standard-schema/spec";
-import { type FetchServer } from "./index";
-type AnyProvider = ServiceProvider<unknown, StandardSchemaV1<any, any>, AnyPorts>;
+import { type FetchServer } from "./index.js";
+type AnyProvider = ServiceProvider<unknown, StandardSchemaV1<any, any>, AnyPorts, any, any>;
 /**
  * Client options accepted by `createTestApp(...)`.
  */
@@ -19,7 +19,7 @@ export type TestAppClientOptions<TProvidedHeaders extends string = never> = Omit
 /**
  * Options for creating a Web Fetch test app.
  */
-export type CreateTestAppOptions<Ctx, Ports extends AnyPorts, Routes extends readonly RouteDef<Ctx>[], Providers extends readonly AnyProvider[], TProvidedHeaders extends string = never> = CreateServerOptions<Ctx, Ports, Routes, Providers> & {
+export type CreateTestAppOptions<Ctx, Ports extends AnyPorts, Routes extends readonly RouteDef<Ctx>[], Providers extends readonly AnyProvider[], TProvidedHeaders extends string = never, ServiceInput = void> = CreateServerOptions<Ctx, Ports, ServiceInput, Routes, Providers> & {
     /**
      * Typed client behavior for `request(...)` and `safeRequest(...)`.
      */
@@ -59,6 +59,29 @@ export type TestApp<Ctx, Ports extends AnyPorts, TProvidedHeaders extends string
      */
     stop: () => Promise<void>;
 };
+/**
+ * Default call arguments merged into every typed test request.
+ */
+export type TestRequestDefaults<TDefaultHeaders extends string = string> = {
+    /**
+     * Headers to apply to each request unless a call overrides the same key.
+     */
+    headers?: Record<TDefaultHeaders, string>;
+};
+/**
+ * Request helpers with default call arguments already applied.
+ */
+export type TestRequester<TProvidedHeaders extends string = never> = {
+    /**
+     * Call a contract through the test app using default request values.
+     */
+    request: <CLike extends ContractLike>(contract: CLike, ...args: CallArgs<ResolveContract<CLike>, TProvidedHeaders>) => Promise<InferSuccessResponse<ResolveContract<CLike>>>;
+    /**
+     * Call a contract through the test app using default request values and
+     * return a typed success/error result instead of throwing.
+     */
+    safeRequest: <CLike extends ContractLike>(contract: CLike, ...args: CallArgs<ResolveContract<CLike>, TProvidedHeaders>) => Promise<EndpointResult<ResolveContract<CLike>, InferEndpointContractError<ResolveContract<CLike>>>>;
+};
 /**
  * Create a `fetch` implementation that dispatches requests to a Beignet Web
  * server without opening a network port.
@@ -67,6 +90,17 @@ export type TestApp<Ctx, Ports extends AnyPorts, TProvidedHeaders extends string
  * @returns Fetch-compatible function backed by `server.fetch`.
  */
 export declare function createTestFetch<Ctx, Ports extends AnyPorts>(server: Pick<FetchServer<Ctx, Ports>, "fetch">): typeof fetch;
+/**
+ * Create typed request helpers that merge default headers into each call.
+ *
+ * Use this for route tests that repeatedly need the same auth, tenant, locale,
+ * or correlation headers while still letting individual calls override them.
+ *
+ * @param app - Test app returned by `createTestApp(...)`.
+ * @param defaults - Default call values to merge into every request.
+ * @returns Typed `request(...)` and `safeRequest(...)` helpers.
+ */
+export declare function createTestRequester<Ctx, Ports extends AnyPorts, const TProvidedHeaders extends string = never, const TDefaultHeaders extends string = never>(app: Pick<TestApp<Ctx, Ports, TProvidedHeaders>, "request" | "safeRequest">, defaults: TestRequestDefaults<TDefaultHeaders>): TestRequester<TProvidedHeaders | TDefaultHeaders>;
 /**
  * Create a Beignet route/runtime test harness.
  *
@@ -74,9 +108,18 @@ export declare function createTestFetch<Ctx, Ports extends AnyPorts>(server: Pic
  * request parsing, route hooks, response validation, and error ownership as a
  * Web Fetch runtime without requiring Next.js or a network listener.
  *
+ * Test-friendly defaults differ from production servers in two ways, and an
+ * explicit option always wins:
+ *
+ * - `onUnboundPorts` defaults to `"ignore"` so apps with deferred provider
+ *   ports boot without installing every provider. Reading an unbound port
+ *   still throws on use.
+ * - `mapUnhandledError` defaults to a mapper that surfaces `err.message` in
+ *   the 500 response body so failing tests show the real error.
+ *
  * @param options - Server options plus optional typed-client settings.
  * @returns Test app with typed `request(...)` helpers and a bound `fetch`.
  */
-export declare function createTestApp<Ctx, Ports extends AnyPorts = AnyPorts, Routes extends readonly RouteDef<Ctx>[] = readonly RouteDef<Ctx>[], Providers extends readonly AnyProvider[] = readonly AnyProvider[], const TProvidedHeaders extends string = never>(options: CreateTestAppOptions<Ctx, Ports, Routes, Providers, TProvidedHeaders>): Promise<TestApp<Ctx, Ports & ProvidedPortsOfList<Providers>, TProvidedHeaders>>;
+export declare function createTestApp<Ctx, Ports extends AnyPorts = AnyPorts, ServiceInput = void, Routes extends readonly RouteDef<Ctx>[] = readonly RouteDef<Ctx>[], Providers extends readonly AnyProvider[] = readonly AnyProvider[], const TProvidedHeaders extends string = never>(options: CreateTestAppOptions<Ctx, Ports, Routes, Providers, TProvidedHeaders, ServiceInput>): Promise<TestApp<Ctx, Ports & InferProviderPorts<Providers>, TProvidedHeaders>>;
 export {};
 //# sourceMappingURL=testing.d.ts.map

package/dist/testing.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"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"}

package/dist/testing.js

@@ -1,5 +1,5 @@
 import { createClient, } from "@beignet/core/client";
-import { createFetchServer } from "./index";
+import { createFetchServer } from "./index.js";
 /**
  * Create a `fetch` implementation that dispatches requests to a Beignet Web
  * server without opening a network port.
@@ -13,6 +13,37 @@ export function createTestFetch(server) {
         return server.fetch(req);
     });
 }
+/**
+ * Create typed request helpers that merge default headers into each call.
+ *
+ * Use this for route tests that repeatedly need the same auth, tenant, locale,
+ * or correlation headers while still letting individual calls override them.
+ *
+ * @param app - Test app returned by `createTestApp(...)`.
+ * @param defaults - Default call values to merge into every request.
+ * @returns Typed `request(...)` and `safeRequest(...)` helpers.
+ */
+export function createTestRequester(app, defaults) {
+    return {
+        request: (contract, ...args) => {
+            const mergedArgs = mergeTestRequestArgs(args, defaults);
+            return app.request(contract, ...mergedArgs);
+        },
+        safeRequest: (contract, ...args) => {
+            const mergedArgs = mergeTestRequestArgs(args, defaults);
+            return app.safeRequest(contract, ...mergedArgs);
+        },
+    };
+}
+function defaultTestUnhandledErrorMapper({ err, }) {
+    return {
+        status: 500,
+        body: {
+            code: "INTERNAL_SERVER_ERROR",
+            message: err instanceof Error ? err.message : "Unknown error",
+        },
+    };
+}
 /**
  * Create a Beignet route/runtime test harness.
  *
@@ -20,12 +51,25 @@ export function createTestFetch(server) {
  * request parsing, route hooks, response validation, and error ownership as a
  * Web Fetch runtime without requiring Next.js or a network listener.
  *
+ * Test-friendly defaults differ from production servers in two ways, and an
+ * explicit option always wins:
+ *
+ * - `onUnboundPorts` defaults to `"ignore"` so apps with deferred provider
+ *   ports boot without installing every provider. Reading an unbound port
+ *   still throws on use.
+ * - `mapUnhandledError` defaults to a mapper that surfaces `err.message` in
+ *   the 500 response body so failing tests show the real error.
+ *
  * @param options - Server options plus optional typed-client settings.
  * @returns Test app with typed `request(...)` helpers and a bound `fetch`.
  */
 export async function createTestApp(options) {
     const { client: clientOptions, ...serverOptions } = options;
-    const server = await createFetchServer(serverOptions);
+    const server = await createFetchServer({
+        ...serverOptions,
+        onUnboundPorts: serverOptions.onUnboundPorts ?? "ignore",
+        mapUnhandledError: serverOptions.mapUnhandledError ?? defaultTestUnhandledErrorMapper,
+    });
     const fetch = createTestFetch(server);
     const client = createClient({
         ...clientOptions,
@@ -42,4 +86,20 @@ export async function createTestApp(options) {
         stop: () => server.stop(),
     };
 }
+function mergeTestRequestArgs(args, defaults) {
+    const [arg] = args;
+    const defaultHeaders = defaults.headers ?? {};
+    if (!arg) {
+        return [{ headers: defaultHeaders }];
+    }
+    return [
+        {
+            ...arg,
+            headers: {
+                ...defaultHeaders,
+                ...arg.headers,
+            },
+        },
+    ];
+}
 //# sourceMappingURL=testing.js.map

package/dist/testing.js.map

@@ -1 +1 @@
-{"version":3,"file":"testing.js","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,YAAY,GAIb,MAAM,sBAAsB,CAAC;AAa9B,OAAO,EAAE,iBAAiB,EAAoB,MAAM,SAAS,CAAC;AAwF9D;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAC7B,MAA8C;IAE9C,OAAO,CAAC,CAAC,KAAwB,EAAE,IAAkB,EAAE,EAAE;QACvD,MAAM,GAAG,GAAG,IAAI,OAAO,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;QAErC,OAAO,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC3B,CAAC,CAAiB,CAAC;AACrB,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAOjC,OAMC;IAID,MAAM,EAAE,MAAM,EAAE,aAAa,EAAE,GAAG,aAAa,EAAE,GAAG,OAAO,CAAC;IAC5D,MAAM,MAAM,GAAG,MAAM,iBAAiB,CAAC,aAAa,CAAC,CAAC;IACtD,MAAM,KAAK,GAAG,eAAe,CAAC,MAAM,CAAC,CAAC;IACtC,MAAM,MAAM,GAAG,YAAY,CAAmB;QAC5C,GAAG,aAAa;QAChB,OAAO,EAAE,aAAa,EAAE,OAAO,IAAI,qBAAqB;QACxD,KAAK;KACN,CAAC,CAAC;IAEH,OAAO;QACL,MAAM;QACN,KAAK;QACL,KAAK,EAAE,MAAM,CAAC,KAAK;QACnB,SAAS,EAAE,MAAM,CAAC,SAAS;QAC3B,OAAO,EAAE,CAAC,QAAQ,EAAE,GAAG,IAAI,EAAE,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;QACvE,WAAW,EAAE,CAAC,QAAQ,EAAE,GAAG,IAAI,EAAE,EAAE,CACjC,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,QAAQ,CAAC,GAAG,IAAI,CAAC;QAC7C,IAAI,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,IAAI,EAAE;KAC1B,CAAC;AACJ,CAAC"}
+{"version":3,"file":"testing.js","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@beignet/web",
-  "version": "0.0.3",
+  "version": "0.0.4",
   "type": "module",
   "description": "Web Fetch adapter for Beignet",
   "main": "./dist/index.js",
@@ -55,8 +55,10 @@
   "engines": {
     "node": ">=18.0.0"
   },
+  "peerDependencies": {
+    "@beignet/core": ">=0.0.3 <1.0.0"
+  },
   "dependencies": {
-    "@beignet/core": "*",
     "@standard-schema/spec": "^1.0.0"
   },
   "devDependencies": {

package/src/index.ts

@@ -1,12 +1,13 @@
 import type { AnyPorts } from "@beignet/core/ports";
 import type {
-  ProvidedPortsOfList,
+  InferProviderPorts,
   ServiceProvider,
 } from "@beignet/core/providers";
 import type {
   ContractLike,
   CreateServerOptions,
   Handler,
+  HttpAdapter,
   HttpRequestLike,
   HttpResponse,
   ResolveContract,
@@ -20,13 +21,19 @@ import type { StandardSchemaV1 } from "@standard-schema/spec";
  * Server types re-exported for Web Fetch apps.
  */
 export type {
+  AnyUseCaseLike,
   CreateServerOptions,
+  HandlerRouteDef,
+  HttpAdapter,
+  HttpAdapterApiHandler,
+  HttpAdapterHandler,
   HttpRequestLike,
   HttpResponse,
   RouteDef,
   RouteGroup,
   RouteHook,
   ServerInstance,
+  UseCaseRouteDef,
 } from "@beignet/core/server";
 
 /**
@@ -35,9 +42,9 @@ export type {
 export {
   contractsFromRoutes,
   createServer,
+  defaultBinderInput,
   defineRoute,
   defineRouteGroup,
-  defineRouteHook,
   defineRoutes,
 } from "@beignet/core/server";
 
@@ -45,13 +52,21 @@ type AnyProvider = ServiceProvider<
   unknown,
   // biome-ignore lint/suspicious/noExplicitAny: provider config types are erased at this level
   StandardSchemaV1<any, any>,
-  AnyPorts
+  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
 >;
 
 /**
  * Beignet server adapted to the Web Fetch API.
  */
-export interface FetchServer<Ctx, Ports extends AnyPorts = AnyPorts> {
+export interface FetchServer<
+  Ctx,
+  Ports extends AnyPorts = AnyPorts,
+  ServiceInput = void,
+> {
   /**
    * Catch-all Web Fetch handler.
    */
@@ -70,6 +85,23 @@ export interface FetchServer<Ctx, Ports extends AnyPorts = AnyPorts> {
       fn: Handler<Ctx, ResolveContract<CLike>>,
     ) => (req: Request) => Promise<Response>;
   };
+  /**
+   * Build a fully assembled request context from a framework-neutral request.
+   */
+  createRequestContext: ServerInstance<
+    Ctx,
+    Ports,
+    ServiceInput
+  >["createRequestContext"];
+  /**
+   * Build a fully assembled service context for schedules, outbox drains,
+   * commands, and background work.
+   */
+  createServiceContext: ServerInstance<
+    Ctx,
+    Ports,
+    ServiceInput
+  >["createServiceContext"];
   /**
    * Registered contract inputs.
    */
@@ -121,6 +153,20 @@ export function toWebResponse(resLike: HttpResponse): Response {
   return Response.json(body as any, { status: resLike.status, headers });
 }
 
+/**
+ * Concrete adapter implementation for Web-standard `Request` and `Response`
+ * runtimes.
+ */
+export const webFetchAdapter: HttpAdapter<Request, Response> = {
+  name: "web-fetch",
+  toRequestLike,
+  toNativeResponse: toWebResponse,
+  createHandler: (handler) => async (req) =>
+    webFetchAdapter.toNativeResponse(
+      await handler(webFetchAdapter.toRequestLike(req)),
+    ),
+};
+
 /**
  * Create a Web Fetch handler from a Beignet server or API handler.
  */
@@ -134,7 +180,7 @@ export function createFetchHandler(
       ? serverOrHandler
       : serverOrHandler.api;
 
-  return async (req) => toWebResponse(await handler(toRequestLike(req)));
+  return webFetchAdapter.createHandler(handler);
 }
 
 /**
@@ -148,11 +194,14 @@ export function createFetchHandler(
 export async function createFetchServer<
   Ctx,
   Ports extends AnyPorts = AnyPorts,
+  ServiceInput = void,
   Routes extends readonly RouteDef<Ctx>[] = readonly RouteDef<Ctx>[],
   Providers extends readonly AnyProvider[] = readonly AnyProvider[],
 >(
-  options: CreateServerOptions<Ctx, Ports, Routes, Providers>,
-): Promise<FetchServer<Ctx, Ports & ProvidedPortsOfList<Providers>>> {
+  options: CreateServerOptions<Ctx, Ports, ServiceInput, Routes, Providers>,
+): Promise<
+  FetchServer<Ctx, Ports & InferProviderPorts<Providers>, ServiceInput>
+> {
   const runtime = await createServer(options);
   const fetch = createFetchHandler(runtime);
 
@@ -162,6 +211,8 @@ export async function createFetchServer<
     route: (contract) => ({
       handle: (fn) => createFetchHandler(runtime.route(contract).handle(fn)),
     }),
+    createRequestContext: runtime.createRequestContext,
+    createServiceContext: runtime.createServiceContext,
     contracts: runtime.contracts,
     stop: () => runtime.stop(),
     ports: runtime.ports,

package/src/testing.ts

@@ -8,23 +8,28 @@ import {
 } from "@beignet/core/client";
 import type { AnyPorts } from "@beignet/core/ports";
 import type {
-  ProvidedPortsOfList,
+  InferProviderPorts,
   ServiceProvider,
 } from "@beignet/core/providers";
 import type {
   ContractLike,
   CreateServerOptions,
+  HttpResponse,
   ResolveContract,
   RouteDef,
 } from "@beignet/core/server";
 import type { StandardSchemaV1 } from "@standard-schema/spec";
-import { createFetchServer, type FetchServer } from "./index";
+import { createFetchServer, type FetchServer } from "./index.js";
 
 type AnyProvider = ServiceProvider<
   unknown,
   // biome-ignore lint/suspicious/noExplicitAny: provider config types are erased at this level.
   StandardSchemaV1<any, any>,
-  AnyPorts
+  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
 >;
 
 /**
@@ -49,7 +54,8 @@ export type CreateTestAppOptions<
   Routes extends readonly RouteDef<Ctx>[],
   Providers extends readonly AnyProvider[],
   TProvidedHeaders extends string = never,
-> = CreateServerOptions<Ctx, Ports, Routes, Providers> & {
+  ServiceInput = void,
+> = CreateServerOptions<Ctx, Ports, ServiceInput, Routes, Providers> & {
   /**
    * Typed client behavior for `request(...)` and `safeRequest(...)`.
    */
@@ -106,6 +112,42 @@ export type TestApp<
   stop: () => Promise<void>;
 };
 
+/**
+ * Default call arguments merged into every typed test request.
+ */
+export type TestRequestDefaults<TDefaultHeaders extends string = string> = {
+  /**
+   * Headers to apply to each request unless a call overrides the same key.
+   */
+  headers?: Record<TDefaultHeaders, string>;
+};
+
+/**
+ * Request helpers with default call arguments already applied.
+ */
+export type TestRequester<TProvidedHeaders extends string = never> = {
+  /**
+   * Call a contract through the test app using default request values.
+   */
+  request: <CLike extends ContractLike>(
+    contract: CLike,
+    ...args: CallArgs<ResolveContract<CLike>, TProvidedHeaders>
+  ) => Promise<InferSuccessResponse<ResolveContract<CLike>>>;
+  /**
+   * Call a contract through the test app using default request values and
+   * return a typed success/error result instead of throwing.
+   */
+  safeRequest: <CLike extends ContractLike>(
+    contract: CLike,
+    ...args: CallArgs<ResolveContract<CLike>, TProvidedHeaders>
+  ) => Promise<
+    EndpointResult<
+      ResolveContract<CLike>,
+      InferEndpointContractError<ResolveContract<CLike>>
+    >
+  >;
+};
+
 /**
  * Create a `fetch` implementation that dispatches requests to a Beignet Web
  * server without opening a network port.
@@ -123,6 +165,59 @@ export function createTestFetch<Ctx, Ports extends AnyPorts>(
   }) as typeof fetch;
 }
 
+/**
+ * Create typed request helpers that merge default headers into each call.
+ *
+ * Use this for route tests that repeatedly need the same auth, tenant, locale,
+ * or correlation headers while still letting individual calls override them.
+ *
+ * @param app - Test app returned by `createTestApp(...)`.
+ * @param defaults - Default call values to merge into every request.
+ * @returns Typed `request(...)` and `safeRequest(...)` helpers.
+ */
+export function createTestRequester<
+  Ctx,
+  Ports extends AnyPorts,
+  const TProvidedHeaders extends string = never,
+  const TDefaultHeaders extends string = never,
+>(
+  app: Pick<TestApp<Ctx, Ports, TProvidedHeaders>, "request" | "safeRequest">,
+  defaults: TestRequestDefaults<TDefaultHeaders>,
+): TestRequester<TProvidedHeaders | TDefaultHeaders> {
+  return {
+    request: (contract, ...args) => {
+      const mergedArgs = mergeTestRequestArgs(args, defaults) as CallArgs<
+        ResolveContract<typeof contract>,
+        TProvidedHeaders
+      >;
+
+      return app.request(contract, ...mergedArgs);
+    },
+    safeRequest: (contract, ...args) => {
+      const mergedArgs = mergeTestRequestArgs(args, defaults) as CallArgs<
+        ResolveContract<typeof contract>,
+        TProvidedHeaders
+      >;
+
+      return app.safeRequest(contract, ...mergedArgs);
+    },
+  };
+}
+
+function defaultTestUnhandledErrorMapper({
+  err,
+}: {
+  err: unknown;
+}): HttpResponse {
+  return {
+    status: 500,
+    body: {
+      code: "INTERNAL_SERVER_ERROR",
+      message: err instanceof Error ? err.message : "Unknown error",
+    },
+  };
+}
+
 /**
  * Create a Beignet route/runtime test harness.
  *
@@ -130,12 +225,22 @@ export function createTestFetch<Ctx, Ports extends AnyPorts>(
  * request parsing, route hooks, response validation, and error ownership as a
  * Web Fetch runtime without requiring Next.js or a network listener.
  *
+ * Test-friendly defaults differ from production servers in two ways, and an
+ * explicit option always wins:
+ *
+ * - `onUnboundPorts` defaults to `"ignore"` so apps with deferred provider
+ *   ports boot without installing every provider. Reading an unbound port
+ *   still throws on use.
+ * - `mapUnhandledError` defaults to a mapper that surfaces `err.message` in
+ *   the 500 response body so failing tests show the real error.
+ *
  * @param options - Server options plus optional typed-client settings.
  * @returns Test app with typed `request(...)` helpers and a bound `fetch`.
  */
 export async function createTestApp<
   Ctx,
   Ports extends AnyPorts = AnyPorts,
+  ServiceInput = void,
   Routes extends readonly RouteDef<Ctx>[] = readonly RouteDef<Ctx>[],
   Providers extends readonly AnyProvider[] = readonly AnyProvider[],
   const TProvidedHeaders extends string = never,
@@ -145,13 +250,19 @@ export async function createTestApp<
     Ports,
     Routes,
     Providers,
-    TProvidedHeaders
+    TProvidedHeaders,
+    ServiceInput
   >,
 ): Promise<
-  TestApp<Ctx, Ports & ProvidedPortsOfList<Providers>, TProvidedHeaders>
+  TestApp<Ctx, Ports & InferProviderPorts<Providers>, TProvidedHeaders>
 > {
   const { client: clientOptions, ...serverOptions } = options;
-  const server = await createFetchServer(serverOptions);
+  const server = await createFetchServer({
+    ...serverOptions,
+    onUnboundPorts: serverOptions.onUnboundPorts ?? "ignore",
+    mapUnhandledError:
+      serverOptions.mapUnhandledError ?? defaultTestUnhandledErrorMapper,
+  });
   const fetch = createTestFetch(server);
   const client = createClient<TProvidedHeaders>({
     ...clientOptions,
@@ -170,3 +281,31 @@ export async function createTestApp<
     stop: () => server.stop(),
   };
 }
+
+function mergeTestRequestArgs<
+  CLike extends ContractLike,
+  TProvidedHeaders extends string,
+>(
+  args: CallArgs<ResolveContract<CLike>, TProvidedHeaders>,
+  defaults: TestRequestDefaults<string>,
+): CallArgs<ResolveContract<CLike>, TProvidedHeaders> {
+  const [arg] = args;
+  const defaultHeaders = defaults.headers ?? {};
+
+  if (!arg) {
+    return [{ headers: defaultHeaders }] as CallArgs<
+      ResolveContract<CLike>,
+      TProvidedHeaders
+    >;
+  }
+
+  return [
+    {
+      ...arg,
+      headers: {
+        ...defaultHeaders,
+        ...arg.headers,
+      },
+    },
+  ] as CallArgs<ResolveContract<CLike>, TProvidedHeaders>;
+}