react-router-effect 2.0.0 → 2.2.0

package/src/factory.ts

@@ -1,6 +1,7 @@
-import { type Context, Effect, type ManagedRuntime } from "effect";
+import { Context, Effect, type ManagedRuntime, Predicate } from "effect";
 import { HttpServerRespondable, HttpServerResponse } from "effect/http";
 import {
+  createContext,
   data,
   redirect,
   type ActionFunctionArgs,
@@ -11,6 +12,7 @@ import {
   type RouterContextProvider,
 } from "react-router";
 
+import { attachActionMeta, type WithActionMeta } from "./action-meta.ts";
 import {
   isRouteError,
   Respond as baseRespond,
@@ -26,7 +28,7 @@ type BaseRespond = typeof baseRespond;
 // Type-level plumbing.
 // ---------------------------------------------------------------------------
 
-type Tagged = { readonly _tag: string };
+export type Tagged = { readonly _tag: string };
 
 /**
  * Everything a failure branch rejects with. React Router routes a thrown
@@ -34,13 +36,13 @@ type Tagged = { readonly _tag: string };
  * `Response` (including `redirect(...)`) as-is. Pinning every `Effect.fail` branch
  * to this union keeps inference from fixing the error channel to the first one.
  */
-type FailureResponse = DataWithResponseInit<unknown> | Response;
+export type FailureResponse = DataWithResponseInit<unknown> | Response;
 
 /**
  * What a handler may return, to *remap* a domain error:
- *  - a **library route error** — `Respond.early(value)` (recover), `Respond.throw(data)`
- *    or `Respond.redirect(url)` (throw) — which the library then processes; or
- *  - an **`Effect`** — `Effect.succeed(value)` to recover with `value`, or
+ *  - a **library route error** - `Respond.early(value)` (recover), `Respond.throw(data)`
+ *    or `Respond.redirect(url)` (throw) - which the library then processes; or
+ *  - an **`Effect`** - `Effect.succeed(value)` to recover with `value`, or
  *    `Effect.fail(response)` to throw `response`.
  */
 export type ErrorHandler<Err> = (
@@ -55,45 +57,45 @@ type ReturnableBodyOf<E> = E extends ReturnableDataError<infer Body> ? Body : ne
  * Guarded so a loader that never recovers directly doesn't leak
  * `DataWithResponseInit<never>` into its return type.
  */
-type DirectRecover<E> = [ReturnableBodyOf<E>] extends [never]
+export type DirectRecover<E> = [ReturnableBodyOf<E>] extends [never]
   ? never
   : DataWithResponseInit<ReturnableBodyOf<E>>;
 
 /** What a handler may return: a library route error or an `Effect` failing with a response. */
 type HandlerReturn = AnyRouteError | Effect.Effect<unknown, FailureResponse>;
 
-/** A `Route.MiddlewareFunction` (or the base `MiddlewareFunction`) — `(args, next) => ...`. */
-type AnyMiddlewareFunction = (...args: never[]) => unknown;
+/** A `Route.MiddlewareFunction` (or the base `MiddlewareFunction`) - `(args, next) => ...`. */
+export type AnyMiddlewareFunction = (...args: never[]) => unknown;
 
 /**
  * The `args` a `Route.MiddlewareFunction` (or the base `MiddlewareFunction`) is called
- * with — inferred from the type argument so `makeMiddleware` can be pinned to a specific
+ * with - inferred from the type argument so `makeMiddleware` can be pinned to a specific
  * generated route's middleware type.
  */
-type MiddlewareArgsOf<Middleware extends AnyMiddlewareFunction> = Parameters<Middleware>[0];
+export type MiddlewareArgsOf<Middleware extends AnyMiddlewareFunction> = Parameters<Middleware>[0];
 
 /**
  * The `next` a `Route.MiddlewareFunction` (or the base `MiddlewareFunction`) is called
- * with — react-router's own `() => Promise<Result>`, not exported under its own name.
+ * with - react-router's own `() => Promise<Result>`, not exported under its own name.
  */
-type MiddlewareNextOf<Middleware extends AnyMiddlewareFunction> = Parameters<Middleware>[1];
+export type MiddlewareNextOf<Middleware extends AnyMiddlewareFunction> = Parameters<Middleware>[1];
 
 /**
  * The `Result` a `Route.MiddlewareFunction` (or the base `MiddlewareFunction`) resolves
- * with — i.e. what its `next()` resolves to, and what the middleware itself may return.
+ * with - i.e. what its `next()` resolves to, and what the middleware itself may return.
  * Read through `Awaited` because react-router declares `next` as an *interface* with a
  * call signature (`MiddlewareNextFunction`), and a route's own may resolve synchronously.
  */
-type MiddlewareResultOf<Middleware extends AnyMiddlewareFunction> =
+export type MiddlewareResultOf<Middleware extends AnyMiddlewareFunction> =
   MiddlewareNextOf<Middleware> extends (...args: never[]) => infer Result ? Awaited<Result> : never;
 
 /**
  * The inferred map of handler RETURN types, keyed by domain-error tag. Making the
- * factory generic over *this* (rather than the whole handler map) is what lets
- * `errorHandlers` contextually type each handler's `error` param from its key —
- * no annotation needed — while still capturing precise return types for recovery.
+ * factory generic over *this* (rather than the handler map as a whole) is what lets
+ * `errorHandlers` contextually type each handler's `error` param from its key -
+ * no annotation needed - while still capturing precise return types for recovery.
  */
-type HandlerReturns<DomainError extends Tagged> = Partial<
+export type HandlerReturns<DomainError extends Tagged> = Partial<
   Record<DomainError["_tag"], HandlerReturn>
 >;
 
@@ -107,14 +109,14 @@ type ErrorHandlers<DomainError extends Tagged, Returns> = {
 };
 
 /**
- * What the registered handlers recover into loader/action data — from each
+ * What the registered handlers recover into loader/action data - from each
  * handler's return type, but only for handlers whose error can actually occur in
  * `E`:
  *  - a remapped `ReturnableDataError<B>` recovers as `DataWithResponseInit<B>`;
  *  - an `Effect.succeed(value)` recovers as `value`;
  *  - throwables, redirects and `Effect.fail(...)` contribute nothing.
  */
-type RecoverOf<DomainError extends Tagged, Returns, E> = {
+export type RecoverOf<DomainError extends Tagged, Returns, E> = {
   [Tag in keyof Returns]: [Extract<E, Extract<DomainError, { readonly _tag: Tag }>>] extends [never]
     ? never
     :
@@ -123,25 +125,25 @@ type RecoverOf<DomainError extends Tagged, Returns, E> = {
 }[keyof Returns];
 
 /**
- * Errors the library deals with on the handler's behalf — so the loader/action/
+ * Errors the library deals with on the handler's behalf - so the loader/action/
  * middleware needn't handle them itself:
- *  - the app's **declared domain errors** (`DomainError`) — handled by a registered
+ *  - the app's **declared domain errors** (`DomainError`) - handled by a registered
  *    handler, or left to the 500 / auto-respond default;
  *  - **library route errors** raised directly via `Respond`;
  *  - anything that renders itself via **`HttpServerRespondable`**;
- *  - `AlsoHandled` — extra, call-site-specific already-handled errors. Only
+ *  - `AlsoHandled` - extra, call-site-specific already-handled errors. Only
  *    `makeMiddleware` uses this, to admit the `FailureResponse` its `next()`
- *    fails with (a downstream throw, already a finished response — the library
+ *    fails with (a downstream throw, already a finished response - the library
  *    re-throws it as-is, so the middleware needn't catch it just to re-raise it).
  */
-type LibraryHandled<DomainError, AlsoHandled = never> =
+export type LibraryHandled<DomainError, AlsoHandled = never> =
   | DomainError
   | AnyRouteError
   | HttpServerRespondable.Respondable
   | AlsoHandled;
 
 /**
- * What remains in a handler's error channel that the library will NOT handle —
+ * What remains in a handler's error channel that the library will NOT handle -
  * i.e. service-specific errors the route consumes that aren't declared domain
  * errors. The loader/action/middleware must handle these itself (catch or map them).
  */
@@ -156,37 +158,37 @@ type Unhandled<E, DomainError, AlsoHandled = never> = Exclude<
 
 /**
  * A readable compile-time diagnostic. It's intersected onto the *effect return type*
- * of `fn` — so the effect's `A`/`E`/`R` still infer directly (naked), while a mismatch
+ * of `fn` - so the effect's `A`/`E`/`R` still infer directly (naked), while a mismatch
  * reports this message, and the offending types, *at the `makeLoader`/`makeAction`
  * call* instead of the opaque "Expected 2 arguments". Resolves to `unknown` (a no-op
  * intersection) when the effect is fully handled and all its requirements are provided:
  *
- *  - **Unhandled error** — the effect can fail with something that isn't a declared
- *    domain error, a library route error, or respondable; `unhandledErrors` names them.
- *  - **Missing requirement** — the effect requires a service that neither the
- *    `runtime` nor the `requestContext` provides; `missingRequirements` names them.
+ *  - **Unhandled error** - the effect can fail with something that isn't a declared
+ *    domain error, a library route error, or respondable; `unhandledErrors` lists them.
+ *  - **Missing requirement** - the effect requires a service that neither the
+ *    `runtime` nor the `requestContext` provides; `missingRequirements` lists them.
  *
- * The message lives in an *inline* object literal (no named alias) so tsc/tsgo print
+ * The message is in an *inline* object literal (no named alias) so tsc/tsgo print
  * its text verbatim rather than collapsing it to an alias name.
  */
 /**
- * Names the unhandled errors for the diagnostic: a tagged error becomes its `_tag`
+ * Lists the unhandled errors for the diagnostic: a tagged error becomes its `_tag`
  * (the string you'd pass to `Effect.catchTag`), anything untagged stays as its type.
  */
-type NameError<U> = U extends { readonly _tag: infer Tag extends string } ? Tag : U;
+export type NameError<U> = U extends { readonly _tag: infer Tag extends string } ? Tag : U;
 
 /**
- * True exactly when `T` is (or, for a union, includes) `any` — not `unknown`, not
+ * True exactly when `T` is (or, for a union, includes) `any` - not `unknown`, not
  * `never`, not any other type. An unrelated mistake elsewhere in the effect (a typo,
  * a call with the wrong number of arguments, a genuine syntax error) commonly makes
  * TypeScript infer `any` for `E`/`R` instead of reporting a clean type; running
  * `Diagnose` on that `any` produces a confusing "unhandled errors: any" message that
- * buries the real mistake. Guarding on this and bailing to `unknown` lets tsc's own,
- * on-site error surface instead. (`1 & T` is `any` when `T` is `any` — including when
- * `any` only appears as a union member, since intersection distributes over unions —
+ * buries the actual mistake. Guarding on this and bailing to `unknown` lets tsc's own,
+ * on-site error appear instead. (`1 & T` is `any` when `T` is `any` - including when
+ * `any` only appears as a union member, since intersection distributes over unions -
  * and `0` is assignable to `any` but not to any concrete type built from `1 & T`.)
  */
-type IsAny<T> = 0 extends 1 & T ? true : false;
+export type IsAny<T> = 0 extends 1 & T ? true : false;
 
 type Diagnose<E, R, DomainError, Provided, AlsoHandled = never> =
   IsAny<E> extends true
@@ -213,7 +215,7 @@ const internalServerError = () =>
   Effect.fail<FailureResponse>(new Response("Internal Server Error", { status: 500 }));
 
 /**
- * A raw `FailureResponse` — a downstream `next()`'s rejection, in `makeMiddleware` —
+ * A raw `FailureResponse` - a downstream `next()`'s rejection, in `makeMiddleware` -
  * is already a finished response; re-throwing it as-is (rather than 500ing it) lets
  * a nested loader's redirect/thrown response pass back up through the middleware chain.
  */
@@ -239,9 +241,15 @@ const processRouteError = (
 
 /**
  * A React Router context key holding a per-request effect `Context.Context`. Set
- * it in middleware and pass it to the factory's `requestContext` — the runner
+ * it in middleware and pass it to the factory's `requestContext` - the runner
  * reads it on every request and provides its services to the loader/action.
  *
+ * With the server adapter, do not set it to a new context. The adapter sets it
+ * to the request fiber's context before React Router runs, and a new context
+ * replaces those services, such as `HttpServerRequest` and the server span.
+ * Provide request services with a router middleware on `ReactRouter.routes`.
+ * The middleware below is for an app without the adapter.
+ *
  * It's just a `RouterContext`; create one with React Router's `createContext`:
  *
  * ```ts
@@ -255,7 +263,7 @@ const processRouteError = (
  *
  * export const requestContext: RequestContextKey<RequestContext> = createContext();
  *
- * // middleware:
+ * // middleware, in an app without the server adapter:
  * export const middleware: Route.MiddlewareFunction[] = [
  *   ({ context, request }, next) => {
  *     context.set(requestContext, Context.make(RequestContext, { userId: readUser(request) }));
@@ -266,6 +274,99 @@ const processRouteError = (
  */
 export type RequestContextKey<ReqServices> = RouterContext<Context.Context<ReqServices>>;
 
+/**
+ * The request store of a factory that configures no `requestContext`. It holds
+ * whatever the server adapter and effect middleware put there, and starts empty.
+ */
+const defaultRequestContext: RequestContextKey<never> = createContext(Context.empty());
+
+/** What `actionMeta` reads: the request and the router context of the action. */
+export interface ActionMetaArgs {
+  readonly request: Request;
+  readonly context: Readonly<RouterContextProvider>;
+}
+
+/**
+ * The entries of `current` that `started` lacks or holds with another value:
+ * what a fiber that began with `started` has provided since.
+ */
+const providedSince = <Services>(
+  started: Context.Context<Services>,
+  current: Context.Context<never>,
+): Context.Context<never> => {
+  const provided = new Map<string, unknown>();
+  for (const [key, value] of current.mapUnsafe) {
+    if (started.mapUnsafe.get(key) !== value) provided.set(key, value);
+  }
+  return Context.makeUnsafe(provided);
+};
+
+/** The `next` an effect middleware gets: runs the rest of the chain as an effect. */
+export type EffectNext<Result> = () => Effect.Effect<Result, FailureResponse>;
+
+/**
+ * The arguments of an effect middleware: React Router's own middleware args,
+ * plus `next` as an effect. The second parameter stays React Router's
+ * promise-returning `next`, so a plain middleware works unchanged.
+ */
+export type EffectMiddlewareArgs<Middleware extends AnyMiddlewareFunction = MiddlewareFunction> =
+  MiddlewareArgsOf<Middleware> & {
+    readonly next: EffectNext<MiddlewareResultOf<Middleware>>;
+  };
+
+/** The router context and signal every route function receives. */
+interface RouteArgs {
+  readonly request: Request;
+  readonly context: Readonly<RouterContextProvider>;
+}
+
+/**
+ * What a route function resolves with: an Effect's success, or the awaited
+ * value. A failure that a handler recovers resolves with its data too.
+ */
+export type RouteResult<Out> =
+  Out extends Effect.Effect<infer A, infer _E, infer _R> ? A : Awaited<Out>;
+
+/**
+ * Turns route functions into the promise-returning functions React Router
+ * calls. An Effect result runs through the factory's error model with the
+ * factory's runtime and the request's effect context; any other result passes
+ * through. The server adapter applies these to every route module, and tests
+ * can call them directly.
+ *
+ * Each is generic over the route's own args, so a test can pass a route's
+ * `Route.LoaderArgs` without a cast. React Router always supplies `request`
+ * and `context`.
+ */
+export interface RouteHandlers {
+  readonly loader: <Args extends RouteArgs, Out>(
+    fn: (args: Args) => Out,
+  ) => (args: Args) => Promise<RouteResult<Out>>;
+  readonly action: <Args extends RouteArgs, Out>(
+    fn: (args: Args) => Out,
+  ) => (args: Args) => Promise<RouteResult<Out>>;
+  /**
+   * The wrapped middleware takes React Router's args, without `next`: the
+   * runner adds `next` as an effect.
+   */
+  readonly middleware: <Args extends RouteArgs, Next extends () => Promise<unknown>, Out>(
+    fn: (args: Args, next: Next) => Out,
+  ) => (args: Omit<Args, "next">, next: Next) => Promise<RouteResult<Out> | undefined>;
+  /** The router context key that holds the request's effect context. */
+  readonly requestContext: RouterContext<Context.Context<never>>;
+}
+
+/**
+ * The types a factory exposes for the server adapter's route check and for
+ * `Register`. Never present at runtime.
+ */
+export interface FactoryTypes<DomainError, Returns, Services, Meta> {
+  readonly DomainError: DomainError;
+  readonly Returns: Returns;
+  readonly Services: Services;
+  readonly Meta: Meta;
+}
+
 // ---------------------------------------------------------------------------
 // Factory.
 // ---------------------------------------------------------------------------
@@ -277,7 +378,7 @@ export type RequestContextKey<ReqServices> = RouterContext<Context.Context<ReqSe
  * Declare the app's **domain errors** as the type argument, then register an
  * *optional* handler per domain error in `errorHandlers`. The handler keys
  * autocomplete to your domain-error tags and each `error` parameter is typed from
- * its key — no annotation needed. It's curried so you can pin the domain errors
+ * its key - no annotation needed. It's curried so you can pin the domain errors
  * while the handler return types are still inferred:
  *
  * ```ts
@@ -293,10 +394,10 @@ export type RequestContextKey<ReqServices> = RouterContext<Context.Context<ReqSe
  *   }));
  * ```
  *
- * The inner config is a **builder** — it receives the library's `Respond` helpers so
+ * The inner config is a **builder** - it receives the library's `Respond` helpers so
  * your handlers can recover/throw with them, and returns the config. `Respond` is
  * also returned from the factory (extended with any `respond` helpers you add), so
- * your app imports a *single* `Respond` — no auto-import ambiguity with a library one.
+ * your app imports a *single* `Respond` - no auto-import ambiguity with a library one.
  *
  * A handler *remaps* the error by returning either a library route error
  * (`Respond.early` to recover; `Respond.throw` / `Respond.redirect` to throw) or an
@@ -305,13 +406,13 @@ export type RequestContextKey<ReqServices> = RouterContext<Context.Context<ReqSe
  *
  * **Declared domain errors** may be left unhandled: if one implements
  * `HttpServerRespondable` it's rendered automatically, otherwise it falls through
- * to a 500. **Any other error** — a service-specific error the route consumes that
- * isn't a declared domain error — *must* be handled in the loader/action, or
+ * to a 500. **Any other error** - a service-specific error the route consumes that
+ * isn't a declared domain error - *must* be handled in the loader/action, or
  * `makeLoader`/`makeAction` fails to type-check.
  *
  * Pass a `runtime` (a `ManagedRuntime`, e.g. from `ManagedRuntime.make(AppLayer)`)
  * to provide your app's services once. Loader/action effects may then require those
- * services directly — no per-call `Effect.provide`:
+ * services directly - no per-call `Effect.provide`:
  *
  * ```ts
  * const { makeLoader, makeAction } = makeEffectRouteFactory<DomainErrors>()(() => ({
@@ -333,9 +434,9 @@ export type RequestContextKey<ReqServices> = RouterContext<Context.Context<ReqSe
  * generated `Route.MiddlewareFunction` (a type argument, since middleware has no
  * separate args-only type) to type `args` and `next`'s result from that route; it
  * defaults to React Router's own `MiddlewareFunction`. The `next` handed to the
- * effect is `() => Effect.Effect<Result, FailureResponse>` — call it with `yield*`
+ * effect is `() => Effect.Effect<Result, FailureResponse>` - call it with `yield*`
  * to run the rest of the chain, and a downstream throw (e.g. a nested loader's
- * redirect) surfaces as a typed failure instead of a rejected promise:
+ * redirect) becomes a typed failure instead of a rejected promise:
  *
  * ```ts
  * const middleware = makeMiddleware<Route.MiddlewareFunction>((args, next) =>
@@ -353,6 +454,7 @@ export function makeEffectRouteFactory<DomainError extends Tagged = never>() {
     RServices = never,
     ReqServices = never,
     const ExtraRespond extends Record<string, (...args: never[]) => unknown> = {},
+    Meta = never,
   >(
     /**
      * Builds the factory config. It receives the library's base `Respond` helpers
@@ -363,7 +465,7 @@ export function makeEffectRouteFactory<DomainError extends Tagged = never>() {
       /**
        * An optional handler per declared domain error, keyed by its tag. The keys
        * autocomplete to your domain-error tags and each handler's `error` parameter
-       * is typed automatically — no annotation needed. A handler *remaps* the error
+       * is typed automatically - no annotation needed. A handler *remaps* the error
        * by returning a library route error (the builder's `Respond.early` / `throw`
        * / `redirect`) or an `Effect` (`Effect.succeed`/`fail`). Omit to register none.
        */
@@ -384,18 +486,29 @@ export function makeEffectRouteFactory<DomainError extends Tagged = never>() {
        */
       requestContext?: RequestContextKey<ReqServices>;
       /**
-       * App-specific `Respond` helpers — merged onto the base `Respond` that the
+       * App-specific `Respond` helpers - merged onto the base `Respond` that the
        * factory returns, so your app imports one `Respond`. Typically opinionated
        * error constructors; annotate their parameters, e.g.
        * `{ formError: (reply: string) => new FormError({ reply }) }`. The base
        * helpers (`early` / `throw` / `redirect`) always win the merge.
        */
       respond?: ExtraRespond;
+      /**
+       * Request-scoped metadata to attach to every action's data under `__meta`,
+       * read after the action resolves. The server adapter attaches it to every
+       * action it runs, including plain functions and `makeAction` wrappers. A
+       * thrown result gets none. Only plain records and `data(...)` bodies include
+       * it; other values are returned unchanged.
+       */
+      actionMeta?: (args: ActionMetaArgs) => Meta;
     },
   ) {
     const config = builder(baseRespond);
     const runtime = config.runtime;
     const requestContextKey = config.requestContext;
+    // Where the request's effect context is stored: the app's key, or the library's own.
+    const storeKey: RequestContextKey<ReqServices> =
+      requestContextKey ?? (defaultRequestContext as RequestContextKey<ReqServices>);
     // The single `Respond` an app uses: base helpers plus any app-specific ones.
     // Base wins the merge so core helpers can't be shadowed.
     const Respond = { ...config.respond, ...baseRespond } as BaseRespond & ExtraRespond;
@@ -404,18 +517,17 @@ export function makeEffectRouteFactory<DomainError extends Tagged = never>() {
     // Defaults to an empty map when `errorHandlers` is omitted.
     const userHandlers = (config.errorHandlers ?? {}) as unknown as Record<
       string,
-      ErrorHandler<DomainError>
+      ErrorHandler<Tagged>
     >;
-
-    const isUserError = (e: unknown): e is DomainError =>
-      typeof e === "object" && e !== null && "_tag" in e && (e as Tagged)._tag in userHandlers;
+    /** The tags of the registered domain errors. */
+    const userTags = Object.keys(userHandlers);
 
     /**
      * Runs a handler's effect to completion: dispatches its whole error channel
      * (registered domain errors, library route errors, respondables, or the 500
      * default), provides the per-request context, and executes against the
      * configured runtime. Shared by `makeLoader`/`makeAction` and `makeMiddleware`
-     * — they differ only in how they build the effect and what `context` they read.
+     * - they differ only in how they build the effect and what `context` they read.
      */
     function runProgram<E>(
       effect: Effect.Effect<unknown, E, RServices | ReqServices>,
@@ -424,10 +536,10 @@ export function makeEffectRouteFactory<DomainError extends Tagged = never>() {
     ): Promise<unknown> {
       // The internal channel is deliberately loose (`unknown` success); the caller
       // restores the precise resolved type (computed from `E` and the handler map).
-      // Sound at runtime — the values produced are exactly those types.
+      // Sound at runtime - the values produced are exactly those types.
       const program = effect.pipe(
-        // Catch the whole error channel and dispatch. The refinement is `e is E`
-        // (provably ⊆ E, and a *refinement* not a bare predicate — the predicate
+        // Catch the full error channel and dispatch. The refinement is `e is E`
+        // (provably ⊆ E, and a *refinement* not a bare predicate - the predicate
         // overload crashes tsc over a generic `E`). A declared domain error with no
         // handler (and not respondable) falls through to the 500 default.
         Effect.catchIf(
@@ -435,9 +547,11 @@ export function makeEffectRouteFactory<DomainError extends Tagged = never>() {
           (e): Effect.Effect<unknown, FailureResponse> => {
             // Registered domain error → remap. A library-error return is processed
             // by the internal dispatch; an `Effect` return is used as-is.
-            if (isUserError(e)) {
-              const out = userHandlers[e._tag](e);
-              return isRouteError(out) ? processRouteError(out) : out;
+            for (const tag of userTags) {
+              if (Predicate.isTagged(e, tag)) {
+                const out = userHandlers[tag](e);
+                return isRouteError(out) ? processRouteError(out) : out;
+              }
             }
             // A library route error raised directly in the handler → recover/throw.
             if (isRouteError(e)) return processRouteError(e);
@@ -456,12 +570,16 @@ export function makeEffectRouteFactory<DomainError extends Tagged = never>() {
           },
         ),
       );
-      // Provide the per-request context (set by middleware) so `ReqServices` are
-      // satisfied, leaving only the runtime's `RServices` in the requirements.
-      // The cast is sound: `provideContext` removes `ReqServices`, and when no
-      // `requestContext` is configured `ReqServices` is `never` (nothing removed).
+      // Provide the request's effect context so `ReqServices` are satisfied,
+      // leaving only the runtime's `RServices` in the requirements. Under the
+      // server adapter the store also holds the HTTP request fiber's context, and
+      // whatever an effect middleware provided around `next()`. The cast is sound:
+      // `provideContext` removes `ReqServices`, and when no `requestContext` is
+      // configured `ReqServices` is `never` (nothing removed).
+      const store = readRequestStore(context);
+      // oxlint-disable-next-line effecttsgo/unsafe-effect-type-assertion -- the cast is sound, as the comment above explains
       const provided = (
-        requestContextKey ? Effect.provideContext(program, context.get(requestContextKey)) : program
+        store === undefined ? program : Effect.provideContext(program, store)
       ) as Effect.Effect<unknown, FailureResponse, RServices>;
       // Run against the configured runtime so its services satisfy the effect's
       // `R`; with no runtime, the effect requires nothing and runs standalone.
@@ -470,15 +588,16 @@ export function makeEffectRouteFactory<DomainError extends Tagged = never>() {
       // signal and discards its result, so the interrupt rejection is never rendered.
       return runtime
         ? runtime.runPromise(provided, { signal })
-        : Effect.runPromise(provided as Effect.Effect<unknown, FailureResponse>, { signal });
+        : // oxlint-disable-next-line effecttsgo/unsafe-effect-type-assertion -- with no runtime `RServices` is `never`
+          Effect.runPromise(provided as Effect.Effect<unknown, FailureResponse>, { signal });
     }
 
     function makeLoaderOrAction<Args extends LoaderFunctionArgs | ActionFunctionArgs, A, E, R>(
-      // `A`/`E`/`R` infer directly from the effect (naked, so inference stays robust).
+      // `A`/`E`/`R` infer directly from the effect (naked, so inference stays intact).
       // The diagnostic is intersected onto the effect's return type: when the effect
       // requires a service the factory doesn't provide (`R` ⊄ runtime+requestContext),
       // or can fail with something the library won't handle, `Diagnose` becomes a
-      // message object the effect isn't assignable to — so this argument fails to
+      // message object the effect isn't assignable to - so this argument fails to
       // type-check with a readable explanation, and the offending types, right here.
       fn: (
         args: Args,
@@ -501,30 +620,30 @@ export function makeEffectRouteFactory<DomainError extends Tagged = never>() {
      * args-only type) to type `args`, `next` and the result from that route; it defaults
      * to React Router's own `MiddlewareFunction`.
      *
-     * The errors the library deals with for a loader/action it deals with here too —
-     * declared domain errors, library route errors and respondables — plus the
+     * The errors the library deals with for a loader/action it deals with here too -
+     * declared domain errors, library route errors and respondables - plus the
      * `FailureResponse` `next()` fails with. Anything else must be handled in the effect,
      * as must any service neither the `runtime` nor the `requestContext` provides.
      *
-     * The wrapper is typed as the route's own middleware — `(args, next) =>
-     * Promise<Result | undefined>` — so it drops straight into a
+     * The wrapper is typed as the route's own middleware - `(args, next) =>
+     * Promise<Result | undefined>` - so it drops straight into a
      * `Route.MiddlewareFunction[]`. A handler that recovers (`Respond.early`) resolves
      * with `data(...)`, which react-router's server middleware pipeline turns into the
      * short-circuit `Response`.
      */
     function makeMiddleware<
       Middleware extends AnyMiddlewareFunction = MiddlewareFunction,
-      // A pinned call passes an explicit type argument, which makes the whole call
-      // explicit — TypeScript has no partial inference — so these defaults stand in
+      // A pinned call passes an explicit type argument, which makes every type argument of the call
+      // explicit - TypeScript has no partial inference - so these defaults stand in
       // for what would otherwise be inferred: exactly the errors the library handles
       // and the services the factory provides.
       E = LibraryHandled<DomainError, FailureResponse>,
       R = RServices | ReqServices,
     >(
       // Same shape as `makeLoaderOrAction`'s `fn`, but middleware also receives
-      // `next` — wrapped as an effect (rather than react-router's raw
+      // `next` - wrapped as an effect (rather than react-router's raw
       // `() => Promise<Result>`) so downstream failures (e.g. a nested loader's
-      // redirect) surface as a typed `FailureResponse`, consistent with the rest
+      // redirect) become a typed `FailureResponse`, consistent with the rest
       // of the library's error model. The success type is fixed to the route's own
       // `Result` (plus `void`), which is what react-router accepts back.
       fn: (
@@ -538,33 +657,124 @@ export function makeEffectRouteFactory<DomainError extends Tagged = never>() {
     ) => Promise<MiddlewareResultOf<Middleware> | undefined> {
       // Inside the body the route's own arg/result types are opaque (they're
       // `Parameters<Middleware>[...]` of an unresolved type parameter), so dispatch
-      // through the loose shape — as `makeLoaderOrAction` does with its diagnostic.
+      // through the loose shape - as `makeLoaderOrAction` does with its diagnostic.
       // Sound at runtime: the values produced are exactly the declared types.
       const run = fn as unknown as (
         args: MiddlewareArgsOf<Middleware>,
         next: () => Effect.Effect<unknown, FailureResponse>,
       ) => Effect.Effect<unknown, E, RServices | ReqServices>;
       return (args, next) => {
-        const effectNext = () =>
-          Effect.tryPromise({
-            try: next as unknown as () => Promise<unknown>,
-            catch: (e) => e as FailureResponse,
-          });
-        const { context, request } = args as unknown as {
-          context: Readonly<RouterContextProvider>;
-          request: Request;
-        };
+        const { context, request } = args as unknown as RouteArgs;
+        const effectNext = makeEffectNext(context, next as unknown as () => Promise<unknown>);
         return runProgram(run(args, effectNext), context, request.signal) as Promise<
           MiddlewareResultOf<Middleware> | undefined
         >;
       };
     }
 
+    /**
+     * Reads the request's effect context from the router context. A test that
+     * passes args without a router context gets none, as before.
+     */
+    function readRequestStore(
+      context: Readonly<RouterContextProvider> | undefined,
+    ): Context.Context<ReqServices> | undefined {
+      // An app key without a default that no middleware has set throws here, as
+      // it always has: the app promised its services would be there. The
+      // library's own key starts empty.
+      return typeof context?.get === "function" ? context.get(storeKey) : undefined;
+    }
+
+    /**
+     * Wraps React Router's `next` as an effect. Before it runs the rest of the
+     * chain, it adds to the request's effect context what the calling fiber
+     * provides beyond the context the middleware started with: services it
+     * provides around `next()`, log annotations, and its current span. Updates
+     * the middleware made with `context.set` stay. A downstream rejection is
+     * already a finished response, so it fails with that response as-is.
+     */
+    function makeEffectNext(
+      context: Readonly<RouterContextProvider>,
+      next: () => Promise<unknown>,
+    ): () => Effect.Effect<unknown, FailureResponse> {
+      const started = readRequestStore(context);
+      return () =>
+        Effect.withFiber((fiber) => {
+          if (started !== undefined) {
+            context.set(
+              storeKey,
+              Context.merge(context.get(storeKey), providedSince(started, fiber.context)),
+            );
+          }
+          return Effect.tryPromise({ try: next, catch: (e) => e as FailureResponse });
+        });
+    }
+
+    /** Runs a loader or action's result: an Effect through the error model, anything else as-is. */
+    function runResult(result: unknown, args: RouteArgs): unknown {
+      return Effect.isEffect(result)
+        ? runProgram(
+            // oxlint-disable-next-line effecttsgo/any-unknown-in-error-context, effecttsgo/unsafe-effect-type-assertion -- a route function's Effect is only known to be an Effect here; `runProgram` dispatches its whole error channel
+            result as Effect.Effect<unknown, unknown, RServices | ReqServices>,
+            args.context,
+            args.request.signal,
+          )
+        : result;
+    }
+
+    const actionMeta = config.actionMeta;
+
+    // React Router calls every route function with args that include at least
+    // `request` and `context`, so each wrapper reads them through `RouteArgs`.
+    // The runners resolve with what `runResult` produces: the Effect's success
+    // or recovered data, or the awaited plain result. `RouteResult` is its type.
+    const handlers: RouteHandlers = {
+      loader: (fn) => async (args) =>
+        runResult(fn(args), args) as RouteResult<ReturnType<typeof fn>>,
+      action: (fn) => async (args) => {
+        const result = await runResult(fn(args), args);
+        return (
+          actionMeta === undefined ? result : attachActionMeta(result, actionMeta(args))
+        ) as RouteResult<ReturnType<typeof fn>>;
+      },
+      middleware: (fn) => async (args, next) => {
+        const routeArgs: RouteArgs = args;
+        // The runner supplies `next` as an effect in place of the one `Args`
+        // names, which it cannot prove for an arbitrary `Args`.
+        const effectArgs = {
+          ...args,
+          next: makeEffectNext(routeArgs.context, next),
+        } as unknown as Parameters<typeof fn>[0];
+        return runResult(fn(effectArgs, next), routeArgs) as RouteResult<ReturnType<typeof fn>>;
+      },
+      requestContext: storeKey as RouterContext<Context.Context<never>>,
+    };
+
     return {
       makeLoader: makeLoaderOrAction,
-      makeAction: makeLoaderOrAction,
+      makeAction: makeLoaderOrAction as <
+        Args extends LoaderFunctionArgs | ActionFunctionArgs,
+        A,
+        E,
+        R,
+      >(
+        fn: (
+          args: Args,
+        ) => Effect.Effect<A, E, R> & Diagnose<E, R, DomainError, RServices | ReqServices>,
+      ) => (
+        args: Args,
+      ) => Promise<WithActionMeta<A | DirectRecover<E> | RecoverOf<DomainError, Returns, E>, Meta>>,
       makeMiddleware,
       Respond,
+      /** The route runner the server adapter applies to every route module. */
+      handlers,
+      /** Type-only: what the adapter's route check and `Register` read. */
+      "~types": undefined as unknown as FactoryTypes<
+        DomainError,
+        Returns,
+        RServices | ReqServices,
+        Meta
+      >,
     };
   };
 }